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

package/src/api/mp.ts

@@ -9,9 +9,11 @@ import { z } from 'zod';
 import { Millis, Ok, Slug, UserIdParam } from '../common';
 import { ErrorBody } from '../errors';
 import { requireActive, requireClaimed } from '../middleware';
+import { InviteLink, InviteLinkCreate, InviteLinkParams, InviteLinkQuery } from './mp/invite-links';
 import { GameMode, Invite, JoinInfo, Launch, LaunchTicket, OpaqueId } from './mp/parties';
 
 export * from './mp/chat';
+export * from './mp/invite-links';
 export * from './mp/parties';
 export * from './mp/races';
 export * from './mp/rooms';
@@ -60,6 +62,24 @@ export const mpEndpoints = {
       errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
       doc: { summary: 'Decline an invite addressed to you', tags: ['mp'] },
     },
+    createInviteLink: {
+      method: 'POST', path: '/mp/links', body: InviteLinkCreate, response: InviteLink,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: "An invite link to the room I'm in (reused while it lives): anyone who opens it joins, or watches when it's full",
+        tags: ['mp'],
+      },
+    },
+    listInviteLinks: {
+      method: 'GET', path: '/mp/links', query: InviteLinkQuery, response: z.object({ links: z.array(InviteLink) }),
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'My live invite links in a game, plus the links to rooms I host', tags: ['mp'] },
+    },
+    revokeInviteLink: {
+      method: 'DELETE', path: '/mp/links/:token', params: InviteLinkParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Revoke an invite link (its creator, or the host of the room it opens)", tags: ['mp'] },
+    },
     cancelGameInvite: {
       method: 'DELETE', path: '/mp/invites/:id', params: IdParams, response: Ok,
       errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
@@ -73,6 +93,11 @@ export const mpEndpoints = {
       errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
       doc: { summary: 'Redeem a launch token (single use, bound to the signed-in user)', tags: ['mp'] },
     },
+    openInviteLink: {
+      method: 'POST', path: '/mp/links/:token/open', params: InviteLinkParams, response: LaunchTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: 'Open an invite link: a join launch when a seat is free, else a watch launch', tags: ['mp'] },
+    },
     setPartyJoinInfo: {
       method: 'POST', path: '/mp/parties/:id/join-info', params: IdParams,
       body: z.object({ info: JoinInfo }),

package/src/api/notify.ts

@@ -19,7 +19,10 @@ export const NotifyPrefs = z.object({
   friendOnlineAll: z.boolean(),
   /** Friends whose bell is on, ascending. */
   friendOnline: z.array(UserId),
-  /** Games followed for "someone's waiting in a lobby", sorted. */
+  /**
+   * Games followed for "someone wants to play" (the game sheet's notify toggle):
+   * an open public lobby or race, or a tournament opening, sorted.
+   */
   lobbyOpen: z.array(Slug),
 });
 

package/src/api/offline.ts

@@ -0,0 +1,45 @@
+/**
+ * Offline replay metadata: which public endpoints a client may queue while
+ * offline and send later, and how the hub makes a replay land exactly once.
+ *
+ * A replayable call carries a client-made operation key in the
+ * {@link OFFLINE_OP_HEADER} header. The hub remembers the reply to each key
+ * for {@link OFFLINE_DEDUPE_TTL_MS}; a second request with the same key gets
+ * that reply again without running the endpoint twice. Endpoints left out
+ * are online-only (social, multiplayer, trades) or replay on their own terms
+ * (analytics events are buffered and sent at least once, without a key).
+ */
+import { z } from 'zod';
+
+/** The request header that carries a replayable call's operation key. */
+export const OFFLINE_OP_HEADER = 'x-hub-op';
+
+/** An operation key: letters, digits and `_ . : -`, 1 to 100 characters. */
+export const OfflineOpKey = z.string().regex(/^[A-Za-z0-9_.:-]{1,100}$/);
+
+/** How long the hub remembers an operation key's reply: 7 days. */
+export const OFFLINE_DEDUPE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** How an endpoint behaves offline: `replay` means it may be queued and sent later, deduplicated by its operation key. */
+export type OfflineMode = 'replay';
+
+/** The public endpoints that support offline replay, by name. */
+export const OFFLINE_REPLAY_ENDPOINTS = {
+  writeSave: 'replay',
+  deleteSave: 'replay',
+  updateGameStat: 'replay',
+  setGameProfile: 'replay',
+  submitScore: 'replay',
+  completeDailyChallenge: 'replay',
+  grantInventoryItems: 'replay',
+  exchangeInventoryItems: 'replay',
+  setGameFavorite: 'replay',
+} as const satisfies Readonly<Record<string, OfflineMode>>;
+
+/** The name of an endpoint that supports offline replay. */
+export type OfflineReplayEndpoint = keyof typeof OFFLINE_REPLAY_ENDPOINTS;
+
+/** Whether endpoint `name` supports offline replay. */
+export function isOfflineReplayEndpoint(name: string): name is OfflineReplayEndpoint {
+  return Object.hasOwn(OFFLINE_REPLAY_ENDPOINTS, name);
+}

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';

package/src/errors/codes/multiplayer.ts

@@ -1,4 +1,4 @@
-/** Error codes from invites, parties, hub rooms, races and the socket envelope. */
+/** Error codes from invites, invite links, parties, hub rooms, races, tournaments and the socket envelope. */
 export const MULTIPLAYER_CODES = [
   // Socket envelope.
   'unknown_op',
@@ -18,6 +18,10 @@ export const MULTIPLAYER_CODES = [
   'bad_info',
   'launch_invalid',
   'not_joinable',
+  // Invite links.
+  'link_invalid',
+  'link_room_gone',
+  'too_many_links',
   // Group chat.
   'bad_quick',
   // Hub rooms.
@@ -40,4 +44,13 @@ export const MULTIPLAYER_CODES = [
   'too_fast',
   'bad_stats',
   'bad_param',
+  // Tournaments.
+  'tournament_not_found',
+  'tournament_closed',
+  'tournament_full',
+  'tournament_over',
+  'not_creator',
+  'not_entered',
+  'cannot_join',
+  'match_not_ready',
 ] as const;

package/src/limits.ts

@@ -98,3 +98,28 @@ export const MANIFEST_LIMITS = {
   /** Largest `game.race.minMs`, in ms (10 minutes). */
   raceMinMsMax: 600_000,
 } as const;
+
+/** What a tournament may be (batch-2026-10 R15). The server enforces each one. */
+export const TOURNAMENT_LIMITS = {
+  /** Longest title, in characters. */
+  titleMax: 48,
+  /** Fewest players. */
+  playersMin: 2,
+  /** Most players. */
+  playersMax: 64,
+  /** Most games in the set a tournament picks from. */
+  gamesMax: 8,
+  /** Lives per player: 1 single, 2 double, 3 triple elimination. */
+  livesMax: 3,
+  /** The default and the longest window to join a ready match before forfeiting, in minutes. */
+  readyMinutesDefault: 10,
+  readyMinutesMax: 60,
+  /** The longest "remind me before it starts", in minutes (one day). */
+  leadMinutesMax: 1440,
+  /** The default reminder for players who signed up for a scheduled tournament, in minutes. */
+  leadMinutesDefault: 10,
+  /** The furthest ahead a tournament may be scheduled, in days. */
+  scheduleDaysMax: 30,
+  /** Most friends invited in one call. */
+  invitesMax: 50,
+} as const;

package/src/manifest/game.ts

@@ -11,6 +11,7 @@ import { MANIFEST_LIMITS } from '../limits';
 import { GameChanges } from './changes';
 import { GameControls } from './controls';
 import { AppFilePath, Command, Trimmed, orFalse } from './fields';
+import { GameLabels } from './labels';
 import { GameLeaderboardDecls } from './leaderboards';
 import { GameMultiplayer, StaticGameMultiplayer } from './multiplayer';
 import { GameRace } from './race';
@@ -63,6 +64,12 @@ const commonFields = {
   menuPosition: MenuPosition.optional(),
   /** Push the menu button away from its corner, px: a number (vertical) or `{ x, y }`. */
   menuOffset: MenuOffset.optional(),
+  /**
+   * What kind of game it is, from the fixed vocabulary in `labels.ts` (genre, look,
+   * where it plays, how many play), for the catalog's label filter. Unknown labels
+   * are a warning, not an error.
+   */
+  labels: GameLabels.optional(),
   /** `true` opts into the shared daily challenges (`hub.daily.define(...)`). */
   dailyChallenges: z.boolean().optional(),
   /** Boards to create up front, so they show before the first score. */

package/src/manifest/index.ts

@@ -7,6 +7,7 @@ export * from './controls';
 export { AppFilePath, COMMAND_PLACEHOLDERS, Command, LobbySuffix } from './fields';
 export * from './game';
 export * from './inject';
+export * from './labels';
 export * from './leaderboards';
 export * from './multiplayer';
 export * from './race';