@claudinho/core 0.3.0 → 0.4.0

package/README.md

@@ -22,8 +22,9 @@ npm i @claudinho/core
 - **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`)
+- **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 odds 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.
 
 ## Example
 

package/dist/index.d.ts

@@ -135,6 +135,10 @@ interface FormatOpts {
 }
 /** Format a kickoff like "Thu 19:00" in the target timezone/locale. */
 declare function formatKickoff(iso: string, opts?: FormatOpts): string;
+/** A short calendar date like "Jun 11" in the target timezone/locale. */
+declare function formatDate(iso: string, opts?: FormatOpts): string;
+/** Time of day like "19:00" (24-hour) in the target timezone/locale. */
+declare function formatTime(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. */
@@ -709,4 +713,54 @@ declare class PolymarketProvider implements MarketProvider {
     private toSignal;
 }
 
-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, type Stage, type StandingRow, type Status, type Team, allFixtures, asFlavorLevel, buildMarketSignal, byKickoff, competitionBase, computeStandings, countdown, deriveFavorite, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, flagEmoji, formatKickoff, 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 };
+/** The two v1 snippet shapes. `social` is the rich card; `compact` is one terse line per match. */
+type ShareStyle = 'compact' | 'social';
+/** The project social tag — a distribution unit, default-on but removable. */
+declare const SHARE_HASHTAG = "#VibingLaVidaLoca";
+/**
+ * The non-affiliation line. Non-optional in every snippet: a shared artifact is
+ * decontextualized, so the legal disclaimer must travel with every paste.
+ */
+declare const SHARE_DISCLAIMER = "Independent fan project \u00B7 not affiliated with FIFA or Anthropic.";
+interface ShareSnippetOptions {
+    /** Snippet shape; defaults to `social`. */
+    style?: ShareStyle;
+    /** Include the reliable market block/line when a signal is present (default true). */
+    includeMarkets?: boolean;
+    /** Include the #VibingLaVidaLoca tag (default true). */
+    includeHashtag?: boolean;
+    /** Include the "Try it: …" install/run cue (default true). */
+    includeInstallLine?: boolean;
+}
+interface ShareSnippetInput {
+    /** Pre-resolved, English title line, e.g. "Next up for Mexico". */
+    title: string;
+    /** Matches to render (0..n). An empty set still yields a valid titled card. */
+    matches: Match[];
+    /**
+     * Reliable, display-ready market signals keyed by match id (sidecar — never
+     * embedded in Match). Callers gate these; the formatter only renders.
+     */
+    marketSignals?: Map<string, MarketSignal>;
+    /** Live-data provider name (e.g. "espn") for attribution; omit when static/degraded. */
+    source?: string;
+    /**
+     * Body line shown when `matches` is empty (e.g. "No upcoming fixture found for
+     * ZZZ."), so an unknown/empty target yields a clear card instead of a void.
+     */
+    emptyNote?: string;
+    /** Exact run cue to advertise, e.g. "npx @claudinho/cli next MEX". */
+    installLine?: string;
+    /** Timezone for kickoff date/time (date/time only — copy stays English). */
+    tz?: string;
+    /** Locale for kickoff date/time. */
+    locale?: string;
+}
+/**
+ * Render a shareable snippet. Pure and deterministic: identical input yields
+ * identical output. Blocks (title, each match, footer) are separated by a blank
+ * line; lines within a block by a single newline.
+ */
+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 };

package/dist/index.js

@@ -310,6 +310,25 @@ function formatKickoff(iso, opts = {}) {
     timeZone: tz
   }).format(new Date(iso));
 }
+function formatDate(iso, opts = {}) {
+  const tz = resolveTz(opts.tz);
+  const locale = safeLocale(opts.locale);
+  return new Intl.DateTimeFormat(locale, {
+    month: "short",
+    day: "numeric",
+    timeZone: tz
+  }).format(new Date(iso));
+}
+function formatTime(iso, opts = {}) {
+  const tz = resolveTz(opts.tz);
+  const locale = safeLocale(opts.locale);
+  return new Intl.DateTimeFormat(locale, {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    timeZone: tz
+  }).format(new Date(iso));
+}
 function countdown(iso, from = /* @__PURE__ */ new Date()) {
   const ms = new Date(iso).getTime() - from.getTime();
   if (ms <= 0) return "now";
@@ -3306,6 +3325,89 @@ async function getMarketSignals(provider, matches, options) {
     return { signals: /* @__PURE__ */ new Map(), checked: /* @__PURE__ */ new Set() };
   }
 }
+
+// src/share/format.ts
+var SHARE_HASHTAG = "#VibingLaVidaLoca";
+var SHARE_DISCLAIMER = "Independent fan project \xB7 not affiliated with FIFA or Anthropic.";
+function mid(m) {
+  return isLive(m.status) || m.status === "FT" ? scoreline(m) : "vs";
+}
+function statusTail(m) {
+  switch (m.status) {
+    case "LIVE":
+      return m.minute ? `${m.minute}'` : "LIVE";
+    case "HT":
+      return "HT";
+    case "FT":
+      return "FT";
+    case "POSTPONED":
+      return "postponed";
+    case "CANCELLED":
+      return "cancelled";
+    default:
+      return "";
+  }
+}
+function compactLine(m, input, single) {
+  const home = `${m.home.flag} ${m.home.code}`;
+  const away = `${m.away.code} ${m.away.flag}`;
+  const opts = { tz: input.tz, locale: input.locale };
+  let tail;
+  if (m.status === "SCHEDULED") {
+    const time = formatTime(m.kickoff, opts);
+    tail = single ? `${formatDate(m.kickoff, opts)} ${time}` : time;
+  } else {
+    tail = statusTail(m);
+  }
+  return `${home} ${mid(m)} ${away}${tail ? ` \xB7 ${tail}` : ""}`;
+}
+function socialCard(m, input) {
+  const lines = [];
+  const head = `${m.home.flag} ${m.home.name} ${mid(m)} ${m.away.name} ${m.away.flag}`;
+  if (m.status === "SCHEDULED") {
+    lines.push(head);
+    const date = formatDate(m.kickoff, { tz: input.tz, locale: input.locale });
+    const time = formatTime(m.kickoff, { tz: input.tz, locale: input.locale });
+    const zone = input.tz ? ` ${input.tz}` : "";
+    lines.push(`${date} \xB7 ${time}${zone}`);
+  } else {
+    const tail = statusTail(m);
+    lines.push(tail ? `${head} \xB7 ${tail}` : head);
+  }
+  const loc = matchLocation(m);
+  if (loc) lines.push(loc);
+  return lines;
+}
+function formatShareSnippet(input, options = {}) {
+  const style = options.style ?? "social";
+  const includeMarkets = options.includeMarkets !== false;
+  const includeHashtag = options.includeHashtag !== false;
+  const includeInstall = options.includeInstallLine !== false;
+  const signals = input.marketSignals ?? /* @__PURE__ */ new Map();
+  const single = input.matches.length === 1;
+  const blocks = [input.title];
+  if (input.matches.length === 0) {
+    if (input.emptyNote) blocks.push(input.emptyNote);
+  } else if (style === "compact") {
+    blocks.push(input.matches.map((m) => compactLine(m, input, single)).join("\n"));
+  } else {
+    for (const m of input.matches) {
+      const card = socialCard(m, input);
+      const sig = includeMarkets ? signals.get(m.id) : void 0;
+      if (sig) {
+        if (single) card.push("", ...marketBlock(sig, m));
+        else card.push(marketLine(sig, m));
+      }
+      blocks.push(card.join("\n"));
+    }
+  }
+  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"));
+  return blocks.join("\n\n");
+}
 export {
   DEFAULT_COMPETITION,
   DEFAULT_FLAVOR,
@@ -3314,6 +3416,8 @@ export {
   FLAVOR_LEVELS,
   FakeMarketProvider,
   PolymarketProvider,
+  SHARE_DISCLAIMER,
+  SHARE_HASHTAG,
   allFixtures,
   asFlavorLevel,
   buildMarketSignal,
@@ -3327,7 +3431,10 @@ export {
   fixturesByGroup,
   fixturesByTeam,
   flagEmoji,
+  formatDate,
   formatKickoff,
+  formatShareSnippet,
+  formatTime,
   getLiveMatches,
   getMarketSignal,
   getMarketSignals,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudinho/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Domain model, provider adapters, standings, and a read-only market-signal sidecar for Claudinho — the 2026 men's football tournament. Not affiliated with FIFA or Anthropic.",
   "type": "module",
   "license": "MIT",