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

package/src/api/progress/game-data.ts

@@ -1,189 +1,189 @@
-/**
- * The caller's own per-game data: profile, save slots, numeric stats, and
- * resetting a game. Guests count: a guest is a real account row.
- */
-import { use } from '@ayepi/core';
-import { z } from 'zod';
-import { Json, Key, Millis, Ok, Slug } from '../../common';
-import { ContentRejected, ErrorBody } from '../../errors';
-import { game, requireUser, session } from '../../middleware';
-import { LooseText, requiredText } from '../../coerce';
-
-/** A player's profile in one game. */
-export const Profile = z.object({
-  game: Slug,
-  /** Shown to other players; `null` when never set. */
-  displayName: z.string().nullable(),
-  /** Any JSON the game stores (`{}` by default). */
-  data: Json,
-  /** Epoch ms. */
-  updatedAt: Millis,
-});
-
-/** A game profile. */
-export type Profile = z.infer<typeof Profile>;
-
-/** A save slot's metadata (no payload). */
-export const SaveMeta = z.object({
-  slot: Key,
-  label: z.string().nullable(),
-  /** Epoch ms. */
-  updatedAt: Millis,
-});
-
-/** A save slot's metadata. */
-export type SaveMeta = z.infer<typeof SaveMeta>;
-
-/** A save slot with its payload. */
-export const Save = SaveMeta.extend({
-  /** The stored JSON (`null` if it could not be read back). */
-  data: Json,
-});
-
-/** A save slot. */
-export type Save = z.infer<typeof Save>;
-
-/** A player's numeric stats in one game: stat {@link Key} to value. */
-export const Stats = z.record(Key, z.number());
-
-/** A player's stats. */
-export type Stats = z.infer<typeof Stats>;
-
-/** How a stat update combines with the stored value. */
-export const StatMode = z.enum(['set', 'incr', 'max']);
-
-/** A stat update mode. */
-export type StatMode = z.infer<typeof StatMode>;
-
-/**
- * A {@link Key} read like the hub's `validKey` (`String(x || '')`), failing
- * with its message: "<label> must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars)."
- */
-function keyField(label: string) {
-  const message = `${label} must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars).`;
-  return requiredText(message).refine((text) => Key.safeParse(text).success, message);
-}
-
-/** A number read like the hub's `finiteNumber` (`Number(x)`), failing with "<label> must be a finite number.". */
-function finiteNumberField(label: string) {
-  return z.coerce.number<number>({ error: `${label} must be a finite number.` });
-}
-
-/**
- * A stat update's mode. The hub reads `body.mode || 'set'`, so a falsy value
- * (`null`, `''`, `0`, `false`) also means `set`. Clients should send a
- * {@link StatMode} or nothing.
- */
-const StatModeField = z
-  .union([StatMode, z.literal(['', 0, false]), z.null()], { error: 'mode must be set, incr, or max.' })
-  .optional()
-  .transform((mode) => mode || 'set');
-
-/**
- * A save's payload: any JSON, but present. (The union with `never` exists only
- * so a missing value fails with the hub's message rather than zod's.)
- */
-const SaveData = z.union([Json, z.never()], { error: 'Missing "data".' });
-
-/** `:slot` of a save. */
-const SlotParams = z.object({ slot: keyField('slot') });
-
-/** The per-game data endpoints. */
-export const gameDataEndpoints = {
-  ...use(session, game).path('/games/:slug').group({
-    /**
-     * A player's stats. Defaults to the caller's own (401 when signed out);
-     * `?user=<id>` reads anyone's, since stats are public like a profile.
-     */
-    getGameStats: {
-      method: 'GET', path: '/stats',
-      query: z.object({
-        /** Whose stats to read (a user id); omit for the caller's. */
-        user: finiteNumberField('user').optional(),
-      }),
-      response: z.object({ stats: Stats }),
-      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: "A player's stats in this game", tags: ['progress'] },
-    },
-  }),
-  ...use(requireUser, game).path('/games/:slug').group({
-    getGameProfile: {
-      method: 'GET', path: '/profile',
-      response: z.object({ profile: Profile.nullable() }),
-      errors: { 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: "The caller's profile in this game, or null", tags: ['progress'] },
-    },
-    /**
-     * Create or replace the caller's profile. A new or changed display name
-     * is moderated (422) because other players see it.
-     */
-    setGameProfile: {
-      method: 'PUT', path: '/profile',
-      body: z.object({
-        /** Up to 60 characters (longer is clipped); `null` or missing clears it. */
-        displayName: LooseText.nullish(),
-        /** Replaces the stored data; missing stores `{}`. */
-        data: Json.optional(),
-      }),
-      response: z.object({ profile: Profile }),
-      errors: { 401: ErrorBody, 404: ErrorBody, 422: ContentRejected },
-      doc: { summary: "Create or replace the caller's profile in this game", tags: ['progress'] },
-    },
-    listSaves: {
-      method: 'GET', path: '/saves',
-      response: z.object({ saves: z.array(SaveMeta) }),
-      errors: { 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: "The caller's save slots, newest first (no payloads)", tags: ['progress'] },
-    },
-    getSave: {
-      method: 'GET', path: '/saves/:slot', params: SlotParams,
-      response: z.object({ save: Save.nullable() }),
-      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'One save slot, or null when empty', tags: ['progress'] },
-    },
-    writeSave: {
-      method: 'PUT', path: '/saves/:slot', params: SlotParams,
-      body: z.object({
-        /** Any JSON up to 64 KB serialized (`HUB_MAX_SAVE_BYTES`); 413 over. */
-        data: SaveData,
-        /** Up to 80 characters (longer is clipped). */
-        label: LooseText.nullish(),
-      }),
-      response: z.object({
-        ok: z.literal(true),
-        /** Epoch ms. */
-        updatedAt: Millis,
-      }),
-      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody, 413: ErrorBody },
-      doc: { summary: 'Create or overwrite a save slot', tags: ['progress'] },
-    },
-    deleteSave: {
-      method: 'DELETE', path: '/saves/:slot', params: SlotParams, response: Ok,
-      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Delete a save slot (idempotent)', tags: ['progress'] },
-    },
-    /** Update one stat. Backs the client's `setStat`, `incrStat` and `maxStat`. */
-    updateGameStat: {
-      method: 'POST', path: '/stats',
-      body: z.object({
-        key: keyField('key'),
-        value: finiteNumberField('value'),
-        /** Default `set`. */
-        mode: StatModeField,
-      }),
-      response: z.object({ key: Key, value: z.number() }),
-      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Set, add to, or raise one stat; returns its new value', tags: ['progress'] },
-    },
-    /**
-     * Wipe the caller's saves, stats, inventory and coins in this game.
-     * Pending trades are closed first, refunding other players' escrow.
-     * Leaderboard entries and the profile are kept.
-     */
-    resetMyGameProgress: {
-      method: 'POST', path: '/reset', response: Ok,
-      errors: { 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: "Reset the caller's progress in this game", tags: ['progress'] },
-    },
-  }),
-};
+/**
+ * The caller's own per-game data: profile, save slots, numeric stats, and
+ * resetting a game. Guests count: a guest is a real account row.
+ */
+import { use } from '@ayepi/core';
+import { z } from 'zod';
+import { Json, Key, Millis, Ok, Slug } from '../../common';
+import { ContentRejected, ErrorBody } from '../../errors';
+import { game, requireUser, session } from '../../middleware';
+import { LooseText, requiredText } from '../../coerce';
+
+/** A player's profile in one game. */
+export const Profile = z.object({
+  game: Slug,
+  /** Shown to other players; `null` when never set. */
+  displayName: z.string().nullable(),
+  /** Any JSON the game stores (`{}` by default). */
+  data: Json,
+  /** Epoch ms. */
+  updatedAt: Millis,
+});
+
+/** A game profile. */
+export type Profile = z.infer<typeof Profile>;
+
+/** A save slot's metadata (no payload). */
+export const SaveMeta = z.object({
+  slot: Key,
+  label: z.string().nullable(),
+  /** Epoch ms. */
+  updatedAt: Millis,
+});
+
+/** A save slot's metadata. */
+export type SaveMeta = z.infer<typeof SaveMeta>;
+
+/** A save slot with its payload. */
+export const Save = SaveMeta.extend({
+  /** The stored JSON (`null` if it could not be read back). */
+  data: Json,
+});
+
+/** A save slot. */
+export type Save = z.infer<typeof Save>;
+
+/** A player's numeric stats in one game: stat {@link Key} to value. */
+export const Stats = z.record(Key, z.number());
+
+/** A player's stats. */
+export type Stats = z.infer<typeof Stats>;
+
+/** How a stat update combines with the stored value. */
+export const StatMode = z.enum(['set', 'incr', 'max']);
+
+/** A stat update mode. */
+export type StatMode = z.infer<typeof StatMode>;
+
+/**
+ * A {@link Key} read like the hub's `validKey` (`String(x || '')`), failing
+ * with its message: "<label> must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars)."
+ */
+function keyField(label: string) {
+  const message = `${label} must match /^[A-Za-z0-9_.:-]{1,64}$/ (1–64 chars).`;
+  return requiredText(message).refine((text) => Key.safeParse(text).success, message);
+}
+
+/** A number read like the hub's `finiteNumber` (`Number(x)`), failing with "<label> must be a finite number.". */
+function finiteNumberField(label: string) {
+  return z.coerce.number<number>({ error: `${label} must be a finite number.` });
+}
+
+/**
+ * A stat update's mode. The hub reads `body.mode || 'set'`, so a falsy value
+ * (`null`, `''`, `0`, `false`) also means `set`. Clients should send a
+ * {@link StatMode} or nothing.
+ */
+const StatModeField = z
+  .union([StatMode, z.literal(['', 0, false]), z.null()], { error: 'mode must be set, incr, or max.' })
+  .optional()
+  .transform((mode) => mode || 'set');
+
+/**
+ * A save's payload: any JSON, but present. (The union with `never` exists only
+ * so a missing value fails with the hub's message rather than zod's.)
+ */
+const SaveData = z.union([Json, z.never()], { error: 'Missing "data".' });
+
+/** `:slot` of a save. */
+const SlotParams = z.object({ slot: keyField('slot') });
+
+/** The per-game data endpoints. */
+export const gameDataEndpoints = {
+  ...use(session, game).path('/games/:slug').group({
+    /**
+     * A player's stats. Defaults to the caller's own (401 when signed out);
+     * `?user=<id>` reads anyone's, since stats are public like a profile.
+     */
+    getGameStats: {
+      method: 'GET', path: '/stats',
+      query: z.object({
+        /** Whose stats to read (a user id); omit for the caller's. */
+        user: finiteNumberField('user').optional(),
+      }),
+      response: z.object({ stats: Stats }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "A player's stats in this game", tags: ['progress'] },
+    },
+  }),
+  ...use(requireUser, game).path('/games/:slug').group({
+    getGameProfile: {
+      method: 'GET', path: '/profile',
+      response: z.object({ profile: Profile.nullable() }),
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "The caller's profile in this game, or null", tags: ['progress'] },
+    },
+    /**
+     * Create or replace the caller's profile. A new or changed display name
+     * is moderated (422) because other players see it.
+     */
+    setGameProfile: {
+      method: 'PUT', path: '/profile',
+      body: z.object({
+        /** Up to 60 characters (longer is clipped); `null` or missing clears it. */
+        displayName: LooseText.nullish(),
+        /** Replaces the stored data; missing stores `{}`. */
+        data: Json.optional(),
+      }),
+      response: z.object({ profile: Profile }),
+      errors: { 401: ErrorBody, 404: ErrorBody, 422: ContentRejected },
+      doc: { summary: "Create or replace the caller's profile in this game", tags: ['progress'] },
+    },
+    listSaves: {
+      method: 'GET', path: '/saves',
+      response: z.object({ saves: z.array(SaveMeta) }),
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "The caller's save slots, newest first (no payloads)", tags: ['progress'] },
+    },
+    getSave: {
+      method: 'GET', path: '/saves/:slot', params: SlotParams,
+      response: z.object({ save: Save.nullable() }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'One save slot, or null when empty', tags: ['progress'] },
+    },
+    writeSave: {
+      method: 'PUT', path: '/saves/:slot', params: SlotParams,
+      body: z.object({
+        /** Any JSON up to 64 KB serialized (`HUB_MAX_SAVE_BYTES`); 413 over. */
+        data: SaveData,
+        /** Up to 80 characters (longer is clipped). */
+        label: LooseText.nullish(),
+      }),
+      response: z.object({
+        ok: z.literal(true),
+        /** Epoch ms. */
+        updatedAt: Millis,
+      }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody, 413: ErrorBody },
+      doc: { summary: 'Create or overwrite a save slot', tags: ['progress'] },
+    },
+    deleteSave: {
+      method: 'DELETE', path: '/saves/:slot', params: SlotParams, response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Delete a save slot (idempotent)', tags: ['progress'] },
+    },
+    /** Update one stat. Backs the client's `setStat`, `incrStat` and `maxStat`. */
+    updateGameStat: {
+      method: 'POST', path: '/stats',
+      body: z.object({
+        key: keyField('key'),
+        value: finiteNumberField('value'),
+        /** Default `set`. */
+        mode: StatModeField,
+      }),
+      response: z.object({ key: Key, value: z.number() }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Set, add to, or raise one stat; returns its new value', tags: ['progress'] },
+    },
+    /**
+     * Wipe the caller's saves, stats, inventory and coins in this game.
+     * Pending trades are closed first, refunding other players' escrow.
+     * Leaderboard entries and the profile are kept.
+     */
+    resetMyGameProgress: {
+      method: 'POST', path: '/reset', response: Ok,
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Reset the caller's progress in this game", tags: ['progress'] },
+    },
+  }),
+};

