The `sports` namespace exposes the new **Sports API** — multi‑sport competition data (football, basketball, tennis, …) with seasons, stages, groups and standings. Responses are **cached** and **enriched** automatically: - **Cached** with a stale‑while‑revalidate strategy — repeat reads are served instantly from a local cache (browser: IndexedDB; server: in‑memory; React Native: AsyncStorage) and refreshed in the background, so live standings stay up to date without extra round‑trips. The cache TTL is the value configured for your client in the Management Portal (Features → Cache TTL). - **Enriched** — each competition is returned with its descriptive metadata (name, branding,
assets, …), each stage with its resolved **stage name**, and each standing with its resolved
**competitor** (team / athlete / national team). Text fields (`name`, `shortName`) are localized to
the `lang` you configured (see Configuration). *** ## `getCompetitionById` Returns a single competition with its season, stages, groups and standings. ```ts sdk.sports.getCompetitionById( competitionId: string, filters?: CompetitionByIdFilters, disableCache?: boolean, ): Promise ``` ### Parameters | Parameter | Type | Required | Description | | --------------- | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `competitionId` | `string` | Yes | Competition identifier, e.g. `"fb:c:1"`. | | `filters` | `CompetitionByIdFilters` | No | Optional query filters (see below). | | `disableCache` | `boolean` | No | When `true`, bypasses the SDK cache **and** the server cache and returns a fresh origin response. Defaults to `false`. | `CompetitionByIdFilters` | Field | Type | Description | | ---------- | -------- | ------------------------------------------------------------------------------------------------ | | `seasonId` | `string` | Season identifier (e.g. `"fb:c:1:2025/26"`). Defaults to the current active season when omitted. | ### Example ```ts import { FansUnitedSDK } from "fansunited-js-sdk"; const sdk = FansUnitedSDK({ apiKey: "", clientId: "", idSchema: "native", lang: "en", }); // Current season const competition = await sdk.sports.getCompetitionById("fb:c:1"); console.log(competition.name); // "First Professional League" (localized to `lang`) const stage = competition.season?.stages?.[0]; console.log(stage?.stageNameModel?.name); // "Regular Season" const standings = stage?.groups?.[0]?.standings ?? []; standings.forEach((row) => { console.log(row.rank, row.competitorModel?.name); // 1 "Arda Kardzhali" }); // A specific season const past = await sdk.sports.getCompetitionById("fb:c:1", { seasonId: "fb:c:1:2024/25", }); // Force a fresh response (skip both SDK and server cache) const fresh = await sdk.sports.getCompetitionById("fb:c:1", undefined, true); ``` *** ## Response models ### `CompetitionModel` | Field | Type | Description | | ------------- | ---------------------------------------- | ------------------------------------- | | `id` | `string` | Competition ID. | | `sport` | `string` | Sport, e.g. `"FOOTBALL"`. | | `meta` | `CompetitionMetaModel \| null` | Referenced entity IDs. | | `season` | `SeasonModel \| null` | Season with stages and standings. | | `type` | `string \| null` | Entity type, e.g. `"COMPETITION"`. | | `contentType` | `string \| null` | Content type keyword. | | `format` | `string \| null` | e.g. `"LEAGUE"`. | | `gender` | `string \| null` | e.g. `"MALE"`. | | `name` | `string \| null` | Competition name (localized). | | `shortName` | `string \| null` | Short name (localized). | | `assets` | `AssetModel[]` | Keyed assets (e.g. `LOGO`). | | `branding` | `CompetitionEntityBrandingModel \| null` | Brand colors / images. | | `related` | `RelatedModel[]` | Related entities (country, teams, …). | ### `CompetitionMetaModel` | Field | Type | Description | | ----------- | ---------- | ------------------------------------------------------------------------- | | `entityIds` | `string[]` | Unique entity IDs referenced in the response (competition + competitors). | ### `SeasonModel` | Field | Type | Description | | ----------- | -------------- | ----------------------------------- | | `id` | `string` | Season ID, e.g. `"fb:c:1:2025/26"`. | | `name` | `string` | Season name. | | `year` | `string` | Season year. | | `status` | `string` | e.g. `"ACTIVE"`. | | `startDate` | `string` | Season start date. | | `endDate` | `string` | Season end date. | | `stages` | `StageModel[]` | Stages within the season. | ### `StageModel` | Field | Type | Description | | ---------------- | ------------------------ | ------------------------------------------------- | | `id` | `string` | Stage ID. | | `stageNameId` | `string` | Stage name ID (e.g. `"stn:1"`). | | `stageNameModel` | `StageNameModel \| null` | Resolved stage name entity. | | `type` | `string` | `"standing"` or `"bracket"`. | | `status` | `string` | Stage status. | | `coverage` | `string` | Coverage level. | | `order` | `number \| null` | Order within the season. | | `startDate` | `string` | Stage start date. | | `endDate` | `string` | Stage end date. | | `groups` | `GroupModel[] \| null` | Groups with standings. `null` for bracket stages. | ### `GroupModel` | Field | Type | Description | | ----------- | ------------------------------ | ------------------------------------------- | | `id` | `number \| null` | Group ID. `null` for single‑group stages. | | `name` | `string \| null` | Group name. `null` for single‑group stages. | | `standings` | `StandingEntryModel[] \| null` | Standing rows. `null` for bracket stages. | ### `StandingEntryModel` | Field | Type | Description | | ----------------- | ------------------------- | ---------------------------------------- | | `rank` | `number \| null` | Current rank. | | `lastRank` | `number \| null` | Previous rank. | | `competitorId` | `string` | Competitor ID. | | `competitorModel` | `CompetitorModel \| null` | Resolved competitor entity. | | `stats` | `StandingStatModel[]` | Standing stats (played, won, points, …). | | `rules` | `string[]` | Standing rules. | ### `StandingStatModel` | Field | Type | Description | | ------- | -------- | ----------------------------------------- | | `key` | `string` | Stat key, e.g. `"points"`. | | `value` | `string` | Stat value (string‑encoded), e.g. `"76"`. | ### `StageNameModel` | Field | Type | Description | | ------ | -------- | ----------------------- | | `id` | `string` | Stage name ID. | | `name` | `string` | Stage name (localized). | | `type` | `string` | e.g. `"STAGE_NAME"`. | ### `CompetitorModel` | Field | Type | Description | | ----------------------- | --------------------------------- | ------------------------------------------ | | `id` | `string` | Competitor ID. | | `sport` | `string` | Sport. | | `type` | `string` | `TEAM`, `ATHLETE` or `NATIONAL_TEAM`. | | `contentType` | `string` | Content type keyword, e.g. `"COMPETITOR"`. | | `gender` | `string \| null` | Gender. | | `name` | `string` | Name (localized). | | `fullName` | `string \| null` | Full name. | | `shortName` | `string \| null` | Short name (localized). | | `threeLetterCode` | `string \| null` | 3‑letter code. | | `nickname` | `string \| null` | Nickname. | | `assets` | `AssetModel[]` | Keyed assets (e.g. `LOGO`). | | `countryId` | `string \| null` | Country ID. | | `metadata` | `CompetitorMetadataModel \| null` | Additional metadata (branding). | | `additionalInformation` | `any[]` | Extra information. | | `related` | `RelatedModel[]` | Related entities. | ### Shared models `AssetModel` — `{ key: string; value: string }` (e.g. `{ key: "LOGO", value: "https://…png" }`). `RelatedModel` — `{ relationship: string; relatedId: string }`. `CompetitorMetadataModel` — `{ branding: CompetitorBrandingModel | null }`. `CompetitorBrandingModel` — `{ primaryColor, secondaryColor, tertiaryColor: string | null }`. `CompetitionEntityBrandingModel` — `{ primaryColor, secondaryColor, textColor, backgroundColor, backgroundGradientFromColor, backgroundGradientToColor, backgroundImage: string | null; shirtColors: any[] }`. *** ## Caching notes - The first call for a competition fetches from the network; subsequent calls within the TTL are served instantly from the local cache. - Once the TTL lapses, the next call still returns instantly (from the cached copy) and refreshes in the background, so the following call has fresh data. - Pass `disableCache: true` to force a fresh origin response (bypasses both the SDK cache and the server cache). - To tune how long the enrichment entities (stage names, competitors, competitions) are cached, use the `cache` configuration option.