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

package/src/manifest/multiplayer.ts

@@ -0,0 +1,71 @@
+/**
+ * `game.multiplayer`: the opt-in that makes a game an online invite/join
+ * target (docs/multiplayer.md §7).
+ */
+import { z } from 'zod';
+import { MANIFEST_LIMITS } from '../limits';
+import { LobbySuffix, hasUniqueKeys, playerRange, trimmedText } from './fields';
+
+/**
+ * How players connect: `hub-rooms` (the hub relays room messages) or
+ * `own-server` (a process app runs its own game server; process apps only).
+ */
+export const Transport = z.enum(['hub-rooms', 'own-server']);
+
+/** A mode key: letters, digits, `_` or `-`, 1 to 32 characters. */
+export const ModeKey = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/, 'must be 1-32 letters, digits, _ or -');
+
+/** A game mode players can be invited into. */
+export const MultiplayerMode = z.strictObject({
+  /** Sent with invites and launches as `mode`. */
+  key: ModeKey,
+  /** What players see. Defaults to the key. */
+  title: trimmedText(MANIFEST_LIMITS.modeTitleMax).optional(),
+  /** `[min, max]` players for this mode, within 1..8. Defaults to the game's. */
+  players: playerRange(1).optional(),
+});
+
+/**
+ * A soften-list word this game's chat may keep (e.g. `shot` for a pool game):
+ * one lowercase word of 2 to 20 letters. Reject-list words never pass.
+ */
+export const ChatAllowWord = z.string().trim().toLowerCase().regex(/^[a-z]{2,20}$/, 'must be a single word of 2-20 letters');
+
+/** The `game.multiplayer` block. */
+export const GameMultiplayer = z.strictObject({
+  /** URL suffix invites and Join open, relative to `/<slug>/`. Default `''` (the game's root). */
+  lobby: LobbySuffix.default(''),
+  /** `[min, max]` players, within 1..8. Default `[2, 8]`. */
+  players: playerRange(1).default([2, 8]),
+  /**
+   * `hub-rooms` or `own-server`. Default: `own-server` for process apps,
+   * `hub-rooms` for static apps (which cannot use `own-server`).
+   */
+  transport: Transport.optional(),
+  /** Friends can invite each other into this game. Default `true`. */
+  invites: z.boolean().default(true),
+  /** Friends can join a game in progress. Default `true`. */
+  join: z.boolean().default(true),
+  /** Friends can watch. Default `false`. */
+  spectate: z.boolean().default(false),
+  /** Offer quick match. Default `false`. */
+  quickMatch: z.boolean().default(false),
+  /** Modes players can be invited into (at most 16, unique keys). */
+  modes: z.array(MultiplayerMode).max(MANIFEST_LIMITS.modesMax).refine(hasUniqueKeys, 'mode keys must be unique').default([]),
+  /**
+   * Extra quick-chat phrases for this game (at most 24, each at most 40
+   * characters). Checked by the content filter at boot; failing ones are dropped.
+   */
+  quickChat: z.array(trimmedText(MANIFEST_LIMITS.quickChatTextMax)).max(MANIFEST_LIMITS.quickChatMax).default([]),
+  /** Soften-list words this game's chat may keep (at most 20). */
+  chatAllow: z.array(ChatAllowWord).max(MANIFEST_LIMITS.chatAllowMax).default([]),
+});
+
+/** A normalised `game.multiplayer` block. */
+export type GameMultiplayer = z.output<typeof GameMultiplayer>;
+
+/** `game.multiplayer` for a static app: `own-server` needs a process app. */
+export const StaticGameMultiplayer = GameMultiplayer.refine((multiplayer) => multiplayer.transport !== 'own-server', {
+  message: 'own-server needs a process app; static apps use hub-rooms',
+  path: ['transport'],
+});

package/src/manifest/race.ts

