cito-mcp 0.3.20 → 0.4.0

package/dist/tools/leaderboard.js

@@ -0,0 +1,427 @@
+/**
+ * leaderboard_aces (TENNIS-18 follow-up).
+ *
+ * Tennis-only: season aces leaderboard from real match_stats aggregates
+ * (GET /tennis/leaderboards/aces). Upstream shape (verified 2026-09-09):
+ * { season, tour, stat: 'aces', items: [{ player_id, full_name, aces, matches }], total }.
+ * Upstream defaults: season=2026, tour=null (both tours combined), and it
+ * 422s on a bad tour or a non-year season — both surface as VALIDATION here.
+ */
+import { asRecord, clampInt, fetchJson, gameNotIncludedHint, pickString, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
+import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
+const DEFAULT_SEASON = 2026;
+const MIN_SEASON = 1968;
+const MAX_SEASON = 2100;
+function parseOptionalTour(args) {
+    const rawTour = typeof args.tour === 'string' ? args.tour.trim() : '';
+    const rawDivision = typeof args.division === 'string' ? args.division.trim() : '';
+    if (rawTour && rawDivision && rawTour.toUpperCase() !== rawDivision.toUpperCase()) {
+        return { error: `tour ('${rawTour}') and division ('${rawDivision}') disagree; pass one of ATP|WTA` };
+    }
+    const raw = rawTour || rawDivision;
+    if (!raw)
+        return {};
+    const upper = raw.toUpperCase();
+    if (upper !== 'ATP' && upper !== 'WTA') {
+        return { error: `tour must be ATP or WTA (got '${raw}')` };
+    }
+    return { tour: upper };
+}
+function parseSeason(args) {
+    const raw = args.season;
+    if (raw === undefined || raw === null || (typeof raw === 'string' && raw.trim() === '')) {
+        return { season: DEFAULT_SEASON };
+    }
+    const num = typeof raw === 'number' ? raw : Number(String(raw).trim());
+    if (!Number.isInteger(num) || num < MIN_SEASON || num > MAX_SEASON) {
+        return { error: `season must be a YYYY year ${MIN_SEASON}-${MAX_SEASON} (got '${String(raw)}')` };
+    }
+    return { season: num };
+}
+function normalizeAceRow(row) {
+    const r = asRecord(row) ?? {};
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    return {
+        playerId: pickString(r.player_id) ?? null,
+        playerName: pickString(r.full_name, r.player_name) ?? null,
+        aces: num(r.aces),
+        matches: num(r.matches),
+    };
+}
+export const leaderboardAces = {
+    name: 'leaderboard_aces',
+    description: `Tennis season aces leaderboard: most aces served in a season, from real match-stats aggregates.
+
+When to use:
+- Who leads the tour in aces this season; season serving-leader tables.
+
+Prefer over: raw leaderboard via call_api for agent-normalized rows.
+
+Do not use when: ranking position → standings with game tennis; week-over-week movement → rankings_movers; one player's recent form → player_form.
+
+Tennis-only. Season defaults to 2026; tour (ATP|WTA) is optional — omit it for the combined board. Rows carry aces + matches played, ordered most aces first.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            tour: stringSchema('ATP or WTA tour; omit for the combined board. Synonym: division.', 'WTA'),
+            division: stringSchema('Synonym for tour (ATP or WTA), matching the standings tool spelling.'),
+            season: {
+                type: 'integer',
+                minimum: MIN_SEASON,
+                maximum: MAX_SEASON,
+                default: DEFAULT_SEASON,
+                description: 'Season year (YYYY). Default 2026.',
+            },
+            limit: limitSchema({ default: 10, max: 100 }),
+        },
+    },
+    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: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game !== 'tennis') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: `leaderboard_aces is tennis-only (game '${game}' has no aces leaderboard)`,
+                game,
+                source: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use standings for the latest snapshot of this game',
+                    'Retry leaderboard_aces with game tennis and an optional tour ATP|WTA',
+                ],
+            });
+        }
+        const tourParse = parseOptionalTour(args);
+        if (tourParse.error) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: tourParse.error,
+                game,
+                source: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const seasonParse = parseSeason(args);
+        if (seasonParse.error || seasonParse.season === undefined) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: seasonParse.error ?? 'season is invalid',
+                game,
+                source: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const limit = clampInt(args.limit, 10, 1, 100);
+        const res = await fetchJson(ctx, '/tennis/leaderboards/aces', {
+            query: {
+                season: seasonParse.season,
+                limit,
+                ...(tourParse.tour ? { tour: tourParse.tour } : {}),
+            },
+        });
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Aces leaderboard failed (HTTP ${res.status})`,
+                game,
+                source: 'leaderboard_aces',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+            });
+        }
+        const root = asRecord(res.data);
+        const body = asRecord(root?.data) ?? root ?? {};
+        const items = (Array.isArray(body.items) ? body.items : []).map(normalizeAceRow);
+        const total = typeof body.total === 'number' ? body.total : items.length;
+        return successEnvelope({
+            pagination: {
+                limit,
+                offset: 0,
+                total,
+                hasMore: false,
+                nextCursor: null,
+                prevCursor: null,
+            },
+            source: 'leaderboard_aces',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            data: {
+                title: `${tourParse.tour ?? 'Combined'} aces leaderboard ${seasonParse.season}`,
+                season: typeof body.season === 'number' ? body.season : seasonParse.season,
+                tour: pickString(body.tour) ?? tourParse.tour ?? null,
+                stat: pickString(body.stat) ?? 'aces',
+                items,
+                total,
+            },
+        });
+    },
+};
+function normalizePctRow(numKey, denKey) {
+    return (row) => {
+        const r = asRecord(row) ?? {};
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+        return {
+            playerId: pickString(r.player_id) ?? null,
+            playerName: pickString(r.full_name, r.player_name) ?? null,
+            attempts: num(r[numKey]),
+            total: num(r[denKey]),
+            pct: num(r.pct),
+            matches: num(r.matches),
+        };
+    };
+}
+function makePctLeaderboardTool(spec) {
+    const normalizeRow = normalizePctRow(spec.numKey, spec.denKey);
+    return {
+        name: spec.name,
+        description: `Tennis season ${spec.titleNoun} leaderboard: ${spec.blurb}
+
+When to use:
+- ${spec.blurb} season tables; clutch/serve-efficiency leader queries.
+
+Prefer over: raw leaderboard via call_api for agent-normalized rows.
+
+Do not use when: ranking position → standings with game tennis; week-over-week movement → rankings_movers; one player's recent form → player_form.
+
+Tennis-only. Season defaults to 2026; tour (ATP|WTA) is optional — omit it for the combined board. ${spec.minAttemptsNote}
+
+Parallel-safe: yes. Upstream cost: 1.`,
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['game'],
+            properties: {
+                game: gameSchema({ allowAll: false, required: true }),
+                tour: stringSchema('ATP or WTA tour; omit for the combined board. Synonym: division.', 'WTA'),
+                division: stringSchema('Synonym for tour (ATP or WTA), matching the standings tool spelling.'),
+                season: {
+                    type: 'integer',
+                    minimum: MIN_SEASON,
+                    maximum: MAX_SEASON,
+                    default: DEFAULT_SEASON,
+                    description: 'Season year (YYYY). Default 2026.',
+                },
+                limit: limitSchema({ default: 10, max: 100 }),
+            },
+        },
+        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: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            const game = gameParse.game;
+            if (game !== 'tennis') {
+                return errorEnvelope({
+                    code: 'NOT_IMPLEMENTED',
+                    message: `${spec.name} is tennis-only (game '${game}' has no ${spec.titleNoun} leaderboard)`,
+                    game,
+                    source: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                    recover: [
+                        'Use standings for the latest snapshot of this game',
+                        `Retry ${spec.name} with game tennis and an optional tour ATP|WTA`,
+                    ],
+                });
+            }
+            const tourParse = parseOptionalTour(args);
+            if (tourParse.error) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: tourParse.error,
+                    game,
+                    source: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            const seasonParse = parseSeason(args);
+            if (seasonParse.error || seasonParse.season === undefined) {
+                return errorEnvelope({
+                    code: 'VALIDATION',
+                    message: seasonParse.error ?? 'season is invalid',
+                    game,
+                    source: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                });
+            }
+            const limit = clampInt(args.limit, 10, 1, 100);
+            const res = await fetchJson(ctx, `/tennis${spec.path}`, {
+                query: {
+                    season: seasonParse.season,
+                    limit,
+                    ...(tourParse.tour ? { tour: tourParse.tour } : {}),
+                },
+            });
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `${spec.titleNoun} leaderboard failed (HTTP ${res.status})`,
+                    game,
+                    source: spec.name,
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls: 1,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            const root = asRecord(res.data);
+            const body = asRecord(root?.data) ?? root ?? {};
+            const items = (Array.isArray(body.items) ? body.items : []).map(normalizeRow);
+            const total = typeof body.total === 'number' ? body.total : items.length;
+            return successEnvelope({
+                pagination: {
+                    limit,
+                    offset: 0,
+                    total,
+                    hasMore: false,
+                    nextCursor: null,
+                    prevCursor: null,
+                },
+                source: spec.name,
+                game,
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                rateLimit: res.headers,
+                data: {
+                    title: `${tourParse.tour ?? 'Combined'} ${spec.titleNoun} leaderboard ${seasonParse.season}`,
+                    season: typeof body.season === 'number' ? body.season : seasonParse.season,
+                    tour: pickString(body.tour) ?? tourParse.tour ?? null,
+                    stat: pickString(body.stat) ?? spec.stat,
+                    items,
+                    total,
+                },
+            });
+        },
+    };
+}
+export const leaderboardBreakPointsSaved = makePctLeaderboardTool({
+    name: 'leaderboard_break_points_saved',
+    path: '/leaderboards/break-points-saved',
+    stat: 'break_points_saved',
+    numKey: 'break_points_saved',
+    denKey: 'break_points_faced',
+    titleNoun: 'break-points-saved',
+    blurb: 'Share of break points saved per player, from real match-stats aggregates, ordered highest pct first.',
+    minAttemptsNote: 'Only players facing at least 50 break points qualify.',
+});
+export const leaderboardFirstServeWon = makePctLeaderboardTool({
+    name: 'leaderboard_first_serve_won',
+    path: '/leaderboards/1st-serve-won',
+    stat: 'first_serve_won',
+    numKey: 'first_serve_points_won',
+    denKey: 'first_serves_in',
+    titleNoun: 'first-serve-won',
+    blurb: 'Share of first-serve points won per player, from real match-stats aggregates, ordered highest pct first.',
+    minAttemptsNote: 'Only players with at least 300 first serves in qualify.',
+});
+export const leaderboardTiebreakWinPct = makePctLeaderboardTool({
+    name: 'leaderboard_tiebreak_win_pct',
+    path: '/leaderboards/tiebreak-win-pct',
+    stat: 'tiebreak_win_pct',
+    numKey: 'tiebreaks_won',
+    denKey: 'tiebreaks_played',
+    titleNoun: 'tiebreak-win-pct',
+    blurb: 'Share of classic 7-point tiebreaks won per player, from real match-set aggregates, ordered highest pct first.',
+    minAttemptsNote: 'Only players contesting at least 10 tiebreaks qualify.',
+});
+export const leaderboardBreakConversion = makePctLeaderboardTool({
+    name: 'leaderboard_break_conversion',
+    path: '/leaderboards/break-conversion',
+    stat: 'break_conversion',
+    numKey: 'break_points_won',
+    denKey: 'break_opportunities',
+    titleNoun: 'break-conversion',
+    blurb: 'Share of break opportunities converted per player, from real match-stats aggregates read return-side, ordered highest pct first.',
+    minAttemptsNote: 'Only players with at least 50 break opportunities qualify.',
+});
+export const leaderboardReturnGamesWon = makePctLeaderboardTool({
+    name: 'leaderboard_return_games_won',
+    path: '/leaderboards/return-games-won',
+    stat: 'return_games_won',
+    numKey: 'return_games_won',
+    denKey: 'return_games_played',
+    titleNoun: 'return-games-won',
+    blurb: 'Share of return games won per player (breaks over opponent service games played), from real match-stats aggregates read return-side, ordered highest pct first.',
+    minAttemptsNote: 'Only players with at least 100 return games played qualify.',
+});
+export const leaderboardFinalsRecord = makePctLeaderboardTool({
+    name: 'leaderboard_finals_record',
+    path: '/leaderboards/finals-record',
+    stat: 'finals_record',
+    numKey: 'finals_won',
+    denKey: 'finals_played',
+    titleNoun: 'finals-record',
+    blurb: 'Share of finals won (titles clutch) per player, from real completed finals rows, ordered highest pct first.',
+    minAttemptsNote: 'Only players contesting at least 3 finals qualify.',
+});
+export const leaderboardComebackWins = makePctLeaderboardTool({
+    name: 'leaderboard_comeback_wins',
+    path: '/leaderboards/comeback-wins',
+    stat: 'comeback_wins',
+    numKey: 'comebacks_won',
+    denKey: 'matches_with_first_set',
+    titleNoun: 'comeback-wins',
+    blurb: 'Share of matches won after losing the first set per player, from real first-set rows joined to completed matches, ordered highest pct first.',
+    minAttemptsNote: 'Only players with first-set data on at least 20 matches qualify.',
+});
+export const leaderboardDecidingSetRecord = makePctLeaderboardTool({
+    name: 'leaderboard_deciding_set_record',
+    path: '/leaderboards/deciding-set-record',
+    stat: 'deciding_set_record',
+    numKey: 'deciders_won',
+    denKey: 'deciders_played',
+    titleNoun: 'deciding-set-record',
+    blurb: 'Share of deciding sets (full-length final sets) won per player, from real match rows, ordered highest pct first.',
+    minAttemptsNote: 'Only players contesting at least 10 deciders qualify.',
+});
+export const leaderboardTools = [
+    leaderboardAces,
+    leaderboardBreakPointsSaved,
+    leaderboardFirstServeWon,
+    leaderboardTiebreakWinPct,
+    leaderboardBreakConversion,
+    leaderboardReturnGamesWon,
+    leaderboardDecidingSetRecord,
+    leaderboardComebackWins,
+    leaderboardFinalsRecord,
+];