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

package/src/api/catalog.ts

@@ -1,171 +1,171 @@
-/**
- * The game catalog, favorites and What's new notes.
- */
-import { z } from 'zod';
-import { Millis, Slug } from '../common';
-import { ErrorBody } from '../errors';
-import { requireUser, session } from '../middleware';
-import { RaceStatFormat } from '../manifest/race';
-import { RaceParamValue } from './mp/races';
-import { LooseNumber, LooseText, Truthy } from '../coerce';
-
-/** A `[min, max]` player count, each 1 to 8. */
-export const PlayerRange = z.tuple([z.number().int().min(1).max(8), z.number().int().min(1).max(8)]);
-
-/**
- * What the menu needs to know about an online game (invite picker, Join and
- * Watch buttons, the catalog's Online tag), not the full manifest.
- */
-export const MultiplayerSummary = z.object({
-  /** `own-server` only for process apps that run their own game server. */
-  transport: z.enum(['hub-rooms', 'own-server']),
-  players: PlayerRange,
-  invites: z.boolean(),
-  join: z.boolean(),
-  spectate: z.boolean(),
-  modes: z.array(z.object({ key: z.string(), title: z.string() })),
-  /** Present (and `true`) when the block was made for a race-only game. */
-  raceOnly: z.literal(true).optional(),
-});
-
-/** An online game's capabilities. */
-export type MultiplayerSummary = z.infer<typeof MultiplayerSummary>;
-
-/** A race game's manifest summary (players, the creator's param choices, the stats the HUD shows). */
-export const RaceSummary = z.object({
-  /** Each 2 to 8. */
-  players: PlayerRange,
-  /** Up to 6 choices the race creator picks. */
-  params: z.array(z.object({
-    key: z.string(),
-    title: z.string(),
-    /** Up to 12. */
-    options: z.array(z.object({ value: RaceParamValue, title: z.string() })),
-    /** One of the options' values. */
-    default: RaceParamValue,
-  })),
-  /** Up to 8 stats the race HUD and history show. */
-  stats: z.array(z.object({
-    key: z.string(),
-    title: z.string(),
-    format: RaceStatFormat,
-  })),
-});
-
-/** A race game's manifest summary. */
-export type RaceSummary = z.infer<typeof RaceSummary>;
-
-/** A listed game, as the menu's game list and the catalog show it. Broken apps are left out. */
-export const GameInfo = z.object({
-  slug: Slug,
-  title: z.string(),
-  /** Its URL path, e.g. `/duel`. */
-  path: z.string(),
-  /** `process` apps run their own server behind the host. */
-  kind: z.enum(['static', 'process']),
-  hasImage: z.boolean(),
-  /** `false` when the game opted out of the injected hub menu. */
-  hubEnabled: z.boolean(),
-  /** `null` for single-player games. */
-  multiplayer: MultiplayerSummary.nullable(),
-  /** `null` unless the game supports races. */
-  race: RaceSummary.nullable(),
-});
-
-/** A listed game. */
-export type GameInfo = z.infer<typeof GameInfo>;
-
-/** `{ games }`: the caller's starred slugs, oldest star first. */
-const Favorites = z.object({ games: z.array(Slug) });
-
-/** One What's new note. */
-export const ChangeNote = z.object({
-  id: z.number().int().positive(),
-  /** The game's slug, or `_hub` for the site's own notes. */
-  game: Slug,
-  /** The game's title, or `diffenderfer.games` for the site's own notes. */
-  title: z.string(),
-  text: z.string(),
-  /** When the note went live (the deploy that first saw it), epoch ms. */
-  at: Millis,
-  /** Not yet seen by this player (or since `?since=` when signed out). */
-  new: z.boolean(),
-});
-
-/** A What's new note. */
-export type ChangeNote = z.infer<typeof ChangeNote>;
-
-/** The catalog endpoints. */
-export const catalogEndpoints = {
-  ...session.group({
-    listGames: {
-      method: 'GET', path: '/games',
-      response: z.object({ games: z.array(GameInfo) }),
-      doc: { summary: 'The game catalog, sorted by title', tags: ['catalog'] },
-    },
-    /**
-     * Notes from the last 30 days, newest first (at most 6 per game and 30
-     * in all). In a game, `?game=` limits them to that game's and the site's.
-     */
-    listWhatsNewNotes: {
-      method: 'GET', path: '/changes',
-      query: z.object({
-        /** A game's slug. Empty means everything; an unknown one lists only the site's notes. */
-        game: z.string().optional(),
-        /**
-         * Signed out only: the device's last-cleared time (epoch ms); without
-         * it (or when it isn't a number) nothing is new.
-         */
-        since: z.preprocess((value: number | string | undefined) => (value === '' ? undefined : value), LooseNumber.optional()).catch(undefined),
-      }),
-      response: z.object({
-        items: z.array(ChangeNote),
-        /** How many of `items` are new. */
-        unseen: z.number().int().nonnegative(),
-        signedIn: z.boolean(),
-      }),
-      doc: { summary: "What's new: recent change notes", tags: ['catalog'] },
-    },
-  }),
-  ...requireUser.group({
-    listFavoriteGames: {
-      method: 'GET', path: '/favorites', response: Favorites,
-      errors: { 401: ErrorBody },
-      doc: { summary: "The caller's starred games", tags: ['catalog'] },
-    },
-    /**
-     * Star or unstar a game (idempotent). Starring needs a known game (404);
-     * unstarring any slug succeeds.
-     */
-    setGameFavorite: {
-      method: 'PUT', path: '/favorites/:slug',
-      params: z.object({ slug: Slug }),
-      body: z.object({
-        /** `true` stars, `false` (or missing) unstars. */
-        on: Truthy.optional(),
-      }),
-      response: Favorites,
-      errors: { 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Star or unstar a game', tags: ['catalog'] },
-    },
-    /**
-     * Mark notes seen now. With `game`: that game's and the site's. With
-     * `all` (or neither): everything.
-     */
-    markWhatsNewSeen: {
-      method: 'POST', path: '/changes/seen',
-      body: z.object({
-        /** A game's slug, read as text; an unknown one is a 404. Ignored with `all`. */
-        game: LooseText.nullish(),
-        all: Truthy.optional(),
-      }),
-      response: z.object({
-        ok: z.literal(true),
-        /** The seen mark stored, epoch ms. */
-        seenAt: Millis,
-      }),
-      errors: { 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: "Mark What's new notes seen", tags: ['catalog'] },
-    },
-  }),
-};
+/**
+ * The game catalog, favorites and What's new notes.
+ */
+import { z } from 'zod';
+import { Millis, Slug } from '../common';
+import { ErrorBody } from '../errors';
+import { requireUser, session } from '../middleware';
+import { RaceStatFormat } from '../manifest/race';
+import { RaceParamValue } from './mp/races';
+import { LooseNumber, LooseText, Truthy } from '../coerce';
+
+/** A `[min, max]` player count, each 1 to 8. */
+export const PlayerRange = z.tuple([z.number().int().min(1).max(8), z.number().int().min(1).max(8)]);
+
+/**
+ * What the menu needs to know about an online game (invite picker, Join and
+ * Watch buttons, the catalog's Online tag), not the full manifest.
+ */
+export const MultiplayerSummary = z.object({
+  /** `own-server` only for process apps that run their own game server. */
+  transport: z.enum(['hub-rooms', 'own-server']),
+  players: PlayerRange,
+  invites: z.boolean(),
+  join: z.boolean(),
+  spectate: z.boolean(),
+  modes: z.array(z.object({ key: z.string(), title: z.string() })),
+  /** Present (and `true`) when the block was made for a race-only game. */
+  raceOnly: z.literal(true).optional(),
+});
+
+/** An online game's capabilities. */
+export type MultiplayerSummary = z.infer<typeof MultiplayerSummary>;
+
+/** A race game's manifest summary (players, the creator's param choices, the stats the HUD shows). */
+export const RaceSummary = z.object({
+  /** Each 2 to 8. */
+  players: PlayerRange,
+  /** Up to 6 choices the race creator picks. */
+  params: z.array(z.object({
+    key: z.string(),
+    title: z.string(),
+    /** Up to 12. */
+    options: z.array(z.object({ value: RaceParamValue, title: z.string() })),
+    /** One of the options' values. */
+    default: RaceParamValue,
+  })),
+  /** Up to 8 stats the race HUD and history show. */
+  stats: z.array(z.object({
+    key: z.string(),
+    title: z.string(),
+    format: RaceStatFormat,
+  })),
+});
+
+/** A race game's manifest summary. */
+export type RaceSummary = z.infer<typeof RaceSummary>;
+
+/** A listed game, as the menu's game list and the catalog show it. Broken apps are left out. */
+export const GameInfo = z.object({
+  slug: Slug,
+  title: z.string(),
+  /** Its URL path, e.g. `/duel`. */
+  path: z.string(),
+  /** `process` apps run their own server behind the host. */
+  kind: z.enum(['static', 'process']),
+  hasImage: z.boolean(),
+  /** `false` when the game opted out of the injected hub menu. */
+  hubEnabled: z.boolean(),
+  /** `null` for single-player games. */
+  multiplayer: MultiplayerSummary.nullable(),
+  /** `null` unless the game supports races. */
+  race: RaceSummary.nullable(),
+});
+
+/** A listed game. */
+export type GameInfo = z.infer<typeof GameInfo>;
+
+/** `{ games }`: the caller's starred slugs, oldest star first. */
+const Favorites = z.object({ games: z.array(Slug) });
+
+/** One What's new note. */
+export const ChangeNote = z.object({
+  id: z.number().int().positive(),
+  /** The game's slug, or `_hub` for the site's own notes. */
+  game: Slug,
+  /** The game's title, or `diffenderfer.games` for the site's own notes. */
+  title: z.string(),
+  text: z.string(),
+  /** When the note went live (the deploy that first saw it), epoch ms. */
+  at: Millis,
+  /** Not yet seen by this player (or since `?since=` when signed out). */
+  new: z.boolean(),
+});
+
+/** A What's new note. */
+export type ChangeNote = z.infer<typeof ChangeNote>;
+
+/** The catalog endpoints. */
+export const catalogEndpoints = {
+  ...session.group({
+    listGames: {
+      method: 'GET', path: '/games',
+      response: z.object({ games: z.array(GameInfo) }),
+      doc: { summary: 'The game catalog, sorted by title', tags: ['catalog'] },
+    },
+    /**
+     * Notes from the last 30 days, newest first (at most 6 per game and 30
+     * in all). In a game, `?game=` limits them to that game's and the site's.
+     */
+    listWhatsNewNotes: {
+      method: 'GET', path: '/changes',
+      query: z.object({
+        /** A game's slug. Empty means everything; an unknown one lists only the site's notes. */
+        game: z.string().optional(),
+        /**
+         * Signed out only: the device's last-cleared time (epoch ms); without
+         * it (or when it isn't a number) nothing is new.
+         */
+        since: z.preprocess((value: number | string | undefined) => (value === '' ? undefined : value), LooseNumber.optional()).catch(undefined),
+      }),
+      response: z.object({
+        items: z.array(ChangeNote),
+        /** How many of `items` are new. */
+        unseen: z.number().int().nonnegative(),
+        signedIn: z.boolean(),
+      }),
+      doc: { summary: "What's new: recent change notes", tags: ['catalog'] },
+    },
+  }),
+  ...requireUser.group({
+    listFavoriteGames: {
+      method: 'GET', path: '/favorites', response: Favorites,
+      errors: { 401: ErrorBody },
+      doc: { summary: "The caller's starred games", tags: ['catalog'] },
+    },
+    /**
+     * Star or unstar a game (idempotent). Starring needs a known game (404);
+     * unstarring any slug succeeds.
+     */
+    setGameFavorite: {
+      method: 'PUT', path: '/favorites/:slug',
+      params: z.object({ slug: Slug }),
+      body: z.object({
+        /** `true` stars, `false` (or missing) unstars. */
+        on: Truthy.optional(),
+      }),
+      response: Favorites,
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Star or unstar a game', tags: ['catalog'] },
+    },
+    /**
+     * Mark notes seen now. With `game`: that game's and the site's. With
+     * `all` (or neither): everything.
+     */
+    markWhatsNewSeen: {
+      method: 'POST', path: '/changes/seen',
+      body: z.object({
+        /** A game's slug, read as text; an unknown one is a 404. Ignored with `all`. */
+        game: LooseText.nullish(),
+        all: Truthy.optional(),
+      }),
+      response: z.object({
+        ok: z.literal(true),
+        /** The seen mark stored, epoch ms. */
+        seenAt: Millis,
+      }),
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Mark What's new notes seen", tags: ['catalog'] },
+    },
+  }),
+};

package/src/api/daily.ts

@@ -1,122 +1,122 @@
-/**
- * Daily challenges: one deterministic challenge per UTC day for games with
- * `game.dailyChallenges: true`. Starting a day mints a signed token; the game
- * presents it on completion. Completions are counted on the game's `daily`
- * leaderboard. The client owns the calendar (its local date); the hub only
- * reports which days are done.
- */
-import { use } from '@ayepi/core';
-import { z } from 'zod';
-import { DayKey, Json, Millis, Slug, UserId } from '../common';
-import { ErrorBody } from '../errors';
-import { game, requireUser, session } from '../middleware';
-import { Rank } from './leaderboards';
-
-/** One completed day. */
-export const DailyCompletion = z.object({
-  /** Epoch ms (server clock). */
-  completedAt: Millis,
-  /** The JSON the game sent on completion, or `null`. */
-  meta: Json,
-});
-
-/** One completed day. */
-export type DailyCompletion = z.infer<typeof DailyCompletion>;
-
-/** A player's completions in one game, keyed by `YYYY-MM-DD`. */
-export const DailyCompletions = z.record(DayKey, DailyCompletion);
-
-/** A player's completions in one game. */
-export type DailyCompletions = z.infer<typeof DailyCompletions>;
-
-/** `:day` of a challenge: within 30 days back and 1 day ahead of UTC today. */
-const DayParams = z.object({ day: z.string().refine((day) => DayKey.safeParse(day).success, { error: 'Invalid day (expected YYYY-MM-DD).' }) });
-
-/** The daily endpoints. */
-export const dailyEndpoints = {
-  ...session.group({
-    /**
-     * Every daily game with the caller's completions (empty maps when signed
-     * out), plus the top 10 players by completions across all games.
-     */
-    listDailyChallengesForAllGames: {
-      method: 'GET', path: '/daily',
-      response: z.object({
-        /** UTC today, a hint: clients use their local date. */
-        today: DayKey,
-        games: z.array(z.object({ slug: Slug, title: z.string(), completions: DailyCompletions })),
-        global: z.array(z.object({
-          rank: Rank,
-          userId: UserId,
-          username: z.string(),
-          /** Daily challenges completed, across all games. */
-          score: z.number().int().nonnegative(),
-        })),
-      }),
-      doc: { summary: 'Daily challenges across every game, plus global standings', tags: ['daily'] },
-    },
-  }),
-  ...use(session, game).path('/games/:slug').group({
-    getGameDailyChallenges: {
-      method: 'GET', path: '/daily',
-      response: z.object({
-        enabled: z.literal(true),
-        /** UTC today, a hint: clients use their local date. */
-        today: DayKey,
-        /** Empty when signed out. */
-        completions: DailyCompletions,
-      }),
-      errors: { 404: ErrorBody },
-      doc: { summary: "The caller's completions in this game (404 if it has no dailies)", tags: ['daily'] },
-    },
-  }),
-  ...use(requireUser, game).path('/games/:slug').group({
-    /**
-     * Start (or replay) a day: returns its seed and a signed token to present
-     * on completion. 400 when the day is outside the window.
-     */
-    startDailyChallenge: {
-      method: 'POST', path: '/daily/:day/start', params: DayParams,
-      response: z.object({
-        /** Present it to `dailyComplete` for the same day. */
-        token: z.string(),
-        day: DayKey,
-        /** Deterministic per (game, day), an unsigned 32-bit integer. */
-        seed: z.number().int().min(0).max(0xffff_ffff),
-        /** When the token stops working (epoch ms), about 26 hours out. */
-        expiresAt: Millis,
-        alreadyCompleted: z.boolean(),
-        /** Epoch ms, or `null` when not completed yet. */
-        completedAt: Millis.nullable(),
-        /** The earlier completion's JSON, or `null`. */
-        meta: Json,
-      }),
-      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: "Start a day's challenge and get its token", tags: ['daily'] },
-    },
-    /**
-     * Record a completion with the token from `dailyStart`. Idempotent: a
-     * replay of a done day changes nothing. 401 on a bad, expired or
-     * mismatched token.
-     */
-    completeDailyChallenge: {
-      method: 'POST', path: '/daily/:day/complete', params: DayParams,
-      body: z.object({
-        /** The token from `dailyStart`; a missing or non-text token is refused like a bad one (401). */
-        token: z.string().optional().catch(undefined),
-        /** Any JSON; a numeric `meta.score` is kept with the completion. */
-        meta: Json.optional(),
-      }),
-      response: z.object({
-        ok: z.literal(true),
-        day: DayKey,
-        /** The caller's completions in this game. */
-        count: z.number().int().positive(),
-        /** The caller's rank on the game's `daily` board. */
-        rank: Rank.nullable(),
-      }),
-      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Complete a day with its token', tags: ['daily'] },
-    },
-  }),
-};
+/**
+ * Daily challenges: one deterministic challenge per UTC day for games with
+ * `game.dailyChallenges: true`. Starting a day mints a signed token; the game
+ * presents it on completion. Completions are counted on the game's `daily`
+ * leaderboard. The client owns the calendar (its local date); the hub only
+ * reports which days are done.
+ */
+import { use } from '@ayepi/core';
+import { z } from 'zod';
+import { DayKey, Json, Millis, Slug, UserId } from '../common';
+import { ErrorBody } from '../errors';
+import { game, requireUser, session } from '../middleware';
+import { Rank } from './leaderboards';
+
+/** One completed day. */
+export const DailyCompletion = z.object({
+  /** Epoch ms (server clock). */
+  completedAt: Millis,
+  /** The JSON the game sent on completion, or `null`. */
+  meta: Json,
+});
+
+/** One completed day. */
+export type DailyCompletion = z.infer<typeof DailyCompletion>;
+
+/** A player's completions in one game, keyed by `YYYY-MM-DD`. */
+export const DailyCompletions = z.record(DayKey, DailyCompletion);
+
+/** A player's completions in one game. */
+export type DailyCompletions = z.infer<typeof DailyCompletions>;
+
+/** `:day` of a challenge: within 30 days back and 1 day ahead of UTC today. */
+const DayParams = z.object({ day: z.string().refine((day) => DayKey.safeParse(day).success, { error: 'Invalid day (expected YYYY-MM-DD).' }) });
+
+/** The daily endpoints. */
+export const dailyEndpoints = {
+  ...session.group({
+    /**
+     * Every daily game with the caller's completions (empty maps when signed
+     * out), plus the top 10 players by completions across all games.
+     */
+    listDailyChallengesForAllGames: {
+      method: 'GET', path: '/daily',
+      response: z.object({
+        /** UTC today, a hint: clients use their local date. */
+        today: DayKey,
+        games: z.array(z.object({ slug: Slug, title: z.string(), completions: DailyCompletions })),
+        global: z.array(z.object({
+          rank: Rank,
+          userId: UserId,
+          username: z.string(),
+          /** Daily challenges completed, across all games. */
+          score: z.number().int().nonnegative(),
+        })),
+      }),
+      doc: { summary: 'Daily challenges across every game, plus global standings', tags: ['daily'] },
+    },
+  }),
+  ...use(session, game).path('/games/:slug').group({
+    getGameDailyChallenges: {
+      method: 'GET', path: '/daily',
+      response: z.object({
+        enabled: z.literal(true),
+        /** UTC today, a hint: clients use their local date. */
+        today: DayKey,
+        /** Empty when signed out. */
+        completions: DailyCompletions,
+      }),
+      errors: { 404: ErrorBody },
+      doc: { summary: "The caller's completions in this game (404 if it has no dailies)", tags: ['daily'] },
+    },
+  }),
+  ...use(requireUser, game).path('/games/:slug').group({
+    /**
+     * Start (or replay) a day: returns its seed and a signed token to present
+     * on completion. 400 when the day is outside the window.
+     */
+    startDailyChallenge: {
+      method: 'POST', path: '/daily/:day/start', params: DayParams,
+      response: z.object({
+        /** Present it to `dailyComplete` for the same day. */
+        token: z.string(),
+        day: DayKey,
+        /** Deterministic per (game, day), an unsigned 32-bit integer. */
+        seed: z.number().int().min(0).max(0xffff_ffff),
+        /** When the token stops working (epoch ms), about 26 hours out. */
+        expiresAt: Millis,
+        alreadyCompleted: z.boolean(),
+        /** Epoch ms, or `null` when not completed yet. */
+        completedAt: Millis.nullable(),
+        /** The earlier completion's JSON, or `null`. */
+        meta: Json,
+      }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Start a day's challenge and get its token", tags: ['daily'] },
+    },
+    /**
+     * Record a completion with the token from `dailyStart`. Idempotent: a
+     * replay of a done day changes nothing. 401 on a bad, expired or
+     * mismatched token.
+     */
+    completeDailyChallenge: {
+      method: 'POST', path: '/daily/:day/complete', params: DayParams,
+      body: z.object({
+        /** The token from `dailyStart`; a missing or non-text token is refused like a bad one (401). */
+        token: z.string().optional().catch(undefined),
+        /** Any JSON; a numeric `meta.score` is kept with the completion. */
+        meta: Json.optional(),
+      }),
+      response: z.object({
+        ok: z.literal(true),
+        day: DayKey,
+        /** The caller's completions in this game. */
+        count: z.number().int().positive(),
+        /** The caller's rank on the game's `daily` board. */
+        rank: Rank.nullable(),
+      }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Complete a day with its token', tags: ['daily'] },
+    },
+  }),
+};