@oxyhq/core 10.2.0 → 11.0.1

package/src/logger/index.ts

@@ -0,0 +1,217 @@
+/**
+ * @oxyhq/core/logger — the ecosystem-wide logging chokepoint.
+ *
+ * A tiny, dependency-free, universal logger that works unchanged in React
+ * Native, browsers, Node, and Bun. Every Oxy app and package should log
+ * through here instead of calling `console.*` directly, so that level,
+ * formatting, and transport are controlled in ONE place.
+ *
+ * Design goals:
+ *  - Zero dependencies. No Node-only imports, no `process.stdout` assumptions.
+ *  - Four levels (`debug` | `info` | `warn` | `error`) plus `silent`.
+ *  - Namespaced child loggers via `createLogger('mention:feed')` / `.child()`.
+ *  - Structured context objects carried through to the sink.
+ *  - A single pluggable sink so backends can pipe to pino / CloudWatch / etc.
+ *    without touching any call site.
+ *  - Debug is off in production by default (`__DEV__` on RN, `NODE_ENV`
+ *    elsewhere); override globally with `configureLogger({ level })`.
+ *
+ * @module logger
+ */
+
+/* global __DEV__ */
+declare const __DEV__: boolean | undefined;
+
+/** Ordered severity levels. `silent` disables all output. */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+
+/** The levels that actually emit an entry (everything but `silent`). */
+export type EmittableLogLevel = Exclude<LogLevel, 'silent'>;
+
+const LEVEL_WEIGHT: Record<LogLevel, number> = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+/**
+ * Structured, JSON-friendly context attached to a log line. The well-known
+ * keys are optional hints; arbitrary keys are allowed so callers can attach
+ * whatever structured fields their sink cares about.
+ */
+export interface LogContext {
+  component?: string;
+  method?: string;
+  userId?: string;
+  sessionId?: string;
+  requestId?: string;
+  [key: string]: unknown;
+}
+
+/** A single normalized log record handed to the active sink. */
+export interface LogEntry {
+  level: EmittableLogLevel;
+  message: string;
+  /** Colon-joined namespace, e.g. `mention:feed`. Absent for the root logger. */
+  namespace?: string;
+  /** Merged structured context (logger base context + per-call context). */
+  context?: LogContext;
+  /** The error value passed to `.error(message, error, …)`, if any. */
+  error?: unknown;
+  /** Extra variadic args passed after the context. */
+  args: unknown[];
+  /** ISO-8601 timestamp of when the entry was created. */
+  timestamp: string;
+}
+
+/** A transport that receives every emitted (level-passing) entry. */
+export type LogSink = (entry: LogEntry) => void;
+
+/** Global logger configuration. */
+export interface LoggerConfig {
+  level: LogLevel;
+  sink: LogSink;
+}
+
+/** A namespaced logger. Instances are cheap; derive children with `.child()`. */
+export interface Logger {
+  /** The logger's colon-joined namespace, if any. */
+  readonly namespace?: string;
+  debug(message: string, context?: LogContext, ...args: unknown[]): void;
+  info(message: string, context?: LogContext, ...args: unknown[]): void;
+  warn(message: string, context?: LogContext, ...args: unknown[]): void;
+  error(message: string, error?: unknown, context?: LogContext, ...args: unknown[]): void;
+  /** Derive a child logger with an extended namespace and merged base context. */
+  child(namespace: string, context?: LogContext): Logger;
+}
+
+/**
+ * True in development. Uses React Native's `__DEV__` when present, otherwise
+ * falls back to `process.env.NODE_ENV === 'development'`. Never throws.
+ */
+export function isDev(): boolean {
+  if (typeof __DEV__ !== 'undefined') return __DEV__ === true;
+  try {
+    return typeof process !== 'undefined' && process.env?.NODE_ENV === 'development';
+  } catch {
+    return false;
+  }
+}
+
+function formatPrefix(entry: LogEntry): string {
+  const parts = [entry.timestamp, entry.level.toUpperCase()];
+  if (entry.namespace) parts.push(`[${entry.namespace}]`);
+  return parts.join(' ');
+}
+
+/**
+ * Default sink: routes each entry to the matching `console` method. `info` and
+ * `debug` go to `console.log` (RN/browser-safe — `console.debug`/`console.info`
+ * are inconsistently surfaced across runtimes).
+ */
+export const consoleSink: LogSink = (entry) => {
+  const extras: unknown[] = [];
+  if (entry.context && Object.keys(entry.context).length > 0) extras.push(entry.context);
+  if (entry.error !== undefined) extras.push(entry.error);
+  if (entry.args.length > 0) extras.push(...entry.args);
+
+  const line = `${formatPrefix(entry)} ${entry.message}`;
+  if (entry.level === 'error') console.error(line, ...extras);
+  else if (entry.level === 'warn') console.warn(line, ...extras);
+  else console.log(line, ...extras);
+};
+
+function defaultLevel(): LogLevel {
+  return isDev() ? 'debug' : 'info';
+}
+
+const config: LoggerConfig = {
+  level: defaultLevel(),
+  sink: consoleSink,
+};
+
+/**
+ * Update the global logger configuration. Affects every logger instance
+ * (root and children) immediately. Pass `{ level }` to gate output and/or
+ * `{ sink }` to redirect transport (pino, CloudWatch, a test capture, …).
+ */
+export function configureLogger(partial: Partial<LoggerConfig>): void {
+  if (partial.level !== undefined) config.level = partial.level;
+  if (partial.sink !== undefined) config.sink = partial.sink;
+}
+
+/** Read a snapshot of the current global configuration. */
+export function getLoggerConfig(): Readonly<LoggerConfig> {
+  return { level: config.level, sink: config.sink };
+}
+
+/** Restore the default level (env-derived) and the console sink. */
+export function resetLoggerConfig(): void {
+  config.level = defaultLevel();
+  config.sink = consoleSink;
+}
+
+function mergeContext(base?: LogContext, extra?: LogContext): LogContext | undefined {
+  if (!base) return extra;
+  if (!extra) return base;
+  return { ...base, ...extra };
+}
+
+function emit(
+  level: EmittableLogLevel,
+  namespace: string | undefined,
+  baseContext: LogContext | undefined,
+  message: string,
+  error: unknown,
+  context: LogContext | undefined,
+  args: unknown[],
+): void {
+  if (LEVEL_WEIGHT[level] > LEVEL_WEIGHT[config.level]) return;
+  config.sink({
+    level,
+    message,
+    namespace,
+    context: mergeContext(baseContext, context),
+    error,
+    args,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+function makeLogger(namespace: string | undefined, baseContext: LogContext | undefined): Logger {
+  return {
+    namespace,
+    debug: (message, context, ...args) =>
+      emit('debug', namespace, baseContext, message, undefined, context, args),
+    info: (message, context, ...args) =>
+      emit('info', namespace, baseContext, message, undefined, context, args),
+    warn: (message, context, ...args) =>
+      emit('warn', namespace, baseContext, message, undefined, context, args),
+    error: (message, error, context, ...args) =>
+      emit('error', namespace, baseContext, message, error, context, args),
+    child: (childNamespace, childContext) =>
+      makeLogger(
+        namespace ? `${namespace}:${childNamespace}` : childNamespace,
+        mergeContext(baseContext, childContext),
+      ),
+  };
+}
+
+/** The shared root logger. Prefer a namespaced `createLogger(...)` in modules. */
+export const logger: Logger = makeLogger(undefined, undefined);
+
+/**
+ * Create a namespaced logger.
+ *
+ * @example
+ * ```ts
+ * const log = createLogger('mention:feed');
+ * log.info('loaded', { count: 20 });
+ * const sub = log.child('prefetch'); // namespace → 'mention:feed:prefetch'
+ * ```
+ */
+export function createLogger(namespace?: string, context?: LogContext): Logger {
+  return makeLogger(namespace, context);
+}

package/src/mixins/OxyServices.assets.ts

@@ -1,7 +1,7 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, RNFileDescriptor, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '@oxyhq/protocol';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { extractErrorStatus } from '../utils/errorUtils';
 
 /**
@@ -428,8 +428,8 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
 
         return response;
       } catch (error) {
-        console.error('File upload error:', error);
-        
+        logger.error('File upload error', error, { component: 'OxyServices.assets' });
+
         let errorMessage = 'File upload failed';
         
         if (error instanceof Error) {

package/src/mixins/OxyServices.auth.ts

@@ -13,7 +13,7 @@ import { OxyAuthenticationError } from '../OxyServices.errors';
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { loadNodeCrypto } from '@oxyhq/protocol';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
 
 /**
@@ -1196,6 +1196,139 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * Begin a WebAuthn / passkey REGISTRATION ceremony. Requests the
+     * `PublicKeyCredentialCreationOptions` the browser's `navigator.credentials
+     * .create()` (or `@simplewebauthn/browser`'s `startRegistration`) needs.
+     *
+     * With a bearer token planted this links a passkey to the signed-in account
+     * (`username` ignored); without one it is a prospective signup and `username`
+     * is the desired handle. The returned options are OPAQUE — Oxy does not own
+     * their shape (the browser / `@simplewebauthn` does), so they pass through
+     * as `unknown` for the caller to hand straight to the ceremony.
+     */
+    async webauthnRegisterOptions(username?: string): Promise<unknown> {
+      try {
+        return await this.makeRequest<unknown>(
+          'POST',
+          '/auth/webauthn/register/options',
+          { ...(username !== undefined ? { username } : {}) },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Finish a WebAuthn / passkey REGISTRATION ceremony. Forwards the opaque
+     * browser `RegistrationResponseJSON` (`response`) alongside the Oxy envelope
+     * (desired `username` for signup + the device-session naming fields).
+     *
+     * Two server branches, disambiguated by the response shape:
+     *  - **Signup** (no bearer): the account is created and a session minted —
+     *    the response carries `sessionId`, is the SAME {@link LoginResult}
+     *    contract as `POST /auth/verify`, and its access token is planted here.
+     *  - **Link** (bearer present): the passkey is attached to the signed-in
+     *    account and the server returns `{ success, message }` with no session,
+     *    which is returned verbatim (no token planting).
+     */
+    async webauthnRegisterVerify(
+      response: unknown,
+      envelope: {
+        username?: string;
+        deviceName?: string;
+        deviceFingerprint?: string;
+        deviceId?: string;
+      } = {},
+    ): Promise<{ success: true; message: string } | LoginResult> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/webauthn/register/verify',
+          { response, ...envelope },
+          { cache: false },
+        );
+        if (res && typeof res === 'object') {
+          const record = res as Record<string, unknown>;
+          // Signup branch: mints a session (LoginSessionResult, carries
+          // `sessionId`). Parse against the login contract and plant the token.
+          if ('sessionId' in record) {
+            const parsed = safeParseContract(loginResultSchema, record);
+            if (!parsed) {
+              throw new Error('auth/webauthn/register/verify returned an unexpected response shape');
+            }
+            if (!('twoFactorRequired' in parsed) && parsed.accessToken) {
+              this.setTokens(parsed.accessToken);
+            }
+            return parsed;
+          }
+          // Link branch: passkey attached to the signed-in account, no session.
+          if (record.success === true && typeof record.message === 'string') {
+            return { success: true, message: record.message };
+          }
+        }
+        throw new Error('auth/webauthn/register/verify returned an unexpected response shape');
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Begin a WebAuthn / passkey AUTHENTICATION ceremony. Requests the
+     * `PublicKeyCredentialRequestOptions` the browser's `navigator.credentials
+     * .get()` (or `@simplewebauthn/browser`'s `startAuthentication`) needs.
+     *
+     * When `username` is present the server scopes `allowCredentials` to that
+     * user's passkeys (username-first); when omitted it returns an empty
+     * allow-list for the usernameless / discoverable-credential flow. The
+     * returned options are OPAQUE and pass through as `unknown`.
+     */
+    async webauthnLoginOptions(username?: string): Promise<unknown> {
+      try {
+        return await this.makeRequest<unknown>(
+          'POST',
+          '/auth/webauthn/login/options',
+          { ...(username !== undefined ? { username } : {}) },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Finish a WebAuthn / passkey AUTHENTICATION ceremony. Forwards the opaque
+     * browser `AuthenticationResponseJSON` (`response`) alongside the
+     * device-session envelope. Resolves to the SAME {@link LoginResult} contract
+     * as `POST /auth/verify`; on the session arm the access token is planted
+     * immediately (mirroring {@link passwordSignIn}), and the response's
+     * `deviceId` + `deviceSecret` are the zero-cookie restore credential.
+     */
+    async webauthnLoginVerify(
+      response: unknown,
+      envelope: { deviceName?: string; deviceFingerprint?: string; deviceId?: string } = {},
+    ): Promise<LoginResult> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/webauthn/login/verify',
+          { response, ...envelope },
+          { cache: false },
+        );
+        const parsed = safeParseContract(loginResultSchema, res);
+        if (!parsed) {
+          throw new Error('auth/webauthn/login/verify returned an unexpected response shape');
+        }
+        if (!('twoFactorRequired' in parsed) && parsed.accessToken) {
+          this.setTokens(parsed.accessToken);
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Exchange an OAuth authorization code (returned to the RP redirect URI
      * after password sign-in at auth.oxy.so) for a device-first session.

package/src/mixins/OxyServices.language.ts

@@ -5,7 +5,7 @@ import { normalizeLocale, getPrimaryLanguage, getLanguageMetadata, getLanguageNa
 import type { SupportedLanguage } from '../utils/languageUtils';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { loadAsyncStorage } from '@oxyhq/protocol';
-import { isDev } from '../shared/utils/debugUtils';
+import { logger } from '../logger';
 
 /**
  * Cross-mixin surface consumed by the language methods. `getCurrentUser` is
@@ -48,7 +48,7 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
             removeItem: storage.removeItem.bind(storage),
           };
         } catch (error) {
-          console.error('AsyncStorage not available in React Native:', error);
+          logger.error('AsyncStorage not available in React Native', error, { component: 'OxyServices.language' });
           throw new Error('AsyncStorage is required in React Native environment');
         }
       } else {
@@ -103,9 +103,7 @@ export function OxyServicesLanguageMixin<T extends typeof OxyServicesBase>(Base:
 
         return null;
       } catch (error) {
-        if (isDev()) {
-          console.warn('Failed to get current language:', error);
-        }
+        logger.warn('Failed to get current language', { component: 'OxyServices.language' }, error);
         return null;
       }
     }

package/src/mixins/OxyServices.privacy.ts

@@ -3,7 +3,7 @@
  */
 import type { BlockedUser, RestrictedUser } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
-import { isDev } from '../shared/utils/debugUtils';
+import { logger } from '../logger';
 
 export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -36,9 +36,7 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         });
       } catch (error) {
         // If there's an error, assume not in list to avoid breaking functionality
-        if (isDev()) {
-          console.warn('Error checking user list:', error);
-        }
+        logger.warn('Error checking user list', { component: 'OxyServices.privacy' }, error);
         return false;
       }
     }

package/src/mixins/OxyServices.security.ts

@@ -3,7 +3,7 @@
  */
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { SecurityActivity, SecurityActivityResponse, SecurityEventType } from '../models/interfaces';
-import { isDev } from '../shared/utils/debugUtils';
+import { logger } from '../logger';
 
 export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
@@ -80,11 +80,9 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
           { cache: false }
         );
       } catch (error) {
-        // Don't throw - logging failures shouldn't break user flow
-        // But log for monitoring
-        if (isDev()) {
-          console.warn('[OxyServices] Failed to log private key exported event:', error);
-        }
+        // Don't throw - logging failures shouldn't break user flow, but surface
+        // for monitoring via the shared logger sink.
+        logger.warn('[OxyServices] Failed to log private key exported event', { component: 'OxyServices.security' }, error);
       }
     }
 
@@ -102,11 +100,9 @@ export function OxyServicesSecurityMixin<T extends typeof OxyServicesBase>(Base:
           { cache: false }
         );
       } catch (error) {
-        // Don't throw - logging failures shouldn't break user flow
-        // But log for monitoring
-        if (isDev()) {
-          console.warn('[OxyServices] Failed to log backup created event:', error);
-        }
+        // Don't throw - logging failures shouldn't break user flow, but surface
+        // for monitoring via the shared logger sink.
+        logger.warn('[OxyServices] Failed to log backup created event', { component: 'OxyServices.security' }, error);
       }
     }
   };

package/src/mixins/OxyServices.topics.ts

@@ -4,7 +4,7 @@
  * Provides methods for topic discovery and management
  */
 import type { OxyServicesBase } from '../OxyServices.base';
-import type { TopicData, TopicTranslation } from '../models/Topic';
+import type { TopicData, TopicListResult, TopicTranslation } from '../models/Topic';
 import { CACHE_TIMES } from './mixinHelpers';
 
 export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T) {
@@ -22,10 +22,15 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       try {
         const params: Record<string, string> = {};
         if (locale) params.locale = locale;
-        return await this.makeRequest('GET', '/topics/categories', params, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.EXTRA_LONG,
-        });
+        // `GET /topics/categories` returns `{ categories: TopicData[] }` — the
+        // SDK's `unwrapResponse` only unwraps `{ data }`, so unwrap here.
+        const response = await this.makeRequest<{ categories: TopicData[] }>(
+          'GET',
+          '/topics/categories',
+          params,
+          { cache: true, cacheTTL: CACHE_TIMES.EXTRA_LONG }
+        );
+        return response.categories ?? [];
       } catch (error) {
         throw this.handleError(error);
       }
@@ -41,9 +46,14 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       try {
         const params: Record<string, string | number> = { q: query };
         if (limit) params.limit = limit;
-        return await this.makeRequest('GET', '/topics/search', params, {
-          cache: false,
-        });
+        // `GET /topics/search` returns `{ topics: TopicData[] }` — unwrap it.
+        const response = await this.makeRequest<{ topics: TopicData[] }>(
+          'GET',
+          '/topics/search',
+          params,
+          { cache: false }
+        );
+        return response.topics ?? [];
       } catch (error) {
         throw this.handleError(error);
       }
@@ -52,7 +62,7 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
     /**
      * List topics with optional filters
      * @param options - Filter and pagination options
-     * @returns List of topics
+     * @returns Paginated topics envelope (`topics` plus `total`/`limit`/`offset`)
      */
     async listTopics(options?: {
       type?: string;
@@ -60,7 +70,7 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       limit?: number;
       offset?: number;
       locale?: string;
-    }): Promise<TopicData[]> {
+    }): Promise<TopicListResult> {
       try {
         const params: Record<string, string | number> = {};
         if (options?.type) params.type = options.type;
@@ -68,10 +78,23 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
         if (options?.limit) params.limit = options.limit;
         if (options?.offset) params.offset = options.offset;
         if (options?.locale) params.locale = options.locale;
-        return await this.makeRequest('GET', '/topics', params, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.SHORT,
-        });
+        // `GET /topics` returns `{ topics, total, limit, offset }`. The pagination
+        // fields matter to callers, so return the whole envelope (typed) rather
+        // than throwing them away.
+        const response = await this.makeRequest<Partial<TopicListResult>>(
+          'GET',
+          '/topics',
+          params,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT }
+        );
+        const requestedLimit = typeof params.limit === 'number' ? params.limit : 0;
+        const requestedOffset = typeof params.offset === 'number' ? params.offset : 0;
+        return {
+          topics: response.topics ?? [],
+          total: response.total ?? response.topics?.length ?? 0,
+          limit: response.limit ?? requestedLimit,
+          offset: response.offset ?? requestedOffset,
+        };
       } catch (error) {
         throw this.handleError(error);
       }
@@ -102,9 +125,16 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       names: Array<{ name: string; type: string }>
     ): Promise<TopicData[]> {
       try {
-        return await this.makeRequest('POST', '/topics/resolve', { names }, {
-          cache: false,
-        });
+        // `POST /topics/resolve` returns `{ topics: Record<name, TopicData> }`
+        // (a name-keyed map, not an array). Unwrap and flatten to the resolved
+        // topics; each TopicData carries its own `name` for re-keying.
+        const response = await this.makeRequest<{ topics: Record<string, TopicData> }>(
+          'POST',
+          '/topics/resolve',
+          { names },
+          { cache: false }
+        );
+        return Object.values(response.topics ?? {});
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.user.ts

@@ -22,7 +22,7 @@ import { buildSearchParams, buildPaginationParams, type PaginationParams } from
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { extractErrorStatus } from '../utils/errorUtils';
 
 /**

package/src/mixins/OxyServices.utility.ts

@@ -10,7 +10,7 @@ import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { loadNodeCrypto } from '@oxyhq/protocol';
 import { buildUrl } from '../utils/apiUtils';
-import { logger } from '../utils/loggerUtils';
+import { logger } from '../logger';
 import { CACHE_TIMES } from './mixinHelpers';
 
 interface JwtPayload {

package/src/mixins/__tests__/discoveryErrorHandling.test.ts

@@ -13,7 +13,7 @@
  */
 
 import { OxyServices } from '../../OxyServices';
-import { logger } from '../../utils/loggerUtils';
+import { logger } from '../../logger';
 
 /** A JSON success `Response` mimicking the API's `{ data: ... }` envelope. */
 function jsonResponse(data: unknown): Response {