pitchapi 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PitchAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# pitchapi — TypeScript SDK
+
+Typed TypeScript/JavaScript client for the [PitchAPI](https://pitchapi.dev)
+football-data API. Match results, shots, xG, lineups, momentum, events, player
+stats, head-to-head, and advanced analytics derived from the event feed.
+
+- Zero dependencies — built on the platform `fetch` (Node 18+, Bun, Deno, edge runtimes)
+- Response types generated from the API's OpenAPI description
+- ESM and CommonJS builds, with type declarations for both
+- Typed errors mapped from the API's stable `error.code`
+- Automatic retries on `429`/`5xx` with `Retry-After` honoured
+
+## Install
+
+```bash
+npm install pitchapi
+```
+
+## Quick start
+
+```ts
+import { PitchAPI } from "pitchapi";
+
+const client = new PitchAPI({ apiKey: "pk_live_..." });
+
+const day = await client.date.get("2026-08-27");
+for (const m of day.matches) {
+  console.log(m.home_team.name, m.score_home, "-", m.score_away, m.away_team.name);
+}
+
+const match = await client.matches.get("m_4DP2fy");
+const shots = await client.matches.shots(match.id);
+const adv = await client.matches.advanced(match.id);        // team rollups
+const net = await client.matches.advancedNetwork(match.id); // pass networks
+```
+
+The key can also come from the `PITCHAPI_API_KEY` environment variable, in
+which case `new PitchAPI()` needs no arguments. Keep the key server-side: never
+ship it in browser code.
+
+## Namespaces
+
+| Namespace | Methods |
+|---|---|
+| `client.date` | `get(date, { status })` — `date` is a `YYYY-MM-DD` string or a `Date` (read in UTC) |
+| `client.matches` | `get`, `shots`, `shot`, `events`, `lineups`, `momentum`, `stats`, `players`, `player`, `playersHalves`, `playerHalves`, `playerShots`, `h2h`, `advanced`, `advancedNetwork`, `advancedPlayers`, `advancedPlayer`, `heatmaps(id, { frame })` |
+| `client.leagues` | `list`, `get`, `matches(id, { season, status })` |
+| `client.teams` | `get` |
+| `client.players` | `get` |
+
+Every method takes an optional last argument `{ signal }` to abort it. Every
+response type is exported by name:
+
+```ts
+import type { Match, Shot, AdvancedTeams } from "pitchapi";
+```
+
+## Upcoming fixtures
+
+Match listings return played matches by default. Pass `status` to reach
+scheduled ones — `"upcoming"` for fixtures that have not kicked off, `"all"`
+for both. An upcoming match carries a kickoff `time_utc` and a `status`, but
+its scores are `null` until it is played.
+
+```ts
+const { matches } = await client.date.get("2026-09-01", { status: "upcoming" });
+
+// The season is resolved first, so asking for upcoming fixtures of a finished
+// campaign is an empty list, not next season's.
+await client.leagues.matches("l_0bfbkO", { season: "2025/2026", status: "all" });
+```
+
+Lineups for a fixture may be a pre-match prediction. `confirmed` is the flag to
+branch on.
+
+```ts
+const lineups = await client.matches.lineups("m_4DP2fy");
+if (lineups.home.confirmed) {
+  console.log(lineups.home.formation, lineups.home.starters.map((p) => p.name));
+}
+```
+
+## Errors
+
+```ts
+import { NotFoundError, RateLimitError } from "pitchapi";
+
+try {
+  await client.matches.advanced("m_unprocessed");
+} catch (e) {
+  if (e instanceof NotFoundError) {
+    // RESOURCE_NOT_FOUND, ANALYTICS_UNAVAILABLE or HALVES_UNAVAILABLE
+    console.log(e.code, e.requestId);
+  } else if (e instanceof RateLimitError) {
+    console.log("retry after", e.retryAfter, "s");
+  } else {
+    throw e;
+  }
+}
+```
+
+Every error extends `PitchAPIError` and carries `code`, `status` and
+`requestId` where the API supplied them.
+
+## Configuration
+
+```ts
+new PitchAPI({
+  apiKey: "pk_live_...",
+  baseUrl: "https://api.pitchapi.dev", // override for tests / proxies
+  timeoutMs: 30_000,                   // per attempt
+  maxRetries: 2,                       // 429/5xx + network errors; 0 disables
+  fetch: customFetch,                  // defaults to globalThis.fetch
+});
+```
+
+## License
+
+This client library is released under the MIT License.
+
+The licence covers the SDK source only. Access to the PitchAPI service and the
+football data it returns is governed separately by the PitchAPI terms of
+service — an MIT-licensed client does not grant any right to the data.

package/dist/index.cjs

@@ -0,0 +1,397 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIConnectionError: () => APIConnectionError,
+  AuthError: () => AuthError,
+  InvalidParameterError: () => InvalidParameterError,
+  NotFoundError: () => NotFoundError,
+  PitchAPI: () => PitchAPI,
+  PitchAPIError: () => PitchAPIError,
+  PlanUpgradeRequiredError: () => PlanUpgradeRequiredError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  SubscriptionSuspendedError: () => SubscriptionSuspendedError,
+  VERSION: () => VERSION
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIConnectionError,
+  AuthError,
+  InvalidParameterError,
+  NotFoundError,
+  PitchAPI,
+  PitchAPIError,
+  PlanUpgradeRequiredError,
+  RateLimitError,
+  ServerError,
+  SubscriptionSuspendedError,
+  VERSION
+});