campus-stats 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.6.0
+
+- **Remove injuries** from CLI, library, cache, and SQLite (not in StatsBomb API).
+- **BYOK:** free Open Data by default; optional StatsBomb customer login
+  (`SB_USERNAME` / `SB_PASSWORD`) → paid API at `data.statsbombservices.com`
+- **Paid extras:** `campus endpoints` + flags (`--with-paid-player-season-stats`, …)
+- **README:** Campus organizes data — free path already connected; bring-your-own
+  StatsBomb licence with clear examples
+
 ## 0.5.0
 
 - **CI / data host:** GitLab → **GitHub Actions**

package/README.md

@@ -1,11 +1,18 @@
 # Campus (`campus-stats`)
 
-**Open, normalized, queryable data for women's football — installable in your app.**
+**A data layer for women's football — not a data vendor.**
 
-`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.
+Campus does **not** sell football data. It **organizes** data from existing
+sources into one schema you can query from a CLI or drop into a web app.
+
+You choose how to feed it:
+
+| Path | What you do | What Campus does |
+|------|-------------|------------------|
+| **Free** | Nothing — already connected | Syncs [StatsBomb Open Data](https://github.com/statsbomb/open-data) (and an FBref schedule pilot) |
+| **Your StatsBomb licence** | Set `SB_USERNAME` / `SB_PASSWORD` | Talks to the StatsBomb **paid API** with *your* credentials and normalizes the response |
+
+Same CLI, same `CampusClient`, same local cache either way.
 
 Requires **Node.js ≥ 22**.
 
@@ -13,129 +20,240 @@ Requires **Node.js ≥ 22**.
 
 ## Install
 
-Published on **npmjs.com**:
-
 ```bash
 npm install campus-stats
+```
 
+Binaries: `campus` and `campus-stats` (same entrypoint).
+
+```bash
 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).
+---
 
-Documentation lives in this README.  
-Source: https://github.com/Minacava/campus-stats
+## Try the free path (no account)
 
----
+Open Data is wired in. No signup, no API key:
 
-## Use as a library (recommended for apps)
+```bash
+# Sync one competition from StatsBomb Open Data
+npx campus sync --competition "Liga F"
 
-```ts
-import { CampusClient } from "campus-stats";
+# Or every women's competition in the open catalogue
+npx campus sync --fantasy
 
-const client = await CampusClient.open();
-await client.syncFantasy({ includePlayerStats: true });
-// or: const client = await CampusClient.fromBundle();
+# Optional: lineups + basic player stats (capped)
+npx campus sync --fantasy --with-players
 
-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" });
+# Query the local cache
+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"
 
-return Response.json({ clubs, nations, matches, squad, points });
+# Confirm you are on free Open Data
+npx campus credentials
+# → statsbomb.mode: "open-data"
 ```
 
-### What you get from the package
+Data is stored in `.campus/cache.json` (or use `--sqlite` / `--db <path>`).
 
-| 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 |
+**Free sources today**
 
----
+| Source | Coverage |
+|--------|----------|
+| StatsBomb Open Data | Women's competitions published on GitHub (e.g. Liga F, WSL, NWSL, major tournaments) |
+| FBref | Schedule pilot — WSL + Liga F (`--source fbref`) |
 
-## Keep data fresh (cron)
+Coverage and freshness follow what those platforms publish for free.
 
-1. GitHub Actions schedule on `main` (e.g. `0 6 * * *`) runs
-   **Refresh fantasy data** and publishes the `data-latest` release
-   (`cache.json`).
-2. Apps call `CampusClient.fromBundle()` or `npx campus pull`.
+---
 
-Details: [`docs/cron.md`](./docs/cron.md).
+## Use your StatsBomb licence (optional)
 
----
+If you already pay Hudl StatsBomb, Campus is a thin pipe: **your login → their
+paid API → one Campus schema → your app**.
+
+Campus never hosts or resells a StatsBomb subscription.
 
-## CLI quick start
+### 1. Connect credentials
 
-After `npm install campus-stats`:
+Same env vars as [statsbombpy](https://github.com/statsbomb/statsbombpy):
 
 ```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
+export SB_USERNAME="you@company.com"
+export SB_PASSWORD="your-statsbomb-password"
+
+npx campus credentials
+# → statsbomb.mode: "paid"
 ```
 
-Store: `.campus/cache.json` (or `--sqlite` / `--db <path>`).
+Or write a local config file (the `.campus/` directory is gitignored):
+
+```json
+{
+  "statsbomb": {
+    "username": "you@company.com",
+    "password": "your-statsbomb-password"
+  }
+}
+```
+
+Or one-off flags:
+
+```bash
+npx campus sync --competition "Liga F" \
+  --sb-user "you@company.com" \
+  --sb-password "your-statsbomb-password"
+```
 
-Single-competition sync and identities still work:
+### 2. Sync (same commands as free)
 
 ```bash
 npx campus sync --competition "Liga F"
-npx campus sync --source fbref --competition "WSL"
-npx campus identities propose --competition "Liga F"
+npx campus sync --fantasy
 ```
 
+With a paid login, Campus calls `https://data.statsbombservices.com` instead of
+Open Data. Which leagues and seasons you get depends on **your StatsBomb
+contract**, not on Campus.
+
+### 3. Optional paid-only endpoints
+
+These hit the StatsBomb paid API **directly** when your licence includes them:
+
+| Flag | StatsBomb paid API |
+|------|--------------------|
+| `--with-paid-player-match-stats` | Player match aggregates |
+| `--with-paid-team-match-stats` | Team match aggregates |
+| `--with-paid-player-season-stats` | Player season aggregates |
+| `--with-paid-team-season-stats` | Team season aggregates |
+| `--with-paid-360` | 360 freeze frames |
+
+```bash
+npx campus sync --competition "Liga F" \
+  --with-paid-player-season-stats \
+  --with-paid-player-match-stats
+```
+
+See the full endpoint map:
+
+```bash
+npx campus endpoints
+```
+
+> **FBref:** there is no official API key. `--source fbref` remains free HTML only.
+
 ---
 
