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

package/src/realtime/envelope.ts

@@ -1,67 +1,67 @@
-/**
- * The legacy `/_ws` envelope (multiplayer-impl.md §4.2), unchanged since v1
- * and kept indefinitely (plan D6):
- *
- * ```
- * client → server  {t:'op',  id, op, d}
- * server → client  {t:'ack', id, ok:true,  d}
- *                  {t:'ack', id, ok:false, err: ErrorBody}
- *                  {t:'ev',  ev, d}
- * ```
- */
-import { z } from 'zod';
-import { Json } from '../common';
-import { ErrorBody, type ErrorCode } from '../errors';
-
-/** A client's op frame. `id` is the client's own counter, echoed in the ack. */
-export const OpFrame = z.object({
-  t: z.literal('op'),
-  id: z.number(),
-  op: z.string(),
-  d: Json.optional(),
-});
-
-/** An op frame. */
-export type OpFrame = z.infer<typeof OpFrame>;
-
-/** A successful ack. */
-export const OkAckFrame = z.object({ t: z.literal('ack'), id: z.number(), ok: z.literal(true), d: Json });
-
-/** A failed ack. */
-export const ErrAckFrame = z.object({ t: z.literal('ack'), id: z.number(), ok: z.literal(false), err: ErrorBody });
-
-/** An ack frame: the server's answer to one op. */
-export const AckFrame = z.discriminatedUnion('ok', [OkAckFrame, ErrAckFrame]);
-
-/** An ack frame. */
-export type AckFrame = z.infer<typeof AckFrame>;
-
-/** A server-pushed event frame. */
-export const EvFrame = z.object({ t: z.literal('ev'), ev: z.string(), d: Json });
-
-/** An event frame. */
-export type EvFrame = z.infer<typeof EvFrame>;
-
-/** Any frame the server sends. */
-export const ServerFrame = z.union([AckFrame, EvFrame]);
-
-/** Close codes the client understands. */
-export const CloseCode = {
-  /** Service restart: reconnect quietly. */
-  restart: 1012,
-  /** The account is suspended. */
-  suspended: 4003,
-  /** Too many sockets for this user or IP. */
-  tooMany: 4029,
-  /** A frame that wasn't a valid op. */
-  badMessage: 4400,
-} as const;
-
-/**
- * Codes any op can fail with, raised by the envelope rather than the op:
- * the per-socket rate limit, an unknown op name, and ops sent before `hello`.
- */
-export const ENVELOPE_ERRORS: readonly ErrorCode[] = ['rate_limited', 'unknown_op', 'hello_required'];
-
-/** Ops the server accepts before `hello`. */
-export const PRE_HELLO_OPS: readonly string[] = ['hello', 'ping'];
+/**
+ * The legacy `/_ws` envelope (multiplayer-impl.md §4.2), unchanged since v1
+ * and kept indefinitely (plan D6):
+ *
+ * ```
+ * client → server  {t:'op',  id, op, d}
+ * server → client  {t:'ack', id, ok:true,  d}
+ *                  {t:'ack', id, ok:false, err: ErrorBody}
+ *                  {t:'ev',  ev, d}
+ * ```
+ */
+import { z } from 'zod';
+import { Json } from '../common';
+import { ErrorBody, type ErrorCode } from '../errors';
+
+/** A client's op frame. `id` is the client's own counter, echoed in the ack. */
+export const OpFrame = z.object({
+  t: z.literal('op'),
+  id: z.number(),
+  op: z.string(),
+  d: Json.optional(),
+});
+
+/** An op frame. */
+export type OpFrame = z.infer<typeof OpFrame>;
+
+/** A successful ack. */
+export const OkAckFrame = z.object({ t: z.literal('ack'), id: z.number(), ok: z.literal(true), d: Json });
+
+/** A failed ack. */
+export const ErrAckFrame = z.object({ t: z.literal('ack'), id: z.number(), ok: z.literal(false), err: ErrorBody });
+
+/** An ack frame: the server's answer to one op. */
+export const AckFrame = z.discriminatedUnion('ok', [OkAckFrame, ErrAckFrame]);
+
+/** An ack frame. */
+export type AckFrame = z.infer<typeof AckFrame>;
+
+/** A server-pushed event frame. */
+export const EvFrame = z.object({ t: z.literal('ev'), ev: z.string(), d: Json });
+
+/** An event frame. */
+export type EvFrame = z.infer<typeof EvFrame>;
+
+/** Any frame the server sends. */
+export const ServerFrame = z.union([AckFrame, EvFrame]);
+
+/** Close codes the client understands. */
+export const CloseCode = {
+  /** Service restart: reconnect quietly. */
+  restart: 1012,
+  /** The account is suspended. */
+  suspended: 4003,
+  /** Too many sockets for this user or IP. */
+  tooMany: 4029,
+  /** A frame that wasn't a valid op. */
+  badMessage: 4400,
+} as const;
+
+/**
+ * Codes any op can fail with, raised by the envelope rather than the op:
+ * the per-socket rate limit, an unknown op name, and ops sent before `hello`.
+ */
+export const ENVELOPE_ERRORS: readonly ErrorCode[] = ['rate_limited', 'unknown_op', 'hello_required'];
+
+/** Ops the server accepts before `hello`. */
+export const PRE_HELLO_OPS: readonly string[] = ['hello', 'ping'];

