campus-stats 0.4.3 → 0.6.0

package/dist/sources/statsbomb.js

@@ -1,22 +1,36 @@
 /**
- * StatsBomb Open Data adapter.
+ * StatsBomb adapter — free Open Data by default, optional paid API.
  *
- * Upstream: https://github.com/statsbomb/open-data
- * Free for research and genuine football-analytics use. If you publish
- * analysis built on this data, credit StatsBomb
- * (https://statsbomb.com/media-pack/). Pass that requirement downstream.
+ * Free (no login):
+ *   https://github.com/statsbomb/open-data
+ *   Credit StatsBomb in published analysis (https://statsbomb.com/media-pack/).
  *
- * This adapter only surfaces women's competitions
- * (`competition_gender === "female"`).
+ * Paid (customer login — same as statsbombpy):
+ *   SB_USERNAME + SB_PASSWORD → https://data.statsbombservices.com
+ *   Coverage and freshness follow your StatsBomb contract.
+ *
+ * Women's competitions only (`competition_gender === "female"`).
  */
+import { DEFAULT_STATSBOMB_API_BASE, } from "../credentials.js";
 import { aggregateStatsBombPlayerMatch } from "./statsbomb-player-stats.js";
 import { entityId } from "../ids.js";
+import { statsBombPaidUrls, paidExtrasSummary, } from "./statsbomb-endpoints.js";
 const SOURCE = "statsbomb";
-const BASE = "https://raw.githubusercontent.com/statsbomb/open-data/master/data";
+const OPEN_DATA_BASE = "https://raw.githubusercontent.com/statsbomb/open-data/master/data";
 function normalizeName(name) {
     return name.trim().toLowerCase();
 }
