@honch/react-native-relay 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# Honch React Native Relay
+
+Release-candidate React Native relay package for companion apps that receive Honch relay frames from offline devices, durably assemble completed device messages, ACK durable receipt, and upload to Honch Capture.
+
+React Native Relay is not a device analytics SDK. Use it only when firmware cannot upload directly.
+
+## Status
+
+Release-candidate `0.1.0`. Production use still requires validation inside the consuming iOS and Android host apps. See [`PRODUCTION_READINESS.md`](PRODUCTION_READINESS.md).
+
+## Capture Contract
+
+Relay uploads use the canonical Capture endpoint:
+
+```text
+POST /capture
+Content-Type: application/vnd.honch.chunk
+X-Honch-Project-Key: <project_api_key>
+X-Honch-Stream-Id: <relay_stream_id>
+X-Honch-Relay-Id: <mobile_relay_id>
+X-Honch-Relay-SDK-Platform: react-native
+X-Honch-Relay-SDK-Version: <package_version>
+```
+
+Firmware relay chunks carry compact message bytes. The mobile relay validates and reassembles relay frames, durably stores the completed compact message, then uploads one or more HTTP chunk frames. It may re-chunk for HTTP but must not rewrite the compact device message body.
+
+## Setup
+
+Install this package and a production durable store into a React Native host app:
+
+```bash
+bun add @honch/react-native-relay
+```
+
+The consuming app must register native modules and run its normal iOS/Android dependency installation flow.
+
+## Durable Storage
+
+Production mobile apps should use MMKV. It is an optional peer dependency, so
+install it only when using `createMmkvRelayStore`:
+
+```bash
+bun add react-native-mmkv react-native-nitro-modules
+```
+
+```ts
+import { createMMKV } from "react-native-mmkv";
+import { createMmkvRelayStore } from "@honch/react-native-relay";
+
+const relayStore = createMmkvRelayStore(createMMKV({ id: "honch-relay" }));
+```
+
+The relay store only requires an MMKV-compatible object with `getString`,
+`set`, and `remove`, so host apps on `react-native-mmkv` v2, v3, or v4 can use
+their existing MMKV installation.
+
+MMKV relay storage uses per-chunk and per-message records with a small index, so receipt does not rewrite a full queue blob for every chunk. Binary frame, payload, and message bodies are stored as base64 strings instead of JSON number arrays. By default it retains up to 4,096 chunks and 1,024 completed messages with no time-based expiry, dropping the oldest entries once a cap is reached to bound offline growth. Time-based expiry is opt-in via `ttlMs`. Override these limits when the host app has a smaller storage budget:
+
+```ts
+const relayStore = createMmkvRelayStore(createMMKV({ id: "honch-relay" }), {
+  keyPrefix: "com.example.honch.relay",
+  maxChunks: 1024,
+  maxCompleteMessages: 256,
+  ttlMs: 3 * 24 * 60 * 60 * 1000
+});
+```
+
+Use `keyPrefix` when sharing an MMKV instance with host app data. The default
+prefix is `honch.relay`.
+
+All bundled stores share the same retention model: count caps on chunks and
+completed messages with drop-oldest eviction and no time-based expiry by default.
+`createMemoryDurableStore` and `createJsonFileRelayStore` accept `maxChunks` and
+`maxCompleteMessages` (defaults 4,096 / 1,024); `createMmkvRelayStore` adds the
+optional `ttlMs`.
+
+Completed messages and incomplete assemblies remain pending across app restarts until Capture accepts or permanently rejects them, unless they age out or the configured queue bounds require dropping oldest state. Retry attempts and next-attempt timestamps are stored with completed messages, so app restarts do not reset relay backoff or hammer Capture while a message is still inside its retry delay.
+
+## Host-Owned Bluetooth
+
+The relay package does not scan, connect, subscribe, request BLE permissions, or write BLE characteristics for the host app. Production apps should keep their existing Bluetooth stack and pass relay frames into the SDK:
+
+```ts
+import { createMobileRelay } from "@honch/react-native-relay";
+
+const relay = createMobileRelay({
+  durableStore,
+  uploaderConfig,
+  schedulerNative
+});
+
+hostBle.onRelayFrame(async ({ deviceId, frameBytes }) => {
+  await relay.receiveFrame(deviceId, frameBytes, {
+    acknowledge: async ({ ackBytes }) => {
+      await hostBle.writeRelayAck(deviceId, ackBytes);
+    }
+  });
+});
+```
+
+ACK bytes are emitted only after the received relay message has been durably assembled and stored. Malformed frames reject and do not produce ACK bytes. Duplicate completed frames can be ACKed again so firmware retries can settle.
+
+The Honch relay BLE UUIDs and frame format remain defined by `spec/relay-chunks.md`; the host app owns how those characteristics are discovered and wired into its device UX.
+
+## Native Host Requirements
+
+iOS:
+
+- Add the Bluetooth usage strings/background modes required by the host app's own BLE implementation.
+- iOS upload scheduling is foreground-only. Call `drainUploads()` from the host
+  app foreground lifecycle; `startUploadScheduler()` drains immediately without
+  native background scheduling when no scheduler binding is configured.
+
+Android:
+
+- Request the Bluetooth permissions required by the host app's own BLE implementation.
+- This package does not merge BLE, location, or notification permissions into
+  the host manifest.
+- Keep `androidx.work:work-runtime` available for scheduled upload drains.
+- Register the package through the consuming React Native Android host.
+- Register a headless JS task named `HonchRelayUpload` that calls the same durable queue drain path used by foreground upload drains.
+
+## Upload Draining
+
+`createMobileRelay` exposes:
+
+- `drainUploads()` to drain pending messages once;
+- `startUploadScheduler()` to start scheduled drains;
+- `stopUploadScheduler()` to cancel scheduled drain work.
+
+Retryable upload failures keep messages pending and schedule the next native upload attempt with relay backoff.
+If Capture returns `Retry-After` on a retryable response, that delay takes precedence over the local exponential backoff.
+Upload retry timing and attempt state stay in the JavaScript relay drain path and durable store. Android WorkManager only retries failures to launch the headless task, and the headless task timeout is capped at 10 seconds to bound wake-lock hold time.
+
+Android scheduled drains start the `HonchRelayUpload` headless JS task from WorkManager. Register the task in the host app entrypoint and call the app-owned relay singleton:
+
+```ts
+import { AppRegistry } from "react-native";
+
+AppRegistry.registerHeadlessTask("HonchRelayUpload", () => async () => {
+  await relay.drainUploads();
+});
+```
+
+## Test And Verification
+
+```bash
+bun run test
+bun run typecheck
+bun run e2e:capture
+bun run verify:ios:native
+bun run verify:android:native
+```
+
+These checks do not replace validation in a consuming host app. Production validation must include BLE behavior, durable storage across app restart, retry preservation, accepted Capture response handling, and live Capture ingestion.

