> ## Documentation Index
> Fetch the complete documentation index at: https://proclubs-sdk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Types and schemas

> Public TypeScript types, constants, Zod response schemas, and drift detection.

The package ships ESM JavaScript and TypeScript declarations from the root
export and dedicated subpaths (`proclubs-sdk/nationalities`, `proclubs-sdk/regions`,
and `proclubs-sdk/metadata`) for standalone label tables.

## Input types

```ts theme={null}
import type {
  ClubRequest,
  ListMatchesInput,
  PlayoffAchievementsInput,
  RankingListInput,
  RankingSearchInput,
  SearchClubsInput,
} from 'proclubs-sdk'
```

| Type | Fields |
| - | - |
| `SearchClubsInput` | `name`, optional `platform` |
| `RankingListInput` | optional `platform` |
| `RankingSearchInput` | `name`, optional `platform` |
| `ClubRequest` | `clubId`, optional `platform` |
| `PlayoffAchievementsInput` | `clubId`, optional `platform` |
| `ListMatchesInput` | `clubId`, optional `platform`, `type`, and `limit` |

## Response types

```ts theme={null}
import type {
  ClubInfo,
  ClubInfoDerivedLabels,
  ClubInfoResponse,
  ClubMatch,
  ClubMatchesResponse,
  ClubMember,
  ClubMemberCareerStats,
  ClubMemberDerivedLabels,
  ClubMemberStats,
  ClubOverallStats,
  ClubOverallStatsResponse,
  PlayoffAchievement,
  PlayoffAchievementDerivedLabels,
  PlayoffAchievementsResponse,
  ClubSearchResponse,
  ClubSummary,
  ClubSummaryInfo,
  CustomKit,
  MatchAggregateStats,
  MatchClubDetails,
  MatchPlayerStats,
  MatchTimeAgo,
  RankingEntry,
  RankingListResponse,
} from 'proclubs-sdk'
```

Response object types preserve unknown upstream fields at runtime. Known fields follow the
observed FC26 shapes described on the namespace reference pages.

`PlayoffAchievementDerivedLabels` contains the typed resolved labels used when
EA already supplies a field with one of the derived label names.
`ClubInfoDerivedLabels` contains the resolved `regionLabel` when EA already
supplies a raw region label. `ClubMemberDerivedLabels` contains the resolved
`nationality` when EA already supplies a raw member nationality.

## Runtime fidelity and normalizations

* **Runtime fidelity:** All object schemas use loose object validation, meaning any additional fields sent by EA are preserved and accessible on returned objects.
* **Envelope unwrapping:** `clubs.get` and `clubs.overallStats` unwrap the upstream envelope to return the requested resource directly (`ClubInfo | null` and `ClubOverallStats | null`). Nested field values stay in their upstream representation.
* **Region labels:** When public club information contains a `regionId`, the SDK copies the object and may add a derived `regionLabel`. If EA already supplies `regionLabel`, that raw value is preserved and the calculated value is exposed under `derivedLabels.regionLabel`. The raw `regionId` is never rewritten. This applies to `clubs.get`, nested `clubInfo` on club searches and ranking entries, and match club `details`. See [Regions](/docs/reference/regions).
* **Nationalities:** When a member contains a known `proNationality`, `members.stats` and `members.careerStats` copy the member and add a derived `nationality`. If EA already supplies `nationality`, that raw value is preserved and the calculated value is exposed under `derivedLabels.nationality`. The raw `proNationality` is never rewritten. See [Nationalities](/docs/reference/nationalities).
* The other nine endpoints (`clubs.search`, `clubs.playoffAchievements`, the four ranking methods, `members.stats`, `members.careerStats`, and `matches.list`) return their full response data directly, aside from region-label, nationality, and playoff-label enrichment.
* Full leaderboards preserve EA response order and have no server pagination. Numeric strings remain strings.

## Constants

```ts theme={null}
import {
  DEFAULT_PLATFORM,
  DEPRECATED_PLATFORMS,
  DIVISION_LABELS,
  EA_CREST_ASSET_BASE_URL,
  MATCH_TYPE_LABELS,
  MATCH_TYPE_RESPONSE_LABELS,
  MATCH_TYPES,
  PLATFORM_LABELS,
  PLAYOFF_RESULT_LABELS,
  PLATFORMS,
  POSITION_LABELS,
  NATIONALITY_LABELS,
  REGION_LABELS,
  REPUTATION_LABELS,
  resolveClubCrestUrl,
  resolveDivisionLabel,
  resolveMatchTypeLabel,
  resolveNationality,
  resolvePlatformLabel,
  resolvePlayoffResultLabel,
  resolvePositionLabel,
  resolveRegionLabel,
  resolveReputationLabel,
  type ClubCrestInput,
  type DivisionLabel,
  type KnownDivisionId,
  type KnownMatchTypeId,
  type KnownMatchTypeResponseId,
  type KnownPlatformId,
  type KnownPlayoffResultId,
  type KnownPositionId,
  type KnownNationalityId,
  type KnownRegionId,
  type KnownReputationId,
  type MatchType,
  type MatchTypeLabel,
  type Nationality,
  type NationalityIsoCode,
  type NationalityLabel,
  type Platform,
  type PlatformLabel,
  type PlayoffResultLabel,
  type PositionLabel,
  type RegionLabel,
  type ReputationLabel,
} from 'proclubs-sdk'
```

