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

package/src/manifest/multiplayer.ts

@@ -1,71 +1,71 @@
-/**
- * `game.multiplayer`: the opt-in that makes a game an online invite/join
- * target (docs/multiplayer.md §7).
- */
-import { z } from 'zod';
-import { MANIFEST_LIMITS } from '../limits';
-import { LobbySuffix, hasUniqueKeys, playerRange, trimmedText } from './fields';
-
-/**
- * How players connect: `hub-rooms` (the hub relays room messages) or
- * `own-server` (a process app runs its own game server; process apps only).
- */
-export const Transport = z.enum(['hub-rooms', 'own-server']);
-
-/** A mode key: letters, digits, `_` or `-`, 1 to 32 characters. */
-export const ModeKey = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/, 'must be 1-32 letters, digits, _ or -');
-
-/** A game mode players can be invited into. */
-export const MultiplayerMode = z.strictObject({
-  /** Sent with invites and launches as `mode`. */
-  key: ModeKey,
-  /** What players see. Defaults to the key. */
-  title: trimmedText(MANIFEST_LIMITS.modeTitleMax).optional(),
-  /** `[min, max]` players for this mode, within 1..8. Defaults to the game's. */
-  players: playerRange(1).optional(),
-});
-
-/**
- * A soften-list word this game's chat may keep (e.g. `shot` for a pool game):
- * one lowercase word of 2 to 20 letters. Reject-list words never pass.
- */
-export const ChatAllowWord = z.string().trim().toLowerCase().regex(/^[a-z]{2,20}$/, 'must be a single word of 2-20 letters');
-
-/** The `game.multiplayer` block. */
-export const GameMultiplayer = z.strictObject({
-  /** URL suffix invites and Join open, relative to `/<slug>/`. Default `''` (the game's root). */
-  lobby: LobbySuffix.default(''),
-  /** `[min, max]` players, within 1..8. Default `[2, 8]`. */
-  players: playerRange(1).default([2, 8]),
-  /**
-   * `hub-rooms` or `own-server`. Default: `own-server` for process apps,
-   * `hub-rooms` for static apps (which cannot use `own-server`).
-   */
-  transport: Transport.optional(),
-  /** Friends can invite each other into this game. Default `true`. */
-  invites: z.boolean().default(true),
-  /** Friends can join a game in progress. Default `true`. */
-  join: z.boolean().default(true),
-  /** Friends can watch. Default `false`. */
-  spectate: z.boolean().default(false),
-  /** Offer quick match. Default `false`. */
-  quickMatch: z.boolean().default(false),
-  /** Modes players can be invited into (at most 16, unique keys). */
-  modes: z.array(MultiplayerMode).max(MANIFEST_LIMITS.modesMax).refine(hasUniqueKeys, 'mode keys must be unique').default([]),
-  /**
-   * Extra quick-chat phrases for this game (at most 24, each at most 40
-   * characters). Checked by the content filter at boot; failing ones are dropped.
-   */
-  quickChat: z.array(trimmedText(MANIFEST_LIMITS.quickChatTextMax)).max(MANIFEST_LIMITS.quickChatMax).default([]),
-  /** Soften-list words this game's chat may keep (at most 20). */
-  chatAllow: z.array(ChatAllowWord).max(MANIFEST_LIMITS.chatAllowMax).default([]),
-});
-
-/** A normalised `game.multiplayer` block. */
-export type GameMultiplayer = z.output<typeof GameMultiplayer>;
-
-/** `game.multiplayer` for a static app: `own-server` needs a process app. */
-export const StaticGameMultiplayer = GameMultiplayer.refine((multiplayer) => multiplayer.transport !== 'own-server', {
-  message: 'own-server needs a process app; static apps use hub-rooms',
-  path: ['transport'],
-});
+/**
+ * `game.multiplayer`: the opt-in that makes a game an online invite/join
+ * target (docs/multiplayer.md §7).
+ */
+import { z } from 'zod';
+import { MANIFEST_LIMITS } from '../limits';
+import { LobbySuffix, hasUniqueKeys, playerRange, trimmedText } from './fields';
+
+/**
+ * How players connect: `hub-rooms` (the hub relays room messages) or
+ * `own-server` (a process app runs its own game server; process apps only).
+ */
+export const Transport = z.enum(['hub-rooms', 'own-server']);
+
+/** A mode key: letters, digits, `_` or `-`, 1 to 32 characters. */
+export const ModeKey = z.string().regex(/^[A-Za-z0-9_-]{1,32}$/, 'must be 1-32 letters, digits, _ or -');
+
+/** A game mode players can be invited into. */
+export const MultiplayerMode = z.strictObject({
+  /** Sent with invites and launches as `mode`. */
+  key: ModeKey,
+  /** What players see. Defaults to the key. */
+  title: trimmedText(MANIFEST_LIMITS.modeTitleMax).optional(),
+  /** `[min, max]` players for this mode, within 1..8. Defaults to the game's. */
+  players: playerRange(1).optional(),
+});
+
+/**
+ * A soften-list word this game's chat may keep (e.g. `shot` for a pool game):
+ * one lowercase word of 2 to 20 letters. Reject-list words never pass.
+ */
+export const ChatAllowWord = z.string().trim().toLowerCase().regex(/^[a-z]{2,20}$/, 'must be a single word of 2-20 letters');
+
+/** The `game.multiplayer` block. */
+export const GameMultiplayer = z.strictObject({
+  /** URL suffix invites and Join open, relative to `/<slug>/`. Default `''` (the game's root). */
+  lobby: LobbySuffix.default(''),
+  /** `[min, max]` players, within 1..8. Default `[2, 8]`. */
+  players: playerRange(1).default([2, 8]),
+  /**
+   * `hub-rooms` or `own-server`. Default: `own-server` for process apps,
+   * `hub-rooms` for static apps (which cannot use `own-server`).
+   */
+  transport: Transport.optional(),
+  /** Friends can invite each other into this game. Default `true`. */
+  invites: z.boolean().default(true),
+  /** Friends can join a game in progress. Default `true`. */
+  join: z.boolean().default(true),
+  /** Friends can watch. Default `false`. */
+  spectate: z.boolean().default(false),
+  /** Offer quick match. Default `false`. */
+  quickMatch: z.boolean().default(false),
+  /** Modes players can be invited into (at most 16, unique keys). */
+  modes: z.array(MultiplayerMode).max(MANIFEST_LIMITS.modesMax).refine(hasUniqueKeys, 'mode keys must be unique').default([]),
+  /**
+   * Extra quick-chat phrases for this game (at most 24, each at most 40
+   * characters). Checked by the content filter at boot; failing ones are dropped.
+   */
+  quickChat: z.array(trimmedText(MANIFEST_LIMITS.quickChatTextMax)).max(MANIFEST_LIMITS.quickChatMax).default([]),
+  /** Soften-list words this game's chat may keep (at most 20). */
+  chatAllow: z.array(ChatAllowWord).max(MANIFEST_LIMITS.chatAllowMax).default([]),
+});
+
+/** A normalised `game.multiplayer` block. */
+export type GameMultiplayer = z.output<typeof GameMultiplayer>;
+
+/** `game.multiplayer` for a static app: `own-server` needs a process app. */
+export const StaticGameMultiplayer = GameMultiplayer.refine((multiplayer) => multiplayer.transport !== 'own-server', {
+  message: 'own-server needs a process app; static apps use hub-rooms',
+  path: ['transport'],
+});

