@tryterra/react-native 0.0.0-stage → 2.1.0

package/lib/Terra.js

@@ -0,0 +1,280 @@
+"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.tokensReady = options.tokenProvider === undefined
+            ? Promise.resolve()
+            : this.answerTokens(options.tokenProvider, options.tokenTimeoutMs ?? 30000);
+        // The runtime can report an unhandled rejection before a later call awaits this promise.
+        this.tokensReady.catch(() => undefined);
+        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,
+            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() {
+        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 = {}) {
+        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 });
+    }
+    /** Answers the native broker's token requests with `provider`, for the lifetime of this runtime. */
+    async answerTokens(provider, timeoutMs) {
+        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);
+            })();
+        });
+        await this.ops.tokenSetProviderPresent({ present: true, timeoutMs });
+    }
+}
+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. */
+    async open(stream, listener, onError) {
+        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));
+                    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;
+    }
+    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;
+}

package/lib/TerraError.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TerraError = void 0;
+const codecs_1 = require("./generated/codecs");
+const errors_1 = require("./generated/errors");
+class TerraError extends Error {
+    constructor(json, options) {
+        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) {
+        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, thrown) {
+        return new TerraError({ code: "bridge.invalid_payload", message: `${op}: ${messageOf(thrown)}`, details: { op } }, { cause: thrown });
+    }
+}
+exports.TerraError = TerraError;
+function isKnownCode(code) {
+    return Object.prototype.hasOwnProperty.call(errors_1.retryableByCode, code);
+}
+function messageOf(thrown) {
+    if (thrown instanceof Error)
+        return thrown.message;
+    if (isObject(thrown) && typeof thrown.message === "string")
+        return thrown.message;
+    return String(thrown);
+}
+function fallbackRetryable(code) {
+    return errors_1.retryableByCode[code] === true;
+}
+/** A JSON string preserves payload types across `NSError` and `WritableMap`, unlike a nested map. */
+function readJSON(thrown) {
+    if (typeof thrown !== "object" || thrown === null)
+        return undefined;
+    const candidate = thrown;
+    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) {
+    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) {
+    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 } = (0, codecs_1.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) {
+    return typeof value === "object" && value !== null;
+}

package/lib/createTerra.d.ts

@@ -0,0 +1,8 @@
+import { Terra, type TerraOptions } from "./Terra";
+/**
+ * Attaches this JavaScript runtime to the native client the app built at launch.
+ *
+ * Call it once, at module scope. The native client outlives a reload, so a reload attaches again
+ * rather than building a second client.
+ */
+export declare function createTerra(options?: TerraOptions): Terra;

package/lib/createTerra.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTerra = createTerra;
+const react_native_1 = require("react-native");
+const NativeTerraBridge_1 = require("./NativeTerraBridge");
+const Terra_1 = require("./Terra");
+/**
+ * Attaches this JavaScript runtime to the native client the app built at launch.
+ *
+ * Call it once, at module scope. The native client outlives a reload, so a reload attaches again
+ * rather than building a second client.
+ */
+function createTerra(options = {}) {
+    const platform = react_native_1.Platform.OS;
+    if (platform !== "ios" && platform !== "android") {
+        throw new Error(`@tryterra/react-native runs on iOS and Android, not ${platform}`);
+    }
+    return new Terra_1.Terra(NativeTerraBridge_1.default, platform, options);
+}

package/lib/generated/client.d.ts

