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

package/src/api/social/endpoints.ts

@@ -0,0 +1,179 @@
+/**
+ * Social core REST (multiplayer-impl.md §5.1): config, your own social
+ * settings, friends and requests, blocks, player cards, recent players and
+ * online counts. Every route here is closed to suspended accounts (403
+ * `suspended`) except `GET /social/config` and `GET /social/me`, which a
+ * suspended player's UI needs to explain what happened.
+ */
+import { z } from 'zod';
+import { Ok } from '../../common';
+import { requiredId } from '../../coerce';
+import { ContentRejected, ErrorBody } from '../../errors';
+import { requireActive, requireClaimed, requireUser, session } from '../../middleware';
+import { NotifyPrefs } from '../notify';
+import { SocialConfig } from './config';
+import { Audience, FriendsList, PlayerCard, RecentPlayer, SocialMe } from './people';
+import { Counts } from './presence';
+
+/** `{ me }`: your social settings after a change. */
+export const SocialMeResult = z.object({ me: SocialMe });
+
+/** `:id`, another player's user id. A malformed id is a 400. */
+const OtherUser = z.object({ id: requiredId('id must be a user id.') });
+
+/** An {@link Audience} field, with the old hub's message for anything else. */
+const audienceField = (field: string) => z.enum(Audience.options, { error: `${field} must be friends or nobody.` });
+
+/**
+ * `POST /social/friends`: who to befriend, by id or by name, and an optional
+ * first message. `userId` wins when both are given; with neither, the player
+ * is not found (404 `no_player`).
+ */
+export const FriendRequestInput = z.object({
+  userId: requiredId('userId must be a user id.').nullish(),
+  /** A username, case-insensitive. */
+  username: z.string().optional(),
+  message: z.string().optional(),
+});
+
+/** A friend request. */
+export type FriendRequestInput = z.infer<typeof FriendRequestInput>;
+
+/** The result of `POST /social/friends`. */
+export const FriendRequestStatus = z.enum(['requested', 'friends']);
+
+/** The social core endpoints. */
+export const socialEndpoints = {
+  ...session.group({
+    getSocialConfig: {
+      method: 'GET', path: '/social/config', response: SocialConfig,
+      doc: { summary: 'The site-wide social configuration', tags: ['social'] },
+    },
+    getOnlineCounts: {
+      method: 'GET', path: '/social/counts', response: Counts,
+      errors: { 403: ErrorBody },
+      doc: { summary: 'Anonymous online counts, overall and per game', tags: ['social'] },
+    },
+  }),
+  ...requireUser.group({
+    getMySocialProfile: {
+      method: 'GET', path: '/social/me',
+      response: z.object({
+        me: SocialMe,
+        notify: NotifyPrefs,
+        /** How many browsers have a push subscription for this account. */
+        pushSubs: z.number().int().nonnegative(),
+      }),
+      errors: { 401: ErrorBody },
+      doc: { summary: 'Your social settings, notification preferences and push subscription count', tags: ['social'] },
+    },
+  }),
+  ...requireActive.group({
+    listFriendsAndRequests: {
+      method: 'GET', path: '/social/friends', response: FriendsList,
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Friends (online first), requests both ways and blocks', tags: ['social'] },
+    },
+    findPlayerByName: {
+      method: 'GET', path: '/social/players/by-name/:name',
+      params: z.object({ name: z.string() }), response: PlayerCard,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'A player card, by username', tags: ['social'] },
+    },
+    getPlayerCard: {
+      method: 'GET', path: '/social/players/:id', params: OtherUser, response: PlayerCard,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'A player card, by id (404 `no_player` when blocked by them or suspended)', tags: ['social'] },
+    },
+  }),
+  ...requireClaimed.group({
+    updateMySocialProfile: {
+      method: 'PUT', path: '/social/me',
+      body: z.object({
+        /** One of the config's preset avatar ids (else 400 `bad_avatar`). */
+        avatar: z.string().optional(),
+        privacy: audienceField('privacy').optional(),
+        dmPolicy: audienceField('dmPolicy').optional(),
+      }),
+      response: SocialMeResult,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Change your avatar, presence privacy or who may message you', tags: ['social'] },
+    },
+    setParentChatLock: {
+      method: 'POST', path: '/social/chat-lock',
+      body: z.union([
+        z.object({ on: z.literal(true) }),
+        z.object({
+          on: z.literal(false),
+          /** The account password; required to turn the lock off. */
+          password: z.string().optional(),
+        }),
+      ], { error: 'on must be true or false.' }),
+      response: SocialMeResult,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: 'Parent chat lock: on with one tap, off only with the account password',
+        description: 'A wrong password is 403 `bad_password` (logged and rate-limited).',
+        tags: ['social'],
+      },
+    },
+    sendFriendRequest: {
+      method: 'POST', path: '/social/friends', body: FriendRequestInput,
+      response: z.object({ status: FriendRequestStatus }),
+      errors: {
+        400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody,
+        422: ContentRejected, 429: ErrorBody,
+      },
+      doc: {
+        summary: 'Send a friend request (a reverse request accepts at once)',
+        description: 'Answers `requested` without doing anything when the target blocked you or is suspended. '
+          + '`message` is moderated now and delivered as the first DM once you are friends.',
+        tags: ['social'],
+      },
+    },
+    acceptFriendRequest: {
+      method: 'POST', path: '/social/friends/:id/accept', params: OtherUser, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'Accept the request from `:id`', tags: ['social'] },
+    },
+    declineFriendRequest: {
+      method: 'POST', path: '/social/friends/:id/decline', params: OtherUser, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Quietly drop the request from `:id`', tags: ['social'] },
+    },
+    removeFriend: {
+      method: 'DELETE', path: '/social/friends/:id', params: OtherUser, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Unfriend `:id`, or cancel your request to them', tags: ['social'] },
+    },
+    setFriendNotifications: {
+      method: 'PUT', path: '/social/friends/:id/notify', params: OtherUser,
+      body: z.object({ online: z.boolean({ error: 'online must be true or false.' }) }), response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Turn a friend's \"tell me when they're online\" bell on or off", tags: ['social'] },
+    },
+    blockPlayer: {
+      method: 'POST', path: '/social/blocks', body: z.object({ userId: requiredId('userId must be a user id.') }), response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: {
+        summary: 'Block a player',
+        description: 'Also unfriends, drops requests both ways and splits a shared party.',
+        tags: ['social'],
+      },
+    },
+    unblockPlayer: {
+      method: 'DELETE', path: '/social/blocks/:id', params: OtherUser, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Unblock a player', tags: ['social'] },
+    },
+    listRecentPlayers: {
+      method: 'GET', path: '/social/recent',
+      response: z.object({
+        /** Newest first, at most 50. */
+        players: z.array(RecentPlayer),
+      }),
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'People you recently played with', tags: ['social'] },
+    },
+  }),
+};