package/src/manifest/race.ts

@@ -1,93 +1,93 @@
-/**
- * `game.race`: the opt-in that turns a single-player game into a race target
- * (docs/multiplayer.md §14, docs/plans/race.md §5).
- */
-import { z } from 'zod';
-import { RaceKey, RaceParamValue as RaceValue } from '../api/mp/races';
-import { MANIFEST_LIMITS } from '../limits';
-import { LobbySuffix, hasUniqueKeys, playerRange, trimmedText } from './fields';
-
-/** A race param value. */
-type RaceValue = z.infer<typeof RaceValue>;
-
-const RaceTitle = trimmedText(MANIFEST_LIMITS.raceTitleMax);
-
-/** One choice of a race param: a bare value, or a value with a title. */
-export const RaceOption = z.union([
-  RaceValue,
-  z.strictObject({
-    /** The value the game receives in `r.params[key]`. */
-    value: RaceValue,
-    /** What the creator sees. Defaults to the value. Checked like quick-chat text. */
-    title: RaceTitle.optional(),
-  }),
-]);
-
-/** The value of an option, bare or titled. */
-function optionValue(option: z.output<typeof RaceOption>): RaceValue {
-  return typeof option === 'object' ? option.value : option;
-}
-
-/** A choice the race creator makes. The server only accepts declared values. */
-export const RaceParam = z
-  .strictObject({
-    /** The key the game reads, `r.params[key]`. */
-    key: RaceKey,
-    /** What the creator sees. Defaults to the key. Checked like quick-chat text. */
-    title: RaceTitle.optional(),
-    /** The choices, 1 to 12. */
-    options: z.array(RaceOption).min(1).max(MANIFEST_LIMITS.raceOptionsMax),
-    /** The preselected value; one of the options' values. Defaults to the first. */
-    default: RaceValue.optional(),
-  })
-  .refine((p) => p.default === undefined || p.options.some((option) => optionValue(option) === p.default), {
-    message: 'default must be one of the option values',
-    path: ['default'],
-  });
-
-/** How the live race HUD and the race history show a stat. */
-export const RaceStatFormat = z.enum(['int', 'percent', 'time', 'bool', 'color']);
-
-/** A value of {@link RaceStatFormat}. */
-export type RaceStatFormat = z.infer<typeof RaceStatFormat>;
-
-/** A stat the live race HUD and the race history show. */
-export const RaceStat = z.strictObject({
-  /** The key the game sends in `hub.race.status({ [key]: value })`. */
-  key: RaceKey,
-  /** The column label. Defaults to the key. Checked like quick-chat text. */
-  title: RaceTitle.optional(),
-  /** `int` (default), `percent`, `time` (ms), `bool` or `color` (`#rrggbb`). */
-  format: RaceStatFormat.default('int'),
-});
-
-/** The `game.race` object form. */
-export const RaceBlock = z.strictObject({
-  /** URL suffix race invites and Join open, relative to `/<slug>/`. Default `?race=lobby`. */
-  lobby: LobbySuffix.default('?race=lobby'),
-  /** `[min, max]` racers, within 2..8. Default `[2, 2]`. */
-  players: playerRange(2).default([2, 2]),
-  /** What the creator picks (at most 6, unique keys). */
-  params: z.array(RaceParam).max(MANIFEST_LIMITS.raceParamsMax).refine(hasUniqueKeys, 'param keys must be unique').default([]),
-  /** What the live HUD and the history show (at most 8, unique keys; the HUD shows the first 3). */
-  stats: z.array(RaceStat).max(MANIFEST_LIMITS.raceStatsMax).refine(hasUniqueKeys, 'stat keys must be unique').default([]),
-  /**
-   * The earliest a finish may count after the go, in ms (0 to 600000). A
-   * sooner finish is held until then. Default: the hub's `raceMinFinishMs`.
-   */
-  minMs: z.number().int().min(0).max(MANIFEST_LIMITS.raceMinMsMax).optional(),
-});
-
-/** A normalised `game.race` block. */
-export type RaceBlock = z.output<typeof RaceBlock>;
-
-/**
- * `game.race`: an object, `true` for all defaults (no params, no stats), or
- * `false` for off. `true` parses to the object form, `false` to `undefined`.
- */
-export const GameRace = z
-  .preprocess((v: boolean | z.input<typeof RaceBlock>) => (v === true ? {} : v === false ? undefined : v), RaceBlock.optional())
-  .optional();
-
-/** `game.race` as a game writes it. */
-export type GameRaceInput = z.input<typeof GameRace>;
+/**
+ * `game.race`: the opt-in that turns a single-player game into a race target
+ * (docs/multiplayer.md §14, docs/plans/race.md §5).
+ */
+import { z } from 'zod';
+import { RaceKey, RaceParamValue as RaceValue } from '../api/mp/races';
+import { MANIFEST_LIMITS } from '../limits';
+import { LobbySuffix, hasUniqueKeys, playerRange, trimmedText } from './fields';
+
+/** A race param value. */
+type RaceValue = z.infer<typeof RaceValue>;
+
+const RaceTitle = trimmedText(MANIFEST_LIMITS.raceTitleMax);
+
+/** One choice of a race param: a bare value, or a value with a title. */
+export const RaceOption = z.union([
+  RaceValue,
+  z.strictObject({
+    /** The value the game receives in `r.params[key]`. */
+    value: RaceValue,
+    /** What the creator sees. Defaults to the value. Checked like quick-chat text. */
+    title: RaceTitle.optional(),
+  }),
+]);
+
+/** The value of an option, bare or titled. */
+function optionValue(option: z.output<typeof RaceOption>): RaceValue {
+  return typeof option === 'object' ? option.value : option;
+}
+
+/** A choice the race creator makes. The server only accepts declared values. */
+export const RaceParam = z
+  .strictObject({
+    /** The key the game reads, `r.params[key]`. */
+    key: RaceKey,
+    /** What the creator sees. Defaults to the key. Checked like quick-chat text. */
+    title: RaceTitle.optional(),
+    /** The choices, 1 to 12. */
+    options: z.array(RaceOption).min(1).max(MANIFEST_LIMITS.raceOptionsMax),
+    /** The preselected value; one of the options' values. Defaults to the first. */
+    default: RaceValue.optional(),
+  })
+  .refine((p) => p.default === undefined || p.options.some((option) => optionValue(option) === p.default), {
+    message: 'default must be one of the option values',
+    path: ['default'],
+  });
+
+/** How the live race HUD and the race history show a stat. */
+export const RaceStatFormat = z.enum(['int', 'percent', 'time', 'bool', 'color']);
+
+/** A value of {@link RaceStatFormat}. */
+export type RaceStatFormat = z.infer<typeof RaceStatFormat>;
+
+/** A stat the live race HUD and the race history show. */
+export const RaceStat = z.strictObject({
+  /** The key the game sends in `hub.race.status({ [key]: value })`. */
+  key: RaceKey,
+  /** The column label. Defaults to the key. Checked like quick-chat text. */
+  title: RaceTitle.optional(),
+  /** `int` (default), `percent`, `time` (ms), `bool` or `color` (`#rrggbb`). */
+  format: RaceStatFormat.default('int'),
+});
+
+/** The `game.race` object form. */
+export const RaceBlock = z.strictObject({
+  /** URL suffix race invites and Join open, relative to `/<slug>/`. Default `?race=lobby`. */
+  lobby: LobbySuffix.default('?race=lobby'),
+  /** `[min, max]` racers, within 2..8. Default `[2, 2]`. */
+  players: playerRange(2).default([2, 2]),
+  /** What the creator picks (at most 6, unique keys). */
+  params: z.array(RaceParam).max(MANIFEST_LIMITS.raceParamsMax).refine(hasUniqueKeys, 'param keys must be unique').default([]),
+  /** What the live HUD and the history show (at most 8, unique keys; the HUD shows the first 3). */
+  stats: z.array(RaceStat).max(MANIFEST_LIMITS.raceStatsMax).refine(hasUniqueKeys, 'stat keys must be unique').default([]),
+  /**
+   * The earliest a finish may count after the go, in ms (0 to 600000). A
+   * sooner finish is held until then. Default: the hub's `raceMinFinishMs`.
+   */
+  minMs: z.number().int().min(0).max(MANIFEST_LIMITS.raceMinMsMax).optional(),
+});
+
+/** A normalised `game.race` block. */
+export type RaceBlock = z.output<typeof RaceBlock>;
+
+/**
+ * `game.race`: an object, `true` for all defaults (no params, no stats), or
+ * `false` for off. `true` parses to the object form, `false` to `undefined`.
+ */
+export const GameRace = z
+  .preprocess((v: boolean | z.input<typeof RaceBlock>) => (v === true ? {} : v === false ? undefined : v), RaceBlock.optional())
+  .optional();
+
+/** `game.race` as a game writes it. */
+export type GameRaceInput = z.input<typeof GameRace>;

