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

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'] },
+    },
+  }),
+};

package/src/api/economy/bundle.ts

@@ -1,69 +1,69 @@
-/**
- * Economy shapes: a player's per-game holdings and the bundles that move
- * goods. Items are opaque, app-defined {@link Key}s; the hub only counts them.
- */
-import { z } from 'zod';
-import { Key } from '../../common';
-
-/**
- * The default largest quantity (or coin amount) one bundle entry may carry.
- * The hub's limit is `HUB_MAX_ITEM_QTY`, which defaults to this.
- */
-export const MAX_ITEM_QTY = 1_000_000;
-
-/**
- * The default most distinct item keys one bundle may name. The hub's limit
- * is `HUB_MAX_BUNDLE_ITEMS`, which defaults to this.
- */
-export const MAX_BUNDLE_ITEMS = 50;
-
-/** A player's holdings in one game: items with a positive count, and coins. */
-export const Inventory = z.object({
-  /** Sorted by key. */
-  items: z.array(z.object({ key: Key, qty: z.number().int().positive() })),
-  coins: z.number().int().nonnegative(),
-});
-
-/** A player's holdings in one game. */
-export type Inventory = z.infer<typeof Inventory>;
-
-/**
- * A bundle quantity, read like the hub's `Number(x)` (numeric strings pass).
- * A value that is not a number reads as `NaN` here rather than failing, so
- * the hub's own range check, which knows its configured limits, answers with
- * its message (e.g. `grant.coins must be an integer in [0, 1000000].`).
- * Clients should send a JSON integer.
- */
-const BundleQuantity = z.coerce.number<number>().catch(Number.NaN);
-
-/**
- * Goods to grant, spend or trade, as a request sends them, for the request
- * field named `label` (`grant`, `take`, `give`, `want`), which the error
- * messages name. Both parts are optional (`null` or missing means none).
- * Item keys must be {@link Key}s, at most `HUB_MAX_BUNDLE_ITEMS` of them,
- * each with a quantity from 1 to `HUB_MAX_ITEM_QTY`; coins run from 0 to
- * `HUB_MAX_ITEM_QTY`. The hub checks those limits and the keys itself.
- */
-export function bundleInput(label: string) {
-  return z.object({
-    /** 0 to `HUB_MAX_ITEM_QTY`. */
-    coins: BundleQuantity.nullish(),
-    /** Item key to quantity (1 to `HUB_MAX_ITEM_QTY`). */
-    items: z.record(z.string(), BundleQuantity, { error: `${label}.items must be an object of key→quantity.` }).nullish(),
-  }, { error: `${label} must be an object.` });
-}
-
-/** A request bundle, for documentation and clients. */
-export const BundleInput = bundleInput('bundle');
-
-/** A request bundle. */
-export type BundleInput = z.infer<typeof BundleInput>;
-
-/** A bundle as the hub stores and returns it on a trade offer: both parts always present. */
-export const Bundle = z.object({
-  items: z.record(Key, z.number().int().positive()),
-  coins: z.number().int().nonnegative(),
-});
-
-/** A stored bundle. */
-export type Bundle = z.infer<typeof Bundle>;
+/**
+ * Economy shapes: a player's per-game holdings and the bundles that move
+ * goods. Items are opaque, app-defined {@link Key}s; the hub only counts them.
+ */
+import { z } from 'zod';
+import { Key } from '../../common';
+
+/**
+ * The default largest quantity (or coin amount) one bundle entry may carry.
+ * The hub's limit is `HUB_MAX_ITEM_QTY`, which defaults to this.
+ */
+export const MAX_ITEM_QTY = 1_000_000;
+
+/**
+ * The default most distinct item keys one bundle may name. The hub's limit
+ * is `HUB_MAX_BUNDLE_ITEMS`, which defaults to this.
+ */
+export const MAX_BUNDLE_ITEMS = 50;
+
+/** A player's holdings in one game: items with a positive count, and coins. */
+export const Inventory = z.object({
+  /** Sorted by key. */
+  items: z.array(z.object({ key: Key, qty: z.number().int().positive() })),
+  coins: z.number().int().nonnegative(),
+});
+
+/** A player's holdings in one game. */
+export type Inventory = z.infer<typeof Inventory>;
+
+/**
+ * A bundle quantity, read like the hub's `Number(x)` (numeric strings pass).
+ * A value that is not a number reads as `NaN` here rather than failing, so
+ * the hub's own range check, which knows its configured limits, answers with
+ * its message (e.g. `grant.coins must be an integer in [0, 1000000].`).
+ * Clients should send a JSON integer.
+ */
+const BundleQuantity = z.coerce.number<number>().catch(Number.NaN);
+
+/**
+ * Goods to grant, spend or trade, as a request sends them, for the request
+ * field named `label` (`grant`, `take`, `give`, `want`), which the error
+ * messages name. Both parts are optional (`null` or missing means none).
+ * Item keys must be {@link Key}s, at most `HUB_MAX_BUNDLE_ITEMS` of them,
+ * each with a quantity from 1 to `HUB_MAX_ITEM_QTY`; coins run from 0 to
+ * `HUB_MAX_ITEM_QTY`. The hub checks those limits and the keys itself.
+ */
+export function bundleInput(label: string) {
+  return z.object({
+    /** 0 to `HUB_MAX_ITEM_QTY`. */
+    coins: BundleQuantity.nullish(),
+    /** Item key to quantity (1 to `HUB_MAX_ITEM_QTY`). */
+    items: z.record(z.string(), BundleQuantity, { error: `${label}.items must be an object of key→quantity.` }).nullish(),
+  }, { error: `${label} must be an object.` });
+}
+
+/** A request bundle, for documentation and clients. */
+export const BundleInput = bundleInput('bundle');
+
+/** A request bundle. */
+export type BundleInput = z.infer<typeof BundleInput>;
+
+/** A bundle as the hub stores and returns it on a trade offer: both parts always present. */
+export const Bundle = z.object({
+  items: z.record(Key, z.number().int().positive()),
+  coins: z.number().int().nonnegative(),
+});
+
+/** A stored bundle. */
+export type Bundle = z.infer<typeof Bundle>;

