@ekmanss/5eplay 20260716.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ekmanss
+
+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,184 @@
+# @ekmanss/5eplay
+
+Typed 5EPlay CS2 match details and live updates for Node.js 22+. The collector uses 5EPlay's
+JSON endpoints and MQTT-over-WebSocket feed directly; it does not launch a browser, execute page
+JavaScript, scrape rendered DOM, or require a logged-in account.
+
+## Install
+
+```bash
+pnpm add @ekmanss/5eplay
+```
+
+## Complete match snapshot
+
+```ts
+import { getFiveEPlayMatch } from '@ekmanss/5eplay';
+
+const result = await getFiveEPlayMatch(
+  'https://event.5eplay.com/csgo/matches/csgo_mc_2395709',
+);
+
+console.log(result.data.match);
+console.log(result.data.maps);
+console.log(result.data.current);
+```
+
+The default snapshot includes every public match-data section used by the page:
+
+- match, tournament, teams, ranks, odds, best-of, stage, and series score;
+- complete map veto and every picked/decider map, including temporarily omitted upcoming maps;
+- per-map scores, halves, round-result codes, live timer/bomb state, and player equipment;
+- completed-map Data Overview metrics and the 5-by-5 Player Comparison kill matrix;
+- complete historical logs and the current map's available log history;
+- pre-match team/player/map analysis, recent matches, and head-to-head history;
+- public player and big-event community rating cards.
+
+Chat messages, login state, cookies, and account-specific actions are deliberately excluded.
+
+`getFiveEPlayMatch()` accepts either the canonical URL or a `csgo_mc_<id>` identifier. It returns
+`{ data, diagnostics }`. Independent HTTP sections are fetched concurrently; a normal capture does
+not open the realtime credential endpoint.
+
+## Currently live matches
+
+Use the list API for frequent checks that only need to know whether a CS2 match has started:
+
+```ts
+import { getFiveEPlayLiveMatches } from '@ekmanss/5eplay';
+
+const result = await getFiveEPlayLiveMatches();
+
+if (result.data.hasLiveMatches) {
+  for (const match of result.data.matches) {
+    console.log(match.id, match.url, match.teams, match.currentMap);
+  }
+}
+```
+
+This method normally makes one small public list request and never fetches match details, analysis,
+logs, community ratings, Markdown, or realtime credentials. The source list also contains upcoming
+matches, so the collector strictly keeps series with live state (including the interval between two
+maps, when `currentMap` is `null`). If the first 20 source rows are all live, it continues paging
+until every live match is collected.
+
+For serialized five-second polling without overlapping requests:
+
+```ts
+import { setTimeout as delay } from 'node:timers/promises';
+import { getFiveEPlayLiveMatches } from '@ekmanss/5eplay';
+
+while (true) {
+  const { data } = await getFiveEPlayLiveMatches({ timeoutMs: 5_000 });
+  console.log(data.hasLiveMatches, data.matches.map((match) => match.url));
+  await delay(5_000);
+}
+```
+
+## Generate a formatted Markdown report
+
+From this repository, pass a match URL/ID and either an exact `.md` filename or a directory:
+
+```bash
+pnpm 5eplay:md -- \
+  'https://event.5eplay.com/csgo/matches/csgo_mc_2395709' \
+  './outputs/5eplay-report.md'
+```
+
+```bash
+pnpm 5eplay:md -- 'csgo_mc_2395709' './outputs'
+```
+
+The directory form writes `./outputs/csgo_mc_2395709.md`. Parent directories are created
+automatically, and the completed report atomically replaces the destination file. The report
+contains match/map details, analysis, complete event logs, and sanitized request diagnostics.
+Community ratings are intentionally omitted and are not requested by the Markdown writer.
+
+The human-readable report is deliberately more compact than the typed snapshot:
+
+- the overview keeps only match status/identity/version/format, capture time, and source URL;
+- completed and live maps show scores, clear half/round results, player tables, duels, highlights,
+  milestones, and readable logs; upcoming maps use one short placeholder;
+- head-to-head and recent matches show only time, teams/opponent, score, and result;
+- player power is reduced to Rating plus firepower, entry, opening, utility, sniping, clutch, and
+  trading scores;
+- transport versions, coordinates, raw round codes, provider JSON, odds, logos, and community
+  ratings stay out of the Markdown report.
+
+These presentation choices do not remove fields from `getFiveEPlayMatch()` or realtime snapshots.
+
+Installed packages expose the same command as `5eplay-match-md` and a programmatic API:
+
+```ts
+import { writeFiveEPlayMatchMarkdown } from '@ekmanss/5eplay';
+
+const written = await writeFiveEPlayMatchMarkdown(
+  'csgo_mc_2395709',
+  '/absolute/path/to/report.md',
+);
+
+console.log(written.outputPath, written.bytes);
+```
+
+Use `renderFiveEPlayMatchMarkdown(result)` instead when the match has already been fetched and the
+caller wants the Markdown string without writing it.
+
+## Realtime session
+
+```ts
+import { createFiveEPlayMatchSession } from '@ekmanss/5eplay';
+
+await using session = await createFiveEPlayMatchSession('csgo_mc_2395709');
+
+for await (const update of session) {
+  if (update.type === 'state') {
+    console.log(update.snapshot.current?.teams);
+  } else if (update.type === 'log') {
+    console.log(update.event.kind, update.event.kill);
+  }
+}
+```
+
+The first yielded item is the complete HTTP snapshot. Later `state` updates contain the latest
+scoreboard snapshot and `log` updates contain one typed event. `session.snapshot()` returns the
+latest merged state at any time. The session uses one authorized MQTT connection for match state
+and one for event logs, sends keepalives, deduplicates log versions, and reconnects with a bounded
+backoff after an unexpected disconnect.
+
+Always close a session, either with `await using`, `await session.close()`, or a `finally` block.
+
+## Options
+
+```ts
+const result = await getFiveEPlayMatch(match, {
+  timeoutMs: 15_000,
+  signal: abortController.signal,
+  includeAnalysis: true,
+  includeLogs: true,
+  includeCommunityRatings: true,
+  onProgress: (event) => console.error(event.stage, event.message),
+});
+```
+
+The three `include*` flags default to `true`. Disable optional sections when only a compact live
+scoreboard is required.
+
+## Errors
+
+Failures throw `FiveEPlayError` with stable `code`, `operation`, `stage`, and `retryable` fields.
+Realtime credentials are kept inside the MQTT connection and never appear in data, diagnostics,
+progress events, or errors.
+
+## Documentation
+
+- [Data contracts](docs/data-contracts.md)
+- [Manual recipes](docs/recipes.md)
+
+## Disclaimer
+
+This is an unofficial project and is not affiliated with or endorsed by 5EPlay. Consumers are
+responsible for complying with applicable terms and using reasonable request rates.
+
+## License
+
+[MIT](LICENSE) © 2026 ekmanss

