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

package/src/api/economy/bundle.ts

@@ -0,0 +1,69 @@
+/**
+ * Economy shapes: a player's per-game holdings and the bundles that move
+ * goods. Items are opaque, app-defined {@link Key}s; the hub only counts them.
+ */
+import { z } from 'zod';
+import { Key } from '../../common';
+
+/**
+ * The default largest quantity (or coin amount) one bundle entry may carry.
+ * The hub's limit is `HUB_MAX_ITEM_QTY`, which defaults to this.
+ */
+export const MAX_ITEM_QTY = 1_000_000;
+
+/**
+ * The default most distinct item keys one bundle may name. The hub's limit
+ * is `HUB_MAX_BUNDLE_ITEMS`, which defaults to this.
+ */
+export const MAX_BUNDLE_ITEMS = 50;
+
+/** A player's holdings in one game: items with a positive count, and coins. */
+export const Inventory = z.object({
+  /** Sorted by key. */
+  items: z.array(z.object({ key: Key, qty: z.number().int().positive() })),
+  coins: z.number().int().nonnegative(),
+});
+
+/** A player's holdings in one game. */
+export type Inventory = z.infer<typeof Inventory>;
+
+/**
+ * A bundle quantity, read like the hub's `Number(x)` (numeric strings pass).
+ * A value that is not a number reads as `NaN` here rather than failing, so
+ * the hub's own range check, which knows its configured limits, answers with
+ * its message (e.g. `grant.coins must be an integer in [0, 1000000].`).
+ * Clients should send a JSON integer.
+ */
+const BundleQuantity = z.coerce.number<number>().catch(Number.NaN);
+
+/**
+ * Goods to grant, spend or trade, as a request sends them, for the request
+ * field named `label` (`grant`, `take`, `give`, `want`), which the error
+ * messages name. Both parts are optional (`null` or missing means none).
+ * Item keys must be {@link Key}s, at most `HUB_MAX_BUNDLE_ITEMS` of them,
+ * each with a quantity from 1 to `HUB_MAX_ITEM_QTY`; coins run from 0 to
+ * `HUB_MAX_ITEM_QTY`. The hub checks those limits and the keys itself.
+ */
+export function bundleInput(label: string) {
+  return z.object({
+    /** 0 to `HUB_MAX_ITEM_QTY`. */
+    coins: BundleQuantity.nullish(),
+    /** Item key to quantity (1 to `HUB_MAX_ITEM_QTY`). */
+    items: z.record(z.string(), BundleQuantity, { error: `${label}.items must be an object of key→quantity.` }).nullish(),
+  }, { error: `${label} must be an object.` });
+}
+
+/** A request bundle, for documentation and clients. */
+export const BundleInput = bundleInput('bundle');
+
+/** A request bundle. */
+export type BundleInput = z.infer<typeof BundleInput>;
+
+/** A bundle as the hub stores and returns it on a trade offer: both parts always present. */
+export const Bundle = z.object({
+  items: z.record(Key, z.number().int().positive()),
+  coins: z.number().int().nonnegative(),
+});
+
+/** A stored bundle. */
+export type Bundle = z.infer<typeof Bundle>;

package/src/api/economy/inventory.ts

