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

package/src/api/mp.ts

@@ -0,0 +1,110 @@
+/**
+ * Multiplayer REST (multiplayer-impl.md §5.6): invites, launch tokens,
+ * parties, joining a friend's game, and game-server tickets. Every route
+ * needs an active account; invites need a claimed one. The live state is in
+ * the hub's memory and changes are pushed over `/_ws` (`invite`,
+ * `invite.update`, `party`).
+ */
+import { z } from 'zod';
+import { Millis, Ok, Slug, UserIdParam } from '../common';
+import { ErrorBody } from '../errors';
+import { requireActive, requireClaimed } from '../middleware';
+import { GameMode, Invite, JoinInfo, Launch, LaunchTicket, OpaqueId } from './mp/parties';
+
+export * from './mp/chat';
+export * from './mp/parties';
+export * from './mp/races';
+export * from './mp/rooms';
+export * from './mp/snapshot';
+
+/** `:id` of an invite or party. */
+const IdParams = z.object({ id: OpaqueId });
+
+/** The answer to `POST /mp/invites`: the invite, plus the inviter's own `host` launch. */
+export const InviteCreated = LaunchTicket.extend({ invite: Invite });
+
+/** A game-server identity ticket. */
+export const GameTicket = z.object({
+  /** `base64url(payload).base64url(hmac)`, verified offline by the game's server with `HUB_APP_KEY`. */
+  ticket: z.string(),
+  /** Epoch ms; tickets live 60 s. */
+  expiresAt: Millis,
+});
+
+/** The mp endpoints. */
+export const mpEndpoints = {
+  ...requireClaimed.group({
+    sendGameInvite: {
+      method: 'POST', path: '/mp/invites',
+      body: z.object({
+        /** The friend to invite. */
+        to: UserIdParam,
+        game: Slug,
+        /** One of the game's modes; race-only games default to `race`. */
+        mode: GameMode.nullish(),
+      }),
+      response: InviteCreated,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: {
+        summary: 'Invite a friend to a game; creates or reuses your party and returns your host launch',
+        tags: ['mp'],
+      },
+    },
+    acceptGameInvite: {
+      method: 'POST', path: '/mp/invites/:id/accept', params: IdParams, response: LaunchTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: { summary: "Accept an invite: join the inviter's party and get a guest launch", tags: ['mp'] },
+    },
+    declineGameInvite: {
+      method: 'POST', path: '/mp/invites/:id/decline', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Decline an invite addressed to you', tags: ['mp'] },
+    },
+    cancelGameInvite: {
+      method: 'DELETE', path: '/mp/invites/:id', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Cancel an invite you sent', tags: ['mp'] },
+    },
+  }),
+  ...requireActive.group({
+    redeemLaunchToken: {
+      method: 'GET', path: '/mp/launch/:token', params: z.object({ token: z.string() }),
+      response: z.object({ launch: Launch }),
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Redeem a launch token (single use, bound to the signed-in user)', tags: ['mp'] },
+    },
+    setPartyJoinInfo: {
+      method: 'POST', path: '/mp/parties/:id/join-info', params: IdParams,
+      body: z.object({ info: JoinInfo }),
+      response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Party leader: publish where the party should connect', tags: ['mp'] },
+    },
+    leaveParty: {
+      method: 'POST', path: '/mp/parties/:id/leave', params: IdParams, response: Ok,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Leave a party (the leader role passes on; an empty party dissolves)', tags: ['mp'] },
+    },
+    launchIntoFriendsRoom: {
+      method: 'POST', path: '/mp/join',
+      body: z.object({
+        /** The player whose game to join or watch. */
+        userId: UserIdParam,
+        /** Watch instead of play. */
+        watch: z.boolean().optional(),
+        /** Joining a stranger's public lobby from a `lobby_open` alert (not a friend's game). */
+        fromLobbyOpen: z.boolean().optional(),
+      }),
+      response: LaunchTicket,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: "A Join or Watch launch into the room a friend's presence advertises", tags: ['mp'] },
+    },
+    getGameServerTicket: {
+      method: 'POST', path: '/mp/ticket',
+      body: z.object({ slug: Slug }),
+      response: GameTicket,
+      errors: { 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 429: ErrorBody },
+      doc: { summary: "A 60 s identity ticket for a game's own server", tags: ['mp'] },
+    },
+  }),
+};

package/src/api/notify.ts