package/src/api/index.ts

@@ -1,85 +1,92 @@
-/**
- * The public REST API: every endpoint a game, the menu or the social runtime
- * calls, as one ayepi spec. Paths are relative to `/_api`. One file per area.
- */
-import { spec } from '@ayepi/core';
-import { analyticsEndpoints } from './analytics';
-import { authEndpoints } from './auth';
-import { catalogEndpoints } from './catalog';
-import { dailyEndpoints } from './daily';
-import { economyEndpoints } from './economy';
-import { leaderboardsEndpoints } from './leaderboards';
-import { messagesEndpoints } from './messages';
-import { mpEndpoints } from './mp';
-import { notifyEndpoints } from './notify';
-import { progressEndpoints } from './progress';
-import { raceEndpoints } from './race';
-import { reportsEndpoints } from './reports';
-import { socialEndpoints } from './social';
-import { versionEndpoints } from './version';
-
-// Every area's shapes (request, response and entity schemas), for clients and tests.
-export * from './analytics';
-export * from './auth';
-export * from './catalog';
-export * from './daily';
-export * from './economy';
-export * from './leaderboards';
-export * from './messages';
-export * from './mp';
-export * from './notify';
-export * from './progress';
-export * from './race';
-export * from './reports';
-export * from './social';
-export * from './version';
-
-/**
- * Every public endpoint, by name. Typed as an intersection of the areas so the
- * published .d.ts refers to each area instead of repeating every endpoint.
- */
-export type PublicEndpoints =
-  typeof authEndpoints
-  & typeof catalogEndpoints
-  & typeof progressEndpoints
-  & typeof leaderboardsEndpoints
-  & typeof dailyEndpoints
-  & typeof economyEndpoints
-  & typeof analyticsEndpoints
-  & typeof socialEndpoints
-  & typeof messagesEndpoints
-  & typeof notifyEndpoints
-  & typeof reportsEndpoints
-  & typeof mpEndpoints
-  & typeof raceEndpoints
-  & typeof versionEndpoints;
-
-/** Every public endpoint, by name. */
-export const publicEndpoints: PublicEndpoints = {
-  ...authEndpoints,
-  ...catalogEndpoints,
-  ...progressEndpoints,
-  ...leaderboardsEndpoints,
-  ...dailyEndpoints,
-  ...economyEndpoints,
-  ...analyticsEndpoints,
-  ...socialEndpoints,
-  ...messagesEndpoints,
-  ...notifyEndpoints,
-  ...reportsEndpoints,
-  ...mpEndpoints,
-  ...raceEndpoints,
-  ...versionEndpoints,
-};
-
-/**
- * The public API spec's type. Declared (not inferred) so the published
- * `.d.ts` refers to `publicEndpoints` instead of repeating every endpoint.
- */
-export interface PublicApi {
-  /** Every public endpoint, by name. */
-  readonly endpoints: PublicEndpoints;
-}
-
-/** The public API spec (paths relative to `/_api`). */
-export const publicApi: PublicApi = spec({ endpoints: publicEndpoints });
+/**
+ * The public REST API: every endpoint a game, the menu or the social runtime
+ * calls, as one ayepi spec. Paths are relative to `/_api`. One file per area.
+ */
+import { spec } from '@ayepi/core';
+import { analyticsEndpoints } from './analytics';
+import { authEndpoints } from './auth';
+import { catalogEndpoints } from './catalog';
+import { dailyEndpoints } from './daily';
+import { economyEndpoints } from './economy';
+import { leaderboardsEndpoints } from './leaderboards';
+import { messagesEndpoints } from './messages';
+import { mpEndpoints } from './mp';
+import { notifyEndpoints } from './notify';
+import { progressEndpoints } from './progress';
+import { raceEndpoints } from './race';
+import { reportsEndpoints } from './reports';
+import { socialEndpoints } from './social';
+import { playOnlineEndpoints, tournamentEndpoints } from './tournaments';
+import { versionEndpoints } from './version';
+
+// Every area's shapes (request, response and entity schemas), for clients and tests.
+export * from './analytics';
+export * from './auth';
+export * from './catalog';
+export * from './daily';
+export * from './economy';
+export * from './leaderboards';
+export * from './messages';
+export * from './mp';
+export * from './notify';
+export * from './offline';
+export * from './progress';
+export * from './race';
+export * from './reports';
+export * from './social';
+export * from './tournaments';
+export * from './version';
+
+/**
+ * Every public endpoint, by name. Typed as an intersection of the areas so the
+ * published .d.ts refers to each area instead of repeating every endpoint.
+ */
+export type PublicEndpoints =
+  typeof authEndpoints
+  & typeof catalogEndpoints
+  & typeof progressEndpoints
+  & typeof leaderboardsEndpoints
+  & typeof dailyEndpoints
+  & typeof economyEndpoints
+  & typeof analyticsEndpoints
+  & typeof socialEndpoints
+  & typeof messagesEndpoints
+  & typeof notifyEndpoints
+  & typeof reportsEndpoints
+  & typeof mpEndpoints
+  & typeof raceEndpoints
+  & typeof tournamentEndpoints
+  & typeof playOnlineEndpoints
+  & typeof versionEndpoints;
+
+/** Every public endpoint, by name. */
+export const publicEndpoints: PublicEndpoints = {
+  ...authEndpoints,
+  ...catalogEndpoints,
+  ...progressEndpoints,
+  ...leaderboardsEndpoints,
+  ...dailyEndpoints,
+  ...economyEndpoints,
+  ...analyticsEndpoints,
+  ...socialEndpoints,
+  ...messagesEndpoints,
+  ...notifyEndpoints,
+  ...reportsEndpoints,
+  ...mpEndpoints,
+  ...raceEndpoints,
+  ...tournamentEndpoints,
+  ...playOnlineEndpoints,
+  ...versionEndpoints,
+};
+
+/**
+ * The public API spec's type. Declared (not inferred) so the published
+ * `.d.ts` refers to `publicEndpoints` instead of repeating every endpoint.
+ */
+export interface PublicApi {
+  /** Every public endpoint, by name. */
+  readonly endpoints: PublicEndpoints;
+}
+
+/** The public API spec (paths relative to `/_api`). */
+export const publicApi: PublicApi = spec({ endpoints: publicEndpoints });