@tryterra/react-native 0.0.0-stage → 2.2.1

package/lib/EndUser.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EndUser = void 0;
+exports.EndUser = {
+    /** The person your backend knows as `id`: the same value it mints their token with. */
+    reference: (id) => ({ kind: "reference", id }),
+    /** Nobody your backend tracks. Every anonymous connect on one device is the same person. */
+    anonymous: { kind: "anonymous" },
+};

package/lib/NativeTerraBridge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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";
+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>;
+}
+declare const _default: Spec;
+export default _default;

package/lib/NativeTerraBridge.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_native_1 = require("react-native");
+exports.default = react_native_1.TurboModuleRegistry.getEnforcing("TerraBridge");

package/lib/Terra.d.ts

@@ -0,0 +1,223 @@
+/**
+ * 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 type { AthleteProfile, BodyEntry, BodyReading, BootstrapState, Connection, DataCategory, DayTotal, DiagnosticsState, DietaryQuantity, EndUser, HealthAccess, HealthChange, HeartRateEntry, HeartRateSample, HydrationSample, IntradaySample, MenstrualEvent, MenstruationFlowDay, NutritionEntry, PermissionStatus, PlannedWorkout, RestingHeartRateSample, StoreAvailability, WorkoutSchedulingStatus, SleepEntry, SleepSegment, Source, StepCount, StepEntry, SupportReport, TerraEvent, TimeRange, Workout, WorkoutEntry, WorkoutIntensitySample, WorkoutRoute } 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[]>;
+    /**
+     * The store's own resting heart rate, one per day it computed, never derived from `heartRate`.
+     * Health Connect grants it under `daily`, so on Android ask for `daily` as well as `body`.
+     */
+    restingHeartRate(range: TimeRange): Promise<readonly RestingHeartRateSample[]>;
+    /**
+     * Weight, height, BMI (iOS), body fat, lean mass, heart rate variability, VO2 max, blood pressure,
+     * blood glucose, oxygen saturation, temperature and respiratory rate. Each reading's `kind` says
+     * what it measured and fixes the unit; blood glucose keeps the unit its writer chose.
+     */
+    readings(range: TimeRange): Promise<readonly BodyReading[]>;
+    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[]>;
+    /**
+     * The store's own total for each whole local day the range touches: distance, active and basal
+     * energy, flights climbed and, on iOS, exercise minutes. A day with nothing recorded has no total
+     * rather than a zero. Steps are `steps`, which keeps writers apart.
+     */
+    totals(range: TimeRange): Promise<readonly DayTotal[]>;
+    /** The active energy, basal energy (iOS), distance and floors records the totals are made of. */
+    intraday(range: TimeRange): Promise<readonly IntradaySample[]>;
+    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[]>;
+    /** The GPS tracks of the workouts in the range, each naming its workout by `workoutId`. */
+    routes(range: TimeRange): Promise<readonly WorkoutRoute[]>;
+    /**
+     * Speed, power and cycling cadence readings in the range. iOS names each one's workout; Health
+     * Connect stores them free-standing, so on Android `workoutId` is absent and `start` equals `end`.
+     */
+    intensity(range: TimeRange): Promise<readonly WorkoutIntensitySample[]>;
+    log(entries: readonly WorkoutEntry[]): Promise<readonly string[]>;
+    delete(id: string): Promise<void>;
+}
+export interface NutritionMetrics {
+    /**
+     * One quantity per nutrient a meal recorded in the range, not grouped into meals. Quantities of
+     * one meal share `foodCorrelationId`. Water is not among them. Each `value` is in its nutrient's
+     * fixed unit: kcal for `energyConsumed`, grams for the macronutrients, milligrams for the rest.
+     */
+    quantities(range: TimeRange): Promise<readonly DietaryQuantity[]>;
+    /** Water drunk in the range, one sample per drink, in millilitres. */
+    hydration(range: TimeRange): Promise<readonly HydrationSample[]>;
+    log(entries: readonly NutritionEntry[]): Promise<readonly string[]>;
+    delete(id: string): Promise<void>;
+}
+/** Read-only on both platforms: neither SDK has a write route for menstruation. */
+export interface MenstruationMetrics {
+    /**
+     * Logged flow days overlapping the range, one per day, each bounded by that day's local
+     * midnights. A day logged with no flow comes back as `none` rather than being left out.
+     */
+    flow(range: TimeRange): Promise<readonly MenstruationFlowDay[]>;
+    /** Ovulation tests, cervical mucus and intermenstrual bleeding logged in the range. */
+    events(range: TimeRange): Promise<readonly MenstrualEvent[]>;
+}
+/** iOS only, and read-only. */
+export interface AthleteMetrics {
+    /**
+     * HealthKit's characteristics as one snapshot. No range, because characteristics have no
+     * history. `undefined` where the store has no notion of them at all; a store that has them and
+     * holds no values answers a profile whose `biologicalSex` is `notSet`.
+     */
+    profile(): Promise<AthleteProfile | undefined>;
+}
+/** 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 declare 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;
+    readonly menstruation: MenstruationMetrics;
+    /** `undefined` on Android, which has no characteristics to read. */
+    readonly athlete: AthleteMetrics | undefined;
+    /** `undefined` on Android, which has no planned workouts. */
+    readonly plannedWorkouts: PlannedWorkouts | undefined;
+    private readonly ops;
+    private readonly streams;
+    private readonly tokenProvider;
+    private readonly tokenTimeoutMs;
+    /**
+     * The provider's registration, in flight or done. `undefined` before it starts and after it failed
+     * or its stream ended, so the next connect that needs it registers again.
+     */
+    private tokenSetup;
+    constructor(native: NativeBridge, platform: Platform, options?: TerraOptions);
+    /**
+     * 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>;
+    /**
+     * 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.
+     */
+    connect(source: Source, endUser: EndUser, options?: {
+        readonly token?: string;
+    }): Promise<Connection>;
+    connections(): Promise<readonly Connection[]>;
+    disconnect(source?: Source): Promise<void>;
+    /**
+     * Whether the device can serve `source` at all, and if not, why. Needs no connection and prompts
+     * for nothing, so an app can decide whether to offer the link before `connect`. iOS answers
+     * `available` or `unsupportedDevice`; Android names the reason, such as `providerAppMissing` when
+     * Health Connect needs installing.
+     */
+    availability(source?: Source): Promise<StoreAvailability>;
+    /** Settles once the token provider, when there is one, can be asked. */
+    private tokensReady;
+    /** Answers the native broker's token requests with `provider` until the stream ends. */
+    private answerTokens;
+}
+export {};

