Quickstart

import WebSocket from "ws";
const KEY = process.env.STATPAD_API_KEY;
const API = "https://api.statpad.dev/v1";
const STREAM = "wss://stream.statpad.dev/v1/stream";
const league = "nfl";
const gameId = process.argv[2];
const stream = `game:${gameId}`;
type Change = { seq: number; op: "upsert" | "delete"; entity_type: string; entity_id: string; version: number; payload: any };
// Everything known about the game, keyed by "entity_type:entity_id". A deleted entity keeps its
// version with a null payload, so an older copy can't bring it back.
const state = new Map<string, { version: number; payload: any }>();
let lastSeq = 0;
function put(type: string, id: string, version: number, payload: any) {
  const key = `${type}:${id}`;
  if ((state.get(key)?.version ?? 0) >= version) return;
  state.set(key, { version, payload });
}
const get = (type: string, id: string) => state.get(`${type}:${id}`)?.payload;
// Step 4: read the game and remember the stream position it reflects.
async function readGame() {
  const res = await fetch(`${API}/${league}/games/${gameId}`, { headers: { Authorization: `Bearer ${KEY}` } });
  if (!res.ok) throw new Error(`GET game: ${res.status} ${await res.text()}`);
  const body = await res.json();
  state.clear();
  put("game", body.game.id, body.game.version, body.game);
  if (body.live_state) put("live_state", gameId, body.live_state.version, body.live_state);
  for (const team of [body.home_team, body.away_team]) put("team", team.id, team.version, team);
  lastSeq = body.seq;
}
function render() {
  const game = get("game", gameId);
  const live = get("live_state", gameId);
  const away = get("team", game.away_team_id)?.alias;
  const home = get("team", game.home_team_id)?.alias;
  const score = `${away} ${live?.away_score ?? game.away_score ?? 0}, ${home} ${live?.home_score ?? game.home_score ?? 0}`;
  if (!live) return console.log(`${score} (${game.status})`);
  const clock = live.clock_seconds == null ? "" : ` ${Math.floor(live.clock_seconds / 60)}:${String(live.clock_seconds % 60).padStart(2, "0")}`;
  const f = live.football;
  const down = f?.down ? `, ${f.down} & ${f.yards_to_go} at the ${f.yardline}` : "";
  console.log(`${score}  Q${live.period}${clock}${down}  (seq ${lastSeq})`);
}
let attempt = 0;
const fatal = new Set(["unauthorized", "forbidden", "unknown_stream", "too_many_subscriptions", "quota_exhausted", "bad_request", "invalid_resume"]);
// Steps 5 and 6: subscribe from lastSeq, apply changes, and reconnect with resume.
function connect() {
  const ws = new WebSocket(STREAM, { headers: { Authorization: `Bearer ${KEY}` } });
  let idle: ReturnType<typeof setTimeout> | undefined;
  const alive = () => {
    clearTimeout(idle);
    idle = setTimeout(() => ws.terminate(), 15_000);
  };
  const subscribe = () => ws.send(JSON.stringify({ type: "subscribe", streams: [stream], resume: { [stream]: lastSeq } }));
  ws.on("open", alive);
  ws.on("message", async (raw) => {
    alive();
    const msg = JSON.parse(raw.toString());
    switch (msg.type) {
      case "welcome":
        subscribe();
        break;
      case "changes":
        attempt = 0;
        for (const c of msg.changes as Change[]) {
          if (c.seq <= lastSeq) continue;
          if (c.seq !== lastSeq + 1) return ws.close();
          if (c.op === "delete") state.set(`${c.entity_type}:${c.entity_id}`, { version: c.version, payload: null });
          else put(c.entity_type, c.entity_id, c.version, c.payload);
          lastSeq = c.seq;
        }
        render();
        break;
      case "error":
        console.error(`${msg.code}: ${msg.message}`);
        if (msg.code === "resync_required") {
          try {
            await readGame();
            subscribe();
          } catch (err) {
            console.error((err as Error).message);
            ws.close();
          }
        } else if (msg.code === "slow_consumer") {
          subscribe();
        } else if (fatal.has(msg.code)) {
          process.exit(1);
        } else {
          ws.close();
        }
        break;
    }
  });
  ws.on("error", (err) => console.error(err.message));
  ws.on("close", (code) => {
    clearTimeout(idle);
    if (code === 1008) {
      console.error("The key was rejected or the plan has no streaming access.");
      process.exit(1);
    }
    const delay = Math.min(30_000, 1000 * 2 ** attempt++) * (0.5 + Math.random() / 2);
    console.error(`Disconnected (${code}), resuming from seq ${lastSeq} in ${Math.round(delay / 1000)}s`);
    setTimeout(connect, delay);
  });
}
await readGame();
render();
connect();