@mateuszrozanski/worldcup-types

TypeScript types for the World Cup 2026 backend ↔ frontend contract. Single source of truth — these types live in the backend repo and are consumed by the frontend via npm.

Note: package temporarily under personal npm scope. Will migrate to @synergycodes/worldcup-types when the org is set up on npm. See ADR-046 in docs/decisions.md.

Install

npm install @mateuszrozanski/worldcup-types

Standard npm package — semver works, dependabot works, npm cache works.

Use

import {
  TournamentState,
  GroupMatch,
  KnockoutMatch,
  MatchEvent,
  AblyEvent,
  AblyEventType,
  WORLDCUP_CHANNEL,
} from '@mateuszrozanski/worldcup-types';

// /api/state response
async function loadBracket(): Promise<TournamentState> {
  const res = await fetch('https://worldcup-backend-staging.up.railway.app/api/state');
  return res.json() as Promise<TournamentState>;
}

// Ably channel name (no magic strings)
const channel = realtime.channels.get(WORLDCUP_CHANNEL);

channel.subscribe((msg) => {
  // msg.name is one of AblyEvent['type']
  // msg.data shape depends on msg.name
  const event = { type: msg.name, data: msg.data } as AblyEvent;
  switch (event.type) {
    case 'score:update': /* ... */ break;
    case 'match:goal':   /* ... */ break;
    // ...
  }
});

Exports

| Group | Symbols | |---|---| | Domain types | TournamentState, Team, Group, GroupMatch, KnockoutMatch, KnockoutRound, QualificationSlot, TeamStanding, MatchEvent, MatchStats, Lineup, Squad, Player, Injury, HeadToHead, HistoricalMatch, MatchStatus, TournamentStatus, Confederation, PlayerPosition, GroupId, TeamId, MatchId, PlayerId | | Ably | WORLDCUP_CHANNEL, AblyEvent (union), AblyEventType | | Helpers | headToHeadKey(a, b) — canonical pair-key ordering for h2h lookup |

Versioning

Standard semver. We're pre-1.0 so:

• patch (0.1.0 → 0.1.1) — additive, backward-compatible
• minor (0.1.0 → 0.2.0) — breaking changes during MVP
• major (0.x → 1.0) — first stable contract

Pin in your package.json:

{
  "dependencies": {
    "@mateuszrozanski/worldcup-types": "^0.1.1"
  }
}

Development (in this repo)

cd types
npm install
npm run build   # emits dist/index.d.ts + index.js

Source files are copies of src/schemas/index.ts and src/ably/ably.events.ts from the parent backend. They MUST stay in sync — the contract test in src/sports-api/contract.spec.ts validates the runtime shape against these types.

Release flow

1. Bump version in types/package.json
2. Commit + tag: git tag types-vX.Y.Z && git push --tags
3. GitHub Actions auto-publishes to npm (workflow: .github/workflows/publish-types.yml)
4. Frontend bumps pin in their package.json + npm install

The CI workflow validates the tag matches the package.json version and uses the NPM_TOKEN secret to publish.

Links

• npm package
• Backend repo
• Frontend integration guide
• ADR-046 — why types live here