@claudinho/core 0.8.18 → 0.9.0

package/dist/index.d.ts

@@ -183,6 +183,54 @@ declare function isValidTimeZone(tz: string | undefined | null): boolean;
  */
 declare function isValidDate(s: string | undefined | null): boolean;
 
+/**
+ * Feed-string sanitizer — the chokepoint between untrusted provider data and
+ * every output surface (terminal, statusline, share cards, and the Claude Code
+ * hook, whose stdout lands in the model's context). Strips control characters
+ * (C0 incl. ESC, DEL, C1) so a compromised feed can't inject ANSI escapes or
+ * multi-line text, and caps length so one field can't flood a surface.
+ *
+ * Applied at the ESPN adapter boundary (toTeam / mapEspnEvent) and mirrored on
+ * the statusline's cache reads (defense against a poisoned cache file).
+ */
+
+/** Default per-field cap — generous for any real team/venue name. */
+declare const FEED_TEXT_MAX = 100;
+/**
+ * Strip C0/C1 control characters (including ESC) and cap at `max` code points.
+ * Whitespace controls (tab/newline/CR) become a single space so words a hostile
+ * feed split across lines don't fuse together. Total: never throws.
+ */
+declare function sanitizeFeedText(value: string, max?: number): string;
+/**
+ * Sanitized, display-safe copy of a Match. Used on cache reads (the
+ * statusline/hook render straight from the cache file), so it must be total:
+ * a malformed entry yields empty strings, never a throw. Beyond the string
+ * fields, the RENDERED numeric fields (score, shootout, minute) are dropped
+ * unless they are real finite numbers — poisoned values degrade to "vs" /
+ * "LIVE", never to injected text. Shootout never survives without its score
+ * (the adapter-level invariant, re-enforced here).
+ */
+declare function sanitizeMatchStrings(m: Match): Match;
+
+/**
+ * Display-width helpers for monospace/plain-text alignment.
+ *
+ * `String.prototype.padEnd` counts UTF-16 units, but emoji flags occupy 2
+ * terminal columns regardless of how many units encode them: a regional-
+ * indicator flag (🇲🇽) is 4 units, while a tag-sequence flag (England 🏴󠁧󠁢󠁥󠁮󠁧󠁿) is
+ * 14 — so unit-counted padding pushed England/Scotland rows ~10 columns out of
+ * line. These helpers count grapheme clusters, with pictographic clusters
+ * (flags included) as 2 columns, matching how terminals render them.
+ */
+/** Terminal display width of a string (grapheme clusters; emoji count as 2). */
+declare function displayWidth(s: string): number;
+/**
+ * Pad with trailing spaces to `width` DISPLAY columns (never truncates — a
+ * too-long value overflows its column rather than being cut mid-name).
+ */
+declare function padVisible(s: string, width: number): string;
+
 /** Outcome (home perspective) from a final/looking scoreline. */
 declare function outcomeFromScore(home: number, away: number): Outcome;
 /** Is the match currently in play (including halftime)? */
@@ -437,6 +485,18 @@ interface ProviderAdapter {
     fetchStandings?(): Promise<GroupStandings[]>;
     /** Optional push subscription (websocket/SSE providers). Returns an unsubscribe fn. */
     subscribe?(onBatch: (matches: Match[]) => void): () => void;
+    /**
+     * Optional: the most recent request failure, cleared when a new request
+     * starts (best-effort under concurrency). Lets a caller whose result path
+     * fails closed to `degraded` booleans still distinguish a throttle/block
+     * (`throttled` — persist a backoff, hammering makes it worse) from an
+     * ordinary blip (retry on the normal cadence).
+     */
+    readonly lastError?: {
+        readonly kind: string;
+        readonly status?: number;
+        readonly throttled?: boolean;
+    };
 }
 
 /**
@@ -455,6 +515,19 @@ interface ProviderAdapter {
 declare const DEFAULT_COMPETITION = "fifa.world";
 /** Build an ESPN soccer base URL for a competition slug (e.g. "fifa.friendly"). */
 declare function competitionBase(slug: string): string;
