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

package/src/api/mp/invite-links.ts

@@ -0,0 +1,42 @@
+/**
+ * Invite links (batch-2026-10 R13): a link any room member can share that
+ * drops whoever opens it into that room, as a player when a seat is free,
+ * otherwise as a spectator. A link is an unguessable token kept by the hub;
+ * it expires (24 h) and its creator or the room's host can revoke it. Link
+ * joiners get the room's usual chat rules and are not friended.
+ */
+import { z } from 'zod';
+import { Millis, Slug, UserId } from '../../common';
+import { GameMode } from './parties';
+
+/** An invite link's token (base64url). */
+export const InviteLinkToken = z.string().regex(/^[A-Za-z0-9_-]{16,64}$/);
+
+/** A live invite link. */
+export const InviteLink = z.object({
+  token: InviteLinkToken,
+  /** `/<slug>/<lobby>?hub_link=<token>`, relative to the site origin. */
+  url: z.string(),
+  game: Slug,
+  mode: GameMode.optional(),
+  /** The room it opens: a hub room code, or an own-server game's room id from presence. */
+  room: z.string(),
+  /** Who made it. */
+  createdBy: UserId,
+  /** Epoch ms. */
+  expiresAt: Millis,
+});
+
+/** An invite link. */
+export type InviteLink = z.infer<typeof InviteLink>;
+
+/** `:token` of an invite link. */
+export const InviteLinkParams = z.object({ token: InviteLinkToken });
+
+/** `POST /mp/links` body: a link to the room I'm in, in this game. */
+export const InviteLinkCreate = z.object({ game: Slug });
+
+/** `GET /mp/links` query: my links in a game (and the links to rooms I host). */
+export const InviteLinkQuery = z.object({ game: Slug });
+
+

package/src/api/mp/parties.ts

@@ -7,6 +7,7 @@
 import { z } from 'zod';
 import { Millis, Slug, UserId } from '../../common';
 import { PlayerLite } from '../../entities';
+import { TournamentLaunch } from '../tournaments/shapes';
 
 /** A game mode key, as the game's `multiplayer.modes[].key` declares it: `[A-Za-z0-9_-]{1,32}`. */
 export const GameMode = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/);
@@ -102,6 +103,10 @@ export const Launch = z.object({
   host: PlayerLite.nullable().optional(),
   /** Join and watch launches: the friend being joined (`null` if the account is gone). */
   target: PlayerLite.nullable().optional(),
+  /** `link`: opened from an invite link; `rejoin`: taking back a seat I still hold (both are join or watch launches). */
+  via: z.enum(['link', 'rejoin']).optional(),
+  /** Host and guest launches into a tournament match: which tournament, which match, and who to play. */
+  tournament: TournamentLaunch.optional(),
 });
 
 /** A launch. */

package/src/api/mp/races.ts

