@claudinho/core 0.4.3 → 0.5.1

package/README.md

@@ -18,13 +18,13 @@ npm i @claudinho/core
 ## What's inside
 
 - **Domain model** — `Match` (incl. `venue`/`city`/`country`), `Team`, `Stage`, `Status`, `PunditPick`, `LedgerRow`
-- **`ProviderAdapter`** — the swappable data-vendor interface; `EspnAdapter` included
+- **`ProviderAdapter`** — the swappable data-vendor interface (`fetchByDate`, `fetchLive`, optional `fetchWindow`/`fetchStandings`); `EspnAdapter` included
 - **Static schedule** — all 104 fixtures (groups, venues, host cities, kickoffs) bundled; query with `allFixtures`, `fixturesByDate` (groups by your timezone), `fixturesByTeam`, `fixturesByGroup`, `nextFixtureForTeam`, `groups`
 - **Live overlay** — `makeAdapter`, `getMatchesForDate`, `getLiveMatches`, `mergeLive` (static base + live state, with graceful degradation)
-- **Standings** — `computeStandings` (points / GD / GF tiebreak)
+- **Standings** — `getStandings` fetches authoritative, cumulative group tables from the provider (`GroupStandings`), failing closed to a roster-at-zero when none is available; `computeStandings` derives a table from a set of matches (points / GD / GF tiebreak)
 - **Helpers** — emoji flags (`nationToFlag`), TZ-aware time (`formatKickoff`, `formatDate`, `formatTime`, `countdown`, `localDate`), location strings (`matchLocation`), localized commentary flair (`matchFlavor` / `FlavorLevel`), validators (`isValidDate`, `isValidTimeZone`)
 - **Prediction-market signals (sidecar)** — read-only market signals kept *separate* from `Match`: the `MarketSignal` / `MarketProvider` model, the `PolymarketProvider` (public Gamma data only — no auth/trading/links; event slugs auto-derived per fixture, validation fails closed), a `FakeMarketProvider`, `makeMarketProvider`, `getMarketSignal` / `getMarketSignals`, the `isReliableMarketSignal` gate, and approved-copy formatters (`marketFavoriteText`, `marketProbabilityText`, `marketBlock`). Informational only — never betting advice.
-- **Shareable snippets** — `formatShareSnippet` builds pure, deterministic, plain-text match cards (composing `Match` + the market copy bank) for the CLI's `share` command and future MCP/site reuse. The non-affiliation disclaimer is non-optional; market lines come from the approved bank.
+- **Shareable snippets** — `formatShareSnippet` builds pure, deterministic, plain-text match cards (composing `Match` + the market copy bank); `formatShareTable` does the same for a group's standings (facts + emoji flags only, no market line). For the CLI's `share` command and MCP/site reuse. The non-affiliation disclaimer is non-optional; market lines come from the approved bank.
 
 ## Example
 

package/dist/index.d.ts

@@ -254,6 +254,11 @@ interface StandingRow {
     goalDiff: number;
     points: number;
 }
+/** A group's table: the group letter ("A".."L") and its rows in standings order. */
+interface GroupStandings {
+    group: string;
+    rows: StandingRow[];
+}
 /**
  * Compute a group table from a set of matches. Teams are seeded from every
  * match (so a pre-tournament table still lists all four teams at 0), and only
@@ -286,6 +291,13 @@ interface ProviderAdapter {
     fetchLive(): Promise<Match[]>;
     /** Optional inclusive date-range fetch (used for schedule generation). */
     fetchWindow?(startDate: string, endDate: string): Promise<Match[]>;
+    /**
+     * Optional authoritative group tables (cumulative across the group stage).
+     * Returned in standings order per group. Providers that can't supply a real
+     * table omit this; callers then fall back (degraded) to a roster at zero —
+     * never a wrong, partial table computed from a narrow live window.
+     */
+    fetchStandings?(): Promise<GroupStandings[]>;
     /** Optional push subscription (websocket/SSE providers). Returns an unsubscribe fn. */
     subscribe?(onBatch: (matches: Match[]) => void): () => void;
 }
@@ -375,6 +387,34 @@ interface EspnAdapterOptions {
      */
     enrichGroups?: boolean;
 }
