cito-mcp 0.1.0 → 0.2.2

package/dist/tools/live.js

@@ -0,0 +1,447 @@
+/**
+ * live_matches + upcoming_schedule
+ */
+import { clampInt, decodeCursor, encodeCursor, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT, errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
+import { normalizeMatch } from './normalize.js';
+import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
+const LIVE_PATHS = {
+    lol: '/lol/live',
+    cs2: '/cs2/live', // fixed: not /cs2/matches/live
+    dota2: '/dota2/matches/live',
+    cod: '/cod/matches/live',
+    ufc: '/ufc/live',
+};
+/**
+ * Extract live match/bout rows. UFC /ufc/live returns
+ * { liveBouts, events, ... } — events are supervisor shells without fighters.
+ * Prefer liveBouts (and nested tracking on events) over plain events[].
+ */
+function extractLiveRows(data, game) {
+    const root = asRecord(data);
+    const payload = asRecord(root?.data) ?? root;
+    if (!payload)
+        return extractRows(data);
+    if (game === 'ufc') {
+        const liveBouts = Array.isArray(payload.liveBouts) ? payload.liveBouts : [];
+        if (liveBouts.length)
+            return liveBouts;
+        // Some shapes nest tracking under events[].tracking
+        const events = Array.isArray(payload.events) ? payload.events : [];
+        const fromTracking = [];
+        for (const ev of events) {
+            const er = asRecord(ev);
+            const tracking = Array.isArray(er?.tracking) ? er.tracking : [];
+            for (const t of tracking) {
+                const tr = asRecord(t) ?? {};
+                fromTracking.push({
+                    ...tr,
+                    eventSlug: pickString(tr.eventSlug, er?.eventSlug, er?.slug),
+                    eventName: pickString(er?.name, er?.eventName, er?.eventSlug),
+                });
+            }
+        }
+        if (fromTracking.length)
+            return fromTracking;
+        // Last resort: empty live board rather than fake ? vs ? event shells
+        return [];
+    }
+    return extractRows(data);
+}
+export const liveMatches = {
+    name: 'live_matches',
+    description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
+
+When to use:
+- "What's live right now?"
+- Ops/dashboard live strip
+
+Prefer over: sequential per-game call_api live probes.
+
+Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
+
+CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
+
+Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
+Example: { "game": "all", "limitPerGame": 10 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            game: gameSchema({
+                description: 'Single game or all. Omit for all primary games. Example: "lol".',
+            }),
+            limitPerGame: limitSchema({
+                default: 10,
+                max: 25,
+                description: 'Max matches kept per game (default 10, max 25).',
+            }),
+            includeLabelsOnly: boolSchema('Token-light mode: shorter item payloads (label + matchId + status).', false),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: true });
+        if (gameParse.error && args.game != null && args.game !== '') {
+            return errorEnvelope({
+                code: 'UNSUPPORTED_GAME',
+                message: gameParse.error,
+                game: null,
+                source: 'live_matches',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const games = gameParse.game && isPrimaryGame(gameParse.game) ? [gameParse.game] : [...PRIMARY_GAMES];
+        const limitPerGame = clampInt(args.limitPerGame, 10, 1, 25);
+        const labelsOnly = args.includeLabelsOnly === true;
+        const partial = [];
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        const settled = await Promise.all(games.map(async (game) => {
+            const path = LIVE_PATHS[game];
+            const res = await fetchJson(ctx, path);
+            return { game, path, res };
+        }));
+        const sections = [];
+        for (const { game, res } of settled) {
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...res.headers };
+            if (!res.ok) {
+                const code = mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) });
+                partial.push(partialFromRejection(`game:${game}`, {
+                    code,
+                    message: `Live board unavailable for ${game} (HTTP ${res.status})`,
+                    httpStatus: res.status,
+                }));
+                sections.push({
+                    game,
+                    count: 0,
+                    ok: false,
+                    note: `unavailable (HTTP ${res.status})`,
+                    items: [],
+                });
+                continue;
+            }
+            // Prefer real match/bout rows over supervisor event shells (UFC /ufc/live).
+            let rows = extractLiveRows(res.data, game);
+            const obj = asRecord(res.data);
+            if (rows.length === 0 && Array.isArray(obj?.matches))
+                rows = obj.matches;
+            const normalized = rows
+                .slice(0, limitPerGame)
+                .map((row) => normalizeMatch(game, row, 'live'))
+                // Drop hollow UFC event-supervisor rows mistaken for bouts (no bout id + no sides).
+                .filter((m) => {
+                if (game !== 'ufc')
+                    return true;
+                if (m.matchId && m.matchId !== 'unknown' && (m.team1?.name || m.team2?.name))
+                    return true;
+                if (m.team1?.name && m.team2?.name)
+                    return true;
+                // Keep if at least a real bout id even when fighters pending
+                return Boolean(m.matchId && m.matchId !== 'unknown' && !String(m.matchId).startsWith('event'));
+            });
+            const items = labelsOnly
+                ? normalized.map((m) => ({
+                    game: m.game,
+                    matchId: m.matchId,
+                    status: m.status,
+                    label: m.label,
+                    startTime: m.startTime,
+                }))
+                : normalized;
+            sections.push({
+                game,
+                count: normalized.length,
+                ok: true,
+                items,
+            });
+        }
+        const totalLive = sections.reduce((sum, s) => sum + (s.ok ? s.count : 0), 0);
+        return successEnvelope({
+            source: 'live_matches',
+            game: games.length === 1 ? games[0] : null,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            partial: partial.length ? partial : undefined,
+            data: {
+                sections,
+                totalLive,
+                asOf: new Date().toISOString(),
+            },
+        });
+    },
+};
+export const upcomingSchedule = {
+    name: 'upcoming_schedule',
+    description: `Upcoming matches/events for one game, with game-specific filters.
+
+When to use:
+- "What's on this week?"
+- Calendar UI; team next matches
+
+Prefer over: live_matches for not-yet-started fixtures.
+
+Do not use when: only in-progress matches needed → live_matches.
+
+Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):
+- lol: hours, team (slug), league (slug)
+- cs2: team, from, to (ISO); hours not applied upstream
+- cod: team, tournamentId
+- dota2 / ufc: limit/cursor primarily; team may be client-filtered where data allows
+
+Parallel-safe: yes. Upstream cost: 1–2.
+Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            hours: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 336,
+                default: 72,
+                description: 'Horizon in hours when from/to not set (default 72). Example: 48.',
+            },
+            from: stringSchema('ISO-8601 start bound.', '2026-07-27T00:00:00.000Z'),
+            to: stringSchema('ISO-8601 end bound.'),
+            team: stringSchema('Team id or slug filter.', 't1'),
+            league: stringSchema('League id or slug filter.', 'lck'),
+            tournamentId: stringSchema('Tournament id filter.'),
+            limit: limitSchema(),
+            cursor: stringSchema('Opaque cursor from pagination.nextCursor only.'),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'upcoming_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        const limit = clampInt(args.limit, DEFAULT_PAGE_LIMIT, 1, MAX_PAGE_LIMIT);
+        const hours = clampInt(args.hours, 72, 1, 336);
+        const cursor = decodeCursor(typeof args.cursor === 'string' ? args.cursor : null);
+        const offset = typeof cursor?.offset === 'number' ? cursor.offset : 0;
+        const team = typeof args.team === 'string' ? args.team : undefined;
+        const league = typeof args.league === 'string' ? args.league : undefined;
+        const tournamentId = typeof args.tournamentId === 'string' ? args.tournamentId : undefined;
+        const from = typeof args.from === 'string' ? args.from : undefined;
+        const to = typeof args.to === 'string' ? args.to : undefined;
+        const warnings = [];
+        const noteIgnored = (param, reason) => {
+            warnings.push(`Ignored filter "${param}": ${reason}`);
+        };
+        let path = '';
+        let query = { limit, offset };
+        if (game === 'lol') {
+            path = '/lol/schedule/upcoming';
+            query = {
+                hours: String(hours),
+                limit: String(limit),
+                offset: String(offset),
+                ...(league ? { leagueSlug: league } : {}),
+                ...(team ? { teamSlug: team } : {}),
+            };
+            if (from)
+                noteIgnored('from', 'LoL upcoming uses hours/team/league, not from');
+            if (to)
+                noteIgnored('to', 'LoL upcoming uses hours/team/league, not to');
+            if (tournamentId)
+                noteIgnored('tournamentId', 'use league filter or standings for LoL tournaments');
+        }
+        else if (game === 'cs2') {
+            path = '/cs2/matches';
+            query = {
+                status: 'upcoming',
+                limit,
+                page: Math.floor(offset / limit) + 1,
+                ...(team ? { team } : {}),
+                ...(from ? { from } : {}),
+                ...(to ? { to } : {}),
+            };
+            if (args.hours !== undefined)
+                noteIgnored('hours', 'CS2 uses from/to or unfiltered upcoming; hours is not applied upstream');
+            if (league)
+                noteIgnored('league', 'CS2 schedule does not accept league here — filter client-side or use event tools');
+            if (tournamentId)
+                noteIgnored('tournamentId', 'CS2 uses eventId via event_card / call_api, not this tool');
+        }
+        else if (game === 'dota2') {
+            path = '/dota2/matches/upcoming';
+            query = { limit, offset };
+            if (args.hours !== undefined)
+                noteIgnored('hours', 'Dota upcoming does not accept hours');
+            if (league)
+                noteIgnored('league', 'Dota upcoming does not accept league');
+            if (tournamentId)
+                noteIgnored('tournamentId', 'Dota upcoming does not accept tournamentId');
+            if (from)
+                noteIgnored('from', 'Dota upcoming does not accept from');
+            if (to)
+                noteIgnored('to', 'Dota upcoming does not accept to');
+        }
+        else if (game === 'cod') {
+            path = '/cod/matches/upcoming';
+            query = {
+                limit,
+                offset,
+                ...(team ? { team } : {}),
+                ...(tournamentId ? { tournamentId } : {}),
+            };
+            if (args.hours !== undefined)
+                noteIgnored('hours', 'COD upcoming does not accept hours');
+            if (league)
+                noteIgnored('league', 'COD uses tournamentId, not league');
+            if (from)
+                noteIgnored('from', 'COD upcoming does not accept from');
+            if (to)
+                noteIgnored('to', 'COD upcoming does not accept to');
+        }
+        else if (game === 'ufc') {
+            path = '/ufc/events/upcoming';
+            // Request more events than limit so client-side hours filter still has a card pool.
+            query = {
+                limit: Math.min(50, Math.max(limit * 3, limit)),
+                page: Math.floor(offset / limit) + 1,
+                includeBouts: true,
+            };
+            // hours / from / to applied client-side after expand (below) — do not warn as ignored.
+            if (team)
+                noteIgnored('team', 'UFC uses fighter filters via resolve/event_card, not team on schedule');
+            if (league)
+                noteIgnored('league', 'UFC has no league filter on upcoming events');
+            if (tournamentId)
+                noteIgnored('tournamentId', 'pass event slug via event_card instead');
+        }
+        const res = await fetchJson(ctx, path, { query });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Upcoming schedule failed for ${game} (HTTP ${res.status})`,
+                game,
+                source: 'upcoming_schedule',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                rateLimit: res.headers,
+                httpStatus: res.status,
+            });
+        }
+        let rows = extractRows(res.data);
+        // UFC events → expand to bout rows (fighters[] shape) so labels are not "? vs ?"
+        if (game === 'ufc') {
+            const expanded = [];
+            for (const event of rows) {
+                const er = asRecord(event) ?? {};
+                const eventName = pickString(er.name, er.title);
+                const eventId = pickString(er.id, er.slug);
+                const eventSlug = pickString(er.slug);
+                const eventStart = pickString(er.startTime, er.date, er.startsAt);
+                const bouts = extractRows(er.bouts ?? er.fights);
+                if (bouts.length) {
+                    for (const bout of bouts) {
+                        const br = asRecord(bout) ?? {};
+                        expanded.push({
+                            ...br,
+                            eventName,
+                            eventId,
+                            eventSlug,
+                            startTime: pickString(br.startTime, br.date, eventStart),
+                        });
+                    }
+                }
+                else {
+                    // Keep event shell as a schedule card with a real label (not fighter matchup)
+                    expanded.push({
+                        id: eventId ?? eventSlug,
+                        matchId: eventId ?? eventSlug,
+                        name: eventName,
+                        title: eventName,
+                        label: eventName ?? eventSlug ?? 'UFC event',
+                        startTime: eventStart,
+                        eventName,
+                        eventId,
+                        eventSlug,
+                        status: pickString(er.status) ?? 'upcoming',
+                    });
+                }
+            }
+            rows = expanded;
+            // Client-side hours / from / to window (API list has no hours param)
+            const now = Date.now();
+            const fromMs = from ? Date.parse(from) : now;
+            const toMs = to
+                ? Date.parse(to)
+                : args.hours !== undefined || !from
+                    ? now + hours * 3600_000
+                    : Number.POSITIVE_INFINITY;
+            if (Number.isFinite(fromMs) && Number.isFinite(toMs)) {
+                const before = rows.length;
+                rows = rows.filter((row) => {
+                    const r = asRecord(row) ?? {};
+                    const ts = pickString(r.startTime, r.date, r.startsAt, r.scheduledAt);
+                    if (!ts)
+                        return true; // keep undated rows rather than drop whole card
+                    const t = Date.parse(ts);
+                    if (!Number.isFinite(t))
+                        return true;
+                    return t >= fromMs && t <= toMs;
+                });
+                if (before > 0 && rows.length === 0) {
+                    warnings.push(`hours/from/to window matched 0 of ${before} UFC rows — widen hours or omit time filters`);
+                }
+            }
+        }
+        // Client-side team filter when API ignored it
+        if (team && (game === 'dota2' || game === 'cs2')) {
+            const t = team.toLowerCase();
+            rows = rows.filter((row) => {
+                const m = normalizeMatch(game, row, 'upcoming');
+                const hay = [m.team1?.id, m.team1?.slug, m.team1?.name, m.team2?.id, m.team2?.slug, m.team2?.name]
+                    .filter(Boolean)
+                    .join(' ')
+                    .toLowerCase();
+                return hay.includes(t);
+            });
+        }
+        const items = rows.slice(0, limit).map((row) => normalizeMatch(game, row, 'upcoming'));
+        const obj = asRecord(res.data);
+        const total = typeof obj?.total === 'number' ? obj.total : null;
+        const hasMore = (typeof obj?.hasMore === 'boolean' ? obj.hasMore : items.length >= limit) ||
+            (total != null && offset + items.length < total);
+        return successEnvelope({
+            source: 'upcoming_schedule',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            warnings: warnings.length ? warnings : undefined,
+            pagination: {
+                limit,
+                offset,
+                total,
+                hasMore,
+                nextCursor: hasMore ? encodeCursor({ offset: offset + limit }) : null,
+                prevCursor: offset > 0 ? encodeCursor({ offset: Math.max(0, offset - limit) }) : null,
+            },
+            data: { items },
+        });
+    },
+};
+export const liveTools = [liveMatches, upcomingSchedule];