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

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

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

package/src/api/progress.ts

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

package/src/api/race.ts

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

package/src/api/reports.ts

@@ -0,0 +1,208 @@
+/**
+ * Reports and suggestions: players flagging problems (multiplayer-impl.md
+ * §5.3) and proposing game ideas (§5.5).
+ *
+ * A report only says *what* is reported; the hub builds the evidence
+ * snapshot from its own records. Suggestions are filtered, reviewed by an
+ * admin, and only approved ones reach the public board.
+ */
+import { z } from 'zod';
+import { Millis, Ok } from '../common';
+import { LooseNumber } from '../coerce';
+import { ContentRejected, ErrorBody } from '../errors';
+import { requireActive, requireClaimed, session } from '../middleware';
+import { Presence } from './social/presence';
+
+/** What is being reported. */
+export const ReportKind = z.enum(['message', 'user', 'username', 'suggestion', 'room_chat', 'presence'], {
+  error: 'kind must be one of message, user, username, suggestion, room_chat, presence.',
+});
+
+/** A report kind. */
+export type ReportKind = z.infer<typeof ReportKind>;
+
+/** Why, from a fixed list (there is no free text). */
+export const ReportReason = z.enum(['mean', 'bad_words', 'personal', 'inappropriate', 'spam', 'other'], {
+  error: 'reason must be one of mean, bad_words, personal, inappropriate, spam, other.',
+});
+
+/** A report reason. */
+export type ReportReason = z.infer<typeof ReportReason>;
+
+/**
+ * `POST /social/reports`. Loose on purpose: anything else the client sends
+ * (an evidence snapshot, quoted text) is ignored, because the hub builds the
+ * snapshot from its own records.
+ */
+export const ReportInput = z.looseObject({
+  kind: ReportKind,
+  /**
+   * The reported player. `0` for a suggestion: the hub finds its author from
+   * `refId`. Read like `Number(x)`: anything that is not a player's id is a 404.
+   */
+  targetUserId: LooseNumber.catch(Number.NaN),
+  /**
+   * What exactly: the message id (`message`), the suggestion id
+   * (`suggestion`) or the room code (`room_chat`). Kept to 64 characters.
+   */
+  refId: z.union([z.string(), z.number()]).nullable().optional(),
+  reason: ReportReason,
+});
+
+/** A report. */
+export type ReportInput = z.infer<typeof ReportInput>;
+
+/** A direct message as a report snapshot keeps it. */
+export const ReportedMessage = z.object({
+  id: z.number().int().positive(),
+  /** The sender's user id. */
+  from: z.number().int(),
+  /** The recipient's user id. */
+  to: z.number().int(),
+  /** When it was sent (epoch ms). */
+  at: Millis,
+  /** The text, or the quick-chat phrase's text (`''` for an unknown phrase). */
+  text: z.string(),
+  /** The quick-chat phrase id, when it was one. */
+  quick: z.string().optional(),
+});
+
+/** A reported direct message. */
+export type ReportedMessage = z.infer<typeof ReportedMessage>;
+
+/**
+ * The evidence the hub records with a report, from its own records (stored
+ * as `snapshot_json`; the admin console shows it). Always the reported
+ * player; then per kind: `message` adds the message and up to 5 before it in
+ * the conversation (oldest first), `suggestion` its title, body and status,
+ * `presence` their status line (`null` when offline), `room_chat` the room
+ * code (room chat isn't stored).
+ */
+export const ReportSnapshot = z.object({
+  userId: z.number().int(),
+  username: z.string(),
+  message: ReportedMessage.optional(),
+  context: z.array(ReportedMessage).optional(),
+  title: z.string().optional(),
+  body: z.string().optional(),
+  status: z.string().optional(),
+  detail: z.string().optional(),
+  presence: Presence.nullable().optional(),
+  room: z.string().optional(),
+});
+
+/** A report's evidence snapshot. */
+export type ReportSnapshot = z.infer<typeof ReportSnapshot>;
+
+/** A suggestion's review status. Only `approved`, `planned` and `done` are on the public board. */
+export const SuggestionStatus = z.enum(['pending', 'approved', 'planned', 'done', 'removed', 'withdrawn']);
+
+/** A suggestion status. */
+export type SuggestionStatus = z.infer<typeof SuggestionStatus>;
+
+/** A suggestion id. */
+export const SuggestionId = z.number().int().positive();
+
+/** A game suggestion. */
+export const Suggestion = z.object({
+  id: SuggestionId,
+  title: z.string(),
+  /** The description. */
+  body: z.string(),
+  status: SuggestionStatus,
+  /** Upvotes. */
+  votes: z.number().int().nonnegative(),
+  /** You upvoted it. */
+  voted: z.boolean(),
+  /** You suggested it. */
+  mine: z.boolean(),
+  /** The reviewer's note to the author, `''` when none. */
+  adminNote: z.string(),
+  /** When it was suggested (epoch ms). */
+  createdAt: Millis,
+  /** The author's username: only once it is on the public board (and always in admin views). */
+  author: z.string().optional(),
+});
+
+/** A game suggestion. */
+export type Suggestion = z.infer<typeof Suggestion>;
+
+/** A vote's result: the new count and whether you are voting. */
+export const VoteResult = z.object({ votes: z.number().int().nonnegative(), voted: z.boolean() });
+
+/**
+ * `:id`, a suggestion: one on the public board to vote, your own pending one
+ * to withdraw. Read like `Number(x)`: anything that isn't one is a 404.
+ */
+const SuggestionParams = z.object({ id: LooseNumber.catch(Number.NaN) });
+
+/** The old hub's one message for a missing or non-text title or description. */
+const SuggestionText = z.string({ error: 'A suggestion needs a title and a description.' });
+
+/** The report and suggestion endpoints. */
+export const reportsEndpoints = {
+  ...requireActive.group({
+    fileReport: {
+      method: 'POST', path: '/social/reports', body: ReportInput,
+      response: z.object({
+        ok: z.literal(true),
+        /** The report's id (the open one, when you already reported the same thing). */
+        id: z.number().int().positive(),
+      }),
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: 'Report a player, a message, a suggestion or a status line',
+        description: '404 when `refId` is nothing you could have seen from that player.',
+        tags: ['reports'],
+      },
+    },
+  }),
+  ...session.group({
+    listPublicSuggestions: {
+      method: 'GET', path: '/suggestions',
+      query: z.object({
+        /** `votes` (default) or `new`. */
+        sort: z.enum(['votes', 'new']).optional().catch(undefined),
+      }),
+      response: z.object({
+        /** The public board (approved, planned, done), at most 200. Ideas from suspended authors drop off. */
+        approved: z.array(Suggestion),
+        /** Your own ideas except withdrawn ones, newest first; empty unless signed in to a claimed account. */
+        mine: z.array(Suggestion),
+      }),
+      errors: { 403: ErrorBody },
+      doc: { summary: 'The ideas board, plus your own ideas', tags: ['suggestions'] },
+    },
+  }),
+  ...requireClaimed.group({
+    submitSuggestion: {
+      method: 'POST', path: '/suggestions',
+      body: z.object({ title: SuggestionText, body: SuggestionText }),
+      response: z.object({ suggestion: Suggestion }),
+      errors: {
+        400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 409: ErrorBody,
+        422: ContentRejected, 429: ErrorBody,
+      },
+      doc: {
+        summary: 'Suggest a game idea (filtered; a few a day, a capped number pending)',
+        description: '409 `too_many_pending`; 429 `rate_limited` with `retryAfterMs` past the daily limit.',
+        tags: ['suggestions'],
+      },
+    },
+    voteForSuggestion: {
+      method: 'POST', path: '/suggestions/:id/vote', params: SuggestionParams, response: VoteResult,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Upvote an idea (idempotent)', tags: ['suggestions'] },
+    },
+    removeSuggestionVote: {
+      method: 'DELETE', path: '/suggestions/:id/vote', params: SuggestionParams, response: VoteResult,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Take an upvote back (idempotent)', tags: ['suggestions'] },
+    },
+    withdrawSuggestion: {
+      method: 'DELETE', path: '/suggestions/:id', params: SuggestionParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: 'Withdraw your own idea while it is still pending', tags: ['suggestions'] },
+    },
+  }),
+};