+interface EspnStandingsStat {
+    name?: string;
+    value?: number;
+}
+interface EspnStandingsEntry {
+    team?: EspnTeam;
+    stats?: EspnStandingsStat[];
+}
+interface EspnStandingsChild {
+    name?: string;
+    abbreviation?: string;
+    standings?: {
+        entries?: EspnStandingsEntry[];
+    };
+}
+interface EspnStandings {
+    children?: EspnStandingsChild[];
+}
+/**
+ * Parse the standings payload into group tables. Pure (exported for tests).
+ *
+ * Two non-obvious robustness points, both verified against the live response:
+ *  - ESPN's `entries` array is NOT in rank order, so we sort by the `rank` stat
+ *    (falling back to points → GD → GF → code when rank is absent).
+ *  - Non-group `children` (knockout brackets) are skipped by the "Group X" name
+ *    test, so this stays correct once the bracket phase begins.
+ */
+declare function parseStandings(data: EspnStandings): GroupStandings[];
 declare class EspnAdapter implements ProviderAdapter {
     private readonly opts;
     readonly name = "espn";
@@ -385,9 +425,18 @@ declare class EspnAdapter implements ProviderAdapter {
     fetchByDate(dateISO: string): Promise<Match[]>;
     fetchWindow(startDate: string, endDate: string): Promise<Match[]>;
     fetchLive(): Promise<Match[]>;
+    /** Standings endpoint URL (lives under apis/v2, not site/v2; derived from base). */
+    private standingsUrl;
+    /**
+     * 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}.
+     */
+    fetchStandings(): Promise<GroupStandings[]>;
     /**
      * Build (and cache) a team-code -> group-letter map from the standings
-     * endpoint. Best-effort: returns {} if standings are unavailable.
+     * endpoint. Best-effort: returns {} if standings are unavailable. Reuses the
+     * same parse as {@link fetchStandings}, so the two never drift.
      */
     fetchGroupMap(force?: boolean): Promise<Record<string, string>>;
     private fetchScoreboard;
@@ -427,6 +476,27 @@ declare function liveSourceLabel(source: string): string;
  * schedule on any provider/network error (graceful degradation).
  */
 declare function getMatchesForDate(adapter: ProviderAdapter, dateISO: string): Promise<LiveResult>;
+interface StandingsResult {
+    /** Group tables in group-letter order; each table's rows in standings order. */
+    tables: GroupStandings[];
+    /** True when no authoritative table was available and rows are a static roster. */
+    degraded: boolean;
+    /** The provider that served a real table (absent when degraded). */
+    source?: string;
+}
+/**
+ * Authoritative group tables, preferring the provider's cumulative standings and
+ * FAILING CLOSED to a roster-at-zero (degraded) when none is available.
+ *
+ * Deliberately does NOT compute a table from a live-match window: that silently
+ * drops earlier matchdays and reports a wrong, partial table (e.g. all-zeros for
+ * a group not playing today) — the bug this replaced. A degraded roster is
+ * honestly empty; a confidently-wrong table is the failure mode we refuse.
+ *
+ * An empty `tables` with `degraded: false` means the fetch succeeded but the
+ * asked-for group isn't in it (caller renders "no such group").
+ */
+declare function getStandings(adapter: ProviderAdapter, group?: string): Promise<StandingsResult>;
 interface MatchByIdResult {
     match?: Match;
     degraded: boolean;
@@ -796,6 +866,14 @@ interface ShareSnippetInput {
     emptyNote?: string;
     /** Exact run cue to advertise, e.g. "npx @claudinho/cli next MEX". */
     installLine?: string;
+    /**
+     * True when the live fetch failed and these are static fixtures (no live
+     * scores). A pasted card must say so — otherwise a "no matches" / scheduled
+     * card reads as authoritative when the feed is actually down. When set with
+     * matches present, a not-live notice is appended; for the empty case the
+     * caller picks a feed-down `emptyNote`.
+     */
+    degraded?: boolean;
     /** Timezone for kickoff date/time (date/time only — copy stays English). */
     tz?: string;
     /** Locale for kickoff date/time. */
@@ -807,5 +885,32 @@ interface ShareSnippetInput {
  * line; lines within a block by a single newline.
  */
 declare function formatShareSnippet(input: ShareSnippetInput, options?: ShareSnippetOptions): string;
+interface ShareTableInput {
+    /** Group tables to render (1..n); each in standings order. */
+    tables: {
+        group: string;
+        rows: StandingRow[];
+    }[];
+    /** Live-data provider name for attribution; omit when degraded/static. */
+    source?: string;
+    /** Exact run cue, e.g. "npx @claudinho/cli table A". */
+    installLine?: string;
+    /** Body line when there are no tables (e.g. "No group Z."). */
+    emptyNote?: string;
+    /**
+     * True when the rows are a static roster (no live results), not an
+     * authoritative table. A shared card is pasted into public/social, so this
+     * MUST be surfaced — otherwise a roster-at-zero reads as a real "nobody has
+     * played yet" table. The card then carries an explicit not-live notice.
+     */
+    degraded?: boolean;
+}
+/**
+ * Render a shareable group-standings card. Pure, plain-text, deterministic. Like
+ * {@link formatShareSnippet} but for tables: facts + emoji flags only, no market
+ * lines (standings carry no market read), disclaimer non-optional, hashtag and
+ * run cue toggleable via {@link ShareSnippetOptions}.
+ */
+declare function formatShareTable(input: ShareTableInput, 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, 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 };
+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 GroupStandings, 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 ShareTableInput, type Stage, type StandingRow, type StandingsResult, type Status, type Team, allFixtures, asFlavorLevel, buildMarketSignal, byKickoff, competitionBase, computeStandings, countdown, currentOrNextFixtureForTeam, deriveFavorite, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, formatDate, formatKickoff, formatShareSnippet, formatShareTable, formatTime, getLiveMatches, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getStandings, 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, parseStandings, resolveCompetition, resolveMarketSource, resolveTz, scoreline };

package/dist/index.js

@@ -2787,6 +2787,43 @@ function mapEspnEvent(ev, ctx = {}) {
 function toEspnDate(d) {
   return d.replace(/\D/g, "").slice(0, 8);
 }
+function statVal(stats, name) {
+  const v = stats?.find((s) => s.name === name)?.value;
+  return typeof v === "number" && Number.isFinite(v) ? Math.round(v) : 0;
+}
+function entryToRow(e) {
+  return {
+    team: toTeam(e.team),
+    played: statVal(e.stats, "gamesPlayed"),
+    won: statVal(e.stats, "wins"),
+    drawn: statVal(e.stats, "ties"),
+    lost: statVal(e.stats, "losses"),
+    goalsFor: statVal(e.stats, "pointsFor"),
+    goalsAgainst: statVal(e.stats, "pointsAgainst"),
+    goalDiff: statVal(e.stats, "pointDifferential"),
+    points: statVal(e.stats, "points")
+  };
+}
+function parseStandings(data) {
+  const out = [];
+  for (const child of data.children ?? []) {
+    const letter = (child.name ?? child.abbreviation ?? "").match(/Group\s+([A-L])/i)?.[1]?.toUpperCase();
+    if (!letter) continue;
+    const ranked = (child.standings?.entries ?? []).map((e) => ({
+      row: entryToRow(e),
+      rank: statVal(e.stats, "rank")
+    }));
+    ranked.sort((a, b) => {
+      if (a.rank && b.rank && a.rank !== b.rank) return a.rank - b.rank;
+      const r = a.row;
+      const s = b.row;
+      return s.points - r.points || s.goalDiff - r.goalDiff || s.goalsFor - r.goalsFor || r.team.code.localeCompare(s.team.code);
+    });
+    out.push({ group: letter, rows: ranked.map((x) => x.row) });
+  }
+  out.sort((a, b) => a.group.localeCompare(b.group));
+  return out;
+}
 var EspnAdapter = class {
   constructor(opts = {}) {
     this.opts = opts;
@@ -2806,25 +2843,30 @@ var EspnAdapter = class {
     const today = await this.fetchScoreboard();
     return today.filter((m) => m.status === "LIVE" || m.status === "HT");
   }
+  /** Standings endpoint URL (lives under apis/v2, not site/v2; derived from base). */
+  standingsUrl() {
+    const base = this.opts.baseUrl ?? DEFAULT_BASE;
+    return `${base.replace("/apis/site/v2/", "/apis/v2/")}/standings`;
+  }
+  /**
+   * 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()));
+  }
   /**
    * Build (and cache) a team-code -> group-letter map from the standings
-   * endpoint. Best-effort: returns {} if standings are unavailable.
+   * endpoint. Best-effort: returns {} if standings are unavailable. Reuses the
+   * same parse as {@link fetchStandings}, so the two never drift.
    */
   async fetchGroupMap(force = false) {
     if (this.groupMap && !force) return this.groupMap;
-    const base = this.opts.baseUrl ?? DEFAULT_BASE;
-    const standingsUrl = `${base.replace("/apis/site/v2/", "/apis/v2/")}/standings`;
     const map = {};
     try {
-      const data = await this.get(standingsUrl);
-      for (const child of data.children ?? []) {
-        const letter = (child.name ?? child.abbreviation ?? "").match(/Group\s+([A-L])/i)?.[1]?.toUpperCase();
-        if (!letter) continue;
-        for (const e of child.standings?.entries ?? []) {
-          const code = e.team?.abbreviation?.toUpperCase();
-          if (code) map[code] = letter;
-        }
-      }
+      const tables = parseStandings(await this.get(this.standingsUrl()));
+      for (const t of tables) for (const r of t.rows) map[r.team.code] = t.group;
     } catch {
     }
     this.groupMap = map;
@@ -2897,6 +2939,22 @@ async function getMatchesForDate(adapter, dateISO) {
     return { matches: base, degraded: true };
   }
 }
+async function getStandings(adapter, group) {
+  const want = group?.toUpperCase();
+  if (adapter.fetchStandings) {
+    try {
+      const all = await adapter.fetchStandings();
+      const tables2 = (want ? all.filter((t) => t.group === want) : all).sort(
+        (a, b) => a.group.localeCompare(b.group)
+      );
+      return { tables: tables2, degraded: false, source: adapter.name };
+    } catch {
+    }
+  }
+  const letters = want ? [want] : groups();
+  const tables = letters.map((g) => ({ group: g, rows: computeStandings(fixturesByGroup(g)) })).filter((t) => t.rows.length > 0);
+  return { tables, degraded: true };
+}
 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);
@@ -3450,11 +3508,53 @@ function formatShareSnippet(input, options = {}) {
       blocks.push(card.join("\n"));
     }
   }
+  if (input.degraded && input.matches.length > 0) {
+    blocks.push("(Live data unavailable \u2014 showing the bundled schedule, not live scores.)");
+  }
+  blocks.push(
+    shareFooter({
+      source: input.source,
+      installLine: input.installLine,
+      includeHashtag,
+      includeInstall
+    })
+  );
+  return blocks.join("\n\n");
+}
+function shareFooter(opts) {
   const footer = [];
-  if (input.source) footer.push(`Live data: ${liveSourceLabel(input.source)}`);
-  footer.push([includeHashtag ? SHARE_HASHTAG : "", SHARE_DISCLAIMER].filter(Boolean).join(" \xB7 "));
-  if (includeInstall && input.installLine) footer.push(`Try it: ${input.installLine}`);
-  blocks.push(footer.join("\n"));
+  if (opts.source) footer.push(`Live data: ${liveSourceLabel(opts.source)}`);
+  footer.push(
+    [opts.includeHashtag ? SHARE_HASHTAG : "", SHARE_DISCLAIMER].filter(Boolean).join(" \xB7 ")
+  );
+  if (opts.includeInstall && opts.installLine) footer.push(`Try it: ${opts.installLine}`);
+  return footer.join("\n");
+}
+function gd(n) {
+  return n > 0 ? `+${n}` : `${n}`;
+}
+function tableRow(r, rank) {
+  return `${rank}. ${r.team.flag} ${r.team.code}  ${r.points} pts \xB7 ${r.won}-${r.drawn}-${r.lost} \xB7 ${gd(r.goalDiff)}`;
+}
+function formatShareTable(input, options = {}) {
+  const includeHashtag = options.includeHashtag !== false;
+  const includeInstall = options.includeInstallLine !== false;
+  const blocks = [];
+  if (input.tables.length === 0) {
+    blocks.push(input.emptyNote ?? "No standings available.");
+  } else {
+    for (const { group, rows } of input.tables) {
+      blocks.push(
+        [`Group ${group} \xB7 standings`, "", ...rows.map((r, i) => tableRow(r, i + 1))].join("\n")
+      );
+    }
+    if (input.degraded) {
+      blocks.push("(Live standings unavailable \u2014 group roster, not live results.)");
+    }
+  }
+  blocks.push(
+    shareFooter({ source: input.source, installLine: input.installLine, includeHashtag, includeInstall })
+  );
   return blocks.join("\n\n");
 }
 export {
@@ -3486,12 +3586,14 @@ export {
   formatDate,
   formatKickoff,
   formatShareSnippet,
+  formatShareTable,
   formatTime,
   getLiveMatches,
   getMarketSignal,
   getMarketSignals,
   getMatchById,
   getMatchesForDate,
+  getStandings,
   groups,
   hasSaneDistribution,
   isFinished,
@@ -3523,6 +3625,7 @@ export {
   nextFixtureForTeam,
   normalizeOutcomes,
   outcomeFromScore,
+  parseStandings,
   resolveCompetition,
   resolveMarketSource,
   resolveTz,

package/package.json

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