@@ -0,0 +1,92 @@
+import type { BodyEntryList, BoolResult, BootstrapState, CategoryRequest, ConnectRequest, Connection, ConnectionList, DiagnosticsState, Empty, HealthAccess, HeartRateEntryList, HeartRateList, LastDeliveryResult, MarkCompleteRequest, NutritionEntryList, PermissionGrant, PermissionRequest, PlannedWorkoutList, RangeRequest, RecordIdList, RecordIdRequest, SleepEntryList, SleepSegmentList, SourceRequest, StatusResult, StatusesResult, StepCountList, StepEntryList, SupportReport, TokenProviderRequest, TokenRejectRequest, TokenResolveRequest, WorkoutEntryList, WorkoutList, WorkoutScheduling } from "./types";
+import type { OpId } from "./ops";
+/** What the facade needs from the native module. The TurboModule spec satisfies it; so does a test double. */
+export interface Invoker {
+    invoke(op: OpId, payload: string): Promise<string>;
+}
+/**
+ * One generated method per op, and nothing else.
+ *
+ * The `op` string exists only between this file and the generated native dispatch, and a vector
+ * in `vectors/bridge` pins the two to each other. A caller never sees it.
+ */
+export declare class GeneratedClient {
+    protected readonly invoker: Invoker;
+    constructor(invoker: Invoker);
+    private call;
+    /**
+     * Reports the native client the JS side is attaching to. Idempotent, and safe to call after a
+     * JS reload.
+     */
+    clientAttach(request: Empty): Promise<BootstrapState>;
+    clientConnect(request: ConnectRequest): Promise<Connection>;
+    clientConnections(request: Empty): Promise<ConnectionList>;
+    clientDisconnect(request: SourceRequest): Promise<Empty>;
+    /**
+     * Tells the broker whether JS can answer at all. Without it a link asks a provider that is not
+     * there and waits out the timeout.
+     */
+    tokenSetProviderPresent(request: TokenProviderRequest): Promise<Empty>;
+    /**
+     * An unknown or already-settled requestId is ignored rather than rejected, so a reload cannot
+     * fail a link that has already moved on.
+     */
+    tokenResolve(request: TokenResolveRequest): Promise<Empty>;
+    tokenReject(request: TokenRejectRequest): Promise<Empty>;
+    permissionsRequest(request: PermissionRequest): Promise<PermissionGrant>;
+    permissionsStatus(request: CategoryRequest): Promise<StatusResult>;
+    permissionsWriteStatus(request: CategoryRequest): Promise<StatusResult>;
+    permissionsRequested(request: SourceRequest): Promise<HealthAccess>;
+    /** Available on android only. */
+    permissionsStatuses(request: SourceRequest): Promise<StatusesResult>;
+    /** Available on android only. */
+    permissionsBackgroundReadStatus(request: SourceRequest): Promise<StatusResult>;
+    /** Available on android only. */
+    permissionsHistoryReadStatus(request: SourceRequest): Promise<StatusResult>;
+    diagnosticsState(request: SourceRequest): Promise<DiagnosticsState>;
+    diagnosticsLastDelivery(request: SourceRequest): Promise<LastDeliveryResult>;
+    diagnosticsReport(request: SourceRequest): Promise<SupportReport>;
+    diagnosticsSend(request: SourceRequest): Promise<Empty>;
+    /**
+     * False means bootstrap did not run. The SDK reports the same thing independently as
+     * backgroundRefreshUnscheduled.
+     */
+    backgroundIsRegistered(request: Empty): Promise<BoolResult>;
+    /** Available on android only. */
+    backgroundCancel(request: Empty): Promise<BoolResult>;
+    bodyHeartRate(request: RangeRequest): Promise<HeartRateList>;
+    /** Its own op rather than an overload: Swift overloads log by element type and JS cannot. */
+    bodyLogHeartRate(request: HeartRateEntryList): Promise<RecordIdList>;
+    bodyLog(request: BodyEntryList): Promise<RecordIdList>;
+    bodyDelete(request: RecordIdRequest): Promise<Empty>;
+    dailySteps(request: RangeRequest): Promise<StepCountList>;
+    dailyLog(request: StepEntryList): Promise<RecordIdList>;
+    dailyDelete(request: RecordIdRequest): Promise<Empty>;
+    sleepSegments(request: RangeRequest): Promise<SleepSegmentList>;
+    sleepLog(request: SleepEntryList): Promise<RecordIdList>;
+    sleepDelete(request: RecordIdRequest): Promise<Empty>;
+    activityWorkouts(request: RangeRequest): Promise<WorkoutList>;
+    activityLog(request: WorkoutEntryList): Promise<RecordIdList>;
+    activityDelete(request: RecordIdRequest): Promise<Empty>;
+    nutritionLog(request: NutritionEntryList): Promise<RecordIdList>;
+    nutritionDelete(request: RecordIdRequest): Promise<Empty>;
+    /** Available on ios only. */
+    plannedWorkoutsPlanned(request: Empty): Promise<PlannedWorkoutList>;
+    /** Available on ios only. */
+    plannedWorkoutsMarkComplete(request: MarkCompleteRequest): Promise<Empty>;
+    /** Available on ios only. */
+    plannedWorkoutsDelete(request: RecordIdRequest): Promise<Empty>;
+    /**
+     * Never prompts.
+     *
+     * Available on ios only.
+     */
+    plannedWorkoutsSchedulingStatus(request: Empty): Promise<WorkoutScheduling>;
+    /**
+     * Shows WorkoutKit's sheet if the person has not been asked, and reconciles straight away once
+     * authorized.
+     *
+     * Available on ios only.
+     */
+    plannedWorkoutsRequestScheduling(request: Empty): Promise<WorkoutScheduling>;
+}