@claudinho/core 0.8.6 → 0.8.8

package/dist/index.d.ts

@@ -626,6 +626,51 @@ interface MatchByIdResult {
  * nothing rather than something wrong).
  */
 declare function marketFixtureForTeam(adapter: ProviderAdapter, code: string, now?: Date): Promise<MatchByIdResult>;
+interface NextFixtureResult {
+    fixture?: Match;
+    /** True when the live overlay fetch failed and only the static skeleton was used. */
+    degraded: boolean;
+    /** The provider that served the live overlay (absent when degraded). */
+    source?: string;
+}
+/**
+ * A team's next UPCOMING fixture, LIVE-RESOLVED across the knockout phase.
+ *
+ * The bundled schedule's knockout slots are resultless placeholders (home/away
+ * are slot refs like "Group A winner", never a nation — see
+ * {@link sanitizeBundledFixture}), so a purely static lookup goes blind the
+ * moment a team's last GROUP game passes: `next MEX` answers "no upcoming
+ * fixture" even after ESPN has confirmed Mexico's Round-of-32 tie. Overlay the
+ * live knockout window (the SAME single fetch {@link getBracket} uses) so the
+ * merged set carries the resolved nations, then pick the team's next fixture
+ * with kickoff ≥ now. (Strictly upcoming — the in-play match is `getLiveMatches`'
+ * job, preserving the pre-overlay `next` semantics.)
+ *
+ * Fails closed: on any provider error it falls back to the static result
+ * (`degraded: true`), so a feed outage degrades to "no fixture" rather than
+ * inventing one — advancement is never read from the static skeleton.
+ */
+declare function getNextFixtureForTeam(adapter: ProviderAdapter, code: string, now?: Date): Promise<NextFixtureResult>;
+interface KnockoutFixturesResult {
+    /** Resolved (both nations known) upcoming knockout fixtures, sorted by kickoff. */
+    fixtures: Match[];
+    /** True when the overlay fetch failed — caller must NOT cache this as "none". */
+    degraded: boolean;
+}
+/**
+ * The RESOLVED upcoming knockout fixtures from the live overlay — the data the
+ * hot-path statusline can't fetch itself but needs to show a real next-match
+ * countdown (e.g. "🇲🇽 vs 🇪🇨 in 2d") instead of a 🏳️ placeholder. The cold-path
+ * refresher calls this and caches the result; the statusline reads the cache.
+ *
+ * Returns only fixtures where BOTH nations are resolved (flag ≠ 🏳️) and kickoff
+ * ≥ now, so a slot ESPN hasn't filled yet is simply absent (the statusline then
+ * fails closed to "⚽ —", never a placeholder). **Fails closed with
+ * `degraded: true` on a provider error** — the caller must keep its prior cached
+ * fixtures rather than cache an empty list as a real "no knockouts" (a transient
+ * outage must never read as "your team is out").
+ */
+declare function getKnockoutFixtures(adapter: ProviderAdapter, now?: Date): Promise<KnockoutFixturesResult>;
 /**
  * A single match by id, with live overlay. The provider's scoreboard buckets
  * days in its own zone (ESPN: US/Eastern), so a fixture's UTC date can differ
@@ -1058,6 +1103,9 @@ declare function parseTeamSlot(team: Team): SlotRef | null;
  */
 declare function buildBracketView(topology: BracketTopology, matches: Match[], tables: GroupStandings[], standingsDegraded: boolean, liveDegraded: boolean, filterStage?: string, lang?: string): BracketView;
 
+/** True when a team carries a real nation flag (not a bracket placeholder). */
+declare function isResolvedNation(team: Team): boolean;
+
 /** The bundled knockout bracket topology (generated by gen:schedule). */
 declare function loadBracketTopology(): BracketTopology;
 
@@ -1099,4 +1147,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, 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 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, allFixtures, 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, getLiveMatches, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getStandings, groups, hasSaneDistribution, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isStaleSignal, isValidDate, isValidTimeZone, liveSourceLabel, loadBracketTopology, localDate, makeAdapter, makeMarketProvider, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, 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, 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, allFixtures, 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, makeAdapter, makeMarketProvider, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketSourceLabel, matchFlavor, matchKey, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeLang, normalizeOutcomes, outcomeFromScore, parseStandings, parseTeamSlot, resolveCompetition, resolveMarketSource, resolveTz, sanitizeBundledFixture, scoreline, stageLabel, stageLabelI18n, t };

package/dist/index.js

@@ -4152,6 +4152,36 @@ async function marketFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Dat
   const next = nextFixtureForTeam(code, { from: now });
   return { match: next, degraded: false };
 }
+async function getNextFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Date()) {
+  const base = allFixtures();
+  let matches = base;
+  let degraded = true;
+  let liveById;
+  try {
+    const live = adapter.fetchWindow ? await adapter.fetchWindow(KNOCKOUT_WINDOW_START, KNOCKOUT_WINDOW_END) : [];
+    matches = mergeLive(base, live);
+    degraded = false;
+    liveById = new Set(live.map((m) => m.id));
+  } catch {
+  }
+  const fixture = nextFixtureForTeam(code, { from: now, fixtures: matches });
+  const source = fixture && liveById?.has(fixture.id) ? adapter.name : void 0;
+  return { fixture, degraded, source };
+}
+async function getKnockoutFixtures(adapter, now = /* @__PURE__ */ new Date()) {
+  if (!adapter.fetchWindow) return { fixtures: [], degraded: true };
+  let live;
+  try {
+    live = await adapter.fetchWindow(KNOCKOUT_WINDOW_START, KNOCKOUT_WINDOW_END);
+  } catch {
+    return { fixtures: [], degraded: true };
+  }
+  const nowMs = now.getTime();
+  const fixtures = live.filter(
+    (m) => m.stage !== "GROUP" && m.stage !== "FRIENDLY" && Date.parse(m.kickoff) >= nowMs && isResolvedNation(m.home) && isResolvedNation(m.away)
+  ).sort(byKickoff);
+  return { fixtures, degraded: false };
+}
 async function getMatchById(adapter, id) {
   const base = allFixtures().find((m) => m.id === id);
   if (!base) return { match: void 0, degraded: false };
@@ -4909,11 +4939,13 @@ export {
   formatShareTable,
   formatTime,
   getBracket,
+  getKnockoutFixtures,
   getLiveMatches,
   getMarketSignal,
   getMarketSignals,
   getMatchById,
   getMatchesForDate,
+  getNextFixtureForTeam,
   getStandings,
   groups,
   hasSaneDistribution,
@@ -4921,6 +4953,7 @@ export {
   isFlavorLevel,
   isLive,
   isReliableMarketSignal,
+  isResolvedNation,
   isStaleSignal,
   isValidDate,
   isValidTimeZone,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudinho/core",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "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",