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

package/src/api/leaderboards.ts

@@ -1,151 +1,151 @@
-/**
- * Leaderboards: score submission, boards and standings. A board belongs to a
- * game and is keyed by an app-chosen {@link Key}; it keeps each player's best
- * score only (highest for `desc` boards, lowest for `asc`).
- */
-import { use } from '@ayepi/core';
-import { z } from 'zod';
-import { Json, Key, Slug, UserId } from '../common';
-import { ErrorBody } from '../errors';
-import { game, requireUser, session } from '../middleware';
-import { RowCount, Truthy } from '../coerce';
-
-/** A board key in a path, with the old hub's message when it is malformed. */
-const BoardKeyParams = z.object({
-  key: z.string().refine((key) => Key.safeParse(key).success, { error: 'board key must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars).' }),
-});
-
-/**
- * A row count the hub reads like `Number(x) || default`: anything that is not
- * an integer falls back to the default instead of failing.
- */
-const LenientRowCount = RowCount.optional().catch(undefined);
-
-/** A board's sort direction: `desc` ranks high scores first, `asc` low scores (times) first. */
-export const SortDir = z.enum(['asc', 'desc']);
-
-/** A board's sort direction. */
-export type SortDir = z.infer<typeof SortDir>;
-
-/** A 1-based rank on a board. */
-export const Rank = z.number().int().positive();
-
-/** A leaderboard's identity, without entries. */
-export const Board = z.object({
-  key: Key,
-  /** Set by the first submitter or the game's `package.json`; defaults to the key. */
-  title: z.string(),
-  sortDir: SortDir,
-});
-
-/** A leaderboard's identity. */
-export type Board = z.infer<typeof Board>;
-
-/**
- * One ranked row of a board. Suspended players and (unless the board opts
- * in) zero scores are left out.
- */
-export const LeaderboardEntry = z.object({
-  rank: Rank,
-  userId: UserId,
-  username: z.string(),
-  score: z.number(),
-  /** The JSON the game stored with the score, or `null`. */
-  meta: Json,
-});
-
-/** A ranked board row. */
-export type LeaderboardEntry = z.infer<typeof LeaderboardEntry>;
-
-/** Every board of one game, each with its top entries (`GET /leaderboards`, the snapshot). */
-export const GameLeaderboards = z.object({
-  slug: Slug,
-  /** The game's title (the slug when the game is no longer listed). */
-  title: z.string(),
-  boards: z.array(Board.extend({ top: z.array(LeaderboardEntry) })),
-});
-
-/** One game's boards with their top entries. */
-export type GameLeaderboards = z.infer<typeof GameLeaderboards>;
-
-/**
- * The player's own standings in one game (`GET /me/records`, the snapshot):
- * their score and rank on each board they have an entry on.
- */
-export const GameRecords = z.object({
-  slug: Slug,
-  /** The game's title (the slug when the game is no longer listed). */
-  title: z.string(),
-  records: z.array(Board.extend({ score: z.number(), rank: Rank })),
-});
-
-/** The player's standings in one game. */
-export type GameRecords = z.infer<typeof GameRecords>;
-
-/**
- * `?top=` for the cross-game views (`GET /leaderboards`, `GET /me/snapshot`):
- * entries per board, 1 to 50 (clamped), default 5.
- */
-export const TopQuery = z.object({ top: LenientRowCount });
-
-/** The leaderboards endpoints. */
-export const leaderboardsEndpoints = {
-  ...session.group({
-    /** Every board of every game, grouped by game, each with its top entries. */
-    listTopOfEveryLeaderboard: {
-      method: 'GET', path: '/leaderboards', query: TopQuery,
-      response: z.object({ games: z.array(GameLeaderboards) }),
-      doc: { summary: 'Every board across every game, with top entries', tags: ['leaderboards'] },
-    },
-  }),
-  ...use(session, game).path('/games/:slug').group({
-    listGameLeaderboards: {
-      method: 'GET', path: '/leaderboards',
-      response: z.object({ boards: z.array(Board) }),
-      errors: { 404: ErrorBody },
-      doc: { summary: "The game's boards (no entries)", tags: ['leaderboards'] },
-    },
-    getLeaderboard: {
-      method: 'GET', path: '/leaderboards/:key',
-      params: BoardKeyParams,
-      /** `limit`: rows to return, 1 to 500 (clamped), default 50. */
-      query: z.object({ limit: LenientRowCount }),
-      response: z.object({ board: Board, entries: z.array(LeaderboardEntry) }),
-      errors: { 400: ErrorBody, 404: ErrorBody },
-      doc: { summary: "One board's ranked entries (404 if the board doesn't exist)", tags: ['leaderboards'] },
-    },
-  }),
-  ...use(requireUser, game).path('/games/:slug').group({
-    /**
-     * Submit a score. The first submission creates the board (with `title`,
-     * `sort` and `showZeros`; later values are ignored). Only an improvement
-     * replaces the player's entry. Boards a game declares with
-     * `source: "server"` refuse client scores (403 `server_board`).
-     */
-    submitScore: {
-      method: 'POST', path: '/leaderboards/:key/scores',
-      params: BoardKeyParams,
-      body: z.object({
-        /** A finite number (numeric strings pass, as for the old hub's `Number(x)`). */
-        score: z.coerce.number<number>({ error: 'score must be a finite number.' }),
-        /** Board title, used only when this call creates the board (non-text is ignored). */
-        title: z.string().optional().catch(undefined),
-        /** Sort direction, used only on creation. Anything but `asc` means `desc`. */
-        sort: SortDir.optional().catch(undefined),
-        /** Keep zero scores visible, used only on creation. */
-        showZeros: Truthy.optional(),
-        /** Any JSON stored with the entry (a character, a run seed). */
-        meta: Json.optional(),
-      }),
-      response: z.object({
-        board: Board,
-        /** The player's stored best after this submission. */
-        best: z.number().nullable(),
-        /** The player's rank on the board (`null` if they have no entry). */
-        rank: Rank.nullable(),
-      }),
-      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Submit a score (best-only; creates the board on first use)', tags: ['leaderboards'] },
-    },
-  }),
-};
+/**
+ * Leaderboards: score submission, boards and standings. A board belongs to a
+ * game and is keyed by an app-chosen {@link Key}; it keeps each player's best
+ * score only (highest for `desc` boards, lowest for `asc`).
+ */
+import { use } from '@ayepi/core';
+import { z } from 'zod';
+import { Json, Key, Slug, UserId } from '../common';
+import { ErrorBody } from '../errors';
+import { game, requireUser, session } from '../middleware';
+import { RowCount, Truthy } from '../coerce';
+
+/** A board key in a path, with the old hub's message when it is malformed. */
+const BoardKeyParams = z.object({
+  key: z.string().refine((key) => Key.safeParse(key).success, { error: 'board key must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars).' }),
+});
+
+/**
+ * A row count the hub reads like `Number(x) || default`: anything that is not
+ * an integer falls back to the default instead of failing.
+ */
+const LenientRowCount = RowCount.optional().catch(undefined);
+
+/** A board's sort direction: `desc` ranks high scores first, `asc` low scores (times) first. */
+export const SortDir = z.enum(['asc', 'desc']);
+
+/** A board's sort direction. */
+export type SortDir = z.infer<typeof SortDir>;
+
+/** A 1-based rank on a board. */
+export const Rank = z.number().int().positive();
+
+/** A leaderboard's identity, without entries. */
+export const Board = z.object({
+  key: Key,
+  /** Set by the first submitter or the game's `package.json`; defaults to the key. */
+  title: z.string(),
+  sortDir: SortDir,
+});
+
+/** A leaderboard's identity. */
+export type Board = z.infer<typeof Board>;
+
+/**
+ * One ranked row of a board. Suspended players and (unless the board opts
+ * in) zero scores are left out.
+ */
+export const LeaderboardEntry = z.object({
+  rank: Rank,
+  userId: UserId,
+  username: z.string(),
+  score: z.number(),
+  /** The JSON the game stored with the score, or `null`. */
+  meta: Json,
+});
+
+/** A ranked board row. */
+export type LeaderboardEntry = z.infer<typeof LeaderboardEntry>;
+
+/** Every board of one game, each with its top entries (`GET /leaderboards`, the snapshot). */
+export const GameLeaderboards = z.object({
+  slug: Slug,
+  /** The game's title (the slug when the game is no longer listed). */
+  title: z.string(),
+  boards: z.array(Board.extend({ top: z.array(LeaderboardEntry) })),
+});
+
+/** One game's boards with their top entries. */
+export type GameLeaderboards = z.infer<typeof GameLeaderboards>;
+
+/**
+ * The player's own standings in one game (`GET /me/records`, the snapshot):
+ * their score and rank on each board they have an entry on.
+ */
+export const GameRecords = z.object({
+  slug: Slug,
+  /** The game's title (the slug when the game is no longer listed). */
+  title: z.string(),
+  records: z.array(Board.extend({ score: z.number(), rank: Rank })),
+});
+
+/** The player's standings in one game. */
+export type GameRecords = z.infer<typeof GameRecords>;
+
+/**
+ * `?top=` for the cross-game views (`GET /leaderboards`, `GET /me/snapshot`):
+ * entries per board, 1 to 50 (clamped), default 5.
+ */
+export const TopQuery = z.object({ top: LenientRowCount });
+
+/** The leaderboards endpoints. */
+export const leaderboardsEndpoints = {
+  ...session.group({
+    /** Every board of every game, grouped by game, each with its top entries. */
+    listTopOfEveryLeaderboard: {
+      method: 'GET', path: '/leaderboards', query: TopQuery,
+      response: z.object({ games: z.array(GameLeaderboards) }),
+      doc: { summary: 'Every board across every game, with top entries', tags: ['leaderboards'] },
+    },
+  }),
+  ...use(session, game).path('/games/:slug').group({
+    listGameLeaderboards: {
+      method: 'GET', path: '/leaderboards',
+      response: z.object({ boards: z.array(Board) }),
+      errors: { 404: ErrorBody },
+      doc: { summary: "The game's boards (no entries)", tags: ['leaderboards'] },
+    },
+    getLeaderboard: {
+      method: 'GET', path: '/leaderboards/:key',
+      params: BoardKeyParams,
+      /** `limit`: rows to return, 1 to 500 (clamped), default 50. */
+      query: z.object({ limit: LenientRowCount }),
+      response: z.object({ board: Board, entries: z.array(LeaderboardEntry) }),
+      errors: { 400: ErrorBody, 404: ErrorBody },
+      doc: { summary: "One board's ranked entries (404 if the board doesn't exist)", tags: ['leaderboards'] },
+    },
+  }),
+  ...use(requireUser, game).path('/games/:slug').group({
+    /**
+     * Submit a score. The first submission creates the board (with `title`,
+     * `sort` and `showZeros`; later values are ignored). Only an improvement
+     * replaces the player's entry. Boards a game declares with
+     * `source: "server"` refuse client scores (403 `server_board`).
+     */
+    submitScore: {
+      method: 'POST', path: '/leaderboards/:key/scores',
+      params: BoardKeyParams,
+      body: z.object({
+        /** A finite number (numeric strings pass, as for the old hub's `Number(x)`). */
+        score: z.coerce.number<number>({ error: 'score must be a finite number.' }),
+        /** Board title, used only when this call creates the board (non-text is ignored). */
+        title: z.string().optional().catch(undefined),
+        /** Sort direction, used only on creation. Anything but `asc` means `desc`. */
+        sort: SortDir.optional().catch(undefined),
+        /** Keep zero scores visible, used only on creation. */
+        showZeros: Truthy.optional(),
+        /** Any JSON stored with the entry (a character, a run seed). */
+        meta: Json.optional(),
+      }),
+      response: z.object({
+        board: Board,
+        /** The player's stored best after this submission. */
+        best: z.number().nullable(),
+        /** The player's rank on the board (`null` if they have no entry). */
+        rank: Rank.nullable(),
+      }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Submit a score (best-only; creates the board on first use)', tags: ['leaderboards'] },
+    },
+  }),
+};

package/src/api/messages.ts

@@ -1,142 +1,142 @@
-/**
- * Direct messages between mutual friends (multiplayer-impl.md §5.2).
- *
- * "Checked before delivered": text is moderated before it is stored or
- * pushed. Free text needs the conversation's chat mode to be `on` (both
- * claimed, friends, no parent lock, site switch on); otherwise only
- * quick-chat ids go through. Hidden messages and messages from currently
- * suspended senders are left out of every read.
- */
-import { z } from 'zod';
-import { Millis, Ok, UserId } from '../common';
-import { LooseNumber, requiredId } from '../coerce';
-import { PlayerLite } from '../entities';
-import { ContentRejected, ErrorBody } from '../errors';
-import { requireClaimed } from '../middleware';
-import { ChatMode } from '../entities';
-import { QuickId } from './social/config';
-
-/** A message id: a positive integer, increasing over time. */
-export const MessageId = z.number().int().positive();
-
-/** A direct message. */
-export const Message = z.object({
-  id: MessageId,
-  /** The sender. */
-  from: UserId,
-  /** The recipient. */
-  to: UserId,
-  /** The delivered (possibly softened) text; a quick message carries its phrase's text. */
-  text: z.string(),
-  /** The quick-chat phrase id, for quick messages only. */
-  quick: QuickId.optional(),
-  /** When it was sent (epoch ms). */
-  at: Millis,
-  /** The recipient has read it. */
-  read: z.boolean(),
-  /** Words were swapped by the filter. Only on the sender's own copy. */
-  softened: z.literal(true).optional(),
-});
-
-/** A direct message. */
-export type Message = z.infer<typeof Message>;
-
-/** A conversation summary: the other player, the last message and how many of theirs you haven't read. */
-export const Conversation = z.object({
-  user: PlayerLite,
-  last: Message,
-  unread: z.number().int().nonnegative(),
-});
-
-/** A conversation summary. */
-export type Conversation = z.infer<typeof Conversation>;
-
-/** One page of a conversation's history. */
-export const MessagesPage = z.object({
-  /** Oldest to newest, at most 50. */
-  messages: z.array(Message),
-  /** Older messages exist (page with `?before=` the first id). */
-  more: z.boolean(),
-  /** The mode the chat UI should render: `off` when DMs are off, `quick` while you are muted. */
-  mode: ChatMode,
-});
-
-/** A page of history. */
-export type MessagesPage = z.infer<typeof MessagesPage>;
-
-/** A DM to send: free text, or a quick-chat phrase id (exactly one). */
-export const SendMessageInput = z.object({
-  /** Free text (moderated; only when the conversation's mode is `on`). */
-  text: z.string().optional(),
-  /** A quick-chat phrase id (any mode but `off`). */
-  quick: QuickId.optional(),
-}).refine((b) => (b.text === undefined) !== (b.quick === undefined), 'Send either text or a quick-chat id.');
-
-/** A DM to send. */
-export type SendMessageInput = z.infer<typeof SendMessageInput>;
-
-/**
- * Unread DMs (the `hello` snapshot's `unread`), ignoring hidden messages and
- * suspended senders.
- */
-export const UnreadSummary = z.object({
-  /** Total unread. */
-  dms: z.number().int().nonnegative(),
-  /** Unread per sender, keyed by the sender's user id (as a decimal string). */
-  byUser: z.record(z.string().regex(/^\d+$/), z.number().int().positive()),
-});
-
-/** Unread DM counts. */
-export type UnreadSummary = z.infer<typeof UnreadSummary>;
-
-/**
- * `:userId`, the other side of the conversation: a claimed, non-suspended
- * player other than you, else 404 "No such player." Read like `Number(x)`:
- * anything that is not a player's id is the same 404.
- */
-const Partner = z.object({ userId: LooseNumber.catch(Number.NaN) });
-
-/** The direct-message endpoints. */
-export const messagesEndpoints = {
-  ...requireClaimed.group({
-    listConversations: {
-      method: 'GET', path: '/social/conversations',
-      response: z.object({
-        /** Newest first, one per partner, at most 200. */
-        conversations: z.array(Conversation),
-      }),
-      errors: { 401: ErrorBody, 403: ErrorBody },
-      doc: { summary: 'Your conversations, newest first', tags: ['messages'] },
-    },
-    listDirectMessages: {
-      method: 'GET', path: '/social/messages/:userId', params: Partner,
-      query: z.object({
-        /** Only messages older than this message id; `0` or anything not a number means from the newest. */
-        before: LooseNumber.optional().catch(undefined),
-      }),
-      response: MessagesPage,
-      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'One page of history with a player', tags: ['messages'] },
-    },
-    sendDirectMessage: {
-      method: 'POST', path: '/social/messages/:userId', params: Partner, body: SendMessageInput,
-      response: z.object({ message: Message }),
-      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 422: ContentRejected },
-      doc: {
-        summary: 'Send a DM to a friend',
-        description: '403 `not_friends` or `dms_closed`; 422 when the text is rejected, the chat mode forbids it, or you are sending too fast.',
-        tags: ['messages'],
-      },
-    },
-    markDirectMessagesRead: {
-      method: 'POST', path: '/social/messages/:userId/read', params: Partner,
-      body: z.object({
-        /** Mark their messages to you up to and including this id. */
-        upTo: requiredId('upTo must be a message id.'),
-      }),
-      response: Ok,
-      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
-      doc: { summary: "Mark a friend's messages to you as read", tags: ['messages'] },
-    },
-  }),
-};
+/**
+ * Direct messages between mutual friends (multiplayer-impl.md §5.2).
+ *
+ * "Checked before delivered": text is moderated before it is stored or
+ * pushed. Free text needs the conversation's chat mode to be `on` (both
+ * claimed, friends, no parent lock, site switch on); otherwise only
+ * quick-chat ids go through. Hidden messages and messages from currently
+ * suspended senders are left out of every read.
+ */
+import { z } from 'zod';
+import { Millis, Ok, UserId } from '../common';
+import { LooseNumber, requiredId } from '../coerce';
+import { PlayerLite } from '../entities';
+import { ContentRejected, ErrorBody } from '../errors';
+import { requireClaimed } from '../middleware';
+import { ChatMode } from '../entities';
+import { QuickId } from './social/config';
+
+/** A message id: a positive integer, increasing over time. */
+export const MessageId = z.number().int().positive();
+
+/** A direct message. */
+export const Message = z.object({
+  id: MessageId,
+  /** The sender. */
+  from: UserId,
+  /** The recipient. */
+  to: UserId,
+  /** The delivered (possibly softened) text; a quick message carries its phrase's text. */
+  text: z.string(),
+  /** The quick-chat phrase id, for quick messages only. */
+  quick: QuickId.optional(),
+  /** When it was sent (epoch ms). */
+  at: Millis,
+  /** The recipient has read it. */
+  read: z.boolean(),
+  /** Words were swapped by the filter. Only on the sender's own copy. */
+  softened: z.literal(true).optional(),
+});
+
+/** A direct message. */
+export type Message = z.infer<typeof Message>;
+
+/** A conversation summary: the other player, the last message and how many of theirs you haven't read. */
+export const Conversation = z.object({
+  user: PlayerLite,
+  last: Message,
+  unread: z.number().int().nonnegative(),
+});
+
+/** A conversation summary. */
+export type Conversation = z.infer<typeof Conversation>;
+
+/** One page of a conversation's history. */
+export const MessagesPage = z.object({
+  /** Oldest to newest, at most 50. */
+  messages: z.array(Message),
+  /** Older messages exist (page with `?before=` the first id). */
+  more: z.boolean(),
+  /** The mode the chat UI should render: `off` when DMs are off, `quick` while you are muted. */
+  mode: ChatMode,
+});
+
+/** A page of history. */
+export type MessagesPage = z.infer<typeof MessagesPage>;
+
+/** A DM to send: free text, or a quick-chat phrase id (exactly one). */
+export const SendMessageInput = z.object({
+  /** Free text (moderated; only when the conversation's mode is `on`). */
+  text: z.string().optional(),
+  /** A quick-chat phrase id (any mode but `off`). */
+  quick: QuickId.optional(),
+}).refine((b) => (b.text === undefined) !== (b.quick === undefined), 'Send either text or a quick-chat id.');
+
+/** A DM to send. */
+export type SendMessageInput = z.infer<typeof SendMessageInput>;
+
+/**
+ * Unread DMs (the `hello` snapshot's `unread`), ignoring hidden messages and
+ * suspended senders.
+ */
+export const UnreadSummary = z.object({
+  /** Total unread. */
+  dms: z.number().int().nonnegative(),
+  /** Unread per sender, keyed by the sender's user id (as a decimal string). */
+  byUser: z.record(z.string().regex(/^\d+$/), z.number().int().positive()),
+});
+
+/** Unread DM counts. */
+export type UnreadSummary = z.infer<typeof UnreadSummary>;
+
+/**
+ * `:userId`, the other side of the conversation: a claimed, non-suspended
+ * player other than you, else 404 "No such player." Read like `Number(x)`:
+ * anything that is not a player's id is the same 404.
+ */
+const Partner = z.object({ userId: LooseNumber.catch(Number.NaN) });
+
+/** The direct-message endpoints. */
+export const messagesEndpoints = {
+  ...requireClaimed.group({
+    listConversations: {
+      method: 'GET', path: '/social/conversations',
+      response: z.object({
+        /** Newest first, one per partner, at most 200. */
+        conversations: z.array(Conversation),
+      }),
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Your conversations, newest first', tags: ['messages'] },
+    },
+    listDirectMessages: {
+      method: 'GET', path: '/social/messages/:userId', params: Partner,
+      query: z.object({
+        /** Only messages older than this message id; `0` or anything not a number means from the newest. */
+        before: LooseNumber.optional().catch(undefined),
+      }),
+      response: MessagesPage,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'One page of history with a player', tags: ['messages'] },
+    },
+    sendDirectMessage: {
+      method: 'POST', path: '/social/messages/:userId', params: Partner, body: SendMessageInput,
+      response: z.object({ message: Message }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 422: ContentRejected },
+      doc: {
+        summary: 'Send a DM to a friend',
+        description: '403 `not_friends` or `dms_closed`; 422 when the text is rejected, the chat mode forbids it, or you are sending too fast.',
+        tags: ['messages'],
+      },
+    },
+    markDirectMessagesRead: {
+      method: 'POST', path: '/social/messages/:userId/read', params: Partner,
+      body: z.object({
+        /** Mark their messages to you up to and including this id. */
+        upTo: requiredId('upTo must be a message id.'),
+      }),
+      response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Mark a friend's messages to you as read", tags: ['messages'] },
+    },
+  }),
+};

