@diffenderfer-games/hub-contract 2.0.0-next.0 → 2.0.0-next.2

package/src/api/social/presence.ts

@@ -1,95 +1,95 @@
-/**
- * Presence: what a player is doing right now, as their friends see it, and
- * the anonymous online counts (multiplayer-impl.md §4.4). Games report a
- * {@link PresenceInput} per tab (socket op `presence`); the hub folds a
- * user's tabs into one {@link Presence} and pushes it to friends
- * (`ev:presence`).
- */
-import { z } from 'zod';
-import { Millis, Slug } from '../../common';
-
-/** Activity kinds, least engaged first. The most engaged tab wins; hidden or idle tabs count as `away`. */
-export const PresenceKind = z.enum(['away', 'menu', 'lobby', 'watching', 'playing']);
-
-/** An activity kind. */
-export type PresenceKind = z.infer<typeof PresenceKind>;
-
-/** A room reference friends can join with: 1 to 64 of `A-Z a-z 0-9 _ : -`. */
-export const PresenceRoom = z.string().regex(/^[A-Za-z0-9_:-]{1,64}$/);
-
-/** A game mode key: 1 to 32 of `A-Z a-z 0-9 _ -`. */
-export const PresenceMode = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/);
-
-/** The fields a tab reports and friends see back, with the limits the hub enforces. */
-const PresenceFields = z.object({
-  kind: PresenceKind,
-  /** A short status line (at most 40 characters), filtered; a rejected one is dropped. */
-  detail: z.string().max(40).optional(),
-  /** Friends may join. Only ever `true` when present. */
-  joinable: z.boolean().optional(),
-  /** Friends may watch. Only ever `true` when present. */
-  watchable: z.boolean().optional(),
-  /** Join info for friends: the game's own room reference, or the hub room's code. */
-  room: PresenceRoom.optional(),
-  /** A public lobby: friends who follow the game may get a `lobby_open` alert. */
-  public: z.boolean().optional(),
-  /** Free seats, 0 to 64. */
-  openSeats: z.number().int().min(0).max(64).optional(),
-  mode: PresenceMode.optional(),
-});
-
-/**
- * What a game reports for its tab (socket op `presence`). The hub is
- * lenient: an unknown `kind`, or input that isn't an object at all (`null`),
- * counts as `{kind:'menu'}`; unknown fields, and fields that break a rule (a
- * bad `room`, a fractional `openSeats`, a field of the wrong type), are
- * ignored one by one, so friends only ever
- * see {@link Presence}'s fields; `detail` is trimmed to 40 characters before
- * filtering.
- */
-export const PresenceInput = z.looseObject({
-  kind: PresenceKind.catch('menu'),
-  detail: z.string().optional().catch(undefined),
-  joinable: z.boolean().optional().catch(undefined),
-  watchable: z.boolean().optional().catch(undefined),
-  room: z.string().optional().catch(undefined),
-  public: z.boolean().optional().catch(undefined),
-  openSeats: z.number().optional().catch(undefined),
-  mode: z.string().optional().catch(undefined),
-}).catch({ kind: 'menu' });
-
-/** A presence report. */
-export type PresenceInput = z.input<typeof PresenceInput>;
-
-/** A user's aggregated presence: their most engaged tab, decorated by the hub. */
-export const Presence = PresenceFields.extend({
-  /** The game the tab is on, `null` on the catalog and other hub pages. */
-  game: Slug.nullable(),
-  /** That game's title, `null` with `game`. */
-  gameTitle: z.string().nullable(),
-  /** When this activity (kind + game) started (epoch ms). */
-  since: Millis,
-  /** Party size, present when the user is in a party of two or more. */
-  partySize: z.number().int().min(2).optional(),
-});
-
-/** A user's aggregated presence. */
-export type Presence = z.infer<typeof Presence>;
-
-/** A non-negative head count. */
-const HeadCount = z.number().int().nonnegative();
-
-/**
- * Anonymous online counts (`GET /social/counts`, `ev:counts`, the `hello`
- * snapshot): everyone with a live presence, guests and hidden players
- * included.
- */
-export const Counts = z.object({
-  /** Everyone online. */
-  online: HeadCount,
-  /** Players per game slug (games with nobody are absent). */
-  byGame: z.record(Slug, HeadCount),
-});
-
-/** Online counts. */
-export type Counts = z.infer<typeof Counts>;
+/**
+ * Presence: what a player is doing right now, as their friends see it, and
+ * the anonymous online counts (multiplayer-impl.md §4.4). Games report a
+ * {@link PresenceInput} per tab (socket op `presence`); the hub folds a
+ * user's tabs into one {@link Presence} and pushes it to friends
+ * (`ev:presence`).
+ */
+import { z } from 'zod';
+import { Millis, Slug } from '../../common';
+
+/** Activity kinds, least engaged first. The most engaged tab wins; hidden or idle tabs count as `away`. */
+export const PresenceKind = z.enum(['away', 'menu', 'lobby', 'watching', 'playing']);
+
+/** An activity kind. */
+export type PresenceKind = z.infer<typeof PresenceKind>;
+
+/** A room reference friends can join with: 1 to 64 of `A-Z a-z 0-9 _ : -`. */
+export const PresenceRoom = z.string().regex(/^[A-Za-z0-9_:-]{1,64}$/);
+
+/** A game mode key: 1 to 32 of `A-Z a-z 0-9 _ -`. */
+export const PresenceMode = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/);
+
+/** The fields a tab reports and friends see back, with the limits the hub enforces. */
+const PresenceFields = z.object({
+  kind: PresenceKind,
+  /** A short status line (at most 40 characters), filtered; a rejected one is dropped. */
+  detail: z.string().max(40).optional(),
+  /** Friends may join. Only ever `true` when present. */
+  joinable: z.boolean().optional(),
+  /** Friends may watch. Only ever `true` when present. */
+  watchable: z.boolean().optional(),
+  /** Join info for friends: the game's own room reference, or the hub room's code. */
+  room: PresenceRoom.optional(),
+  /** A public lobby: friends who follow the game may get a `lobby_open` alert. */
+  public: z.boolean().optional(),
+  /** Free seats, 0 to 64. */
+  openSeats: z.number().int().min(0).max(64).optional(),
+  mode: PresenceMode.optional(),
+});
+
+/**
+ * What a game reports for its tab (socket op `presence`). The hub is
+ * lenient: an unknown `kind`, or input that isn't an object at all (`null`),
+ * counts as `{kind:'menu'}`; unknown fields, and fields that break a rule (a
+ * bad `room`, a fractional `openSeats`, a field of the wrong type), are
+ * ignored one by one, so friends only ever
+ * see {@link Presence}'s fields; `detail` is trimmed to 40 characters before
+ * filtering.
+ */
+export const PresenceInput = z.looseObject({
+  kind: PresenceKind.catch('menu'),
+  detail: z.string().optional().catch(undefined),
+  joinable: z.boolean().optional().catch(undefined),
+  watchable: z.boolean().optional().catch(undefined),
+  room: z.string().optional().catch(undefined),
+  public: z.boolean().optional().catch(undefined),
+  openSeats: z.number().optional().catch(undefined),
+  mode: z.string().optional().catch(undefined),
+}).catch({ kind: 'menu' });
+
+/** A presence report. */
+export type PresenceInput = z.input<typeof PresenceInput>;
+
+/** A user's aggregated presence: their most engaged tab, decorated by the hub. */
+export const Presence = PresenceFields.extend({
+  /** The game the tab is on, `null` on the catalog and other hub pages. */
+  game: Slug.nullable(),
+  /** That game's title, `null` with `game`. */
+  gameTitle: z.string().nullable(),
+  /** When this activity (kind + game) started (epoch ms). */
+  since: Millis,
+  /** Party size, present when the user is in a party of two or more. */
+  partySize: z.number().int().min(2).optional(),
+});
+
+/** A user's aggregated presence. */
+export type Presence = z.infer<typeof Presence>;
+
+/** A non-negative head count. */
+const HeadCount = z.number().int().nonnegative();
+
+/**
+ * Anonymous online counts (`GET /social/counts`, `ev:counts`, the `hello`
+ * snapshot): everyone with a live presence, guests and hidden players
+ * included.
+ */
+export const Counts = z.object({
+  /** Everyone online. */
+  online: HeadCount,
+  /** Players per game slug (games with nobody are absent). */
+  byGame: z.record(Slug, HeadCount),
+});
+
+/** Online counts. */
+export type Counts = z.infer<typeof Counts>;

