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

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

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.
• 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.
• 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

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'

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. NATIONALITY_LABELS, KnownNationalityId, NationalityLabel, NationalityIsoCode, Nationality, and resolveNationality are documented on Nationalities. Platform, match-type, position, reputation, division, playoff, and crest helpers are documented on Metadata labels.

Response schemas

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

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'

const result = clubMemberStatsSchema.safeParse(untrustedPayload)

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

Drift detection and compatibility

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.

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, 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

import type {
  ProClubsClientOptions,
  ProClubsRequestInit,
  ProClubsRequestOptions,
  ProClubsResponse,
  ProClubsTransport,
} from 'proclubs-sdk'

See Configure the client for the transport contract and a minimal adapter.