campus-stats 0.4.0

package/dist/index.js

@@ -0,0 +1,9 @@
+export { StatsBombSource } from "./sources/statsbomb.js";
+export { FbrefSource, listFbrefPilotNames } from "./sources/fbref.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 { 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/injuries.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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

@@ -0,0 +1,15 @@
+/**
+ * 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 ?? [];
+}

package/dist/refs.d.ts

@@ -0,0 +1,7 @@
+/** Provenance link back to an upstream provider record. */
+export interface SourceRef {
+    /** Provider key, e.g. "statsbomb", "fbref". */
+    source: string;
+    /** Provider-native identifier (stringified if numeric upstream). */
+    id: string;
+}

package/dist/refs.js

@@ -0,0 +1 @@
+export {};

package/dist/scoring.d.ts

@@ -0,0 +1,37 @@
+import type { CampusCache, PlayerMatchStats } from "./types.js";
+/** Default fantasy scoring weights (outfield-oriented v1). */
+export interface FantasyScoringRules {
+    appearance: number;
+    goal: number;
+    assist: number;
+    yellowCard: number;
+    redCard: number;
+    /** Bonus when minutes >= this threshold (0 disables). */
+    fullMatchMinutes: number;
+    fullMatchBonus: number;
+}
+export declare const DEFAULT_FANTASY_RULES: FantasyScoringRules;
+export interface FantasyPointRow {
+    matchId: string;
+    playerId: string;
+    teamId: string;
+    points: number;
+    breakdown: {
+        appearance: number;
+        goals: number;
+        assists: number;
+        yellowCards: number;
+        redCards: number;
+        fullMatchBonus: number;
+    };
+}
+/** Score one PlayerMatchStats row with the given rules. */
+export declare function scorePlayerMatchStats(stats: PlayerMatchStats, rules?: FantasyScoringRules): FantasyPointRow;
+/** Score every player-match row in a cache (optionally filtered). */
+export declare function scoreFantasyPoints(cache: CampusCache, options?: {
+    competitionId?: string;
+    matchId?: string;
+    playerId?: string;
+    teamId?: string;
+    rules?: FantasyScoringRules;
+}): FantasyPointRow[];

package/dist/scoring.js

@@ -0,0 +1,56 @@
+export const DEFAULT_FANTASY_RULES = {
+    appearance: 1,
+    goal: 4,
+    assist: 3,
+    yellowCard: -1,
+    redCard: -3,
+    fullMatchMinutes: 60,
+    fullMatchBonus: 1,
+};
+/** Score one PlayerMatchStats row with the given rules. */
+export function scorePlayerMatchStats(stats, rules = DEFAULT_FANTASY_RULES) {
+    const minutes = stats.minutes ?? 0;
+    const appearance = minutes > 0 || stats.goals > 0 || stats.assists > 0
+        ? rules.appearance
+        : 0;
+    const goals = stats.goals * rules.goal;
+    const assists = stats.assists * rules.assist;
+    const yellowCards = stats.yellowCards * rules.yellowCard;
+    const redCards = stats.redCards * rules.redCard;
+    const fullMatchBonus = rules.fullMatchMinutes > 0 && minutes >= rules.fullMatchMinutes
+        ? rules.fullMatchBonus
+        : 0;
+    return {
+        matchId: stats.matchId,
+        playerId: stats.playerId,
+        teamId: stats.teamId,
+        points: appearance + goals + assists + yellowCards + redCards + fullMatchBonus,
+        breakdown: {
+            appearance,
+            goals,
+            assists,
+            yellowCards,
+            redCards,
+            fullMatchBonus,
+        },
+    };
+}
+/** Score every player-match row in a cache (optionally filtered). */
+export function scoreFantasyPoints(cache, options = {}) {
+    const matchIds = new Set(cache.matches
+        .filter((m) => options.competitionId ? m.competitionId === options.competitionId : true)
+        .map((m) => m.id));
+    return cache.playerMatchStats
+        .filter((s) => {
+        if (!matchIds.has(s.matchId))
+            return false;
+        if (options.matchId && s.matchId !== options.matchId)
+            return false;
+        if (options.playerId && s.playerId !== options.playerId)
+            return false;
+        if (options.teamId && s.teamId !== options.teamId)
+            return false;
+        return true;
+    })
+        .map((s) => scorePlayerMatchStats(s, options.rules));
+}