+type ProviderErrorKind = 'http' | 'timeout' | 'parse';
+/**
+ * Classified provider failure, so a caller that got a degraded result can tell
+ * a throttle/block (back off — hammering makes it worse) from a timeout or a
+ * shape change (plain degraded, retry on the normal cadence).
+ */
+declare class ProviderError extends Error {
+    readonly kind: ProviderErrorKind;
+    readonly status?: number;
+    constructor(message: string, kind: ProviderErrorKind, status?: number);
+    /** 429/403 — the upstream is refusing us; retrying at the live cadence makes it worse. */
+    get throttled(): boolean;
+}
 interface EspnStatusType {
     name?: string;
     state?: string;
@@ -560,6 +633,20 @@ declare class EspnAdapter implements ProviderAdapter {
     readonly capabilities: ProviderCapabilities;
     /** Cached team-code -> group-letter map (built lazily from standings). */
     private groupMap?;
+    /**
+     * One in-flight/recent standings fetch shared by fetchStandings and
+     * fetchGroupMap, so a command like `bracket` hits the endpoint once instead
+     * of twice, and a long-lived MCP server stays fresh (short TTL). A rejected
+     * fetch clears the slot — a transient failure is never cached.
+     */
+    private standingsShared?;
+    /**
+     * The most recent request failure (best-effort under concurrency; cleared
+     * when a new request starts). A post-hoc hint for callers whose result path
+     * fails closed to `degraded` booleans but who still need to distinguish a
+     * throttle (persist a backoff) from an ordinary blip.
+     */
+    lastError?: ProviderError;
     constructor(opts?: EspnAdapterOptions);
     fetchByDate(dateISO: string): Promise<Match[]>;
     fetchWindow(startDate: string, endDate: string): Promise<Match[]>;
@@ -572,6 +659,8 @@ declare class EspnAdapter implements ProviderAdapter {
     fetchLive(): Promise<Match[]>;
     /** Standings endpoint URL (lives under apis/v2, not site/v2; derived from base). */
     private standingsUrl;
+    /** The shared standings fetch (see {@link standingsShared}). */
+    private sharedStandings;
     /**
      * Authoritative, cumulative group tables from the standings endpoint. Throws
      * on fetch/parse failure (the caller decides the fallback). Group-stage only:
@@ -580,8 +669,11 @@ declare class EspnAdapter implements ProviderAdapter {
     fetchStandings(): Promise<GroupStandings[]>;
     /**
      * Build (and cache) a team-code -> group-letter map from the standings
-     * endpoint. Best-effort: returns {} if standings are unavailable. Reuses the
-     * same parse as {@link fetchStandings}, so the two never drift.
+     * endpoint. Best-effort: returns {} if standings are unavailable — but a
+     * transient failure is NOT cached (only a successful parse pins the map), so
+     * one blip can't silently drop group letters for the adapter's lifetime.
+     * Reuses the same parse/fetch as {@link fetchStandings}, so the two never
+     * drift and one command never fetches standings twice.
      */
     fetchGroupMap(force?: boolean): Promise<Record<string, string>>;
     private fetchScoreboard;
@@ -596,7 +688,14 @@ declare class EspnAdapter implements ProviderAdapter {
  * always the World Cup.
  */
 declare function resolveCompetition(explicit?: string): string;
-/** Construct a provider adapter for a `--source` name (default: espn). */
+/** Provider names {@link makeAdapter} can construct (the CLI validates against this). */
+declare const KNOWN_SOURCES: readonly ["espn"];
+/**
+ * Construct a provider adapter for a `--source` name (default: espn). An
+ * unknown source FAILS LOUD instead of silently running ESPN — `--source foo`
+ * previously no-op'd, which lied about what the flag did (attribution stayed
+ * honest, but the advertised knob did nothing).
+ */
 declare function makeAdapter(source?: string): ProviderAdapter;
 /**
  * Merge live matches over a base set by id. Live entries replace base entries
@@ -642,6 +741,10 @@ interface StandingsResult {
  * asked-for group isn't in it (caller renders "no such group").
  */
 declare function getStandings(adapter: ProviderAdapter, group?: string): Promise<StandingsResult>;
+declare function knockoutWindow(): {
+    start: string;
+    end: string;
+} | null;
 /**
  * Knockout bracket with hybrid slot resolution: confirmed FT winners/losers from
  * the live overlay; group slots project from live standings once a group has started.
@@ -1176,4 +1279,4 @@ declare function formatShareBracket(input: ShareBracketInput, options?: ShareBra
 /** Compact one-line-per-match bracket for narrow share contexts. */
 declare function formatBracketCompactLine(mv: BracketMatchView, opts?: BracketFormatOpts): string;
 
-export { BRACKET_STAGE_ORDER, type BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketTopology, type BracketView, type BuildSignalInput, DEFAULT_COMPETITION, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, EspnAdapter, type EspnAdapterOptions, FLAVOR_LEVELS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FlavorLevel, type FormatOpts, type GroupStandings, type KnockoutFixturesResult, LIVE_WINDOW_MS, type Lang, type LedgerRow, type LiveResult, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchByIdResult, type MatchEvent, type NextFixtureResult, type Outcome, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, type PunditPick, type ResolvedParticipant, SHARE_DISCLAIMER, SHARE_HASHTAG, type ShareBracketInput, type ShareBracketOptions, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type ShareTableInput, type SlotRef, type Stage, type StandingRow, type StandingsResult, type Status, type Team, type TeamInfo, type TeamLookup, allFixtures, allTeams, asFlavorLevel, buildBracketTopology, buildBracketView, buildMarketSignal, byKickoff, competitionBase, computeStandings, countdown, currentOrNextFixtureForTeam, deriveFavorite, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, formatBracketCompactLine, formatBracketList, formatBracketMatchLine, formatBracketTree, formatDate, formatKickoff, formatShareBracket, formatShareSnippet, formatShareTable, formatTime, getBracket, getKnockoutFixtures, getLiveMatches, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getNextFixtureForTeam, getStandings, groups, hasSaneDistribution, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isResolvedNation, isStaleSignal, isValidDate, isValidTimeZone, liveSourceLabel, loadBracketTopology, localDate, lookupTeam, makeAdapter, makeMarketProvider, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketSignalRendersFor, marketSourceLabel, matchFlavor, matchKey, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeLang, normalizeOutcomes, outcomeFromScore, parseStandings, parseTeamSlot, resolveCompetition, resolveMarketSource, resolveTz, sanitizeBundledFixture, scoreline, stageLabel, stageLabelI18n, t };
+export { BRACKET_STAGE_ORDER, type BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketTopology, type BracketView, type BuildSignalInput, DEFAULT_COMPETITION, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, EspnAdapter, type EspnAdapterOptions, FEED_TEXT_MAX, FLAVOR_LEVELS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FlavorLevel, type FormatOpts, type GroupStandings, KNOWN_SOURCES, type KnockoutFixturesResult, LIVE_WINDOW_MS, type Lang, type LedgerRow, type LiveResult, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchByIdResult, type MatchEvent, type NextFixtureResult, type Outcome, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, ProviderError, type ProviderErrorKind, type PunditPick, type ResolvedParticipant, SHARE_DISCLAIMER, SHARE_HASHTAG, type ShareBracketInput, type ShareBracketOptions, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type ShareTableInput, type SlotRef, type Stage, type StandingRow, type StandingsResult, type Status, type Team, type TeamInfo, type TeamLookup, allFixtures, allTeams, asFlavorLevel, buildBracketTopology, buildBracketView, buildMarketSignal, byKickoff, competitionBase, computeStandings, countdown, currentOrNextFixtureForTeam, deriveFavorite, displayWidth, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, formatBracketCompactLine, formatBracketList, formatBracketMatchLine, formatBracketTree, formatDate, formatKickoff, formatShareBracket, formatShareSnippet, formatShareTable, formatTime, getBracket, getKnockoutFixtures, getLiveMatches, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getNextFixtureForTeam, getStandings, groups, hasSaneDistribution, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isResolvedNation, isStaleSignal, isValidDate, isValidTimeZone, knockoutWindow, liveSourceLabel, loadBracketTopology, localDate, lookupTeam, makeAdapter, makeMarketProvider, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketSignalRendersFor, marketSourceLabel, matchFlavor, matchKey, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeLang, normalizeOutcomes, outcomeFromScore, padVisible, parseStandings, parseTeamSlot, resolveCompetition, resolveMarketSource, resolveTz, sanitizeBundledFixture, sanitizeFeedText, sanitizeMatchStrings, scoreline, stageLabel, stageLabelI18n, t };

package/dist/index.js

@@ -378,7 +378,8 @@ function normalizeLang(lang) {
 }
 function t(lang, key, vars) {
   const dict = CATALOGS[normalizeLang(lang)];
-  let s = dict[key] ?? EN[key] ?? key;
+  const en = EN;
+  let s = dict[key] ?? en[key] ?? key;
   if (vars) {
     for (const [k, v] of Object.entries(vars)) s = s.replaceAll(`{${k}}`, v);
   }
@@ -502,6 +503,67 @@ function shiftUtcDate(dateISO, days) {
   return new Date(Date.UTC(y ?? 1970, (m ?? 1) - 1, (d ?? 1) + days)).toISOString().slice(0, 10);
 }
 
+// src/sanitize.ts
+var FEED_TEXT_MAX = 100;
+function sanitizeFeedText(value, max = FEED_TEXT_MAX) {
+  let out = "";
+  let count = 0;
+  for (const ch of String(value)) {
+    const cp = ch.codePointAt(0) ?? 0;
+    const isWhitespaceControl = cp === 9 || cp === 10 || cp === 13;
+    if ((cp <= 31 || cp >= 127 && cp <= 159) && !isWhitespaceControl) continue;
+    if (count >= max) break;
+    out += isWhitespaceControl ? " " : ch;
+    count++;
+  }
+  return out;
+}
+function sanitizeTeam(t2) {
+  return {
+    ...t2 ?? {},
+    code: sanitizeFeedText(t2?.code ?? ""),
+    name: sanitizeFeedText(t2?.name ?? ""),
+    flag: sanitizeFeedText(t2?.flag ?? "")
+  };
+}
+function finiteOrUndefined(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function sanitizeScorePair(v) {
+  const home = finiteOrUndefined(v?.home);
+  const away = finiteOrUndefined(v?.away);
+  return home !== void 0 && away !== void 0 ? { home, away } : void 0;
+}
+function sanitizeMatchStrings(m) {
+  const score = sanitizeScorePair(m.score);
+  return {
+    ...m,
+    venue: sanitizeFeedText(m.venue ?? ""),
+    city: m.city == null ? m.city : sanitizeFeedText(m.city),
+    country: m.country == null ? m.country : sanitizeFeedText(m.country),
+    home: sanitizeTeam(m.home),
+    away: sanitizeTeam(m.away),
+    score,
+    shootout: score ? sanitizeScorePair(m.shootout) : void 0,
+    minute: finiteOrUndefined(m.minute)
+  };
+}
+
+// src/text.ts
+var segmenter = new Intl.Segmenter();
+var WIDE_CLUSTER = new RegExp("^(?:\\p{Regional_Indicator}|\\p{Extended_Pictographic})", "u");
+function displayWidth(s) {
+  let w = 0;
+  for (const { segment } of segmenter.segment(s)) {
+    w += WIDE_CLUSTER.test(segment) ? 2 : 1;
+  }
+  return w;
+}
+function padVisible(s, width) {
+  const w = displayWidth(s);
+  return w >= width ? s : s + " ".repeat(width - w);
+}
+
 // src/normalize.ts
 function outcomeFromScore(home, away) {
   if (home > away) return "H";
@@ -3024,10 +3086,27 @@ function rosterAtZero(matches) {
 var ESPN_SOCCER = "https://site.api.espn.com/apis/site/v2/sports/soccer";
 var DEFAULT_COMPETITION = "fifa.world";
 var DEFAULT_BASE = `${ESPN_SOCCER}/${DEFAULT_COMPETITION}`;
-var USER_AGENT = "claudinho/0.0 (+https://github.com/arturogarrido/claudinho)";
+var USER_AGENT = `claudinho/${"0.9.0"} (+https://github.com/arturogarrido/claudinho)`;
+var MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
 function competitionBase(slug) {
   return `${ESPN_SOCCER}/${slug}`;
 }
+var DEFAULT_TIMEOUT_MS = 6e3;
+var STANDINGS_SHARE_MS = 3e4;
+var ProviderError = class extends Error {
+  kind;
+  status;
+  constructor(message, kind, status) {
+    super(message);
+    this.name = "ProviderError";
+    this.kind = kind;
+    this.status = status;
+  }
+  /** 429/403 — the upstream is refusing us; retrying at the live cadence makes it worse. */
+  get throttled() {
+    return this.kind === "http" && (this.status === 429 || this.status === 403);
+  }
+};
 function mapStatus(st) {
   const name = (st?.type?.name ?? "").toUpperCase();
   const state = st?.type?.state ?? "";
@@ -3068,9 +3147,15 @@ function toInt(s) {
   return Number.isFinite(n) ? n : void 0;
 }
 function toTeam(t2) {
-  const name = t2?.displayName ?? t2?.name ?? t2?.location ?? t2?.shortDisplayName ?? "TBD";
-  const code = (t2?.abbreviation ?? name.slice(0, 3)).toUpperCase();
-  return { code, name, flag: nationToFlag(t2?.displayName ?? t2?.abbreviation ?? name) };
+  const name = sanitizeFeedText(
+    t2?.displayName ?? t2?.name ?? t2?.location ?? t2?.shortDisplayName ?? "TBD"
+  );
+  const code = sanitizeFeedText(t2?.abbreviation ?? name.slice(0, 3)).toUpperCase();
+  return {
+    code,
+    name,
+    flag: nationToFlag(sanitizeFeedText(t2?.displayName ?? t2?.abbreviation ?? name))
+  };
 }
 function mapEspnEvent(ev, ctx = {}) {
   const comp = ev.competitions?.[0];
@@ -3101,9 +3186,9 @@ function mapEspnEvent(ev, ctx = {}) {
     stage,
     group,
     kickoff: ev.date,
-    venue: comp?.venue?.fullName ?? "",
-    city: comp?.venue?.address?.city || void 0,
-    country: comp?.venue?.address?.country || void 0,
+    venue: sanitizeFeedText(comp?.venue?.fullName ?? ""),
+    city: sanitizeFeedText(comp?.venue?.address?.city ?? "") || void 0,
+    country: sanitizeFeedText(comp?.venue?.address?.country ?? "") || void 0,
     home,
     away,
     score: hasScore ? { home: hs, away: as } : void 0,
@@ -3163,6 +3248,20 @@ var EspnAdapter = class {
   capabilities = { push: false, latencyHintSec: 45 };
   /** Cached team-code -> group-letter map (built lazily from standings). */
   groupMap;
+  /**
+   * One in-flight/recent standings fetch shared by fetchStandings and
+   * fetchGroupMap, so a command like `bracket` hits the endpoint once instead
+   * of twice, and a long-lived MCP server stays fresh (short TTL). A rejected
+   * fetch clears the slot — a transient failure is never cached.
+   */
+  standingsShared;
+  /**
+   * The most recent request failure (best-effort under concurrency; cleared
+   * when a new request starts). A post-hoc hint for callers whose result path
+   * fails closed to `degraded` booleans but who still need to distinguish a
+   * throttle (persist a backoff) from an ordinary blip.
+   */
+  lastError;
   async fetchByDate(dateISO) {
     return this.fetchScoreboard(toEspnDate(dateISO));
   }
@@ -3184,37 +3283,58 @@ var EspnAdapter = class {
     const base = this.opts.baseUrl ?? DEFAULT_BASE;
     return `${base.replace("/apis/site/v2/", "/apis/v2/")}/standings`;
   }
+  /** The shared standings fetch (see {@link standingsShared}). */
+  sharedStandings() {
+    const now = Date.now();
+    if (this.standingsShared && now - this.standingsShared.at < STANDINGS_SHARE_MS) {
+      return this.standingsShared.promise;
+    }
+    const promise = this.get(this.standingsUrl()).then(
+      (d) => parseStandings(d)
+    );
+    this.standingsShared = { at: now, promise };
+    promise.catch(() => {
+      if (this.standingsShared?.promise === promise) this.standingsShared = void 0;
+    });
+    return promise;
+  }
   /**
    * Authoritative, cumulative group tables from the standings endpoint. Throws
    * on fetch/parse failure (the caller decides the fallback). Group-stage only:
    * non-group `children` are filtered out by {@link parseStandings}.
    */
   async fetchStandings() {
-    return parseStandings(await this.get(this.standingsUrl()));
+    return this.sharedStandings();
   }
   /**
    * Build (and cache) a team-code -> group-letter map from the standings
-   * endpoint. Best-effort: returns {} if standings are unavailable. Reuses the
-   * same parse as {@link fetchStandings}, so the two never drift.
+   * endpoint. Best-effort: returns {} if standings are unavailable — but a
+   * transient failure is NOT cached (only a successful parse pins the map), so
+   * one blip can't silently drop group letters for the adapter's lifetime.
+   * Reuses the same parse/fetch as {@link fetchStandings}, so the two never
+   * drift and one command never fetches standings twice.
    */
   async fetchGroupMap(force = false) {
     if (this.groupMap && !force) return this.groupMap;
-    const map = {};
     try {
-      const tables = parseStandings(await this.get(this.standingsUrl()));
+      const tables = await this.sharedStandings();
+      const map = {};
       for (const t2 of tables) for (const r of t2.rows) map[r.team.code] = t2.group;
+      this.groupMap = map;
+      return map;
     } catch {
+      return {};
     }
-    this.groupMap = map;
-    return map;
   }
   async fetchScoreboard(dates) {
     const base = this.opts.baseUrl ?? DEFAULT_BASE;
     const url = new URL(`${base}/scoreboard`);
     url.searchParams.set("limit", "300");
     if (dates) url.searchParams.set("dates", dates);
-    const groupByTeam = this.opts.enrichGroups === false ? {} : await this.fetchGroupMap();
-    const data = await this.get(url.toString());
+    const [groupByTeam, data] = await Promise.all([
+      this.opts.enrichGroups === false ? Promise.resolve({}) : this.fetchGroupMap(),
+      this.get(url.toString())
+    ]);
     return (data.events ?? []).map((ev) => mapEspnEvent(ev, { groupByTeam }));
   }
   async get(url) {
@@ -3222,17 +3342,51 @@ var EspnAdapter = class {
     const controller = new AbortController();
     const timer = setTimeout(
       () => controller.abort(),
-      this.opts.timeoutMs ?? 15e3
+      this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
     );
+    this.lastError = void 0;
     try {
-      const res = await doFetch(url, {
-        signal: controller.signal,
-        headers: { Accept: "application/json", "User-Agent": USER_AGENT }
-      });
+      let res;
+      try {
+        res = await doFetch(url, {
+          signal: controller.signal,
+          // ESPN never legitimately redirects; following one would sidestep the
+          // fixed-host guarantee, so treat any redirect as a failure (degraded).
+          redirect: "error",
+          headers: { Accept: "application/json", "User-Agent": USER_AGENT }
+        });
+      } catch (e) {
+        throw e?.name === "AbortError" ? new ProviderError(`ESPN request timed out: ${url}`, "timeout") : new ProviderError(`ESPN request failed: ${e?.message ?? e}`, "http");
+      }
       if (!res.ok) {
-        throw new Error(`ESPN request failed: ${res.status} ${res.statusText}`);
+        throw new ProviderError(
+          `ESPN request failed: ${res.status} ${res.statusText}`,
+          "http",
+          res.status
+        );
+      }
+      const length = Number(res.headers?.get?.("content-length"));
+      if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) {
+        throw new ProviderError(`ESPN response too large: ${length} bytes`, "parse");
+      }
+      try {
+        return await res.json();
+      } catch (e) {
+        throw new ProviderError(
+          `ESPN response unparseable: ${e?.message ?? e}`,
+          "parse"
+        );
+      }
+    } catch (e) {
+      const pe = e instanceof ProviderError ? e : new ProviderError(String(e?.message ?? e), "http");
+      this.lastError = pe;
+      if (typeof process !== "undefined" && process.env?.CLAUDINHO_DEBUG) {
+        process.stderr.write(
+          `claudinho: espn ${pe.kind}${pe.status ? ` ${pe.status}` : ""}: ${url}
+`
+        );
       }
-      return await res.json();
+      throw pe;
     } finally {
       clearTimeout(timer);
     }
@@ -4126,13 +4280,18 @@ function resolveCompetition(explicit) {
   }
   return DEFAULT_COMPETITION;
 }
+var KNOWN_SOURCES = ["espn"];
 function makeAdapter(source = "espn") {
   switch (source) {
-    default: {
+    case "espn": {
       const competition = resolveCompetition();
       const baseUrl = competition === DEFAULT_COMPETITION ? void 0 : competitionBase(competition);
       return new EspnAdapter({ baseUrl });
     }
+    default:
+      throw new Error(
+        `Unknown data source "${source}" (available: ${KNOWN_SOURCES.join(", ")})`
+      );
   }
 }
 function mergeLive(base, live) {
@@ -4170,8 +4329,16 @@ async function getStandings(adapter, group) {
   const tables = letters.map((g) => ({ group: g, rows: rosterAtZero(fixturesByGroup(g)) })).filter((t2) => t2.rows.length > 0);
   return { tables, degraded: true };
 }
-var KNOCKOUT_WINDOW_START = "20260628";
-var KNOCKOUT_WINDOW_END = "20260719";
+var knockoutWindowMemo;
+function knockoutWindow() {
+  if (knockoutWindowMemo !== void 0) return knockoutWindowMemo;
+  const days = allFixtures().filter((m) => m.stage !== "GROUP" && m.stage !== "FRIENDLY").map((m) => m.kickoff.slice(0, 10).replace(/-/g, "")).filter((d) => d.length === 8);
+  knockoutWindowMemo = days.length ? {
+    start: days.reduce((a, b) => a < b ? a : b),
+    end: days.reduce((a, b) => a > b ? a : b)
+  } : null;
+  return knockoutWindowMemo;
+}
 async function getBracket(adapter, opts = {}) {
   const topology = loadBracketTopology();
   const base = allFixtures().filter((m) => m.stage !== "GROUP" && m.stage !== "FRIENDLY");
@@ -4179,7 +4346,8 @@ async function getBracket(adapter, opts = {}) {
   let liveDegraded = true;
   let source;
   try {
-    const live = adapter.fetchWindow ? await adapter.fetchWindow(KNOCKOUT_WINDOW_START, KNOCKOUT_WINDOW_END) : [];
+    const win = knockoutWindow();
+    const live = adapter.fetchWindow && win ? await adapter.fetchWindow(win.start, win.end) : [];
     matches = mergeLive(base, live);
     liveDegraded = false;
     source = adapter.name;
@@ -4212,8 +4380,9 @@ async function marketFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Dat
   let fixtures = allFixtures();
   let overlayFailed = false;
   try {
-    if (adapter.fetchWindow) {
-      fixtures = mergeLive(fixtures, await adapter.fetchWindow(KNOCKOUT_WINDOW_START, KNOCKOUT_WINDOW_END));
+    const win = knockoutWindow();
+    if (adapter.fetchWindow && win) {
+      fixtures = mergeLive(fixtures, await adapter.fetchWindow(win.start, win.end));
     }
   } catch {
     overlayFailed = true;
@@ -4236,7 +4405,8 @@ async function getNextFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Da
   let degraded = true;
   let liveById;
   try {
-    const live = adapter.fetchWindow ? await adapter.fetchWindow(KNOCKOUT_WINDOW_START, KNOCKOUT_WINDOW_END) : [];
+    const win = knockoutWindow();
+    const live = adapter.fetchWindow && win ? await adapter.fetchWindow(win.start, win.end) : [];
     matches = mergeLive(base, live);
     degraded = false;
     liveById = new Set(live.map((m) => m.id));
@@ -4247,10 +4417,11 @@ async function getNextFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Da
   return { fixture, degraded, source };
 }
 async function getKnockoutFixtures(adapter, now = /* @__PURE__ */ new Date()) {
-  if (!adapter.fetchWindow) return { fixtures: [], degraded: true };
+  const win = knockoutWindow();
+  if (!adapter.fetchWindow || !win) return { fixtures: [], degraded: true };
   let live;
   try {
-    live = await adapter.fetchWindow(KNOCKOUT_WINDOW_START, KNOCKOUT_WINDOW_END);
+    live = await adapter.fetchWindow(win.start, win.end);
   } catch {
     return { fixtures: [], degraded: true };
   }
@@ -4508,7 +4679,7 @@ var mapping_2026_default = {
 var DEFAULT_BASE2 = "https://gamma-api.polymarket.com";
 var ALLOWED_HOSTS = /* @__PURE__ */ new Set(["gamma-api.polymarket.com"]);
 var USER_AGENT2 = "claudinho/0.0 (+https://github.com/arturogarrido/claudinho)";
-var DEFAULT_TIMEOUT_MS = 8e3;
+var DEFAULT_TIMEOUT_MS2 = 8e3;
 var WC_SERIES_SLUG = "soccer-fifwc";
 var WC_SPORT = "fifwc";
 var KICKOFF_TOLERANCE_MS = 6 * 60 * 6e4;
@@ -4546,7 +4717,7 @@ var PolymarketProvider = class {
     const entry = (this.opts.mapping ?? BUNDLED_MAPPING)[match.id];
     const slugs = entry?.eventSlug ? [entry.eventSlug] : deriveEventSlugs(match);
     if (slugs.length === 0) return { checked: true };
-    const configured = options?.timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const configured = options?.timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
     try {
       for (const slug of slugs) {
         const remaining = deadline - Date.now();
@@ -4566,13 +4737,20 @@ var PolymarketProvider = class {
     const url = `${base}/events?slug=${encodeURIComponent(slug)}`;
     const doFetch = this.opts.fetchImpl ?? fetch;
     const res = await doFetch(url, {
-      signal: AbortSignal.timeout(timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      signal: AbortSignal.timeout(timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2),
+      // Gamma never legitimately redirects; following one would sidestep the
+      // host allow-list (it only validates the base URL), so reject redirects.
+      redirect: "error",
       headers: { Accept: "application/json", "User-Agent": USER_AGENT2 }
     });
     if (res.status === 404) return void 0;
     if (!res.ok) {
       throw new Error(`Polymarket request failed: ${res.status} ${res.statusText}`);
     }
+    const length = Number(res.headers?.get?.("content-length"));
+    if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) {
+      throw new Error(`Polymarket response too large: ${length} bytes`);
+    }
     const data = await res.json();
     const event = Array.isArray(data) ? data[0] : data;
     return event && typeof event === "object" ? event : void 0;
@@ -5025,10 +5203,13 @@ export {
   DEFAULT_FLAVOR,
   DEFAULT_MAX_AGE_MS,
   EspnAdapter,
+  FEED_TEXT_MAX,
   FLAVOR_LEVELS,
   FakeMarketProvider,
+  KNOWN_SOURCES,
   LIVE_WINDOW_MS,
   PolymarketProvider,
+  ProviderError,
   SHARE_DISCLAIMER,
   SHARE_HASHTAG,
   allFixtures,
@@ -5043,6 +5224,7 @@ export {
   countdown,
   currentOrNextFixtureForTeam,
   deriveFavorite,
+  displayWidth,
   favoriteStrength,
   fixturesByDate,
   fixturesByGroup,
@@ -5078,6 +5260,7 @@ export {
   isStaleSignal,
   isValidDate,
   isValidTimeZone,
+  knockoutWindow,
   liveSourceLabel,
   loadBracketTopology,
   localDate,
@@ -5105,12 +5288,15 @@ export {
   normalizeLang,
   normalizeOutcomes,
   outcomeFromScore,
+  padVisible,
   parseStandings,
   parseTeamSlot,
   resolveCompetition,
   resolveMarketSource,
   resolveTz,
   sanitizeBundledFixture,
+  sanitizeFeedText,
+  sanitizeMatchStrings,
   scoreline,
   stageLabel,
   stageLabelI18n,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudinho/core",
-  "version": "0.8.18",
+  "version": "0.9.0",
   "description": "Domain model, provider adapters (ESPN), standings, bundled schedule, and the read-only Polymarket market-signal sidecar powering Claudinho. Not affiliated with FIFA or Anthropic.",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,7 @@
   ],
   "devDependencies": {
     "@types/node": "^22.20.0",
+    "@vitest/coverage-v8": "^4.1.9",
     "tsup": "^8.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",