package/src/realtime/events/multiplayer.ts

@@ -1,8 +1,9 @@
-/** Socket events for invites, parties, hub rooms and races. */
-import type { EventDef } from '../define';
-import { partyEvents } from './parties';
-import { raceEvents } from './races';
-import { roomEvents } from './rooms';
-
-/** The multiplayer events, by event name. */
-export const multiplayerEvents = { ...partyEvents, ...roomEvents, ...raceEvents } satisfies Record<string, EventDef>;
+/** Socket events for invites, parties, hub rooms, races and tournaments. */
+import type { EventDef } from '../define';
+import { partyEvents } from './parties';
+import { raceEvents } from './races';
+import { roomEvents } from './rooms';
+import { tournamentEvents } from './tournaments';
+
+/** The multiplayer events, by event name. */
+export const multiplayerEvents = { ...partyEvents, ...roomEvents, ...raceEvents, ...tournamentEvents } satisfies Record<string, EventDef>;

package/src/realtime/events/parties.ts

@@ -1,31 +1,31 @@
-/** Invite and party events (multiplayer-impl.md §5.6). */
-import { z } from 'zod';
-import { PlayerLite } from '../../entities';
-import { ChatLineEvent } from '../../api/mp/chat';
-import { Invite, InviteStatus, OpaqueId, Party } from '../../api/mp/parties';
-import { event, type EventDef } from '../define';
-
-/** The invite and party events, by event name. */
-export const partyEvents = {
-  invite: event({
-    d: Invite,
-    doc: 'A friend invited you to a game.',
-  }),
-  'invite.update': event({
-    d: z.object({
-      id: OpaqueId,
-      status: InviteStatus,
-      /** Who accepted or declined (absent for cancelled and expired). */
-      by: PlayerLite.optional(),
-    }),
-    doc: 'An invite ended; sent to the inviter and the invitee (so its toast closes).',
-  }),
-  party: event({
-    d: Party.nullable(),
-    doc: "Your party's current state, or null when you left it or it dissolved.",
-  }),
-  'party.chat': event({
-    d: ChatLineEvent,
-    doc: 'A party chat line.',
-  }),
-} satisfies Record<string, EventDef>;
+/** Invite and party events (multiplayer-impl.md §5.6). */
+import { z } from 'zod';
+import { PlayerLite } from '../../entities';
+import { ChatLineEvent } from '../../api/mp/chat';
+import { Invite, InviteStatus, OpaqueId, Party } from '../../api/mp/parties';
+import { event, type EventDef } from '../define';
+
+/** The invite and party events, by event name. */
+export const partyEvents = {
+  invite: event({
+    d: Invite,
+    doc: 'A friend invited you to a game.',
+  }),
+  'invite.update': event({
+    d: z.object({
+      id: OpaqueId,
+      status: InviteStatus,
+      /** Who accepted or declined (absent for cancelled and expired). */
+      by: PlayerLite.optional(),
+    }),
+    doc: 'An invite ended; sent to the inviter and the invitee (so its toast closes).',
+  }),
+  party: event({
+    d: Party.nullable(),
+    doc: "Your party's current state, or null when you left it or it dissolved.",
+  }),
+  'party.chat': event({
+    d: ChatLineEvent,
+    doc: 'A party chat line.',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/events/races.ts

@@ -1,27 +1,27 @@
-/** Race events (docs/plans/race.md §4). */
-import { z } from 'zod';
-import { UserId } from '../../common';
-import { RaceProgress, RaceResult, RaceStart, RaceStats } from '../../api/mp/races';
-import { event, type EventDef } from '../define';
-
-/** The race events, by event name. */
-export const raceEvents = {
-  'race.start': event({
-    d: RaceStart,
-    doc: 'The countdown began: the seed is revealed now.',
-  }),
-  'race.status': event({
-    d: z.object({
-      userId: UserId,
-      stats: RaceStats,
-      progress: RaceProgress.optional(),
-      /** ms since the go (server clock). */
-      at: z.number().int().nonnegative(),
-    }),
-    doc: "Another racer's live status, for the race HUD.",
-  }),
-  'race.result': event({
-    d: z.object({ result: RaceResult }),
-    doc: 'The race was decided.',
-  }),
-} satisfies Record<string, EventDef>;
+/** Race events (docs/plans/race.md §4). */
+import { z } from 'zod';
+import { UserId } from '../../common';
+import { RaceProgress, RaceResult, RaceStart, RaceStats } from '../../api/mp/races';
+import { event, type EventDef } from '../define';
+
+/** The race events, by event name. */
+export const raceEvents = {
+  'race.start': event({
+    d: RaceStart,
+    doc: 'The countdown began: the seed is revealed now.',
+  }),
+  'race.status': event({
+    d: z.object({
+      userId: UserId,
+      stats: RaceStats,
+      progress: RaceProgress.optional(),
+      /** ms since the go (server clock). */
+      at: z.number().int().nonnegative(),
+    }),
+    doc: "Another racer's live status, for the race HUD.",
+  }),
+  'race.result': event({
+    d: z.object({ result: RaceResult }),
+    doc: 'The race was decided.',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/events/rooms.ts

@@ -1,48 +1,52 @@
-/** Hub relay room events (multiplayer-impl.md §6). Race rooms send these too. */
-import { z } from 'zod';
-import { Json, UserId } from '../../common';
-import { ChatLineEvent } from '../../api/mp/chat';
-import { OpaqueId } from '../../api/mp/parties';
-import { RoomClosedReason, RoomInfo, RoomMessage, RoomState, SeatGoneReason } from '../../api/mp/rooms';
-import { event, type EventDef } from '../define';
-
-/** The room events, by event name. */
-export const roomEvents = {
-  room: event({
-    d: z.object({
-      room: RoomInfo,
-      /** What the host passed to `room.end`; present once, on that update. */
-      results: Json.optional(),
-    }),
-    doc: 'The room changed: roster, ready flags, phase, host, race state.',
-  }),
-  'room.msg': event({
-    d: RoomMessage,
-    doc: 'A relayed game message.',
-  }),
-  'room.state': event({
-    d: z.object({
-      /** Shallow-merged into the state unless `replace`; a `null` value deletes its key. */
-      patch: RoomState,
-      replace: z.boolean(),
-      seq: z.number().int().positive(),
-    }),
-    doc: 'The shared state changed.',
-  }),
-  'room.chat': event({
-    d: ChatLineEvent,
-    doc: 'A room chat line.',
-  }),
-  'room.kicked': event({
-    d: z.object({ roomId: OpaqueId }),
-    doc: 'The host removed you from the room.',
-  }),
-  'room.closed': event({
-    d: z.object({ reason: RoomClosedReason }),
-    doc: 'The room is gone for this tab (emptied, ended, host left, moved, another tab took the seat, removed).',
-  }),
-  'room.abandoned': event({
-    d: z.object({ userId: UserId, reason: SeatGoneReason }),
-    doc: 'A player left mid-game (or their reconnect grace ran out); the game decides what that means.',
-  }),
-} satisfies Record<string, EventDef>;
+/** Hub relay room events (multiplayer-impl.md §6). Race rooms send these too. */
+import { z } from 'zod';
+import { Json, UserId } from '../../common';
+import { ChatLineEvent } from '../../api/mp/chat';
+import { OpaqueId } from '../../api/mp/parties';
+import { RoomClosedReason, RoomInfo, RoomMessage, RoomState, SeatChange, SeatGoneReason } from '../../api/mp/rooms';
+import { event, type EventDef } from '../define';
+
+/** The room events, by event name. */
+export const roomEvents = {
+  room: event({
+    d: z.object({
+      room: RoomInfo,
+      /** What the host passed to `room.end`; present once, on that update. */
+      results: Json.optional(),
+    }),
+    doc: 'The room changed: roster, ready flags, phase, host, race state.',
+  }),
+  'room.msg': event({
+    d: RoomMessage,
+    doc: 'A relayed game message.',
+  }),
+  'room.state': event({
+    d: z.object({
+      /** Shallow-merged into the state unless `replace`; a `null` value deletes its key. */
+      patch: RoomState,
+      replace: z.boolean(),
+      seq: z.number().int().positive(),
+    }),
+    doc: 'The shared state changed.',
+  }),
+  'room.chat': event({
+    d: ChatLineEvent,
+    doc: 'A room chat line.',
+  }),
+  'room.kicked': event({
+    d: z.object({ roomId: OpaqueId }),
+    doc: 'The host removed you from the room.',
+  }),
+  'room.closed': event({
+    d: z.object({ reason: RoomClosedReason }),
+    doc: 'The room is gone for this tab (emptied, ended, moved, another tab took the seat, removed). `host_left` is no longer sent: the host role passes on.',
+  }),
+  'room.abandoned': event({
+    d: z.object({ userId: UserId, reason: SeatGoneReason }),
+    doc: 'A player left mid-game (or their reconnect grace ran out); the game decides what that means.',
+  }),
+  'room.seat': event({
+    d: SeatChange,
+    doc: 'A seat went away (held for the grace period), came back (reclaimed) or is gone. The game hands an away seat to its computer player and gives it back on `back`.',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/events/social.ts

@@ -1,81 +1,81 @@
-/**
- * Socket events for presence, counts, friends, typing, config, DMs, notices
- * and suspension (multiplayer-impl.md §4.6). Every event goes to all of the
- * recipient's tabs.
- */
-import { z } from 'zod';
-import { Millis, UserId } from '../../common';
-import { PlayerLite } from '../../entities';
-import { Message, MessageId } from '../../api/messages';
-import { SocialConfig } from '../../api/social/config';
-import { FriendChange } from '../../api/social/people';
-import { Counts, Presence } from '../../api/social/presence';
-import { event, type EventDef } from '../define';
-
-/** What kind of thing a notice is about. `renamed`: an admin changed your username. */
-export const NoticeKind = z.enum(['dm', 'friend_request', 'friend_online', 'lobby_open', 'invite', 'suggestion', 'renamed']);
-
-/** A notice kind. */
-export type NoticeKind = z.infer<typeof NoticeKind>;
-
-/** A toast (`ev:notice`), sent instead of a push when the player has a visible tab. */
-export const Notice = z.object({
-  kind: NoticeKind,
-  title: z.string(),
-  body: z.string().optional(),
-  /** A button: its label and the page it opens. */
-  action: z.object({ label: z.string(), url: z.string() }).optional(),
-});
-
-/** A toast. */
-export type Notice = z.infer<typeof Notice>;
-
-/** The social events, by event name. */
-export const socialEvents = {
-  presence: event({
-    d: z.object({
-      userId: UserId,
-      /** `null`: offline, or no longer visible to you. */
-      p: Presence.nullable(),
-    }),
-    doc: "A friend's presence changed.",
-  }),
-  counts: event({ d: Counts, doc: 'The online counts changed (broadcast to every tab, at most every 15 s).' }),
-  friends: event({
-    d: z.object({ change: FriendChange, user: PlayerLite }),
-    doc: 'Your friends list changed (refetch `GET /social/friends`).',
-  }),
-  typing: event({ d: z.object({ from: UserId }), doc: 'A friend is typing to you.' }),
-  config: event({ d: SocialConfig, doc: 'The site-wide social configuration changed (broadcast).' }),
-  dm: event({
-    d: z.object({
-      message: Message,
-      /** The other side of the conversation, from your point of view. */
-      conversationWith: UserId,
-    }),
-    doc: 'A DM was delivered: to the recipient, and to the sender\'s other tabs.',
-  }),
-  'dm.read': event({
-    d: z.object({
-      /** Who read. */
-      by: UserId,
-      /** Their messages up to and including this id are read. */
-      upTo: MessageId,
-    }),
-    doc: 'Messages were read (to the sender, and to the reader\'s own tabs to sync badges).',
-  }),
-  'dm.hidden': event({
-    d: z.object({ ids: z.array(MessageId) }),
-    doc: 'A moderator hid these messages: drop them from both sides of the conversation.',
-  }),
-  notice: event({ d: Notice, doc: 'A toast to show.' }),
-  suspended: event({
-    d: z.object({
-      /** When the suspension ends (epoch ms). */
-      until: Millis,
-      /** The moderator's reason, when given. */
-      reason: z.string().optional(),
-    }),
-    doc: 'The account is suspended; the socket then closes with 4003.',
-  }),
-} satisfies Record<string, EventDef>;
+/**
+ * Socket events for presence, counts, friends, typing, config, DMs, notices
+ * and suspension (multiplayer-impl.md §4.6). Every event goes to all of the
+ * recipient's tabs.
+ */
+import { z } from 'zod';
+import { Millis, UserId } from '../../common';
+import { PlayerLite } from '../../entities';
+import { Message, MessageId } from '../../api/messages';
+import { SocialConfig } from '../../api/social/config';
+import { FriendChange } from '../../api/social/people';
+import { Counts, Presence } from '../../api/social/presence';
+import { event, type EventDef } from '../define';
+
+/** What kind of thing a notice is about. `renamed`: an admin changed your username; `tournament`: a match is ready, a start is near, a forfeit warning. */
+export const NoticeKind = z.enum(['dm', 'friend_request', 'friend_online', 'lobby_open', 'invite', 'suggestion', 'renamed', 'tournament']);
+
+/** A notice kind. */
+export type NoticeKind = z.infer<typeof NoticeKind>;
+
+/** A toast (`ev:notice`), sent instead of a push when the player has a visible tab. */
+export const Notice = z.object({
+  kind: NoticeKind,
+  title: z.string(),
+  body: z.string().optional(),
+  /** A button: its label and the page it opens. */
+  action: z.object({ label: z.string(), url: z.string() }).optional(),
+});
+
+/** A toast. */
+export type Notice = z.infer<typeof Notice>;
+
+/** The social events, by event name. */
+export const socialEvents = {
+  presence: event({
+    d: z.object({
+      userId: UserId,
+      /** `null`: offline, or no longer visible to you. */
+      p: Presence.nullable(),
+    }),
+    doc: "A friend's presence changed.",
+  }),
+  counts: event({ d: Counts, doc: 'The online counts changed (broadcast to every tab, at most every 15 s).' }),
+  friends: event({
+    d: z.object({ change: FriendChange, user: PlayerLite }),
+    doc: 'Your friends list changed (refetch `GET /social/friends`).',
+  }),
+  typing: event({ d: z.object({ from: UserId }), doc: 'A friend is typing to you.' }),
+  config: event({ d: SocialConfig, doc: 'The site-wide social configuration changed (broadcast).' }),
+  dm: event({
+    d: z.object({
+      message: Message,
+      /** The other side of the conversation, from your point of view. */
+      conversationWith: UserId,
+    }),
+    doc: 'A DM was delivered: to the recipient, and to the sender\'s other tabs.',
+  }),
+  'dm.read': event({
+    d: z.object({
+      /** Who read. */
+      by: UserId,
+      /** Their messages up to and including this id are read. */
+      upTo: MessageId,
+    }),
+    doc: 'Messages were read (to the sender, and to the reader\'s own tabs to sync badges).',
+  }),
+  'dm.hidden': event({
+    d: z.object({ ids: z.array(MessageId) }),
+    doc: 'A moderator hid these messages: drop them from both sides of the conversation.',
+  }),
+  notice: event({ d: Notice, doc: 'A toast to show.' }),
+  suspended: event({
+    d: z.object({
+      /** When the suspension ends (epoch ms). */
+      until: Millis,
+      /** The moderator's reason, when given. */
+      reason: z.string().optional(),
+    }),
+    doc: 'The account is suspended; the socket then closes with 4003.',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/events/tournaments.ts

@@ -0,0 +1,12 @@
+/** Tournament events (batch-2026-10 R15). */
+import { z } from 'zod';
+import { TournamentSummary } from '../../api/tournaments/shapes';
+import { event, type EventDef } from '../define';
+
+/** The tournament events, by event name. */
+export const tournamentEvents = {
+  tournament: event({
+    d: z.object({ tournament: TournamentSummary }),
+    doc: 'A tournament you are in, follow, created or were invited to changed (sign-ups, the start, a match ready or decided, the end).',
+  }),
+} satisfies Record<string, EventDef>;

package/src/realtime/index.ts

@@ -1,24 +1,24 @@
-/**
- * The `/_ws` socket contract: the legacy envelope plus every op and event,
- * by name.
- */
-import { multiplayerEvents } from './events/multiplayer';
-import { socialEvents } from './events/social';
-import { helloOps } from './ops/hello';
-import { multiplayerOps } from './ops/multiplayer';
-import { socialOps } from './ops/social';
-
-export * from './define';
-export * from './envelope';
-
-/** Every socket op, by op name (an intersection type keeps the .d.ts small). */
-export const ops: typeof helloOps & typeof socialOps & typeof multiplayerOps = { ...helloOps, ...socialOps, ...multiplayerOps };
-
-/** Every socket event, by event name (an intersection type keeps the .d.ts small). */
-export const events: typeof socialEvents & typeof multiplayerEvents = { ...socialEvents, ...multiplayerEvents };
-
-/** A socket op name. */
-export type OpName = keyof typeof ops;
-
-/** A socket event name. */
-export type EventName = keyof typeof events;
+/**
+ * The `/_ws` socket contract: the legacy envelope plus every op and event,
+ * by name.
+ */
+import { multiplayerEvents } from './events/multiplayer';
+import { socialEvents } from './events/social';
+import { helloOps } from './ops/hello';
+import { multiplayerOps } from './ops/multiplayer';
+import { socialOps } from './ops/social';
+
+export * from './define';
+export * from './envelope';
+
+/** Every socket op, by op name (an intersection type keeps the .d.ts small). */
+export const ops: typeof helloOps & typeof socialOps & typeof multiplayerOps = { ...helloOps, ...socialOps, ...multiplayerOps };
+
+/** Every socket event, by event name (an intersection type keeps the .d.ts small). */
+export const events: typeof socialEvents & typeof multiplayerEvents = { ...socialEvents, ...multiplayerEvents };
+
+/** A socket op name. */
+export type OpName = keyof typeof ops;
+
+/** A socket event name. */
+export type EventName = keyof typeof events;

package/src/realtime/ops/empty.ts

@@ -1,8 +1,8 @@
-/** The empty input and ack many socket ops share. */
-import { z } from 'zod';
-
-/** An op that takes no input (`d` absent or `{}`). */
-export const NoInput = z.object({});
-
-/** An ack with no payload (`{}`). */
-export const EmptyAck = z.object({});
+/** The empty input and ack many socket ops share. */
+import { z } from 'zod';
+
+/** An op that takes no input (`d` absent or `{}`). */
+export const NoInput = z.object({});
+
+/** An ack with no payload (`{}`). */
+export const EmptyAck = z.object({});