package/android/build.gradle

@@ -0,0 +1,30 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+}
+
+plugins {
+  id "com.android.library"
+}
+
+android {
+  namespace "io.honch.reactnativerelay"
+  compileSdkVersion 35
+
+  defaultConfig {
+    minSdkVersion 23
+    targetSdkVersion 35
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  compileOnly "com.facebook.react:react-android:+"
+  implementation "androidx.work:work-runtime:2.9.1"
+}

package/android/gradle.properties

@@ -0,0 +1 @@
+android.useAndroidX=true

package/android/settings.gradle

@@ -0,0 +1,12 @@
+pluginManagement {
+  repositories {
+    google()
+    mavenCentral()
+    gradlePluginPortal()
+  }
+  plugins {
+    id "com.android.library" version "8.7.3"
+  }
+}
+
+rootProject.name = "HonchReactNativeRelayAndroid"

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application>
+        <service
+            android:name=".HonchRelayUploadTaskService"
+            android:exported="false" />
+    </application>
+</manifest>

package/android/src/main/java/io/honch/reactnativerelay/HonchReactNativeRelayModule.java

@@ -0,0 +1,67 @@
+package io.honch.reactnativerelay;
+
+import androidx.annotation.NonNull;
+import androidx.work.ExistingWorkPolicy;
+import androidx.work.OneTimeWorkRequest;
+import androidx.work.WorkManager;
+
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+
+import java.util.concurrent.TimeUnit;
+
+public class HonchReactNativeRelayModule extends ReactContextBaseJavaModule {
+    public static final String NAME = "HonchReactNativeRelay";
+
+    private final ReactApplicationContext reactContext;
+
+    public HonchReactNativeRelayModule(ReactApplicationContext reactContext) {
+        super(reactContext);
+        this.reactContext = reactContext;
+    }
+
+    @NonNull
+    @Override
+    public String getName() {
+        return NAME;
+    }
+
+    @ReactMethod
+    public void scheduleUpload(double delayMs, Promise promise) {
+        try {
+            OneTimeWorkRequest request = new OneTimeWorkRequest.Builder(HonchRelayUploadWorker.class)
+                .setInitialDelay((long)delayMs, TimeUnit.MILLISECONDS)
+                .setInputData(new androidx.work.Data.Builder().putLong("delayMs", (long)delayMs).build())
+                .addTag(HonchRelayUploadWorker.WORK_TAG)
+                .build();
+            WorkManager
+                .getInstance(reactContext)
+                .enqueueUniqueWork(HonchRelayUploadWorker.WORK_TAG, ExistingWorkPolicy.REPLACE, request);
+            promise.resolve(null);
+        } catch (RuntimeException error) {
+            promise.reject("schedule_upload_failed", error);
+        }
+    }
+
+    @ReactMethod
+    public void cancelUpload(Promise promise) {
+        try {
+            cancelScheduledUploads();
+            promise.resolve(null);
+        } catch (RuntimeException error) {
+            promise.reject("cancel_upload_failed", error);
+        }
+    }
+
+    @Override
+    public void invalidate() {
+        cancelScheduledUploads();
+        super.invalidate();
+    }
+
+    private void cancelScheduledUploads() {
+        WorkManager.getInstance(reactContext).cancelAllWorkByTag(HonchRelayUploadWorker.WORK_TAG);
+    }
+}

package/android/src/main/java/io/honch/reactnativerelay/HonchReactNativeRelayPackage.java

@@ -0,0 +1,28 @@
+package io.honch.reactnativerelay;
+
+import androidx.annotation.NonNull;
+
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+public class HonchReactNativeRelayPackage implements ReactPackage {
+    @NonNull
+    @Override
+    public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext reactContext) {
+        List<NativeModule> modules = new ArrayList<>();
+        modules.add(new HonchReactNativeRelayModule(reactContext));
+        return modules;
+    }
+
+    @NonNull
+    @Override
+    public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactContext) {
+        return Collections.emptyList();
+    }
+}

