fansunited-data-layer 0.18.0 → 0.18.3

package/README.md

@@ -43,6 +43,11 @@ const board = await getFansUnitedSportsCompetitionHydrated("fb:c:1", {
 });
 
 for (const stage of board.season.stages) {
+    // Stage-name labels are hydrated alongside competitors —
+    // entities.get(stageNameId) returns a localized FUSportsStageName.
+    const label = board.entities.get(stage.stageNameId);
+    console.log(`\n=== ${label?.name ?? stage.stageNameId} ===`);
+
     for (const group of stage.groups ?? []) {
         for (const entry of group.standings) {
             const team = board.entities.get(entry.competitorId);

package/api/fansunited/sports/competition/hydrated.d.ts

@@ -2,8 +2,13 @@
  * Hydrated wrapper for the Fans United Sports API competition endpoint.
  *
  * Composes the (cached) raw competition response with a (cached) batch
- * resolution of every entity ID in `meta.entityIds` via the Search API,
- * and returns one object the consumer can render directly.
+ * resolution of every referenced entity via the Search API, and returns one
+ * object the consumer can render directly. Hydration covers:
+ *   - everything listed in `meta.entityIds` (competitors, venues, …)
+ *   - every `stage.stageNameId` referenced by `season.stages[]`
+ *     ({@link FUSportsStageName}) — these are pulled from the response
+ *     structure because the upstream `meta.entity_ids` field has been
+ *     observed not to include them.
  *
  * Cache topology:
  *   - sports/competition response → cached under "sportsCompetition"
@@ -12,12 +17,23 @@
  *     by id only; the raw multi-locale payload serves every locale via
  *     transformEntity(raw, lang).
  *
- * @example
+ * @example Standings + localized stage labels
+ * ```ts
  * const data = await getFansUnitedSportsCompetitionHydrated("fb:c:1", { locale: "BG" });
- * for (const entry of data.season.stages[0].groups[0].standings) {
- *   const team = data.entities.get(entry.competitorId);
- *   console.log(`${entry.rank} ${team?.name}`);
+ *
+ * for (const stage of data.season.stages) {
+ *     // Stage name lookup — same shape as any other entity in the map.
+ *     const label = data.entities.get(stage.stageNameId);
+ *     console.log(`\n=== ${label?.name ?? stage.stageNameId} ===`);
+ *
+ *     for (const group of stage.groups ?? []) {
+ *         for (const entry of group.standings) {
+ *             const team = data.entities.get(entry.competitorId);
+ *             console.log(`${entry.rank} ${team?.name ?? entry.competitorId}`);
+ *         }
+ *     }
  * }
+ * ```
  */
 import type { FUSportsCompetitionDetails } from "../../../../types/canonical/sports-competition.types";
 import type { DataLayerConfig } from "../../../../config";
@@ -34,8 +50,13 @@ export interface GetSportsCompetitionHydratedOptions {
 /**
  * Sports API competition response plus a lookup map for every referenced entity.
  *
- * The map is keyed by entity ID. Missing IDs (404s from the Search API) are
- * silently omitted — render code should fall back gracefully on a missing entry:
+ * The map is keyed by entity ID and holds the localized {@link SearchEntityResult}
+ * union — competitors (teams/athletes), venues, countries, coaches, and
+ * stage-name labels (`FUSportsStageName & { entityType: "stageName" }`) for
+ * every `stage.stageNameId` referenced by `season.stages[]`.
+ *
+ * Missing IDs (404s from the Search API) are silently omitted — render code
+ * should fall back gracefully on a missing entry:
  *   `entities.get(id) ?? { name: id }`.
  */
 export interface FUSportsCompetitionHydrated extends FUSportsCompetitionDetails {

package/api/fansunited/sports/competition/hydrated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hydrated.d.ts","sourceRoot":"","sources":["../../../../../src/lib/api/fansunited/sports/competition/hydrated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sDAAsD,CAAC;AACvG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAI7D,MAAM,WAAW,mCAAmC;IAChD,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,2BAA4B,SAAQ,0BAA0B;IAC3E,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC7C;AAED,wBAAsB,sCAAsC,CACxD,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,mCAAmC,EAC7C,MAAM,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,2BAA2B,CAAC,CAsBtC"}
+{"version":3,"file":"hydrated.d.ts","sourceRoot":"","sources":["../../../../../src/lib/api/fansunited/sports/competition/hydrated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sDAAsD,CAAC;AACvG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAkB7D,MAAM,WAAW,mCAAmC;IAChD,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,2BAA4B,SAAQ,0BAA0B;IAC3E,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC7C;AAED,wBAAsB,sCAAsC,CACxD,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,mCAAmC,EAC7C,MAAM,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,2BAA2B,CAAC,CA0BtC"}

package/api/fansunited/sports/competition/hydrated.js

@@ -1,12 +1,21 @@
 import { getFansUnitedSportsCompetition } from "./index.js";
 import { getFansUnitedEntitiesByIds } from "../../search/index.js";
+function collectStageNameIds(details) {
+  const ids = [];
+  for (const stage of details.season.stages) {
+    if (stage.stageNameId) ids.push(stage.stageNameId);
+  }
+  return ids;
+}
 async function getFansUnitedSportsCompetitionHydrated(competitionId, options, config) {
   const raw = await getFansUnitedSportsCompetition(
     competitionId,
     { seasonId: options?.seasonId, next: options?.next },
     config
   );
-  const entityIds = raw.meta.entityIds;
+  const entityIds = Array.from(
+    /* @__PURE__ */ new Set([...raw.meta.entityIds, ...collectStageNameIds(raw)])
+  );
   const entities = /* @__PURE__ */ new Map();
   if (entityIds.length > 0) {
     const resolved = await getFansUnitedEntitiesByIds(entityIds, {

package/api/fansunited/sports/competition/hydrated.js.map

@@ -1 +1 @@
-{"version":3,"file":"hydrated.js","sources":["../../../../../src/lib/api/fansunited/sports/competition/hydrated.ts"],"sourcesContent":["/**\n * Hydrated wrapper for the Fans United Sports API competition endpoint.\n *\n * Composes the (cached) raw competition response with a (cached) batch\n * resolution of every entity ID in `meta.entityIds` via the Search API,\n * and returns one object the consumer can render directly.\n *\n * Cache topology:\n *   - sports/competition response → cached under \"sportsCompetition\"\n *     (5min stale / 1h max) by id+season.\n *   - search/entity responses     → cached under \"search\" (24h stale / 7d max)\n *     by id only; the raw multi-locale payload serves every locale via\n *     transformEntity(raw, lang).\n *\n * @example\n * const data = await getFansUnitedSportsCompetitionHydrated(\"fb:c:1\", { locale: \"BG\" });\n * for (const entry of data.season.stages[0].groups[0].standings) {\n *   const team = data.entities.get(entry.competitorId);\n *   console.log(`${entry.rank} ${team?.name}`);\n * }\n */\n\nimport type { FUSportsCompetitionDetails } from \"../../../../types/canonical/sports-competition.types\";\nimport type { DataLayerConfig } from \"../../../../config\";\nimport type { NextCacheOptions } from \"../../http\";\nimport type { SearchEntityResult } from \"../../search/types\";\nimport { getFansUnitedSportsCompetition } from \"./index\";\nimport { getFansUnitedEntitiesByIds } from \"../../search\";\n\nexport interface GetSportsCompetitionHydratedOptions {\n    /** Season identifier (e.g. \"fb:c:1:2025/26\"). Defaults to the active season. */\n    seasonId?: string;\n    /** Locale code (e.g. \"EN\", \"BG\") used to resolve entity translations. Falls back to EN. */\n    locale?: string;\n    /** Next.js cache options for ISR/on-demand revalidation. */\n    next?: NextCacheOptions;\n}\n\n/**\n * Sports API competition response plus a lookup map for every referenced entity.\n *\n * The map is keyed by entity ID. Missing IDs (404s from the Search API) are\n * silently omitted — render code should fall back gracefully on a missing entry:\n *   `entities.get(id) ?? { name: id }`.\n */\nexport interface FUSportsCompetitionHydrated extends FUSportsCompetitionDetails {\n    entities: Map<string, SearchEntityResult>;\n}\n\nexport async function getFansUnitedSportsCompetitionHydrated(\n    competitionId: string,\n    options?: GetSportsCompetitionHydratedOptions,\n    config?: DataLayerConfig\n): Promise<FUSportsCompetitionHydrated> {\n    const raw = await getFansUnitedSportsCompetition(\n        competitionId,\n        { seasonId: options?.seasonId, next: options?.next },\n        config\n    );\n\n    const entityIds = raw.meta.entityIds;\n    const entities = new Map<string, SearchEntityResult>();\n\n    if (entityIds.length > 0) {\n        const resolved = await getFansUnitedEntitiesByIds(entityIds, {\n            lang: options?.locale,\n            next: options?.next,\n            config,\n        });\n        for (const e of resolved) {\n            entities.set(e.id, e);\n        }\n    }\n\n    return { ...raw, entities };\n}\n"],"names":[],"mappings":";;AAiDA,eAAsB,uCAClB,eACA,SACA,QACoC;AACpC,QAAM,MAAM,MAAM;AAAA,IACd;AAAA,IACA,EAAE,UAAU,SAAS,UAAU,MAAM,SAAS,KAAA;AAAA,IAC9C;AAAA,EAAA;AAGJ,QAAM,YAAY,IAAI,KAAK;AAC3B,QAAM,+BAAe,IAAA;AAErB,MAAI,UAAU,SAAS,GAAG;AACtB,UAAM,WAAW,MAAM,2BAA2B,WAAW;AAAA,MACzD,MAAM,SAAS;AAAA,MACf,MAAM,SAAS;AAAA,MACf;AAAA,IAAA,CACH;AACD,eAAW,KAAK,UAAU;AACtB,eAAS,IAAI,EAAE,IAAI,CAAC;AAAA,IACxB;AAAA,EACJ;AAEA,SAAO,EAAE,GAAG,KAAK,SAAA;AACrB;"}
+{"version":3,"file":"hydrated.js","sources":["../../../../../src/lib/api/fansunited/sports/competition/hydrated.ts"],"sourcesContent":["/**\n * Hydrated wrapper for the Fans United Sports API competition endpoint.\n *\n * Composes the (cached) raw competition response with a (cached) batch\n * resolution of every referenced entity via the Search API, and returns one\n * object the consumer can render directly. Hydration covers:\n *   - everything listed in `meta.entityIds` (competitors, venues, …)\n *   - every `stage.stageNameId` referenced by `season.stages[]`\n *     ({@link FUSportsStageName}) — these are pulled from the response\n *     structure because the upstream `meta.entity_ids` field has been\n *     observed not to include them.\n *\n * Cache topology:\n *   - sports/competition response → cached under \"sportsCompetition\"\n *     (5min stale / 1h max) by id+season.\n *   - search/entity responses     → cached under \"search\" (24h stale / 7d max)\n *     by id only; the raw multi-locale payload serves every locale via\n *     transformEntity(raw, lang).\n *\n * @example Standings + localized stage labels\n * ```ts\n * const data = await getFansUnitedSportsCompetitionHydrated(\"fb:c:1\", { locale: \"BG\" });\n *\n * for (const stage of data.season.stages) {\n *     // Stage name lookup — same shape as any other entity in the map.\n *     const label = data.entities.get(stage.stageNameId);\n *     console.log(`\\n=== ${label?.name ?? stage.stageNameId} ===`);\n *\n *     for (const group of stage.groups ?? []) {\n *         for (const entry of group.standings) {\n *             const team = data.entities.get(entry.competitorId);\n *             console.log(`${entry.rank} ${team?.name ?? entry.competitorId}`);\n *         }\n *     }\n * }\n * ```\n */\n\nimport type { FUSportsCompetitionDetails } from \"../../../../types/canonical/sports-competition.types\";\nimport type { DataLayerConfig } from \"../../../../config\";\nimport type { NextCacheOptions } from \"../../http\";\nimport type { SearchEntityResult } from \"../../search/types\";\nimport { getFansUnitedSportsCompetition } from \"./index\";\nimport { getFansUnitedEntitiesByIds } from \"../../search\";\n\n/**\n * Stage-name IDs are referenced via {@link FUSportsCompetitionStage.stageNameId}\n * but the upstream `meta.entity_ids` field has been observed not to include\n * them. Collect explicitly so they're guaranteed to hydrate into the entities\n * map alongside teams, players, etc.\n */\nfunction collectStageNameIds(details: FUSportsCompetitionDetails): string[] {\n    const ids: string[] = [];\n    for (const stage of details.season.stages) {\n        if (stage.stageNameId) ids.push(stage.stageNameId);\n    }\n    return ids;\n}\n\nexport interface GetSportsCompetitionHydratedOptions {\n    /** Season identifier (e.g. \"fb:c:1:2025/26\"). Defaults to the active season. */\n    seasonId?: string;\n    /** Locale code (e.g. \"EN\", \"BG\") used to resolve entity translations. Falls back to EN. */\n    locale?: string;\n    /** Next.js cache options for ISR/on-demand revalidation. */\n    next?: NextCacheOptions;\n}\n\n/**\n * Sports API competition response plus a lookup map for every referenced entity.\n *\n * The map is keyed by entity ID and holds the localized {@link SearchEntityResult}\n * union — competitors (teams/athletes), venues, countries, coaches, and\n * stage-name labels (`FUSportsStageName & { entityType: \"stageName\" }`) for\n * every `stage.stageNameId` referenced by `season.stages[]`.\n *\n * Missing IDs (404s from the Search API) are silently omitted — render code\n * should fall back gracefully on a missing entry:\n *   `entities.get(id) ?? { name: id }`.\n */\nexport interface FUSportsCompetitionHydrated extends FUSportsCompetitionDetails {\n    entities: Map<string, SearchEntityResult>;\n}\n\nexport async function getFansUnitedSportsCompetitionHydrated(\n    competitionId: string,\n    options?: GetSportsCompetitionHydratedOptions,\n    config?: DataLayerConfig\n): Promise<FUSportsCompetitionHydrated> {\n    const raw = await getFansUnitedSportsCompetition(\n        competitionId,\n        { seasonId: options?.seasonId, next: options?.next },\n        config\n    );\n\n    // Union meta.entity_ids with stage_name_ids walked from season.stages —\n    // dedupe so duplicates only cost one Search API row.\n    const entityIds = Array.from(\n        new Set<string>([...raw.meta.entityIds, ...collectStageNameIds(raw)])\n    );\n    const entities = new Map<string, SearchEntityResult>();\n\n    if (entityIds.length > 0) {\n        const resolved = await getFansUnitedEntitiesByIds(entityIds, {\n            lang: options?.locale,\n            next: options?.next,\n            config,\n        });\n        for (const e of resolved) {\n            entities.set(e.id, e);\n        }\n    }\n\n    return { ...raw, entities };\n}\n"],"names":[],"mappings":";;AAmDA,SAAS,oBAAoB,SAA+C;AACxE,QAAM,MAAgB,CAAA;AACtB,aAAW,SAAS,QAAQ,OAAO,QAAQ;AACvC,QAAI,MAAM,YAAa,KAAI,KAAK,MAAM,WAAW;AAAA,EACrD;AACA,SAAO;AACX;AA2BA,eAAsB,uCAClB,eACA,SACA,QACoC;AACpC,QAAM,MAAM,MAAM;AAAA,IACd;AAAA,IACA,EAAE,UAAU,SAAS,UAAU,MAAM,SAAS,KAAA;AAAA,IAC9C;AAAA,EAAA;AAKJ,QAAM,YAAY,MAAM;AAAA,IACpB,oBAAI,IAAY,CAAC,GAAG,IAAI,KAAK,WAAW,GAAG,oBAAoB,GAAG,CAAC,CAAC;AAAA,EAAA;AAExE,QAAM,+BAAe,IAAA;AAErB,MAAI,UAAU,SAAS,GAAG;AACtB,UAAM,WAAW,MAAM,2BAA2B,WAAW;AAAA,MACzD,MAAM,SAAS;AAAA,MACf,MAAM,SAAS;AAAA,MACf;AAAA,IAAA,CACH;AACD,eAAW,KAAK,UAAU;AACtB,eAAS,IAAI,EAAE,IAAI,CAAC;AAAA,IACxB;AAAA,EACJ;AAEA,SAAO,EAAE,GAAG,KAAK,SAAA;AACrB;"}

package/package.json

@@ -4,7 +4,7 @@
     "description": "A TypeScript library for fetching and transforming sports data from multiple API providers. Returns clean, canonical types that are provider-agnostic.",
     "homepage": "https://fansunited.com/",
     "private": false,
-    "version": "0.18.0",
+    "version": "0.18.3",
     "type": "module",
     "sideEffects": false,
     "module": "./fansunited-data-layer.js",