@@ -1,211 +1,211 @@
-/**
- * Race shapes (docs/plans/race.md): params, live stats, racers and decided
- * results. Shared by the `race.*` socket ops and events, the race block of
- * a room, and `GET /race/history`. Each rule here is defined once.
- */
-import { z } from 'zod';
-import { HexColor, Millis, Slug, UserId } from '../../common';
-import { RACE_STATS_LIMITS } from '../../limits';
-
-/** A race param or stat key: a letter, then up to 23 letters, digits or `_`. */
-export const RaceKey = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,23}$/);
-
-/** A race param value, one of the game's declared options: a number, a boolean or a short token. */
-export const RaceParamValue = z.union([
-  z.number(),
-  z.boolean(),
-  z.string().regex(/^[A-Za-z0-9_-]{1,24}$/),
-]);
-
-/**
- * The creator's choices, keyed by the manifest's `race.params[].key`. The
- * hub keeps only declared keys and option values (anything else becomes the
- * param's default), so everyone gets the same puzzle.
- */
-export const RaceParams = z.record(RaceKey, RaceParamValue);
-
-/** A race's params. */
-export type RaceParams = z.infer<typeof RaceParams>;
-
-/** Live stat values are clamped to ±1e9. */
-const STAT_LIMIT = 1e9;
-
-/**
- * A live stat value: a finite number (clamped to ±1e9), a boolean or a
- * `#rrggbb` colour (lower-cased). Never text.
- */
-export const RaceStatValue = z.union([
-  z.number().transform((n) => Math.max(-STAT_LIMIT, Math.min(STAT_LIMIT, n))),
-  z.boolean(),
-  HexColor.transform((c) => c.toLowerCase()),
-]);
-
-/** A live stat value, as cleaned by the hub. */
-export type RaceStatValue = z.output<typeof RaceStatValue>;
-
-/**
- * A racer's live stats, keyed like the manifest's `race.stats[].key`: at
- * most 12 keys and 600 bytes of JSON once cleaned.
- */
-export const RaceStats = z
-  .record(RaceKey, RaceStatValue)
-  .refine((s) => Object.keys(s).length <= RACE_STATS_LIMITS.maxKeys, `at most ${String(RACE_STATS_LIMITS.maxKeys)} stats`)
-  .refine((s) => JSON.stringify(s).length <= RACE_STATS_LIMITS.maxBytes, 'stats too large');
-
-/** A racer's stats. */
-export type RaceStats = z.infer<typeof RaceStats>;
-
-/** How far along a racer is, 0 to 1. The hub clamps values outside that range. */
-export const RaceProgress = z.number().transform((n) => Math.max(0, Math.min(1, n)));
-
-/** A race room's phase: waiting for racers → countdown → racing → done (→ countdown on a rematch). */
-export const RacePhase = z.enum(['waiting', 'countdown', 'racing', 'done']);
-
-/** A racer's state while the race runs. */
-export const RacerState = z.enum(['racing', 'finished', 'lost', 'forfeit', 'disconnected']);
-
-/** A value of {@link RacerState}. */
-export type RacerState = z.infer<typeof RacerState>;
-
-/** How a race ended: the winner finished, everyone else lost / gave up / dropped, or time ran out. */
-export const RaceOutcome = z.enum(['finished', 'lost', 'forfeit', 'disconnected', 'timeout']);
-
-/** A value of {@link RaceOutcome}. */
-export type RaceOutcome = z.infer<typeof RaceOutcome>;
-
-/** One racer's result. `beaten`: still racing when someone else won. */
-export const RacerResult = z.enum(['won', 'beaten', 'lost', 'forfeit', 'disconnected', 'timeout']);
-
-/** A value of {@link RacerResult}. */
-export type RacerResult = z.infer<typeof RacerResult>;
-
-/** Fields every live racer line has (room roster and result card). */
-const RacerLine = z.object({
-  userId: UserId,
-  /** The racer's username when the race began. */
-  name: z.string(),
-  /** Avatar token; never empty. */
-  avatar: z.string(),
-  stats: RaceStats,
-  /** 0..1, when the game reports it. */
-  progress: RaceProgress.optional(),
-});
-
-/** A racer in a race room's roster (RoomInfo.race.players). */
-export const Racer = RacerLine.extend({
-  state: RacerState,
-  /** Server-measured ms from the go to finishing or dropping out. */
-  ms: z.number().int().nonnegative().optional(),
-});
-
-/** A racer in a race room. */
-export type Racer = z.infer<typeof Racer>;
-
-/** One racer's line in a {@link RaceResult}. */
-export const RaceResultPlayer = RacerLine.extend({
-  /** 1 for the winner. */
-  place: z.number().int().positive(),
-  result: RacerResult,
-  /** Server-measured ms from the go to finishing or dropping out (the race's end for those still in). */
-  ms: z.number().int().nonnegative(),
-});
-
-/** Fields a decided race has both live and in the history. */
-const DecidedRace = z.object({
-  game: Slug,
-  params: RaceParams,
-  outcome: RaceOutcome,
-  /** Epoch ms of the go. */
-  startedAt: Millis,
-  /** Epoch ms. */
-  endedAt: Millis,
-  /** ms from the go to the decision. */
-  durationMs: z.number().int().nonnegative(),
-});
-
-/** A decided race: the `race.result` event, the `race.finish` ack and RoomInfo.race.result. */
-export const RaceResult = DecidedRace.extend({
-  /** The race's id in the history; `null` if recording it failed. */
-  id: z.number().int().positive().nullable(),
-  /** The room code. */
-  room: z.string(),
-  /** 1 for the room's first race, +1 per rematch. */
-  round: z.number().int().positive(),
-  seed: z.number().int().positive(),
-  /** `null` when nobody won (time ran out, or everyone dropped out). */
-  winnerId: UserId.nullable(),
-  /** In finishing order (place 1 first). */
-  players: z.array(RaceResultPlayer),
-});
-
-/** A decided race. */
-export type RaceResult = z.infer<typeof RaceResult>;
-
-/** The referee's view of a race room (RoomInfo.race). */
-export const RaceState = z.object({
-  phase: RacePhase,
-  /** 1 for the first race in the room, +1 per rematch; 0 while waiting for the first. */
-  round: z.number().int().nonnegative(),
-  params: RaceParams,
-  /** The countdown can start once this many racers are seated. */
-  minPlayers: z.number().int().positive(),
-  /** Everyone racing this round (empty while waiting for the first). */
-  players: z.array(Racer),
-  /** Who asked for a rematch since the last race. */
-  rematch: z.array(UserId),
-  /** Present once the countdown starts (never before, so nobody can pre-solve). */
-  seed: z.number().int().positive().optional(),
-  /** Epoch ms of the go (server clock); present with `seed`. */
-  startAt: Millis.optional(),
-  /** Present once the round is decided. */
-  result: RaceResult.optional(),
-});
-
-/** A race room's referee state. */
-export type RaceState = z.infer<typeof RaceState>;
-
-/** The countdown began (`race.start`): build the puzzle from `seed` + `params`. */
-export const RaceStart = z.object({
-  roomId: z.string(),
-  round: z.number().int().positive(),
-  seed: z.number().int().positive(),
-  params: RaceParams,
-  /** Epoch ms of the go (server clock). */
-  startAt: Millis,
-  /** ms until the go. */
-  startsIn: z.number().int().nonnegative(),
-  /** The racers' user ids. */
-  players: z.array(UserId),
-});
-
-/** A racer in a history record. Suspended opponents are `hidden`: id 0, name "A player", no avatar. */
-export const RaceRecordPlayer = z.object({
-  /** 0 when hidden. */
-  userId: z.number().int().nonnegative(),
-  username: z.string(),
-  /** Avatar token; `''` when hidden. */
-  avatar: z.string(),
-  guest: z.boolean(),
-  place: z.number().int().positive(),
-  result: RacerResult,
-  /** Server-measured ms from the go to finishing or dropping out. */
-  ms: z.number().int().nonnegative().optional(),
-  progress: RaceProgress.optional(),
-  stats: RaceStats,
-  hidden: z.literal(true).optional(),
-});
-
-/** One past race the player was in (`GET /race/history`). */
-export const RaceRecord = DecidedRace.extend({
-  id: z.number().int().positive(),
-  gameTitle: z.string(),
-  /** `null` when nobody won; 0 when the winner is hidden (suspended). */
-  winnerId: z.number().int().nonnegative().nullable(),
-  /** The signed-in player's own line (`null` only if their row is missing). */
-  me: RaceRecordPlayer.nullable(),
-  /** In place order. */
-  players: z.array(RaceRecordPlayer),
-});
-
-/** A past race. */
-export type RaceRecord = z.infer<typeof RaceRecord>;
+/**
+ * Race shapes (docs/plans/race.md): params, live stats, racers and decided
+ * results. Shared by the `race.*` socket ops and events, the race block of
+ * a room, and `GET /race/history`. Each rule here is defined once.
+ */
+import { z } from 'zod';
+import { HexColor, Millis, Slug, UserId } from '../../common';
+import { RACE_STATS_LIMITS } from '../../limits';
+
+/** A race param or stat key: a letter, then up to 23 letters, digits or `_`. */
+export const RaceKey = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,23}$/);
+
+/** A race param value, one of the game's declared options: a number, a boolean or a short token. */
+export const RaceParamValue = z.union([
+  z.number(),
+  z.boolean(),
+  z.string().regex(/^[A-Za-z0-9_-]{1,24}$/),
+]);
+
+/**
+ * The creator's choices, keyed by the manifest's `race.params[].key`. The
+ * hub keeps only declared keys and option values (anything else becomes the
+ * param's default), so everyone gets the same puzzle.
+ */
+export const RaceParams = z.record(RaceKey, RaceParamValue);
+
+/** A race's params. */
+export type RaceParams = z.infer<typeof RaceParams>;
+
+/** Live stat values are clamped to ±1e9. */
+const STAT_LIMIT = 1e9;
+
+/**
+ * A live stat value: a finite number (clamped to ±1e9), a boolean or a
+ * `#rrggbb` colour (lower-cased). Never text.
+ */
+export const RaceStatValue = z.union([
+  z.number().transform((n) => Math.max(-STAT_LIMIT, Math.min(STAT_LIMIT, n))),
+  z.boolean(),
+  HexColor.transform((c) => c.toLowerCase()),
+]);
+
+/** A live stat value, as cleaned by the hub. */
+export type RaceStatValue = z.output<typeof RaceStatValue>;
+
+/**
+ * A racer's live stats, keyed like the manifest's `race.stats[].key`: at
+ * most 12 keys and 600 bytes of JSON once cleaned.
+ */
+export const RaceStats = z
+  .record(RaceKey, RaceStatValue)
+  .refine((s) => Object.keys(s).length <= RACE_STATS_LIMITS.maxKeys, `at most ${String(RACE_STATS_LIMITS.maxKeys)} stats`)
+  .refine((s) => JSON.stringify(s).length <= RACE_STATS_LIMITS.maxBytes, 'stats too large');
+
+/** A racer's stats. */
+export type RaceStats = z.infer<typeof RaceStats>;
+
+/** How far along a racer is, 0 to 1. The hub clamps values outside that range. */
+export const RaceProgress = z.number().transform((n) => Math.max(0, Math.min(1, n)));
+
+/** A race room's phase: waiting for racers → countdown → racing → done (→ countdown on a rematch). */
+export const RacePhase = z.enum(['waiting', 'countdown', 'racing', 'done']);
+
+/** A racer's state while the race runs. */
+export const RacerState = z.enum(['racing', 'finished', 'lost', 'forfeit', 'disconnected']);
+
+/** A value of {@link RacerState}. */
+export type RacerState = z.infer<typeof RacerState>;
+
+/** How a race ended: the winner finished, everyone else lost / gave up / dropped, or time ran out. */
+export const RaceOutcome = z.enum(['finished', 'lost', 'forfeit', 'disconnected', 'timeout']);
+
+/** A value of {@link RaceOutcome}. */
+export type RaceOutcome = z.infer<typeof RaceOutcome>;
+
+/** One racer's result. `beaten`: still racing when someone else won. */
+export const RacerResult = z.enum(['won', 'beaten', 'lost', 'forfeit', 'disconnected', 'timeout']);
+
+/** A value of {@link RacerResult}. */
+export type RacerResult = z.infer<typeof RacerResult>;
+
+/** Fields every live racer line has (room roster and result card). */
+const RacerLine = z.object({
+  userId: UserId,
+  /** The racer's username when the race began. */
+  name: z.string(),
+  /** Avatar token; never empty. */
+  avatar: z.string(),
+  stats: RaceStats,
+  /** 0..1, when the game reports it. */
+  progress: RaceProgress.optional(),
+});
+
+/** A racer in a race room's roster (RoomInfo.race.players). */
+export const Racer = RacerLine.extend({
+  state: RacerState,
+  /** Server-measured ms from the go to finishing or dropping out. */
+  ms: z.number().int().nonnegative().optional(),
+});
+
+/** A racer in a race room. */
+export type Racer = z.infer<typeof Racer>;
+
+/** One racer's line in a {@link RaceResult}. */
+export const RaceResultPlayer = RacerLine.extend({
+  /** 1 for the winner. */
+  place: z.number().int().positive(),
+  result: RacerResult,
+  /** Server-measured ms from the go to finishing or dropping out (the race's end for those still in). */
+  ms: z.number().int().nonnegative(),
+});
+
+/** Fields a decided race has both live and in the history. */
+const DecidedRace = z.object({
+  game: Slug,
+  params: RaceParams,
+  outcome: RaceOutcome,
+  /** Epoch ms of the go. */
+  startedAt: Millis,
+  /** Epoch ms. */
+  endedAt: Millis,
+  /** ms from the go to the decision. */
+  durationMs: z.number().int().nonnegative(),
+});
+
+/** A decided race: the `race.result` event, the `race.finish` ack and RoomInfo.race.result. */
+export const RaceResult = DecidedRace.extend({
+  /** The race's id in the history; `null` if recording it failed. */
+  id: z.number().int().positive().nullable(),
+  /** The room code. */
+  room: z.string(),
+  /** 1 for the room's first race, +1 per rematch. */
+  round: z.number().int().positive(),
+  seed: z.number().int().positive(),
+  /** `null` when nobody won (time ran out, or everyone dropped out). */
+  winnerId: UserId.nullable(),
+  /** In finishing order (place 1 first). */
+  players: z.array(RaceResultPlayer),
+});
+
+/** A decided race. */
+export type RaceResult = z.infer<typeof RaceResult>;
+
+/** The referee's view of a race room (RoomInfo.race). */
+export const RaceState = z.object({
+  phase: RacePhase,
+  /** 1 for the first race in the room, +1 per rematch; 0 while waiting for the first. */
+  round: z.number().int().nonnegative(),
+  params: RaceParams,
+  /** The countdown can start once this many racers are seated. */
+  minPlayers: z.number().int().positive(),
+  /** Everyone racing this round (empty while waiting for the first). */
+  players: z.array(Racer),
+  /** Who asked for a rematch since the last race. */
+  rematch: z.array(UserId),
+  /** Present once the countdown starts (never before, so nobody can pre-solve). */
+  seed: z.number().int().positive().optional(),
+  /** Epoch ms of the go (server clock); present with `seed`. */
+  startAt: Millis.optional(),
+  /** Present once the round is decided. */
+  result: RaceResult.optional(),
+});
+
+/** A race room's referee state. */
+export type RaceState = z.infer<typeof RaceState>;
+
+/** The countdown began (`race.start`): build the puzzle from `seed` + `params`. */
+export const RaceStart = z.object({
+  roomId: z.string(),
+  round: z.number().int().positive(),
+  seed: z.number().int().positive(),
+  params: RaceParams,
+  /** Epoch ms of the go (server clock). */
+  startAt: Millis,
+  /** ms until the go. */
+  startsIn: z.number().int().nonnegative(),
+  /** The racers' user ids. */
+  players: z.array(UserId),
+});
+
+/** A racer in a history record. Suspended opponents are `hidden`: id 0, name "A player", no avatar. */
+export const RaceRecordPlayer = z.object({
+  /** 0 when hidden. */
+  userId: z.number().int().nonnegative(),
+  username: z.string(),
+  /** Avatar token; `''` when hidden. */
+  avatar: z.string(),
+  guest: z.boolean(),
+  place: z.number().int().positive(),
+  result: RacerResult,
+  /** Server-measured ms from the go to finishing or dropping out. */
+  ms: z.number().int().nonnegative().optional(),
+  progress: RaceProgress.optional(),
+  stats: RaceStats,
+  hidden: z.literal(true).optional(),
+});
+
+/** One past race the player was in (`GET /race/history`). */
+export const RaceRecord = DecidedRace.extend({
+  id: z.number().int().positive(),
+  gameTitle: z.string(),
+  /** `null` when nobody won; 0 when the winner is hidden (suspended). */
+  winnerId: z.number().int().nonnegative().nullable(),
+  /** The signed-in player's own line (`null` only if their row is missing). */
+  me: RaceRecordPlayer.nullable(),
+  /** In place order. */
+  players: z.array(RaceRecordPlayer),
+});
+
+/** A past race. */
+export type RaceRecord = z.infer<typeof RaceRecord>;