package/android/src/main/java/io/honch/reactnativerelay/HonchRelayUploadTaskService.java

@@ -0,0 +1,24 @@
+package io.honch.reactnativerelay;
+
+import android.content.Intent;
+
+import androidx.annotation.Nullable;
+
+import com.facebook.react.HeadlessJsTaskService;
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.WritableMap;
+import com.facebook.react.jstasks.HeadlessJsTaskConfig;
+
+public class HonchRelayUploadTaskService extends HeadlessJsTaskService {
+    public static final String TASK_NAME = "HonchRelayUpload";
+    public static final String EXTRA_DELAY_MS = "delayMs";
+    private static final long TASK_TIMEOUT_MS = 10000L;
+
+    @Nullable
+    @Override
+    protected HeadlessJsTaskConfig getTaskConfig(Intent intent) {
+        WritableMap data = Arguments.createMap();
+        data.putDouble(EXTRA_DELAY_MS, intent.getLongExtra(EXTRA_DELAY_MS, 0L));
+        return new HeadlessJsTaskConfig(TASK_NAME, data, TASK_TIMEOUT_MS, true);
+    }
+}

package/android/src/main/java/io/honch/reactnativerelay/HonchRelayUploadWorker.java

@@ -0,0 +1,34 @@
+package io.honch.reactnativerelay;
+
+import android.content.Context;
+import android.content.Intent;
+import android.util.Log;
+
+import androidx.annotation.NonNull;
+import androidx.work.Worker;
+import androidx.work.WorkerParameters;
+
+public class HonchRelayUploadWorker extends Worker {
+    public static final String WORK_TAG = "honch-relay-upload";
+    private static final String TAG = "HonchRelayUpload";
+
+    public HonchRelayUploadWorker(@NonNull Context context, @NonNull WorkerParameters params) {
+        super(context, params);
+    }
+
+    @NonNull
+    @Override
+    public Result doWork() {
+        Context context = getApplicationContext();
+        Intent intent = new Intent(context, HonchRelayUploadTaskService.class);
+        intent.putExtra(HonchRelayUploadTaskService.EXTRA_DELAY_MS, getInputData().getLong("delayMs", 0L));
+
+        try {
+            context.startService(intent);
+            return Result.success();
+        } catch (RuntimeException error) {
+            Log.e(TAG, "Failed to start relay upload task", error);
+            return Result.retry();
+        }
+    }
+}

package/example/App.tsx