package/dist/async_queue.d.ts

@@ -0,0 +1,6 @@
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    #private;
+    push(value: T): void;
+    close(error?: unknown): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/async_queue.js

@@ -0,0 +1,44 @@
+export class AsyncQueue {
+    #values = [];
+    #waiters = [];
+    #closed = false;
+    #error;
+    push(value) {
+        if (this.#closed)
+            return;
+        const waiter = this.#waiters.shift();
+        if (waiter)
+            waiter.resolve({ done: false, value });
+        else
+            this.#values.push(value);
+    }
+    close(error) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#error = error;
+        for (const waiter of this.#waiters.splice(0)) {
+            if (error === undefined)
+                waiter.resolve({ done: true, value: undefined });
+            else
+                waiter.reject(error);
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                const value = this.#values.shift();
+                if (value !== undefined)
+                    return { done: false, value };
+                if (this.#closed) {
+                    if (this.#error !== undefined)
+                        throw this.#error;
+                    return { done: true, value: undefined };
+                }
+                return await new Promise((resolve, reject) => {
+                    this.#waiters.push({ resolve, reject });
+                });
+            },
+        };
+    }
+}

package/dist/capture.d.ts

@@ -0,0 +1,11 @@
+import { type CommunityCapture, type LogCapture } from './transform.js';
+import type { FiveEPlayClientOptions, FiveEPlayMatchIdentity, FiveEPlayRequestOptions, GetFiveEPlayMatchResult } from './types.js';
+export interface CapturedFiveEPlayMatch {
+    result: GetFiveEPlayMatchResult;
+    identity: FiveEPlayMatchIdentity;
+    detailData: unknown;
+    analysisData: unknown | null;
+    logs: Map<number, LogCapture>;
+    community: CommunityCapture | null;
+}
+export declare function captureFiveEPlayMatch(input: string, clientOptions?: FiveEPlayClientOptions, requestOptions?: FiveEPlayRequestOptions): Promise<CapturedFiveEPlayMatch>;

package/dist/capture.js

