@claudinho/core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arturo Garrido
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @claudinho/core ⚽
+
+Shared domain model, data-provider adapters, and helpers for **Claudinho** —
+the 2026 men's football tournament in your dev environment. This is the engine
+behind [`@claudinho/cli`](https://www.npmjs.com/package/@claudinho/cli) and
+[`@claudinho/mcp`](https://www.npmjs.com/package/@claudinho/mcp).
+
+> ⚠️ **Not affiliated with, endorsed by, or connected to FIFA or Anthropic.**
+> An independent, open-source fan project. Facts + emoji flags only.
+
+## Install
+
+```bash
+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
+- **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)
+- **Helpers** — emoji flags (`nationToFlag`), TZ-aware time (`formatKickoff`, `countdown`, `localDate`), location strings (`matchLocation`), localized commentary flair (`matchFlavor` / `FlavorLevel`), validators (`isValidDate`, `isValidTimeZone`)
+
+## Example
+
+```ts
+import { allFixtures, nextFixtureForTeam, formatKickoff } from '@claudinho/core';
+
+const next = nextFixtureForTeam('MEX');
+console.log(next?.home.flag, 'vs', next?.away.flag,
+  formatKickoff(next!.kickoff, { tz: 'America/Mexico_City', locale: 'es' }));
+```
+
+## License
+
+MIT © 2026 Arturo Garrido · [source & issues](https://github.com/arturogarrido/claudinho)
+
+---
+
+_Built while watching the games._ **#VibingLaVidaLoca** ⚽

package/dist/index.d.ts

@@ -0,0 +1,406 @@
+/**
+ * Claudinho domain model — the canonical, provider-agnostic shapes.
+ * Every data vendor maps INTO these types via a ProviderAdapter.
+ */
+/** A national team. `flag` is an emoji (no image assets, no copyright). */
+interface Team {
+    /** Short code, typically the FIFA/IOC 3-letter abbreviation (e.g. "MEX"). */
+    code: string;
+    /** Human-readable name (e.g. "Mexico"). */
+    name: string;
+    /** Emoji flag (e.g. "🇲🇽"). */
+    flag: string;
+}
+/**
+ * Tournament stage. "3P" is the third-place play-off. "FRIENDLY" is used for
+ * non-tournament fixtures (e.g. international friendlies) surfaced when the
+ * adapter points at a non-World-Cup competition.
+ */
+type Stage = 'GROUP' | 'R32' | 'R16' | 'QF' | 'SF' | '3P' | 'F' | 'FRIENDLY';
+/** Normalized match status across all providers. */
+type Status = 'SCHEDULED' | 'LIVE' | 'HT' | 'FT' | 'POSTPONED' | 'CANCELLED';
+/** Match outcome from the home team's perspective. */
+type Outcome = 'H' | 'D' | 'A';
+/** A discrete in-match event (provider-dependent; often absent on free tiers). */
+interface MatchEvent {
+    type: 'GOAL' | 'OWN_GOAL' | 'PEN' | 'YELLOW' | 'RED' | 'SUB';
+    minute: number;
+    teamCode: string;
+    player?: string;
+}
+/** A single fixture/result — the central entity. */
+interface Match {
+    /** Stable id (provider id for now; cross-provider keying comes later). */
+    id: string;
+    stage: Stage;
+    /** Group letter "A".."L" for the group stage; undefined for knockouts. */
+    group?: string;
+    /** Kickoff time, ISO 8601 in UTC (always ends in "Z"). */
+    kickoff: string;
+    venue: string;
+    /** Host city (e.g. "Mexico City"). Present when the provider supplies it. */
+    city?: string;
+    /** Host country (e.g. "Mexico"). Present when the provider supplies it. */
+    country?: string;
+    home: Team;
+    away: Team;
+    /** Present once the match is no longer purely SCHEDULED. */
+    score?: {
+        home: number;
+        away: number;
+    };
+    /** Live match minute when in progress. */
+    minute?: number;
+    status: Status;
+    /** Goals/cards when the provider supplies them. */
+    events?: MatchEvent[];
+    /** When this snapshot was produced (ISO 8601). */
+    updatedAt: string;
+}
+/** The AI pundit's prediction for a fixture, localized. */
+interface PunditPick {
+    matchId: string;
+    lang: string;
+    scoreline: {
+        home: number;
+        away: number;
+    };
+    outcome: Outcome;
+    /** One-line rationale, localized. */
+    reason: string;
+    /** 0..1 self-reported confidence. */
+    confidence: number;
+    createdAt: string;
+}
+/** One scored row in the pundit accuracy ledger. */
+interface LedgerRow {
+    matchId: string;
+    predicted: {
+        home: number;
+        away: number;
+        outcome: Outcome;
+    };
+    actual: {
+        home: number;
+        away: number;
+        outcome: Outcome;
+    };
+    exactHit: boolean;
+    outcomeHit: boolean;
+    /** Brier score component for the outcome prediction. */
+    brier: number;
+}
+
+/**
+ * Emoji flags from country identifiers — zero image assets, no copyright,
+ * render natively almost everywhere.
+ *
+ * Region codes are ISO 3166-1 alpha-2 (e.g. "MX"), with three special
+ * subdivision codes for the home nations ("GB-SCT", "GB-ENG", "GB-WLS")
+ * which use emoji tag sequences rather than regional-indicator pairs.
+ */
+/**
+ * Convert a region code to an emoji flag.
+ * - "MX" -> 🇲🇽
+ * - "GB-SCT" -> 🏴 (Scotland subdivision flag)
+ * Returns the neutral flag for anything unrecognized.
+ */
+declare function flagEmoji(region: string): string;
+/**
+ * Resolve a flag emoji from a nation name or code.
+ * Tries the name table first (ESPN reliably provides display names),
+ * then the 3-letter code table, then a programmatic Intl reverse-lookup.
+ * Falls back to the neutral flag.
+ */
+declare function nationToFlag(nameOrCode: string | undefined | null): string;
+/**
+ * Resolve a region code (alpha-2 / subdivision) from a nation name or code.
+ * Order: curated name table → 3-letter code table → Intl reverse-lookup.
+ */
+declare function nationToRegion(nameOrCode: string | undefined | null): string | undefined;
+
+/**
+ * Resolve the effective timezone: explicit arg > CLAUDINHO_TZ env > system.
+ *
+ * Crucially, an *invalid* candidate is skipped rather than returned, so a bad
+ * `--tz`/CLAUDINHO_TZ can never reach an Intl call and throw. The worst case is
+ * a silent fall back to the system zone (or undefined → runtime default).
+ * Callers that want to *tell* the user it was invalid should check
+ * `isValidTimeZone` themselves (the CLI does).
+ */
+declare function resolveTz(explicit?: string): string | undefined;
+interface FormatOpts {
+    tz?: string;
+    locale?: string;
+}
+/** Format a kickoff like "Thu 19:00" in the target timezone/locale. */
+declare function formatKickoff(iso: string, opts?: FormatOpts): string;
+/** Compact human countdown until kickoff: "3d4h", "2h10m", "45m", or "now". */
+declare function countdown(iso: string, from?: Date): string;
+/** The calendar date (YYYY-MM-DD) of a kickoff in the target timezone. */
+declare function localDate(iso: string, tz?: string): string;
+
+/**
+ * Small input validators shared across clients. Pure, dependency-free, and
+ * safe in Node and Workers.
+ */
+/** True if `tz` is an IANA timezone the runtime accepts (e.g. "America/Mexico_City"). */
+declare function isValidTimeZone(tz: string | undefined | null): boolean;
+/**
+ * True if `s` is a real calendar date in strict `YYYY-MM-DD` form. Rejects
+ * malformed strings AND impossible dates that JS would otherwise roll over
+ * (e.g. "2026-02-30").
+ */
+declare function isValidDate(s: string | undefined | null): boolean;
+
+/** Outcome (home perspective) from a final/looking scoreline. */
+declare function outcomeFromScore(home: number, away: number): Outcome;
+/** Is the match currently in play (including halftime)? */
+declare function isLive(status: Status): boolean;
+/** Has the match finished in regulation/normal completion? */
+declare function isFinished(status: Status): boolean;
+/** Compact scoreline string, e.g. "1–0" (en dash) or "vs" when unscored. */
+declare function scoreline(match: Match): string;
+/**
+ * Human-readable location: venue plus city/country when the provider supplies
+ * them, e.g. "Estadio Banorte, Mexico City, Mexico". Keeping this in one place
+ * means the CLI and MCP surfaces stay consistent — and gives the model an
+ * unambiguous city so it never has to guess one.
+ */
+declare function matchLocation(match: Match): string;
+/** Sort comparator by kickoff time, ascending. */
+declare function byKickoff(a: Match, b: Match): number;
+
+/**
+ * Commentary "flavor" — a small, localized layer of football-broadcast energy
+ * that lets surfaces (and the model) narrate scores with some spice.
+ *
+ * IMPORTANT (legal): these are GENERIC, unattributed exclamations that evoke the
+ * *genre* of football commentary (with a Latin-American TV spirit for `es`).
+ * They must NEVER quote, name, or impersonate a real commentator or reproduce a
+ * person's signature catchphrase. Keep it that way when extending the banks.
+ */
+
+/** Commentary-flair intensity. */
+type FlavorLevel = 'off' | 'subtle' | 'full';
+declare const FLAVOR_LEVELS: readonly ["off", "subtle", "full"];
+/** Spice is on by default — the project ships `full`. */
+declare const DEFAULT_FLAVOR: FlavorLevel;
+declare function isFlavorLevel(s: string): s is FlavorLevel;
+/** Coerce arbitrary input (flag/env) to a level, defaulting to `full`. */
+declare function asFlavorLevel(s: string | undefined | null): FlavorLevel;
+/**
+ * A short, localized exclamation for a match's moment — or '' when the level or
+ * moment calls for restraint. Deterministic per match id. Never quotes a person.
+ */
+declare function matchFlavor(m: Match, opts?: {
+    level?: FlavorLevel;
+    locale?: string;
+}): string;
+
+/** The full bundled fixture list. */
+declare function allFixtures(): Match[];
+/**
+ * Fixtures on a given calendar date ("YYYY-MM-DD"), grouped in the caller's
+ * timezone (`tz`; defaults to env/system via `resolveTz`).
+ *
+ * Grouping uses the *local* date — the same zone the UI shows the weekday in —
+ * so a late-UTC kickoff (e.g. `01:00Z`, which is the previous evening in the
+ * Americas) lands on the day the user actually experiences it. Filtering on the
+ * raw UTC date instead would put it under a header whose weekday contradicts the
+ * one rendered for the match (e.g. a Friday match shown under Saturday's date).
+ */
+declare function fixturesByDate(dateISO: string, fixtures?: Match[], tz?: string): Match[];
+/** All fixtures involving a team code (case-insensitive). */
+declare function fixturesByTeam(code: string, fixtures?: Match[]): Match[];
+/** All fixtures in a group letter ("A".."L"). */
+declare function fixturesByGroup(group: string, fixtures?: Match[]): Match[];
+/** The next upcoming fixture for a team at/after `from` (default now). */
+declare function nextFixtureForTeam(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[];
+
+/** One row of a group table. */
+interface StandingRow {
+    team: Team;
+    played: number;
+    won: number;
+    drawn: number;
+    lost: number;
+    goalsFor: number;
+    goalsAgainst: number;
+    goalDiff: number;
+    points: number;
+}
+/**
+ * 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
+ * finished matches with a score contribute to the tally.
+ *
+ * Sort: points, then goal difference, then goals for, then name. (Real FIFA
+ * tiebreakers add head-to-head and fair-play; this is the standard simplified
+ * ordering used for display.)
+ */
+declare function computeStandings(matches: Match[]): StandingRow[];
+
+/** Capabilities a provider advertises so callers can pick a strategy. */
+interface ProviderCapabilities {
+    /** True if the provider can push events (websocket/SSE) vs poll-only. */
+    push: boolean;
+    /** Rough event->feed latency hint, in seconds (for poll-cadence tuning). */
+    latencyHintSec: number;
+}
+/**
+ * The single swap-point for data vendors. Every provider (ESPN, API-Football,
+ * Goalserve, …) implements this and maps INTO the canonical Match model, so the
+ * vendor choice stays a one-module decision.
+ */
+interface ProviderAdapter {
+    readonly name: string;
+    readonly capabilities: ProviderCapabilities;
+    /** All fixtures/results for a single calendar date (provider's timezone semantics). */
+    fetchByDate(dateISO: string): Promise<Match[]>;
+    /** Currently in-progress matches (poll path). */
+    fetchLive(): Promise<Match[]>;
+    /** Optional inclusive date-range fetch (used for schedule generation). */
+    fetchWindow?(startDate: string, endDate: string): Promise<Match[]>;
+    /** Optional push subscription (websocket/SSE providers). Returns an unsubscribe fn. */
+    subscribe?(onBatch: (matches: Match[]) => void): () => void;
+}
+
+/**
+ * ESPN adapter — the free, keyless default/fallback source.
+ *
+ * Uses ESPN's unofficial public scoreboard endpoint:
+ *   https://site.api.espn.com/apis/site/v2/sports/soccer/fifa.world/scoreboard
+ *
+ * Undocumented and unguaranteed — but confirmed to return real 2026 fixtures
+ * (teams, ISO-UTC kickoffs, venues, status). The SCHEDULED/FT mapping is
+ * verified against live data; the in-play minute/score path is best-effort and
+ * should be re-verified during an actual live match.
+ */
+
+/** Default competition slug (the 2026 World Cup). */
+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;
+interface EspnStatusType {
+    name?: string;
+    state?: string;
+    completed?: boolean;
+    shortDetail?: string;
+}
+interface EspnStatus {
+    type?: EspnStatusType;
+    clock?: number;
+    displayClock?: string;
+    period?: number;
+}
+interface EspnTeam {
+    abbreviation?: string;
+    displayName?: string;
+    shortDisplayName?: string;
+    name?: string;
+    location?: string;
+}
+interface EspnCompetitor {
+    homeAway?: 'home' | 'away';
+    score?: string;
+    winner?: boolean;
+    team?: EspnTeam;
+}
+interface EspnCompetition {
+    id?: string;
+    date?: string;
+    competitors?: EspnCompetitor[];
+    venue?: {
+        fullName?: string;
+        address?: {
+            city?: string;
+            country?: string;
+        };
+    };
+    status?: EspnStatus;
+}
+interface EspnSeason {
+    year?: number;
+    slug?: string;
+}
+interface EspnEvent {
+    id: string;
+    date: string;
+    name?: string;
+    shortName?: string;
+    season?: EspnSeason;
+    status?: EspnStatus;
+    competitions?: EspnCompetition[];
+}
+/** Optional context to enrich mapping (authoritative team->group letter). */
+interface MapContext {
+    /** Map of UPPERCASE team code -> group letter ("A".."L"), from standings. */
+    groupByTeam?: Record<string, string>;
+}
+/** Map a single ESPN event into the canonical Match model. Exported for tests. */
+declare function mapEspnEvent(ev: EspnEvent, ctx?: MapContext): Match;
+interface EspnAdapterOptions {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    /**
+     * Enrich group-stage matches with their group letter via the standings
+     * endpoint (one extra request). Default true. Set false on the hot live-poll
+     * path, where group letters aren't needed and the extra call is wasteful.
+     */
+    enrichGroups?: boolean;
+}
+declare class EspnAdapter implements ProviderAdapter {
+    private readonly opts;
+    readonly name = "espn";
+    readonly capabilities: ProviderCapabilities;
+    /** Cached team-code -> group-letter map (built lazily from standings). */
+    private groupMap?;
+    constructor(opts?: EspnAdapterOptions);
+    fetchByDate(dateISO: string): Promise<Match[]>;
+    fetchWindow(startDate: string, endDate: string): Promise<Match[]>;
+    fetchLive(): Promise<Match[]>;
+    /**
+     * Build (and cache) a team-code -> group-letter map from the standings
+     * endpoint. Best-effort: returns {} if standings are unavailable.
+     */
+    fetchGroupMap(force?: boolean): Promise<Record<string, string>>;
+    private fetchScoreboard;
+    private get;
+}
+
+/**
+ * The ESPN competition slug to fetch live state from. Defaults to the 2026
+ * World Cup (`fifa.world`); override with CLAUDINHO_COMPETITION (e.g.
+ * `fifa.friendly` to follow international friendlies during pre-tournament
+ * testing). Only affects the *live* fetch — the bundled static schedule is
+ * always the World Cup.
+ */
+declare function resolveCompetition(explicit?: string): string;
+/** Construct a provider adapter for a `--source` name (default: espn). */
+declare function makeAdapter(source?: string): ProviderAdapter;
+/**
+ * Merge live matches over a base set by id. Live entries replace base entries
+ * with the same id; unknown ids are appended.
+ */
+declare function mergeLive(base: Match[], live: Match[]): Match[];
+interface LiveResult {
+    matches: Match[];
+    /** True when the provider call failed and we fell back to static data. */
+    degraded: boolean;
+}
+/**
+ * Matches for a date, preferring live provider data, falling back to the static
+ * schedule on any provider/network error (graceful degradation).
+ */
+declare function getMatchesForDate(adapter: ProviderAdapter, dateISO: string): Promise<LiveResult>;
+/** Currently-live matches; empty + degraded on error. */
+declare function getLiveMatches(adapter: ProviderAdapter): Promise<LiveResult>;
+
+export { DEFAULT_COMPETITION, DEFAULT_FLAVOR, EspnAdapter, type EspnAdapterOptions, FLAVOR_LEVELS, type FlavorLevel, type FormatOpts, type LedgerRow, type LiveResult, type MapContext, type Match, type MatchEvent, type Outcome, type ProviderAdapter, type ProviderCapabilities, type PunditPick, type Stage, type StandingRow, type Status, type Team, allFixtures, asFlavorLevel, byKickoff, competitionBase, computeStandings, countdown, fixturesByDate, fixturesByGroup, fixturesByTeam, flagEmoji, formatKickoff, getLiveMatches, getMatchesForDate, groups, isFinished, isFlavorLevel, isLive, isValidDate, isValidTimeZone, localDate, makeAdapter, mapEspnEvent, matchFlavor, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, outcomeFromScore, resolveCompetition, resolveTz, scoreline };