@@ -0,0 +1,111 @@
+/**
+ * Notification preferences and Web Push subscriptions
+ * (multiplayer-impl.md §5.4). Everything is off by default and claimed-only.
+ * Which channel an alert takes (a live `ev:notice` toast or a push) is the
+ * hub's decision; see `ev:notice`.
+ */
+import { z } from 'zod';
+import { Ok, Slug, UserId } from '../common';
+import { ErrorBody } from '../errors';
+import { requireActive, requireClaimed } from '../middleware';
+
+/** Notification preferences (`GET`/`PUT /social/notify`, `GET /social/me`). */
+export const NotifyPrefs = z.object({
+  /** Push a new DM when no tab is open. */
+  dm: z.boolean(),
+  /** Push a friend request when no tab is open. */
+  friend_request: z.boolean(),
+  /** "Tell me when any friend comes online", on top of the per-friend bells. */
+  friendOnlineAll: z.boolean(),
+  /** Friends whose bell is on, ascending. */
+  friendOnline: z.array(UserId),
+  /** Games followed for "someone's waiting in a lobby", sorted. */
+  lobbyOpen: z.array(Slug),
+});
+
+/** Notification preferences. */
+export type NotifyPrefs = z.infer<typeof NotifyPrefs>;
+
+/** The preference kinds `PUT /social/notify` can flip. */
+export const NotifyPrefKind = z.enum(['dm', 'friend_request', 'friend_online', 'lobby_open'], {
+  error: 'kind must be dm, friend_request, friend_online or lobby_open.',
+});
+
+/** A preference kind. */
+export type NotifyPrefKind = z.infer<typeof NotifyPrefKind>;
+
+/**
+ * One `PUT /social/notify` change. `target`: for `friend_online`, a friend's
+ * id (a number, or its decimal string) for that friend's bell, or absent
+ * (`''`, `null`) for the "any friend" switch; for `lobby_open`, the game slug.
+ * Ignored for `dm` and `friend_request`. Any other number or text is a 404
+ * (not a friend, no such game), as on the old hub. `enabled` is checked
+ * first, so its message wins when both fields are wrong.
+ */
+export const NotifyChange = z.object({
+  enabled: z.boolean({ error: 'enabled must be true or false.' }),
+  kind: NotifyPrefKind,
+  target: z.union([z.string(), z.number()]).nullable().optional(),
+});
+
+/** A notification preference change. */
+export type NotifyChange = z.infer<typeof NotifyChange>;
+
+/** The 400 for a subscription the hub can't push to (malformed, or not on a known push service). */
+export const UNSUPPORTED_SUBSCRIPTION = "That browser subscription isn't supported.";
+
+/**
+ * A browser push subscription, as `PushSubscription.toJSON()` gives it. The
+ * endpoint must be `https` on a known push service; `p256dh` is a 65-byte
+ * and `auth` an at-least-16-byte base64url key.
+ */
+export const PushSubscriptionJson = z.object({
+  endpoint: z.string().max(1000, { error: UNSUPPORTED_SUBSCRIPTION }),
+  /** When the subscription expires (epoch ms), `null` when it doesn't. */
+  expirationTime: z.number().nullable().optional(),
+  keys: z.object({
+    p256dh: z.string().max(200, { error: UNSUPPORTED_SUBSCRIPTION }),
+    auth: z.string().max(100, { error: UNSUPPORTED_SUBSCRIPTION }),
+  }),
+});
+
+/** A browser push subscription. */
+export type PushSubscriptionJson = z.infer<typeof PushSubscriptionJson>;
+
+/** The notification endpoints. */
+export const notifyEndpoints = {
+  ...requireActive.group({
+    getNotificationPreferences: {
+      method: 'GET', path: '/social/notify', response: NotifyPrefs,
+      errors: { 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: 'Your notification preferences (all off for guests)', tags: ['notify'] },
+    },
+    unsubscribeFromPush: {
+      method: 'DELETE', path: '/social/push',
+      body: z.object({ endpoint: z.string({ error: 'endpoint is required.' }).min(1, { error: 'endpoint is required.' }) }), response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: { summary: "Forget one of this account's push subscriptions", tags: ['notify'] },
+    },
+  }),
+  ...requireClaimed.group({
+    setNotificationPreferences: {
+      method: 'PUT', path: '/social/notify', body: NotifyChange, response: NotifyPrefs,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody, 404: ErrorBody, 409: ErrorBody },
+      doc: {
+        summary: 'Flip one notification preference',
+        description: '404 for a friend bell on a non-friend or an unknown game; 409 past 50 followed games.',
+        tags: ['notify'],
+      },
+    },
+    subscribeToPush: {
+      method: 'POST', path: '/social/push',
+      body: z.object({ subscription: z.union([PushSubscriptionJson, z.never()], { error: UNSUPPORTED_SUBSCRIPTION }) }), response: Ok,
+      errors: { 400: ErrorBody, 401: ErrorBody, 403: ErrorBody },
+      doc: {
+        summary: "Store this browser's push subscription",
+        description: 'One browser is one endpoint: subscribing from another account moves it. Past the per-user cap the oldest is dropped.',
+        tags: ['notify'],
+      },
+    },
+  }),
+};

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