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

package/src/core/rest/rest-client.ts

@@ -1,152 +1,163 @@
-/**
- * The REST transport: a small fetch router over the contract's route table
- * (plan §12 A10). It splits one merged fields object into the path, query
- * and JSON body the way ayepi's client does, stamps `x-hub-client`, and turns
- * failures into {@link HubError}s. It carries no schemas: replies are typed
- * from the contract and trusted, as ayepi's zod-free client trusts them.
- */
-import { errorFor, HubError, readErrorFields, UNSUPPORTED_BY_HUB } from '../errors';
-import { isRecord } from '../storage/json-guards';
-import { HUB_CLIENT_VERSION } from '../version/client-version.gen';
-import type { EndpointFields, EndpointName, EndpointReply } from './endpoint-types';
-import { ROUTES } from './routes.gen';
-
-/** The header that tells the hub which client version is calling. */
-export const CLIENT_VERSION_HEADER = 'x-hub-client';
-
-/** What both hubs answer for a route they do not have. */
-const NO_SUCH_ENDPOINT = 'No such API endpoint.';
-
-/** How a {@link RestClient} reaches the hub. */
-export interface RestClientOptions {
-  /** The API's absolute base URL without a trailing slash, e.g. `https://diffenderfer.games/_api`. */
-  readonly apiBase: string;
-  /** The fetch to use. */
-  readonly fetch: typeof fetch;
-  /** Called whenever the hub answered at all (any status): the network is up. */
-  readonly onReachable?: () => void;
-}
-
-/** The arguments of a call: the fields, optional when the endpoint takes none that are required. */
-export type CallArguments<K extends EndpointName> = Partial<EndpointFields<K>> extends EndpointFields<K>
-  ? [fields?: EndpointFields<K>]
-  : [fields: EndpointFields<K>];
-
-/** Typed calls to the hub's public REST API. */
-export interface RestClient {
-  /** The API's absolute base URL. */
-  readonly apiBase: string;
-  /** Call an endpoint; resolves with its reply body, rejects with a {@link HubError}. */
-  call<K extends EndpointName>(name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
-}
-
-/** One field value as URL text. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a request field value of any contract type
-function urlText(fieldValue: unknown): string {
-  if (typeof fieldValue === 'string') {
-    return fieldValue;
-  }
-  if (typeof fieldValue === 'number' || typeof fieldValue === 'boolean') {
-    return String(fieldValue);
-  }
-  return JSON.stringify(fieldValue);
-}
-
-/** The request one call makes: its URL (under the API base), method and JSON body. */
-export interface PlannedRequest {
-  /** The path and query, e.g. `/games/pool/leaderboards/best?limit=50`. */
-  readonly pathAndQuery: string;
-  /** The HTTP method. */
-  readonly method: string;
-  /** The JSON body text, or `undefined` for none. */
-  readonly bodyText: string | undefined;
-}
-
-/**
- * Split merged fields into path, query and body for one endpoint: `:name`
- * segments take their field, query keys go to the query string, and the
- * rest is the JSON body. POST and PUT always send a body (`{}` when empty),
- * as the v1 client did; DELETE sends one only when it has fields.
- */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
-export function planRequest(name: EndpointName, fields: unknown): PlannedRequest {
-  const route = ROUTES[name];
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
-  const remaining = new Map<string, unknown>(Object.entries(isRecord(fields) ? fields : {}).filter(([, fieldValue]) => fieldValue !== undefined));
-  const path = route.path.replace(/:([A-Za-z]+)/g, (_segment, paramName: string) => {
-    const paramValue = remaining.get(paramName);
-    remaining.delete(paramName);
-    return encodeURIComponent(urlText(paramValue));
-  });
-  const queryKeys: readonly string[] = route.method === 'GET' ? [...remaining.keys()] : route.query;
-  const query = new URLSearchParams();
-  for (const key of queryKeys) {
-    const queryValue = remaining.get(key);
-    remaining.delete(key);
-    if (queryValue !== undefined && queryValue !== null) {
-      query.set(key, urlText(queryValue));
-    }
-  }
-  const queryText = query.toString();
-  const hasBody = route.method === 'POST' || route.method === 'PUT' || (route.method === 'DELETE' && remaining.size > 0);
-  return {
-    pathAndQuery: queryText === '' ? path : `${path}?${queryText}`,
-    method: route.method,
-    bodyText: hasBody ? JSON.stringify(Object.fromEntries(remaining)) : undefined,
-  };
-}
-
-/**
- * The reply body, typed by the contract. This is the client's one trust
- * boundary on replies: there is no zod in the browser bundle (plan D16).
- */
-async function readReply<Reply>(response: Response): Promise<Reply> {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- trust boundary: the hub's JSON reply, typed by the contract (the zod-free client trusts the server, plan D16)
-    return await response.json();
-  } catch {
-    throw new HubError('The hub sent a reply that is not JSON.', response.status);
-  }
-}
-
-/** The error for a failed response. */
-async function failureOf(name: EndpointName, response: Response): Promise<HubError> {
-  let fields = readErrorFields(undefined);
-  try {
-    fields = readErrorFields(await response.json());
-  } catch {
-    // A non-JSON error body keeps the generic message.
-  }
-  if (response.status === 404 && fields.error === NO_SUCH_ENDPOINT) {
-    return new HubError(`This hub does not have "${name}" yet: deploy the hub first, or use an older client.`, 404, { code: UNSUPPORTED_BY_HUB });
-  }
-  return errorFor(fields.error ?? `Request failed (${response.status})`, response.status, fields);
-}
-
-/** A REST client for one API base. */
-export function createRestClient(options: RestClientOptions): RestClient {
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
-  async function send<Reply>(name: EndpointName, fields: unknown): Promise<Reply> {
-    const planned = planRequest(name, fields);
-    let response: Response;
-    try {
-      response = await options.fetch(options.apiBase + planned.pathAndQuery, {
-        method: planned.method,
-        credentials: 'same-origin',
-        headers: { 'content-type': 'application/json', [CLIENT_VERSION_HEADER]: HUB_CLIENT_VERSION },
-        ...(planned.bodyText === undefined ? {} : { body: planned.bodyText }),
-      });
-    } catch (failure) {
-      throw new HubError(`Hub unreachable: ${failure instanceof Error ? failure.message : String(failure)}`);
-    }
-    options.onReachable?.();
-    if (!response.ok) {
-      throw await failureOf(name, response);
-    }
-    return readReply<Reply>(response);
-  }
-  return {
-    apiBase: options.apiBase,
-    call: (name, ...fieldsArgument) => send(name, fieldsArgument[0]),
-  };
-}
+/**
+ * The REST transport: a small fetch router over the contract's route table
+ * (plan §12 A10). It splits one merged fields object into the path, query
+ * and JSON body the way ayepi's client does, stamps `x-hub-client`, and turns
+ * failures into {@link HubError}s. It carries no schemas: replies are typed
+ * from the contract and trusted, as ayepi's zod-free client trusts them.
+ */
+import { errorFor, HubError, readErrorFields, UNSUPPORTED_BY_HUB } from '../errors';
+import { isRecord } from '../storage/json-guards';
+import { HUB_CLIENT_VERSION } from '../version/client-version.gen';
+import type { EndpointFields, EndpointName, EndpointReply } from './endpoint-types';
+import { OFFLINE_OP_HEADER, ROUTES } from './routes.gen';
+
+/** The header that tells the hub which client version is calling. */
+export const CLIENT_VERSION_HEADER = 'x-hub-client';
+
+/** What both hubs answer for a route they do not have. */
+const NO_SUCH_ENDPOINT = 'No such API endpoint.';
+
+/** How a {@link RestClient} reaches the hub. */
+export interface RestClientOptions {
+  /** The API's absolute base URL without a trailing slash, e.g. `https://diffenderfer.games/_api`. */
+  readonly apiBase: string;
+  /** The fetch to use. */
+  readonly fetch: typeof fetch;
+  /** Called whenever the hub answered at all (any status): the network is up. */
+  readonly onReachable?: () => void;
+}
+
+/** The arguments of a call: the fields, optional when the endpoint takes none that are required. */
+export type CallArguments<K extends EndpointName> = Partial<EndpointFields<K>> extends EndpointFields<K>
+  ? [fields?: EndpointFields<K>]
+  : [fields: EndpointFields<K>];
+
+/** Typed calls to the hub's public REST API. */
+export interface RestClient {
+  /** The API's absolute base URL. */
+  readonly apiBase: string;
+  /** Call an endpoint; resolves with its reply body, rejects with a {@link HubError}. */
+  call<K extends EndpointName>(name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
+  /**
+   * Call an endpoint as part of an offline operation: an endpoint marked for
+   * offline replay gets `opKey` in the operation header, so the hub runs it
+   * once however often it is sent; any other endpoint is called as usual.
+   */
+  callOnce<K extends EndpointName>(opKey: string, name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
+}
+
+/** One field value as URL text. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a request field value of any contract type
+function urlText(fieldValue: unknown): string {
+  if (typeof fieldValue === 'string') {
+    return fieldValue;
+  }
+  if (typeof fieldValue === 'number' || typeof fieldValue === 'boolean') {
+    return String(fieldValue);
+  }
+  return JSON.stringify(fieldValue);
+}
+
+/** The request one call makes: its URL (under the API base), method and JSON body. */
+export interface PlannedRequest {
+  /** The path and query, e.g. `/games/pool/leaderboards/best?limit=50`. */
+  readonly pathAndQuery: string;
+  /** The HTTP method. */
+  readonly method: string;
+  /** The JSON body text, or `undefined` for none. */
+  readonly bodyText: string | undefined;
+}
+
+/**
+ * Split merged fields into path, query and body for one endpoint: `:name`
+ * segments take their field, query keys go to the query string, and the
+ * rest is the JSON body. POST and PUT always send a body (`{}` when empty),
+ * as the v1 client did; DELETE sends one only when it has fields.
+ */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+export function planRequest(name: EndpointName, fields: unknown): PlannedRequest {
+  const route = ROUTES[name];
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+  const remaining = new Map<string, unknown>(Object.entries(isRecord(fields) ? fields : {}).filter(([, fieldValue]) => fieldValue !== undefined));
+  const path = route.path.replace(/:([A-Za-z]+)/g, (_segment, paramName: string) => {
+    const paramValue = remaining.get(paramName);
+    remaining.delete(paramName);
+    return encodeURIComponent(urlText(paramValue));
+  });
+  const queryKeys: readonly string[] = route.method === 'GET' ? [...remaining.keys()] : route.query;
+  const query = new URLSearchParams();
+  for (const key of queryKeys) {
+    const queryValue = remaining.get(key);
+    remaining.delete(key);
+    if (queryValue !== undefined && queryValue !== null) {
+      query.set(key, urlText(queryValue));
+    }
+  }
+  const queryText = query.toString();
+  const hasBody = route.method === 'POST' || route.method === 'PUT' || (route.method === 'DELETE' && remaining.size > 0);
+  return {
+    pathAndQuery: queryText === '' ? path : `${path}?${queryText}`,
+    method: route.method,
+    bodyText: hasBody ? JSON.stringify(Object.fromEntries(remaining)) : undefined,
+  };
+}
+
+/**
+ * The reply body, typed by the contract. This is the client's one trust
+ * boundary on replies: there is no zod in the browser bundle (plan D16).
+ */
+async function readReply<Reply>(response: Response): Promise<Reply> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- trust boundary: the hub's JSON reply, typed by the contract (the zod-free client trusts the server, plan D16)
+    return await response.json();
+  } catch {
+    throw new HubError('The hub sent a reply that is not JSON.', response.status);
+  }
+}
+
+/** The error for a failed response. */
+async function failureOf(name: EndpointName, response: Response): Promise<HubError> {
+  let fields = readErrorFields(undefined);
+  try {
+    fields = readErrorFields(await response.json());
+  } catch {
+    // A non-JSON error body keeps the generic message.
+  }
+  if (response.status === 404 && fields.error === NO_SUCH_ENDPOINT) {
+    return new HubError(`This hub does not have "${name}" yet: deploy the hub first, or use an older client.`, 404, { code: UNSUPPORTED_BY_HUB });
+  }
+  return errorFor(fields.error ?? `Request failed (${response.status})`, response.status, fields);
+}
+
+/** A REST client for one API base. */
+export function createRestClient(options: RestClientOptions): RestClient {
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+  async function send<Reply>(name: EndpointName, fields: unknown, opKey?: string): Promise<Reply> {
+    const planned = planRequest(name, fields);
+    let response: Response;
+    try {
+      response = await options.fetch(options.apiBase + planned.pathAndQuery, {
+        method: planned.method,
+        credentials: 'same-origin',
+        headers: {
+          'content-type': 'application/json',
+          [CLIENT_VERSION_HEADER]: HUB_CLIENT_VERSION,
+          ...(opKey !== undefined && ROUTES[name].offline === 'replay' ? { [OFFLINE_OP_HEADER]: opKey } : {}),
+        },
+        ...(planned.bodyText === undefined ? {} : { body: planned.bodyText }),
+      });
+    } catch (failure) {
+      throw new HubError(`Hub unreachable: ${failure instanceof Error ? failure.message : String(failure)}`);
+    }
+    options.onReachable?.();
+    if (!response.ok) {
+      throw await failureOf(name, response);
+    }
+    return readReply<Reply>(response);
+  }
+  return {
+    apiBase: options.apiBase,
+    call: (name, ...fieldsArgument) => send(name, fieldsArgument[0]),
+    callOnce: (opKey, name, ...fieldsArgument) => send(name, fieldsArgument[0], opKey),
+  };
+}