package/src/api/social/people.ts

@@ -0,0 +1,118 @@
+/**
+ * People shapes: your own social settings, friends, requests, player cards
+ * and recent players. Several are also part of the socket `hello` snapshot.
+ *
+ * Privacy rules behind them: a block in either direction looks to the
+ * blocked side like an ordinary unfriend (or a missing player), suspended
+ * players are invisible, and guests have no friends.
+ */
+import { z } from 'zod';
+import { Millis, Slug } from '../../common';
+import { PlayerLite, SessionUser } from '../../entities';
+import { Presence } from './presence';
+
+/** Who may see my presence, or message me: friends, or nobody. */
+export const Audience = z.enum(['friends', 'nobody']);
+
+/** An audience setting. */
+export type Audience = z.infer<typeof Audience>;
+
+/**
+ * Your own account's social fields (`GET`/`PUT /social/me`, the `hello`
+ * snapshot's `me`). Never shown to other players.
+ */
+export const SocialMe = SessionUser.extend({
+  /** Avatar token; never empty (a default is derived from the id). */
+  avatar: PlayerLite.shape.avatar,
+  /** Who sees my presence and last-seen time. */
+  privacy: Audience,
+  /** Who may message me (and invite me). */
+  dmPolicy: Audience,
+});
+
+/** Your own social settings. */
+export type SocialMe = z.infer<typeof SocialMe>;
+
+/** A friend, with what you may see of their presence. Online friends sort first. */
+export const FriendEntry = PlayerLite.extend({
+  /** `null` when offline or hiding their presence. */
+  presence: Presence.nullable(),
+  /** "Tell me when they come online" is on for this friend. */
+  notifyOnline: z.boolean(),
+  /** When you became friends (epoch ms). */
+  since: Millis,
+  /** When they were last online (epoch ms); `0` when unknown or they hide their presence. */
+  lastSeenAt: Millis,
+});
+
+/** A friend. */
+export type FriendEntry = z.infer<typeof FriendEntry>;
+
+/** Pending friend requests both ways, newest first (blocked and suspended players left out). */
+export const FriendRequests = z.object({
+  /** Requests waiting for you. */
+  incoming: z.array(PlayerLite),
+  /** Requests you sent. */
+  outgoing: z.array(PlayerLite),
+});
+
+/** Pending friend requests. */
+export type FriendRequests = z.infer<typeof FriendRequests>;
+
+/** `GET /social/friends`: friends, requests and the players you blocked. Guests get empty lists. */
+export const FriendsList = FriendRequests.extend({
+  friends: z.array(FriendEntry),
+  /** Players you blocked, newest first. */
+  blocked: z.array(PlayerLite),
+});
+
+/** Friends, requests and blocks. */
+export type FriendsList = z.infer<typeof FriendsList>;
+
+/**
+ * What changed in `ev:friends` (the client refetches `GET /social/friends`).
+ * `restored`: a friend's suspension ended. A player you blocked only ever
+ * sees `removed`.
+ */
+export const FriendChange = z.enum(['request', 'accepted', 'removed', 'declined', 'cancelled', 'blocked', 'restored']);
+
+/** A friends-list change. */
+export type FriendChange = z.infer<typeof FriendChange>;
+
+/** My relation to another player, as their card shows it. */
+export const Relation = z.enum(['self', 'friend', 'incoming', 'outgoing', 'blocked', 'none']);
+
+/** A relation. */
+export type Relation = z.infer<typeof Relation>;
+
+/**
+ * A player card (`GET /social/players/:id`). Someone who blocked you, or who
+ * is suspended, answers 404 exactly like a player who doesn't exist.
+ */
+export const PlayerCard = PlayerLite.extend({
+  relation: Relation,
+  /** Friends only; `null` otherwise, or when offline or hidden. */
+  presence: Presence.nullable(),
+  /** A friend request can be sent (both claimed, no relation yet or theirs is pending, requests on). */
+  canFriend: z.boolean(),
+  /** Friends who take messages, while DMs are on. */
+  canMessage: z.boolean(),
+  /** Friends who take messages. */
+  canInvite: z.boolean(),
+  /** Anyone but yourself. */
+  canReport: z.boolean(),
+});
+
+/** A player card. */
+export type PlayerCard = z.infer<typeof PlayerCard>;
+
+/** Someone you recently played with (`GET /social/recent`). */
+export const RecentPlayer = PlayerLite.extend({
+  /** The game you played together. */
+  game: Slug,
+  /** When you last played together (epoch ms). */
+  lastAt: Millis,
+});
+
+/** A recent player. */
+export type RecentPlayer = z.infer<typeof RecentPlayer>;

