@tryterra/react-native 0.0.0-stage → 2.2.1

package/ios/TerraBridgeCore/TerraBridgeOpsImpl.swift

@@ -0,0 +1,318 @@
+import Foundation
+@_spi(Bridge) import TerraSDK
+
+/// The hand-written half: one short function per op.
+///
+/// It cannot be incomplete, because `TerraBridgeOps` is generated from the schema and an op added
+/// there stops this compiling. Conversions live in `Conversions`; what is left is the shape of each
+/// call, and the one place Apple's surface differs from the wire's: `sync`, `disconnect` and plans
+/// hang off a `Connection` here rather than off the client.
+struct TerraBridgeOpsImpl: TerraBridgeOps {
+    let terra: Terra
+    let host: any BridgeHost
+    let broker: TokenBroker
+    let audience: TokenAudience
+
+    // MARK: client
+
+    func clientAttach(_ request: Empty) async throws -> BootstrapState {
+        BootstrapState(
+            bootstrapped: true,
+            devId: host.devID,
+            platform: "ios",
+            sdkVersion: TerraSDK.sdkVersion,
+            backgroundRegistered: await host.backgroundRegistered())
+    }
+
+    func clientConnect(_ request: ConnectRequest) async throws -> Connection {
+        let source = try Conversions.source(request.source)
+        let endUser = Conversions.endUser(request.endUser)
+        if let token = request.token {
+            return Conversions.connection(try await terra.connect(source, for: endUser, using: token))
+        }
+        // The client's provider is the broker, so it is never nil, and the SDK's answer for a
+        // revoked link with no provider - `linkRevoked` - would become the broker's "nobody is
+        // listening". So the bridge answers it here, before any link starts.
+        if await !broker.canAnswer, await terra.needsTokenForRevokedLink(source, for: endUser) {
+            throw TerraError.linkRevoked(source)
+        }
+        return Conversions.connection(try await terra.connect(source, for: endUser))
+    }
+
+    func clientConnections(_ request: Empty) async throws -> ConnectionList {
+        ConnectionList(connections: try await terra.connections.map(Conversions.connection))
+    }
+
+    func clientAvailability(_ request: SourceRequest) async throws -> AvailabilityResult {
+        AvailabilityResult(availability: Conversions.availability(
+            await terra.availability(for: try Conversions.source(request.source))))
+    }
+
+    func clientDisconnect(_ request: SourceRequest) async throws -> Empty {
+        try await connection(request.source).disconnect()
+        return Empty()
+    }
+
+    // MARK: token
+
+    func tokenSetProviderPresent(_ request: TokenProviderRequest) async throws -> Empty {
+        await broker.setProviderPresent(request.present, timeoutMs: request.timeoutMs, audience: audience)
+        return Empty()
+    }
+
+    func tokenResolve(_ request: TokenResolveRequest) async throws -> Empty {
+        await broker.resolve(request.requestId, token: request.token)
+        return Empty()
+    }
+
+    func tokenReject(_ request: TokenRejectRequest) async throws -> Empty {
+        await broker.reject(request.requestId, message: request.message)
+        return Empty()
+    }
+
+    // MARK: permissions
+
+    /// HealthKit will not say what was granted for reads, so Apple answers nothing.
+    func permissionsRequest(_ request: PermissionRequest) async throws -> PermissionGrant {
+        _ = try Conversions.source(request.source)
+        try await terra.permissions.request(
+            read: request.read.map(Conversions.category),
+            write: request.write.map(Conversions.category),
+            workouts: request.workouts.map(Conversions.scope))
+        return PermissionGrant()
+    }
+
+    func permissionsStatus(_ request: CategoryRequest) async throws -> StatusResult {
+        _ = try Conversions.source(request.source)
+        return StatusResult(status: Conversions.permissionStatus(
+            await terra.permissions.status(for: Conversions.category(request.category))))
+    }
+
+    func permissionsWriteStatus(_ request: CategoryRequest) async throws -> StatusResult {
+        _ = try Conversions.source(request.source)
+        return StatusResult(status: Conversions.permissionStatus(
+            await terra.permissions.writeStatus(for: Conversions.category(request.category))))
+    }
+
+    func permissionsRequested(_ request: SourceRequest) async throws -> HealthAccess {
+        _ = try Conversions.source(request.source)
+        return Conversions.access(await terra.permissions.requested)
+    }
+
+    // MARK: diagnostics
+
+    func diagnosticsState(_ request: SourceRequest) async throws -> DiagnosticsState {
+        Conversions.diagnosticsState(await terra.diagnostics.state(for: try Conversions.source(request.source)))
+    }
+
+    func diagnosticsLastDelivery(_ request: SourceRequest) async throws -> LastDeliveryResult {
+        let at = await terra.diagnostics.lastDelivery(for: try Conversions.source(request.source))
+        return LastDeliveryResult(at: at.map(BridgeInstant.format))
+    }
+
+    func diagnosticsReport(_ request: SourceRequest) async throws -> SupportReport {
+        try Conversions.report(await terra.diagnostics.report(for: try Conversions.source(request.source)))
+    }
+
+    func diagnosticsSend(_ request: SourceRequest) async throws -> Empty {
+        try await terra.diagnostics.send(for: try Conversions.source(request.source))
+        return Empty()
+    }
+
+    // MARK: background
+
+    func backgroundIsRegistered(_ request: Empty) async throws -> BoolResult {
+        BoolResult(value: await host.backgroundRegistered())
+    }
+
+    // MARK: body
+
+    func bodyHeartRate(_ request: RangeRequest) async throws -> HeartRateList {
+        HeartRateList(samples: try await terra.body.heartRate(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.heartRate))
+    }
+
+    func bodyRestingHeartRate(_ request: RangeRequest) async throws -> RestingHeartRateList {
+        RestingHeartRateList(samples: try await terra.body.restingHeartRate(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.restingHeartRate))
+    }
+
+    func bodyReadings(_ request: RangeRequest) async throws -> BodyReadingList {
+        BodyReadingList(samples: try await terra.body.readings(in: Conversions.timeRange(request.range, at: "$.range"))
+            .compactMap(Conversions.bodyReading))
+    }
+
+    func bodyLogHeartRate(_ request: HeartRateEntryList) async throws -> RecordIdList {
+        ids(try await terra.body.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func bodyLog(_ request: BodyEntryList) async throws -> RecordIdList {
+        ids(try await terra.body.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func bodyDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.body.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: daily
+
+    func dailySteps(_ request: RangeRequest) async throws -> StepCountList {
+        StepCountList(samples: try await terra.daily.steps(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.steps))
+    }
+
+    func dailyTotals(_ request: RangeRequest) async throws -> DayTotalList {
+        DayTotalList(totals: try await terra.daily.totals(in: Conversions.timeRange(request.range, at: "$.range"))
+            .compactMap(Conversions.dayTotal))
+    }
+
+    func dailyIntraday(_ request: RangeRequest) async throws -> IntradaySampleList {
+        IntradaySampleList(samples: try await terra.daily.intraday(in: Conversions.timeRange(request.range, at: "$.range"))
+            .compactMap(Conversions.intraday))
+    }
+
+    func dailyLog(_ request: StepEntryList) async throws -> RecordIdList {
+        ids(try await terra.daily.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func dailyDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.daily.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: sleep
+
+    func sleepSegments(_ request: RangeRequest) async throws -> SleepSegmentList {
+        SleepSegmentList(samples: try await terra.sleep.segments(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.segment))
+    }
+
+    func sleepLog(_ request: SleepEntryList) async throws -> RecordIdList {
+        ids(try await terra.sleep.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func sleepDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.sleep.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: activity
+
+    func activityWorkouts(_ request: RangeRequest) async throws -> WorkoutList {
+        WorkoutList(samples: try await terra.activity.workouts(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.workout))
+    }
+
+    func activityRoutes(_ request: RangeRequest) async throws -> WorkoutRouteList {
+        WorkoutRouteList(routes: try await terra.activity.routes(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.route))
+    }
+
+    func activityIntensity(_ request: RangeRequest) async throws -> WorkoutIntensityList {
+        WorkoutIntensityList(samples: try await terra.activity.intensity(in: Conversions.timeRange(request.range, at: "$.range"))
+            .compactMap(Conversions.intensity))
+    }
+
+    func activityLog(_ request: WorkoutEntryList) async throws -> RecordIdList {
+        ids(try await terra.activity.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func activityDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.activity.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    // MARK: nutrition
+
+    func nutritionQuantities(_ request: RangeRequest) async throws -> DietaryQuantityList {
+        DietaryQuantityList(samples: try await terra.nutrition.quantities(in: Conversions.timeRange(request.range, at: "$.range"))
+            .compactMap(Conversions.quantity))
+    }
+
+    func nutritionLog(_ request: NutritionEntryList) async throws -> RecordIdList {
+        ids(try await terra.nutrition.log(entries(request.entries, Conversions.entry)))
+    }
+
+    func nutritionDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await terra.nutrition.delete(id: Conversions.uuid(request.id, at: "$.id"))
+        return Empty()
+    }
+
+    func nutritionHydration(_ request: RangeRequest) async throws -> HydrationList {
+        HydrationList(samples: try await terra.nutrition.hydration(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.hydration))
+    }
+
+    // MARK: menstruation
+
+    func menstruationFlow(_ request: RangeRequest) async throws -> MenstruationFlowDayList {
+        MenstruationFlowDayList(samples: try await terra.menstruation.flow(in: Conversions.timeRange(request.range, at: "$.range"))
+            .map(Conversions.flowDay))
+    }
+
+    func menstruationEvents(_ request: RangeRequest) async throws -> MenstrualEventList {
+        MenstrualEventList(samples: try await terra.menstruation.events(in: Conversions.timeRange(request.range, at: "$.range"))
+            .compactMap(Conversions.menstrualEvent))
+    }
+
+    // MARK: athlete
+
+    func athleteProfile(_ request: Empty) async throws -> AthleteProfileResult {
+        AthleteProfileResult(profile: try await terra.athlete.profile()
+            .map { Conversions.athleteProfile($0, zone: .current) })
+    }
+
+    // MARK: planned workouts
+
+    func plannedWorkoutsPlanned(_ request: Empty) async throws -> PlannedWorkoutList {
+        PlannedWorkoutList(workouts: try await connection(nil).workouts.planned().map(Conversions.plannedWorkout))
+    }
+
+    func plannedWorkoutsMarkComplete(_ request: MarkCompleteRequest) async throws -> Empty {
+        let plans = try await connection(nil).workouts
+        if let at = request.at {
+            try await plans.markComplete(id: request.id, at: Conversions.instant(at, at: "$.at"))
+        } else {
+            try await plans.markComplete(id: request.id)
+        }
+        return Empty()
+    }
+
+    func plannedWorkoutsDelete(_ request: RecordIdRequest) async throws -> Empty {
+        try await connection(nil).workouts.delete(id: request.id)
+        return Empty()
+    }
+
+    func plannedWorkoutsSchedulingStatus(_ request: Empty) async throws -> WorkoutScheduling {
+        WorkoutScheduling(status: Conversions.schedulingStatus(
+            try await connection(nil).workouts.schedulingStatus()))
+    }
+
+    func plannedWorkoutsRequestScheduling(_ request: Empty) async throws -> WorkoutScheduling {
+        WorkoutScheduling(status: Conversions.schedulingStatus(
+            try await connection(nil).workouts.requestScheduling()))
+    }
+
+    // MARK: -
+
+    /// Apple hangs per-link behaviour on the `Connection`, so an op naming a source finds it first.
+    private func connection(_ wire: Source?) async throws -> TerraSDK.Connection {
+        let source = try Conversions.source(wire)
+        guard let connection = try await terra.connections.first(where: { $0.source == source }) else {
+            throw TerraError.notConnected(source)
+        }
+        return connection
+    }
+
+    /// Each entry converted with its own path, so a bad one is named by index.
+    private func entries<Wire, Entry>(
+        _ wire: [Wire], _ convert: (Wire, String) throws -> Entry
+    ) throws -> [Entry] {
+        try wire.enumerated().map { try convert($1, "$.entries[\($0)]") }
+    }
+
+    private func ids(_ ids: [UUID]) -> RecordIdList {
+        RecordIdList(ids: ids.map(\.uuidString))
+    }
+}

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;
+};