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

package/src/api/mp.ts

@@ -1,110 +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'] },
-    },
-  }),
-};
+/**
+ * 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

@@ -1,111 +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'],
-      },
-    },
-  }),
-};
+/**
+ * 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'],
+      },
+    },
+  }),
+};