campus-stats 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.4.0
+
+- **Rename (npm):** package **`campus`** → **`campus-stats`** so public
+  `npm install campus-stats` works (unscoped `campus` is taken on npmjs.com)
+- Publish target: **npmjs.com** primary; GitLab Package Registry as mirror
+- CLI bins: `campus` and `campus-stats` (same entrypoint)
+- Import path: `import { CampusClient } from "campus-stats"`
+- Product brand, `CampusClient`, `.campus/` cache, and `campus-data` unchanged
+
+## 0.3.0
+
+- **Rename:** package/CLI `campo-stats` → **`campus`** (brand alignment)
+- API rename: `CampoClient` → `CampusClient`, `CampoCache` → `CampusCache`
+- Local cache directory: `.campo-stats/` → `.campus/`
+- Data bundle package: `campo-stats-data` → `campus-data`
+- Smoke test for package identity (`name`, bin, cache paths)
+
+## 0.2.0
+
+- App-facing `CampusClient` API (`open` / `fromBundle` / `syncFantasy` / queries)
+- `sync --fantasy` / `--all`, `update`, `pull`, `available`
+- Lineups + season squad queries; default fantasy scoring
+- Injuries API stub (empty — no open source yet)
+- GitLab CI cron job `refresh_fantasy_data` + `docs/cron.md`
+- Competition `international` and team `kind` (`club` | `national`)
+
+## 0.1.0
+
+- Initial package layout (distributed via GitLab Package Registry, not npmjs)
+- StatsBomb + FBref (schedule) adapters
+- JSON cache and optional SQLite persistence
+- Player match stats (StatsBomb, capped)
+- Cross-source team identity proposals

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Campus / campus contributors
+
+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,163 @@
+# Campus (`campus-stats`)
+
+**Open, normalized, queryable data for women's football — installable in your app.**
+
+`campus-stats` is the npm package for **Campus**: a library + CLI that pulls
+women's football stats from public sources, normalizes them into one schema,
+and gives your web/API/app access to competitions, seasons, clubs, national
+teams, matches, lineups, player stats, and basic fantasy points.
+
+Requires **Node.js ≥ 22**.
+
+---
+
+## Install
+
+Published on **npmjs.com**:
+
+```bash
+npm install campus-stats
+
+npx campus sync --competition "Liga F"
+npx campus teams --competition "Liga F"
+npx campus matches --competition "Liga F" --team "Barcelona"
+```
+
+The CLI binaries are `campus` and `campus-stats` (same entrypoint).
+
+Maintainer publish setup: [`docs/npm.md`](./docs/npm.md).  
+Optional GitLab mirror: [`docs/gitlab-package.md`](./docs/gitlab-package.md).
+
+---
+
+## Use as a library (recommended for apps)
+
+```ts
+import { CampusClient } from "campus-stats";
+
+const client = await CampusClient.open();
+await client.syncFantasy({ includePlayerStats: true });
+// or: const client = await CampusClient.fromBundle();
+
+const clubs = client.teams({ competition: "Liga F", kind: "club" });
+const nations = client.teams({ competition: "Women's World Cup", kind: "national" });
+const matches = client.matches({ competition: "Liga F", team: "Barcelona" });
+const squad = client.squad({ competition: "Liga F", team: "Barcelona" });
+const points = client.fantasyPoints({ competition: "Liga F", player: "Walsh" });
+
+return Response.json({ clubs, nations, matches, squad, points });
+```
+
+### What you get from the package
+
+| API | Purpose |
+|-----|---------|
+| `CampusClient` | Main entry for apps: sync / pull / query |
+| `syncFantasyBundle` / `updateCachedCompetitions` | Low-level sync helpers |
+| `scoreFantasyPoints` | Default fantasy scoring rules |
+| `listInjuries` | Stable stub (empty until a source exists) |
+| Types | `Competition`, `Team`, `Match`, `Player`, `LineupEntry`, … |
+| CLI bins `campus` / `campus-stats` | Same data from the terminal |
+
+---
+
+## Keep data fresh (cron)
+
+1. GitLab **Pipeline schedule** on `main` (e.g. `0 6 * * *`) runs
+   `refresh_fantasy_data` and publishes `campus-data/latest/cache.json`.
+2. Apps call `CampusClient.fromBundle()` or `npx campus pull`.
+
+Details: [`docs/cron.md`](./docs/cron.md).
+
+---
+
+## CLI quick start
+
+After `npm install campus-stats`:
+
+```bash
+npx campus sync --fantasy                 # all women's comps (clubs + selecciones)
+npx campus sync --fantasy --with-players  # + lineups + player stats (capped)
+npx campus pull                           # download cron bundle
+npx campus competitions
+npx campus matches --competition "Liga F" --team "Barcelona"
+npx campus squad --competition "Liga F" --team "Barcelona"
+npx campus fantasy-points --competition "Liga F"
+npx campus injuries                       # empty + documented deferral
+```
+
+Store: `.campus/cache.json` (or `--sqlite` / `--db <path>`).
+
+Single-competition sync and identities still work:
+
+```bash
+npx campus sync --competition "Liga F"
+npx campus sync --source fbref --competition "WSL"
+npx campus identities propose --competition "Liga F"
+```
+
+---
+
+## Supported data (open sources)
+
+| Source | Coverage | Notes |
+|--------|----------|-------|
+| **StatsBomb Open Data** | Liga F, WSL, NWSL, Serie A Women, Frauen Bundesliga, Women's World Cup, UEFA Women's Euro | Clubs + national teams; optional player stats / lineups |
+| **FBref** | WSL + Liga F schedules (pilot) | Live HTML may hit Cloudflare |
+
+Injuries are **not** in these open feeds yet — the API is ready, the list is empty.
+
+---
+
+## Why this shape
+
+- **One canonical schema** (`Competition`, `Season`, `Team`, `Match`, …). Adapters translate; the app never sees provider field names.
+- **Provenance on every record** (`sources: [{ source, id }]`) so cross-source identity is possible.
+- **Local-first cache** (JSON by default, SQLite optional) — no hosted database required for the library.
+
+---
+
+## Develop from a clone
+
+For contributors working on this repo:
+
+```bash
+git clone https://gitlab.com/marina34/campus.git
+cd campus
+npm install
+npm run build
+npm test
+npx campus --help
+```
+
+---
+
+## Project plan & docs
+
+| Epic | Description |
+|------|-------------|
+| [00 — Foundation](./docs/epics/00-fundacion-v0.md) | Schema, StatsBomb, CLI, JSON cache |
+| [01 — FBref](./docs/epics/01-adapter-fbref.md) | Second public source |
+| [02 — Identity](./docs/epics/02-resolucion-identidad.md) | Cross-source team resolution |
+| [03 — Player stats](./docs/epics/03-stats-jugadora.md) | Per-match player stats |
+| [04 — SQLite](./docs/epics/04-persistencia-sqlite.md) | Persistence beyond JSON |
+| [05 — Package](./docs/epics/05-publicacion-npm.md) | npmjs + GitLab package distribution |
+
+More: [`docs/cron.md`](./docs/cron.md) · [`docs/injuries.md`](./docs/injuries.md) · [`docs/npm.md`](./docs/npm.md) · [`docs/gitlab-package.md`](./docs/gitlab-package.md) · [`CHANGELOG.md`](./CHANGELOG.md)
+
+---
+
+## Data source & terms
+
+**Code is MIT. Data is not ours to relicense.**
+
+- [StatsBomb Open Data](https://github.com/statsbomb/open-data): free for research and genuine football analytics. Credit StatsBomb in published analysis ([media pack](https://statsbomb.com/media-pack/)).
+- FBref / Sports Reference: respect site terms, `robots.txt`, and rate limits.
+
+Pass those requirements downstream.
+
+---
+
+## License
+
+Code: MIT (see [`LICENSE`](./LICENSE)). Data: subject to each source's terms.

package/dist/cache.d.ts

@@ -0,0 +1,10 @@
+import type { CampusCache } from "./types.js";
+import type { SyncResult } from "./sources/types.js";
+export declare const DEFAULT_CACHE_DIR = ".campus";
+export declare const DEFAULT_CACHE_FILE = "cache.json";
+export declare function emptyCache(): CampusCache;
+export declare function cachePath(cwd?: string): string;
+export declare function loadCache(filePath?: string): Promise<CampusCache>;
+export declare function saveCache(cache: CampusCache, filePath?: string): Promise<void>;
+/** Merge a sync result into the cache without wiping unrelated competitions. */
+export declare function mergeSyncResult(cache: CampusCache, result: SyncResult): CampusCache;

package/dist/cache.js

@@ -0,0 +1,69 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const DEFAULT_CACHE_DIR = ".campus";
+export const DEFAULT_CACHE_FILE = "cache.json";
+export function emptyCache() {
+    return {
+        competitions: [],
+        seasons: [],
+        teams: [],
+        matches: [],
+        identities: [],
+        players: [],
+        playerMatchStats: [],
+        lineups: [],
+        injuries: [],
+    };
+}
+export function cachePath(cwd = process.cwd()) {
+    return path.join(cwd, DEFAULT_CACHE_DIR, DEFAULT_CACHE_FILE);
+}
+export async function loadCache(filePath = cachePath()) {
+    try {
+        const raw = await readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            competitions: parsed.competitions ?? [],
+            seasons: parsed.seasons ?? [],
+            teams: parsed.teams ?? [],
+            matches: parsed.matches ?? [],
+            identities: parsed.identities ?? [],
+            players: parsed.players ?? [],
+            playerMatchStats: parsed.playerMatchStats ?? [],
+            lineups: parsed.lineups ?? [],
+            injuries: parsed.injuries ?? [],
+        };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return emptyCache();
+        throw err;
+    }
+}
+export async function saveCache(cache, filePath = cachePath()) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(cache, null, 2) + "\n", "utf8");
+}
+function mergeById(existing, incoming) {
+    const map = new Map();
+    for (const item of existing)
+        map.set(item.id, item);
+    for (const item of incoming)
+        map.set(item.id, item);
+    return [...map.values()];
+}
+/** Merge a sync result into the cache without wiping unrelated competitions. */
+export function mergeSyncResult(cache, result) {
+    return {
+        competitions: mergeById(cache.competitions, result.competitions),
+        seasons: mergeById(cache.seasons, result.seasons),
+        teams: mergeById(cache.teams, result.teams),
+        matches: mergeById(cache.matches, result.matches),
+        identities: cache.identities,
+        players: mergeById(cache.players, result.players ?? []),
+        playerMatchStats: mergeById(cache.playerMatchStats, result.playerMatchStats ?? []),
+        lineups: mergeById(cache.lineups, result.lineups ?? []),
+        injuries: mergeById(cache.injuries, result.injuries ?? []),
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};