@@ -0,0 +1,57 @@
+/**
+ * Per-game inventory: the hub is the ledger (no negative balances, goods are
+ * conserved in trades) but does not judge game rules, so granting is trusted
+ * like scores are.
+ */
+import { use } from '@ayepi/core';
+import { z } from 'zod';
+import { ErrorBody } from '../../errors';
+import { game, requireActive, requireUser } from '../../middleware';
+import { bundleInput, Inventory } from './bundle';
+
+const BAD_USER_ID = 'Bad user id.';
+
+/** `:userId`: a positive integer, else 400 "Bad user id.". */
+const PlayerIdParam = z.coerce.number<number>({ error: BAD_USER_ID }).int({ error: BAD_USER_ID }).positive({ error: BAD_USER_ID });
+
+/** The inventory endpoints. */
+export const inventoryEndpoints = {
+  ...use(requireUser, game).path('/games/:slug').group({
+    getMyInventory: {
+      method: 'GET', path: '/inventory', response: Inventory,
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "The caller's items and coins in this game", tags: ['economy'] },
+    },
+    /** Add goods to the caller (gameplay rewards, opening a box). The body is the bundle. */
+    grantInventoryItems: {
+      method: 'POST', path: '/inventory/grant', body: bundleInput('grant'), response: Inventory,
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Grant goods to the caller; returns the new holdings', tags: ['economy'] },
+    },
+    /**
+     * Atomically remove `take` from the caller and add `give`: selling (take
+     * items, give coins) and buying from the house (take coins, give items).
+     * 409 when the caller can't cover `take`.
+     */
+    exchangeInventoryItems: {
+      method: 'POST', path: '/inventory/exchange',
+      body: z.object({ take: bundleInput('take').nullish(), give: bundleInput('give').nullish() }),
+      response: Inventory,
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'Swap goods with the house; returns the new holdings', tags: ['economy'] },
+    },
+  }),
+  ...use(requireActive, game).path('/games/:slug').group({
+    /**
+     * Another claimed player's holdings in this game, for composing a trade
+     * offer. 404 for a guest or unknown id.
+     */
+    getPlayerInventory: {
+      method: 'GET', path: '/players/:userId/inventory',
+      params: z.object({ userId: PlayerIdParam }),
+      response: Inventory,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Another player's holdings (to compose a trade)", tags: ['economy'] },
+    },
+  }),
+};

package/src/api/economy/trades.ts