@@ -0,0 +1,132 @@
+import React, { useEffect, useState } from "react";
+import {
+  SafeAreaView,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View
+} from "react-native";
+import type { StoredRelayMessage } from "@honch/react-native-relay";
+import { relay } from "./relay";
+
+export default function App() {
+  const [status, setStatus] = useState("idle");
+  const [pending, setPending] = useState<StoredRelayMessage[]>([]);
+  const [lastError, setLastError] = useState<string>("none");
+  const [lastReceivedDeviceId, setLastReceivedDeviceId] = useState<string>("none");
+
+  useEffect(() => {
+    void refreshPending();
+  }, []);
+
+  async function refreshPending() {
+    setPending(await relay.pending());
+  }
+
+  async function run(label: string, action: () => Promise<void>) {
+    setStatus(label);
+    setLastError("none");
+    try {
+      await action();
+      await refreshPending();
+      setStatus("idle");
+    } catch (error) {
+      setLastError(error instanceof Error ? error.message : String(error));
+      setStatus("error");
+    }
+  }
+
+  async function drainUploads() {
+    await run("draining", () => relay.drainUploads());
+  }
+
+  async function receiveHostFrame(
+    deviceId: string,
+    frameBytes: Uint8Array,
+    writeAck: (ackBytes: Uint8Array) => Promise<void>
+  ) {
+    await relay.receiveFrame(deviceId, frameBytes, {
+      acknowledge: async ({ ackBytes }) => {
+        await writeAck(ackBytes);
+        setLastReceivedDeviceId(deviceId);
+      }
+    });
+    await refreshPending();
+  }
+
+  void receiveHostFrame;
+
+  return (
+    <SafeAreaView style={styles.root}>
+      <ScrollView contentContainerStyle={styles.content}>
+        <Text style={styles.title}>Honch Relay Example</Text>
+        <View style={styles.section}>
+          <Text>Status: {status}</Text>
+          <Text>Pending messages: {pending.length}</Text>
+          <Text>Last received device: {lastReceivedDeviceId}</Text>
+          <Text>Last error: {lastError}</Text>
+        </View>
+        <View style={styles.actions}>
+          <TouchableOpacity style={styles.button} onPress={drainUploads}>
+            <Text style={styles.buttonText}>Drain Uploads</Text>
+          </TouchableOpacity>
+        </View>
+        <View style={styles.section}>
+          <Text style={styles.heading}>Pending Messages</Text>
+          {pending.map((message) => (
+            <View key={`${message.deviceId}:${message.sequence}`} style={styles.messageRow}>
+              <Text>{message.deviceId}</Text>
+              <Text>
+                seq {message.sequence} / {message.body.byteLength} bytes
+              </Text>
+            </View>
+          ))}
+        </View>
+      </ScrollView>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1
+  },
+  content: {
+    gap: 16,
+    padding: 20
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: "700"
+  },
+  section: {
+    gap: 8
+  },
+  heading: {
+    fontSize: 16,
+    fontWeight: "700"
+  },
+  actions: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    gap: 8
+  },
+  button: {
+    backgroundColor: "#111827",
+    borderRadius: 6,
+    paddingHorizontal: 12,
+    paddingVertical: 10
+  },
+  buttonText: {
+    color: "#ffffff",
+    fontWeight: "600"
+  },
+  messageRow: {
+    borderColor: "#d1d5db",
+    borderRadius: 6,
+    borderWidth: 1,
+    gap: 4,
+    padding: 12
+  }
+});

package/example/README.md

@@ -0,0 +1,37 @@
+# Honch React Native Relay Example
+
+This directory contains a host-app example shape for validating the preview
+React Native Relay package inside a consuming mobile app.
+
+`relay.ts` wires the package to `NativeModules.HonchReactNativeRelay`, stores
+relay queue state in MMKV, and exports the app-owned relay singleton used by
+both the foreground UI and Android headless upload task. `App.tsx` shows the
+host-owned handoff shape: the host app's BLE stack calls `relay.receiveFrame`
+with notification bytes and writes the returned ACK bytes itself.
+`index.ts` registers the `HonchRelayUpload` headless task.
+
+The example app should prove:
+
+- Host-owned BLE scan, discovery, connect, notify subscription, and ACK writes.
+- Relay chunk receipt and CRC validation.
+- Durable mobile-side message assembly.
+- Manual and scheduled upload draining.
+- iOS foreground upload draining from the host app lifecycle.
+- Android headless `HonchRelayUpload` task registration for scheduled drains.
+- Capture ingestion verification using a unique event name.
+
+Required app configuration:
+
+- Capture endpoint URL.
+- Honch project key or relay-scoped token.
+- Relay ID.
+- Bluetooth usage strings, background modes, and runtime permissions required by
+  the host app's own BLE implementation.
+- The relay package does not merge Android BLE, location, or notification
+  permissions; add host-app permissions only for host-owned BLE or separate
+  host features.
+
+The package directory is not a complete React Native host app. To run this
+example, copy the app into a generated React Native project or add platform
+host files (`ios/`, `android/`, `Podfile`, Gradle wrapper), then install this
+package through the host app.

