@ekmanss/5eplay 20260716.0.0

package/docs/data-contracts.md

@@ -0,0 +1,113 @@
+# Data contracts
+
+## Match Detail 1.0.0
+
+`getFiveEPlayMatch()` returns `{ data, diagnostics }`. `data` has `schemaVersion: '1.0.0'`,
+`sport: 'cs2'`, a canonical 5EPlay source URL, and the following stable sections.
+
+### Identity and series state
+
+- `match` contains the `csgo_mc_*` identity, numeric projection, live status, CS2 version,
+  best-of, schedule, stage, and per-team series score.
+- `tournament` contains the event identity, logo, grade, location, prize, dates, and source status.
+- `teams` contains exactly the source teams with 5E/Valve ranks, logos, series scores, odds, and
+  displayed odds percentages.
+- `veto` preserves source order and normalizes `ban`, `pick`, and `left` actions.
+
+When an in-progress API response temporarily omits an unplayed decider from `bouts_state`, the
+collector reconstructs that `upcoming` map from the authoritative veto. It does not invent scores
+or player data.
+
+### Maps
+
+Every map contains:
+
+- status, pick ownership, winner, score, current sides, first/second-half and overtime results;
+- live round number/stage, round start, timer, bomb state, player health, money, armor, kit, weapon;
+- `playerStats[].overall`, `.ct`, and `.t`, covering Rating, K-D-A, K/D, KD difference, KAST, ADR,
+  Round Swing, KPR, DPR, impact, multi-kill rating, headshots, first kills, flash assists, trades,
+  clutches, MVPs, and multi-kills;
+- `playerDuels`, the exact Player Comparison matrix represented as typed player/opponent kill rows;
+- public highlights and milestones;
+- `eventLog.events` in chronological order.
+
+An HTTP log page with `not_more: '1'` is marked `complete: true`. Each event retains the provider's
+monotonic `updateVersion` and typed round, kill, assist, flash, bomb, join/leave, suicide, restart,
+weapon, special-kill flag, and coordinate fields. Unknown future event types remain present as
+`kind: 'unknown'` instead of being discarded.
+
+`current` is the same live map object projected at the top level, or `null` when no map is live.
+
+### Analysis and community ratings
+
+`analysis` covers the visible pre-match team metrics, player metrics, map history, player-power
+records, recent matches, and head-to-head matches. Provider-specific power records remain JSON
+objects so new metrics are preserved without a schema bump.
+
+`communityRatings` contains every public tab and returned card, including player, coach, and
+big-event cards. Account-specific `my_*` voting state, write actions, and chat messages are not
+returned.
+
+### Missing values
+
+Missing numeric/string scalars are `null`; collections are empty arrays. Source percentage strings
+are returned as numbers without `%`. Provider IDs stay strings because team, player, tournament,
+and match namespaces are distinct.
+
+## Realtime updates
+
+A `FiveEPlayMatchSession` is an async iterable of:
+
+- `snapshot`: the initial complete HTTP result;
+- `state`: a merged MQTT scoreboard/state update;
+- `log`: one deduplicated MQTT event-log update.
+
+Every update includes a complete immutable snapshot. MQTT messages can be partial: map states are
+merged by `bout_num`, while match/tournament/global sections are shallow-merged over the verified
+HTTP baseline. Log events are merged by `updateVersion` and remain chronological.
+
+The credential endpoint's `client_id`, `username`, and `password` are transport-only. They are not
+part of either contract.
+
+## Live Matches 1.0.0
+
+`getFiveEPlayLiveMatches()` returns a lightweight `{ data, diagnostics }` result intended for
+frequent polling. `data.hasLiveMatches` is exactly `data.matches.length > 0`. Every match contains
+its canonical ID/URL, BO format, schedule/stage, tournament identity, two teams and series scores,
+available map summaries, and `currentMap`.
+
+The schedule endpoint groups both live and upcoming rows. A row is included only when its series
+state is live or it contains a live map. A series remains live between maps even though
+`currentMap` is then `null`. Normal polling uses the source's first 20 ordered rows and one HTTP
+request; another page is requested only when all 20 rows are live. No detail, analysis, event-log,
+community-rating, Markdown, or MQTT credential request is made.
+
+## Diagnostics
+
+Diagnostics include operation timing, canonical input where applicable, warnings, and one sanitized
+entry per HTTP request with only request kind, HTTP status, duration, byte size, and optional
+map/tab/page identity.
+URLs with credentials, request/response bodies, MQTT credentials, cookies, and chat state are never
+included.
+
+## Markdown Report 1.0.0
+
+`writeFiveEPlayMatchMarkdown(input, target)` fetches a snapshot, renders a reader-focused report,
+creates missing parent directories, and atomically replaces the destination. A target ending in
+`.md` is the exact file; any other target is treated as a directory and receives
+`<match-id>.md`. `renderFiveEPlayMatchMarkdown(result)` returns the same content without writing.
+
+The report includes:
+
+- a compact match/team overview and the complete veto;
+- completed/live map scores, half splits, readable round sequences, player overview/side tables,
+  player duels, concise highlights/milestones, and readable event logs;
+- a single-line placeholder for each upcoming map;
+- compact team/player/map analysis, head-to-head scores, recent results, and seven player-power
+  category scores;
+- sanitized capture diagnostics.
+
+The report intentionally omits community ratings, odds, logos, schedule/event metadata, transport
+versions, coordinates, raw round/milestone/power JSON, and provider-only codes. Those values remain
+available in the typed Match Detail contract. The Markdown writer also disables the community
+rating HTTP requests, while all other report data is fetched normally.