package/src/api/social/presence.ts

@@ -0,0 +1,95 @@
+/**
+ * Presence: what a player is doing right now, as their friends see it, and
+ * the anonymous online counts (multiplayer-impl.md §4.4). Games report a
+ * {@link PresenceInput} per tab (socket op `presence`); the hub folds a
+ * user's tabs into one {@link Presence} and pushes it to friends
+ * (`ev:presence`).
+ */
+import { z } from 'zod';
+import { Millis, Slug } from '../../common';
+
+/** Activity kinds, least engaged first. The most engaged tab wins; hidden or idle tabs count as `away`. */
+export const PresenceKind = z.enum(['away', 'menu', 'lobby', 'watching', 'playing']);
+
+/** An activity kind. */
+export type PresenceKind = z.infer<typeof PresenceKind>;
+
+/** A room reference friends can join with: 1 to 64 of `A-Z a-z 0-9 _ : -`. */
+export const PresenceRoom = z.string().regex(/^[A-Za-z0-9_:-]{1,64}$/);
+
+/** A game mode key: 1 to 32 of `A-Z a-z 0-9 _ -`. */
+export const PresenceMode = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/);
+
+/** The fields a tab reports and friends see back, with the limits the hub enforces. */
+const PresenceFields = z.object({
+  kind: PresenceKind,
+  /** A short status line (at most 40 characters), filtered; a rejected one is dropped. */
+  detail: z.string().max(40).optional(),
+  /** Friends may join. Only ever `true` when present. */
+  joinable: z.boolean().optional(),
+  /** Friends may watch. Only ever `true` when present. */
+  watchable: z.boolean().optional(),
+  /** Join info for friends: the game's own room reference, or the hub room's code. */
+  room: PresenceRoom.optional(),
+  /** A public lobby: friends who follow the game may get a `lobby_open` alert. */
+  public: z.boolean().optional(),
+  /** Free seats, 0 to 64. */
+  openSeats: z.number().int().min(0).max(64).optional(),
+  mode: PresenceMode.optional(),
+});
+
+/**
+ * What a game reports for its tab (socket op `presence`). The hub is
+ * lenient: an unknown `kind`, or input that isn't an object at all (`null`),
+ * counts as `{kind:'menu'}`; unknown fields, and fields that break a rule (a
+ * bad `room`, a fractional `openSeats`, a field of the wrong type), are
+ * ignored one by one, so friends only ever
+ * see {@link Presence}'s fields; `detail` is trimmed to 40 characters before
+ * filtering.
+ */
+export const PresenceInput = z.looseObject({
+  kind: PresenceKind.catch('menu'),
+  detail: z.string().optional().catch(undefined),
+  joinable: z.boolean().optional().catch(undefined),
+  watchable: z.boolean().optional().catch(undefined),
+  room: z.string().optional().catch(undefined),
+  public: z.boolean().optional().catch(undefined),
+  openSeats: z.number().optional().catch(undefined),
+  mode: z.string().optional().catch(undefined),
+}).catch({ kind: 'menu' });
+
+/** A presence report. */
+export type PresenceInput = z.input<typeof PresenceInput>;
+
+/** A user's aggregated presence: their most engaged tab, decorated by the hub. */
+export const Presence = PresenceFields.extend({
+  /** The game the tab is on, `null` on the catalog and other hub pages. */
+  game: Slug.nullable(),
+  /** That game's title, `null` with `game`. */
+  gameTitle: z.string().nullable(),
+  /** When this activity (kind + game) started (epoch ms). */
+  since: Millis,
+  /** Party size, present when the user is in a party of two or more. */
+  partySize: z.number().int().min(2).optional(),
+});
+
+/** A user's aggregated presence. */
+export type Presence = z.infer<typeof Presence>;
+
+/** A non-negative head count. */
+const HeadCount = z.number().int().nonnegative();
+
+/**
+ * Anonymous online counts (`GET /social/counts`, `ev:counts`, the `hello`
+ * snapshot): everyone with a live presence, guests and hidden players
+ * included.
+ */
+export const Counts = z.object({
+  /** Everyone online. */
+  online: HeadCount,
+  /** Players per game slug (games with nobody are absent). */
+  byGame: z.record(Slug, HeadCount),
+});
+
+/** Online counts. */
+export type Counts = z.infer<typeof Counts>;

