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

package/src/api/notify.ts

@@ -1,111 +1,114 @@
-/**
- * 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 wants to play" (the game sheet's notify toggle):
+   * an open public lobby or race, or a tournament opening, 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/offline.ts

@@ -0,0 +1,45 @@
+/**
+ * Offline replay metadata: which public endpoints a client may queue while
+ * offline and send later, and how the hub makes a replay land exactly once.
+ *
+ * A replayable call carries a client-made operation key in the
+ * {@link OFFLINE_OP_HEADER} header. The hub remembers the reply to each key
+ * for {@link OFFLINE_DEDUPE_TTL_MS}; a second request with the same key gets
+ * that reply again without running the endpoint twice. Endpoints left out
+ * are online-only (social, multiplayer, trades) or replay on their own terms
+ * (analytics events are buffered and sent at least once, without a key).
+ */
+import { z } from 'zod';
+
+/** The request header that carries a replayable call's operation key. */
+export const OFFLINE_OP_HEADER = 'x-hub-op';
+
+/** An operation key: letters, digits and `_ . : -`, 1 to 100 characters. */
+export const OfflineOpKey = z.string().regex(/^[A-Za-z0-9_.:-]{1,100}$/);
+
+/** How long the hub remembers an operation key's reply: 7 days. */
+export const OFFLINE_DEDUPE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** How an endpoint behaves offline: `replay` means it may be queued and sent later, deduplicated by its operation key. */
+export type OfflineMode = 'replay';
+
+/** The public endpoints that support offline replay, by name. */
+export const OFFLINE_REPLAY_ENDPOINTS = {
+  writeSave: 'replay',
+  deleteSave: 'replay',
+  updateGameStat: 'replay',
+  setGameProfile: 'replay',
+  submitScore: 'replay',
+  completeDailyChallenge: 'replay',
+  grantInventoryItems: 'replay',
+  exchangeInventoryItems: 'replay',
+  setGameFavorite: 'replay',
+} as const satisfies Readonly<Record<string, OfflineMode>>;
+
+/** The name of an endpoint that supports offline replay. */
+export type OfflineReplayEndpoint = keyof typeof OFFLINE_REPLAY_ENDPOINTS;
+
+/** Whether endpoint `name` supports offline replay. */
+export function isOfflineReplayEndpoint(name: string): name is OfflineReplayEndpoint {
+  return Object.hasOwn(OFFLINE_REPLAY_ENDPOINTS, name);
+}