package/src/middleware.ts

@@ -1,47 +1,47 @@
-/**
- * Middleware **defs** for the public API (plan §6.1). A def is a contract
- * only: a name, the context it provides and its dependencies. It holds no
- * code, so it is safe in a published package; the server binds the real
- * implementation. Each endpoint's guards are part of its declaration, which
- * lets tests check rules such as "every social endpoint requires an active
- * account" (plan §10.3).
- */
-import { ctx, middleware } from '@ayepi/core';
-import { Slug } from './common';
-import type { SessionUser } from './entities';
-
-/**
- * Resolves the `hub_session` cookie (the user, or `null`) and the anonymous
- * `hub_cid` client id. Every endpoint has it.
- */
-export const session = middleware('session', {
-  provides: ctx<{ user: SessionUser | null; clientId: string }>(),
-  doc: { security: { cookieAuth: { type: 'apiKey', in: 'cookie', name: 'hub_session' } } },
-});
-
-/** Signed in, as a guest or an account. Otherwise 401 `signed_out`. */
-export const requireUser = middleware('requireUser', {
-  provides: ctx<{ user: SessionUser }>(),
-  requires: [session],
-});
-
-/**
- * Signed in and not suspended. Otherwise 401 `signed_out` or 403
- * `suspended`. Every social, multiplayer, race and trade endpoint has it.
- */
-export const requireActive = middleware('requireActive', {
-  provides: ctx<{ user: SessionUser }>(),
-  requires: [requireUser],
-});
-
-/** Active and a claimed account (not a guest). Otherwise 403 `claim_required`. */
-export const requireClaimed = middleware('requireClaimed', {
-  provides: ctx<{ user: SessionUser }>(),
-  requires: [requireActive],
-});
-
-/**
- * Owns the `:slug` path segment and checks it names a known game.
- * Otherwise 404 "No such game".
- */
-export const game = middleware.loader('slug', Slug, { requires: [session] });
+/**
+ * Middleware **defs** for the public API (plan §6.1). A def is a contract
+ * only: a name, the context it provides and its dependencies. It holds no
+ * code, so it is safe in a published package; the server binds the real
+ * implementation. Each endpoint's guards are part of its declaration, which
+ * lets tests check rules such as "every social endpoint requires an active
+ * account" (plan §10.3).
+ */
+import { ctx, middleware } from '@ayepi/core';
+import { Slug } from './common';
+import type { SessionUser } from './entities';
+
+/**
+ * Resolves the `hub_session` cookie (the user, or `null`) and the anonymous
+ * `hub_cid` client id. Every endpoint has it.
+ */
+export const session = middleware('session', {
+  provides: ctx<{ user: SessionUser | null; clientId: string }>(),
+  doc: { security: { cookieAuth: { type: 'apiKey', in: 'cookie', name: 'hub_session' } } },
+});
+
+/** Signed in, as a guest or an account. Otherwise 401 `signed_out`. */
+export const requireUser = middleware('requireUser', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [session],
+});
+
+/**
+ * Signed in and not suspended. Otherwise 401 `signed_out` or 403
+ * `suspended`. Every social, multiplayer, race and trade endpoint has it.
+ */
+export const requireActive = middleware('requireActive', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [requireUser],
+});
+
+/** Active and a claimed account (not a guest). Otherwise 403 `claim_required`. */
+export const requireClaimed = middleware('requireClaimed', {
+  provides: ctx<{ user: SessionUser }>(),
+  requires: [requireActive],
+});
+
+/**
+ * Owns the `:slug` path segment and checks it names a known game.
+ * Otherwise 404 "No such game".
+ */
+export const game = middleware.loader('slug', Slug, { requires: [session] });

