@tryterra/react-native 0.0.0-stage → 2.1.0

package/ios/TerraBridgeCore/TerraBridgeStreamsImpl.swift

@@ -0,0 +1,60 @@
+import Foundation
+import TerraSDK
+
+/// The hand-written half of streams: one source per stream, a fresh one per call.
+///
+/// Routing, element validation and framing are generated (`BridgeStreamDispatch`); this only
+/// produces values, so a stream added to the schema stops this compiling until it has a source.
+/// Each source is open when its method returns, so nothing after `subscribe` returns is missed.
+struct TerraBridgeStreamsImpl: TerraBridgeStreams {
+    let terra: Terra
+    let audience: TokenAudience
+    let deviceZone: @Sendable () -> TimeZone
+
+    /// An event the bridge could not encode is relayed as an empty object, which the generated
+    /// envelope check refuses, so the subscription ends with an error instead of skipping it.
+    func diagnosticsEvents(_ params: Empty) async throws -> AsyncStream<TerraEvent> {
+        Self.relay(terra.diagnostics.events()) { (try? Conversions.event($0)) ?? BridgeJSON([:]) }
+    }
+
+    func bodyChanges(_ params: Empty) async throws -> AsyncStream<HealthChange> {
+        changes(await terra.body.changes())
+    }
+
+    func dailyChanges(_ params: Empty) async throws -> AsyncStream<HealthChange> {
+        changes(await terra.daily.changes())
+    }
+
+    func sleepChanges(_ params: Empty) async throws -> AsyncStream<HealthChange> {
+        changes(await terra.sleep.changes())
+    }
+
+    func activityChanges(_ params: Empty) async throws -> AsyncStream<HealthChange> {
+        changes(await terra.activity.changes())
+    }
+
+    func bridgeTokenRequest(_ params: Empty) async throws -> AsyncStream<TokenRequest> {
+        audience.listen()
+    }
+
+    /// A category the surface excludes has no wire name; a namespace's stream never carries one.
+    private func changes(_ source: AsyncStream<TerraSDK.HealthChange>) -> AsyncStream<HealthChange> {
+        let zone = deviceZone
+        return Self.relay(source) { Conversions.change($0, zone: zone()) }
+    }
+
+    /// Forwards an SDK stream, converting each element, until either side goes away.
+    private static func relay<Element: Sendable, Wire: Sendable>(
+        _ source: AsyncStream<Element>, _ convert: @escaping @Sendable (Element) -> Wire?
+    ) -> AsyncStream<Wire> {
+        AsyncStream { continuation in
+            let task = Task {
+                for await element in source {
+                    if let wire = convert(element) { continuation.yield(wire) }
+                }
+                continuation.finish()
+            }
+            continuation.onTermination = { _ in task.cancel() }
+        }
+    }
+}

package/ios/TerraBridgeCore/TokenBroker.swift

