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

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;

package/src/errors/codes/social.ts

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

package/src/errors/index.ts

@@ -0,0 +1,88 @@
+/**
+ * The error model (plan §5.3). Every failed REST call and every failed socket
+ * ack carries an {@link ErrorBody}. `error` is always safe to show a player.
+ * Public codes are listed per area in `codes/`; admin-only codes live in the
+ * server-only internal contract.
+ *
+ * Each schema here also has a named `…Schema` interface. Endpoints reference
+ * these schemas hundreds of times; naming their types lets the published
+ * `.d.ts` refer to them instead of printing every code at every use.
+ */
+import { z } from 'zod';
+import { Millis } from '../common';
+import { CORE_CODES } from './codes/core';
+import { MULTIPLAYER_CODES } from './codes/multiplayer';
+import { PLAY_CODES } from './codes/play';
+import { SOCIAL_CODES } from './codes/social';
+
+const errorCode = z.enum([...CORE_CODES, ...PLAY_CODES, ...SOCIAL_CODES, ...MULTIPLAYER_CODES]);
+
+/** The type of the {@link ErrorCode} schema. */
+export interface ErrorCodeSchema extends Readonly<typeof errorCode> {}
+
+/** Every public error code. */
+export const ErrorCode: ErrorCodeSchema = errorCode;
+
+/** A public error code. */
+export type ErrorCode = z.infer<ErrorCodeSchema>;
+
+const rejectReason = z.enum([
+  'link', 'personal_info', 'contact', 'language', 'slur', 'sexual', 'grown_up', 'unkind',
+  'threat', 'drugs', 'spam', 'shouting', 'too_long', 'empty', 'chars', 'reserved',
+  'rate_limited', 'muted', 'check_unavailable', 'chat_off', 'not_friends', 'suspended',
+  'quick_only', 'dms_closed', 'other',
+]);
+
+/** The type of the {@link RejectReason} schema. */
+export interface RejectReasonSchema extends Readonly<typeof rejectReason> {}
+
+/**
+ * Why text was rejected or a chat action was refused. Coarse on purpose: a
+ * reason names a category, never the word or list that matched.
+ */
+export const RejectReason: RejectReasonSchema = rejectReason;
+
+/** A content-reject reason. */
+export type RejectReason = z.infer<RejectReasonSchema>;
+
+const errorBody = z.object({
+  /** A sentence that is always safe to show the player. */
+  error: z.string(),
+  /** What went wrong, for code to branch on. */
+  code: ErrorCode.optional(),
+  /** Content rejects and suspensions: the category. */
+  reason: RejectReason.optional(),
+  /** A kid-friendly suggestion, e.g. "try saying it another way". */
+  hint: z.string().optional(),
+  /** Rate limits: how long to wait, in ms (0 when not limited). */
+  retryAfterMs: z.number().int().nonnegative().optional(),
+  /** Suspensions and mutes: when they end (epoch ms). */
+  until: Millis.optional(),
+});
+
+/** The type of the {@link ErrorBody} schema. */
+export interface ErrorBodySchema extends Readonly<typeof errorBody> {}
+
+/** The body of every error response and failed socket ack. */
+export const ErrorBody: ErrorBodySchema = errorBody;
+
+/** An error body. */
+export type ErrorBody = z.infer<ErrorBodySchema>;
+
+const contentRejected = errorBody.extend({
+  code: z.literal('content_rejected'),
+  reason: RejectReason,
+  hint: z.string(),
+});
+
+/** The type of the {@link ContentRejected} schema. */
+export interface ContentRejectedSchema extends Readonly<typeof contentRejected> {}
+
+/**
+ * The 422 content-rejected body (multiplayer.md §4.6), shared by DMs, room
+ * chat, suggestions, names and trade notes.
+ */
+export const ContentRejected: ContentRejectedSchema = contentRejected;
+
+/** A content-rejected body. */
+export type ContentRejected = z.infer<ContentRejectedSchema>;

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * The diffenderfer.games hub wire contract: zod schemas and types for the
+ * public REST API, the `/_ws` socket envelope, ops and events, error bodies
+ * and the `game.*` manifest.
+ *
+ * @packageDocumentation
+ */
+export * from './common';
+export * from './entities';
+export * from './errors';
+export * from './middleware';
+export * from './api';
+export * from './realtime';
+export * from './manifest';
+export * from './limits';
+export * from './logic';

package/src/limits.ts

