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

package/src/api/version.ts

@@ -1,40 +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'] },
-    },
-  }),
-};
+/**
+ * `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

@@ -1,50 +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 });
-}
+/**
+ * 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

@@ -1,42 +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}$/);
+/**
+ * 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

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

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

@@ -1,43 +1,56 @@
-/** 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;
+/** Error codes from invites, invite links, parties, hub rooms, races, tournaments 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',
+  // Invite links.
+  'link_invalid',
+  'link_room_gone',
+  'too_many_links',
+  // 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',
+  // Tournaments.
+  'tournament_not_found',
+  'tournament_closed',
+  'tournament_full',
+  'tournament_over',
+  'not_creator',
+  'not_entered',
+  'cannot_join',
+  'match_not_ready',
+] as const;

package/src/errors/codes/play.ts

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

package/src/errors/codes/social.ts

@@ -1,31 +1,31 @@
-/** Error codes from friends, messages, notifications, reports and suggestions. */
-export const SOCIAL_CODES = [
-  /** No such player, or one who blocked you or is suspended (they look the same). */
-  'no_player',
-  /** Not one of the preset avatars. */
-  'bad_avatar',
-  /** The chat-lock password was wrong. */
-  'bad_password',
-  /** An admin turned new friend requests off. */
-  'friend_requests_off',
-  /** You can't do that to yourself (friend, block; also invites, joins and room targets). */
-  'bad_target',
-  /** The other player is a guest and must create an account first. */
-  'guest_target',
-  /** You blocked them: unblock first. */
-  'blocked',
-  /** You or they have the most friends allowed. */
-  'friends_limit',
-  /** Too many outgoing friend requests waiting. */
-  'pending_limit',
-  /** The friend request is gone. */
-  'no_request',
-  /** You're not friends (messages, friend bells). */
-  'not_friends',
-  /** You've blocked the most players allowed. */
-  'blocks_limit',
-  /** The player isn't taking messages. */
-  'dms_closed',
-  /** Too many of your suggestions are waiting for review. */
-  'too_many_pending',
-] as const;
+/** Error codes from friends, messages, notifications, reports and suggestions. */
+export const SOCIAL_CODES = [
+  /** No such player, or one who blocked you or is suspended (they look the same). */
+  'no_player',
+  /** Not one of the preset avatars. */
+  'bad_avatar',
+  /** The chat-lock password was wrong. */
+  'bad_password',
+  /** An admin turned new friend requests off. */
+  'friend_requests_off',
+  /** You can't do that to yourself (friend, block; also invites, joins and room targets). */
+  'bad_target',
+  /** The other player is a guest and must create an account first. */
+  'guest_target',
+  /** You blocked them: unblock first. */
+  'blocked',
+  /** You or they have the most friends allowed. */
+  'friends_limit',
+  /** Too many outgoing friend requests waiting. */
+  'pending_limit',
+  /** The friend request is gone. */
+  'no_request',
+  /** You're not friends (messages, friend bells). */
+  'not_friends',
+  /** You've blocked the most players allowed. */
+  'blocks_limit',
+  /** The player isn't taking messages. */
+  'dms_closed',
+  /** Too many of your suggestions are waiting for review. */
+  'too_many_pending',
+] as const;