@tryterra/react-native 0.0.0-stage → 2.1.0

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@tryterra/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.1.0",
+  "description": "Terra's health SDK for React Native",
+  "license": "MIT",
+  "homepage": "https://docs.tryterra.co",
+  "author": "Terra",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tryterra/terra-mobile.git",
+    "directory": "react-native"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "!src/__tests__",
+    "lib",
+    "ios",
+    "frameworks",
+    "android",
+    "!android/build",
+    "!android/.gradle",
+    "!android/.cxx",
+    "TerraReactNative.podspec",
+    "docs",
+    "!docs/distribution.md"
+  ],
+  "terraNative": {
+    "ios": "2.1.0",
+    "android": "2.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "build": "node scripts/clean-lib.js && tsc -p tsconfig.build.json",
+    "vendor": "node scripts/vendor-bridge-core.js",
+    "fetch-sdk": "node scripts/fetch-terrasdk.js",
+    "prepack": "npm run build && npm run vendor && npm run fetch-sdk"
+  },
+  "codegenConfig": {
+    "name": "TerraReactNativeSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "co.tryterra.sdk.reactnative"
+    },
+    "ios": {
+      "modulesProvider": {
+        "TerraBridge": "TerraBridgeModule"
+      }
+    }
+  },
+  "peerDependencies": {
+    "react-native": ">=0.81.0"
+  },
+  "devDependencies": {
+    "@babel/core": "7.26.0",
+    "@babel/preset-env": "7.26.0",
+    "@babel/preset-typescript": "7.26.0",
+    "@types/jest": "29.5.14",
+    "babel-jest": "29.7.0",
+    "jest": "29.7.0",
+    "react-native": "0.81.6",
+    "typescript": "5.9.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/EndUser.ts

@@ -0,0 +1,15 @@
+/**
+ * Who a connect is for. Every connect names one: a second account on the same phone is a different
+ * person, and must not be handed the first one's link.
+ */
+
+import type { EndUser as WireEndUser } from "./generated/types";
+
+export type EndUser = WireEndUser;
+
+export const EndUser = {
+  /** The person your backend knows as `id`: the same value it mints their token with. */
+  reference: (id: string): EndUser => ({ kind: "reference", id }),
+  /** Nobody your backend tracks. Every anonymous connect on one device is the same person. */
+  anonymous: { kind: "anonymous" } as EndUser,
+} as const;

package/src/NativeTerraBridge.ts

@@ -0,0 +1,27 @@
+/**
+ * The TurboModule spec. React Native's Codegen reads this file at the host app's build and
+ * generates the native interfaces that `ios/TerraBridgeModule.mm` and
+ * `android/.../TerraBridgeModule.kt` implement.
+ *
+ * Deliberately narrow: one op call, one stream subscription, one emitter. The op strings and their
+ * payloads are typed on both sides by `surface/gen`, so nothing here changes when the SDK grows an
+ * op.
+ */
+
+import type { CodegenTypes, TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+export type StreamMessageEvent = {
+  subscriptionId: string;
+  /** A `StreamMessage`, as the wire spells it. */
+  message: string;
+};
+
+export interface Spec extends TurboModule {
+  invoke(op: string, payload: string): Promise<string>;
+  subscribe(stream: string, params: string): Promise<string>;
+  unsubscribe(subscriptionId: string): void;
+  readonly onMessage: CodegenTypes.EventEmitter<StreamMessageEvent>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("TerraBridge");

package/src/Terra.ts

@@ -0,0 +1,462 @@
+/**
+ * The client an app holds: namespaces over the generated ops, the token provider, and the streams.
+ *
+ * Hand-written, deliberately thin. Every method is one generated `GeneratedClient` call; what lives
+ * here is only what the generated layer cannot know - which runtime the app is on, how a JS
+ * function answers a native token request, and how one native event emitter fans out to many
+ * listeners. `facade.test.ts` drives every method and fails when an op in the schema has no member
+ * here, so this file cannot quietly fall behind the surface the way the 1.x wrapper did.
+ */
+
+import { TerraError } from "./TerraError";
+import { GeneratedClient, type Invoker } from "./generated/client";
+import { availableOn, type OpId, type StreamId } from "./generated/ops";
+import { decodeStreamDelivery, type StreamElements } from "./generated/streams";
+import type {
+  BodyEntry,
+  BootstrapState,
+  Connection,
+  DataCategory,
+  DiagnosticsState,
+  EndUser,
+  HealthAccess,
+  HealthChange,
+  HeartRateEntry,
+  HeartRateSample,
+  NutritionEntry,
+  PermissionStatus,
+  PlannedWorkout,
+  WorkoutSchedulingStatus,
+  SleepEntry,
+  SleepSegment,
+  Source,
+  StepCount,
+  StepEntry,
+  SupportReport,
+  TerraEvent,
+  TimeRange,
+  Workout,
+  WorkoutEntry,
+  WorkoutScope,
+} from "./generated/types";
+
+/** What the facade needs from the native module. `NativeTerraBridge` satisfies it; so does a double. */
+export interface NativeBridge {
+  invoke(op: string, payload: string): Promise<string>;
+  subscribe(stream: string, params: string): Promise<string>;
+  unsubscribe(subscriptionId: string): void;
+  onMessage(listener: (event: { subscriptionId: string; message: string }) => void): { remove(): void };
+}
+
+export type Platform = "ios" | "android";
+
+/** Asked for a one-shot link token, and only while `connect` establishes a new link. */
+export type TokenProvider = () => Promise<string>;
+
+export interface TerraOptions {
+  /**
+   * Called only when `connect` has to make a new link and was given no token. A restored link
+   * never asks, and neither does a background wake: uploads are signed by the device key.
+   */
+  readonly tokenProvider?: TokenProvider;
+  /** How long the native side waits for `tokenProvider`. 30 seconds by default. */
+  readonly tokenTimeoutMs?: number;
+}
+
+export type Unsubscribe = () => void;
+
+/** A stream's listener. `onError` receives the error a stream ended with; a stream that completes ends quietly. */
+export interface StreamListener<T> {
+  (element: T): void;
+}
+
+export interface Permissions {
+  /**
+   * One sheet covering both directions and everything asked before. Android answers what this call
+   * obtained; HealthKit will not report read grants, so iOS answers `undefined`.
+   *
+   * `source` defaults to `health`. `samsungHealth` presents Samsung Health's own consent popup and
+   * is Android only.
+   */
+  request(access: Partial<HealthAccess>, source?: Source): Promise<HealthAccess | undefined>;
+  status(category: DataCategory, source?: Source): Promise<PermissionStatus>;
+  writeStatus(category: DataCategory, source?: Source): Promise<PermissionStatus>;
+  requested(source?: Source): Promise<HealthAccess>;
+  /** Android only. */
+  readonly statuses?: (source?: Source) => Promise<Partial<Record<DataCategory, PermissionStatus>>>;
+  /** Android only. */
+  readonly backgroundReadStatus?: (source?: Source) => Promise<PermissionStatus>;
+  /** Android only. */
+  readonly historyReadStatus?: (source?: Source) => Promise<PermissionStatus>;
+}
+
+export interface Diagnostics {
+  state(source?: Source): Promise<DiagnosticsState>;
+  lastDelivery(source?: Source): Promise<Date | undefined>;
+  report(source?: Source): Promise<SupportReport>;
+  send(source?: Source): Promise<void>;
+  /** Everything the SDK does, as it happens. Never carries a health value. */
+  events(listener: StreamListener<TerraEvent>, onError?: (error: TerraError) => void): Unsubscribe;
+}
+
+export interface Background {
+  /** Whether the native bootstrap registered background sync at launch. False is a host setup bug. */
+  isRegistered(): Promise<boolean>;
+  /** Android only: drops the schedule. */
+  readonly cancel?: () => Promise<boolean>;
+}
+
+interface Changes {
+  /** Which days changed in the health store. Re-read through this namespace's accessor. */
+  changes(listener: StreamListener<HealthChange>, onError?: (error: TerraError) => void): Unsubscribe;
+}
+
+export interface BodyMetrics extends Changes {
+  heartRate(range: TimeRange): Promise<readonly HeartRateSample[]>;
+  logHeartRate(entries: readonly HeartRateEntry[]): Promise<readonly string[]>;
+  log(entries: readonly BodyEntry[]): Promise<readonly string[]>;
+  delete(id: string): Promise<void>;
+}
+
+export interface DailyMetrics extends Changes {
+  steps(range: TimeRange): Promise<readonly StepCount[]>;
+  log(entries: readonly StepEntry[]): Promise<readonly string[]>;
+  delete(id: string): Promise<void>;
+}
+
+export interface SleepMetrics extends Changes {
+  segments(range: TimeRange): Promise<readonly SleepSegment[]>;
+  log(entries: readonly SleepEntry[]): Promise<readonly string[]>;
+  delete(id: string): Promise<void>;
+}
+
+export interface ActivityMetrics extends Changes {
+  workouts(range: TimeRange): Promise<readonly Workout[]>;
+  log(entries: readonly WorkoutEntry[]): Promise<readonly string[]>;
+  delete(id: string): Promise<void>;
+}
+
+/** Write-only on both platforms. */
+export interface NutritionMetrics {
+  log(entries: readonly NutritionEntry[]): Promise<readonly string[]>;
+  delete(id: string): Promise<void>;
+}
+
+/** iOS only. */
+export interface PlannedWorkouts {
+  planned(): Promise<readonly PlannedWorkout[]>;
+  markComplete(id: string, at?: Date): Promise<void>;
+  delete(id: string): Promise<void>;
+  /** Whether plans can be put on the person's Apple Watch. Never prompts. */
+  schedulingStatus(): Promise<WorkoutSchedulingStatus>;
+  /**
+   * Shows WorkoutKit's sheet if the person has not been asked. Once authorized, every sync run
+   * keeps the Watch schedule in step with Terra; nothing else needs calling.
+   */
+  requestScheduling(): Promise<WorkoutSchedulingStatus>;
+}
+
+export class Terra {
+  readonly platform: Platform;
+  readonly permissions: Permissions;
+  readonly diagnostics: Diagnostics;
+  readonly background: Background;
+  readonly body: BodyMetrics;
+  readonly daily: DailyMetrics;
+  readonly sleep: SleepMetrics;
+  readonly activity: ActivityMetrics;
+  readonly nutrition: NutritionMetrics;
+  /** `undefined` on Android, which has no planned workouts. */
+  readonly plannedWorkouts: PlannedWorkouts | undefined;
+
+  private readonly ops: GeneratedClient;
+  private readonly streams: StreamHub;
+  /** Settles once the token provider, when there is one, can be asked. */
+  private readonly tokensReady: Promise<void>;
+
+  constructor(native: NativeBridge, platform: Platform, options: TerraOptions = {}) {
+    this.platform = platform;
+    const invoker: Invoker = native;
+    const ops = new GeneratedClient(invoker);
+    this.ops = ops;
+    this.streams = new StreamHub(native);
+    this.tokensReady = options.tokenProvider === undefined
+      ? Promise.resolve()
+      : this.answerTokens(options.tokenProvider, options.tokenTimeoutMs ?? 30_000);
+    // The runtime can report an unhandled rejection before a later call awaits this promise.
+    this.tokensReady.catch(() => undefined);
+
+    const on = (op: OpId) => availableOn[op].includes(platform);
+    const stream = <S extends StreamId>(id: S) =>
+      (listener: StreamListener<StreamElements[S]>, onError?: (error: TerraError) => void) =>
+        this.streams.subscribe(id, listener, onError);
+
+    this.permissions = {
+      request: async (access, source) => {
+        const grant = await ops.permissionsRequest({
+          read: access.read ?? [],
+          write: access.write ?? [],
+          workouts: access.workouts ?? ([] as readonly WorkoutScope[]),
+          source,
+        });
+        return grant.granted;
+      },
+      status: async (category, source) => (await ops.permissionsStatus({ category, source })).status,
+      writeStatus: async (category, source) => (await ops.permissionsWriteStatus({ category, source })).status,
+      requested: (source) => ops.permissionsRequested({ source }),
+      ...(on("permissions.statuses") && {
+        statuses: async (source?: Source) => (await ops.permissionsStatuses({ source })).statuses,
+      }),
+      ...(on("permissions.backgroundReadStatus") && {
+        backgroundReadStatus: async (source?: Source) => (await ops.permissionsBackgroundReadStatus({ source })).status,
+      }),
+      ...(on("permissions.historyReadStatus") && {
+        historyReadStatus: async (source?: Source) => (await ops.permissionsHistoryReadStatus({ source })).status,
+      }),
+    };
+
+    this.diagnostics = {
+      state: (source) => ops.diagnosticsState({ source }),
+      lastDelivery: async (source) => (await ops.diagnosticsLastDelivery({ source })).at,
+      report: (source) => ops.diagnosticsReport({ source }),
+      send: async (source) => {
+        await ops.diagnosticsSend({ source });
+      },
+      events: stream("diagnostics.events"),
+    };
+
+    this.background = {
+      isRegistered: async () => (await ops.backgroundIsRegistered({})).value,
+      ...(on("background.cancel") && { cancel: async () => (await ops.backgroundCancel({})).value }),
+    };
+
+    this.body = {
+      heartRate: async (range) => (await ops.bodyHeartRate({ range })).samples,
+      logHeartRate: async (entries) => (await ops.bodyLogHeartRate({ entries })).ids,
+      log: async (entries) => (await ops.bodyLog({ entries })).ids,
+      delete: async (id) => {
+        await ops.bodyDelete({ id });
+      },
+      changes: stream("body.changes"),
+    };
+
+    this.daily = {
+      steps: async (range) => (await ops.dailySteps({ range })).samples,
+      log: async (entries) => (await ops.dailyLog({ entries })).ids,
+      delete: async (id) => {
+        await ops.dailyDelete({ id });
+      },
+      changes: stream("daily.changes"),
+    };
+
+    this.sleep = {
+      segments: async (range) => (await ops.sleepSegments({ range })).samples,
+      log: async (entries) => (await ops.sleepLog({ entries })).ids,
+      delete: async (id) => {
+        await ops.sleepDelete({ id });
+      },
+      changes: stream("sleep.changes"),
+    };
+
+    this.activity = {
+      workouts: async (range) => (await ops.activityWorkouts({ range })).samples,
+      log: async (entries) => (await ops.activityLog({ entries })).ids,
+      delete: async (id) => {
+        await ops.activityDelete({ id });
+      },
+      changes: stream("activity.changes"),
+    };
+
+    this.nutrition = {
+      log: async (entries) => (await ops.nutritionLog({ entries })).ids,
+      delete: async (id) => {
+        await ops.nutritionDelete({ id });
+      },
+    };
+
+    this.plannedWorkouts = on("plannedWorkouts.planned")
+      ? {
+          planned: async () => (await ops.plannedWorkoutsPlanned({})).workouts,
+          markComplete: async (id, at) => {
+            await ops.plannedWorkoutsMarkComplete({ id, at });
+          },
+          delete: async (id) => {
+            await ops.plannedWorkoutsDelete({ id });
+          },
+          schedulingStatus: async () => (await ops.plannedWorkoutsSchedulingStatus({})).status,
+          requestScheduling: async () => (await ops.plannedWorkoutsRequestScheduling({})).status,
+        }
+      : undefined;
+  }
+
+  /**
+   * The native client this runtime is attached to. Rejects with `bridge.not_bootstrapped`, carrying
+   * the exact line to add in `details.line`, when the app's native launch never set Terra up.
+   */
+  attach(): Promise<BootstrapState> {
+    return this.ops.clientAttach({});
+  }
+
+  /**
+   * Links `source` for the person `endUser` names, or restores the link already made for them.
+   *
+   * Every connect names its person: a second account on the same phone must not be handed the
+   * first one's link. With `token` the grant in hand is spent (a QR code, a deep link); without it
+   * the `tokenProvider` is asked, and only when a new link is actually needed.
+   */
+  async connect(source: Source, endUser: EndUser, options: { readonly token?: string } = {}): Promise<Connection> {
+    await this.tokensReady;
+    return this.ops.clientConnect({ source, endUser, token: options.token });
+  }
+
+  async connections(): Promise<readonly Connection[]> {
+    return (await this.ops.clientConnections({})).connections;
+  }
+
+  async disconnect(source?: Source): Promise<void> {
+    await this.ops.clientDisconnect({ source });
+  }
+
+  /** Answers the native broker's token requests with `provider`, for the lifetime of this runtime. */
+  private async answerTokens(provider: TokenProvider, timeoutMs: number): Promise<void> {
+    await this.streams.open("bridge.tokenRequest", ({ requestId }) => {
+      void (async () => {
+        let token: string;
+        try {
+          token = await provider();
+        } catch (failed) {
+          const message = failed instanceof Error ? failed.message : String(failed);
+          await this.ops.tokenReject({ requestId, message }).catch(() => undefined);
+          return;
+        }
+        await this.ops.tokenResolve({ requestId, token }).catch(() => undefined);
+      })();
+    });
+    await this.ops.tokenSetProviderPresent({ present: true, timeoutMs });
+  }
+}
+
+class StreamHub {
+  private readonly handlers = new Map<string, (message: string) => void>();
+  private readonly early = new Map<string, string[]>();
+  private pending = 0;
+  private listening: { remove(): void } | undefined;
+
+  constructor(private readonly native: NativeBridge) {}
+
+  /** Subscribes and answers once the native stream is open. */
+  async open<S extends StreamId>(
+    stream: S,
+    listener: StreamListener<StreamElements[S]>,
+    onError?: (error: TerraError) => void,
+  ): Promise<string> {
+    this.listen();
+    this.pending += 1;
+    let id: string;
+    try {
+      id = await this.native.subscribe(stream, "{}");
+    } catch (thrown) {
+      this.settled();
+      throw TerraError.from(thrown);
+    }
+    const handle = (message: string) => {
+      const delivery = decodeStreamDelivery(stream, JSON.parse(message));
+      switch (delivery.kind) {
+        case "data":
+          listener(delivery.element);
+          return;
+        case "error":
+          this.ended(id);
+          onError?.(new TerraError(delivery.error));
+          return;
+        case "complete":
+          this.ended(id);
+          return;
+      }
+    };
+    this.handlers.set(id, handle);
+    const held = this.early.get(id);
+    this.early.delete(id);
+    this.settled();
+    held?.forEach(handle);
+    return id;
+  }
+
+  private settled(): void {
+    this.pending -= 1;
+    if (this.pending === 0) this.early.clear();
+    this.releaseIfIdle();
+  }
+
+  private ended(id: string): void {
+    this.handlers.delete(id);
+    this.releaseIfIdle();
+  }
+
+  private releaseIfIdle(): void {
+    if (this.handlers.size > 0 || this.pending > 0) return;
+    this.listening?.remove();
+    this.listening = undefined;
+  }
+
+  /** Subscribes without waiting; the returned function cancels whether or not the stream has opened yet. */
+  subscribe<S extends StreamId>(
+    stream: S,
+    listener: StreamListener<StreamElements[S]>,
+    onError?: (error: TerraError) => void,
+  ): Unsubscribe {
+    let cancelled = false;
+    let opened: string | undefined;
+    this.open(stream, (element) => {
+      if (!cancelled) listener(element);
+    }, (error) => {
+      if (!cancelled) onError?.(error);
+    }).then(
+      (id) => {
+        opened = id;
+        if (cancelled) this.close(id);
+      },
+      (error: TerraError) => {
+        if (!cancelled) onError?.(error);
+      },
+    );
+    return () => {
+      if (cancelled) return;
+      cancelled = true;
+      if (opened !== undefined) this.close(opened);
+    };
+  }
+
+  private close(id: string): void {
+    this.handlers.delete(id);
+    this.early.delete(id);
+    this.native.unsubscribe(id);
+    this.releaseIfIdle();
+  }
+
+  private listen(): void {
+    if (this.listening !== undefined) return;
+    this.listening = this.native.onMessage(({ subscriptionId, message }) => {
+      const handler = this.handlers.get(subscriptionId);
+      if (handler !== undefined) {
+        handler(message);
+        return;
+      }
+      if (this.pending === 0) return;
+      const held = this.early.get(subscriptionId) ?? [];
+      if (held.length < EARLY_LIMIT || isTerminal(message)) held.push(message);
+      this.early.set(subscriptionId, held);
+    });
+  }
+}
+
+const EARLY_LIMIT = 64;
+
+function isTerminal(message: string): boolean {
+  try {
+    const kind = (JSON.parse(message) as { kind?: unknown }).kind;
+    return kind === "error" || kind === "complete";
+  } catch {
+    return false;
+  }
+}

package/src/TerraError.ts

@@ -0,0 +1,116 @@
+/**
+ * The error every rejected op carries, hydrated from the bridge's JSON.
+ *
+ * Hand-written, and one of only two files here that are: the shape is fixed, while the *vocabulary*
+ * it carries is generated. `code` is a `TerraErrorCode`, so a code renamed natively stops a
+ * `switch` over it compiling rather than silently never matching.
+ */
+
+import { decodeTerraErrorPayload } from "./generated/codecs";
+import { retryableByCode, type TerraErrorCode } from "./generated/errors";
+import type { Source, TerraErrorPayload } from "./generated/types";
+
+/**
+ * The JSON a native rejection carries in its userInfo / message: the schema's own payload, except
+ * that `retryable` may be left out, in which case the per-code table answers.
+ */
+export type TerraErrorJSON = Omit<TerraErrorPayload, "retryable"> & { readonly retryable?: boolean };
+
+export class TerraError extends Error {
+  readonly code: TerraErrorCode;
+  /**
+   * Whether the same call could succeed if repeated.
+   *
+   * Read from the rejection rather than from `retryableByCode`, because one code decides per
+   * instance: `network.server_error` is retryable for a 503 and not for a 400. The table is the
+   * fallback for a rejection that did not carry the flag at all.
+   */
+  readonly retryable: boolean;
+  readonly source: Source | undefined;
+  readonly details: Record<string, unknown> | undefined;
+
+  constructor(json: TerraErrorJSON, options?: { readonly cause?: unknown }) {
+    super(json.message, options);
+    this.name = "TerraError";
+    const known = isKnownCode(json.code);
+    this.code = known ? json.code : "platform";
+    this.retryable = known ? (json.retryable ?? fallbackRetryable(json.code)) : false;
+    this.source = json.source;
+    this.details = known ? json.details : { ...json.details, unrecognisedCode: json.code };
+  }
+
+  /**
+   * Rebuilds a `TerraError` from whatever the native module rejected with.
+   *
+   * Anything unrecognisable becomes `platform` rather than being rethrown as-is: a caller that has
+   * to handle both `TerraError` and an arbitrary `Error` ends up handling neither properly, and the
+   * original is kept as `cause` and its text in `message`.
+   */
+  static from(thrown: unknown): TerraError {
+    if (thrown instanceof TerraError) return thrown;
+    const json = readJSON(thrown);
+    if (json !== undefined) return new TerraError(json, { cause: thrown });
+    return new TerraError({ code: "platform", retryable: false, message: messageOf(thrown) }, { cause: thrown });
+  }
+
+  /** A response the bridge resolved that this build cannot read: the native side and JS disagree. */
+  static invalidPayload(op: string, thrown: unknown): TerraError {
+    return new TerraError(
+      { code: "bridge.invalid_payload", message: `${op}: ${messageOf(thrown)}`, details: { op } },
+      { cause: thrown },
+    );
+  }
+}
+
+function isKnownCode(code: string): code is TerraErrorCode {
+  return Object.prototype.hasOwnProperty.call(retryableByCode, code);
+}
+
+function messageOf(thrown: unknown): string {
+  if (thrown instanceof Error) return thrown.message;
+  if (isObject(thrown) && typeof thrown.message === "string") return thrown.message;
+  return String(thrown);
+}
+
+function fallbackRetryable(code: TerraErrorCode): boolean {
+  return retryableByCode[code] === true;
+}
+
+/** A JSON string preserves payload types across `NSError` and `WritableMap`, unlike a nested map. */
+function readJSON(thrown: unknown): TerraErrorJSON | undefined {
+  if (typeof thrown !== "object" || thrown === null) return undefined;
+  const candidate = thrown as Record<string, unknown>;
+  const userInfo = candidate.userInfo;
+  const encoded = isObject(userInfo) ? userInfo.payload : undefined;
+  return (typeof encoded === "string" ? decode(parse(encoded)) : undefined) ?? decode(userInfo) ?? decode(candidate);
+}
+
+function parse(encoded: string): unknown {
+  try {
+    return JSON.parse(encoded);
+  } catch {
+    return undefined;
+  }
+}
+
+/** The generated decoder does the checking: a string code, a boolean flag, a known source. */
+function decode(raw: unknown): TerraErrorJSON | undefined {
+  if (!isObject(raw) || typeof raw.code !== "string") return undefined;
+  try {
+    // Read field by field: an Error's `message` is not enumerable, so spreading one drops it.
+    const { retryable, ...rest } = decodeTerraErrorPayload({
+      code: raw.code,
+      retryable: raw.retryable ?? false,
+      message: raw.message,
+      source: raw.source,
+      details: raw.details,
+    });
+    return raw.retryable === undefined ? rest : { ...rest, retryable };
+  } catch {
+    return undefined;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}