@@ -0,0 +1,147 @@
+import Foundation
+import TerraSDK
+
+/// The SDK's token provider, answered by a runtime on the other side of the bridge.
+///
+/// The client is built at launch, before any JavaScript exists, and captures its provider then. So
+/// the provider is this broker, built first and handed to the client, and the runtime that is
+/// listening now is whichever session last said it has a provider.
+///
+/// Safe because the SDK asks on one path only, `connect`, which only a live runtime can call. A
+/// background wake never asks: uploads are signed by the device key.
+actor TokenBroker {
+    static let defaultTimeoutMs = 30_000
+
+    private struct Pending {
+        let audience: ObjectIdentifier
+        let continuation: CheckedContinuation<String, any Error>
+        let timer: Task<Void, Never>
+    }
+
+    private weak var owner: TokenAudience?
+    private var timeoutMs = TokenBroker.defaultTimeoutMs
+    private var pending: [String: Pending] = [:]
+
+    /// What the client calls. No listener answers `tokenUnavailable` at once, which is what a
+    /// native app built without a provider gets.
+    func provide() async throws -> String {
+        guard let owner else { throw TerraError.tokenUnavailable }
+        let id = "tok-\(UUID().uuidString.lowercased())"
+        let budget = timeoutMs
+        return try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<String, any Error>) in
+                if Task.isCancelled {
+                    continuation.resume(throwing: CancellationError())
+                    return
+                }
+                let timer = Task.detached { [weak self] in
+                    try? await Task.sleep(nanoseconds: UInt64(min(max(budget, 0), 3_600_000)) * 1_000_000)
+                    await self?.settle(id, .failure(BridgeError.tokenTimeout(timeoutMs: budget)))
+                }
+                pending[id] = Pending(audience: ObjectIdentifier(owner), continuation: continuation, timer: timer)
+                if !owner.deliver(TokenRequest(requestId: id)) {
+                    settle(id, .failure(TerraError.tokenUnavailable))
+                }
+            }
+        } onCancel: {
+            Task { await self.settle(id, .failure(CancellationError())) }
+        }
+    }
+
+    /// Whether an ask made now would reach anyone.
+    var canAnswer: Bool { owner?.isListening ?? false }
+
+    /// The session that answers from now on, or none.
+    func setProviderPresent(_ present: Bool, timeoutMs: Int, audience: TokenAudience) {
+        guard !audience.isClosed else { return }
+        if present {
+            owner = audience
+            self.timeoutMs = timeoutMs
+        } else if owner === audience {
+            owner = nil
+        }
+    }
+
+    /// An unknown or settled id is ignored: a runtime that reloaded answers asks its predecessor
+    /// made, and failing that would turn a harmless race into a failed link.
+    func resolve(_ requestId: String, token: String) {
+        settle(requestId, .success(token))
+    }
+
+    func reject(_ requestId: String, message: String) {
+        settle(requestId, .failure(ProviderRefused(message: message)))
+    }
+
+    /// Fails what this session was asked, and stops routing to it. Only this session's: a stale
+    /// teardown arriving after its successor registered must not fail the successor's link.
+    func invalidate(_ audience: TokenAudience) {
+        if owner === audience { owner = nil }
+        let identity = ObjectIdentifier(audience)
+        for (id, ask) in pending where ask.audience == identity {
+            settle(id, .failure(ProviderRefused(message: "the host runtime went away")))
+        }
+    }
+
+    var pendingCount: Int { pending.count }
+
+    private func settle(_ id: String, _ result: Result<String, any Error>) {
+        guard let ask = pending.removeValue(forKey: id) else { return }
+        ask.timer.cancel()
+        ask.continuation.resume(with: result)
+    }
+
+    /// The provider's own failure. Its text never crosses the bridge; see `Rejections`.
+    struct ProviderRefused: Error, Sendable {
+        let message: String
+    }
+}
+
+/// The token-request subscriptions of one session.
+final class TokenAudience: Sendable {
+    private struct State {
+        var listeners: [UUID: AsyncStream<TokenRequest>.Continuation] = [:]
+        var closed = false
+    }
+
+    private let state = Locked(State())
+
+    var isClosed: Bool { state.withLock { $0.closed } }
+
+    var isListening: Bool { state.withLock { !$0.closed && !$0.listeners.isEmpty } }
+
+    func listen() -> AsyncStream<TokenRequest> {
+        let (stream, continuation) = AsyncStream<TokenRequest>.makeStream()
+        let key = UUID()
+        let accepted = state.withLock { state in
+            guard !state.closed else { return false }
+            state.listeners[key] = continuation
+            return true
+        }
+        guard accepted else {
+            continuation.finish()
+            return stream
+        }
+        continuation.onTermination = { [weak self] _ in
+            self?.state.withLock { _ = $0.listeners.removeValue(forKey: key) }
+        }
+        return stream
+    }
+
+    func deliver(_ request: TokenRequest) -> Bool {
+        let listeners = state.withLock { $0.closed ? [] : Array($0.listeners.values) }
+        var delivered = false
+        for listener in listeners {
+            if case .enqueued = listener.yield(request) { delivered = true }
+        }
+        return delivered
+    }
+
+    func close() {
+        let listeners = state.withLock { state in
+            state.closed = true
+            defer { state.listeners = [:] }
+            return Array(state.listeners.values)
+        }
+        for listener in listeners { listener.finish() }
+    }
+}

package/ios/TerraBridgeModule.mm

@@ -0,0 +1,79 @@
+#import <React/RCTInvalidating.h>
+#import <TerraReactNativeSpec/TerraReactNativeSpec.h>
+
+// Declared here rather than in a header: a public header importing the C++ spec would be read by
+// the Swift half of this module, which cannot import C++.
+@interface TerraBridgeModule : NativeTerraBridgeSpecBase <NativeTerraBridgeSpec, RCTInvalidating>
+@end
+
+#if __has_include("TerraReactNative-Swift.h")
+#import "TerraReactNative-Swift.h"
+#else
+#import <TerraReactNative/TerraReactNative-Swift.h>
+#endif
+
+static NSString *const TerraBridgeErrorDomain = @"co.tryterra.sdk.bridge";
+
+@implementation TerraBridgeModule {
+  TerraBridgeModuleImpl *_impl;
+}
+
+RCT_EXPORT_MODULE(TerraBridge)
+
+- (instancetype)init
+{
+  if (self = [super init]) {
+    __weak TerraBridgeModule *weakSelf = self;
+    _impl = [[TerraBridgeModuleImpl alloc] initWithEmit:^(NSString *subscriptionId, NSString *message) {
+      [weakSelf emitOnMessage:@{@"subscriptionId" : subscriptionId, @"message" : message}];
+    }];
+  }
+  return self;
+}
+
+static void (^TerraReject(RCTPromiseRejectBlock reject))(NSString *, NSString *, NSString *)
+{
+  return ^(NSString *code, NSString *message, NSString *payload) {
+    reject(code, message, [NSError errorWithDomain:TerraBridgeErrorDomain code:0 userInfo:@{@"payload" : payload}]);
+  };
+}
+
+- (void)invoke:(NSString *)op
+       payload:(NSString *)payload
+       resolve:(RCTPromiseResolveBlock)resolve
+        reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl invoke:op
+        payload:payload
+        resolve:^(NSString *response) { resolve(response); }
+         reject:TerraReject(reject)];
+}
+
+- (void)subscribe:(NSString *)stream
+           params:(NSString *)params
+          resolve:(RCTPromiseResolveBlock)resolve
+           reject:(RCTPromiseRejectBlock)reject
+{
+  [_impl subscribe:stream
+            params:params
+           resolve:^(NSString *subscriptionId) { resolve(subscriptionId); }
+            reject:TerraReject(reject)];
+}
+
+- (void)unsubscribe:(NSString *)subscriptionId
+{
+  [_impl unsubscribe:subscriptionId];
+}
+
+- (void)invalidate
+{
+  [_impl invalidate];
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+  return std::make_shared<facebook::react::NativeTerraBridgeSpecJSI>(params);
+}
+
+@end