-## Supported data (open sources)
+## Use in your app
 
-| 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 |
+```ts
+import { CampusClient, resolveCredentials, syncFantasyBundle } from "campus-stats";
+
+// Free: omit credentials → Open Data
+// Paid: set SB_USERNAME / SB_PASSWORD in the environment
+const creds = await resolveCredentials();
+
+await syncFantasyBundle({
+  includePlayerStats: true,
+  credentials: creds.statsbombPaidReady
+    ? {
+        username: creds.statsbomb.username,
+        password: creds.statsbomb.password,
+      }
+    : undefined,
+});
+
+const client = await CampusClient.open();
 
-Injuries are **not** in these open feeds yet — the API is ready, the list is empty.
+const clubs = client.teams({ competition: "Liga F", kind: "club" });
+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, matches, squad, points });
+```
+
+Or load a published bundle without syncing yourself:
+
+```ts
+const client = await CampusClient.fromBundle();
+```
+
+| Export | Purpose |
+|--------|---------|
+| `CampusClient` | Open cache / bundle, query teams, matches, squads, fantasy points |
+| `syncFantasyBundle` / `updateCachedCompetitions` | Bulk sync helpers |
+| `resolveCredentials` | Detect free vs paid StatsBomb login |
+| `scoreFantasyPoints` | Default fantasy scoring rules |
+| Types | `Competition`, `Season`, `Team`, `Match`, `Player`, `LineupEntry`, … |
+
+---
+
+## CLI cheat sheet
+
+```bash
+npx campus sync --fantasy|--all [--with-players] [--player-stats-limit <n>]
+npx campus sync --competition <name> [--source statsbomb|fbref] [--with-players]
+npx campus update
+npx campus pull
+npx campus available
+npx campus credentials
+npx campus endpoints
+npx campus competitions
+npx campus seasons --competition <name>
+npx campus teams --competition <name>
+npx campus matches --competition <name> [--season <name>] [--team <name>]
+npx campus players [--team <name>] [--name <name>]
+npx campus player-stats [--competition <name>] [--match <id>] [--player <name>]
+npx campus lineups [--match <id>] [--team <name>]
+npx campus squad --competition <name> --team <name>
+npx campus fantasy-points [--competition <name>] [--player <name>]
+npx campus identities propose --competition <name>
+```
+
+Paid extras (require `SB_USERNAME` / `SB_PASSWORD`):  
+`--with-paid-player-match-stats`, `--with-paid-team-match-stats`,
+`--with-paid-player-season-stats`, `--with-paid-team-season-stats`,
+`--with-paid-360`.
 
 ---
 
-## Why this shape
+## Keep data fresh
 
-- **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.
+- **Pull a published snapshot:** `npx campus pull` or `CampusClient.fromBundle()`  
+  (this repo can publish a daily `data-latest` release via GitHub Actions).
+- **Sync yourself:** `npx campus sync --fantasy` or `npx campus update`.
 
 ---
 
-## Docs & source
+## Design
 
-All public docs are in this README on GitHub:
-https://github.com/Minacava/campus-stats
+- **One schema** — your app never sees provider field names.
+- **Provenance** — every record carries `sources: [{ source, id }]`.
+- **Local-first** — JSON cache by default; SQLite optional (`--sqlite`).
 
 ---
 
-## Data source & terms
+## 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.
+- [StatsBomb Open Data](https://github.com/statsbomb/open-data) — free for research and genuine football analytics; credit StatsBomb ([media pack](https://statsbomb.com/media-pack/)).
+- StatsBomb paid API — your Hudl StatsBomb contract; never commit `SB_USERNAME` / `SB_PASSWORD`.
+- FBref / Sports Reference — respect site terms, `robots.txt`, and rate limits.
 
-Pass those requirements downstream.
+Pass those requirements downstream to your users.
 
 ---
 
 ## License
 
-Code: MIT (see [`LICENSE`](./LICENSE)). Data: subject to each source's terms.
+Code: MIT (see [`LICENSE`](./LICENSE)).  
+Data: subject to each upstream source’s terms.
+
+Source: https://github.com/Minacava/campus-stats

package/dist/cache.js

@@ -12,7 +12,6 @@ export function emptyCache() {
         players: [],
         playerMatchStats: [],
         lineups: [],
-        injuries: [],
     };
 }
 export function cachePath(cwd = process.cwd()) {
@@ -31,7 +30,6 @@ export async function loadCache(filePath = cachePath()) {
             players: parsed.players ?? [],
             playerMatchStats: parsed.playerMatchStats ?? [],
             lineups: parsed.lineups ?? [],
-            injuries: parsed.injuries ?? [],
         };
     }
     catch (err) {
@@ -64,6 +62,5 @@ export function mergeSyncResult(cache, result) {
         players: mergeById(cache.players, result.players ?? []),
         playerMatchStats: mergeById(cache.playerMatchStats, result.playerMatchStats ?? []),
         lineups: mergeById(cache.lineups, result.lineups ?? []),
-        injuries: mergeById(cache.injuries, result.injuries ?? []),
     };
 }