```ts theme={null}
PLATFORMS // ['common-gen5', 'common-gen4', 'nx']
DEPRECATED_PLATFORMS // ['common-gen4'], rejected by EA since FC 27
DEFAULT_PLATFORM // 'common-gen5'
MATCH_TYPES // ['friendlyMatch', 'leagueMatch', 'playoffMatch']
MATCH_TYPE_RESPONSE_LABELS['1'] // 'League Match'
resolveMatchTypeLabel('leagueMatch') // 'League Match'
resolveMatchTypeLabel('1') // 'League Match'
PLATFORM_LABELS['common-gen5'] // 'Crossplatform Current Gen'
REPUTATION_LABELS['3'] // 'World Renown'
resolveReputationLabel('6') // undefined
resolveClubCrestUrl({ teamId: 112809, customKit: { selectedKitType: '1', crestAssetId: '99140109' } })
REGION_LABELS['5457237'] // 'Southern Europe'
resolveRegionLabel(5457237) // 'Southern Europe'
NATIONALITY_LABELS['14'] // { label: 'England', isoCode: 'GB-ENG' }
resolveNationality(14) // { id: '14', label: 'England', isoCode: 'GB-ENG' }
```

`REGION_LABELS`, `KnownRegionId`, `RegionLabel`, and `resolveRegionLabel` are
documented on [Regions](/docs/reference/regions). `NATIONALITY_LABELS`,
`KnownNationalityId`, `NationalityLabel`, `NationalityIsoCode`, `Nationality`,
and `resolveNationality` are documented on
[Nationalities](/docs/reference/nationalities). Platform, match-type,
position, reputation, division, playoff, and crest helpers are documented on
[Metadata labels](/docs/reference/metadata).

## Response schemas

The public Zod schemas let consumers validate stored or forwarded EA payloads
against the same envelopes as the SDK.

```ts theme={null}
import {
  clubInfoResponseSchema,
  clubInfoSchema,
  clubMatchesResponseSchema,
  clubMatchSchema,
  clubMemberSchema,
  clubMemberStatsSchema,
  clubOverallStatsResponseSchema,
  clubOverallStatsSchema,
  clubSearchResponseSchema,
  clubSummaryInfoSchema,
  clubSummarySchema,
  customKitSchema,
  listMatchesInputSchema,
  matchAggregateStatsSchema,
  matchClubDetailsSchema,
  matchPlayerStatsSchema,
  matchTimeAgoSchema,
  rankingEntrySchema,
  rankingListInputSchema,
  rankingListResponseSchema,
  rankingSearchInputSchema,
  playoffAchievementSchema,
  playoffAchievementsInputSchema,
  playoffAchievementsResponseSchema,
  clubRequestSchema,
  searchClubsInputSchema,
} from 'proclubs-sdk'
```

```ts theme={null}
const result = clubMemberStatsSchema.safeParse(untrustedPayload)

if (result.success) {
  console.log(result.data.members)
}
```

## Drift detection and compatibility

```ts theme={null}
import {
  ENDPOINT_CONTRACTS,
  detectDrift,
  generateReport,
  runCompatibilityCheck,
  type CompatibilityReport,
  type DriftIssue,
  type EndpointDriftResult,
} from 'proclubs-sdk'
```

The SDK provides a deterministic structural drift detector that compares EA responses against the observed FC26 contract shape. It categorizes changes into `field_added`, `field_removed`, `type_changed`, `envelope_changed`, and `unknown_value`.

```ts theme={null}
const drift = detectDrift('clubsSearch', searchPayload)
if (drift.status === 'drifted') {
  console.log(drift.issues)
}
```

Run drift detection on **raw EA payloads**, not on SDK output. `regionLabel` and
`nationality` are derived SDK fields and would otherwise appear as `field_added`.

An endpoint with only `unknown_value` diagnostics remains `passed`: the raw EA
value is usable, while the diagnostic tells maintainers that a label mapping
may need to be extended. Structural changes, rejected payloads, and invalid
envelopes are `drifted`. Empty arrays are `unverified` because their shape
cannot be confirmed from an empty response.

An unknown `regionId` does not fail club requests. The same ID can appear in a
compatibility report as `unknown_value` so maintainers can extend
`REGION_LABELS` after confirming the EA label. An unknown `proNationality` is
reported the same way for `NATIONALITY_LABELS`. That signal is additive (`minor`)
and is separate from the mapping used at runtime. See [Regions](/docs/reference/regions),
[Nationalities](/docs/reference/nationalities), and issue #17.

### Interpreting compatibility reports

Each report ends with a summary status and a release recommendation:

| Recommendation | Meaning | Suggested action |
| - | - | - |
| `patch` | All endpoints match the known contract. | Safe to release; no contract change. |
| `minor` | EA added fields only (`field_added`), or an enum/region value is not yet mapped (`unknown_value`). Existing fields are intact. | Type and document the new fields or value, then release a minor version. |
| `major` | Fields were removed or renamed, types changed, or envelopes shifted. | Assess consumer impact before releasing a major version. |
| `manual_review` | The run stopped early or produced mixed signals (for example, a Zod rejection on top of structural drift). | Inspect the per-endpoint issues before deciding. |

Drift detection never mutates schemas, fixtures, or types automatically.
Update the contract manually after confirming each reported change against
live data.

## Transport types

```ts theme={null}
import type {
  ProClubsClientOptions,
  ProClubsRequestInit,
  ProClubsRequestOptions,
  ProClubsResponse,
  ProClubsTransport,
} from 'proclubs-sdk'
```

See [Configure the client](/docs/guides/configuration) for the transport
contract and a minimal adapter.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.