package/lib/Terra.js

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Terra = void 0;
+const TerraError_1 = require("./TerraError");
+const client_1 = require("./generated/client");
+const ops_1 = require("./generated/ops");
+const streams_1 = require("./generated/streams");
+class Terra {
+    constructor(native, platform, options = {}) {
+        this.platform = platform;
+        const invoker = native;
+        const ops = new client_1.GeneratedClient(invoker);
+        this.ops = ops;
+        this.streams = new StreamHub(native);
+        this.tokenProvider = options.tokenProvider;
+        this.tokenTimeoutMs = options.tokenTimeoutMs ?? 30000;
+        // Registered now, so the provider is in place before anything asks. A failure here is reported
+        // to the connect that needs the provider, which also tries again.
+        void this.tokensReady();
+        const on = (op) => ops_1.availableOn[op].includes(platform);
+        const stream = (id) => (listener, onError) => 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 ?? [],
+                    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) => (await ops.permissionsStatuses({ source })).statuses,
+            }),
+            ...(on("permissions.backgroundReadStatus") && {
+                backgroundReadStatus: async (source) => (await ops.permissionsBackgroundReadStatus({ source })).status,
+            }),
+            ...(on("permissions.historyReadStatus") && {
+                historyReadStatus: async (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,
+            restingHeartRate: async (range) => (await ops.bodyRestingHeartRate({ range })).samples,
+            readings: async (range) => (await ops.bodyReadings({ 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,
+            totals: async (range) => (await ops.dailyTotals({ range })).totals,
+            intraday: async (range) => (await ops.dailyIntraday({ 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,
+            routes: async (range) => (await ops.activityRoutes({ range })).routes,
+            intensity: async (range) => (await ops.activityIntensity({ range })).samples,
+            log: async (entries) => (await ops.activityLog({ entries })).ids,
+            delete: async (id) => {
+                await ops.activityDelete({ id });
+            },
+            changes: stream("activity.changes"),
+        };
+        this.nutrition = {
+            quantities: async (range) => (await ops.nutritionQuantities({ range })).samples,
+            hydration: async (range) => (await ops.nutritionHydration({ range })).samples,
+            log: async (entries) => (await ops.nutritionLog({ entries })).ids,
+            delete: async (id) => {
+                await ops.nutritionDelete({ id });
+            },
+        };
+        this.menstruation = {
+            flow: async (range) => (await ops.menstruationFlow({ range })).samples,
+            events: async (range) => (await ops.menstruationEvents({ range })).samples,
+        };
+        this.athlete = on("athlete.profile")
+            ? { profile: async () => (await ops.athleteProfile({})).profile }
+            : undefined;
+        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() {
+        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, endUser, options = {}) {
+        // A connect that carries its token never asks the provider, so it does not wait on it either.
+        if (options.token === undefined)
+            await this.tokensReady();
+        return this.ops.clientConnect({ source, endUser, token: options.token });
+    }
+    async connections() {
+        return (await this.ops.clientConnections({})).connections;
+    }
+    async disconnect(source) {
+        await this.ops.clientDisconnect({ source });
+    }
+    /**
+     * Whether the device can serve `source` at all, and if not, why. Needs no connection and prompts
+     * for nothing, so an app can decide whether to offer the link before `connect`. iOS answers
+     * `available` or `unsupportedDevice`; Android names the reason, such as `providerAppMissing` when
+     * Health Connect needs installing.
+     */
+    async availability(source) {
+        return (await this.ops.clientAvailability({ source })).availability;
+    }
+    /** Settles once the token provider, when there is one, can be asked. */
+    tokensReady() {
+        const provider = this.tokenProvider;
+        if (provider === undefined)
+            return Promise.resolve();
+        if (this.tokenSetup !== undefined)
+            return this.tokenSetup;
+        const forget = () => {
+            if (this.tokenSetup === setup)
+                this.tokenSetup = undefined;
+        };
+        const setup = this.answerTokens(provider, this.tokenTimeoutMs, forget);
+        this.tokenSetup = setup;
+        // Handles the failure, so it is never an unhandled rejection, and forgets the setup so the next
+        // connect tries again rather than rethrowing a failure that may have passed.
+        setup.catch(forget);
+        return setup;
+    }
+    /** Answers the native broker's token requests with `provider` until the stream ends. */
+    async answerTokens(provider, timeoutMs, onEnd) {
+        const id = await this.streams.open("bridge.tokenRequest", ({ requestId }) => {
+            void (async () => {
+                let token;
+                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);
+            })();
+        }, undefined, onEnd);
+        try {
+            await this.ops.tokenSetProviderPresent({ present: true, timeoutMs });
+        }
+        catch (failed) {
+            // A provider the broker was never told about answers nothing, so its stream is let go of.
+            this.streams.close(id);
+            throw failed;
+        }
+    }
+}
+exports.Terra = Terra;
+class StreamHub {
+    constructor(native) {
+        this.native = native;
+        this.handlers = new Map();
+        this.early = new Map();
+        this.pending = 0;
+    }
+    /**
+     * Subscribes and answers once the native stream is open. `onEnd` runs once the stream ends from the
+     * native side, by error or by completing; not when it is closed from here.
+     */
+    async open(stream, listener, onError, onEnd) {
+        this.listen();
+        this.pending += 1;
+        let id;
+        try {
+            id = await this.native.subscribe(stream, "{}");
+        }
+        catch (thrown) {
+            this.settled();
+            throw TerraError_1.TerraError.from(thrown);
+        }
+        const handle = (message) => {
+            const delivery = (0, streams_1.decodeStreamDelivery)(stream, JSON.parse(message));
+            switch (delivery.kind) {
+                case "data":
+                    listener(delivery.element);
+                    return;
+                case "error":
+                    this.ended(id);
+                    onError?.(new TerraError_1.TerraError(delivery.error));
+                    onEnd?.();
+                    return;
+                case "complete":
+                    this.ended(id);
+                    onEnd?.();
+                    return;
+            }
+        };
+        this.handlers.set(id, handle);
+        const held = this.early.get(id);
+        this.early.delete(id);
+        this.settled();
+        held?.forEach(handle);
+        return id;
+    }
+    settled() {
+        this.pending -= 1;
+        if (this.pending === 0)
+            this.early.clear();
+        this.releaseIfIdle();
+    }
+    ended(id) {
+        this.handlers.delete(id);
+        this.releaseIfIdle();
+    }
+    releaseIfIdle() {
+        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(stream, listener, onError) {
+        let cancelled = false;
+        let opened;
+        this.open(stream, (element) => {
+            if (!cancelled)
+                listener(element);
+        }, (error) => {
+            if (!cancelled)
+                onError?.(error);
+        }).then((id) => {
+            opened = id;
+            if (cancelled)
+                this.close(id);
+        }, (error) => {
+            if (!cancelled)
+                onError?.(error);
+        });
+        return () => {
+            if (cancelled)
+                return;
+            cancelled = true;
+            if (opened !== undefined)
+                this.close(opened);
+        };
+    }
+    close(id) {
+        this.handlers.delete(id);
+        this.early.delete(id);
+        this.native.unsubscribe(id);
+        this.releaseIfIdle();
+    }
+    listen() {
+        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) {
+    try {
+        const kind = JSON.parse(message).kind;
+        return kind === "error" || kind === "complete";
+    }
+    catch {
+        return false;
+    }
+}

package/lib/TerraError.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 { 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 declare 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;
+    });
+    /**
+     * 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;
+    /** A response the bridge resolved that this build cannot read: the native side and JS disagree. */
+    static invalidPayload(op: string, thrown: unknown): TerraError;
+}