package/src/api/progress.ts

@@ -1,59 +1,59 @@
-/**
- * Per-game player data: profiles, saves, stats, game reset, and the player's
- * records and snapshot. The per-game endpoints live in `progress/game-data.ts`.
- */
-import { z } from 'zod';
-import { Slug } from '../common';
-import { SessionUser } from '../entities';
-import { session } from '../middleware';
-import { Inventory } from './economy/bundle';
-import { GameLeaderboards, GameRecords, TopQuery } from './leaderboards';
-import { gameDataEndpoints, Profile, Save, Stats } from './progress/game-data';
-
-export { Profile, Save, SaveMeta, StatMode, Stats } from './progress/game-data';
-
-/** Everything the caller has in one game, as the snapshot carries it. */
-export const GameSnapshot = z.object({
-  profile: Profile.nullable(),
-  /** Newest first, with payloads. */
-  saves: z.array(Save),
-  stats: Stats,
-  inventory: Inventory,
-});
-
-/** One game's slice of the snapshot. */
-export type GameSnapshot = z.infer<typeof GameSnapshot>;
-
-/** The progress endpoints. */
-export const progressEndpoints = {
-  ...gameDataEndpoints,
-  ...session.group({
-    /**
-     * The caller's leaderboard standings, grouped by game (empty when
-     * signed out). `?game=` limits it to one game; empty means every game,
-     * and text that is no game's slug matches nothing, as in the old hub.
-     */
-    listMyLeaderboardRecords: {
-      method: 'GET', path: '/me/records',
-      query: z.object({ game: z.string().optional() }),
-      response: z.object({ games: z.array(GameRecords) }),
-      doc: { summary: "The caller's leaderboard standings", tags: ['progress'] },
-    },
-    /**
-     * Everything the caller has, in one request, to warm the offline cache
-     * for every game (the client's `prefetchAll`). Signed out, only the
-     * global boards are filled in.
-     */
-    getMyOfflineSnapshot: {
-      method: 'GET', path: '/me/snapshot', query: TopQuery,
-      response: z.object({
-        user: SessionUser.nullable(),
-        /** By slug: every game the caller has any profile, save, stat or holding in. */
-        games: z.record(Slug, GameSnapshot),
-        records: z.array(GameRecords),
-        leaderboards: z.array(GameLeaderboards),
-      }),
-      doc: { summary: "The caller's data across every game, plus the global boards", tags: ['progress'] },
-    },
-  }),
-};
+/**
+ * Per-game player data: profiles, saves, stats, game reset, and the player's
+ * records and snapshot. The per-game endpoints live in `progress/game-data.ts`.
+ */
+import { z } from 'zod';
+import { Slug } from '../common';
+import { SessionUser } from '../entities';
+import { session } from '../middleware';
+import { Inventory } from './economy/bundle';
+import { GameLeaderboards, GameRecords, TopQuery } from './leaderboards';
+import { gameDataEndpoints, Profile, Save, Stats } from './progress/game-data';
+
+export { Profile, Save, SaveMeta, StatMode, Stats } from './progress/game-data';
+
+/** Everything the caller has in one game, as the snapshot carries it. */
+export const GameSnapshot = z.object({
+  profile: Profile.nullable(),
+  /** Newest first, with payloads. */
+  saves: z.array(Save),
+  stats: Stats,
+  inventory: Inventory,
+});
+
+/** One game's slice of the snapshot. */
+export type GameSnapshot = z.infer<typeof GameSnapshot>;
+
+/** The progress endpoints. */
+export const progressEndpoints = {
+  ...gameDataEndpoints,
+  ...session.group({
+    /**
+     * The caller's leaderboard standings, grouped by game (empty when
+     * signed out). `?game=` limits it to one game; empty means every game,
+     * and text that is no game's slug matches nothing, as in the old hub.
+     */
+    listMyLeaderboardRecords: {
+      method: 'GET', path: '/me/records',
+      query: z.object({ game: z.string().optional() }),
+      response: z.object({ games: z.array(GameRecords) }),
+      doc: { summary: "The caller's leaderboard standings", tags: ['progress'] },
+    },
+    /**
+     * Everything the caller has, in one request, to warm the offline cache
+     * for every game (the client's `prefetchAll`). Signed out, only the
+     * global boards are filled in.
+     */
+    getMyOfflineSnapshot: {
+      method: 'GET', path: '/me/snapshot', query: TopQuery,
+      response: z.object({
+        user: SessionUser.nullable(),
+        /** By slug: every game the caller has any profile, save, stat or holding in. */
+        games: z.record(Slug, GameSnapshot),
+        records: z.array(GameRecords),
+        leaderboards: z.array(GameLeaderboards),
+      }),
+      doc: { summary: "The caller's data across every game, plus the global boards", tags: ['progress'] },
+    },
+  }),
+};