@@ -0,0 +1,154 @@
+/**
+ * Async player-to-player trades on the economy ledger. Making an offer
+ * escrows its `give` side; the recipient accepts (atomic swap), declines or
+ * counters, and the sender may cancel. Pending offers expire after 14 days
+ * (`HUB_TRADE_TTL_MS`), refunding the escrow.
+ */
+import { ctx, middleware, use } from '@ayepi/core';
+import { z } from 'zod';
+import { Millis, Slug } from '../../common';
+import { PlayerLite, type SessionUser } from '../../entities';
+import { ContentRejected, ErrorBody } from '../../errors';
+import { game, requireActive } from '../../middleware';
+import { LooseNumber, LooseText } from '../../coerce';
+import { Bundle, bundleInput } from './bundle';
+
+/** Where an offer is in its life. Only `pending` offers can change. */
+export const TradeStatus = z.enum(['pending', 'accepted', 'declined', 'cancelled', 'countered', 'expired']);
+
+/** A trade status. */
+export type TradeStatus = z.infer<typeof TradeStatus>;
+
+/** A party to a trade, or a player the roster offers to trade with. */
+export const TradePlayer = PlayerLite.pick({ id: true, username: true });
+
+/** A trade party. */
+export type TradePlayer = z.infer<typeof TradePlayer>;
+
+/** A trade offer, seen from the caller's side. */
+export const TradeOffer = z.object({
+  id: z.number().int().positive(),
+  game: Slug,
+  status: TradeStatus,
+  /** `outgoing` when the caller sent it. */
+  direction: z.enum(['incoming', 'outgoing']),
+  from: TradePlayer,
+  to: TradePlayer,
+  /** What the sender offers (escrowed while pending). */
+  give: Bundle,
+  /** What the sender asks for in return. */
+  want: Bundle,
+  /** The sender's note, `''` when none. */
+  note: z.string(),
+  /** The offer this one counters, or `null`. */
+  parentId: z.number().int().positive().nullable(),
+  /** Epoch ms. */
+  createdAt: Millis,
+  /** When it stopped being pending (epoch ms), or `null`. */
+  resolvedAt: Millis.nullable(),
+  /** When a pending offer expires (epoch ms). */
+  expiresAt: Millis,
+});
+
+/** A trade offer. */
+export type TradeOffer = z.infer<typeof TradeOffer>;
+
+/**
+ * Active and a claimed account, for making, accepting and countering trades
+ * (so escrow is never stranded on a guest). A guest gets 403 "Create a free
+ * account (via the menu) to trade." with no `code`, before the game or the
+ * body is checked; unlike the shared `requireClaimed`, which says
+ * `claim_required`.
+ */
+export const requireTrader = middleware('requireTrader', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [requireActive],
+});
+
+/** `{ offer }`: the offer after a trade action. */
+const OfferResult = z.object({ offer: TradeOffer });
+
+/** The two sides of a new offer or counter, plus an optional note (moderated, up to 200 characters). */
+const OfferTerms = z.object({
+  give: bundleInput('give').nullish(),
+  want: bundleInput('want').nullish(),
+  /** Shown to the other player, so it is moderated. */
+  note: LooseText.nullish(),
+});
+
+/**
+ * `:id` of a trade offer, read with `Number()`: an id that is not a number
+ * names no offer, so it is a 404 "No such trade offer." like an unknown one.
+ */
+const OfferParams = z.object({ id: LooseNumber.catch(Number.NaN) });
+
+/** Errors from resolving an offer: not yours (403), unknown (404), no longer pending (409). */
+const ResolveErrors = { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody };
+
+/** The trade endpoints. */
+export const tradeEndpoints = {
+  ...use(requireActive, game).path('/games/:slug').group({
+    /** Claimed players with a footprint in this game, excluding the caller (up to 500, by name). */
+    listTradePartners: {
+      method: 'GET', path: '/trades/players',
+      response: z.object({ players: z.array(TradePlayer) }),
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Players the caller can trade with in this game', tags: ['trades'] },
+    },
+    /** The caller's offers in this game, newest first (up to 100). Expired offers are settled first. */
+    listMyTrades: {
+      method: 'GET', path: '/trades',
+      query: z.object({
+        /** Only offers sent to (`incoming`) or by (`outgoing`) the caller; omit (or anything else) for both. */
+        box: z.enum(['incoming', 'outgoing']).optional().catch(undefined),
+        /** Only offers with this {@link TradeStatus}; an unknown status matches nothing, `''` means any. */
+        status: z.union([TradeStatus, z.string()]).optional(),
+      }),
+      response: z.object({ offers: z.array(TradeOffer) }),
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: "The caller's trade offers", tags: ['trades'] },
+    },
+    declineTrade: {
+      method: 'POST', path: '/trades/:id/decline', params: OfferParams, response: OfferResult,
+      errors: ResolveErrors,
+      doc: { summary: 'Decline an offer sent to the caller (refunds the escrow)', tags: ['trades'] },
+    },
+    cancelTrade: {
+      method: 'POST', path: '/trades/:id/cancel', params: OfferParams, response: OfferResult,
+      errors: ResolveErrors,
+      doc: { summary: 'Cancel an offer the caller sent (refunds the escrow)', tags: ['trades'] },
+    },
+  }),
+  ...use(requireTrader, game).path('/games/:slug').group({
+    /**
+     * Offer a trade to the player named `toUser`. Escrows `give` (409 if the
+     * caller can't cover it); at least one side must be non-empty.
+     */
+    createTrade: {
+      method: 'POST', path: '/trades',
+      body: OfferTerms.extend({
+        /** The recipient's username (case-insensitive). Missing or blank is a 400. */
+        toUser: LooseText.nullish(),
+      }),
+      responses: { 201: OfferResult },
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 422: ContentRejected },
+      doc: { summary: 'Make a trade offer', tags: ['trades'] },
+    },
+    /** Accept an offer sent to the caller: they must own its `want` side (409 otherwise). */
+    acceptTrade: {
+      method: 'POST', path: '/trades/:id/accept', params: OfferParams, response: OfferResult,
+      errors: ResolveErrors,
+      doc: { summary: 'Accept an offer (atomic swap)', tags: ['trades'] },
+    },
+    /**
+     * Counter an offer sent to the caller: the original is refunded and
+     * closed as `countered`, and a linked offer goes back to its sender.
+     */
+    counterTradeOffer: {
+      method: 'POST', path: '/trades/:id/counter', params: OfferParams, body: OfferTerms,
+      responses: { 201: OfferResult },
+      errors: { ...ResolveErrors, 400: ErrorBody, 422: ContentRejected },
+      doc: { summary: 'Counter an offer with a new one', tags: ['trades'] },
+    },
+  }),
+};

