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

package/src/errors/index.ts

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

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

@@ -1,100 +1,125 @@
-/**
- * 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;
+/**
+ * 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;
+
+/** What a tournament may be (batch-2026-10 R15). The server enforces each one. */
+export const TOURNAMENT_LIMITS = {
+  /** Longest title, in characters. */
+  titleMax: 48,
+  /** Fewest players. */
+  playersMin: 2,
+  /** Most players. */
+  playersMax: 64,
+  /** Most games in the set a tournament picks from. */
+  gamesMax: 8,
+  /** Lives per player: 1 single, 2 double, 3 triple elimination. */
+  livesMax: 3,
+  /** The default and the longest window to join a ready match before forfeiting, in minutes. */
+  readyMinutesDefault: 10,
+  readyMinutesMax: 60,
+  /** The longest "remind me before it starts", in minutes (one day). */
+  leadMinutesMax: 1440,
+  /** The default reminder for players who signed up for a scheduled tournament, in minutes. */
+  leadMinutesDefault: 10,
+  /** The furthest ahead a tournament may be scheduled, in days. */
+  scheduleDaysMax: 30,
+  /** Most friends invited in one call. */
+  invitesMax: 50,
+} as const;

package/src/logic/daily.ts

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

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