package/src/api/social.ts

@@ -0,0 +1,9 @@
+/**
+ * Friends, blocks, the social profile and settings, player cards and counts,
+ * plus the shared social shapes (config, presence, people) the socket
+ * `hello` snapshot and events reuse. Split by topic under `social/`.
+ */
+export * from './social/config';
+export * from './social/presence';
+export * from './social/people';
+export * from './social/endpoints';

package/src/api/version.ts

@@ -0,0 +1,40 @@
+/**
+ * `GET /version`: which client versions this hub serves (plan §4.3.3). Games'
+ * clients read it once per page, and `hub-doctor` reads it in a game's CI.
+ * The old hub has no such route and answers 404 "No such API endpoint.", which
+ * clients read as "a hub from before versioning".
+ */
+import { z } from 'zod';
+import { session } from '../middleware';
+
+/**
+ * A semver range in the npm form: comparators (`>=2.0.0-0`, `<3.0.0`)
+ * separated by spaces are all required; `||` separates alternatives.
+ */
+export const VersionRange = z.string().min(1);
+
+/** What `GET /version` answers. */
+export const HubVersion = z.object({
+  /** The hub release this server was built from: the version of the client it serves at `/_hub/hub.js`. */
+  server: z.string(),
+  /** The version of `@diffenderfer-games/hub-contract` the server implements. */
+  contract: z.string(),
+  /** Client versions the server supports (`x-hub-client`); a client outside it should be updated. */
+  supported: VersionRange,
+  /** Supported client versions that are deprecated: they still work, and `hub-doctor` warns. */
+  deprecated: VersionRange,
+});
+
+/** The hub's version and the client versions it supports. */
+export type HubVersion = z.infer<typeof HubVersion>;
+
+/** The version endpoints. */
+export const versionEndpoints = {
+  ...session.group({
+    getHubVersion: {
+      method: 'GET', path: '/version',
+      response: HubVersion,
+      doc: { summary: 'The hub version and the client versions it supports', tags: ['catalog'] },
+    },
+  }),
+};

