campus-stats 0.4.3 → 0.6.0

package/dist/data-bundle.js

@@ -1,17 +1,18 @@
 /**
- * Published women's fantasy data bundle (refreshed by GitLab CI cron).
- * Generic Package Registry paths under project 86296665.
+ * Published women's fantasy data bundle (refreshed by GitHub Actions cron).
+ * Served as assets on the rolling Release tag `data-latest`.
  */
-export const GITLAB_PROJECT_ID = "86296665";
-export const DATA_BUNDLE_PACKAGE = "campus-data";
-export const DATA_BUNDLE_VERSION = "latest";
+export const DATA_BUNDLE_OWNER = "Minacava";
+export const DATA_BUNDLE_REPO = "campus-stats";
+export const DATA_BUNDLE_RELEASE_TAG = "data-latest";
 export const DATA_BUNDLE_FILE = "cache.json";
+export const DATA_BUNDLE_META_FILE = "meta.json";
 /** Absolute URL of the periodically refreshed cache snapshot. */
-export function dataBundleUrl(projectId = GITLAB_PROJECT_ID, version = DATA_BUNDLE_VERSION) {
-    return (`https://gitlab.com/api/v4/projects/${projectId}/packages/generic/` +
-        `${DATA_BUNDLE_PACKAGE}/${version}/${DATA_BUNDLE_FILE}`);
+export function dataBundleUrl(tag = DATA_BUNDLE_RELEASE_TAG) {
+    return (`https://github.com/${DATA_BUNDLE_OWNER}/${DATA_BUNDLE_REPO}` +
+        `/releases/download/${tag}/${DATA_BUNDLE_FILE}`);
 }
-export function dataBundleMetaUrl(projectId = GITLAB_PROJECT_ID, version = DATA_BUNDLE_VERSION) {
-    return (`https://gitlab.com/api/v4/projects/${projectId}/packages/generic/` +
-        `${DATA_BUNDLE_PACKAGE}/${version}/meta.json`);
+export function dataBundleMetaUrl(tag = DATA_BUNDLE_RELEASE_TAG) {
+    return (`https://github.com/${DATA_BUNDLE_OWNER}/${DATA_BUNDLE_REPO}` +
+        `/releases/download/${tag}/${DATA_BUNDLE_META_FILE}`);
 }

package/dist/db/sqlite-store.d.ts

@@ -1,5 +1,5 @@
 import type { CampusCache } from "../types.js";
-export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS competitions (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  country TEXT,\n  gender TEXT NOT NULL,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS seasons (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  competition_id TEXT NOT NULL,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS teams (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  country TEXT,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS matches (\n  id TEXT PRIMARY KEY,\n  competition_id TEXT NOT NULL,\n  season_id TEXT NOT NULL,\n  date TEXT,\n  home_team_id TEXT NOT NULL,\n  away_team_id TEXT NOT NULL,\n  home_score INTEGER,\n  away_score INTEGER,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS identities (\n  id TEXT PRIMARY KEY,\n  kind TEXT NOT NULL,\n  name TEXT NOT NULL,\n  aliases_json TEXT NOT NULL,\n  sources_json TEXT NOT NULL,\n  confidence TEXT NOT NULL,\n  status TEXT NOT NULL,\n  competition_hint TEXT\n);\nCREATE TABLE IF NOT EXISTS players (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  nickname TEXT,\n  country TEXT,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS player_match_stats (\n  id TEXT PRIMARY KEY,\n  match_id TEXT NOT NULL,\n  player_id TEXT NOT NULL,\n  team_id TEXT NOT NULL,\n  minutes INTEGER,\n  goals INTEGER NOT NULL,\n  assists INTEGER NOT NULL,\n  yellow_cards INTEGER NOT NULL,\n  red_cards INTEGER NOT NULL,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS lineups (\n  id TEXT PRIMARY KEY,\n  match_id TEXT NOT NULL,\n  team_id TEXT NOT NULL,\n  player_id TEXT NOT NULL,\n  started INTEGER NOT NULL,\n  jersey_number INTEGER,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS injuries (\n  id TEXT PRIMARY KEY,\n  player_id TEXT NOT NULL,\n  team_id TEXT,\n  status TEXT NOT NULL,\n  description TEXT,\n  from_date TEXT,\n  to_date TEXT,\n  sources_json TEXT NOT NULL\n);\n";
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS competitions (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  country TEXT,\n  gender TEXT NOT NULL,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS seasons (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  competition_id TEXT NOT NULL,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS teams (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  country TEXT,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS matches (\n  id TEXT PRIMARY KEY,\n  competition_id TEXT NOT NULL,\n  season_id TEXT NOT NULL,\n  date TEXT,\n  home_team_id TEXT NOT NULL,\n  away_team_id TEXT NOT NULL,\n  home_score INTEGER,\n  away_score INTEGER,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS identities (\n  id TEXT PRIMARY KEY,\n  kind TEXT NOT NULL,\n  name TEXT NOT NULL,\n  aliases_json TEXT NOT NULL,\n  sources_json TEXT NOT NULL,\n  confidence TEXT NOT NULL,\n  status TEXT NOT NULL,\n  competition_hint TEXT\n);\nCREATE TABLE IF NOT EXISTS players (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  nickname TEXT,\n  country TEXT,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS player_match_stats (\n  id TEXT PRIMARY KEY,\n  match_id TEXT NOT NULL,\n  player_id TEXT NOT NULL,\n  team_id TEXT NOT NULL,\n  minutes INTEGER,\n  goals INTEGER NOT NULL,\n  assists INTEGER NOT NULL,\n  yellow_cards INTEGER NOT NULL,\n  red_cards INTEGER NOT NULL,\n  sources_json TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS lineups (\n  id TEXT PRIMARY KEY,\n  match_id TEXT NOT NULL,\n  team_id TEXT NOT NULL,\n  player_id TEXT NOT NULL,\n  started INTEGER NOT NULL,\n  jersey_number INTEGER,\n  sources_json TEXT NOT NULL\n);\n";
 export declare class SqliteStore {
     private readonly db;
     constructor(dbPath: string);

package/dist/db/sqlite-store.js

@@ -69,16 +69,6 @@ CREATE TABLE IF NOT EXISTS lineups (
   jersey_number INTEGER,
   sources_json TEXT NOT NULL
 );
-CREATE TABLE IF NOT EXISTS injuries (
-  id TEXT PRIMARY KEY,
-  player_id TEXT NOT NULL,
-  team_id TEXT,
-  status TEXT NOT NULL,
-  description TEXT,
-  from_date TEXT,
-  to_date TEXT,
-  sources_json TEXT NOT NULL
-);
 `;
 function j(value) {
     return JSON.stringify(value);
@@ -109,7 +99,6 @@ export class SqliteStore {
                 "players",
                 "player_match_stats",
                 "lineups",
-                "injuries",
             ]) {
                 this.db.prepare(`DELETE FROM ${table}`).run();
             }
@@ -228,19 +217,6 @@ export class SqliteStore {
             jerseyNumber: row.jersey_number == null ? null : Number(row.jersey_number),
             sources: parseJson(String(row.sources_json)),
         }));
-        const injuries = this.db
-            .prepare("SELECT * FROM injuries")
-            .all()
-            .map((row) => ({
-            id: String(row.id),
-            playerId: String(row.player_id),
-            teamId: row.team_id == null ? undefined : String(row.team_id),
-            status: String(row.status),
-            description: row.description == null ? undefined : String(row.description),
-            fromDate: row.from_date == null ? undefined : String(row.from_date),
-            toDate: row.to_date == null ? undefined : String(row.to_date),
-            sources: parseJson(String(row.sources_json)),
-        }));
         return {
             competitions,
             seasons,
@@ -250,7 +226,6 @@ export class SqliteStore {
             players,
             playerMatchStats,
             lineups,
-            injuries,
         };
     }
     insertCache(cache) {
@@ -329,16 +304,5 @@ export class SqliteStore {
         for (const l of cache.lineups) {
             upsertLineup.run(l.id, l.matchId, l.teamId, l.playerId, l.started ? 1 : 0, l.jerseyNumber ?? null, j(l.sources));
         }
-        const upsertInjury = this.db.prepare(`INSERT INTO injuries (
-         id, player_id, team_id, status, description, from_date, to_date, sources_json
-       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(id) DO UPDATE SET
-         player_id=excluded.player_id, team_id=excluded.team_id,
-         status=excluded.status, description=excluded.description,
-         from_date=excluded.from_date, to_date=excluded.to_date,
-         sources_json=excluded.sources_json`);
-        for (const i of cache.injuries) {
-            upsertInjury.run(i.id, i.playerId, i.teamId ?? null, i.status, i.description ?? null, i.fromDate ?? null, i.toDate ?? null, j(i.sources));
-        }
     }
 }

package/dist/fantasy.js

@@ -100,7 +100,6 @@ function emptySyncResult() {
         players: [],
         playerMatchStats: [],
         lineups: [],
-        injuries: [],
     };
 }
 function mergeSyncResults(a, b) {
@@ -109,13 +108,11 @@ function mergeSyncResults(a, b) {
         players: a.players ?? [],
         playerMatchStats: a.playerMatchStats ?? [],
         lineups: a.lineups ?? [],
-        injuries: a.injuries ?? [],
     }), {
         ...b,
         players: b.players ?? [],
         playerMatchStats: b.playerMatchStats ?? [],
         lineups: b.lineups ?? [],
-        injuries: b.injuries ?? [],
     });
     return {
         competitions: cache.competitions,
@@ -125,7 +122,6 @@ function mergeSyncResults(a, b) {
         players: cache.players,
         playerMatchStats: cache.playerMatchStats,
         lineups: cache.lineups,
-        injuries: cache.injuries,
     };
 }
 function pickMatchesForPlayerStats(result, opts) {

package/dist/http.js

@@ -2,7 +2,7 @@
  * Polite HTTP helper for HTML sources (FBref, etc.).
  * Sequential requests share a minimum delay; failed GETs retry with backoff.
  */
-const DEFAULT_UA = "campus/0.0.1 (women's football research; +https://gitlab.com/marina34/campus)";
+const DEFAULT_UA = "campus/0.0.1 (women's football research; +https://github.com/Minacava/campus-stats)";
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/index.d.ts

@@ -1,16 +1,16 @@
-export type { SourceRef, TeamKind, Competition, Season, Team, Match, Player, PlayerMatchStats, LineupEntry, InjuryRecord, CampusCache, } from "./types.js";
+export type { SourceRef, TeamKind, Competition, Season, Team, Match, Player, PlayerMatchStats, LineupEntry, CampusCache, } from "./types.js";
 export type { IdentityKind, IdentityConfidence, IdentityStatus, CanonicalIdentity, } from "./identity/types.js";
 export type { FootballSource, SyncResult } from "./sources/types.js";
-export { StatsBombSource } from "./sources/statsbomb.js";
-export type { WomenCompetitionInfo } from "./sources/statsbomb.js";
-export { FbrefSource, listFbrefPilotNames } from "./sources/fbref.js";
+export { StatsBombSource, FbrefSource, listFbrefPilotNames, createFootballSource, KNOWN_SOURCE_IDS, listStatsBombEndpoints, paidExtrasSummary, statsBombPaidUrls, STATSBOMB_API_VERSIONS, STATSBOMB_ENDPOINT_CATALOG, } from "./sources/index.js";
+export type { WomenCompetitionInfo, StatsBombAccessMode, StatsBombSourceOptions, FbrefSourceOptions, SourceId, CreateSourceOptions, StatsBombPaidExtras, StatsBombEndpointInfo, StatsBombEndpointId, StatsBombEndpointAvailability, } from "./sources/index.js";
+export { SB_USERNAME_ENV, SB_PASSWORD_ENV, CAMPUS_STATSBOMB_USERNAME_ENV, CAMPUS_STATSBOMB_PASSWORD_ENV, CAMPUS_STATSBOMB_API_BASE_URL_ENV, DEFAULT_STATSBOMB_API_BASE, defaultConfigPath, loadConfigFile, resolveCredentials, requireStatsBombPaidLogin, maskSecret, describeCredentials, requireApiKey, } from "./credentials.js";
+export type { StatsBombCredentials, CampusConfigFile, CredentialSource, ResolvedCredentials, ResolveCredentialsOptions, } from "./credentials.js";
 export { emptyCache, cachePath, loadCache, saveCache, mergeSyncResult, DEFAULT_CACHE_DIR, DEFAULT_CACHE_FILE, } from "./cache.js";
 export { SqliteStore, SCHEMA_SQL } from "./db/sqlite-store.js";
 export { FANTASY_PLAYER_STATS_LIMIT, listWomenCompetitions, syncFantasyBundle, updateCachedCompetitions, competitionIsInternational, } from "./fantasy.js";
 export type { FantasySyncOptions } from "./fantasy.js";
-export { GITLAB_PROJECT_ID, DATA_BUNDLE_PACKAGE, DATA_BUNDLE_VERSION, DATA_BUNDLE_FILE, dataBundleUrl, dataBundleMetaUrl, } from "./data-bundle.js";
+export { DATA_BUNDLE_OWNER, DATA_BUNDLE_REPO, DATA_BUNDLE_RELEASE_TAG, DATA_BUNDLE_FILE, DATA_BUNDLE_META_FILE, dataBundleUrl, dataBundleMetaUrl, } from "./data-bundle.js";
 export { CampusClient } from "./client.js";
 export type { SquadMember } from "./client.js";
 export { DEFAULT_FANTASY_RULES, scorePlayerMatchStats, scoreFantasyPoints, } from "./scoring.js";
 export type { FantasyScoringRules, FantasyPointRow } from "./scoring.js";
-export { INJURIES_AVAILABLE, INJURIES_STATUS_MESSAGE, listInjuries, } from "./injuries.js";

package/dist/index.js

@@ -1,9 +1,8 @@
-export { StatsBombSource } from "./sources/statsbomb.js";
-export { FbrefSource, listFbrefPilotNames } from "./sources/fbref.js";
+export { StatsBombSource, FbrefSource, listFbrefPilotNames, createFootballSource, KNOWN_SOURCE_IDS, listStatsBombEndpoints, paidExtrasSummary, statsBombPaidUrls, STATSBOMB_API_VERSIONS, STATSBOMB_ENDPOINT_CATALOG, } from "./sources/index.js";
+export { SB_USERNAME_ENV, SB_PASSWORD_ENV, CAMPUS_STATSBOMB_USERNAME_ENV, CAMPUS_STATSBOMB_PASSWORD_ENV, CAMPUS_STATSBOMB_API_BASE_URL_ENV, DEFAULT_STATSBOMB_API_BASE, defaultConfigPath, loadConfigFile, resolveCredentials, requireStatsBombPaidLogin, maskSecret, describeCredentials, requireApiKey, } from "./credentials.js";
 export { emptyCache, cachePath, loadCache, saveCache, mergeSyncResult, DEFAULT_CACHE_DIR, DEFAULT_CACHE_FILE, } from "./cache.js";
 export { SqliteStore, SCHEMA_SQL } from "./db/sqlite-store.js";
 export { FANTASY_PLAYER_STATS_LIMIT, listWomenCompetitions, syncFantasyBundle, updateCachedCompetitions, competitionIsInternational, } from "./fantasy.js";
-export { GITLAB_PROJECT_ID, DATA_BUNDLE_PACKAGE, DATA_BUNDLE_VERSION, DATA_BUNDLE_FILE, dataBundleUrl, dataBundleMetaUrl, } from "./data-bundle.js";
+export { DATA_BUNDLE_OWNER, DATA_BUNDLE_REPO, DATA_BUNDLE_RELEASE_TAG, DATA_BUNDLE_FILE, DATA_BUNDLE_META_FILE, dataBundleUrl, dataBundleMetaUrl, } from "./data-bundle.js";
 export { CampusClient } from "./client.js";
 export { DEFAULT_FANTASY_RULES, scorePlayerMatchStats, scoreFantasyPoints, } from "./scoring.js";
-export { INJURIES_AVAILABLE, INJURIES_STATUS_MESSAGE, listInjuries, } from "./injuries.js";

package/dist/sources/create.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Factory for CLI / library source selection.
+ */
+import type { StatsBombCredentials } from "../credentials.js";
+import { type FbrefSourceOptions } from "./fbref.js";
+import { type StatsBombSourceOptions } from "./statsbomb.js";
+import type { FootballSource } from "./types.js";
+export type SourceId = "statsbomb" | "fbref";
+export declare const KNOWN_SOURCE_IDS: SourceId[];
+export interface CreateSourceOptions {
+    statsbomb?: StatsBombSourceOptions;
+    fbref?: FbrefSourceOptions;
+    /** Convenience: StatsBomb customer login for paid API mode. */
+    credentials?: StatsBombCredentials;
+}
+export declare function createFootballSource(id: string, options?: CreateSourceOptions): FootballSource;

package/dist/sources/create.js

@@ -0,0 +1,23 @@
+/**
+ * Factory for CLI / library source selection.
+ */
+import { FbrefSource } from "./fbref.js";
+import { StatsBombSource, } from "./statsbomb.js";
+export const KNOWN_SOURCE_IDS = ["statsbomb", "fbref"];
+export function createFootballSource(id, options = {}) {
+    const normalized = id.trim().toLowerCase();
+    if (normalized === "statsbomb") {
+        return new StatsBombSource({
+            ...options.statsbomb,
+            credentials: options.credentials ?? options.statsbomb?.credentials,
+        });
+    }
+    if (normalized === "fbref") {
+        return new FbrefSource(options.fbref);
+    }
+    if (normalized === "live") {
+        throw new Error('Source "live" was removed. Use --source statsbomb with SB_USERNAME / ' +
+            "SB_PASSWORD for the StatsBomb paid API (see docs/byok.md).");
+    }
+    throw new Error(`Unknown source: "${id}". Use ${KNOWN_SOURCE_IDS.join(", ")}.`);
+}

package/dist/sources/fbref.d.ts

@@ -6,6 +6,9 @@
  * polite HttpClient defaults. This environment often receives Cloudflare
  * 403s; use fixtures / --fixture for offline sync.
  *
+ * Sports Reference does not offer a public FBref API key — Campus has no
+ * paid-key path for this source (see docs/byok.md).
+ *
  * See docs/fbref-pilot.md for competition ids and HTML shape.
  */
 import { HttpClient } from "../http.js";

package/dist/sources/fbref.js

@@ -6,6 +6,9 @@
  * polite HttpClient defaults. This environment often receives Cloudflare
  * 403s; use fixtures / --fixture for offline sync.
  *
+ * Sports Reference does not offer a public FBref API key — Campus has no
+ * paid-key path for this source (see docs/byok.md).
+ *
  * See docs/fbref-pilot.md for competition ids and HTML shape.
  */
 import { HttpClient } from "../http.js";

package/dist/sources/index.d.ts

@@ -1,3 +1,9 @@
 export type { FootballSource, SyncResult } from "./types.js";
 export { StatsBombSource } from "./statsbomb.js";
+export type { StatsBombAccessMode, StatsBombSourceOptions, WomenCompetitionInfo, } from "./statsbomb.js";
 export { FbrefSource, listFbrefPilotNames } from "./fbref.js";
+export type { FbrefSourceOptions } from "./fbref.js";
+export { createFootballSource, KNOWN_SOURCE_IDS } from "./create.js";
+export type { SourceId, CreateSourceOptions } from "./create.js";
+export { listStatsBombEndpoints, paidExtrasSummary, statsBombPaidUrls, buildPaidEndpointUrl, STATSBOMB_API_VERSIONS, STATSBOMB_ENDPOINT_CATALOG, } from "./statsbomb-endpoints.js";
+export type { StatsBombPaidExtras, StatsBombEndpointInfo, StatsBombEndpointId, StatsBombEndpointAvailability, } from "./statsbomb-endpoints.js";

package/dist/sources/index.js

@@ -1,2 +1,4 @@
 export { StatsBombSource } from "./statsbomb.js";
 export { FbrefSource, listFbrefPilotNames } from "./fbref.js";
+export { createFootballSource, KNOWN_SOURCE_IDS } from "./create.js";
+export { listStatsBombEndpoints, paidExtrasSummary, statsBombPaidUrls, buildPaidEndpointUrl, STATSBOMB_API_VERSIONS, STATSBOMB_ENDPOINT_CATALOG, } from "./statsbomb-endpoints.js";

package/dist/sources/statsbomb-endpoints.d.ts

@@ -0,0 +1,57 @@
+/**
+ * StatsBomb Data API endpoint catalogue.
+ *
+ * Free Open Data and the paid customer API share many concepts; paid adds
+ * aggregate / 360 / mapping endpoints and licensed competition coverage.
+ *
+ * Host (paid): https://data.statsbombservices.com
+ * Auth: HTTP Basic (SB_USERNAME / SB_PASSWORD) — same as statsbombpy.
+ */
+/** Default API versions (statsbombpy fallbacks when live map is unavailable). */
+export declare const STATSBOMB_API_VERSIONS: {
+    readonly competitions: "v4";
+    readonly matches: "v6";
+    readonly lineups: "v5";
+    readonly events: "v11";
+    readonly frames360: "v2";
+    readonly playerMatchStats: "v8";
+    readonly playerSeasonStats: "v7";
+    readonly teamMatchStats: "v4";
+    readonly teamSeasonStats: "v4";
+};
+export type StatsBombEndpointId = "competitions" | "matches" | "lineups" | "events" | "frames360" | "playerMatchStats" | "teamMatchStats" | "playerSeasonStats" | "teamSeasonStats" | "playerMapping" | "endpointVersions";
+export type StatsBombEndpointAvailability = "wired" | "optional-paid";
+export interface StatsBombEndpointInfo {
+    id: StatsBombEndpointId;
+    name: string;
+    paidPath?: string;
+    openDataPath?: string;
+    availability: StatsBombEndpointAvailability;
+    wiredInCampus: boolean;
+    requiresPaidLicense: boolean;
+    notes: string;
+}
+export declare const STATSBOMB_ENDPOINT_CATALOG: StatsBombEndpointInfo[];
+/** Optional paid extras the CLI can request once a login is present. */
+export interface StatsBombPaidExtras {
+    playerMatchStats?: boolean;
+    teamMatchStats?: boolean;
+    playerSeasonStats?: boolean;
+    teamSeasonStats?: boolean;
+    frames360?: boolean;
+}
+export declare function listStatsBombEndpoints(): StatsBombEndpointInfo[];
+export declare function paidExtrasSummary(extras?: StatsBombPaidExtras): string[];
+export declare function buildPaidEndpointUrl(template: string, params: Record<string, string | number>, apiBaseUrl?: string): string;
+export declare function statsBombPaidUrls(apiBaseUrl?: string): {
+    competitions: () => string;
+    matches: (competitionId: number, seasonId: number) => string;
+    lineups: (matchId: string | number) => string;
+    events: (matchId: string | number) => string;
+    frames360: (matchId: string | number) => string;
+    playerMatchStats: (matchId: string | number) => string;
+    teamMatchStats: (matchId: string | number) => string;
+    playerSeasonStats: (competitionId: number, seasonId: number) => string;
+    teamSeasonStats: (competitionId: number, seasonId: number) => string;
+    endpointVersions: () => string;
+};

package/dist/sources/statsbomb-endpoints.js

@@ -0,0 +1,169 @@
+/**
+ * StatsBomb Data API endpoint catalogue.
+ *
+ * Free Open Data and the paid customer API share many concepts; paid adds
+ * aggregate / 360 / mapping endpoints and licensed competition coverage.
+ *
+ * Host (paid): https://data.statsbombservices.com
+ * Auth: HTTP Basic (SB_USERNAME / SB_PASSWORD) — same as statsbombpy.
+ */
+import { DEFAULT_STATSBOMB_API_BASE } from "../credentials.js";
+/** Default API versions (statsbombpy fallbacks when live map is unavailable). */
+export const STATSBOMB_API_VERSIONS = {
+    competitions: "v4",
+    matches: "v6",
+    lineups: "v5",
+    events: "v11",
+    frames360: "v2",
+    playerMatchStats: "v8",
+    playerSeasonStats: "v7",
+    teamMatchStats: "v4",
+    teamSeasonStats: "v4",
+};
+export const STATSBOMB_ENDPOINT_CATALOG = [
+    {
+        id: "competitions",
+        name: "Competitions",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.competitions}/competitions`,
+        openDataPath: "/competitions.json",
+        availability: "wired",
+        wiredInCampus: true,
+        requiresPaidLicense: false,
+        notes: "Paid returns only competition-seasons in your contract; open-data is the public subset.",
+    },
+    {
+        id: "matches",
+        name: "Matches in competition season",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.matches}/competitions/{competition_id}/seasons/{season_id}/matches`,
+        openDataPath: "/matches/{competition_id}/{season_id}.json",
+        availability: "wired",
+        wiredInCampus: true,
+        requiresPaidLicense: false,
+        notes: "Core schedule + scores.",
+    },
+    {
+        id: "lineups",
+        name: "Lineups for match",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.lineups}/lineups/{match_id}`,
+        openDataPath: "/lineups/{match_id}.json",
+        availability: "wired",
+        wiredInCampus: true,
+        requiresPaidLicense: false,
+        notes: "Used when --with-players (capped).",
+    },
+    {
+        id: "events",
+        name: "Events in match",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.events}/events/{match_id}`,
+        openDataPath: "/events/{match_id}.json",
+        availability: "wired",
+        wiredInCampus: true,
+        requiresPaidLicense: false,
+        notes: "Used when --with-players.",
+    },
+    {
+        id: "playerMatchStats",
+        name: "Player match stats (aggregated)",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.playerMatchStats}/matches/{match_id}/player-stats`,
+        availability: "optional-paid",
+        wiredInCampus: false,
+        requiresPaidLicense: true,
+        notes: "From the StatsBomb paid API when your licence includes it. Use --with-paid-player-match-stats.",
+    },
+    {
+        id: "teamMatchStats",
+        name: "Team match stats (aggregated)",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.teamMatchStats}/matches/{match_id}/team-stats`,
+        availability: "optional-paid",
+        wiredInCampus: false,
+        requiresPaidLicense: true,
+        notes: "From the StatsBomb paid API when your licence includes it. Use --with-paid-team-match-stats.",
+    },
+    {
+        id: "playerSeasonStats",
+        name: "Player season stats",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.playerSeasonStats}/competitions/{competition_id}/seasons/{season_id}/player-stats`,
+        availability: "optional-paid",
+        wiredInCampus: false,
+        requiresPaidLicense: true,
+        notes: "From the StatsBomb paid API when your licence includes it. Use --with-paid-player-season-stats.",
+    },
+    {
+        id: "teamSeasonStats",
+        name: "Team season stats",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.teamSeasonStats}/competitions/{competition_id}/seasons/{season_id}/team-stats`,
+        availability: "optional-paid",
+        wiredInCampus: false,
+        requiresPaidLicense: true,
+        notes: "From the StatsBomb paid API when your licence includes it. Use --with-paid-team-season-stats.",
+    },
+    {
+        id: "frames360",
+        name: "360 freeze frames",
+        paidPath: `/api/${STATSBOMB_API_VERSIONS.frames360}/360-frames/{match_id}`,
+        openDataPath: "/three-sixty/{match_id}.json",
+        availability: "optional-paid",
+        wiredInCampus: false,
+        requiresPaidLicense: true,
+        notes: "From the StatsBomb paid API (360 licence). Use --with-paid-360.",
+    },
+    {
+        id: "playerMapping",
+        name: "Player mapping (live ↔ offline ids)",
+        paidPath: "/api/v*/player-mapping (see StatsBomb Data Hub)",
+        availability: "optional-paid",
+        wiredInCampus: false,
+        requiresPaidLicense: true,
+        notes: "From the StatsBomb paid API / Data Hub when licensed.",
+    },
+    {
+        id: "endpointVersions",
+        name: "Endpoint versions map",
+        paidPath: "/api/endpoint-versions",
+        availability: "optional-paid",
+        wiredInCampus: false,
+        requiresPaidLicense: true,
+        notes: "From the StatsBomb paid API; Campus uses version fallbacks today.",
+    },
+];
+export function listStatsBombEndpoints() {
+    return STATSBOMB_ENDPOINT_CATALOG;
+}
+export function paidExtrasSummary(extras = {}) {
+    const enabled = [];
+    if (extras.playerMatchStats)
+        enabled.push("playerMatchStats");
+    if (extras.teamMatchStats)
+        enabled.push("teamMatchStats");
+    if (extras.playerSeasonStats)
+        enabled.push("playerSeasonStats");
+    if (extras.teamSeasonStats)
+        enabled.push("teamSeasonStats");
+    if (extras.frames360)
+        enabled.push("frames360");
+    return enabled;
+}
+export function buildPaidEndpointUrl(template, params, apiBaseUrl = DEFAULT_STATSBOMB_API_BASE) {
+    let path = template;
+    for (const [key, value] of Object.entries(params)) {
+        path = path.replace(`{${key}}`, String(value));
+    }
+    const base = apiBaseUrl.replace(/\/$/, "");
+    return path.startsWith("http") ? path : `${base}${path}`;
+}
+export function statsBombPaidUrls(apiBaseUrl = DEFAULT_STATSBOMB_API_BASE) {
+    const base = apiBaseUrl.replace(/\/$/, "");
+    const v = STATSBOMB_API_VERSIONS;
+    return {
+        competitions: () => `${base}/api/${v.competitions}/competitions`,
+        matches: (competitionId, seasonId) => `${base}/api/${v.matches}/competitions/${competitionId}/seasons/${seasonId}/matches`,
+        lineups: (matchId) => `${base}/api/${v.lineups}/lineups/${matchId}`,
+        events: (matchId) => `${base}/api/${v.events}/events/${matchId}`,
+        frames360: (matchId) => `${base}/api/${v.frames360}/360-frames/${matchId}`,
+        playerMatchStats: (matchId) => `${base}/api/${v.playerMatchStats}/matches/${matchId}/player-stats`,
+        teamMatchStats: (matchId) => `${base}/api/${v.teamMatchStats}/matches/${matchId}/team-stats`,
+        playerSeasonStats: (competitionId, seasonId) => `${base}/api/${v.playerSeasonStats}/competitions/${competitionId}/seasons/${seasonId}/player-stats`,
+        teamSeasonStats: (competitionId, seasonId) => `${base}/api/${v.teamSeasonStats}/competitions/${competitionId}/seasons/${seasonId}/team-stats`,
+        endpointVersions: () => `${base}/api/endpoint-versions`,
+    };
+}

package/dist/sources/statsbomb.d.ts

@@ -1,16 +1,21 @@
 /**
- * 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 type { LineupEntry, Match, Player, PlayerMatchStats } from "../types.js";
+import { type StatsBombCredentials } from "../credentials.js";
 import type { FootballSource, SyncResult } from "./types.js";
+import { type StatsBombPaidExtras } from "./statsbomb-endpoints.js";
+export type StatsBombAccessMode = "open-data" | "paid";
 export interface WomenCompetitionInfo {
     id: number;
     name: string;
@@ -22,25 +27,70 @@ export interface WomenCompetitionInfo {
     }>;
 }
 export interface StatsBombSourceOptions {
-    /** Override open-data root (default: GitHub raw master/data). */
+    /**
+     * Customer login for the paid StatsBomb API. When both username and
+     * password are set, Campus hits data.statsbombservices.com instead of
+     * free Open Data.
+     */
+    credentials?: StatsBombCredentials;
+    /**
+     * Override open-data root (default: GitHub raw master/data).
+     * Alias: `baseUrl` (kept for fixtures / existing callers).
+     */
+    openDataBaseUrl?: string;
+    /** @deprecated Prefer `openDataBaseUrl`. */
     baseUrl?: string;
+    /** Override paid API host (default: data.statsbombservices.com). */
+    apiBaseUrl?: string;
     /** Inject fetch for offline fixtures / tests. */
     fetchJson?: <T>(url: string) => Promise<T>;
     /** When true, also pull lineups/events and aggregate v1 player stats. */
     includePlayerStats?: boolean;
     /** Cap matches enriched with player stats (default 5). */
     playerStatsLimit?: number;
+    /**
+     * Optional paid-only endpoints (aggregates, 360, …). Ignored in open-data
+     * mode. Requires a StatsBomb customer login + licence that includes them.
+     */
+    paidExtras?: StatsBombPaidExtras;
 }
 export declare class StatsBombSource implements FootballSource {
     readonly id = "statsbomb";
-    private readonly baseUrl;
+    readonly accessMode: StatsBombAccessMode;
+    private readonly openDataBaseUrl;
+    private readonly apiBaseUrl;
+    private readonly username?;
+    private readonly password?;
     private readonly fetchJson;
     private readonly includePlayerStats;
     private readonly playerStatsLimit;
+    private readonly paidExtras;
     constructor(options?: StatsBombSourceOptions);
+    private paidUrls;
+    private competitionsUrl;
+    private matchesUrl;
+    private lineupsUrl;
+    private eventsUrl;
     /** Catalogue of women's competitions (clubs + national-team tournaments). */
     listWomenCompetitions(): Promise<WomenCompetitionInfo[]>;
     syncCompetition(competitionName: string): Promise<SyncResult>;
+    /**
+     * 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).
+     */
+    probePaidExtras(context: {
+        competitionId: number;
+        seasonId: number;
+        matchId?: string | number;
+    }): Promise<Array<{
+        id: string;
+        ok: boolean;
+        url: string;
+        itemCount?: number;
+        error?: string;
+        mappedToCampusSchema: false;
+    }>>;
     /** Load aggregated v1 player stats + lineups for the given canonical matches. */
     loadPlayerStatsForMatches(matches: Match[]): Promise<{
         players: Player[];