@claudinho/core 0.7.0 → 0.8.1

package/dist/index.d.ts

@@ -54,6 +54,11 @@ interface Match {
     status: Status;
     /** Goals/cards when the provider supplies them. */
     events?: MatchEvent[];
+    /**
+     * Winner's team code when the provider marks one (e.g. ESPN `competitor.winner`
+     * after penalties). Used for knockout advancement when the score is level.
+     */
+    winnerCode?: string;
     /** When this snapshot was produced (ISO 8601). */
     updatedAt: string;
 }
@@ -119,6 +124,15 @@ declare function nationToFlag(nameOrCode: string | undefined | null): string;
  */
 declare function nationToRegion(nameOrCode: string | undefined | null): string | undefined;
 
+/** Supported UI locales — same set as CLI/MCP `lang`. */
+type Lang = 'en' | 'es' | 'pt' | 'fr';
+/** Normalize MCP/CLI `lang` to a supported catalog (falls back to English). */
+declare function normalizeLang(lang?: string): Lang;
+/** Translate a message key with optional `{placeholder}` interpolation. */
+declare function t(lang: string | undefined, key: string, vars?: Record<string, string>): string;
+/** Localized knockout/group stage label for bracket rendering. */
+declare function stageLabelI18n(lang: string | undefined, stage: string, group?: string): string;
+
 /**
  * Resolve the effective timezone: explicit arg > CLAUDINHO_TZ env > system.
  *
@@ -204,13 +218,86 @@ declare function matchFlavor(m: Match, opts?: {
     locale?: string;
 }): string;
 
+/** A participant slot in the bundled bracket topology (pre-resolution). */
+type SlotRef = {
+    kind: 'group';
+    position: 1 | 2;
+    group: string;
+} | {
+    kind: 'third';
+    groups: string[];
+} | {
+    kind: 'winner';
+    stage: Stage;
+    index: number;
+} | {
+    kind: 'loser';
+    stage: Stage;
+    index: number;
+}
+/** ESPN pre-draw nation label — display only; never confirmed from the bundled schedule. */
+ | {
+    kind: 'seed';
+    label: string;
+    code: string;
+};
+interface BracketMatchNode {
+    matchId: string;
+    stage: Stage;
+    /** 1-based index within the stage, ordered by kickoff. */
+    index: number;
+    home: SlotRef;
+    away: SlotRef;
+}
+interface BracketTopology {
+    generatedAt: string;
+    stages: Stage[];
+    matches: BracketMatchNode[];
+}
+/** Knockout rounds in display order (3P before the final). */
+declare const BRACKET_STAGE_ORDER: Stage[];
+type SlotStatus = 'confirmed' | 'projected' | 'tbd';
+/** A resolved bracket participant for display. */
+interface ResolvedParticipant {
+    label: string;
+    flag: string;
+    code?: string;
+    status: SlotStatus;
+}
+interface BracketMatchView {
+    matchId: string;
+    stage: Stage;
+    index: number;
+    kickoff: string;
+    home: ResolvedParticipant;
+    away: ResolvedParticipant;
+    match: Match;
+}
+interface BracketStageView {
+    stage: Stage;
+    label: string;
+    matches: BracketMatchView[];
+}
+interface BracketView {
+    stages: BracketStageView[];
+    degraded: boolean;
+    standingsDegraded: boolean;
+    source?: string;
+}
+interface BracketResult {
+    view: BracketView;
+    degraded: boolean;
+    standingsDegraded: boolean;
+    source?: string;
+}
+
 /**
  * Strip live/final state from a fixture for the bundled skeleton schedule.
  * The JSON ships kickoffs, teams, venues, and bracket structure only — never
  * results. Live scores come from the provider overlay; degraded standings use
  * roster-at-zero, not a stale snapshot table.
  */
-declare function sanitizeBundledFixture(m: Match): Match;
+declare function sanitizeBundledFixture(m: Match, node?: BracketMatchNode): Match;
 /** The full bundled fixture list. */
 declare function allFixtures(): Match[];
 /**
@@ -512,6 +599,14 @@ interface StandingsResult {
  * asked-for group isn't in it (caller renders "no such group").
  */
 declare function getStandings(adapter: ProviderAdapter, group?: string): Promise<StandingsResult>;
+/**
+ * Knockout bracket with hybrid slot resolution: confirmed FT winners/losers from
+ * the live overlay; group slots project only when the group is fully played.
+ */
+declare function getBracket(adapter: ProviderAdapter, opts?: {
+    stage?: Stage;
+    lang?: string;
+}): Promise<BracketResult>;
 interface MatchByIdResult {
     match?: Match;
     degraded: boolean;
@@ -940,4 +1035,66 @@ interface ShareTableInput {
  */
 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, 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, sanitizeBundledFixture, scoreline, stageLabel };
+declare function matchKey(stage: Stage, index: number): string;
+/**
+ * Build and validate bracket topology from knockout fixtures.
+ * Throws when ESPN introduces an unparsed placeholder or the graph is inconsistent.
+ */
+declare function buildBracketTopology(matches: Match[], generatedAt: string): BracketTopology;
+
+/**
+ * Parse an ESPN home/away label into a bracket slot reference (name patterns only).
+ * Real nation flags are mapped to `seed` — never `team` — so the bundled schedule
+ * cannot treat ESPN pre-draw labels as confirmed participants.
+ */
+declare function parseTeamSlot(team: Team): SlotRef | null;
+
+/**
+ * Resolve the bundled topology against merged knockout matches and standings.
+ * Group slots project only when the group is fully played; winner/loser slots
+ * require a confirmed FT result on the source match.
+ */
+declare function buildBracketView(topology: BracketTopology, matches: Match[], tables: GroupStandings[], standingsDegraded: boolean, liveDegraded: boolean, filterStage?: string, lang?: string): BracketView;
+
+/** The bundled knockout bracket topology (generated by gen:schedule). */
+declare function loadBracketTopology(): BracketTopology;
+
+interface BracketFormatOpts {
+    flags?: boolean;
+    tz?: string;
+    locale?: string;
+}
+/** One bracket match line for list or tree output. */
+declare function formatBracketMatchLine(mv: BracketMatchView, opts?: BracketFormatOpts): string;
+/** Staged list view — default bracket renderer. */
+declare function formatBracketList(view: BracketView, opts?: BracketFormatOpts & {
+    footer?: boolean;
+}): string;
+/**
+ * ASCII bracket with stage connectors. Returns null when the terminal is too narrow —
+ * callers should fall back to {@link formatBracketList}.
+ */
+declare function formatBracketTree(view: BracketView, opts?: BracketFormatOpts & {
+    width?: number;
+    footer?: boolean;
+}): string | null;
+interface ShareBracketInput {
+    view: BracketView;
+    source?: string;
+    installLine?: string;
+    emptyNote?: string;
+}
+interface ShareBracketOptions {
+    includeHashtag?: boolean;
+    includeInstallLine?: boolean;
+    stage?: Stage;
+    locale?: string;
+    tz?: string;
+    style?: ShareStyle;
+}
+/** Plain-text share card for the knockout bracket. */
+declare function formatShareBracket(input: ShareBracketInput, options?: ShareBracketOptions): string;
+/** 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 };