package/docs/recipes.md

@@ -0,0 +1,129 @@
+# Manual recipes
+
+Run these commands from the repository root after `pnpm build`.
+
+## Poll for newly started matches
+
+```ts
+import { setTimeout as delay } from 'node:timers/promises';
+import { getFiveEPlayLiveMatches } from '@ekmanss/5eplay';
+
+const known = new Set<string>();
+
+while (true) {
+  const { data } = await getFiveEPlayLiveMatches({ timeoutMs: 5_000 });
+  for (const match of data.matches) {
+    if (!known.has(match.id)) {
+      console.log('started', match.id, match.url);
+      known.add(match.id);
+    }
+  }
+  for (const id of [...known]) {
+    if (!data.matches.some((match) => match.id === id)) known.delete(id);
+  }
+  await delay(5_000);
+}
+```
+
+Calls are serialized, so a slow request never overlaps the next poll. A normal call uses one list
+request and performs no match-detail, log, analysis, community, Markdown, browser, or MQTT work.
+
+## Generate the human-readable Markdown report
+
+Pass an exact Markdown filename:
+
+```bash
+pnpm 5eplay:md -- \
+  'https://event.5eplay.com/csgo/matches/csgo_mc_2395709' \
+  './outputs/5eplay/csgo_mc_2395709.md'
+```
+
+Or pass a directory and let the writer use `<match-id>.md`:
+
+```bash
+pnpm 5eplay:md -- 'csgo_mc_2395709' './outputs/5eplay'
+```
+
+The writer creates missing parent directories and atomically replaces an existing destination.
+Community ratings are not requested because they are not part of the Markdown report.
+
+From another Node.js program:
+
+```ts
+import { writeFiveEPlayMatchMarkdown } from '@ekmanss/5eplay';
+
+const written = await writeFiveEPlayMatchMarkdown(
+  'csgo_mc_2395709',
+  '/absolute/path/current-match.md',
+);
+
+console.log(written.outputPath, written.bytes);
+```
+
+## Save a complete snapshot
+
+```bash
+FIVEEPLAY_MATCH_URL='https://event.5eplay.com/csgo/matches/csgo_mc_2395709' \
+node --input-type=module <<'EOF' > match.json
+import { getFiveEPlayMatch } from './packages/5eplay/dist/index.js';
+
+const result = await getFiveEPlayMatch(process.env.FIVEEPLAY_MATCH_URL);
+process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+EOF
+```
+
+## Inspect maps and live players
+
+```bash
+jq '{
+  match: .data.match,
+  maps: [.data.maps[] | {number, name, status, teams}],
+  livePlayers: [.data.current.playerStats[]?.overall[]? | {
+    name,
+    health: .equipment.health,
+    money: .equipment.money,
+    weapon: .equipment.weapon,
+    kills: .metrics.kills,
+    deaths: .metrics.deaths,
+    assists: .metrics.assists,
+    adr: .metrics.adr
+  }]
+}' match.json
+```
+
+## Stream realtime changes as NDJSON
+
+```bash
+FIVEEPLAY_MATCH_URL='csgo_mc_2395709' \
+node --input-type=module <<'EOF'
+import { createFiveEPlayMatchSession } from './packages/5eplay/dist/index.js';
+
+const controller = new AbortController();
+process.once('SIGINT', () => controller.abort());
+
+await using session = await createFiveEPlayMatchSession(
+  process.env.FIVEEPLAY_MATCH_URL,
+  { signal: controller.signal },
+);
+
+for await (const update of session) {
+  const compact = update.type === 'log'
+    ? { type: update.type, capturedAt: update.capturedAt, event: update.event }
+    : { type: update.type, capturedAt: update.capturedAt, current: update.snapshot.current };
+  process.stdout.write(JSON.stringify(compact) + '\n');
+}
+EOF
+```
+
+## Compact scoreboard-only snapshot
+
+```js
+const result = await getFiveEPlayMatch(match, {
+  includeAnalysis: false,
+  includeCommunityRatings: false,
+  includeLogs: false,
+});
+```
+
+This mode makes only the match-data request and is appropriate for high-frequency read-only
+scoreboard refreshes when a persistent MQTT session is not desired.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ekmanss/5eplay",
+  "version": "20260716.0.0",
+  "description": "Typed 5EPlay CS2 live-match discovery, match-detail snapshots, and MQTT updates without a browser.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "5eplay-match-md": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "match:md": "tsx src/cli.ts",
+    "test": "tsx --test tests/match.test.ts",
+    "test:live": "tsx tests/live.ts",
+    "test:live:list": "tsx tests/live_list.ts",
+    "verify": "pnpm check && pnpm test && pnpm build",
+    "prepack": "pnpm verify"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "tsx": "4.23.0",
+    "typescript": "5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ekmanss/sports-data-collectors.git",
+    "directory": "packages/5eplay"
+  },
+  "homepage": "https://github.com/ekmanss/sports-data-collectors/tree/main/packages/5eplay#readme",
+  "bugs": {
+    "url": "https://github.com/ekmanss/sports-data-collectors/issues"
+  },
+  "author": "ekmanss",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}