package/src/coerce.ts

@@ -0,0 +1,50 @@
+/**
+ * Request coercions the single-player handlers apply today. The old hub reads
+ * many request fields loosely (`Number(x)`, `String(x)`, truthiness), and the
+ * contract must accept every request the hub accepts, so these schemas
+ * coerce the same way while keeping the input type clients should send.
+ */
+import { z } from 'zod';
+
+/**
+ * A finite number, read like the hub's `Number(x)`: numeric strings (and
+ * query-string values) pass. Clients should send a JSON number.
+ */
+export const LooseNumber = z.coerce.number<number>();
+
+/**
+ * A flag read by truthiness, like the hub's `if (body.on)`: any value is
+ * accepted and becomes `true` or `false`. Clients should send a boolean.
+ */
+export const Truthy = z.coerce.boolean<boolean>();
+
+/**
+ * Free text read with `String(x)`; the hub trims or clips it to its own limit
+ * rather than rejecting it. Clients should send a string.
+ */
+export const LooseText = z.coerce.string<string>();
+
+/**
+ * A row count from the query string (`?limit=`, `?top=`). The hub clamps it to
+ * its own range and falls back to a default for `0` or a missing value.
+ */
+export const RowCount = LooseNumber.int();
+
+/**
+ * Required text read like the hub's `String(x || '')`, with the old hub's
+ * message for a missing or invalid value. Numbers are accepted and become
+ * strings; anything else fails with `message`. Refine the result with
+ * `.pipe(...)` (e.g. a pattern carrying the same message).
+ */
+export function requiredText(message: string) {
+  return z.union([z.string(), z.number()], { error: message }).transform(String);
+}
+
+/**
+ * A positive integer id read like the hub's `Number(x)` (numeric strings
+ * pass), with the old hub's message for any bad value (`"id must be a user
+ * id."`). Clients should send a JSON number.
+ */
+export function requiredId(message: string) {
+  return z.coerce.number<number>({ error: message }).int({ error: message }).positive({ error: message });
+}

package/src/common.ts

@@ -0,0 +1,42 @@
+/**
+ * Primitives shared by every part of the contract. Each one is the single
+ * definition of its rule: the server validates with it, the client's types
+ * come from it, and the docs are generated from it.
+ */
+import { z } from 'zod';
+
+/** A user id: a positive integer. In paths it arrives as a string and is coerced. */
+export const UserId = z.number().int().positive();
+
+/** A user id taken from a URL path segment (`/players/:userId`). */
+export const UserIdParam = z.coerce.number().int().positive();
+
+/** A numeric row id taken from a URL path segment (`/trades/:id`, `/reports/:id`). */
+export const IdParam = z.coerce.number().int().positive();
+
+/** Milliseconds since the Unix epoch. */
+export const Millis = z.number().int().nonnegative();
+
+/** A game's slug: its folder name under `apps/`, as used in `/<slug>/` URLs. */
+export const Slug = z.string().min(1).max(64);
+
+/**
+ * An app-chosen identifier: a save slot, leaderboard key or stat name.
+ * Letters, digits and `_ . : -`, 1 to 64 characters.
+ */
+export const Key = z.string().regex(/^[A-Za-z0-9_.:-]{1,64}$/);
+
+/** Any JSON value (saves, metadata, room state). */
+export const Json = z.json();
+
+/** A JSON value as stored and returned by the hub: never `undefined`. */
+export type Json = z.infer<typeof Json>;
+
+/** The `{ ok: true }` body many write endpoints answer with. */
+export const Ok = z.object({ ok: z.literal(true) });
+
+/** A UTC day key, `YYYY-MM-DD`. */
+export const DayKey = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+
+/** A `#rrggbb` colour. */
+export const HexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/);