package/src/api/mp/chat.ts

@@ -1,36 +1,36 @@
-/**
- * Group chat in hub rooms and parties (multiplayer.md §4.3, §4.8): what a
- * player sends, and the moderated line everyone receives.
- */
-import { z } from 'zod';
-import { UserId } from '../../common';
-
-
-/**
- * A chat send: a quick-chat phrase id, or free text. When `quick` is set it
- * wins and `text` is ignored.
- */
-export const ChatSend = z.object({
-  /** Free text; only allowed in mode `on`, then moderated. */
-  text: z.string().optional(),
-  /** A quick-chat phrase id (hub phrase, `e:<emoji>` emote or game phrase). */
-  quick: z.string().optional(),
-});
-
-/** The line as delivered: the (possibly softened) text, and the phrase id for quick-chat. */
-export const ChatLine = z.object({
-  text: z.string(),
-  /** Set when the line is a quick-chat phrase. */
-  quick: z.string().optional(),
-  /** Moderation reworded the text. */
-  softened: z.literal(true).optional(),
-});
-
-/** A delivered chat line. */
-export type ChatLine = z.infer<typeof ChatLine>;
-
-/** A chat line pushed to a room or party, with its sender. */
-export const ChatLineEvent = ChatLine.extend({ from: UserId });
-
-/** The error codes a chat send can fail with (besides its surface's own). */
-export const CHAT_ERRORS = ['rate_limited', 'content_rejected', 'bad_quick'] as const;
+/**
+ * Group chat in hub rooms and parties (multiplayer.md §4.3, §4.8): what a
+ * player sends, and the moderated line everyone receives.
+ */
+import { z } from 'zod';
+import { UserId } from '../../common';
+
+
+/**
+ * A chat send: a quick-chat phrase id, or free text. When `quick` is set it
+ * wins and `text` is ignored.
+ */
+export const ChatSend = z.object({
+  /** Free text; only allowed in mode `on`, then moderated. */
+  text: z.string().optional(),
+  /** A quick-chat phrase id (hub phrase, `e:<emoji>` emote or game phrase). */
+  quick: z.string().optional(),
+});
+
+/** The line as delivered: the (possibly softened) text, and the phrase id for quick-chat. */
+export const ChatLine = z.object({
+  text: z.string(),
+  /** Set when the line is a quick-chat phrase. */
+  quick: z.string().optional(),
+  /** Moderation reworded the text. */
+  softened: z.literal(true).optional(),
+});
+
+/** A delivered chat line. */
+export type ChatLine = z.infer<typeof ChatLine>;
+
+/** A chat line pushed to a room or party, with its sender. */
+export const ChatLineEvent = ChatLine.extend({ from: UserId });
+
+/** The error codes a chat send can fail with (besides its surface's own). */
+export const CHAT_ERRORS = ['rate_limited', 'content_rejected', 'bad_quick'] as const;