@@ -0,0 +1,100 @@
+/**
+ * Limits a UI has to know about: text lengths, name rules, seat counts and
+ * the rules for a game's `package.json` `game.*` block. Each number is
+ * defined once here; the schemas and the server import it.
+ *
+ * Rate thresholds, caps and timers are server-only and not part of this package.
+ */
+import { z } from 'zod';
+
+/** Account name and password rules (sign-up, claim, rename). */
+export const ACCOUNT_LIMITS = {
+  /** Shortest username, after trimming. */
+  usernameMin: 2,
+  /** Longest username, after trimming. */
+  usernameMax: 24,
+  /** Shortest password. */
+  passwordMin: 6,
+  /** How many built-in avatars there are (`a0` … `a23`). */
+  avatarCount: 24,
+} as const;
+
+/** The characters a username may use: letters, digits, `_`, `-` and spaces. */
+export const USERNAME_PATTERN = /^[A-Za-z0-9_\- ]+$/;
+
+/**
+ * The text limits every social UI renders from. The hub sends the live values
+ * in `GET /social/config` and the socket `hello` (`limits`); the server can
+ * change them (`HUB_LIMITS_JSON`), so a UI should prefer the sent values.
+ */
+export const UiLimits = z.object({
+  /** Longest direct message, in characters. */
+  dmMaxChars: z.number().int().positive(),
+  /** Longest room or party chat line, in characters. */
+  roomChatMaxChars: z.number().int().positive(),
+  /** Longest suggestion title, in characters. */
+  suggestionTitleMax: z.number().int().positive(),
+  /** Longest suggestion body, in characters. */
+  suggestionBodyMax: z.number().int().positive(),
+});
+
+/** The text limits every social UI renders from. */
+export type UiLimits = z.infer<typeof UiLimits>;
+
+/** Today's default {@link UiLimits}, used until the hub sends its own. */
+export const UI_LIMIT_DEFAULTS = {
+  dmMaxChars: 200,
+  roomChatMaxChars: 120,
+  suggestionTitleMax: 60,
+  suggestionBodyMax: 500,
+} as const satisfies UiLimits;
+
+/** Seats in hub rooms and parties. */
+export const SEAT_LIMITS = {
+  /** Most players in one hub room, and the top of any `players` range. */
+  maxSeats: 8,
+  /** Most members in one party. */
+  partyMax: 8,
+} as const;
+
+/** What a racer's live stats (`hub.race.status(stats)`) may hold. */
+export const RACE_STATS_LIMITS = {
+  /** Most stat keys in one update. */
+  maxKeys: 12,
+  /** Largest update, in bytes of JSON. */
+  maxBytes: 600,
+} as const;
+
+/** Limits on the `package.json` `game.*` block (see the manifest schemas). */
+export const MANIFEST_LIMITS = {
+  /** Most `game.changes` entries the hub reads. */
+  changesMax: 200,
+  /** Longest `game.changes` entry, in characters. */
+  changeTextMax: 280,
+  /** Longest leaderboard title, in characters. */
+  leaderboardTitleMax: 80,
+  /** Furthest the menu button may be pushed from its corner, in px. */
+  menuOffsetMax: 600,
+  /** Longest lobby URL suffix, in characters. */
+  lobbyMax: 200,
+  /** Most `game.multiplayer.modes`. */
+  modesMax: 16,
+  /** Longest mode title, in characters. */
+  modeTitleMax: 40,
+  /** Most `game.multiplayer.quickChat` phrases. */
+  quickChatMax: 24,
+  /** Longest quick-chat phrase, in characters. */
+  quickChatTextMax: 40,
+  /** Most `game.multiplayer.chatAllow` words. */
+  chatAllowMax: 20,
+  /** Most `game.race.params`. */
+  raceParamsMax: 6,
+  /** Most options in one race param. */
+  raceOptionsMax: 12,
+  /** Most `game.race.stats` (the live HUD shows the first 3). */
+  raceStatsMax: 8,
+  /** Longest race param, option or stat title, in characters. */
+  raceTitleMax: 24,
+  /** Largest `game.race.minMs`, in ms (10 minutes). */
+  raceMinMsMax: 600_000,
+} as const;

package/src/logic/daily.ts