package/src/api/social.ts

@@ -1,9 +1,9 @@
-/**
- * Friends, blocks, the social profile and settings, player cards and counts,
- * plus the shared social shapes (config, presence, people) the socket
- * `hello` snapshot and events reuse. Split by topic under `social/`.
- */
-export * from './social/config';
-export * from './social/presence';
-export * from './social/people';
-export * from './social/endpoints';
+/**
+ * Friends, blocks, the social profile and settings, player cards and counts,
+ * plus the shared social shapes (config, presence, people) the socket
+ * `hello` snapshot and events reuse. Split by topic under `social/`.
+ */
+export * from './social/config';
+export * from './social/presence';
+export * from './social/people';
+export * from './social/endpoints';

package/src/api/tournaments/endpoints.ts

@@ -0,0 +1,102 @@
+/**
+ * The tournament endpoints (batch-2026-10 R15). Anyone may look at open
+ * tournaments; a closed one answers 404 to everyone it wasn't shared with.
+ * Creating, inviting and following need a claimed account; guests may sign
+ * up for open tournaments (and for closed ones they were invited to) and
+ * play their matches.
+ */
+import { z } from 'zod';
+import { IdParam, Ok, Slug, UserId } from '../../common';
+import { ErrorBody } from '../../errors';
+import { requireActive, requireClaimed, session } from '../../middleware';
+import { TOURNAMENT_LIMITS } from '../../limits';
+import { LaunchTicket } from '../mp/parties';
+import { TournamentCreate, TournamentDetail, TournamentSummary } from './shapes';
+
+/** `:id` of a tournament. */
+const TournamentParams = z.object({ id: IdParam });
+
+/** `:id` and `:match` of a tournament match. */
+const MatchParams = z.object({ id: IdParam, match: z.string().regex(/^m\d{1,4}$/) });
+
+/** The invite key from a shared link (`?hub_key=`), letting its opener into a closed tournament. */
+const InviteKey = z.string().regex(/^[A-Za-z0-9_-]{8,64}$/);
+
+/** `GET /tournaments` filters. */
+export const TournamentListQuery = z.object({
+  /** Only tournaments in this game. */
+  game: z.union([z.literal(''), Slug]).optional(),
+});
+
+/** The tournament endpoints. */
+export const tournamentEndpoints = {
+  ...session.group({
+    listTournaments: {
+      method: 'GET', path: '/tournaments', query: TournamentListQuery,
+      response: z.object({ tournaments: z.array(TournamentSummary) }),
+      doc: { summary: 'Open tournaments plus the ones I am in, invited to or follow, soonest first', tags: ['tournaments'] },
+    },
+    getTournament: {
+      method: 'GET', path: '/tournaments/:id', params: TournamentParams,
+      query: z.object({ key: InviteKey.optional() }),
+      response: TournamentDetail,
+      errors: { 404: ErrorBody },
+      doc: { summary: 'A tournament with its players and bracket (404 for a closed one not shared with me)', tags: ['tournaments'] },
+    },
+  }),
+  ...requireClaimed.group({
+    createTournament: {
+      method: 'POST', path: '/tournaments', body: TournamentCreate, response: TournamentDetail,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 422: ErrorBody, 429: ErrorBody },
+      doc: { summary: 'Create a tournament (I am signed up to it); the title goes through the content filter', tags: ['tournaments'] },
+    },
+    inviteToTournament: {
+      method: 'POST', path: '/tournaments/:id/invites', params: TournamentParams,
+      body: z.object({ userIds: z.array(UserId).min(1).max(TOURNAMENT_LIMITS.invitesMax) }),
+      response: z.object({ invited: z.number().int().nonnegative() }),
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: 'Creator: invite friends (others are skipped without saying why)', tags: ['tournaments'] },
+    },
+    followTournament: {
+      method: 'PUT', path: '/tournaments/:id/follow', params: TournamentParams,
+      body: z.object({ leadMinutes: z.number().int().min(0).max(TOURNAMENT_LIMITS.leadMinutesMax).nullish() }),
+      response: TournamentSummary,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Follow a tournament (hear when it opens, starts and ends); leadMinutes: remind me that long before a scheduled start (absent: no reminder)', tags: ['tournaments'] },
+    },
+    unfollowTournament: {
+      method: 'DELETE', path: '/tournaments/:id/follow', params: TournamentParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Stop following a tournament', tags: ['tournaments'] },
+    },
+    startTournament: {
+      method: 'POST', path: '/tournaments/:id/start', params: TournamentParams, response: TournamentDetail,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'Creator: start now with whoever signed up (at least two)', tags: ['tournaments'] },
+    },
+    cancelTournament: {
+      method: 'DELETE', path: '/tournaments/:id', params: TournamentParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'Creator (or an admin): cancel a tournament that has not finished', tags: ['tournaments'] },
+    },
+  }),
+  ...requireActive.group({
+    joinTournament: {
+      method: 'POST', path: '/tournaments/:id/join', params: TournamentParams,
+      body: z.object({ key: InviteKey.optional() }),
+      response: TournamentDetail,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: 'Sign up (open tournaments, or closed ones I was invited to or have the link for)', tags: ['tournaments'] },
+    },
+    leaveTournament: {
+      method: 'POST', path: '/tournaments/:id/leave', params: TournamentParams, response: TournamentDetail,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'Drop out: before the start my place is freed; after it I forfeit what is left', tags: ['tournaments'] },
+    },
+    launchTournamentMatch: {
+      method: 'POST', path: '/tournaments/:id/matches/:match/launch', params: MatchParams, response: LaunchTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'A launch into my ready match: host for the better seed, guest for the other', tags: ['tournaments'] },
+    },
+  }),
+};