package/src/api/race.ts

@@ -1,47 +1,47 @@
-/**
- * Races: the signed-in player's own race history (docs/plans/race.md §7).
- * The live race runs over the socket (`race.*` ops and events).
- */
-import { z } from 'zod';
-import { ErrorBody } from '../errors';
-import { requireActive } from '../middleware';
-import { RaceRecord } from './mp/races';
-
-/** An optional positive-integer query param; empty means "not set". */
-const OptionalCount = z.union([z.literal(''), z.coerce.number().int().positive()]).optional();
-
-/** `GET /race/history` filters. */
-export const RaceHistoryQuery = z.object({
-  /** Only this game (default: every game). */
-  game: z.union([z.literal(''), z.string().regex(/^[A-Za-z0-9_-]{1,64}$/)]).optional(),
-  /** Only races with this player (a user id). */
-  with: OptionalCount,
-  /** Only races older than this race id (paging). */
-  before: OptionalCount,
-  /** Page size, 1 to 50 (default 20; larger values are capped). */
-  limit: OptionalCount,
-});
-
-/** A page of the player's races, newest first. */
-export const RaceHistory = z.object({
-  races: z.array(RaceRecord),
-  /** More races exist before the last one. */
-  more: z.boolean(),
-  /** Totals over every race matching the filters (not just this page). */
-  summary: z.object({
-    races: z.number().int().nonnegative(),
-    wins: z.number().int().nonnegative(),
-    losses: z.number().int().nonnegative(),
-  }),
-});
-
-/** The race endpoints. */
-export const raceEndpoints = {
-  ...requireActive.group({
-    listMyRaceHistory: {
-      method: 'GET', path: '/race/history', query: RaceHistoryQuery, response: RaceHistory,
-      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
-      doc: { summary: "The signed-in player's decided races, newest first", tags: ['race'] },
-    },
-  }),
-};
+/**
+ * Races: the signed-in player's own race history (docs/plans/race.md §7).
+ * The live race runs over the socket (`race.*` ops and events).
+ */
+import { z } from 'zod';
+import { ErrorBody } from '../errors';
+import { requireActive } from '../middleware';
+import { RaceRecord } from './mp/races';
+
+/** An optional positive-integer query param; empty means "not set". */
+const OptionalCount = z.union([z.literal(''), z.coerce.number().int().positive()]).optional();
+
+/** `GET /race/history` filters. */
+export const RaceHistoryQuery = z.object({
+  /** Only this game (default: every game). */
+  game: z.union([z.literal(''), z.string().regex(/^[A-Za-z0-9_-]{1,64}$/)]).optional(),
+  /** Only races with this player (a user id). */
+  with: OptionalCount,
+  /** Only races older than this race id (paging). */
+  before: OptionalCount,
+  /** Page size, 1 to 50 (default 20; larger values are capped). */
+  limit: OptionalCount,
+});
+
+/** A page of the player's races, newest first. */
+export const RaceHistory = z.object({
+  races: z.array(RaceRecord),
+  /** More races exist before the last one. */
+  more: z.boolean(),
+  /** Totals over every race matching the filters (not just this page). */
+  summary: z.object({
+    races: z.number().int().nonnegative(),
+    wins: z.number().int().nonnegative(),
+    losses: z.number().int().nonnegative(),
+  }),
+});
+
+/** The race endpoints. */
+export const raceEndpoints = {
+  ...requireActive.group({
+    listMyRaceHistory: {
+      method: 'GET', path: '/race/history', query: RaceHistoryQuery, response: RaceHistory,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: "The signed-in player's decided races, newest first", tags: ['race'] },
+    },
+  }),
+};