@@ -0,0 +1,199 @@
+import { asFiveEPlayError, FiveEPlayError } from './errors.js';
+import { fetchJson, responseData } from './http.js';
+import { requireMatchIdentity } from './input.js';
+import { buildFiveEPlayMatch, } from './transform.js';
+import { integer, record, records, text } from './value.js';
+const DATA_API = 'https://esports-data.5eplaycdn.com/v1/api/csgo';
+const COMMUNITY_API = 'https://app.5eplay.com/api/score';
+function emit(options, stage, message) {
+    options.onProgress?.({
+        operation: 'match-detail',
+        stage,
+        message,
+        timestamp: new Date().toISOString(),
+    });
+}
+function requestLifetime(options) {
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const timeout = setTimeout(() => {
+        controller.abort(new FiveEPlayError(`5EPlay operation timed out after ${timeoutMs}ms`, {
+            code: 'TIMEOUT', operation: 'match-detail', stage: 'fetching-match', retryable: true,
+        }));
+    }, timeoutMs);
+    const abort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted)
+        abort();
+    else
+        options.signal?.addEventListener('abort', abort, { once: true });
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            clearTimeout(timeout);
+            options.signal?.removeEventListener('abort', abort);
+        },
+    };
+}
+function matchApi(identity, suffix) {
+    return `${DATA_API}/matches/${identity.id}/${suffix}`;
+}
+async function optionalData(task, warnings, section) {
+    try {
+        return await task();
+    }
+    catch (error) {
+        warnings.push({
+            code: 'OPTIONAL_SECTION_UNAVAILABLE',
+            section,
+            reason: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+async function captureLogs(context, identity, detailData) {
+    const sourceMatch = record(record(detailData).match);
+    const activeBouts = records(sourceMatch.bouts_state).flatMap((bout) => {
+        const number = integer(bout.bout_num);
+        const status = integer(bout.status);
+        return number !== null && (status === 1 || status === 2) ? [{ number }] : [];
+    });
+    const entries = await Promise.all(activeBouts.map(async ({ number }) => {
+        const url = `${DATA_API}/match/${identity.id}/event/log?update_version=0&limit=500&bout_id=${identity.id}_${number}`;
+        const response = await fetchJson(context, url, {
+            kind: 'log', stage: 'fetching-logs', mapNumber: number,
+        });
+        const data = record(responseData(response, {
+            operation: 'match-detail', stage: 'fetching-logs', matchId: identity.id,
+        }));
+        return [number, {
+                complete: data.not_more === '1' || data.not_more === 1,
+                fromVersion: text(data.from_ver),
+                toVersion: text(data.to_ver),
+                rows: Array.isArray(data.list) ? data.list : [],
+            }];
+    }));
+    return new Map(entries);
+}
+async function captureCommunity(context, identity, tabsData) {
+    const tabs = Array.isArray(tabsData) ? tabsData : [];
+    const entries = await Promise.all(tabs.map(async (rawTab) => {
+        const tab = record(rawTab);
+        const tabName = text(tab.tab) ?? '';
+        const id = text(tab.id) ?? '';
+        const query = new URLSearchParams({
+            match_id: identity.id,
+            tab: tabName,
+            game_type: '1',
+            team_id: id,
+        });
+        const response = await fetchJson(context, `${COMMUNITY_API}/match_score_list?${query}`, {
+            kind: 'community-list', stage: 'fetching-community', tab: `${tabName}:${id}`,
+        });
+        const cards = responseData(response, {
+            operation: 'match-detail', stage: 'fetching-community', matchId: identity.id,
+        });
+        return [`${tabName}:${id}`, Array.isArray(cards) ? cards : []];
+    }));
+    return { tabs, cardsByTab: new Map(entries) };
+}
+export async function captureFiveEPlayMatch(input, clientOptions = {}, requestOptions = {}) {
+    const startedAt = new Date().toISOString();
+    emit(requestOptions, 'validating-input', 'Validating 5EPlay match input');
+    const identity = requireMatchIdentity(input);
+    const lifetime = requestLifetime(requestOptions);
+    const diagnostics = [];
+    const warnings = [];
+    const context = {
+        operation: 'match-detail',
+        matchId: identity.id,
+        signal: lifetime.signal,
+        fetch: clientOptions.fetch ?? globalThis.fetch,
+        diagnostics,
+    };
+    if (typeof context.fetch !== 'function') {
+        lifetime.dispose();
+        throw new FiveEPlayError('global fetch is unavailable', {
+            code: 'INTERNAL_ERROR', operation: 'match-detail', stage: 'fetching-match', retryable: false,
+            matchId: identity.id,
+        });
+    }
+    try {
+        emit(requestOptions, 'fetching-match', 'Fetching 5EPlay match snapshot');
+        const detailPromise = fetchJson(context, matchApi(identity, 'data'), {
+            kind: 'match', stage: 'fetching-match',
+        }).then((value) => responseData(value, {
+            operation: 'match-detail', stage: 'fetching-match', matchId: identity.id,
+        }));
+        const analysisPromise = requestOptions.includeAnalysis === false ? Promise.resolve(null)
+            : optionalData(async () => {
+                emit(requestOptions, 'fetching-analysis', 'Fetching pre-match analysis');
+                const value = await fetchJson(context, matchApi(identity, 'analysis_v1'), {
+                    kind: 'analysis', stage: 'fetching-analysis',
+                });
+                return responseData(value, {
+                    operation: 'match-detail', stage: 'fetching-analysis', matchId: identity.id,
+                });
+            }, warnings, 'analysis');
+        const tabsPromise = requestOptions.includeCommunityRatings === false ? Promise.resolve(null)
+            : optionalData(async () => {
+                emit(requestOptions, 'fetching-community', 'Fetching community rating tabs');
+                const query = new URLSearchParams({ match_id: identity.id, game_type: '1' });
+                const value = await fetchJson(context, `${COMMUNITY_API}/match_score_tab?${query}`, {
+                    kind: 'community-tabs', stage: 'fetching-community',
+                });
+                return responseData(value, {
+                    operation: 'match-detail', stage: 'fetching-community', matchId: identity.id,
+                });
+            }, warnings, 'communityRatings');
+        const [detailData, analysisData, tabsData] = await Promise.all([
+            detailPromise, analysisPromise, tabsPromise,
+        ]);
+        const sourceId = text(record(record(record(detailData).match).mc_info).id);
+        if (sourceId !== identity.id) {
+            throw new FiveEPlayError('5EPlay match payload identity does not match the request', {
+                code: 'INVALID_RESPONSE', operation: 'match-detail', stage: 'fetching-match',
+                retryable: true, matchId: identity.id, details: { sourceId },
+            });
+        }
+        const logsPromise = requestOptions.includeLogs === false
+            ? Promise.resolve(new Map())
+            : (emit(requestOptions, 'fetching-logs', 'Fetching complete map logs'),
+                captureLogs(context, identity, detailData));
+        const communityPromise = tabsData === null ? Promise.resolve(null)
+            : optionalData(() => captureCommunity(context, identity, tabsData), warnings, 'communityRatings');
+        const [logs, community] = await Promise.all([logsPromise, communityPromise]);
+        emit(requestOptions, 'building-output', 'Building typed 5EPlay match output');
+        const capturedAt = new Date().toISOString();
+        const data = buildFiveEPlayMatch({
+            identity, capturedAt, detailData, analysisData, logs, community,
+        });
+        const completedAt = new Date().toISOString();
+        const result = {
+            data,
+            diagnostics: {
+                schemaVersion: '1.0.0',
+                operation: 'match-detail',
+                startedAt,
+                completedAt,
+                durationMs: Math.max(0, Date.parse(completedAt) - Date.parse(startedAt)),
+                input: identity,
+                requests: diagnostics,
+                warnings,
+            },
+        };
+        emit(requestOptions, 'completed', '5EPlay match capture completed');
+        return { result, identity, detailData, analysisData, logs, community };
+    }
+    catch (error) {
+        if (lifetime.signal.aborted && lifetime.signal.reason instanceof Error) {
+            throw lifetime.signal.reason;
+        }
+        throw asFiveEPlayError(error, {
+            code: 'INTERNAL_ERROR', operation: 'match-detail', stage: 'fetching-match',
+            retryable: false, matchId: identity.id,
+        });
+    }
+    finally {
+        lifetime.dispose();
+    }
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { writeFiveEPlayMatchMarkdown } from './write_markdown.js';
+function usage() {
+    return [
+        '用法：',
+        '  5eplay-match-md <比赛URL或ID> <输出.md或输出目录>',
+        '',
+        '示例：',
+        "  5eplay-match-md 'https://event.5eplay.com/csgo/matches/csgo_mc_2395709' './outputs/report.md'",
+        "  5eplay-match-md 'csgo_mc_2395709' './outputs'",
+    ].join('\n');
+}
+const rawArguments = process.argv.slice(2);
+const arguments_ = rawArguments[0] === '--' ? rawArguments.slice(1) : rawArguments;
+if (arguments_.includes('--help') || arguments_.includes('-h')) {
+    process.stdout.write(`${usage()}\n`);
+    process.exit(0);
+}
+if (arguments_.length !== 2) {
+    process.stderr.write(`${usage()}\n`);
+    process.exit(2);
+}
+const [input, target] = arguments_;
+try {
+    const written = await writeFiveEPlayMatchMarkdown(input, target, {
+        timeoutMs: 30_000,
+        onProgress: (event) => process.stderr.write(`[${event.stage}] ${event.message}\n`),
+    });
+    process.stdout.write(`${JSON.stringify({
+        outputPath: written.outputPath,
+        bytes: written.bytes,
+        matchId: written.result.data.match.id,
+        status: written.result.data.match.status,
+        maps: written.result.data.maps.length,
+    }, null, 2)}\n`);
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`生成 5EPlay Markdown 失败：${message}\n`);
+    process.exitCode = 1;
+}

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import type { GetFiveEPlayMatchOptions, GetFiveEPlayMatchResult } from './types.js';
+export declare function getFiveEPlayMatch(input: string, options?: GetFiveEPlayMatchOptions): Promise<GetFiveEPlayMatchResult>;

package/dist/client.js

@@ -0,0 +1,4 @@
+import { captureFiveEPlayMatch } from './capture.js';
+export async function getFiveEPlayMatch(input, options = {}) {
+    return (await captureFiveEPlayMatch(input, options, options)).result;
+}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+import type { FiveEPlayErrorCode, FiveEPlayOperation, FiveEPlayStage } from './types.js';
+export interface FiveEPlayErrorOptions {
+    code: FiveEPlayErrorCode;
+    operation: FiveEPlayOperation;
+    stage: FiveEPlayStage;
+    retryable: boolean;
+    matchId?: string;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+export declare class FiveEPlayError extends Error {
+    readonly code: FiveEPlayErrorCode;
+    readonly operation: FiveEPlayOperation;
+    readonly stage: FiveEPlayStage;
+    readonly retryable: boolean;
+    readonly matchId?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options: FiveEPlayErrorOptions);
+}
+export declare function asFiveEPlayError(error: unknown, fallback: FiveEPlayErrorOptions): FiveEPlayError;

package/dist/errors.js

@@ -0,0 +1,42 @@
+function safeCause(cause) {
+    if (cause === undefined)
+        return undefined;
+    const message = (cause instanceof Error ? cause.message : String(cause))
+        .replace(/(client_id|username|password)["'=:\s]+[^,}\s]+/gi, '$1=***')
+        .replace(/(https?:\/\/|wss:\/\/)[^\s/@:]+:[^\s/@]+@/gi, '$1***:***@');
+    return new Error(message);
+}
+export class FiveEPlayError extends Error {
+    code;
+    operation;
+    stage;
+    retryable;
+    matchId;
+    details;
+    constructor(message, options) {
+        super(message, { cause: safeCause(options.cause) });
+        this.name = 'FiveEPlayError';
+        this.code = options.code;
+        this.operation = options.operation;
+        this.stage = options.stage;
+        this.retryable = options.retryable;
+        this.matchId = options.matchId;
+        this.details = options.details;
+    }
+}
+export function asFiveEPlayError(error, fallback) {
+    if (error instanceof FiveEPlayError)
+        return error;
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return new FiveEPlayError('5EPlay operation was aborted', {
+            ...fallback,
+            code: 'ABORTED',
+            retryable: false,
+            cause: error,
+        });
+    }
+    return new FiveEPlayError(error instanceof Error ? error.message : String(error), {
+        ...fallback,
+        cause: error,
+    });
+}

package/dist/http.d.ts

@@ -0,0 +1,23 @@
+import type { FiveEPlayOperation, FiveEPlayRequestDiagnostic, FiveEPlayStage } from './types.js';
+export interface RequestContext {
+    operation: FiveEPlayOperation;
+    matchId?: string;
+    signal: AbortSignal;
+    fetch: typeof globalThis.fetch;
+    diagnostics: FiveEPlayRequestDiagnostic[];
+}
+export interface FetchJsonOptions {
+    kind: FiveEPlayRequestDiagnostic['kind'];
+    stage: FiveEPlayStage;
+    method?: 'GET' | 'POST';
+    body?: unknown;
+    mapNumber?: number;
+    tab?: string;
+    page?: number;
+}
+export declare function fetchJson(context: RequestContext, url: string, options: FetchJsonOptions): Promise<unknown>;
+export declare function responseData(value: unknown, context: {
+    operation: FiveEPlayOperation;
+    stage: FiveEPlayStage;
+    matchId?: string;
+}): unknown;