@@ -0,0 +1,93 @@
+/**
+ * `game.race`: the opt-in that turns a single-player game into a race target
+ * (docs/multiplayer.md §14, docs/plans/race.md §5).
+ */
+import { z } from 'zod';
+import { RaceKey, RaceParamValue as RaceValue } from '../api/mp/races';
+import { MANIFEST_LIMITS } from '../limits';
+import { LobbySuffix, hasUniqueKeys, playerRange, trimmedText } from './fields';
+
+/** A race param value. */
+type RaceValue = z.infer<typeof RaceValue>;
+
+const RaceTitle = trimmedText(MANIFEST_LIMITS.raceTitleMax);
+
+/** One choice of a race param: a bare value, or a value with a title. */
+export const RaceOption = z.union([
+  RaceValue,
+  z.strictObject({
+    /** The value the game receives in `r.params[key]`. */
+    value: RaceValue,
+    /** What the creator sees. Defaults to the value. Checked like quick-chat text. */
+    title: RaceTitle.optional(),
+  }),
+]);
+
+/** The value of an option, bare or titled. */
+function optionValue(option: z.output<typeof RaceOption>): RaceValue {
+  return typeof option === 'object' ? option.value : option;
+}
+
+/** A choice the race creator makes. The server only accepts declared values. */
+export const RaceParam = z
+  .strictObject({
+    /** The key the game reads, `r.params[key]`. */
+    key: RaceKey,
+    /** What the creator sees. Defaults to the key. Checked like quick-chat text. */
+    title: RaceTitle.optional(),
+    /** The choices, 1 to 12. */
+    options: z.array(RaceOption).min(1).max(MANIFEST_LIMITS.raceOptionsMax),
+    /** The preselected value; one of the options' values. Defaults to the first. */
+    default: RaceValue.optional(),
+  })
+  .refine((p) => p.default === undefined || p.options.some((option) => optionValue(option) === p.default), {
+    message: 'default must be one of the option values',
+    path: ['default'],
+  });
+
+/** How the live race HUD and the race history show a stat. */
+export const RaceStatFormat = z.enum(['int', 'percent', 'time', 'bool', 'color']);
+
+/** A value of {@link RaceStatFormat}. */
+export type RaceStatFormat = z.infer<typeof RaceStatFormat>;
+
+/** A stat the live race HUD and the race history show. */
+export const RaceStat = z.strictObject({
+  /** The key the game sends in `hub.race.status({ [key]: value })`. */
+  key: RaceKey,
+  /** The column label. Defaults to the key. Checked like quick-chat text. */
+  title: RaceTitle.optional(),
+  /** `int` (default), `percent`, `time` (ms), `bool` or `color` (`#rrggbb`). */
+  format: RaceStatFormat.default('int'),
+});
+
+/** The `game.race` object form. */
+export const RaceBlock = z.strictObject({
+  /** URL suffix race invites and Join open, relative to `/<slug>/`. Default `?race=lobby`. */
+  lobby: LobbySuffix.default('?race=lobby'),
+  /** `[min, max]` racers, within 2..8. Default `[2, 2]`. */
+  players: playerRange(2).default([2, 2]),
+  /** What the creator picks (at most 6, unique keys). */
+  params: z.array(RaceParam).max(MANIFEST_LIMITS.raceParamsMax).refine(hasUniqueKeys, 'param keys must be unique').default([]),
+  /** What the live HUD and the history show (at most 8, unique keys; the HUD shows the first 3). */
+  stats: z.array(RaceStat).max(MANIFEST_LIMITS.raceStatsMax).refine(hasUniqueKeys, 'stat keys must be unique').default([]),
+  /**
+   * The earliest a finish may count after the go, in ms (0 to 600000). A
+   * sooner finish is held until then. Default: the hub's `raceMinFinishMs`.
+   */
+  minMs: z.number().int().min(0).max(MANIFEST_LIMITS.raceMinMsMax).optional(),
+});
+
+/** A normalised `game.race` block. */
+export type RaceBlock = z.output<typeof RaceBlock>;
+
+/**
+ * `game.race`: an object, `true` for all defaults (no params, no stats), or
+ * `false` for off. `true` parses to the object form, `false` to `undefined`.
+ */
+export const GameRace = z
+  .preprocess((v: boolean | z.input<typeof RaceBlock>) => (v === true ? {} : v === false ? undefined : v), RaceBlock.optional())
+  .optional();
+
+/** `game.race` as a game writes it. */
+export type GameRaceInput = z.input<typeof GameRace>;