package/src/core/rest/routes.gen.ts

@@ -1,90 +1,111 @@
 // Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client` in next/.
-/** Every public REST endpoint's method, path (under `/_api`) and query keys, from the contract. */
+/** Every public REST endpoint's method, path (under `/_api`), query keys and offline mode (`'replay'` when it may be queued offline), from the contract. */
 export const ROUTES = {
-  ensureGuestSession: { method: 'POST', path: '/auth/guest', query: [] },
-  signUpWithPassword: { method: 'POST', path: '/auth/signup', query: [] },
-  logInWithPassword: { method: 'POST', path: '/auth/login', query: [] },
-  logOut: { method: 'POST', path: '/auth/logout', query: [] },
-  getCurrentUser: { method: 'GET', path: '/me', query: [] },
-  claimGuestAccount: { method: 'POST', path: '/auth/claim', query: [] },
-  listGames: { method: 'GET', path: '/games', query: [] },
-  listWhatsNewNotes: { method: 'GET', path: '/changes', query: ['game', 'since'] },
-  listFavoriteGames: { method: 'GET', path: '/favorites', query: [] },
-  setGameFavorite: { method: 'PUT', path: '/favorites/:slug', query: [] },
-  markWhatsNewSeen: { method: 'POST', path: '/changes/seen', query: [] },
-  getGameStats: { method: 'GET', path: '/games/:slug/stats', query: ['user'] },
-  getGameProfile: { method: 'GET', path: '/games/:slug/profile', query: [] },
-  setGameProfile: { method: 'PUT', path: '/games/:slug/profile', query: [] },
-  listSaves: { method: 'GET', path: '/games/:slug/saves', query: [] },
-  getSave: { method: 'GET', path: '/games/:slug/saves/:slot', query: [] },
-  writeSave: { method: 'PUT', path: '/games/:slug/saves/:slot', query: [] },
-  deleteSave: { method: 'DELETE', path: '/games/:slug/saves/:slot', query: [] },
-  updateGameStat: { method: 'POST', path: '/games/:slug/stats', query: [] },
-  resetMyGameProgress: { method: 'POST', path: '/games/:slug/reset', query: [] },
-  listMyLeaderboardRecords: { method: 'GET', path: '/me/records', query: ['game'] },
-  getMyOfflineSnapshot: { method: 'GET', path: '/me/snapshot', query: ['top'] },
-  listTopOfEveryLeaderboard: { method: 'GET', path: '/leaderboards', query: ['top'] },
-  listGameLeaderboards: { method: 'GET', path: '/games/:slug/leaderboards', query: [] },
-  getLeaderboard: { method: 'GET', path: '/games/:slug/leaderboards/:key', query: ['limit'] },
-  submitScore: { method: 'POST', path: '/games/:slug/leaderboards/:key/scores', query: [] },
-  listDailyChallengesForAllGames: { method: 'GET', path: '/daily', query: [] },
-  getGameDailyChallenges: { method: 'GET', path: '/games/:slug/daily', query: [] },
-  startDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/start', query: [] },
-  completeDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/complete', query: [] },
-  getMyInventory: { method: 'GET', path: '/games/:slug/inventory', query: [] },
-  grantInventoryItems: { method: 'POST', path: '/games/:slug/inventory/grant', query: [] },
-  exchangeInventoryItems: { method: 'POST', path: '/games/:slug/inventory/exchange', query: [] },
-  getPlayerInventory: { method: 'GET', path: '/games/:slug/players/:userId/inventory', query: [] },
-  listTradePartners: { method: 'GET', path: '/games/:slug/trades/players', query: [] },
-  listMyTrades: { method: 'GET', path: '/games/:slug/trades', query: ['box', 'status'] },
-  declineTrade: { method: 'POST', path: '/games/:slug/trades/:id/decline', query: [] },
-  cancelTrade: { method: 'POST', path: '/games/:slug/trades/:id/cancel', query: [] },
-  createTrade: { method: 'POST', path: '/games/:slug/trades', query: [] },
-  acceptTrade: { method: 'POST', path: '/games/:slug/trades/:id/accept', query: [] },
-  counterTradeOffer: { method: 'POST', path: '/games/:slug/trades/:id/counter', query: [] },
-  getSiteAnalytics: { method: 'GET', path: '/analytics', query: [] },
-  reportClientError: { method: 'POST', path: '/client-log', query: [] },
-  recordGameEvent: { method: 'POST', path: '/games/:slug/events', query: [] },
-  getGameAnalytics: { method: 'GET', path: '/games/:slug/analytics', query: [] },
-  getSocialConfig: { method: 'GET', path: '/social/config', query: [] },
-  getOnlineCounts: { method: 'GET', path: '/social/counts', query: [] },
-  getMySocialProfile: { method: 'GET', path: '/social/me', query: [] },
-  listFriendsAndRequests: { method: 'GET', path: '/social/friends', query: [] },
-  findPlayerByName: { method: 'GET', path: '/social/players/by-name/:name', query: [] },
-  getPlayerCard: { method: 'GET', path: '/social/players/:id', query: [] },
-  updateMySocialProfile: { method: 'PUT', path: '/social/me', query: [] },
-  setParentChatLock: { method: 'POST', path: '/social/chat-lock', query: [] },
-  sendFriendRequest: { method: 'POST', path: '/social/friends', query: [] },
-  acceptFriendRequest: { method: 'POST', path: '/social/friends/:id/accept', query: [] },
-  declineFriendRequest: { method: 'POST', path: '/social/friends/:id/decline', query: [] },
-  removeFriend: { method: 'DELETE', path: '/social/friends/:id', query: [] },
-  setFriendNotifications: { method: 'PUT', path: '/social/friends/:id/notify', query: [] },
-  blockPlayer: { method: 'POST', path: '/social/blocks', query: [] },
-  unblockPlayer: { method: 'DELETE', path: '/social/blocks/:id', query: [] },
-  listRecentPlayers: { method: 'GET', path: '/social/recent', query: [] },
-  listConversations: { method: 'GET', path: '/social/conversations', query: [] },
-  listDirectMessages: { method: 'GET', path: '/social/messages/:userId', query: ['before'] },
-  sendDirectMessage: { method: 'POST', path: '/social/messages/:userId', query: [] },
-  markDirectMessagesRead: { method: 'POST', path: '/social/messages/:userId/read', query: [] },
-  getNotificationPreferences: { method: 'GET', path: '/social/notify', query: [] },
-  unsubscribeFromPush: { method: 'DELETE', path: '/social/push', query: [] },
-  setNotificationPreferences: { method: 'PUT', path: '/social/notify', query: [] },
-  subscribeToPush: { method: 'POST', path: '/social/push', query: [] },
-  fileReport: { method: 'POST', path: '/social/reports', query: [] },
-  listPublicSuggestions: { method: 'GET', path: '/suggestions', query: ['sort'] },
-  submitSuggestion: { method: 'POST', path: '/suggestions', query: [] },
-  voteForSuggestion: { method: 'POST', path: '/suggestions/:id/vote', query: [] },
-  removeSuggestionVote: { method: 'DELETE', path: '/suggestions/:id/vote', query: [] },
-  withdrawSuggestion: { method: 'DELETE', path: '/suggestions/:id', query: [] },
-  sendGameInvite: { method: 'POST', path: '/mp/invites', query: [] },
-  acceptGameInvite: { method: 'POST', path: '/mp/invites/:id/accept', query: [] },
-  declineGameInvite: { method: 'POST', path: '/mp/invites/:id/decline', query: [] },
-  cancelGameInvite: { method: 'DELETE', path: '/mp/invites/:id', query: [] },
-  redeemLaunchToken: { method: 'GET', path: '/mp/launch/:token', query: [] },
-  setPartyJoinInfo: { method: 'POST', path: '/mp/parties/:id/join-info', query: [] },
-  leaveParty: { method: 'POST', path: '/mp/parties/:id/leave', query: [] },
-  launchIntoFriendsRoom: { method: 'POST', path: '/mp/join', query: [] },
-  getGameServerTicket: { method: 'POST', path: '/mp/ticket', query: [] },
-  listMyRaceHistory: { method: 'GET', path: '/race/history', query: ['game', 'with', 'before', 'limit'] },
-  getHubVersion: { method: 'GET', path: '/version', query: [] },
+  ensureGuestSession: { method: 'POST', path: '/auth/guest', query: [], offline: null },
+  signUpWithPassword: { method: 'POST', path: '/auth/signup', query: [], offline: null },
+  logInWithPassword: { method: 'POST', path: '/auth/login', query: [], offline: null },
+  logOut: { method: 'POST', path: '/auth/logout', query: [], offline: null },
+  getCurrentUser: { method: 'GET', path: '/me', query: [], offline: null },
+  claimGuestAccount: { method: 'POST', path: '/auth/claim', query: [], offline: null },
+  getGamePlayerCounts: { method: 'GET', path: '/catalog/players', query: [], offline: null },
+  getMyGameActivity: { method: 'GET', path: '/games/:slug/me/activity', query: [], offline: null },
+  listGames: { method: 'GET', path: '/games', query: [], offline: null },
+  listWhatsNewNotes: { method: 'GET', path: '/changes', query: ['game', 'since'], offline: null },
+  listFavoriteGames: { method: 'GET', path: '/favorites', query: [], offline: null },
+  setGameFavorite: { method: 'PUT', path: '/favorites/:slug', query: [], offline: 'replay' },
+  markWhatsNewSeen: { method: 'POST', path: '/changes/seen', query: [], offline: null },
+  getGameStats: { method: 'GET', path: '/games/:slug/stats', query: ['user'], offline: null },
+  getGameProfile: { method: 'GET', path: '/games/:slug/profile', query: [], offline: null },
+  setGameProfile: { method: 'PUT', path: '/games/:slug/profile', query: [], offline: 'replay' },
+  listSaves: { method: 'GET', path: '/games/:slug/saves', query: [], offline: null },
+  getSave: { method: 'GET', path: '/games/:slug/saves/:slot', query: [], offline: null },
+  writeSave: { method: 'PUT', path: '/games/:slug/saves/:slot', query: [], offline: 'replay' },
+  deleteSave: { method: 'DELETE', path: '/games/:slug/saves/:slot', query: [], offline: 'replay' },
+  updateGameStat: { method: 'POST', path: '/games/:slug/stats', query: [], offline: 'replay' },
+  resetMyGameProgress: { method: 'POST', path: '/games/:slug/reset', query: [], offline: null },
+  listMyLeaderboardRecords: { method: 'GET', path: '/me/records', query: ['game'], offline: null },
+  getMyOfflineSnapshot: { method: 'GET', path: '/me/snapshot', query: ['top'], offline: null },
+  listTopOfEveryLeaderboard: { method: 'GET', path: '/leaderboards', query: ['top'], offline: null },
+  listGameLeaderboards: { method: 'GET', path: '/games/:slug/leaderboards', query: [], offline: null },
+  getLeaderboard: { method: 'GET', path: '/games/:slug/leaderboards/:key', query: ['limit'], offline: null },
+  submitScore: { method: 'POST', path: '/games/:slug/leaderboards/:key/scores', query: [], offline: 'replay' },
+  listDailyChallengesForAllGames: { method: 'GET', path: '/daily', query: [], offline: null },
+  getGameDailyChallenges: { method: 'GET', path: '/games/:slug/daily', query: [], offline: null },
+  startDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/start', query: [], offline: null },
+  completeDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/complete', query: [], offline: 'replay' },
+  getMyInventory: { method: 'GET', path: '/games/:slug/inventory', query: [], offline: null },
+  grantInventoryItems: { method: 'POST', path: '/games/:slug/inventory/grant', query: [], offline: 'replay' },
+  exchangeInventoryItems: { method: 'POST', path: '/games/:slug/inventory/exchange', query: [], offline: 'replay' },
+  getPlayerInventory: { method: 'GET', path: '/games/:slug/players/:userId/inventory', query: [], offline: null },
+  listTradePartners: { method: 'GET', path: '/games/:slug/trades/players', query: [], offline: null },
+  listMyTrades: { method: 'GET', path: '/games/:slug/trades', query: ['box', 'status'], offline: null },
+  declineTrade: { method: 'POST', path: '/games/:slug/trades/:id/decline', query: [], offline: null },
+  cancelTrade: { method: 'POST', path: '/games/:slug/trades/:id/cancel', query: [], offline: null },
+  createTrade: { method: 'POST', path: '/games/:slug/trades', query: [], offline: null },
+  acceptTrade: { method: 'POST', path: '/games/:slug/trades/:id/accept', query: [], offline: null },
+  counterTradeOffer: { method: 'POST', path: '/games/:slug/trades/:id/counter', query: [], offline: null },
+  getSiteAnalytics: { method: 'GET', path: '/analytics', query: [], offline: null },
+  reportClientError: { method: 'POST', path: '/client-log', query: [], offline: null },
+  recordGameEvent: { method: 'POST', path: '/games/:slug/events', query: [], offline: null },
+  getGameAnalytics: { method: 'GET', path: '/games/:slug/analytics', query: [], offline: null },
+  getSocialConfig: { method: 'GET', path: '/social/config', query: [], offline: null },
+  getOnlineCounts: { method: 'GET', path: '/social/counts', query: [], offline: null },
+  getMySocialProfile: { method: 'GET', path: '/social/me', query: [], offline: null },
+  listFriendsAndRequests: { method: 'GET', path: '/social/friends', query: [], offline: null },
+  findPlayerByName: { method: 'GET', path: '/social/players/by-name/:name', query: [], offline: null },
+  getPlayerCard: { method: 'GET', path: '/social/players/:id', query: [], offline: null },
+  updateMySocialProfile: { method: 'PUT', path: '/social/me', query: [], offline: null },
+  setParentChatLock: { method: 'POST', path: '/social/chat-lock', query: [], offline: null },
+  sendFriendRequest: { method: 'POST', path: '/social/friends', query: [], offline: null },
+  acceptFriendRequest: { method: 'POST', path: '/social/friends/:id/accept', query: [], offline: null },
+  declineFriendRequest: { method: 'POST', path: '/social/friends/:id/decline', query: [], offline: null },
+  removeFriend: { method: 'DELETE', path: '/social/friends/:id', query: [], offline: null },
+  setFriendNotifications: { method: 'PUT', path: '/social/friends/:id/notify', query: [], offline: null },
+  blockPlayer: { method: 'POST', path: '/social/blocks', query: [], offline: null },
+  unblockPlayer: { method: 'DELETE', path: '/social/blocks/:id', query: [], offline: null },
+  listRecentPlayers: { method: 'GET', path: '/social/recent', query: [], offline: null },
+  listConversations: { method: 'GET', path: '/social/conversations', query: [], offline: null },
+  listDirectMessages: { method: 'GET', path: '/social/messages/:userId', query: ['before'], offline: null },
+  sendDirectMessage: { method: 'POST', path: '/social/messages/:userId', query: [], offline: null },
+  markDirectMessagesRead: { method: 'POST', path: '/social/messages/:userId/read', query: [], offline: null },
+  getNotificationPreferences: { method: 'GET', path: '/social/notify', query: [], offline: null },
+  unsubscribeFromPush: { method: 'DELETE', path: '/social/push', query: [], offline: null },
+  setNotificationPreferences: { method: 'PUT', path: '/social/notify', query: [], offline: null },
+  subscribeToPush: { method: 'POST', path: '/social/push', query: [], offline: null },
+  fileReport: { method: 'POST', path: '/social/reports', query: [], offline: null },
+  listPublicSuggestions: { method: 'GET', path: '/suggestions', query: ['sort'], offline: null },
+  submitSuggestion: { method: 'POST', path: '/suggestions', query: [], offline: null },
+  voteForSuggestion: { method: 'POST', path: '/suggestions/:id/vote', query: [], offline: null },
+  removeSuggestionVote: { method: 'DELETE', path: '/suggestions/:id/vote', query: [], offline: null },
+  withdrawSuggestion: { method: 'DELETE', path: '/suggestions/:id', query: [], offline: null },
+  sendGameInvite: { method: 'POST', path: '/mp/invites', query: [], offline: null },
+  acceptGameInvite: { method: 'POST', path: '/mp/invites/:id/accept', query: [], offline: null },
+  declineGameInvite: { method: 'POST', path: '/mp/invites/:id/decline', query: [], offline: null },
+  createInviteLink: { method: 'POST', path: '/mp/links', query: [], offline: null },
+  listInviteLinks: { method: 'GET', path: '/mp/links', query: ['game'], offline: null },
+  revokeInviteLink: { method: 'DELETE', path: '/mp/links/:token', query: [], offline: null },
+  cancelGameInvite: { method: 'DELETE', path: '/mp/invites/:id', query: [], offline: null },
+  redeemLaunchToken: { method: 'GET', path: '/mp/launch/:token', query: [], offline: null },
+  openInviteLink: { method: 'POST', path: '/mp/links/:token/open', query: [], offline: null },
+  setPartyJoinInfo: { method: 'POST', path: '/mp/parties/:id/join-info', query: [], offline: null },
+  leaveParty: { method: 'POST', path: '/mp/parties/:id/leave', query: [], offline: null },
+  launchIntoFriendsRoom: { method: 'POST', path: '/mp/join', query: [], offline: null },
+  getGameServerTicket: { method: 'POST', path: '/mp/ticket', query: [], offline: null },
+  listMyRaceHistory: { method: 'GET', path: '/race/history', query: ['game', 'with', 'before', 'limit'], offline: null },
+  listTournaments: { method: 'GET', path: '/tournaments', query: ['game'], offline: null },
+  getTournament: { method: 'GET', path: '/tournaments/:id', query: ['key'], offline: null },
+  createTournament: { method: 'POST', path: '/tournaments', query: [], offline: null },
+  inviteToTournament: { method: 'POST', path: '/tournaments/:id/invites', query: [], offline: null },
+  followTournament: { method: 'PUT', path: '/tournaments/:id/follow', query: [], offline: null },
+  unfollowTournament: { method: 'DELETE', path: '/tournaments/:id/follow', query: [], offline: null },
+  startTournament: { method: 'POST', path: '/tournaments/:id/start', query: [], offline: null },
+  cancelTournament: { method: 'DELETE', path: '/tournaments/:id', query: [], offline: null },
+  joinTournament: { method: 'POST', path: '/tournaments/:id/join', query: [], offline: null },
+  leaveTournament: { method: 'POST', path: '/tournaments/:id/leave', query: [], offline: null },
+  launchTournamentMatch: { method: 'POST', path: '/tournaments/:id/matches/:match/launch', query: [], offline: null },
+  getPlayOnline: { method: 'GET', path: '/play-online', query: [], offline: null },
+  getHubVersion: { method: 'GET', path: '/version', query: [], offline: null },
 } as const;
+
+/** The request header that carries an offline operation key (the contract's `OFFLINE_OP_HEADER`). */
+export const OFFLINE_OP_HEADER = 'x-hub-op';