-async function defaultFetchJson(url) {
+function asArray(payload) {
+    if (payload == null)
+        return [];
+    if (Array.isArray(payload))
+        return payload;
+    return Object.values(payload);
+}
+function basicAuthHeader(username, password) {
+    return `Basic ${Buffer.from(`${username}:${password}`, "utf8").toString("base64")}`;
+}
+async function defaultOpenFetchJson(url) {
     const res = await fetch(url);
     if (!res.ok) {
         throw new Error(`StatsBomb fetch failed (${res.status}): ${url}`);
@@ -25,19 +39,84 @@ async function defaultFetchJson(url) {
 }
 export class StatsBombSource {
     id = SOURCE;
-    baseUrl;
+    accessMode;
+    openDataBaseUrl;
+    apiBaseUrl;
+    username;
+    password;
     fetchJson;
     includePlayerStats;
     playerStatsLimit;
+    paidExtras;
     constructor(options = {}) {
-        this.baseUrl = options.baseUrl ?? BASE;
-        this.fetchJson = options.fetchJson ?? defaultFetchJson;
+        const username = options.credentials?.username?.trim();
+        const password = options.credentials?.password?.trim();
+        this.accessMode = username && password ? "paid" : "open-data";
+        this.username = username;
+        this.password = password;
+        this.openDataBaseUrl =
+            options.openDataBaseUrl ?? options.baseUrl ?? OPEN_DATA_BASE;
+        this.apiBaseUrl = (options.apiBaseUrl ??
+            options.credentials?.apiBaseUrl ??
+            DEFAULT_STATSBOMB_API_BASE).replace(/\/$/, "");
         this.includePlayerStats = options.includePlayerStats ?? false;
         this.playerStatsLimit = options.playerStatsLimit ?? 5;
+        this.paidExtras = options.paidExtras ?? {};
+        if (options.fetchJson) {
+            this.fetchJson = options.fetchJson;
+        }
+        else if (this.accessMode === "paid") {
+            const user = username;
+            const pass = password;
+            this.fetchJson = async (url) => {
+                const res = await fetch(url, {
+                    headers: {
+                        accept: "application/json",
+                        authorization: basicAuthHeader(user, pass),
+                        "user-agent": "campus-stats (StatsBomb customer BYOK; +https://github.com/Minacava/campus-stats)",
+                    },
+                });
+                if (!res.ok) {
+                    throw new Error(`StatsBomb paid API HTTP ${res.status} for ${url}. ` +
+                        `Check SB_USERNAME / SB_PASSWORD and that your contract covers this endpoint.`);
+                }
+                return (await res.json());
+            };
+        }
+        else {
+            this.fetchJson = defaultOpenFetchJson;
+        }
+    }
+    paidUrls() {
+        return statsBombPaidUrls(this.apiBaseUrl);
+    }
+    competitionsUrl() {
+        if (this.accessMode === "paid") {
+            return this.paidUrls().competitions();
+        }
+        return `${this.openDataBaseUrl}/competitions.json`;
+    }
+    matchesUrl(competitionId, seasonId) {
+        if (this.accessMode === "paid") {
+            return this.paidUrls().matches(competitionId, seasonId);
+        }
+        return `${this.openDataBaseUrl}/matches/${competitionId}/${seasonId}.json`;
+    }
+    lineupsUrl(matchId) {
+        if (this.accessMode === "paid") {
+            return this.paidUrls().lineups(matchId);
+        }
+        return `${this.openDataBaseUrl}/lineups/${matchId}.json`;
+    }
+    eventsUrl(matchId) {
+        if (this.accessMode === "paid") {
+            return this.paidUrls().events(matchId);
+        }
+        return `${this.openDataBaseUrl}/events/${matchId}.json`;
     }
     /** Catalogue of women's competitions (clubs + national-team tournaments). */
     async listWomenCompetitions() {
-        const all = await this.fetchJson(`${this.baseUrl}/competitions.json`);
+        const all = asArray(await this.fetchJson(this.competitionsUrl()));
         const byId = new Map();
         for (const row of all) {
             if (row.competition_gender !== "female")
@@ -59,7 +138,7 @@ export class StatsBombSource {
         return [...byId.values()].sort((a, b) => a.name.localeCompare(b.name));
     }
     async syncCompetition(competitionName) {
-        const all = await this.fetchJson(`${this.baseUrl}/competitions.json`);
+        const all = asArray(await this.fetchJson(this.competitionsUrl()));
         const rows = all.filter((c) => c.competition_gender === "female" &&
             normalizeName(c.competition_name) === normalizeName(competitionName));
         if (rows.length === 0) {
@@ -68,8 +147,11 @@ export class StatsBombSource {
                     .filter((c) => c.competition_gender === "female")
                     .map((c) => c.competition_name)),
             ].sort();
-            throw new Error(`Competition not found in StatsBomb women's data: "${competitionName}". ` +
-                `Available: ${available.join(", ")}`);
+            const modeHint = this.accessMode === "paid"
+                ? "StatsBomb paid API (your contract coverage)"
+                : "StatsBomb Open Data";
+            throw new Error(`Competition not found in ${modeHint}: "${competitionName}". ` +
+                `Available: ${available.join(", ") || "(none)"}`);
         }
         const competitions = new Map();
         const seasons = new Map();
@@ -99,7 +181,7 @@ export class StatsBombSource {
                     },
                 ],
             });
-            const matchRows = await this.fetchJson(`${this.baseUrl}/matches/${row.competition_id}/${row.season_id}.json`);
+            const matchRows = asArray(await this.fetchJson(this.matchesUrl(row.competition_id, row.season_id)));
             for (const m of matchRows) {
                 const homeId = entityId(SOURCE, "team", m.home_team.home_team_id);
                 const awayId = entityId(SOURCE, "team", m.away_team.away_team_id);
@@ -144,6 +226,82 @@ export class StatsBombSource {
         }
         return result;
     }
+    /**
+     * Hit optional paid-only endpoints for a sample competition/season/match.
+     * Confirms the licence covers them; Campus does not yet map these into the
+     * canonical schema (probe only).
+     */
+    async probePaidExtras(context) {
+        const enabled = paidExtrasSummary(this.paidExtras);
+        if (enabled.length === 0)
+            return [];
+        if (this.accessMode !== "paid") {
+            throw new Error(`Paid extras (${enabled.join(", ")}) need SB_USERNAME / SB_PASSWORD. ` +
+                `See docs/statsbomb-endpoints.md.`);
+        }
+        const urls = this.paidUrls();
+        const jobs = [];
+        if (this.paidExtras.playerSeasonStats) {
+            jobs.push({
+                id: "playerSeasonStats",
+                url: urls.playerSeasonStats(context.competitionId, context.seasonId),
+            });
+        }
+        if (this.paidExtras.teamSeasonStats) {
+            jobs.push({
+                id: "teamSeasonStats",
+                url: urls.teamSeasonStats(context.competitionId, context.seasonId),
+            });
+        }
+        if (context.matchId != null) {
+            if (this.paidExtras.playerMatchStats) {
+                jobs.push({
+                    id: "playerMatchStats",
+                    url: urls.playerMatchStats(context.matchId),
+                });
+            }
+            if (this.paidExtras.teamMatchStats) {
+                jobs.push({
+                    id: "teamMatchStats",
+                    url: urls.teamMatchStats(context.matchId),
+                });
+            }
+            if (this.paidExtras.frames360) {
+                jobs.push({
+                    id: "frames360",
+                    url: urls.frames360(context.matchId),
+                });
+            }
+        }
+        const out = [];
+        for (const job of jobs) {
+            try {
+                const payload = await this.fetchJson(job.url);
+                const itemCount = Array.isArray(payload)
+                    ? payload.length
+                    : payload && typeof payload === "object"
+                        ? Object.keys(payload).length
+                        : undefined;
+                out.push({
+                    id: job.id,
+                    ok: true,
+                    url: job.url,
+                    itemCount,
+                    mappedToCampusSchema: false,
+                });
+            }
+            catch (err) {
+                out.push({
+                    id: job.id,
+                    ok: false,
+                    url: job.url,
+                    error: err instanceof Error ? err.message : String(err),
+                    mappedToCampusSchema: false,
+                });
+            }
+        }
+        return out;
+    }
     /** Load aggregated v1 player stats + lineups for the given canonical matches. */
     async loadPlayerStatsForMatches(matches) {
         const players = new Map();
@@ -153,8 +311,8 @@ export class StatsBombSource {
             const nativeId = match.sources.find((s) => s.source === SOURCE)?.id;
             if (!nativeId)
                 continue;
-            const lineups = await this.fetchJson(`${this.baseUrl}/lineups/${nativeId}.json`);
-            const events = await this.fetchJson(`${this.baseUrl}/events/${nativeId}.json`);
+            const lineups = asArray(await this.fetchJson(this.lineupsUrl(nativeId)));
+            const events = asArray(await this.fetchJson(this.eventsUrl(nativeId)));
             const agg = aggregateStatsBombPlayerMatch(match.id, lineups, events);
             for (const p of agg.players)
                 players.set(p.id, p);

package/dist/sources/types.d.ts

@@ -1,4 +1,4 @@
-import type { Competition, InjuryRecord, LineupEntry, Match, Player, PlayerMatchStats, Season, Team } from "../types.js";
+import type { Competition, LineupEntry, Match, Player, PlayerMatchStats, Season, Team } from "../types.js";
 /** Result of syncing one competition from a provider into canonical entities. */
 export interface SyncResult {
     competitions: Competition[];
@@ -8,7 +8,6 @@ export interface SyncResult {
     players?: Player[];
     playerMatchStats?: PlayerMatchStats[];
     lineups?: LineupEntry[];
-    injuries?: InjuryRecord[];
 }
 /**
  * Provider adapter contract.

package/dist/types.d.ts

@@ -84,21 +84,6 @@ export interface LineupEntry {
     jerseyNumber?: number | null;
     sources: SourceRef[];
 }
-/**
- * Injury / availability record.
- * Open StatsBomb data does not include injuries — this shape is reserved for
- * future adapters; the CLI currently returns an empty list.
- */
-export interface InjuryRecord {
-    id: string;
-    playerId: string;
-    teamId?: string;
-    status: "injured" | "doubtful" | "suspended" | "unknown";
-    description?: string;
-    fromDate?: string;
-    toDate?: string;
-    sources: SourceRef[];
-}
 /** In-memory / on-disk cache shape (JSON file in v0). */
 export interface CampusCache {
     competitions: Competition[];
@@ -110,5 +95,4 @@ export interface CampusCache {
     players: Player[];
     playerMatchStats: PlayerMatchStats[];
     lineups: LineupEntry[];
-    injuries: InjuryRecord[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "campus-stats",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "Campus — installable women's football data layer for apps (clubs, national teams, matches, fantasy points)",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,11 +41,12 @@
     "cli"
   ],
   "repository": {
-    "url": "https://campus-tawny-mu.vercel.app/"
+    "type": "git",
+    "url": "git+https://github.com/Minacava/campus-stats.git"
   },
-  "homepage": "https://campus-tawny-mu.vercel.app/",
+  "homepage": "https://github.com/Minacava/campus-stats#readme",
   "bugs": {
-    "url": "https://campus-tawny-mu.vercel.app/"
+    "url": "https://github.com/Minacava/campus-stats/issues"
   },
   "license": "MIT",
   "devDependencies": {

package/dist/injuries.d.ts

@@ -1,12 +0,0 @@
-/**
- * Injury / availability feed.
- *
- * StatsBomb Open Data (and our FBref pilot) do not publish injury lists.
- * This module keeps a stable API so fantasy apps can call `listInjuries`
- * today and plug a future adapter without changing call sites.
- */
-import type { CampusCache, InjuryRecord } from "./types.js";
-export declare const INJURIES_AVAILABLE = false;
-export declare const INJURIES_STATUS_MESSAGE: string;
-/** Always empty until an injury-capable adapter is added. */
-export declare function listInjuries(cache: CampusCache): InjuryRecord[];

package/dist/injuries.js

@@ -1,15 +0,0 @@
-/**
- * Injury / availability feed.
- *
- * StatsBomb Open Data (and our FBref pilot) do not publish injury lists.
- * This module keeps a stable API so fantasy apps can call `listInjuries`
- * today and plug a future adapter without changing call sites.
- */
-export const INJURIES_AVAILABLE = false;
-export const INJURIES_STATUS_MESSAGE = "Injury feeds are not available from current open sources (StatsBomb / FBref pilot). " +
-    "campus exposes InjuryRecord + listInjuries() for future adapters; " +
-    "today the list is always empty.";
-/** Always empty until an injury-capable adapter is added. */
-export function listInjuries(cache) {
-    return cache.injuries ?? [];
-}