package/src/api/tournaments/play-online.ts

@@ -0,0 +1,71 @@
+/**
+ * "Play online" (batch-2026-10 R15): everything the viewer could play with
+ * someone, now and later, for the home page card and its modal. Public
+ * lobbies and races waiting for a player (joined through
+ * `POST /mp/join { userId, fromLobbyOpen: true }`), invites to the viewer,
+ * the tournaments they are in or follow (with a ready match first), and open
+ * tournaments still taking sign-ups.
+ */
+import { z } from 'zod';
+import { Millis, Slug } from '../../common';
+import { PlayerLite } from '../../entities';
+import { session } from '../../middleware';
+import { GameMode, Invite } from '../mp/parties';
+import { TournamentSummary } from './shapes';
+
+/** A public lobby or race waiting for players right now. */
+export const OpenLobbyEntry = z.object({
+  /** Who is waiting (join them with `POST /mp/join`). */
+  host: PlayerLite,
+  game: Slug,
+  gameTitle: z.string(),
+  /** `race` for a race waiting for racers, otherwise the lobby's mode when it has one. */
+  mode: GameMode.optional(),
+  openSeats: z.number().int().positive(),
+  /** When they started waiting, epoch ms. */
+  since: Millis,
+});
+
+/** A public lobby or race waiting for players. */
+export type OpenLobbyEntry = z.infer<typeof OpenLobbyEntry>;
+
+/** The counts on the home card. */
+export const PlayOnlineCounts = z.object({
+  /** Lobbies to join now, plus my matches that are ready. */
+  now: z.number().int().nonnegative(),
+  /** Game invites and tournament invites waiting for me. */
+  invites: z.number().int().nonnegative(),
+  /** Tournaments I signed up for or follow, not over. */
+  mine: z.number().int().nonnegative(),
+  /** Open tournaments still taking sign-ups. */
+  upcoming: z.number().int().nonnegative(),
+});
+
+/** The counts on the home card. */
+export type PlayOnlineCounts = z.infer<typeof PlayOnlineCounts>;
+
+/** Everything playable online for the viewer. */
+export const PlayOnline = z.object({
+  counts: PlayOnlineCounts,
+  lobbies: z.array(OpenLobbyEntry),
+  gameInvites: z.array(Invite),
+  /** Closed tournaments I'm invited to and haven't joined. */
+  tournamentInvites: z.array(TournamentSummary),
+  /** Mine: a ready match first, then the soonest. */
+  mine: z.array(TournamentSummary),
+  /** Open, taking sign-ups, not mine. */
+  upcoming: z.array(TournamentSummary),
+});
+
+/** Everything playable online for the viewer. */
+export type PlayOnline = z.infer<typeof PlayOnline>;
+
+/** The play-online endpoint. Signed-out visitors get the open tournaments only. */
+export const playOnlineEndpoints = {
+  ...session.group({
+    getPlayOnline: {
+      method: 'GET', path: '/play-online', response: PlayOnline,
+      doc: { summary: 'Lobbies to join now, invites, my tournaments and upcoming open ones (the home page card and modal)', tags: ['tournaments'] },
+    },
+  }),
+};

