@claudinho/core 0.4.2 → 0.4.3

package/dist/index.d.ts

@@ -224,6 +224,21 @@ declare function nextFixtureForTeam(code: string, opts?: {
     from?: Date;
     fixtures?: Match[];
 }): Match | undefined;
+/** A fixture is potentially live from kickoff until ~kickoff + 140 min. */
+declare const LIVE_WINDOW_MS: number;
+/** Fixtures whose live window contains `now` (cheap, static — no network). */
+declare function fixturesInLiveWindow(now?: number, fixtures?: Match[]): Match[];
+/**
+ * The team's in-play fixture when one is inside its live window, else the next
+ * upcoming fixture. This is "the match that matters for <team> right now":
+ * mid-match, a user (or an agent) asking about a team almost always means the
+ * one being played — `nextFixtureForTeam` alone would skip it the moment the
+ * kickoff is in the past and silently answer about next week.
+ */
+declare function currentOrNextFixtureForTeam(code: string, opts?: {
+    from?: Date;
+    fixtures?: Match[];
+}): Match | undefined;
 /** Sorted list of distinct group letters present in the schedule. */
 declare function groups(fixtures?: Match[]): string[];
 
@@ -412,6 +427,34 @@ declare function liveSourceLabel(source: string): string;
  * schedule on any provider/network error (graceful degradation).
  */
 declare function getMatchesForDate(adapter: ProviderAdapter, dateISO: string): Promise<LiveResult>;
+interface MatchByIdResult {
+    match?: Match;
+    degraded: boolean;
+    source?: string;
+}
+/**
+ * The fixture a team-scoped MARKET query should be about, live-confirmed.
+ * Static window math alone fails twice at the edges: a match in extra time
+ * (now > kickoff + 140min, still LIVE) would be skipped for next week's
+ * fixture, and a just-finished match (inside the window, already FT) would be
+ * selected over the next one. So: pick the in-window candidate using a widened
+ * window, overlay live state, and fall through to the next fixture when the
+ * overlay says the candidate is finished. Degraded fetches keep the static
+ * candidate (fail-closed: the market-relevance gate then errs toward showing
+ * nothing rather than something wrong).
+ */
+declare function marketFixtureForTeam(adapter: ProviderAdapter, code: string, now?: Date): Promise<MatchByIdResult>;
+/**
+ * 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
+ * from the scoreboard day it's filed under — a 02:00Z kickoff belongs to the
+ * previous ET evening, and fetching only the UTC date silently misses its live
+ * state (the match then renders from the static schedule as if scheduled).
+ * Fetch the ±1-day window around the fixture's UTC date instead — the same
+ * trick `getMatchesForDate` uses — and fall back to the static fixture on any
+ * provider error.
+ */
+declare function getMatchById(adapter: ProviderAdapter, id: string): Promise<MatchByIdResult>;
 /** Currently-live matches; empty + degraded on error. */
 declare function getLiveMatches(adapter: ProviderAdapter): Promise<LiveResult>;
 
@@ -520,14 +563,16 @@ interface MarketProvider {
     findSignals(matches: Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
 }
 
-/**
- * Probability normalization + the reliability gate. `isReliableMarketSignal` is
- * the single primitive every default-on surface keys off: "show only when
- * reliable, otherwise omit silently."
- */
-
 /** Default freshness window: a signal older than this is stale (15 minutes). */
 declare const DEFAULT_MAX_AGE_MS: number;
+/**
+ * Market signals are pre-match and in-play reads. Once a match has finished —
+ * status `FT`, or (for static fixtures that never get a live overlay) once its
+ * live window has long passed — a "favorite" is resolved history: showing
+ * "markets favor X 100%" after full time reads as a bug, not information.
+ * An unparseable kickoff fails open (the reliability gate still applies).
+ */
+declare function marketRelevant(match: Match, now?: Date): boolean;
 /**
  * Re-scale outcome probabilities so the positive ones sum to 1. This removes
  * market "vig" (raw prices sum to >1) and is scale-agnostic: inputs may be
@@ -763,4 +808,4 @@ interface ShareSnippetInput {
  */
 declare function formatShareSnippet(input: ShareSnippetInput, options?: ShareSnippetOptions): string;
 
-export { 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 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 MatchEvent, type Outcome, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, type PunditPick, SHARE_DISCLAIMER, SHARE_HASHTAG, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type Stage, type StandingRow, type Status, type Team, allFixtures, asFlavorLevel, buildMarketSignal, byKickoff, competitionBase, computeStandings, countdown, deriveFavorite, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, flagEmoji, formatDate, formatKickoff, formatShareSnippet, formatTime, getLiveMatches, getMarketSignal, getMarketSignals, getMatchesForDate, groups, hasSaneDistribution, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isStaleSignal, isValidDate, isValidTimeZone, liveSourceLabel, localDate, makeAdapter, makeMarketProvider, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketLine, marketProbabilityText, marketSourceLabel, matchFlavor, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeOutcomes, outcomeFromScore, resolveCompetition, resolveMarketSource, resolveTz, scoreline };
+export { type BuildSignalInput, DEFAULT_COMPETITION, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, EspnAdapter, type EspnAdapterOptions, FLAVOR_LEVELS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FlavorLevel, type FormatOpts, LIVE_WINDOW_MS, 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, SHARE_DISCLAIMER, SHARE_HASHTAG, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type Stage, type StandingRow, type Status, type Team, allFixtures, asFlavorLevel, buildMarketSignal, byKickoff, competitionBase, computeStandings, countdown, currentOrNextFixtureForTeam, deriveFavorite, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, formatDate, formatKickoff, formatShareSnippet, formatTime, getLiveMatches, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, groups, hasSaneDistribution, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isStaleSignal, isValidDate, isValidTimeZone, liveSourceLabel, localDate, makeAdapter, makeMarketProvider, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketSourceLabel, matchFlavor, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeOutcomes, outcomeFromScore, resolveCompetition, resolveMarketSource, resolveTz, scoreline };

package/dist/index.js

@@ -2622,6 +2622,22 @@ function nextFixtureForTeam(code, opts = {}) {
     (m) => new Date(m.kickoff).getTime() >= from.getTime()
   );
 }