package/src/realtime/define.ts

@@ -1,52 +1,52 @@
-/**
- * Definers for socket ops and events (plan §5.2). One declaration per op or
- * event feeds the server (validation), the runtime and test clients (types)
- * and the generated op/event tables.
- */
-import type { z } from 'zod';
-import type { ErrorCode } from '../errors';
-
-/** A client → server op on `/_ws`: its input, its ack and the codes it can fail with. */
-export interface OpDef<D extends z.ZodType = z.ZodType, A extends z.ZodType = z.ZodType> {
-  /** The op's input (`d` in `{t:'op', id, op, d}`). */
-  readonly d: D;
-  /** The success ack's payload (`d` in `{t:'ack', ok:true, d}`). */
-  readonly ack: A;
-  /** Error codes this op can fail with, beyond the envelope's own (see `ENVELOPE_ERRORS`). */
-  readonly errors: readonly ErrorCode[];
-  /**
-   * The refusal a malformed `d` gets (status 400), when the hub names it
-   * (`bad_stats`, `bad_patch`). Without it the refusal is `bad_request`
-   * with the first validation message.
-   */
-  readonly invalid?: { readonly code: ErrorCode; readonly error: string };
-  /** One line for the generated op table. */
-  readonly doc: string;
-}
-
-/** A server → client event on `/_ws`. */
-export interface EventDef<D extends z.ZodType = z.ZodType> {
-  /** The payload (`d` in `{t:'ev', ev, d}`). */
-  readonly d: D;
-  /** One line for the generated event table. */
-  readonly doc: string;
-}
-
-/** Declare an op (identity at runtime; keeps the literal types). */
-export function op<const D extends z.ZodType, const A extends z.ZodType>(def: OpDef<D, A>): OpDef<D, A> {
-  return def;
-}
-
-/** Declare an event (identity at runtime; keeps the literal types). */
-export function event<const D extends z.ZodType>(def: EventDef<D>): EventDef<D> {
-  return def;
-}
-
-/** The input type of an op. */
-export type OpInput<O extends OpDef> = z.input<O['d']>;
-
-/** The ack payload type of an op. */
-export type OpAck<O extends OpDef> = z.output<O['ack']>;
-
-/** The payload type of an event. */
-export type EventData<E extends EventDef> = z.output<E['d']>;
+/**
+ * Definers for socket ops and events (plan §5.2). One declaration per op or
+ * event feeds the server (validation), the runtime and test clients (types)
+ * and the generated op/event tables.
+ */
+import type { z } from 'zod';
+import type { ErrorCode } from '../errors';
+
+/** A client → server op on `/_ws`: its input, its ack and the codes it can fail with. */
+export interface OpDef<D extends z.ZodType = z.ZodType, A extends z.ZodType = z.ZodType> {
+  /** The op's input (`d` in `{t:'op', id, op, d}`). */
+  readonly d: D;
+  /** The success ack's payload (`d` in `{t:'ack', ok:true, d}`). */
+  readonly ack: A;
+  /** Error codes this op can fail with, beyond the envelope's own (see `ENVELOPE_ERRORS`). */
+  readonly errors: readonly ErrorCode[];
+  /**
+   * The refusal a malformed `d` gets (status 400), when the hub names it
+   * (`bad_stats`, `bad_patch`). Without it the refusal is `bad_request`
+   * with the first validation message.
+   */
+  readonly invalid?: { readonly code: ErrorCode; readonly error: string };
+  /** One line for the generated op table. */
+  readonly doc: string;
+}
+
+/** A server → client event on `/_ws`. */
+export interface EventDef<D extends z.ZodType = z.ZodType> {
+  /** The payload (`d` in `{t:'ev', ev, d}`). */
+  readonly d: D;
+  /** One line for the generated event table. */
+  readonly doc: string;
+}
+
+/** Declare an op (identity at runtime; keeps the literal types). */
+export function op<const D extends z.ZodType, const A extends z.ZodType>(def: OpDef<D, A>): OpDef<D, A> {
+  return def;
+}
+
+/** Declare an event (identity at runtime; keeps the literal types). */
+export function event<const D extends z.ZodType>(def: EventDef<D>): EventDef<D> {
+  return def;
+}
+
+/** The input type of an op. */
+export type OpInput<O extends OpDef> = z.input<O['d']>;
+
+/** The ack payload type of an op. */
+export type OpAck<O extends OpDef> = z.output<O['ack']>;
+
+/** The payload type of an event. */
+export type EventData<E extends EventDef> = z.output<E['d']>;