package/src/entities.ts

@@ -0,0 +1,62 @@
+/**
+ * Entity shapes that several areas of the API share. Shapes used by only one
+ * area live in that area's `api/` file.
+ */
+import { z } from 'zod';
+import { Millis, UserId } from './common';
+
+/** Account roles. An empty string is a normal player. */
+export const Role = z.enum(['', 'admin']);
+
+/**
+ * The signed-in user as the hub sees it (`GET /me`, socket `hello`).
+ * `id`, `username` and `guest` are the long-standing fields; the rest drive
+ * social permissions and are only ever sent to the user themself.
+ */
+export const SessionUser = z.object({
+  id: UserId,
+  username: z.string(),
+  /** A temporary account with no password yet; it can be claimed. */
+  guest: z.boolean(),
+  role: Role,
+  /** Avatar token, `''` for the default. */
+  avatar: z.string(),
+  /** A parent locked chat for this account. */
+  chatLock: z.boolean(),
+  /** Muted until this time (epoch ms), `0` when not muted. */
+  mutedUntil: Millis,
+  /** Suspended until this time (epoch ms), `0` when not suspended. */
+  suspendedUntil: Millis,
+});
+
+/** The signed-in user. */
+export type SessionUser = z.infer<typeof SessionUser>;
+
+/** The short account shape the auth endpoints return for a new session. */
+export const AuthUser = SessionUser.pick({ id: true, username: true, guest: true });
+
+/** The short account shape. */
+export type AuthUser = z.infer<typeof AuthUser>;
+
+/**
+ * The effective chat mode of a conversation, room or the whole site: free
+ * text (still filtered), quick-chat phrases only, or no messaging at all.
+ * The strictest of the operator setting, the admin switch and every
+ * participant (guests and parent-locked accounts are `quick`) applies.
+ */
+export const ChatMode = z.enum(['on', 'quick', 'off']);
+
+/** A chat mode. */
+export type ChatMode = z.infer<typeof ChatMode>;
+
+/** Another player as lists and cards show them. */
+export const PlayerLite = z.object({
+  id: UserId,
+  username: z.string(),
+  /** Avatar token; never empty (a default is derived from the id). */
+  avatar: z.string(),
+  guest: z.boolean(),
+});
+
+/** Another player. */
+export type PlayerLite = z.infer<typeof PlayerLite>;

package/src/errors/codes/core.ts

@@ -0,0 +1,10 @@
+/** Error codes any endpoint or socket op can return. */
+export const CORE_CODES = [
+  'bad_request',
+  'signed_out',
+  'suspended',
+  'claim_required',
+  'rate_limited',
+  'content_rejected',
+  'too_large',
+] as const;

package/src/errors/codes/multiplayer.ts

@@ -0,0 +1,43 @@
+/** Error codes from invites, parties, hub rooms, races and the socket envelope. */
+export const MULTIPLAYER_CODES = [
+  // Socket envelope.
+  'unknown_op',
+  'hello_required',
+  // Games and modes.
+  'not_multiplayer',
+  'not_supported',
+  'bad_mode',
+  // Invites, parties, launches, joins.
+  'bad_target',
+  'cannot_invite',
+  'already_member',
+  'party_full',
+  'invite_gone',
+  'party_gone',
+  'not_leader',
+  'bad_info',
+  'launch_invalid',
+  'not_joinable',
+  // Group chat.
+  'bad_quick',
+  // Hub rooms.
+  'room_not_found',
+  'not_in_room',
+  'not_host',
+  'too_many_rooms',
+  'banned',
+  'in_progress',
+  'room_full',
+  'not_ready',
+  'ended',
+  'bad_patch',
+  'race_room',
+  // Races.
+  'not_race',
+  'not_in_race',
+  'not_started',
+  'race_over',
+  'too_fast',
+  'bad_stats',
+  'bad_param',
+] as const;

package/src/errors/codes/play.ts

@@ -0,0 +1,5 @@
+/** Error codes from accounts and the single-player API (saves, stats, boards, daily, economy, trades). */
+export const PLAY_CODES = [
+  /** A score was sent to a board only the game's own server may update (`source: "server"`). */
+  'server_board',
+] as const;