campus-stats 0.4.0

package/dist/sources/statsbomb.js

@@ -0,0 +1,170 @@
+/**
+ * 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 { aggregateStatsBombPlayerMatch } from "./statsbomb-player-stats.js";
+import { entityId } from "../ids.js";
+const SOURCE = "statsbomb";
+const BASE = "https://raw.githubusercontent.com/statsbomb/open-data/master/data";
+function normalizeName(name) {
+    return name.trim().toLowerCase();
+}
+async function defaultFetchJson(url) {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`StatsBomb fetch failed (${res.status}): ${url}`);
+    }
+    return (await res.json());
+}
+export class StatsBombSource {
+    id = SOURCE;
+    baseUrl;
+    fetchJson;
+    includePlayerStats;
+    playerStatsLimit;
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? BASE;
+        this.fetchJson = options.fetchJson ?? defaultFetchJson;
+        this.includePlayerStats = options.includePlayerStats ?? false;
+        this.playerStatsLimit = options.playerStatsLimit ?? 5;
+    }
+    /** Catalogue of women's competitions (clubs + national-team tournaments). */
+    async listWomenCompetitions() {
+        const all = await this.fetchJson(`${this.baseUrl}/competitions.json`);
+        const byId = new Map();
+        for (const row of all) {
+            if (row.competition_gender !== "female")
+                continue;
+            const existing = byId.get(row.competition_id);
+            if (!existing) {
+                byId.set(row.competition_id, {
+                    id: row.competition_id,
+                    name: row.competition_name,
+                    country: row.country_name,
+                    international: Boolean(row.competition_international),
+                    seasons: [{ id: row.season_id, name: row.season_name }],
+                });
+            }
+            else {
+                existing.seasons.push({ id: row.season_id, name: row.season_name });
+            }
+        }
+        return [...byId.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async syncCompetition(competitionName) {
+        const all = await this.fetchJson(`${this.baseUrl}/competitions.json`);
+        const rows = all.filter((c) => c.competition_gender === "female" &&
+            normalizeName(c.competition_name) === normalizeName(competitionName));
+        if (rows.length === 0) {
+            const available = [
+                ...new Set(all
+                    .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 competitions = new Map();
+        const seasons = new Map();
+        const teams = new Map();
+        const matches = [];
+        for (const row of rows) {
+            const competitionId = entityId(SOURCE, "comp", row.competition_id);
+            const international = Boolean(row.competition_international);
+            const teamKind = international ? "national" : "club";
+            competitions.set(competitionId, {
+                id: competitionId,
+                name: row.competition_name,
+                country: row.country_name,
+                gender: "female",
+                international,
+                sources: [{ source: SOURCE, id: String(row.competition_id) }],
+            });
+            const seasonId = entityId(SOURCE, "season", row.competition_id, row.season_id);
+            seasons.set(seasonId, {
+                id: seasonId,
+                name: row.season_name,
+                competitionId,
+                sources: [
+                    {
+                        source: SOURCE,
+                        id: `${row.competition_id}:${row.season_id}`,
+                    },
+                ],
+            });
+            const matchRows = await this.fetchJson(`${this.baseUrl}/matches/${row.competition_id}/${row.season_id}.json`);
+            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);
+                teams.set(homeId, {
+                    id: homeId,
+                    name: m.home_team.home_team_name,
+                    country: m.home_team.country?.name,
+                    kind: teamKind,
+                    sources: [{ source: SOURCE, id: String(m.home_team.home_team_id) }],
+                });
+                teams.set(awayId, {
+                    id: awayId,
+                    name: m.away_team.away_team_name,
+                    country: m.away_team.country?.name,
+                    kind: teamKind,
+                    sources: [{ source: SOURCE, id: String(m.away_team.away_team_id) }],
+                });
+                matches.push({
+                    id: entityId(SOURCE, "match", m.match_id),
+                    competitionId,
+                    seasonId,
+                    date: m.match_date,
+                    homeTeamId: homeId,
+                    awayTeamId: awayId,
+                    homeScore: m.home_score,
+                    awayScore: m.away_score,
+                    sources: [{ source: SOURCE, id: String(m.match_id) }],
+                });
+            }
+        }
+        const result = {
+            competitions: [...competitions.values()],
+            seasons: [...seasons.values()],
+            teams: [...teams.values()],
+            matches,
+        };
+        if (this.includePlayerStats) {
+            const enriched = await this.loadPlayerStatsForMatches(matches.slice(0, this.playerStatsLimit));
+            result.players = enriched.players;
+            result.playerMatchStats = enriched.playerMatchStats;
+            result.lineups = enriched.lineups;
+        }
+        return result;
+    }
+    /** Load aggregated v1 player stats + lineups for the given canonical matches. */
+    async loadPlayerStatsForMatches(matches) {
+        const players = new Map();
+        const playerMatchStats = [];
+        const lineupEntries = [];
+        for (const match of matches) {
+            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 agg = aggregateStatsBombPlayerMatch(match.id, lineups, events);
+            for (const p of agg.players)
+                players.set(p.id, p);
+            playerMatchStats.push(...agg.playerMatchStats);
+            lineupEntries.push(...agg.lineups);
+        }
+        return {
+            players: [...players.values()],
+            playerMatchStats,
+            lineups: lineupEntries,
+        };
+    }
+}

package/dist/sources/types.d.ts

@@ -0,0 +1,23 @@
+import type { Competition, InjuryRecord, 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[];
+    seasons: Season[];
+    teams: Team[];
+    matches: Match[];
+    players?: Player[];
+    playerMatchStats?: PlayerMatchStats[];
+    lineups?: LineupEntry[];
+    injuries?: InjuryRecord[];
+}
+/**
+ * Provider adapter contract.
+ * Implementations map native payloads onto the campus schema and
+ * attach provenance via `sources` on every entity.
+ */
+export interface FootballSource {
+    /** Stable provider key (also used in SourceRef.source). */
+    readonly id: string;
+    /** Sync all seasons/teams/matches for a competition display name. */
+    syncCompetition(competitionName: string): Promise<SyncResult>;
+}

package/dist/sources/types.js

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

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+import type { SourceRef } from "./refs.js";
+import type { CanonicalIdentity } from "./identity/types.js";
+export type { SourceRef } from "./refs.js";
+/**
+ * Canonical domain schema for campus.
+ * Provider-agnostic — adapters map raw source fields into these types.
+ */
+/** Club side vs national team (selección). */
+export type TeamKind = "club" | "national";
+export interface Competition {
+    /** Stable campus id (derived from primary source + native id). */
+    id: string;
+    /** Display name, e.g. "Liga F". */
+    name: string;
+    /** ISO-ish country or region label when known. */
+    country?: string;
+    /** Always women's football in this package; kept for clarity. */
+    gender: "female";
+    /** True for World Cup, Euro, etc. (national-team tournaments). */
+    international?: boolean;
+    sources: SourceRef[];
+}
+export interface Season {
+    id: string;
+    /** Display label, e.g. "2023/2024". */
+    name: string;
+    competitionId: string;
+    sources: SourceRef[];
+}
+export interface Team {
+    id: string;
+    name: string;
+    country?: string;
+    /** Club or national team when known from the competition context. */
+    kind?: TeamKind;
+    sources: SourceRef[];
+}
+export interface Match {
+    id: string;
+    competitionId: string;
+    seasonId: string;
+    /** Kick-off date YYYY-MM-DD when known. */
+    date?: string;
+    homeTeamId: string;
+    awayTeamId: string;
+    homeScore?: number | null;
+    awayScore?: number | null;
+    sources: SourceRef[];
+}
+/** Player identity at package level (not per-match). */
+export interface Player {
+    id: string;
+    name: string;
+    /** Preferred short name when known. */
+    nickname?: string;
+    country?: string;
+    sources: SourceRef[];
+}
+/**
+ * Aggregated per-player stats for a single match (v1 metrics subset).
+ * See docs/player-stats.md for the metric contract.
+ */
+export interface PlayerMatchStats {
+    id: string;
+    matchId: string;
+    playerId: string;
+    teamId: string;
+    /** Minutes played when known. */
+    minutes?: number | null;
+    goals: number;
+    assists: number;
+    yellowCards: number;
+    redCards: number;
+    sources: SourceRef[];
+}
+/** One player appearance in a match squad / lineup. */
+export interface LineupEntry {
+    id: string;
+    matchId: string;
+    teamId: string;
+    playerId: string;
+    /** True when the player has a recorded on-pitch position interval. */
+    started: boolean;
+    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[];
+    seasons: Season[];
+    teams: Team[];
+    matches: Match[];
+    /** Cross-source identity resolutions (epic 02). */
+    identities: CanonicalIdentity[];
+    players: Player[];
+    playerMatchStats: PlayerMatchStats[];
+    lineups: LineupEntry[];
+    injuries: InjuryRecord[];
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "campus-stats",
+  "version": "0.4.0",
+  "description": "Campus — installable women's football data layer for apps (clubs, national teams, matches, fantasy points)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "campus": "./dist/cli.js",
+    "campus-stats": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "campus",
+    "campus-stats",
+    "football",
+    "soccer",
+    "women",
+    "fantasy",
+    "stats",
+    "statsbomb",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/marina34/campus.git"
+  },
+  "homepage": "https://gitlab.com/marina34/campus",
+  "bugs": {
+    "url": "https://gitlab.com/marina34/campus/-/issues"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}