package/src/middleware.ts

@@ -0,0 +1,47 @@
+/**
+ * Middleware **defs** for the public API (plan §6.1). A def is a contract
+ * only: a name, the context it provides and its dependencies. It holds no
+ * code, so it is safe in a published package; the server binds the real
+ * implementation. Each endpoint's guards are part of its declaration, which
+ * lets tests check rules such as "every social endpoint requires an active
+ * account" (plan §10.3).
+ */
+import { ctx, middleware } from '@ayepi/core';
+import { Slug } from './common';
+import type { SessionUser } from './entities';
+
+/**
+ * Resolves the `hub_session` cookie (the user, or `null`) and the anonymous
+ * `hub_cid` client id. Every endpoint has it.
+ */
+export const session = middleware('session', {
+  provides: ctx<{ user: SessionUser | null; clientId: string }>(),
+  doc: { security: { cookieAuth: { type: 'apiKey', in: 'cookie', name: 'hub_session' } } },
+});
+
+/** Signed in, as a guest or an account. Otherwise 401 `signed_out`. */
+export const requireUser = middleware('requireUser', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [session],
+});
+
+/**
+ * Signed in and not suspended. Otherwise 401 `signed_out` or 403
+ * `suspended`. Every social, multiplayer, race and trade endpoint has it.
+ */
+export const requireActive = middleware('requireActive', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [requireUser],
+});
+
+/** Active and a claimed account (not a guest). Otherwise 403 `claim_required`. */
+export const requireClaimed = middleware('requireClaimed', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [requireActive],
+});
+
+/**
+ * Owns the `:slug` path segment and checks it names a known game.
+ * Otherwise 404 "No such game".
+ */
+export const game = middleware.loader('slug', Slug, { requires: [session] });

package/src/realtime/define.ts

@@ -0,0 +1,52 @@
+/**
+ * Definers for socket ops and events (plan §5.2). One declaration per op or
+ * event feeds the server (validation), the runtime and test clients (types)
+ * and the generated op/event tables.
+ */
+import type { z } from 'zod';
+import type { ErrorCode } from '../errors';
+
+/** A client → server op on `/_ws`: its input, its ack and the codes it can fail with. */
+export interface OpDef<D extends z.ZodType = z.ZodType, A extends z.ZodType = z.ZodType> {
+  /** The op's input (`d` in `{t:'op', id, op, d}`). */
+  readonly d: D;
+  /** The success ack's payload (`d` in `{t:'ack', ok:true, d}`). */
+  readonly ack: A;
+  /** Error codes this op can fail with, beyond the envelope's own (see `ENVELOPE_ERRORS`). */
+  readonly errors: readonly ErrorCode[];
+  /**
+   * The refusal a malformed `d` gets (status 400), when the hub names it
+   * (`bad_stats`, `bad_patch`). Without it the refusal is `bad_request`
+   * with the first validation message.
+   */
+  readonly invalid?: { readonly code: ErrorCode; readonly error: string };
+  /** One line for the generated op table. */
+  readonly doc: string;
+}
+
+/** A server → client event on `/_ws`. */
+export interface EventDef<D extends z.ZodType = z.ZodType> {
+  /** The payload (`d` in `{t:'ev', ev, d}`). */
+  readonly d: D;
+  /** One line for the generated event table. */
+  readonly doc: string;
+}
+
+/** Declare an op (identity at runtime; keeps the literal types). */
+export function op<const D extends z.ZodType, const A extends z.ZodType>(def: OpDef<D, A>): OpDef<D, A> {
+  return def;
+}
+
+/** Declare an event (identity at runtime; keeps the literal types). */
+export function event<const D extends z.ZodType>(def: EventDef<D>): EventDef<D> {
+  return def;
+}
+
+/** The input type of an op. */
+export type OpInput<O extends OpDef> = z.input<O['d']>;
+
+/** The ack payload type of an op. */
+export type OpAck<O extends OpDef> = z.output<O['ack']>;
+
+/** The payload type of an event. */
+export type EventData<E extends EventDef> = z.output<E['d']>;