package/example/index.ts

@@ -0,0 +1,10 @@
+import { AppRegistry } from "react-native";
+
+import App from "./App";
+import { relay } from "./relay";
+
+AppRegistry.registerComponent("HonchRelayExample", () => App);
+
+AppRegistry.registerHeadlessTask("HonchRelayUpload", () => async () => {
+  await relay.drainUploads();
+});

package/example/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "honch-react-native-relay-example",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "android": "react-native run-android",
+    "ios": "react-native run-ios",
+    "start": "react-native start"
+  },
+  "dependencies": {
+    "@honch/react-native-relay": "file:..",
+    "react": "latest",
+    "react-native": "latest",
+    "react-native-mmkv": "^4.3.1"
+  },
+  "devDependencies": {
+    "@react-native-community/cli": "latest",
+    "typescript": "latest"
+  }
+}

package/example/relay.ts

@@ -0,0 +1,27 @@
+import { NativeModules } from "react-native";
+import { createMMKV } from "react-native-mmkv";
+import {
+  createMmkvRelayStore,
+  createMobileRelay,
+  createRelayNativeBindings,
+  type StoredRelayMessage
+} from "@honch/react-native-relay";
+
+const captureConfig = {
+  endpointUrl: "http://127.0.0.1:8001",
+  projectKey: "test_key_123",
+  relayId: "mobile-relay-example",
+  relaySdkPlatform: "react-native",
+  relaySdkVersion: "0.1.0",
+  streamId: (message: StoredRelayMessage) => `relay-${message.deviceId}`,
+  messageId: (message: StoredRelayMessage) => Number(message.sequence)
+};
+
+const nativeModule = NativeModules.HonchReactNativeRelay;
+const bindings = createRelayNativeBindings(nativeModule);
+
+export const relay = createMobileRelay({
+  durableStore: createMmkvRelayStore(createMMKV({ id: "honch-relay-example" })),
+  uploaderConfig: captureConfig,
+  schedulerNative: bindings.schedulerNative
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@honch/react-native-relay",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "react-native": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "e2e:capture": "bun e2e/relay-capture-e2e.ts",
+    "verify:android:native": "scripts/verify-android-native.sh",
+    "verify:ios:native": "scripts/verify-ios-syntax.sh"
+  },
+  "peerDependencies": {
+    "react-native": ">=0.72",
+    "react-native-mmkv": ">=2 <5",
+    "react-native-nitro-modules": "^0.35.7"
+  },
+  "peerDependenciesMeta": {
+    "react-native-mmkv": {
+      "optional": true
+    },
+    "react-native-nitro-modules": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,11 @@
+export default {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: "./android",
+        packageImportPath: "import io.honch.reactnativerelay.HonchReactNativeRelayPackage;",
+        packageInstance: "new HonchReactNativeRelayPackage()"
+      }
+    }
+  }
+};

package/src/drain.ts

@@ -0,0 +1,36 @@
+import { nextBackoffDelayMs } from "./retry";
+import type { RelayQueue, StoredRelayMessage } from "./relayQueue";
+import type { RelayUploadOutcome } from "./uploader";
+
+export type DrainRelayQueueOptions = {
+  queue: RelayQueue;
+  upload(message: StoredRelayMessage): Promise<RelayUploadOutcome>;
+  now?: () => number;
+  random?: () => number;
+};
+
+export async function drainRelayQueue(options: DrainRelayQueueOptions): Promise<void> {
+  const now = options.now ?? Date.now;
+  const messages = await options.queue.pending();
+  for (const message of messages) {
+    const currentTimeMs = now();
+    if (message.nextAttemptAtMs !== undefined && message.nextAttemptAtMs > currentTimeMs) {
+      continue;
+    }
+    const outcome = await options.upload(message);
+    if (outcome.action === "consume") {
+      await options.queue.markUploaded(message.deviceId, message.sequence);
+      continue;
+    }
+    if (outcome.action === "drop") {
+      await options.queue.markDropped(message.deviceId, message.sequence);
+      continue;
+    }
+    const attempt = (message.retryAttempt ?? 0) + 1;
+    const delayMs = outcome.retryAfterMs ?? nextBackoffDelayMs(message.retryAttempt ?? 0, options.random);
+    await options.queue.markRetry(message.deviceId, message.sequence, {
+      attempt,
+      nextAttemptAtMs: currentTimeMs + delayMs
+    });
+  }
+}