+var LIVE_WINDOW_MS = 140 * 6e4;
+function fixturesInLiveWindow(now = Date.now(), fixtures = SCHEDULE) {
+  return fixtures.filter((m) => {
+    const k = Date.parse(m.kickoff);
+    return now >= k && now <= k + LIVE_WINDOW_MS;
+  }).sort(byKickoff);
+}
+function currentOrNextFixtureForTeam(code, opts = {}) {
+  const from = opts.from ?? /* @__PURE__ */ new Date();
+  const nowMs = from.getTime();
+  const inPlay = fixturesByTeam(code, opts.fixtures ?? SCHEDULE).find((m) => {
+    const k = Date.parse(m.kickoff);
+    return nowMs >= k && nowMs <= k + LIVE_WINDOW_MS;
+  });
+  return inPlay ?? nextFixtureForTeam(code, opts);
+}
 function groups(fixtures = SCHEDULE) {
   const set = /* @__PURE__ */ new Set();
   for (const m of fixtures) if (m.group) set.add(m.group);
@@ -2885,6 +2901,33 @@ function shiftUtcDate(dateISO, days) {
   const [y, m, d] = dateISO.slice(0, 10).split("-").map(Number);
   return new Date(Date.UTC(y ?? 1970, (m ?? 1) - 1, (d ?? 1) + days)).toISOString().slice(0, 10);
 }
+var EXTRA_TIME_SLACK_MS = 60 * 6e4;
+async function marketFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Date()) {
+  const nowMs = now.getTime();
+  const candidate = fixturesByTeam(code).find((m) => {
+    const k = Date.parse(m.kickoff);
+    return nowMs >= k && nowMs <= k + LIVE_WINDOW_MS + EXTRA_TIME_SLACK_MS;
+  });
+  if (candidate) {
+    const r = await getMatchById(adapter, candidate.id);
+    const m = r.match ?? candidate;
+    if (!isFinished(m.status)) return { ...r, match: m };
+  }
+  const next = nextFixtureForTeam(code, { from: now });
+  return { match: next, degraded: false };
+}
+async function getMatchById(adapter, id) {
+  const base = allFixtures().find((m) => m.id === id);
+  if (!base) return { match: void 0, degraded: false };
+  const day = base.kickoff.slice(0, 10);
+  try {
+    const live = adapter.fetchWindow ? await adapter.fetchWindow(shiftUtcDate(day, -1), shiftUtcDate(day, 1)) : await adapter.fetchByDate(day);
+    const hit = live.find((m) => m.id === id);
+    return { match: hit ?? base, degraded: false, source: hit ? adapter.name : void 0 };
+  } catch {
+    return { match: base, degraded: true };
+  }
+}
 async function getLiveMatches(adapter) {
   try {
     return { matches: await adapter.fetchLive(), degraded: false, source: adapter.name };
@@ -2895,6 +2938,12 @@ async function getLiveMatches(adapter) {
 
 // src/markets/normalize.ts
 var DEFAULT_MAX_AGE_MS = 15 * 6e4;
+function marketRelevant(match, now = /* @__PURE__ */ new Date()) {
+  if (isLive(match.status)) return true;
+  if (isFinished(match.status)) return false;
+  const k = Date.parse(match.kickoff);
+  return !Number.isFinite(k) || now.getTime() <= k + LIVE_WINDOW_MS;
+}
 function normalizeOutcomes(outcomes) {
   const sum = outcomes.reduce(
     (s, o) => s + (Number.isFinite(o.probability) && o.probability > 0 ? o.probability : 0),
@@ -3415,6 +3464,7 @@ export {
   EspnAdapter,
   FLAVOR_LEVELS,
   FakeMarketProvider,
+  LIVE_WINDOW_MS,
   PolymarketProvider,
   SHARE_DISCLAIMER,
   SHARE_HASHTAG,
@@ -3425,11 +3475,13 @@ export {
   competitionBase,
   computeStandings,
   countdown,
+  currentOrNextFixtureForTeam,
   deriveFavorite,
   favoriteStrength,
   fixturesByDate,
   fixturesByGroup,
   fixturesByTeam,
+  fixturesInLiveWindow,
   flagEmoji,
   formatDate,
   formatKickoff,
@@ -3438,6 +3490,7 @@ export {
   getLiveMatches,
   getMarketSignal,
   getMarketSignals,
+  getMatchById,
   getMatchesForDate,
   groups,
   hasSaneDistribution,
@@ -3457,8 +3510,10 @@ export {
   marketAttributionText,
   marketBlock,
   marketFavoriteText,
+  marketFixtureForTeam,
   marketLine,
   marketProbabilityText,
+  marketRelevant,
   marketSourceLabel,
   matchFlavor,
   matchLocation,

package/package.json

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