@tryterra/react-native 0.0.0-stage → 2.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# @tryterra/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Terra's health SDK for React Native: Apple Health on iOS, Health Connect (and optionally Samsung
+Health) on Android. A TurboModule over the native SDKs in this repository. React Native 0.81 or
+newer, New Architecture only.
+
+```ts
+import { createTerra, EndUser } from "@tryterra/react-native";
+
+const terra = createTerra({ tokenProvider: () => api.terraToken() });
+
+await terra.connect("health", EndUser.reference(user.id));
+await terra.permissions.request({ read: ["body"] });
+const hr = await terra.body.heartRate({ kind: "lastHours", hours: 1 });
+```
+
+There is no sync call: once connected, the SDK uploads on its own, in the background too. Every
+rejection is a `TerraError` with a stable `code` (see `docs/availability.md` for the full list and
+what exists on which platform).
+
+## Local reads
+
+Every read goes straight to the device's store and never touches the network:
+
+| Member | Answers | Platforms |
+|---|---|---|
+| `body.heartRate(range)` | `HeartRateSample[]` | both |
+| `body.restingHeartRate(range)` | `RestingHeartRateSample[]`, the store's own daily figure | both; Android grants it under `daily` |
+| `body.readings(range)` | `BodyReading[]`, each `kind` carrying its unit | both; `bmi` and wrist temperature iOS only |
+| `daily.steps(range)` | `StepCount[]` | both |
+| `daily.totals(range)` | `DayTotal[]`, one per metric per whole local day | both; `appleExerciseTime` iOS only |
+| `daily.intraday(range)` | `IntradaySample[]` | both; `basalEnergy` iOS only |
+| `sleep.segments(range)` | `SleepSegment[]` | both |
+| `activity.workouts(range)` | `Workout[]`, with the writer's `title` where it set one | both |
+| `activity.routes(range)` | `WorkoutRoute[]`, each naming its workout | both |
+| `activity.intensity(range)` | `WorkoutIntensitySample[]` | both; no `workoutId` on Android |
+| `nutrition.quantities(range)` | `DietaryQuantity[]`, one per nutrient, not grouped into meals | both |
+| `nutrition.hydration(range)` | `HydrationSample[]`, in millilitres | both |
+| `menstruation.flow(range)` | `MenstruationFlowDay[]`, one per logged day | both |
+| `menstruation.events(range)` | `MenstrualEvent[]`: ovulation tests, cervical mucus, intermenstrual bleeding | both |
+| `athlete?.profile()` | `AthleteProfile`, or `undefined` where the store has none | iOS; `terra.athlete` is `undefined` on Android |
+
+Ask for the category first: `permissions.request({ read: ["nutrition", "menstruation"] })`, plus
+`"athlete"` on iOS, without which HealthKit hides the characteristics and `profile()` answers
+`notSet` and nothing else. A read rejects with `not_connected` before `connect`, and with
+`permission_denied` naming the category in `details.category` when the grant was refused.
+
+`terra.availability(source?)` answers before any of them, with no connection: `available`, or why
+not - `unsupportedDevice` on iOS, and on Android the reason Health Connect gives, such as
+`providerAppMissing` when it needs installing.
+
+## Native setup
+
+The client is built natively at launch, before any JavaScript runs, because background delivery
+needs it then. Both platforms read the dev id from native configuration.
+
+### iOS
+
+1. `Info.plist`: `TerraDevID`, `NSHealthShareUsageDescription`, `NSHealthUpdateUsageDescription`,
+   `UIBackgroundModes` with `fetch`, and `BGTaskSchedulerPermittedIdentifiers` with
+   `co.tryterra.sdk.refresh`.
+2. Entitlements: `com.apple.developer.healthkit`, `com.apple.developer.healthkit.access` (an empty
+   array) and `com.apple.developer.healthkit.background-delivery`.
+3. One line, first thing in `application(_:didFinishLaunchingWithOptions:)`:
+
+   ```swift
+   import TerraReactNative
+   TerraReactNative.bootstrap()
+   ```
+
+   Without it every call rejects with `bridge.not_bootstrapped`, and `details.line` names the line.
+
+### Android
+
+1. `minSdkVersion` 28, `compileSdkVersion` 36.
+2. In `<application>`: `<meta-data android:name="co.tryterra.sdk.DEV_ID" android:value="..." />`.
+   Nothing else in code: an `androidx.startup` initializer bootstraps before `Application.onCreate`.
+   An app that removed WorkManager's default initializer, to configure WorkManager itself, adds
+   `TerraReactNative.bootstrap(this)` at the end of `Application.onCreate`.
+3. One `<uses-permission android:name="android.permission.health.*">` per Health Connect type your
+   `permissions.request` reads, plus the permissions-rationale activity filters. `example/` has a
+   complete manifest.
+
+### Samsung Health (Android, optional)
+
+1. Get Samsung's partner approval and download `samsung-health-data-api.aar` (Health Data SDK
+   1.1.0) from Samsung. Samsung's licence forbids anyone else redistributing it.
+2. Add it to your app module: `implementation(files("libs/samsung-health-data-api.aar"))`.
+3. Set `terraSamsungHealth=true` in `android/gradle.properties`.
+
+Then `terra.connect("samsungHealth", ...)`, `terra.permissions.request({...}, "samsungHealth")` and
+`terra.diagnostics.state("samsungHealth")` reach Samsung Health directly. Reads, writes and change
+streams are Health Connect's. Without step 3, `samsungHealth` rejects with
+`health_data_unavailable`.
+
+## Developing in this repository
+
+```
+npm ci && npx tsc --noEmit && npx jest       # the JS lane (surface.yml)
+npm run build                                 # lib/, the types the example compiles against
+cd example && npm ci && npx tsc --noEmit      # the example's typecheck (react-native.yml)
+npm run pods                                  # then: npm run ios / npm run android
+```
+
+`npm run pods` is a plain `pod install` (CocoaPods from Homebrew or `gem install`). The Podfile
+takes React Native's core prebuilt, as CI does; built from source it does not compile under Xcode 26
+and rewrites `Podfile.lock`.
+
+`example/` builds against this checkout's SDKs, not the published ones: its Podfile sets
+`TERRA_IOS_SDK_FROM_SOURCE=1` and points `TerraiOS` at `ios/TerraiOS.podspec`, and
+`npm run android` first publishes `android/` into `android/build/published`, the only repository
+the example takes `co.tryterra:terra-android` from.
+`xcrun simctl launch booted co.tryterra.reactnative.example -terraSmoke` (or
+`adb shell am start -a android.intent.action.VIEW -d terraexample://smoke`) runs its smoke test.
+
+How the native halves ship, and why, is `docs/distribution.md`.
+
+## Releasing
+
+The package pins one version of each native SDK in `package.json`'s `terraNative`, and
+`packaging.test.ts` holds those pins equal to `sdkVersion` in `ios/Sources/TerraSDK/Version.swift`
+and `VERSION_NAME` in `android/gradle.properties`. The tarball carries the released
+`TerraSDK.xcframework` (`prepack` downloads it from the `tryterra/TerraiOS` release and checks it
+against the checksum that tag's `Package.swift` pins), and a customer's Gradle sync resolves the
+Android SDK from Maven Central, so the wrapper is released last:
+
+1. Release iOS (`v<version>`, then the `tryterra/TerraiOS` steps in the root README) and Android
+   (`android-v<version>`, then release the staged bundle from the Central Portal).
+2. Push `react-native-v<version>`. `.github/workflows/react-native-release.yml` checks the tag
+   against `version`, refuses while either native pin is missing from the `tryterra/TerraiOS`
+   release or Central, packs, and publishes with `npm publish --access public` (a pre-release under
+   the `next` dist-tag).
+
+The workflow publishes through npm trusted publishing, with no npm secret in this repository. It
+works once the package's settings on npmjs.com list `tryterra/terra-mobile` and
+`react-native-release.yml` as a trusted publisher; npm allows that only after the package exists, so
+the first version is published by hand with `npm publish --access public` from `react-native/`. A
+version already on npm is skipped.
+
+`npm pack --dry-run` shows the tarball. `prepack` builds `lib/`, copies hybrid-common into
+`ios/TerraBridgeCore` and `android/src/bridgeCore`, and fetches `frameworks/TerraSDK.xcframework`
+(`npm run fetch-sdk`), none of which a checkout carries. The xcframework is most of the tarball's
+12.6 MB.

package/TerraReactNative.podspec

@@ -0,0 +1,48 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+# hybrid-common's Swift, copied in by scripts/vendor-bridge-core.js: from `prepack` for the npm
+# tarball, and from the example app's Podfile in this repository. A podspec cannot reach a source
+# file outside its own directory, so without the copy this pod would compile a module with no
+# bridge in it and fail at link time far from the cause.
+bridge_core = File.join(__dir__, "ios", "TerraBridgeCore")
+unless File.directory?(bridge_core)
+  raise "TerraReactNative: #{bridge_core} is missing. In a terra-mobile checkout run " \
+        "`npm run vendor` in react-native/; an installed package always carries it."
+end
+
+Pod::Spec.new do |s|
+  s.name         = "TerraReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://github.com/tryterra/terra-mobile"
+  s.license      = package["license"]
+  s.authors      = "Terra"
+  # RN 0.81's own floor; TerraSDK's is 15.0.
+  s.platforms    = { :ios => "15.1" }
+  s.source       = { :git => "https://github.com/tryterra/terra-mobile.git", :tag => "v#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  # hybrid-common is written in the Swift 6 language mode, and its concurrency checking is part of
+  # what it promises.
+  s.swift_version = "6.0"
+
+  # CocoaPods trunk takes no new releases; React Native's `spm_dependency` links dynamic
+  # binary targets without embedding them in the app.
+  if ENV["TERRA_IOS_SDK_FROM_SOURCE"] == "1"
+    s.dependency "TerraiOS", package["terraNative"]["ios"]
+  else
+    sdk = File.join(__dir__, "frameworks", "TerraSDK.xcframework")
+    unless File.directory?(sdk)
+      raise "TerraReactNative: #{sdk} is missing. In a terra-mobile checkout run " \
+            "`npm run fetch-sdk` in react-native/, or set TERRA_IOS_SDK_FROM_SOURCE=1; an installed " \
+            "package always carries it."
+    end
+    s.vendored_frameworks = "frameworks/TerraSDK.xcframework"
+  end
+
+  s.pod_target_xcconfig = { "DEFINES_MODULE" => "YES" }
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,87 @@
+import groovy.json.JsonSlurper
+
+buildscript {
+  // The host's Kotlin, so the serialization plugin matches the compiler that runs it.
+  ext.terraKotlinVersion = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : "2.1.20"
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    // hybrid-common's generated DTOs are @Serializable. A host's root build has the Kotlin plugin
+    // already; the serialization plugin it has no reason to carry.
+    classpath "org.jetbrains.kotlin:kotlin-serialization:${terraKotlinVersion}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "org.jetbrains.kotlin.plugin.serialization"
+apply plugin: "com.facebook.react"
+
+def packageJson = new JsonSlurper().parse(file("../package.json"))
+// The native SDK, exactly the version this package was released against. In this repository the
+// example's settings.gradle includes ../android as a build, which substitutes the project for it.
+def terraAndroidVersion = packageJson.terraNative.android
+
+// hybrid-common compiled in place inside a terra-mobile checkout, so this build can never compile a
+// stale copy; inside an npm tarball, the copy `prepack` made (scripts/vendor-bridge-core.js).
+// Canonical, because a `file:..` install reaches this project through a node_modules symlink, and
+// the checkout is only one level up from where the link points.
+def bridgeCoreInRepo = new File(projectDir.canonicalFile, "../../hybrid-common/android/src/main/kotlin").canonicalFile
+def bridgeCore = bridgeCoreInRepo.exists() ? bridgeCoreInRepo : file("src/bridgeCore/kotlin")
+if (!bridgeCore.exists()) {
+  throw new GradleException("@tryterra/react-native: hybrid-common sources are missing at ${bridgeCore}")
+}
+
+// Samsung Health is opt-in, because the host has to supply Samsung's SDK itself: Samsung's licence
+// forbids redistributing it, so no artifact of ours can carry it (see
+// android/terra-android-samsung/libs/README.md). A host sets `terraSamsungHealth=true` in its
+// gradle.properties and adds `samsung-health-data-api.aar` to its app; this module then depends on
+// the add-on and registers its store at launch.
+def samsungHealth = (rootProject.findProperty("terraSamsungHealth") ?: "false").toString().toBoolean()
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "co.tryterra.sdk.reactnative"
+  compileSdkVersion safeExtGet("compileSdkVersion", 36)
+
+  defaultConfig {
+    // The SDK's floor, above React Native's own 24.
+    minSdkVersion Math.max(28, safeExtGet("minSdkVersion", 28) as int)
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [bridgeCore.path, samsungHealth ? "src/samsung/kotlin" : "src/healthConnectOnly/kotlin"]
+    }
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  api "co.tryterra:terra-android:${terraAndroidVersion}"
+  if (samsungHealth) {
+    implementation "co.tryterra:terra-android-samsung:${terraAndroidVersion}"
+  }
+  implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.1"
+  implementation "androidx.startup:startup-runtime:1.2.0"
+}

package/android/src/bridgeCore/kotlin/README.md

@@ -0,0 +1 @@
+Copied from hybrid-common by scripts/vendor-bridge-core.js. Do not edit; change hybrid-common.

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/BridgeBootstrap.kt

@@ -0,0 +1,133 @@
+package co.tryterra.sdk.bridge
+
+import android.app.Activity
+import android.app.Application
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Bundle
+import android.util.Log
+import androidx.activity.result.ActivityResultCaller
+import co.tryterra.sdk.SDK_VERSION
+import co.tryterra.sdk.Source
+import co.tryterra.sdk.StoreRegistration
+import co.tryterra.sdk.Terra
+import co.tryterra.sdk.TerraError
+import co.tryterra.sdk.background.BackgroundSync
+import co.tryterra.sdk.bridge.generated.BridgeError
+import co.tryterra.sdk.permissions.PermissionLauncher
+import java.util.concurrent.atomic.AtomicReference
+import kotlinx.coroutines.CoroutineScope
+
+public object BridgeBootstrap {
+
+    /** The manifest meta-data carrying the developer id. */
+    public const val DEV_ID_KEY: String = "co.tryterra.sdk.DEV_ID"
+
+    private const val TAG = "TerraBridge"
+
+    /** What bootstrap parked: the client, and the broker the client was built with. */
+    public class Parked internal constructor(
+        public val terra: Terra,
+        internal val tokens: TokenBroker,
+        internal val host: BridgeHost,
+    )
+
+    private val parked = AtomicReference<Parked?>(null)
+
+    /** What bootstrap parked, or null when it has not run. */
+    public val current: Parked? get() = parked.get()
+
+    @Synchronized
+    public fun bootstrap(context: Context, stores: StoreRegistration.() -> Unit = {}): Parked? {
+        parked.get()?.let { return it }
+        val app = context.applicationContext as Application
+        val meta = metaData(app)
+        val devId = meta?.getString(DEV_ID_KEY)?.trim()?.takeIf { it.isNotEmpty() }
+        if (devId == null) {
+            Log.e(TAG, "no <meta-data android:name=\"$DEV_ID_KEY\"> in the app manifest, so Terra is not set up")
+            return null
+        }
+
+        val tokens = TokenBroker()
+        val terra = Terra(app, devId, tokenProvider = tokens::provide, stores = stores)
+        val launchers = Launchers(terra, servedSources(terra))
+        app.registerActivityLifecycleCallbacks(launchers)
+        val registered = BackgroundSync.register(app, terra)
+        val result = Parked(terra, tokens, LaunchHost(app, terra, launchers, devId, registered))
+        parked.set(result)
+        return result
+    }
+
+    public fun attach(scope: CoroutineScope, missingLine: String, emit: (String, String) -> Unit): TerraBridge {
+        val current = parked.get()
+            ?: throw TerraBridge.BridgeRejection(Rejections.of(BridgeError.NotBootstrapped(missingLine)))
+        return TerraBridge(current.terra, current.tokens, current.host, scope, emit = emit)
+    }
+
+    private fun metaData(app: Application): Bundle? = try {
+        app.packageManager.getApplicationInfo(app.packageName, PackageManager.GET_META_DATA).metaData
+    } catch (missing: PackageManager.NameNotFoundException) {
+        null
+    }
+
+    /** The sources [terra] has a store for, asked of the client itself rather than tracked beside it. */
+    internal fun servedSources(terra: Terra): Set<Source> = Source.entries.filterTo(LinkedHashSet()) { source ->
+        try {
+            terra.on(source)
+            true
+        } catch (missing: TerraError.HealthDataUnavailable) {
+            false
+        }
+    }
+
+    internal class Launchers(
+        private val terra: Terra,
+        private val sources: Set<Source>,
+    ) : Application.ActivityLifecycleCallbacks {
+        private val slots = LauncherSlots<Activity, PermissionLauncher>()
+
+        fun current(source: Source): PermissionLauncher? = slots.current(source)
+
+        override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {
+            if (activity !is ActivityResultCaller) return
+            val made = sources.mapNotNull { source ->
+                try {
+                    source to terra.on(source).permissions.launcher(activity)
+                } catch (refused: RuntimeException) {
+                    Log.w(TAG, "no permission sheet for $source in ${activity.javaClass.simpleName}", refused)
+                    null
+                }
+            }.toMap()
+            slots.created(activity, made)
+        }
+
+        override fun onActivityDestroyed(activity: Activity) {
+            slots.destroyed(activity)?.values?.forEach { it.unregister() }
+        }
+
+        override fun onActivityStarted(activity: Activity) = slots.started(activity)
+        override fun onActivityStopped(activity: Activity) = slots.stopped(activity)
+        override fun onActivityResumed(activity: Activity) {}
+        override fun onActivityPaused(activity: Activity) {}
+        override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}
+    }
+
+    private class LaunchHost(
+        private val app: Application,
+        private val terra: Terra,
+        private val launchers: Launchers,
+        override val devId: String,
+        private val registered: Boolean,
+    ) : BridgeHost {
+        override fun permissionLauncher(source: Source): PermissionLauncher? = launchers.current(source)
+
+        override suspend fun backgroundRegistered(): Boolean =
+            registered && BackgroundSync.isScheduled(app, Terra.DEFAULT_STORAGE_DOMAIN) != false
+
+        override suspend fun cancelBackgroundSync(): Boolean = BackgroundSync.cancel(app, terra)
+
+        override val platform: String = "android"
+
+        override val sdkVersion: String = SDK_VERSION
+    }
+}

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/BridgeHost.kt

@@ -0,0 +1,32 @@
+package co.tryterra.sdk.bridge
+
+import co.tryterra.sdk.Source
+import co.tryterra.sdk.permissions.PermissionLauncher
+
+/**
+ * The parts of an op that are not the SDK: the permission sheet's launcher, and the scheduler.
+ *
+ * A seam rather than a `Context` parameter, for the reason `HealthStore` is one in the SDK itself:
+ * everything behind it needs a device, and everything in front of it can then be decided on a plain
+ * JVM. `TerraBridgeOpsImpl` holds no `Context`, so the whole dispatch is testable on `ubuntu-latest`
+ * with no emulator - which is the lane that catches the disease this wrapper exists to cure.
+ */
+public interface BridgeHost {
+
+    /** The launcher the current activity registered for [source]'s permission sheet, or null when none has. */
+    public fun permissionLauncher(source: Source): PermissionLauncher?
+
+    /** Whether the scheduler holds this client's periodic work. False means bootstrap did not run. */
+    public suspend fun backgroundRegistered(): Boolean
+
+    /** Drops the schedule. Android only; there is no iOS counterpart. */
+    public suspend fun cancelBackgroundSync(): Boolean
+
+    /** What `client.attach` reports, so a host can tell a misconfiguration from a bug. */
+    public val platform: String
+
+    public val sdkVersion: String
+
+    /** The dev id the native bootstrap was configured with, or null when it did not run. */
+    public val devId: String?
+}