API request & response types (TypeScript)

TypeScript types for GGScore public paid API: headers, query parameters, and JSON response bodies. Complements the ReDoc reference.

How to use

Copy the module below into your project, or import it if you colocate a copy (e.g. import type { PlayedMatchItem } from ".../ggscore-public-api").
Request: send header X-API-Key for all paid data routes (same as the interactive ReDoc on /docs). GET /api/v2/stats and GET /api/v2/ping do not require a key.
Query: list endpoints use page and limit; map recent matches use limit only. Exact bounds are in OpenAPI.
Machine-readable schema: GET /api/v2/openapi-public.json (same contract as this file; OpenAPI is canonical for edge cases).

Module: types/ggscore-public-api.ts

/**
 * GGScore v2 — public paid JSON API (TypeScript request/response shapes).
 *
 * Base path: `/api/v2/...` (see `API_URL` in the app). Authenticate paid data
 * endpoints with header `X-API-Key: <your key>` (from the user cabinet).
 *
 * OpenAPI: `GET {API_URL}/api/v2/openapi-public.json` — ReDoc: `/docs` (iframe).
 * Keep this file loosely in sync with `api-v2/.../data_schema.py`.
 */

/** Standard pagination for list endpoints. */
export type PaginationQuery = {
  /** 1-based page index (default 1). */
  page?: number;
  /**
   * Page size. `GET /matches` and `/upcoming_matches` use 1–100;
   * `GET /teams` and `/events` use 1–500.
   */
  limit?: number;
};

export type PublicApiAuthHeaders = {
  "X-API-Key": string;
};

export type MatchesListQuery = PaginationQuery & {
  /** Optional filters — see ReDoc for the full list. */
  [key: string]: string | number | undefined;
};

export type MapRecentMatchesQuery = {
  /** 1–100, default 30. */
  limit?: number;
};

export interface MatchesMeta {
  page: number;
  limit: number;
  total: number;
  pages: number;
}

/** Embedded team in match payloads. */
export interface PublicTeamRef {
  id: string;
  title: string;
  image_url: string | null;
  [key: string]: unknown;
}

export interface PublicCountryRef {
  id?: string | number | null;
  title?: string | null;
  code?: string | null;
  [key: string]: unknown;
}

export interface PublicEventRef {
  id: string;
  title: string;
  image_url?: string | null;
  [key: string]: unknown;
}

export interface PublicMatchKindRef {
  id?: string;
  title?: string;
  [key: string]: unknown;
}

export interface PlayedMapRef {
  id: string;
  slug: string;
  title: string;
  image_url: string | null;
}

export interface PlayedMapWinnerTeam {
  id: string;
  title: string;
  image_url: string | null;
}

export interface PlayedMatchGameItem {
  sequence: number;
  winner_rounds: number;
  loser_rounds: number;
  map: PlayedMapRef;
  map_winner_team: PlayedMapWinnerTeam;
}

/**
 * One finished (played) match — `GET /matches`, `GET /match/{id}`,
 * and items in `GET /maps/{slug}/recent_matches`.
 */
export interface PlayedMatchItem {
  id: string | null;
  played_at: string | null;
  team_won: PublicTeamRef;
  team_lose: PublicTeamRef;
  team_won_country: PublicCountryRef | null;
  team_lose_country: PublicCountryRef | null;
  match_kind: PublicMatchKindRef | null;
  score_won: number | null;
  score_lose: number | null;
  stars: number | null;
  event: PublicEventRef;
  location: string | null;
  /** Per-map BO series results; empty array when not available. */
  games: PlayedMatchGameItem[];
  [key: string]: unknown;
}

export interface PlayedMatchesResponse {
  data: PlayedMatchItem[];
  meta: MatchesMeta;
}

/** Upcoming fixture row (`GET /upcoming_matches`). */
export interface UpcomingMatchItem {
  id: string | null;
  play_at: string | null;
  team1: PublicTeamRef | string;
  team2: PublicTeamRef | string;
  team1_country: PublicCountryRef | null;
  team2_country: PublicCountryRef | null;
  match_kind: PublicMatchKindRef | null;
  stars: number | null;
  event: PublicEventRef;
  location: string | null;
  [key: string]: unknown;
}

export interface UpcomingMatchesResponse {
  data: UpcomingMatchItem[];
  meta: MatchesMeta;
}

export type CountryItem = {
  id?: string | number | null;
  title?: string | null;
  code?: string | null;
  [key: string]: unknown;
};

/** `GET /countries` — JSON array. */
export type CountriesResponse = CountryItem[];

export interface TeamCardResponse {
  id: string;
  title: string;
  image_url: string | null;
}

export interface EventCardResponse {
  id: string;
  title: string;
  image_url: string | null;
}

export interface MapCatalogItem {
  slug: string;
  title: string;
  last_played_at: string | null;
}

export interface MapsCatalogResponse {
  items: MapCatalogItem[];
}

export interface MapRecentPlayedResponse {
  items: PlayedMatchItem[];
}

export interface TeamListItem {
  id: string;
  title: string;
  image_url: string | null;
}

export interface TeamsListResponse {
  data: TeamListItem[];
  meta: MatchesMeta;
}

export interface EventListItem {
  id: string;
  title: string;
  image_url: string | null;
}

export interface EventsListResponse {
  data: EventListItem[];
  meta: MatchesMeta;
}

/** `GET /stats` — no API key. */
export interface DataStatsResponse {
  total_matches: number;
  total_upcoming_matches: number;
  total_countries: number;
  total_users: number;
  new_users_24h: number;
  new_matches_24h: number;
  upcoming_today: number;
  total_teams: number;
  total_events: number;
}