package/src/api/tournaments/shapes.ts

@@ -0,0 +1,202 @@
+/**
+ * Tournaments (batch-2026-10 R15): brackets of 1v1 matches in one game or a
+ * set of games. Single elimination, or double/triple elimination with
+ * redemption brackets; seeded by rank in the game or at random; started at a
+ * scheduled time or once enough players sign up. Open tournaments are
+ * listed for anyone; closed ones only for the players invited.
+ *
+ * A match is an ordinary launch into the game (`host` for the better seed,
+ * `guest` for the other, sharing a two-player party), carrying
+ * {@link TournamentLaunch}; the game reports the winner the way it already
+ * ends a match.
+ */
+import { z } from 'zod';
+import { Millis, Slug, UserId } from '../../common';
+import { PlayerLite } from '../../entities';
+import { TOURNAMENT_LIMITS } from '../../limits';
+
+/** A tournament's id. */
+export const TournamentId = z.number().int().positive();
+
+/** `open`: listed, anyone can sign up or follow. `closed`: only invited players see it. */
+export const TournamentVisibility = z.enum(['open', 'closed']);
+
+/** How the bracket is seeded: by each player's wins in the tournament's games, or at random. */
+export const TournamentSeeding = z.enum(['rank', 'random']);
+
+/** Which game each match is: the one game, one random pick from the set for the whole tournament, or a random pick per match. */
+export const TournamentGamePick = z.enum(['fixed', 'random-once', 'random-each']);
+
+/** When a tournament starts: at a set time (with whoever signed up), or as soon as `minPlayers` sign up. */
+export const TournamentStart = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('scheduled'), at: Millis }),
+  z.object({ kind: z.literal('filled') }),
+]);
+
+/** When a tournament starts. */
+export type TournamentStart = z.infer<typeof TournamentStart>;
+
+/** `signup` → `running` → `done`; or `cancelled` (by its creator, or too few players at the start). */
+export const TournamentPhase = z.enum(['signup', 'running', 'done', 'cancelled']);
+
+/** A tournament's phase. */
+export type TournamentPhase = z.infer<typeof TournamentPhase>;
+
+/** Where a match sits: the winners bracket, a redemption bracket (players with losses), or the final ladder. */
+export const TournamentStage = z.enum(['winners', 'redemption', 'final']);
+
+/** How a match was decided. */
+export const TournamentDecision = z.enum(['played', 'forfeit', 'bye', 'timeout', 'withdrawn']);
+
+/** How a match was decided. */
+export type TournamentDecision = z.infer<typeof TournamentDecision>;
+
+/** A player count within the tournament limits. */
+const PlayerCount = z.number().int().min(TOURNAMENT_LIMITS.playersMin).max(TOURNAMENT_LIMITS.playersMax);
+
+/** `POST /tournaments`. Everything but `games` has a default: the quick "public 1v1, single elimination". */
+export const TournamentCreate = z.object({
+  /** Shown to everyone who can see the tournament; checked by the content filter. Default: made from the game's title. */
+  title: z.string().trim().min(1).max(TOURNAMENT_LIMITS.titleMax).optional(),
+  /** The game, or the set to pick from; each must support tournaments. */
+  games: z.array(Slug).min(1).max(TOURNAMENT_LIMITS.gamesMax),
+  pick: TournamentGamePick.default('fixed'),
+  /** Lives per player: 1 single (default), 2 double, 3 triple elimination. */
+  lives: z.number().int().min(1).max(TOURNAMENT_LIMITS.livesMax).default(1),
+  seeding: TournamentSeeding.default('random'),
+  visibility: TournamentVisibility.default('open'),
+  start: TournamentStart.default({ kind: 'filled' }),
+  /** Players needed to start (a `filled` start), or to go ahead at the scheduled time. Default 2. */
+  minPlayers: PlayerCount.default(2),
+  /** Most players who can sign up. Default 2. */
+  maxPlayers: PlayerCount.default(2),
+  /** Minutes a ready match waits for its players before the absent side forfeits. */
+  readyMinutes: z.number().int().min(1).max(TOURNAMENT_LIMITS.readyMinutesMax).default(TOURNAMENT_LIMITS.readyMinutesDefault),
+  /** Friends to invite now (closed tournaments, or a nudge for open ones). */
+  invite: z.array(UserId).max(TOURNAMENT_LIMITS.invitesMax).optional(),
+});
+
+/** What creating a tournament takes. */
+export type TournamentCreate = z.output<typeof TournamentCreate>;
+
+/** One entrant, as the bracket shows them. */
+export const TournamentPlayer = z.object({
+  user: PlayerLite,
+  /** 1 is the top seed; `null` until the bracket is drawn. */
+  seed: z.number().int().positive().nullable(),
+  wins: z.number().int().nonnegative(),
+  losses: z.number().int().nonnegative(),
+  /** Knocked out (lost every life, or withdrew). */
+  out: z.boolean(),
+});
+
+/** One entrant. */
+export type TournamentPlayer = z.infer<typeof TournamentPlayer>;
+
+/** One match in the bracket. Sides are user ids (see the detail's `players`). */
+export const TournamentMatch = z.object({
+  id: z.string(),
+  stage: TournamentStage,
+  /** Redemption bracket number (losses), 0 elsewhere. */
+  level: z.number().int().nonnegative(),
+  round: z.number().int().positive(),
+  slot: z.number().int().nonnegative(),
+  /** `null` while unknown, or the empty side of a bye. */
+  a: UserId.nullable(),
+  b: UserId.nullable(),
+  status: z.enum(['waiting', 'ready', 'done']),
+  winnerId: UserId.nullable(),
+  decision: TournamentDecision.nullable(),
+  /** The game this match is played in, once known. */
+  game: Slug.nullable(),
+  /** Ready matches: when the absent side forfeits, epoch ms. */
+  deadlineAt: Millis.nullable(),
+  /** Whether the match has started in the game. */
+  started: z.boolean(),
+});
+
+/** One match. */
+export type TournamentMatch = z.infer<typeof TournamentMatch>;
+
+/** A ready match of mine: who against, in which game, and until when. */
+export const MyTournamentMatch = z.object({
+  id: z.string(),
+  opponent: PlayerLite.nullable(),
+  game: Slug,
+  gameTitle: z.string(),
+  deadlineAt: Millis,
+  started: z.boolean(),
+});
+
+/** A ready match of mine. */
+export type MyTournamentMatch = z.infer<typeof MyTournamentMatch>;
+
+/** The viewer's own relation to a tournament. */
+export const TournamentMe = z.object({
+  joined: z.boolean(),
+  /** Invited and not yet signed up. */
+  invited: z.boolean(),
+  following: z.boolean(),
+  /** Minutes before a scheduled start to remind me; `null` for no reminder. */
+  leadMinutes: z.number().int().nonnegative().nullable(),
+  isCreator: z.boolean(),
+  /** Still in (signed up and not knocked out). */
+  stillIn: z.boolean(),
+  nextMatch: MyTournamentMatch.nullable(),
+});
+
+/** A tournament in lists. */
+export const TournamentSummary = z.object({
+  id: TournamentId,
+  title: z.string(),
+  creator: PlayerLite.nullable(),
+  visibility: TournamentVisibility,
+  phase: TournamentPhase,
+  /** The game set (one game for `fixed`). */
+  games: z.array(Slug),
+  pick: TournamentGamePick,
+  /** The game every match is in, once known (`fixed`, or `random-once` after the start); `null` for `random-each`. */
+  game: Slug.nullable(),
+  /** A title per game slug. */
+  gameTitles: z.record(Slug, z.string()),
+  lives: z.number().int().min(1),
+  seeding: TournamentSeeding,
+  start: TournamentStart,
+  minPlayers: z.number().int(),
+  maxPlayers: z.number().int(),
+  readyMinutes: z.number().int(),
+  /** How many have signed up. */
+  entrants: z.number().int().nonnegative(),
+  createdAt: Millis,
+  startedAt: Millis.nullable(),
+  endedAt: Millis.nullable(),
+  champion: PlayerLite.nullable(),
+  me: TournamentMe,
+});
+
+/** A tournament in lists. */
+export type TournamentSummary = z.infer<typeof TournamentSummary>;
+
+/** A tournament with its players and bracket. */
+export const TournamentDetail = TournamentSummary.extend({
+  players: z.array(TournamentPlayer),
+  matches: z.array(TournamentMatch),
+  /** The creator's link that lets friends of friends in (closed tournaments, creator only). */
+  inviteUrl: z.string().nullable(),
+});
+
+/** A tournament with its bracket. */
+export type TournamentDetail = z.infer<typeof TournamentDetail>;
+
+/** What a launch into a tournament match carries (`launch.tournament`). */
+export const TournamentLaunch = z.object({
+  id: TournamentId,
+  title: z.string(),
+  /** The match id within the tournament; own-server games send it back with the result. */
+  match: z.string(),
+  /** Who to play. */
+  opponent: PlayerLite.nullable(),
+});
+
+/** What a launch into a tournament match carries. */
+export type TournamentLaunch = z.infer<typeof TournamentLaunch>;

package/src/api/tournaments.ts

@@ -0,0 +1,7 @@
+/**
+ * Tournaments and "Play online" (batch-2026-10 R15), split by topic under
+ * `tournaments/`.
+ */
+export * from './tournaments/shapes';
+export * from './tournaments/endpoints';
+export * from './tournaments/play-online';