package/src/api/economy.ts

@@ -0,0 +1,15 @@
+/**
+ * Per-game economy: inventory, grants, exchanges and trades. The endpoints
+ * and shapes live in `economy/`.
+ */
+import { inventoryEndpoints } from './economy/inventory';
+import { tradeEndpoints } from './economy/trades';
+
+export * from './economy/bundle';
+export { requireTrader, TradeOffer, TradePlayer, TradeStatus } from './economy/trades';
+
+/** The economy endpoints. */
+export const economyEndpoints = {
+  ...inventoryEndpoints,
+  ...tradeEndpoints,
+};

package/src/api/index.ts

@@ -0,0 +1,85 @@
+/**
+ * The public REST API: every endpoint a game, the menu or the social runtime
+ * calls, as one ayepi spec. Paths are relative to `/_api`. One file per area.
+ */
+import { spec } from '@ayepi/core';
+import { analyticsEndpoints } from './analytics';
+import { authEndpoints } from './auth';
+import { catalogEndpoints } from './catalog';
+import { dailyEndpoints } from './daily';
+import { economyEndpoints } from './economy';
+import { leaderboardsEndpoints } from './leaderboards';
+import { messagesEndpoints } from './messages';
+import { mpEndpoints } from './mp';
+import { notifyEndpoints } from './notify';
+import { progressEndpoints } from './progress';
+import { raceEndpoints } from './race';
+import { reportsEndpoints } from './reports';
+import { socialEndpoints } from './social';
+import { versionEndpoints } from './version';
+
+// Every area's shapes (request, response and entity schemas), for clients and tests.
+export * from './analytics';
+export * from './auth';
+export * from './catalog';
+export * from './daily';
+export * from './economy';
+export * from './leaderboards';
+export * from './messages';
+export * from './mp';
+export * from './notify';
+export * from './progress';
+export * from './race';
+export * from './reports';
+export * from './social';
+export * from './version';
+
+/**
+ * Every public endpoint, by name. Typed as an intersection of the areas so the
+ * published .d.ts refers to each area instead of repeating every endpoint.
+ */
+export type PublicEndpoints =
+  typeof authEndpoints
+  & typeof catalogEndpoints
+  & typeof progressEndpoints
+  & typeof leaderboardsEndpoints
+  & typeof dailyEndpoints
+  & typeof economyEndpoints
+  & typeof analyticsEndpoints
+  & typeof socialEndpoints
+  & typeof messagesEndpoints
+  & typeof notifyEndpoints
+  & typeof reportsEndpoints
+  & typeof mpEndpoints
+  & typeof raceEndpoints
+  & typeof versionEndpoints;
+
+/** Every public endpoint, by name. */
+export const publicEndpoints: PublicEndpoints = {
+  ...authEndpoints,
+  ...catalogEndpoints,
+  ...progressEndpoints,
+  ...leaderboardsEndpoints,
+  ...dailyEndpoints,
+  ...economyEndpoints,
+  ...analyticsEndpoints,
+  ...socialEndpoints,
+  ...messagesEndpoints,
+  ...notifyEndpoints,
+  ...reportsEndpoints,
+  ...mpEndpoints,
+  ...raceEndpoints,
+  ...versionEndpoints,
+};
+
+/**
+ * The public API spec's type. Declared (not inferred) so the published
+ * `.d.ts` refers to `publicEndpoints` instead of repeating every endpoint.
+ */
+export interface PublicApi {
+  /** Every public endpoint, by name. */
+  readonly endpoints: PublicEndpoints;
+}
+
+/** The public API spec (paths relative to `/_api`). */
+export const publicApi: PublicApi = spec({ endpoints: publicEndpoints });

package/src/api/leaderboards.ts

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

package/src/api/messages.ts

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