package/src/realtime/envelope.ts

@@ -0,0 +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'];

package/src/realtime/events/multiplayer.ts

@@ -0,0 +1,8 @@
+/** 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>;

package/src/realtime/events/parties.ts

@@ -0,0 +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>;

package/src/realtime/events/races.ts

@@ -0,0 +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>;

package/src/realtime/events/rooms.ts

@@ -0,0 +1,48 @@
+/** 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>;

package/src/realtime/events/social.ts

@@ -0,0 +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>;

package/src/realtime/index.ts

@@ -0,0 +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;

package/src/realtime/ops/empty.ts

@@ -0,0 +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({});

package/src/realtime/ops/hello.ts

@@ -0,0 +1,40 @@
+/**
+ * `hello`: the first op on every socket (multiplayer-impl.md §4.5). It marks
+ * the tab live for events and presence and answers with the snapshot a
+ * client needs to draw the Friends drawer, invites and any room it still holds.
+ */
+import { z } from 'zod';
+import { UnreadSummary } from '../../api/messages';
+import { MultiplayerSnapshot } from '../../api/mp/snapshot';
+import { SocialConfig } from '../../api/social/config';
+import { FriendEntry, FriendRequests, SocialMe } from '../../api/social/people';
+import { Counts } from '../../api/social/presence';
+import { op } from '../define';
+
+/** `hello` input. Anything unrecognised is ignored rather than rejected. */
+export const HelloInput = z.object({
+  /** The game this tab is in, or `null` on the home page. Unknown slugs count as `null`. */
+  slug: z.string().nullable().optional(),
+  /** A per-tab id (`[A-Za-z0-9_-]{1,64}`); other values are ignored. */
+  tab: z.string().optional(),
+  /** The document is visible (default `true`). */
+  visible: z.boolean().optional(),
+  /** The client package version that opened the socket (`2.3.0`); v1 vendored copies send none. */
+  client: z.string().optional(),
+});
+
+/** The `hello` snapshot. Guests get no friends and empty request lists. */
+export const HelloSnapshot = z.object({
+  me: SocialMe,
+  config: SocialConfig,
+  counts: Counts,
+  friends: z.array(FriendEntry),
+  requests: FriendRequests,
+  unread: UnreadSummary,
+  ...MultiplayerSnapshot.shape,
+});
+
+/** The `hello` op (allowed before `hello`, obviously). */
+export const helloOps = {
+  hello: op({ d: HelloInput, ack: HelloSnapshot, errors: [], doc: 'Start the session on this socket; answers with the snapshot.' }),
+};

package/src/realtime/ops/multiplayer.ts

@@ -0,0 +1,8 @@
+/** Socket ops for invites, parties, hub rooms and races. */
+import type { OpDef } from '../define';
+import { partyOps } from './parties';
+import { raceOps } from './races';
+import { roomOps } from './rooms';
+
+/** The multiplayer ops, by op name. */
+export const multiplayerOps = { ...partyOps, ...roomOps, ...raceOps } satisfies Record<string, OpDef>;

package/src/realtime/ops/parties.ts

@@ -0,0 +1,13 @@
+/** The party socket op: party chat. Invites and party membership are REST (`/mp/*`). */
+import { CHAT_ERRORS, ChatLine, ChatSend } from '../../api/mp/chat';
+import { op, type OpDef } from '../define';
+
+/** The party ops, by op name. */
+export const partyOps = {
+  'party.chat': op({
+    d: ChatSend,
+    ack: ChatLine,
+    errors: ['party_gone', ...CHAT_ERRORS],
+    doc: "Chat to your party: free text only when every member is a mutual friend, quick-chat otherwise.",
+  }),
+} satisfies Record<string, OpDef>;