cito-mcp 0.3.21 → 0.4.1

package/dist/tools/normalize.js

@@ -62,6 +62,138 @@ function numOrNull(v) {
         return Number(v);
     return null;
 }
+/**
+ * One set of a tennis score string ("6-4", "7-6(6)", "6-4, 3-6") as games won.
+ *
+ * A tiebreak is parenthesised after the games ("7-6(6)"), so the regex stops at
+ * the games. Anything else returns null rather than a guess: retirement rows
+ * carry "6-3 2-1 RET", and reading "RET" as games would invent a set.
+ */
+export function parseTennisSetToken(token) {
+    const m = /^\s*(\d{1,2})\s*-\s*(\d{1,2})/.exec(token);
+    if (!m)
+        return null;
+    return { p1: Number(m[1]), p2: Number(m[2]) };
+}
+/**
+ * Sets won by one side, counted from the match-level game score
+ * ("4-6 6-3 6-3 7-5" → 3 for side 1, 1 for side 2).
+ *
+ * `score` orders every token as player1-player2 on this feed, which is verified
+ * against the same row's sets[] (set 1: score token "4-6", player1_games 4,
+ * player2_games 6). Ties are impossible in a completed set, so a token where
+ * neither side is ahead contributes to neither total.
+ */
+export function tennisSetsWonFromScore(score, side) {
+    if (!score)
+        return null;
+    let won = 0;
+    let parsed = 0;
+    for (const token of score.split(/[\s,]+/)) {
+        if (!token)
+            continue;
+        const set = parseTennisSetToken(token);
+        if (!set)
+            continue;
+        parsed += 1;
+        const mine = side === 1 ? set.p1 : set.p2;
+        const theirs = side === 1 ? set.p2 : set.p1;
+        if (mine > theirs)
+            won += 1;
+    }
+    return parsed > 0 ? won : null;
+}
+/**
+ * Sets won by one side, counted from the structured sets[] array.
+ *
+ * player1_games/player2_games are the ONLY side-correct pair here. The sibling
+ * winner_games/loser_games are oriented to the match winner, not to side 1 —
+ * on s365_2026_4849786 set 1 is `winner_games: 4, loser_games: 6` while side 1
+ * (the winner, Shelton) actually lost that set 4-6. Reading those would have
+ * produced a confidently wrong 1-3 scoreline.
+ */
+export function tennisSetsWonFromSets(sets, side) {
+    if (!Array.isArray(sets) || sets.length === 0)
+        return null;
+    let won = 0;
+    let parsed = 0;
+    for (const raw of sets) {
+        const s = asRecord(raw);
+        if (!s)
+            continue;
+        const p1 = numOrNull(s.player1_games);
+        const p2 = numOrNull(s.player2_games);
+        if (p1 === null || p2 === null)
+            continue;
+        parsed += 1;
+        const mine = side === 1 ? p1 : p2;
+        const theirs = side === 1 ? p2 : p1;
+        if (mine > theirs)
+            won += 1;
+    }
+    return parsed > 0 ? won : null;
+}
+/**
+ * Whether a set row is finished.
+ *
+ * The live route states `is_completed`; the archive route omits the key
+ * entirely, and reading only the flag marked all four sets of a COMPLETED US
+ * Open semi-final `completed: false`. When the flag is absent the games decide:
+ * a set is over at 6-x with a two-game margin, or at 7-6/7-5.
+ */
+export function tennisSetCompleted(sr) {
+    if (typeof sr.is_completed === 'boolean')
+        return sr.is_completed;
+    const p1 = numOrNull(sr.player1_games);
+    const p2 = numOrNull(sr.player2_games);
+    if (p1 === null || p2 === null)
+        return false;
+    const hi = Math.max(p1, p2);
+    const lo = Math.min(p1, p2);
+    return (hi >= 6 && hi - lo >= 2) || (hi === 7 && lo === 6);
+}
+/**
+ * Sets won by one side of a tennis match, from whichever spelling the row uses.
+ *
+ * Four sources exist because three different endpoints describe the same match:
+ *   1. `sets_won`            — the live route puts it on each player object
+ *   2. `winner_sets_won`/`loser_sets_won` — the archive route's own totals
+ *   3. `sets[]`              — per-set games, present on both
+ *   4. the `score` string    — "4-6 6-3 6-3 7-5", present on both
+ *
+ * The archive route (`/tennis/matches/{id}`) carries NO sets_won on its player
+ * objects at all, which is why a completed US Open semi-final rendered as
+ * "Ben Shelton - : - Frances Tiafoe" while the same response held the real
+ * score in `score` and in `sets[]`. Reading only source 1 is the bug; the order
+ * above is authority, not preference — a server-computed total beats a count we
+ * derive, and the structured array beats re-parsing a display string.
+ */
+export function tennisSetsWon(opts) {
+    const explicit = numOrNull(opts.sideSetsWon);
+    if (explicit !== null)
+        return explicit;
+    // winner_sets_won / loser_sets_won belong to a side, and which side is known
+    // either from the row's own is_winner flag or by matching ids. Without one of
+    // those signals the pair is unusable and the structured sets below are safer
+    // than a coin flip.
+    const wsw = numOrNull(opts.winnerSetsWon);
+    const lsw = numOrNull(opts.loserSetsWon);
+    if (wsw !== null && lsw !== null) {
+        let isWinner = opts.isWinner;
+        if (isWinner === null || isWinner === undefined) {
+            if (opts.winnerId && opts.sideId)
+                isWinner = opts.winnerId === opts.sideId;
+        }
+        if (isWinner === true)
+            return wsw;
+        if (isWinner === false)
+            return lsw;
+    }
+    const fromSets = tennisSetsWonFromSets(Array.isArray(opts.sets) ? opts.sets : [], opts.side);
+    if (fromSets !== null)
+        return fromSets;
+    return tennisSetsWonFromScore(opts.score ?? undefined, opts.side);
+}
 /**
  * Collect image URLs from a corner/team row and its nested profile. Returns
  * undefined when the upstream carried none, so lean rows stay lean; when any
@@ -82,9 +214,11 @@ function imagesFrom(game, ...sources) {
         return null;
     };
     const images = {
-        headshotUrl: pick('headshotUrl', 'headshot'),
+        // portrait_url is the tennis feed's only likeness (see identityFrom in
+        // player.ts); without it a tennis side on every board carried no image.
+        headshotUrl: pick('headshotUrl', 'headshot', 'portrait_url'),
         bodyImageUrl: pick('bodyImageUrl', 'fullBodyImageUrl'),
-        imageUrl: pick('imageUrl', 'image', 'photoUrl', 'logoUrl', 'logo'),
+        imageUrl: pick('imageUrl', 'image', 'photoUrl', 'logoUrl', 'logo', 'portrait_url'),
         proxiedImageUrl: pick('proxiedImageUrl', 'proxiedHeadshotUrl'),
     };
     if (!images.proxiedImageUrl) {
@@ -125,7 +259,9 @@ function sideExtras(o, game) {
     const rank = pickString(o.rankText, o.rank, profile?.rankText);
     const championStatus = pickString(o.championStatus, profile?.championStatus);
     const division = pickString(profile?.division, o.division, o.weightClass);
-    const country = pickString(o.country, profile?.country);
+    // `ioc` is the tennis feed's country code ("ESP"); it was not read, so every
+    // tennis side on every board came back country-less.
+    const country = pickString(o.country, profile?.country, o.ioc);
     const flag = pickString(o.flag, profile?.flag);
     const outcome = pickString(o.outcome);
     return {
@@ -238,11 +374,38 @@ export function normalizeMatch(game, row, forcedStatus) {
         const p2obj = asRecord(r.player2);
         const p1 = pickString(p1obj?.name, r.player1_name);
         const p2 = pickString(p2obj?.name, r.player2_name);
+        // winner_sets_won/loser_sets_won and score/sets are match-level; only the
+        // side flags differ, so they are shared by both branches below.
+        const scoreText = pickString(r.score, r.score_raw) ?? null;
         if (p1 || p2) {
-            const score1 = typeof p1obj?.sets_won === 'number' ? p1obj.sets_won : undefined;
-            const score2 = typeof p2obj?.sets_won === 'number' ? p2obj.sets_won : undefined;
-            team1 = sideFrom(p1, pickString(p1obj?.id, r.player1_id), undefined, score1);
-            team2 = sideFrom(p2, pickString(p2obj?.id, r.player2_id), undefined, score2);
+            const p1Id = pickString(p1obj?.id, r.player1_id) ?? null;
+            const p2Id = pickString(p2obj?.id, r.player2_id) ?? null;
+            const winnerId = pickString(r.winner_id) ?? null;
+            const boolOrNull = (v) => (typeof v === 'boolean' ? v : null);
+            const score1 = tennisSetsWon({
+                sideSetsWon: p1obj?.sets_won,
+                winnerSetsWon: r.winner_sets_won,
+                loserSetsWon: r.loser_sets_won,
+                isWinner: boolOrNull(p1obj?.is_winner),
+                winnerId,
+                sideId: p1Id,
+                sets: r.sets,
+                score: scoreText,
+                side: 1,
+            });
+            const score2 = tennisSetsWon({
+                sideSetsWon: p2obj?.sets_won,
+                winnerSetsWon: r.winner_sets_won,
+                loserSetsWon: r.loser_sets_won,
+                isWinner: boolOrNull(p2obj?.is_winner),
+                winnerId,
+                sideId: p2Id,
+                sets: r.sets,
+                score: scoreText,
+                side: 2,
+            });
+            team1 = sideFrom(p1, p1Id ?? undefined, undefined, score1, sideExtras(p1obj ?? {}, game));
+            team2 = sideFrom(p2, p2Id ?? undefined, undefined, score2, sideExtras(p2obj ?? {}, game));
         }
         else {
             // Archive detail nests winner/loser objects with real names; list rows
@@ -254,8 +417,25 @@ export function normalizeMatch(game, row, forcedStatus) {
             const wId = pickString(wObj?.id, r.winner_id);
             const lId = pickString(lObj?.id, r.loser_id);
             if (wName || lName || wId || lId) {
-                team1 = sideFrom(wName ?? wId, wId, undefined, undefined);
-                team2 = sideFrom(lName ?? lId, lId, undefined, undefined);
+                // This shape IS winner-first, so side 1 is the winner by construction.
+                const wScore = tennisSetsWon({
+                    winnerSetsWon: r.winner_sets_won,
+                    loserSetsWon: r.loser_sets_won,
+                    isWinner: true,
+                    sets: r.sets,
+                    score: scoreText,
+                    side: 1,
+                });
+                const lScore = tennisSetsWon({
+                    winnerSetsWon: r.winner_sets_won,
+                    loserSetsWon: r.loser_sets_won,
+                    isWinner: false,
+                    sets: r.sets,
+                    score: scoreText,
+                    side: 2,
+                });
+                team1 = sideFrom(wName ?? wId, wId, undefined, wScore);
+                team2 = sideFrom(lName ?? lId, lId, undefined, lScore);
             }
         }
     }
@@ -440,9 +620,21 @@ export function normalizeMatch(game, row, forcedStatus) {
         ? undefined
         : explicitRaw;
     const explicitIsPlaceholder = explicit != null && /^\?\s*vs\s*\?$/i.test(explicit.trim());
+    // Tennis rows carry no `label`, but the live route does set `name` — and that
+    // name is the TOURNAMENT ("Challenger, Seville"), not the matchup. Preferring
+    // it made live_matches label a tennis row by its event while
+    // upcoming_schedule, off a route with no such field, labelled the same
+    // fixture "Max Alcala Gurri vs Dusan Lajovic". Two boards, one match, two
+    // labels. A "matchup" that is really an event name is not a matchup.
+    const explicitIsEventName = explicit != null &&
+        game === 'tennis' &&
+        Boolean(team1?.name || team2?.name) &&
+        [eventName, eventSlug, r.tournament_name, r.tournament]
+            .filter((v) => typeof v === 'string' && v.length > 0)
+            .some((v) => v.trim().toLowerCase() === explicit.trim().toLowerCase());
     const weightOrClass = pickString(r.weightClass, r.division, r.weight_class, r.boutClass);
     let label;
-    if (explicit && !explicitIsPlaceholder) {
+    if (explicit && !explicitIsPlaceholder && !explicitIsEventName) {
         label = explicit;
     }
     else if (team1?.name || team2?.name) {
@@ -483,12 +675,19 @@ export function normalizeMatch(game, row, forcedStatus) {
     if (game === 'tennis' && Array.isArray(r.sets) && r.sets.length) {
         tennisSets = r.sets.map((s) => {
             const sr = asRecord(s) ?? {};
+            const p1g = numOrNull(sr.player1_games);
+            const p2g = numOrNull(sr.player2_games);
             return {
-                setNumber: numOrNull(sr.set_num),
-                player1Games: numOrNull(sr.player1_games),
-                player2Games: numOrNull(sr.player2_games),
+                // The live route spells it set_num; the archive route set_number. Both
+                // are emitted by the same API for the same set.
+                setNumber: numOrNull(sr.set_num) ?? numOrNull(sr.set_number),
+                score: pickString(sr.score) ?? (p1g !== null && p2g !== null ? `${p1g}-${p2g}` : null),
+                player1Games: p1g,
+                player2Games: p2g,
                 tiebreak: sr.tiebreak == null ? null : (pickString(sr.tiebreak) ?? String(sr.tiebreak)),
-                completed: sr.is_completed === true,
+                // is_completed is a live-route field only; the archive route omits it
+                // and every set of a finished match read as completed:false.
+                completed: tennisSetCompleted(sr),
             };
         });
         tennisGameScore = pickString(r.game_score) ?? null;
@@ -624,7 +823,14 @@ export function rankScore(query, name, id, slug, ...extra) {
                 best = Math.max(best, 92); // "jon jones" vs "Jon Jones"
             }
             else {
-                const hits = qt.filter((t) => ct.some((x) => x.includes(t) || t.includes(x))).length;
+                // A hit is the candidate token containing the query token, or the query
+                // token containing a candidate token OF REAL LENGTH. The reverse
+                // direction used to accept any length, so the single letter "e" in
+                // "E Skinner" counted as a hit against the query "sinner" ("sinner"
+                // contains "e") and scored 32 — which is how eight strangers padded a
+                // search for one player. A one- or two-character fragment carries no
+                // identity, so it no longer counts.
+                const hits = qt.filter((t) => ct.some((x) => x.includes(t) || (t.includes(x) && x.length >= 3))).length;
                 if (hits === qt.length && qt.length > 0)
                     best = Math.max(best, 75);
                 else if (hits)

package/dist/tools/odds.js

@@ -0,0 +1,295 @@
+/**
+ * tennis_odds — the betting-odds surface for tennis (TENNIS-24).
+ *
+ * WHY THIS EXISTS
+ * The tennis API serves three odds routes, and NONE of them had a tool. Odds are
+ * a headline feature of the paid tiers and one of the most common reasons to buy
+ * a sports API, so a builder had to discover /tennis/odds/* through call_api or
+ * the docs. This closes that gap.
+ *
+ * Coverage is genuinely partial upstream, and the tool says so rather than
+ * returning an empty success: /tennis/odds/{id} answers with
+ * `coverage: { odds: false }` and an empty bookmakers[] for any match the feed
+ * has no prices for (verified against atp_2026_560, which returned exactly
+ * that). An agent that cannot tell "no odds exist for this match" from "the call
+ * failed" will invent a price, so the response distinguishes the two.
+ */
+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';
+/** A bookmaker row: { key, title, last_update, markets: [{ key, outcomes: [{ name, price }] }] }. */
+function normalizeBookmaker(row) {
+    const r = asRecord(row) ?? {};
+    const markets = (Array.isArray(r.markets) ? r.markets : []).map((mk) => {
+        const m = asRecord(mk) ?? {};
+        const outcomes = (Array.isArray(m.outcomes) ? m.outcomes : []).map((o) => {
+            const oc = asRecord(o) ?? {};
+            return {
+                name: pickString(oc.name) ?? null,
+                // Decimal odds as the feed supplies them; never recomputed or implied.
+                price: typeof oc.price === 'number' && Number.isFinite(oc.price) ? oc.price : null,
+                point: typeof oc.point === 'number' && Number.isFinite(oc.point) ? oc.point : null,
+            };
+        });
+        return {
+            market: pickString(m.key) ?? null,
+            outcomes,
+            // Implied probability from the prices actually returned, so a caller does
+            // not have to redo the arithmetic. Null when any price is missing.
+            impliedProbabilities: (() => {
+                const prices = outcomes.map((o) => o.price).filter((p) => p !== null && p > 1);
+                if (prices.length !== outcomes.length || prices.length === 0)
+                    return null;
+                const inv = prices.map((p) => 1 / p);
+                const sum = inv.reduce((a, b) => a + b, 0);
+                return inv.map((v) => Number((v / sum).toFixed(4)));
+            })(),
+        };
+    });
+    return {
+        key: pickString(r.key) ?? null,
+        title: pickString(r.title) ?? null,
+        lastUpdate: pickString(r.last_update) ?? null,
+        markets,
+    };
+}
+/**
+ * The one tennis-odds projection, shared by `tennis_odds` and `match_details`.
+ *
+ * Both surfaces read the same REST payload, and before this the two disagreed:
+ * `tennis_odds scope=match` served FanDuel 1.105 / Matchbook 1.13 with implied
+ * probabilities while `match_details sections:["odds"]` answered
+ * NOT_IMPLEMENTED "UFC only today" for the same match id. A caller could not
+ * tell whether tennis odds existed. One shaper, one answer.
+ */
+export function summarizeTennisOdds(data) {
+    const root = asRecord(data) ?? {};
+    // fetchJson hands back the whole REST envelope; the unit tests feed the inner
+    // object directly. Accept both.
+    const payload = asRecord(root.data) ?? root;
+    const coverage = asRecord(payload.coverage) ?? {};
+    const bookmakers = (Array.isArray(payload.bookmakers) ? payload.bookmakers : []).map(normalizeBookmaker);
+    const hasOdds = coverage.odds === true || bookmakers.length > 0;
+    return {
+        matchId: pickString(payload.match_id) ?? null,
+        oddsFormat: pickString(payload.odds_format) ?? 'decimal',
+        commenceTime: pickString(payload.commence_time) ?? null,
+        /** Upstream says the feed has since moved on; the prices are still real. */
+        stale: payload.stale === true,
+        bookmakers,
+        // Explicit, because an empty bookmakers[] is otherwise indistinguishable
+        // from a failed scrape.
+        oddsAvailable: hasOdds,
+        note: hasOdds
+            ? null
+            : 'No bookmaker is currently quoting this match. This is an upstream coverage gap, not an error; retry closer to the start time.',
+        fullBookPath: '/tennis/odds/{matchId}',
+    };
+}
+function parseTennis(args, tool) {
+    const gameParse = parseGame(args.game, { allowAll: false, required: true });
+    if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+        return { error: gameParse.error ?? 'game is required', game: null };
+    }
+    const game = gameParse.game;
+    if (game !== 'tennis') {
+        return {
+            error: `${tool} is tennis-only (odds for '${game}' is not served by this endpoint)`,
+            game,
+        };
+    }
+    return { game };
+}
+function requireTennisId(args, tool) {
+    const id = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+    if (!id)
+        return { error: `${tool} requires matchId` };
+    return { matchId: id };
+}
+export const tennisOdds = {
+    name: 'tennis_odds',
+    description: `Tennis betting odds: upcoming matches with prices, plus pre-match and in-play odds for one match.
+
+Modes (pick with 'scope'):
+- upcoming (default): matches with odds available, each with the bookmakers quoting it.
+- match: pre-match odds for one match_id.
+- live: in-play odds for one match_id.
+
+When to use:
+- "What are the odds on X vs Y?"; pre-match prices; in-play prices; which matches have odds today.
+
+Prefer over: call_api for /tennis/odds/*; match_preview (no prices).
+
+Do not use when: the match result → match_details; rankings → standings.
+
+Tennis-only. Odds are decimal. Coverage is partial upstream: a match with no
+priced bookmaker returns coverage.odds=false and an empty bookmakers[] rather
+than invented numbers, and this tool surfaces that distinction explicitly.
+
+Parallel-safe: yes. Upstream cost: 1.`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            scope: stringSchema('upcoming (default) | match | live.', 'upcoming'),
+            matchId: stringSchema('Match id for scope=match or scope=live, e.g. "s365_2026_4853596".', 's365_2026_4853596'),
+            limit: limitSchema({ default: 20, max: 50, description: 'Rows for scope=upcoming (default 20, max 50).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const parsed = parseTennis(args, 'tennis_odds');
+        if (parsed.error) {
+            return errorEnvelope({
+                code: parsed.error.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: parsed.error,
+                game: parsed.game,
+                source: 'tennis_odds',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = parsed.game;
+        const scopeRaw = typeof args.scope === 'string' ? args.scope.trim().toLowerCase() : 'upcoming';
+        if (!['upcoming', 'match', 'live'].includes(scopeRaw)) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `scope must be upcoming, match, or live (got '${args.scope}')`,
+                game,
+                source: 'tennis_odds',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: ['Use scope=upcoming for matches with odds', 'Use scope=match or scope=live with a matchId'],
+            });
+        }
+        const matchId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        if (scopeRaw !== 'upcoming' && !matchId) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: `matchId is required when scope=${scopeRaw}`,
+                game,
+                source: 'tennis_odds',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [`Pass matchId, or use scope=upcoming with no id`],
+            });
+        }
+        const limit = clampInt(args.limit, 20, 1, 50);
+        if (scopeRaw === 'upcoming') {
+            const res = await fetchJson(ctx, '/tennis/odds/upcoming', { query: { limit } });
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `Upcoming tennis odds failed (HTTP ${res.status})`,
+                    game,
+                    source: 'tennis_odds',
+                    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((row) => {
+                const r = asRecord(row) ?? {};
+                const home = asRecord(r.home) ?? {};
+                const away = asRecord(r.away) ?? {};
+                const homeId = pickString(home.player_id, home.id) ?? null;
+                const awayId = pickString(away.player_id, away.id) ?? null;
+                const matchId = pickString(r.match_id, r.id) ?? null;
+                const oddsEventId = pickString(r.odds_event_id) ?? null;
+                return {
+                    matchId,
+                    oddsEventId,
+                    tournament: pickString(r.tournament) ?? null,
+                    commenceTime: pickString(r.commence_time, r.starts_at) ?? null,
+                    player1: { name: pickString(home.name) ?? null, id: homeId },
+                    player2: { name: pickString(away.name) ?? null, id: awayId },
+                    bookmakers: Array.isArray(r.bookmakers) ? r.bookmakers.map((b) => pickString(b) ?? null) : [],
+                    live: r.live === true,
+                    /**
+                     * The feed does not join its odds events to matches: every row of
+                     * /tennis/odds/upcoming carries match_id:null (verified on all 94
+                     * rows), so a caller could not go odds -> match and the two halves of
+                     * a betting UI could not be stitched together. matchId itself is left
+                     * exactly as the feed states it — null stays null, because inventing
+                     * one would be worse — and the join key that DOES resolve is named
+                     * alongside it.
+                     */
+                    joinKey: matchId
+                        ? { kind: 'matchId', matchId }
+                        : oddsEventId
+                            ? { kind: 'oddsEventId', oddsEventId }
+                            : null,
+                    /** Player ids present on the row, which identify the fixture when matchId is null. */
+                    playerIds: [homeId, awayId].filter((x) => Boolean(x)),
+                };
+            });
+            const total = typeof body.total === 'number' ? body.total : items.length;
+            return successEnvelope({
+                pagination: {
+                    limit,
+                    offset: 0,
+                    total,
+                    hasMore: body.has_next === true,
+                    nextCursor: null,
+                    prevCursor: null,
+                },
+                source: 'tennis_odds',
+                game,
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                rateLimit: res.headers,
+                data: {
+                    title: `Tennis odds — upcoming (${items.length} of ${total})`,
+                    scope: scopeRaw,
+                    oddsFormat: 'decimal',
+                    items,
+                    total,
+                },
+            });
+        }
+        const path = scopeRaw === 'match'
+            ? `/tennis/odds/${encodeURIComponent(matchId)}`
+            : `/tennis/odds/${encodeURIComponent(matchId)}/live`;
+        const res = await fetchJson(ctx, path, {});
+        if (!res.ok) {
+            return errorEnvelope({
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `Tennis ${scopeRaw} odds failed for '${matchId}' (HTTP ${res.status})`,
+                game,
+                source: 'tennis_odds',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls: 1,
+                httpStatus: res.status,
+                rateLimit: res.headers,
+                recover: ['Check the match id with live_matches or match_details'],
+            });
+        }
+        const summary = summarizeTennisOdds(res.data);
+        return successEnvelope({
+            source: 'tennis_odds',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls: 1,
+            rateLimit: res.headers,
+            data: {
+                title: `Tennis ${scopeRaw} odds — ${matchId}`,
+                scope: scopeRaw,
+                // One projection, the same object match_details sections:["odds"]
+                // returns. See summarizeTennisOdds.
+                ...summary,
+                matchId: summary.matchId ?? matchId,
+            },
+        });
+    },
+};
+export const oddsTools = [tennisOdds];