pitchapi 0.1.1

package/dist/index.js

@@ -0,0 +1,360 @@
+// src/errors.ts
+var PitchAPIError = class extends Error {
+  constructor(message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = new.target.name;
+    this.code = options.code;
+    this.status = options.status;
+    this.requestId = options.requestId;
+  }
+};
+var APIConnectionError = class extends PitchAPIError {
+};
+var InvalidParameterError = class extends PitchAPIError {
+};
+var AuthError = class extends PitchAPIError {
+};
+var SubscriptionSuspendedError = class extends PitchAPIError {
+};
+var PlanUpgradeRequiredError = class extends PitchAPIError {
+};
+var NotFoundError = class extends PitchAPIError {
+};
+var RateLimitError = class extends PitchAPIError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.retryAfter = options.retryAfter;
+  }
+};
+var ServerError = class extends PitchAPIError {
+};
+var CODE_MAP = {
+  INVALID_PARAMETER: InvalidParameterError,
+  UNAUTHORIZED: AuthError,
+  SUBSCRIPTION_SUSPENDED: SubscriptionSuspendedError,
+  PLAN_UPGRADE_REQUIRED: PlanUpgradeRequiredError,
+  RESOURCE_NOT_FOUND: NotFoundError,
+  ANALYTICS_UNAVAILABLE: NotFoundError,
+  HALVES_UNAVAILABLE: NotFoundError,
+  RATE_LIMIT_EXCEEDED: RateLimitError,
+  INTERNAL_SERVER_ERROR: ServerError
+};
+function errorClassFor(code, status) {
+  if (code !== void 0 && Object.prototype.hasOwnProperty.call(CODE_MAP, code)) {
+    return CODE_MAP[code];
+  }
+  if (status === 400) return InvalidParameterError;
+  if (status === 401) return AuthError;
+  if (status === 403) return PlanUpgradeRequiredError;
+  if (status === 404) return NotFoundError;
+  if (status === 429) return RateLimitError;
+  if (status >= 500) return ServerError;
+  return PitchAPIError;
+}
+
+// src/version.ts
+var VERSION = "0.1.1";
+
+// src/transport.ts
+var DEFAULT_BASE_URL = "https://api.pitchapi.dev";
+var API_PREFIX = "/v1";
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isServerRuntime() {
+  return typeof globalThis.document === "undefined";
+}
+function buildHeaders(apiKey) {
+  const headers = {
+    "X-API-KEY": apiKey,
+    Accept: "application/json"
+  };
+  if (isServerRuntime()) headers["User-Agent"] = `pitchapi-js/${VERSION}`;
+  return headers;
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n >= 0 ? n : void 0;
+}
+function backoffMs(attempt, retryAfter) {
+  if (retryAfter !== void 0) return retryAfter * 1e3;
+  const base = Math.min(2 ** attempt, 8);
+  return Math.random() * base * 1e3;
+}
+function buildQuery(params) {
+  if (!params) return "";
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== void 0) qs.set(k, v);
+  }
+  const s = qs.toString();
+  return s ? `?${s}` : "";
+}
+function unwrap(status, payload, requestId, retryAfter) {
+  if (status >= 200 && status < 300) {
+    if (payload !== null && typeof payload === "object" && "data" in payload) {
+      return payload.data;
+    }
+    throw new PitchAPIError("malformed success response: missing 'data' envelope", { status, requestId });
+  }
+  let code;
+  let message = `HTTP ${status}`;
+  if (payload !== null && typeof payload === "object" && "error" in payload) {
+    const err = payload.error;
+    if (err !== null && typeof err === "object") {
+      const e = err;
+      if (typeof e.code === "string") code = e.code;
+      if (typeof e.message === "string") message = e.message;
+    }
+  }
+  const Cls = errorClassFor(code, status);
+  if (Cls === RateLimitError) {
+    throw new RateLimitError(message, { code, status, requestId, retryAfter });
+  }
+  if (Cls === ServerError && code === void 0) message = `server error (HTTP ${status})`;
+  throw new Cls(message, { code, status, requestId });
+}
+var Transport = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.headers = buildHeaders(opts.apiKey);
+    this.sleep = opts.sleep ?? defaultSleep;
+  }
+  async get(path, query, signal) {
+    const url = this.opts.baseUrl + API_PREFIX + path + buildQuery(query);
+    let attempt = 0;
+    for (; ; ) {
+      let response;
+      try {
+        response = await this.fetchOnce(url, signal);
+      } catch (err) {
+        if (signal?.aborted) throw err;
+        if (attempt < this.opts.maxRetries) {
+          await this.sleep(backoffMs(attempt, void 0));
+          attempt++;
+          continue;
+        }
+        throw new APIConnectionError(`request failed: ${describe(err)}`, { cause: err });
+      }
+      const status = response.status;
+      const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+      if (attempt < this.opts.maxRetries && RETRY_STATUSES.has(status)) {
+        await response.body?.cancel().catch(() => void 0);
+        await this.sleep(backoffMs(attempt, retryAfter));
+        attempt++;
+        continue;
+      }
+      const requestId = response.headers.get("X-Request-ID") ?? void 0;
+      let payload = null;
+      try {
+        payload = await response.json();
+      } catch {
+      }
+      return unwrap(status, payload, requestId, retryAfter);
+    }
+  }
+  async fetchOnce(url, signal) {
+    const timeout = AbortSignal.timeout(this.opts.timeoutMs);
+    const combined = signal ? anySignal([signal, timeout]) : timeout;
+    return this.opts.fetch(url, { method: "GET", headers: this.headers, signal: combined });
+  }
+};
+function anySignal(signals) {
+  const any = AbortSignal.any;
+  if (any) return any(signals);
+  const controller = new AbortController();
+  for (const s of signals) {
+    if (s.aborted) {
+      controller.abort(s.reason);
+      break;
+    }
+    s.addEventListener("abort", () => controller.abort(s.reason), { once: true });
+  }
+  return controller.signal;
+}
+function describe(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/client.ts
+function env(name) {
+  const proc = globalThis.process;
+  return proc?.env?.[name] || void 0;
+}
+function formatDate(value) {
+  return typeof value === "string" ? value : value.toISOString().slice(0, 10);
+}
+var seg = encodeURIComponent;
+var Resource = class {
+  constructor(t) {
+    this.t = t;
+  }
+  request(path, opts, query) {
+    return this.t.get(path, query, opts?.signal);
+  }
+};
+var DateResource = class extends Resource {
+  /**
+   * Every match on a day. `date` is a `YYYY-MM-DD` string or a `Date`, which
+   * is read in UTC. An upcoming fixture carries a kickoff `time_utc` and a
+   * `status` but no score yet.
+   */
+  get(date, opts) {
+    return this.request(`/date/${seg(formatDate(date))}`, opts, { status: opts?.status });
+  }
+};
+var MatchesResource = class extends Resource {
+  /** Match summary — league, teams, score, referee, stadium. */
+  get(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}`, opts);
+  }
+  /** Every shot, grouped by period, with pitch coordinates and xG. */
+  shots(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/shots`, opts);
+  }
+  /** A single shot by its opaque ID. */
+  shot(matchId, shotId, opts) {
+    return this.request(`/matches/${seg(matchId)}/shots/${seg(shotId)}`, opts);
+  }
+  /** Match events (goals, cards, subs, ...). */
+  events(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/events`, opts);
+  }
+  /** Starting lineups and substitutes. Before kickoff the XI may be predicted. */
+  lineups(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/lineups`, opts);
+  }
+  /** Possession-momentum timeline. */
+  momentum(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/momentum`, opts);
+  }
+  /** Team-level match statistics. */
+  stats(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/stats`, opts);
+  }
+  /** Per-player match stat lines. */
+  players(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/players`, opts);
+  }
+  /** One player's match stat line. */
+  player(matchId, playerId, opts) {
+    return this.request(`/matches/${seg(matchId)}/players/${seg(playerId)}`, opts);
+  }
+  /**
+   * Every player's stat line for the first and the second half. Throws
+   * `NotFoundError` (code `HALVES_UNAVAILABLE`) for a match without them.
+   */
+  playersHalves(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/players/halves`, opts);
+  }
+  /** One player's stat line for each half they played. */
+  playerHalves(matchId, playerId, opts) {
+    return this.request(`/matches/${seg(matchId)}/players/${seg(playerId)}/halves`, opts);
+  }
+  /** A single player's shots in the match. */
+  playerShots(matchId, playerId, opts) {
+    return this.request(`/matches/${seg(matchId)}/players/${seg(playerId)}/shots`, opts);
+  }
+  /** Head-to-head history for the two sides. */
+  h2h(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/h2h`, opts);
+  }
+  /**
+   * Team advanced rollups (PPDA, field tilt, xG timeline). Throws
+   * `NotFoundError` (code `ANALYTICS_UNAVAILABLE`) for a match not yet rated.
+   */
+  advanced(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/advanced`, opts);
+  }
+  /** Pass networks for both sides. */
+  advancedNetwork(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/advanced/network`, opts);
+  }
+  /** Player-level advanced rollups. */
+  advancedPlayers(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/advanced/players`, opts);
+  }
+  /** One player's advanced rollup. */
+  advancedPlayer(matchId, playerId, opts) {
+    return this.request(`/matches/${seg(matchId)}/advanced/players/${seg(playerId)}`, opts);
+  }
+  /**
+   * Binned activity for both teams and every player who touched the ball.
+   * Cells are sparse `[cell_x, cell_y, actions]` triples on a 16x12 grid.
+   */
+  heatmaps(matchId, opts) {
+    return this.request(`/matches/${seg(matchId)}/heatmaps`, opts, { frame: opts?.frame });
+  }
+};
+var LeaguesResource = class extends Resource {
+  /** All leagues, each with its accepted seasons and coverage. */
+  list(opts) {
+    return this.request("/leagues", opts);
+  }
+  /** League detail. */
+  get(leagueId, opts) {
+    return this.request(`/leagues/${seg(leagueId)}`, opts);
+  }
+  /**
+   * Matches in a league. `season` is `"2025/2026"` for a fall-spring league
+   * and `"2026"` for a calendar-year one; omitted, the latest season with
+   * data. The season is resolved before `status` applies, so `upcoming` on a
+   * finished season is an empty list.
+   */
+  matches(leagueId, opts) {
+    return this.request(`/leagues/${seg(leagueId)}/matches`, opts, {
+      season: opts?.season,
+      status: opts?.status
+    });
+  }
+};
+var TeamsResource = class extends Resource {
+  /** Team profile. */
+  get(teamId, opts) {
+    return this.request(`/teams/${seg(teamId)}`, opts);
+  }
+};
+var PlayersResource = class extends Resource {
+  /** Player profile. */
+  get(playerId, opts) {
+    return this.request(`/players/${seg(playerId)}`, opts);
+  }
+};
+var PitchAPI = class {
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? env("PITCHAPI_API_KEY");
+    if (!apiKey) {
+      throw new Error("an API key is required: pass { apiKey } or set the PITCHAPI_API_KEY environment variable");
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new Error("no global fetch: use Node 18+ or pass { fetch }");
+    }
+    const transport = new Transport({
+      apiKey,
+      baseUrl: (options.baseUrl ?? env("PITCHAPI_BASE_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+      timeoutMs: options.timeoutMs ?? 3e4,
+      maxRetries: options.maxRetries ?? 2,
+      // Bound to globalThis: some runtimes throw on an unbound fetch.
+      fetch: options.fetch ?? fetchImpl.bind(globalThis)
+    });
+    this.date = new DateResource(transport);
+    this.matches = new MatchesResource(transport);
+    this.leagues = new LeaguesResource(transport);
+    this.teams = new TeamsResource(transport);
+    this.players = new PlayersResource(transport);
+  }
+};
+export {
+  APIConnectionError,
+  AuthError,
+  InvalidParameterError,
+  NotFoundError,
+  PitchAPI,
+  PitchAPIError,
+  PlanUpgradeRequiredError,
+  RateLimitError,
+  ServerError,
+  SubscriptionSuspendedError,
+  VERSION
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "pitchapi",
+  "version": "0.1.1",
+  "description": "TypeScript SDK for the PitchAPI football-data API",
+  "keywords": [
+    "football",
+    "soccer",
+    "xg",
+    "analytics",
+    "api",
+    "sdk"
+  ],
+  "license": "MIT",
+  "author": "PitchAPI",
+  "homepage": "https://pitchapi.dev",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "gen": "node scripts/gen.mjs",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
+    "test": "vitest run",
+    "check": "publint --strict && attw --pack . --profile node16",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run check"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@types/node": "^22.20.5",
+    "openapi-typescript": "7.13.0",
+    "publint": "0.3.25",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7"
+  }
+}