package/src/api/social/config.ts

@@ -0,0 +1,47 @@
+/**
+ * The site-wide social configuration every social UI renders from
+ * (`GET /social/config`, `ev:config`, the `hello` snapshot).
+ */
+import { z } from 'zod';
+import { ChatMode } from '../../entities';
+
+
+/** A quick-chat phrase id: a hub phrase (`gg`), an emote (`e:<emoji>`) or a game phrase (`g:<slug>:<n>`). */
+export const QuickId = z.string().min(1);
+
+/** A non-negative character limit. */
+const CharLimit = z.number().int().nonnegative();
+
+/** Text length limits, in characters. */
+export const SocialLimits = z.object({
+  dmMaxChars: CharLimit,
+  roomChatMaxChars: CharLimit,
+  suggestionTitleMax: CharLimit,
+  suggestionBodyMax: CharLimit,
+});
+
+/** The site-wide social configuration. */
+export const SocialConfig = z.object({
+  /** The site-wide chat mode (operator setting tightened by the admin switch). */
+  chatMode: ChatMode,
+  /** The AI safety reviewer is configured. */
+  ai: z.boolean(),
+  /** Where parents can reach the operator, `''` when unset. */
+  contactUrl: z.string(),
+  /** The public "how chat is kept safe" page. */
+  parentsUrl: z.string(),
+  /** The Web Push VAPID public key (base64url), `''` when push isn't configured. */
+  vapidPublicKey: z.string(),
+  /** Every quick-chat phrase, id to text: hub phrases, emotes and every game's phrases. */
+  quickChat: z.record(QuickId, z.string()),
+  /** The emote emoji (also in `quickChat` as `e:<emoji>` ids). */
+  emotes: z.array(z.string()),
+  limits: SocialLimits,
+  /** The preset avatar ids (`a0` to `a23`). */
+  avatars: z.array(z.string()),
+  /** Present (`true`) only when the host runs in test mode (`HUB_TEST=1`). */
+  test: z.literal(true).optional(),
+});
+
+/** The social configuration. */
+export type SocialConfig = z.infer<typeof SocialConfig>;