package/dist/sources/fbref-map.d.ts

@@ -0,0 +1,14 @@
+import type { SyncResult } from "./types.js";
+import type { FbrefScheduleRow } from "./fbref-parse.js";
+export interface FbrefCompetitionMeta {
+    /** FBref competition id, e.g. "189". */
+    fbrefCompetitionId: string;
+    name: string;
+    country?: string;
+    /** Season display label, e.g. "2023/2024". */
+    seasonName: string;
+    /** Optional season path segment, e.g. "2023-2024". */
+    seasonSlug?: string;
+}
+/** Map parsed FBref schedule rows into campus canonical entities. */
+export declare function mapFbrefScheduleToSyncResult(meta: FbrefCompetitionMeta, rows: FbrefScheduleRow[]): SyncResult;

package/dist/sources/fbref-map.js

@@ -0,0 +1,56 @@
+import { entityId } from "../ids.js";
+const SOURCE = "fbref";
+/** Map parsed FBref schedule rows into campus canonical entities. */
+export function mapFbrefScheduleToSyncResult(meta, rows) {
+    const competitionId = entityId(SOURCE, "comp", meta.fbrefCompetitionId);
+    const seasonKey = meta.seasonSlug ?? meta.seasonName.replace(/\//g, "-");
+    const seasonId = entityId(SOURCE, "season", meta.fbrefCompetitionId, seasonKey);
+    const competition = {
+        id: competitionId,
+        name: meta.name,
+        country: meta.country,
+        gender: "female",
+        sources: [{ source: SOURCE, id: meta.fbrefCompetitionId }],
+    };
+    const season = {
+        id: seasonId,
+        name: meta.seasonName,
+        competitionId,
+        sources: [{ source: SOURCE, id: `${meta.fbrefCompetitionId}:${seasonKey}` }],
+    };
+    const teams = new Map();
+    const matches = [];
+    for (const row of rows) {
+        const homeId = entityId(SOURCE, "team", row.homeTeamId);
+        const awayId = entityId(SOURCE, "team", row.awayTeamId);
+        teams.set(homeId, {
+            id: homeId,
+            name: row.homeTeamName,
+            sources: [{ source: SOURCE, id: row.homeTeamId }],
+        });
+        teams.set(awayId, {
+            id: awayId,
+            name: row.awayTeamName,
+            sources: [{ source: SOURCE, id: row.awayTeamId }],
+        });
+        const matchNativeId = row.matchId ??
+            `${meta.fbrefCompetitionId}:${row.date ?? "undated"}:${row.homeTeamId}:${row.awayTeamId}`;
+        matches.push({
+            id: entityId(SOURCE, "match", matchNativeId),
+            competitionId,
+            seasonId,
+            date: row.date,
+            homeTeamId: homeId,
+            awayTeamId: awayId,
+            homeScore: row.homeScore,
+            awayScore: row.awayScore,
+            sources: [{ source: SOURCE, id: matchNativeId }],
+        });
+    }
+    return {
+        competitions: [competition],
+        seasons: [season],
+        teams: [...teams.values()],
+        matches,
+    };
+}

package/dist/sources/fbref-parse.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal HTML schedule parser for FBref `sched_*` tables.
+ * Only reads data-stat attributes documented in docs/fbref-pilot.md.
+ */
+export interface FbrefScheduleRow {
+    date?: string;
+    homeTeamId: string;
+    homeTeamName: string;
+    awayTeamId: string;
+    awayTeamName: string;
+    homeScore?: number | null;
+    awayScore?: number | null;
+    /** FBref match id when present in the score link. */
+    matchId?: string;
+}
+/** Extract match rows from a FBref competition schedule HTML page. */
+export declare function parseFbrefSchedule(html: string): FbrefScheduleRow[];

package/dist/sources/fbref-parse.js

@@ -0,0 +1,87 @@
+/**
+ * Minimal HTML schedule parser for FBref `sched_*` tables.
+ * Only reads data-stat attributes documented in docs/fbref-pilot.md.
+ */
+function decodeBasicEntities(text) {
+    return text
+        .replace(/ /g, " ")
+        .replace(/&/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)))
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function cellHtml(rowHtml, stat) {
+    const re = new RegExp(`<t[hd]\\b[^>]*\\bdata-stat="${stat}"[^>]*>([\\s\\S]*?)</t[hd]>`, "i");
+    const m = rowHtml.match(re);
+    return m?.[1];
+}
+function firstLink(cell) {
+    if (!cell)
+        return undefined;
+    const m = cell.match(/<a\b[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/i);
+    if (!m) {
+        const text = decodeBasicEntities(cell.replace(/<[^>]+>/g, ""));
+        return text ? { href: "", text } : undefined;
+    }
+    return {
+        href: m[1] ?? "",
+        text: decodeBasicEntities((m[2] ?? "").replace(/<[^>]+>/g, "")),
+    };
+}
+function squadFromHref(href) {
+    const m = href.match(/\/squads\/([a-f0-9]+)\//i);
+    return m?.[1];
+}
+function matchFromHref(href) {
+    const m = href.match(/\/matches\/([a-z0-9]+)\//i);
+    return m?.[1];
+}
+function parseScore(raw) {
+    const text = decodeBasicEntities(raw.replace(/<[^>]+>/g, ""));
+    if (!text)
+        return { home: null, away: null };
+    const m = text.match(/(\d+)\s*[–\-—]\s*(\d+)/);
+    if (!m)
+        return {};
+    return { home: Number(m[1]), away: Number(m[2]) };
+}
+/** Extract match rows from a FBref competition schedule HTML page. */
+export function parseFbrefSchedule(html) {
+    const tableMatch = html.match(/<table\b[^>]*\bid="sched_[^"]+"[^>]*>([\s\S]*?)<\/table>/i);
+    const tableHtml = tableMatch?.[1] ?? html;
+    const bodyMatch = tableHtml.match(/<tbody\b[^>]*>([\s\S]*?)<\/tbody>/i);
+    const body = bodyMatch?.[1] ?? tableHtml;
+    const rows = [];
+    const rowRe = /<tr\b[^>]*>([\s\S]*?)<\/tr>/gi;
+    let rowMatch;
+    while ((rowMatch = rowRe.exec(body))) {
+        const rowHtml = rowMatch[1] ?? "";
+        if (/spacer|thead/i.test(rowMatch[0]))
+            continue;
+        const homeLink = firstLink(cellHtml(rowHtml, "home_team"));
+        const awayLink = firstLink(cellHtml(rowHtml, "away_team"));
+        if (!homeLink || !awayLink)
+            continue;
+        const homeTeamId = squadFromHref(homeLink.href);
+        const awayTeamId = squadFromHref(awayLink.href);
+        if (!homeTeamId || !awayTeamId)
+            continue;
+        const dateLink = firstLink(cellHtml(rowHtml, "date"));
+        const scoreCell = cellHtml(rowHtml, "score") ?? "";
+        const scoreLink = firstLink(scoreCell);
+        const score = parseScore(scoreCell);
+        rows.push({
+            date: dateLink?.text || undefined,
+            homeTeamId,
+            homeTeamName: homeLink.text,
+            awayTeamId,
+            awayTeamName: awayLink.text,
+            homeScore: score.home,
+            awayScore: score.away,
+            matchId: scoreLink ? matchFromHref(scoreLink.href) : undefined,
+        });
+    }
+    return rows;
+}

package/dist/sources/fbref.d.ts

@@ -0,0 +1,27 @@
+/**
+ * FBref HTML adapter (women's competitions).
+ *
+ * Upstream: https://www.fbref.com/
+ * Respect Sports Reference terms, robots.txt, and rate limits. Prefer the
+ * polite HttpClient defaults. This environment often receives Cloudflare
+ * 403s; use fixtures / --fixture for offline sync.
+ *
+ * See docs/fbref-pilot.md for competition ids and HTML shape.
+ */
+import { HttpClient } from "../http.js";
+import type { FootballSource, SyncResult } from "./types.js";
+export interface FbrefSourceOptions {
+    http?: HttpClient;
+    /** Override HTML loader (fixtures / tests). */
+    loadHtml?: (url: string) => Promise<string>;
+    baseUrl?: string;
+}
+export declare class FbrefSource implements FootballSource {
+    readonly id = "fbref";
+    private readonly http;
+    private readonly loadHtml;
+    private readonly baseUrl;
+    constructor(options?: FbrefSourceOptions);
+    syncCompetition(competitionName: string): Promise<SyncResult>;
+}
+export declare function listFbrefPilotNames(): string[];

package/dist/sources/fbref.js

@@ -0,0 +1,72 @@
+/**
+ * FBref HTML adapter (women's competitions).
+ *
+ * Upstream: https://www.fbref.com/
+ * Respect Sports Reference terms, robots.txt, and rate limits. Prefer the
+ * polite HttpClient defaults. This environment often receives Cloudflare
+ * 403s; use fixtures / --fixture for offline sync.
+ *
+ * See docs/fbref-pilot.md for competition ids and HTML shape.
+ */
+import { HttpClient } from "../http.js";
+import { parseFbrefSchedule } from "./fbref-parse.js";
+import { mapFbrefScheduleToSyncResult, } from "./fbref-map.js";
+const SOURCE = "fbref";
+const BASE = "https://fbref.com";
+const PILOTS = [
+    {
+        fbrefCompetitionId: "189",
+        name: "FA Women's Super League",
+        country: "England",
+        seasonName: "2023/2024",
+        seasonSlug: "2023-2024",
+        aliases: ["wsl", "fa women's super league", "women's super league"],
+        schedulePath: "/en/comps/189/2023-2024/schedule/2023-2024-Womens-Super-League-Scores-and-Fixtures",
+    },
+    {
+        fbrefCompetitionId: "230",
+        name: "Liga F",
+        country: "Spain",
+        seasonName: "2023/2024",
+        seasonSlug: "2023-2024",
+        aliases: ["liga f"],
+        schedulePath: "/en/comps/230/2023-2024/schedule/2023-2024-Liga-F-Scores-and-Fixtures",
+    },
+];
+function normalize(name) {
+    return name.trim().toLowerCase();
+}
+export class FbrefSource {
+    id = SOURCE;
+    http;
+    loadHtml;
+    baseUrl;
+    constructor(options = {}) {
+        this.http = options.http ?? new HttpClient();
+        this.baseUrl = options.baseUrl ?? BASE;
+        this.loadHtml =
+            options.loadHtml ?? ((url) => this.http.getText(url));
+    }
+    async syncCompetition(competitionName) {
+        const pilot = PILOTS.find((p) => normalize(p.name) === normalize(competitionName) ||
+            p.aliases.includes(normalize(competitionName)));
+        if (!pilot) {
+            throw new Error(`Competition not supported by FBref adapter yet: "${competitionName}". ` +
+                `Pilots: ${PILOTS.map((p) => p.name).join(", ")}`);
+        }
+        const url = `${this.baseUrl}${pilot.schedulePath}`;
+        const html = await this.loadHtml(url);
+        if (/Just a moment/i.test(html) || /cf-browser-verification/i.test(html)) {
+            throw new Error(`FBref returned a Cloudflare challenge for ${url}. ` +
+                `Retry from a non-blocked network or sync with an HTML fixture.`);
+        }
+        const rows = parseFbrefSchedule(html);
+        if (rows.length === 0) {
+            throw new Error(`No schedule rows parsed from FBref page: ${url}`);
+        }
+        return mapFbrefScheduleToSyncResult(pilot, rows);
+    }
+}
+export function listFbrefPilotNames() {
+    return PILOTS.map((p) => p.name);
+}

package/dist/sources/index.d.ts

@@ -0,0 +1,3 @@
+export type { FootballSource, SyncResult } from "./types.js";
+export { StatsBombSource } from "./statsbomb.js";
+export { FbrefSource, listFbrefPilotNames } from "./fbref.js";

package/dist/sources/index.js

@@ -0,0 +1,2 @@
+export { StatsBombSource } from "./statsbomb.js";
+export { FbrefSource, listFbrefPilotNames } from "./fbref.js";

package/dist/sources/statsbomb-player-stats.d.ts

@@ -0,0 +1,63 @@
+import type { LineupEntry, Player, PlayerMatchStats } from "../types.js";
+interface SbCard {
+    time?: string;
+    card_type?: string;
+    reason?: string;
+    period?: number;
+}
+interface SbPosition {
+    from?: string | null;
+    to?: string | null;
+}
+interface SbLineupPlayer {
+    player_id: number;
+    player_name: string;
+    player_nickname?: string | null;
+    jersey_number?: number | null;
+    country?: {
+        name?: string;
+    };
+    cards?: SbCard[];
+    positions?: SbPosition[];
+}
+interface SbLineupTeam {
+    team_id: number;
+    team_name: string;
+    lineup: SbLineupPlayer[];
+}
+interface SbEvent {
+    type?: {
+        name?: string;
+    };
+    player?: {
+        id?: number;
+        name?: string;
+    };
+    team?: {
+        id?: number;
+        name?: string;
+    };
+    shot?: {
+        outcome?: {
+            name?: string;
+        };
+        key_pass_id?: string;
+    };
+    pass?: {
+        goal_assist?: boolean;
+    };
+    id?: string;
+}
+/** Approximate minutes played from StatsBomb lineup position intervals. */
+export declare function minutesFromPositions(positions: SbPosition[] | undefined): number | null;
+export interface AggregatedPlayerMatch {
+    players: Player[];
+    playerMatchStats: PlayerMatchStats[];
+    lineups: LineupEntry[];
+}
+/**
+ * Build Player + PlayerMatchStats + LineupEntry for one match
+ * from StatsBomb lineups + events.
+ */
+export declare function aggregateStatsBombPlayerMatch(matchIdCampo: string, lineups: SbLineupTeam[], events: SbEvent[]): AggregatedPlayerMatch;
+export {};

package/dist/sources/statsbomb-player-stats.js

@@ -0,0 +1,107 @@
+import { entityId } from "../ids.js";
+const SOURCE = "statsbomb";
+function parseClockToMinutes(clock) {
+    if (!clock)
+        return null;
+    const m = clock.match(/^(\d+):(\d+)/);
+    if (!m)
+        return null;
+    return Number(m[1]) + Number(m[2]) / 60;
+}
+/** Approximate minutes played from StatsBomb lineup position intervals. */
+export function minutesFromPositions(positions) {
+    if (!positions || positions.length === 0)
+        return null;
+    let total = 0;
+    let any = false;
+    for (const pos of positions) {
+        const from = parseClockToMinutes(pos.from);
+        const to = parseClockToMinutes(pos.to ?? "90:00");
+        if (from == null || to == null)
+            continue;
+        any = true;
+        total += Math.max(0, to - from);
+    }
+    return any ? Math.round(total) : null;
+}
+function countCards(cards) {
+    let yellow = 0;
+    let red = 0;
+    for (const card of cards ?? []) {
+        const t = (card.card_type ?? "").toLowerCase();
+        if (t.includes("second yellow") || t.includes("red"))
+            red += 1;
+        else if (t.includes("yellow"))
+            yellow += 1;
+    }
+    return { yellow, red };
+}
+/**
+ * Build Player + PlayerMatchStats + LineupEntry for one match
+ * from StatsBomb lineups + events.
+ */
+export function aggregateStatsBombPlayerMatch(matchIdCampo, lineups, events) {
+    const goals = new Map();
+    const assists = new Map();
+    for (const event of events) {
+        const playerId = event.player?.id;
+        if (playerId == null)
+            continue;
+        if (event.type?.name === "Shot" && event.shot?.outcome?.name === "Goal") {
+            goals.set(playerId, (goals.get(playerId) ?? 0) + 1);
+        }
+        if (event.type?.name === "Pass" && event.pass?.goal_assist) {
+            assists.set(playerId, (assists.get(playerId) ?? 0) + 1);
+        }
+    }
+    const players = new Map();
+    const stats = [];
+    const lineupEntries = [];
+    const matchNative = matchIdCampo.split(":").pop();
+    for (const team of lineups) {
+        const teamId = entityId(SOURCE, "team", team.team_id);
+        for (const p of team.lineup) {
+            const playerId = entityId(SOURCE, "player", p.player_id);
+            players.set(playerId, {
+                id: playerId,
+                name: p.player_name,
+                nickname: p.player_nickname ?? undefined,
+                country: p.country?.name,
+                sources: [{ source: SOURCE, id: String(p.player_id) }],
+            });
+            const cards = countCards(p.cards);
+            const started = (p.positions?.length ?? 0) > 0;
+            stats.push({
+                id: entityId(SOURCE, "pstats", matchNative, p.player_id),
+                matchId: matchIdCampo,
+                playerId,
+                teamId,
+                minutes: minutesFromPositions(p.positions),
+                goals: goals.get(p.player_id) ?? 0,
+                assists: assists.get(p.player_id) ?? 0,
+                yellowCards: cards.yellow,
+                redCards: cards.red,
+                sources: [
+                    {
+                        source: SOURCE,
+                        id: `${matchNative}:${p.player_id}`,
+                    },
+                ],
+            });
+            lineupEntries.push({
+                id: entityId(SOURCE, "lineup", matchNative, p.player_id),
+                matchId: matchIdCampo,
+                teamId,
+                playerId,
+                started,
+                jerseyNumber: p.jersey_number ?? null,
+                sources: [{ source: SOURCE, id: `${matchNative}:${p.player_id}` }],
+            });
+        }
+    }
+    return {
+        players: [...players.values()],
+        playerMatchStats: stats,
+        lineups: lineupEntries,
+    };
+}

package/dist/sources/statsbomb.d.ts

@@ -0,0 +1,50 @@
+/**
+ * StatsBomb Open Data adapter.
+ *
+ * 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.
+ *
+ * This adapter only surfaces women's competitions
+ * (`competition_gender === "female"`).
+ */
+import type { LineupEntry, Match, Player, PlayerMatchStats } from "../types.js";
+import type { FootballSource, SyncResult } from "./types.js";
+export interface WomenCompetitionInfo {
+    id: number;
+    name: string;
+    country: string;
+    international: boolean;
+    seasons: Array<{
+        id: number;
+        name: string;
+    }>;
+}
+export interface StatsBombSourceOptions {
+    /** Override open-data root (default: GitHub raw master/data). */
+    baseUrl?: 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;
+}
+export declare class StatsBombSource implements FootballSource {
+    readonly id = "statsbomb";
+    private readonly baseUrl;
+    private readonly fetchJson;
+    private readonly includePlayerStats;
+    private readonly playerStatsLimit;
+    constructor(options?: StatsBombSourceOptions);
+    /** Catalogue of women's competitions (clubs + national-team tournaments). */
+    listWomenCompetitions(): Promise<WomenCompetitionInfo[]>;
+    syncCompetition(competitionName: string): Promise<SyncResult>;
+    /** Load aggregated v1 player stats + lineups for the given canonical matches. */
+    loadPlayerStatsForMatches(matches: Match[]): Promise<{
+        players: Player[];
+        playerMatchStats: PlayerMatchStats[];
+        lineups: LineupEntry[];
+    }>;
+}