package/ios/TerraBridgeModuleImpl.swift

@@ -0,0 +1,49 @@
+import Foundation
+
+@objc(TerraBridgeModuleImpl)
+public final class TerraBridgeModuleImpl: NSObject, @unchecked Sendable {
+    public typealias Resolve = @Sendable (String) -> Void
+    /// `(code, message, payload JSON)`. The module rejects with the payload under `userInfo.payload`.
+    public typealias Reject = @Sendable (String, String, String) -> Void
+
+    private let attachment: RuntimeAttachment
+
+    @objc public init(emit: @escaping @Sendable (_ subscriptionId: String, _ message: String) -> Void) {
+        attachment = RuntimeAttachment(missingLine: TerraReactNative.missingLine, emit: emit)
+    }
+
+    /// Nothing answers a runtime that has been invalidated: its promises belong to a JS context that is gone.
+    @objc public func invoke(_ op: String, payload: String, resolve: @escaping Resolve, reject: @escaping Reject) {
+        let attachment = attachment
+        Task {
+            do throws(BridgeRejection) {
+                guard let session = try attachment.session() else { return }
+                let answer = try await session.dispatch(op: op, payload: payload)
+                if !attachment.isInvalidated { resolve(answer) }
+            } catch {
+                if !attachment.isInvalidated { reject(error.code, error.payload.message, error.json) }
+            }
+        }
+    }
+
+    @objc public func subscribe(_ stream: String, params: String, resolve: @escaping Resolve, reject: @escaping Reject) {
+        let attachment = attachment
+        Task {
+            do throws(BridgeRejection) {
+                guard let session = try attachment.session() else { return }
+                let id = try await session.subscribe(stream: stream, params: params)
+                if !attachment.isInvalidated { resolve(id) }
+            } catch {
+                if !attachment.isInvalidated { reject(error.code, error.payload.message, error.json) }
+            }
+        }
+    }
+
+    @objc public func unsubscribe(_ subscriptionId: String) {
+        attachment.current()?.unsubscribe(id: subscriptionId)
+    }
+
+    @objc public func invalidate() {
+        attachment.invalidate()
+    }
+}

package/ios/TerraReactNative.swift

@@ -0,0 +1,19 @@
+import Foundation
+import os
+
+/// iOS raises if a background task is registered after launch finishes.
+/// A HealthKit wake never starts a JavaScript runtime.
+@objc(TerraReactNative)
+public final class TerraReactNative: NSObject {
+    static let missingLine = "TerraReactNative.bootstrap() in application(_:didFinishLaunchingWithOptions:), with TerraDevID in Info.plist"
+
+    private static let log = Logger(subsystem: "co.tryterra.sdk", category: "TerraReactNative")
+
+    /// Builds the client, registers background sync, and parks both for JavaScript to attach to.
+    /// Safe to call more than once; the second call does nothing.
+    @objc public static func bootstrap() {
+        if BridgeBootstrap.bootstrap(bundle: .main) == nil {
+            log.error("Terra is not set up: Info.plist has no \(BridgeBootstrap.devIDKey, privacy: .public)")
+        }
+    }
+}

package/lib/EndUser.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare const EndUser: {
+    /** The person your backend knows as `id`: the same value it mints their token with. */
+    readonly reference: (id: string) => EndUser;
+    /** Nobody your backend tracks. Every anonymous connect on one device is the same person. */
+    readonly anonymous: EndUser;
+};

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,154 @@
+/**
+ * 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 { BodyEntry, BootstrapState, Connection, DataCategory, DiagnosticsState, EndUser, HealthAccess, HealthChange, HeartRateEntry, HeartRateSample, NutritionEntry, PermissionStatus, PlannedWorkout, WorkoutSchedulingStatus, SleepEntry, SleepSegment, Source, StepCount, StepEntry, SupportReport, TerraEvent, TimeRange, Workout, WorkoutEntry } 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 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;
+    /** `undefined` on Android, which has no planned workouts. */
+    readonly plannedWorkouts: PlannedWorkouts | undefined;
+    private readonly ops;
+    private readonly streams;
+    /** Settles once the token provider, when there is one, can be asked. */
+    private readonly tokensReady;
+    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>;
+    /** Answers the native broker's token requests with `provider`, for the lifetime of this runtime. */
+    private answerTokens;
+}
+export {};