@@ -0,0 +1,54 @@
+/**
+ * Daily-challenge day keys and seeds: UTC `YYYY-MM-DD` keys, the playable
+ * window, and the deterministic per-(game, day) seed both the hub and the
+ * game compute. Pure; the signed tokens stay server-only.
+ */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** The UTC day key (`YYYY-MM-DD`) of a timestamp. */
+export function dayKey(ts: number): string {
+  return new Date(ts).toISOString().slice(0, 10);
+}
+
+/**
+ * The playable window, newest first: today and the `count - 1` days before it.
+ * @param count - how many days (the back-fill window, 30 by default on the hub)
+ */
+export function windowDays(now: number, count: number): string[] {
+  return Array.from({ length: count }, (_, i) => dayKey(now - i * DAY_MS));
+}
+
+/**
+ * Is `day` playable? A player's local "today" can be UTC±1, so one day into
+ * the future is accepted, plus `backfillDays` into the past. Compared in
+ * whole UTC days, so it is locale-independent.
+ */
+export function inWindow(day: string, now: number, backfillDays: number): boolean {
+  if (!DAY_RE.test(day)) {
+    return false;
+  }
+  const dayStart = Date.parse(`${day}T00:00:00Z`);
+  const today = Date.parse(`${dayKey(now)}T00:00:00Z`);
+  if (Number.isNaN(dayStart) || Number.isNaN(today)) {
+    return false;
+  }
+  const diff = Math.round((dayStart - today) / DAY_MS);
+  return diff <= 1 && diff >= -backfillDays;
+}
+
+/**
+ * The deterministic uint32 seed for a (game, day): FNV-1a over `game#day`.
+ * The game derives its level or difficulty from it, so everyone plays the
+ * same challenge.
+ */
+export function seedForDay(game: string, day: string): number {
+  let hash = 2166136261 >>> 0;
+  const seedInput = `${game}#${day}`;
+  for (let i = 0; i < seedInput.length; i++) {
+    hash ^= seedInput.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}

package/src/logic/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure, browser-safe helpers every hub UI shares: time and count wording,
+ * presence status lines, race wording, and daily day keys and seeds.
+ */
+export * from './daily';
+export * from './presence';
+export * from './race';
+export * from './time';

package/src/logic/presence.ts

@@ -0,0 +1,62 @@
+/**
+ * How a friend's presence reads in every list: the status dot, label, game,
+ * detail and elapsed time (plan §5.2 of multiplayer.md: "consistent everywhere").
+ */
+import type { Presence } from '../api/social/presence';
+import { elapsed, relativeTime } from './time';
+
+/** The pieces of a status line, so renderers can bold the game title. */
+export interface StatusParts {
+  /** A coloured dot emoji. */
+  readonly dot: string;
+  /** 'Playing', 'In lobby', 'Away', 'Online', 'Last seen 3h ago'… */
+  readonly label: string;
+  /** The game title (rendered bold), or `''`. */
+  readonly game: string;
+  /** The game-provided detail, or `''`. */
+  readonly detail: string;
+  /** Elapsed time while playing (`'4:12'`), or `''`. */
+  readonly elapsed: string;
+  readonly online: boolean;
+  /** Their presence offers Join. */
+  readonly joinable: boolean;
+  /** Their presence offers Watch. */
+  readonly watchable: boolean;
+}
+
+/** Status line pieces for a friend; `p` is `null` when they are offline. */
+export function statusParts(presence: Presence | null, now: number, lastSeenAt = 0): StatusParts {
+  const base = { game: '', detail: '', elapsed: '', online: true, joinable: false, watchable: false };
+  if (!presence) {
+    return { ...base, online: false, dot: '⚪', label: lastSeenAt ? `Last seen ${relativeTime(lastSeenAt, now)}` : 'Offline' };
+  }
+  const game = presence.gameTitle ?? '';
+  const detail = presence.detail ?? '';
+  const hasRoom = presence.room !== undefined && presence.room !== '';
+  const flags = { joinable: presence.joinable === true && hasRoom, watchable: presence.watchable === true && hasRoom };
+  switch (presence.kind) {
+    case 'playing':
+      return { ...base, ...flags, dot: '🟢', label: 'Playing', game, detail, elapsed: elapsed(presence.since, now) };
+    case 'watching':
+      return { ...base, ...flags, dot: '🟢', label: 'Watching', game, detail };
+    case 'lobby':
+      return { ...base, ...flags, dot: '🟠', label: 'In lobby', game, detail };
+    case 'away':
+      return { ...base, dot: '🟡', label: 'Away', game };
+    case 'menu':
+      return { ...base, dot: '🟢', label: 'Online', game };
+  }
+}
+
+/** The status line as one string, e.g. "🟢 Playing 8 Ball Pool · Table vs Sam · 4:12". */
+export function statusText(parts: StatusParts): string {
+  const head = parts.label === 'Playing' || parts.label === 'Watching'
+    ? [parts.game ? `${parts.label} ${parts.game}` : parts.label]
+    : [parts.label, parts.game];
+  return `${parts.dot} ${[...head, parts.detail, parts.elapsed].filter(Boolean).join(' · ')}`;
+}
+
+/** The drawer header: "👥 3 friends online · 41 playing now". */
+export function headerLine(friendsOnline: number, online: number): string {
+  return `👥 ${String(friendsOnline)} friend${friendsOnline === 1 ? '' : 's'} online · ${String(online)} playing now`;
+}