@xorgate/react-native 0.1.0

package/dist/wake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake.d.ts","sourceRoot":"","sources":["../src/wake.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAK3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,GAAG,UAAU,CAOhE"}

package/dist/wake.js

@@ -0,0 +1,38 @@
+import { AppState } from "react-native";
+/**
+ * The foreground edge. This is the wake source a phone actually needs: iOS
+ * suspends the app's sockets within seconds of it leaving the screen, so both
+ * the MQTT connection and the peer connection are usually dead by the time the
+ * user comes back — and the live plane would otherwise sit out a backoff of up
+ * to 30 s in front of them. A browser tab has the same problem in miniature;
+ * `visibilitychange` is the web's version of this listener.
+ *
+ * Only the `active` edge counts. "inactive" is the app switcher or a system
+ * sheet over the app, where nothing has been torn down yet.
+ */
+export function appStateWake(onWake) {
+    const subscription = AppState.addEventListener("change", (state) => {
+        if (state === "active")
+            onWake();
+    });
+    return () => subscription.remove();
+}
+/**
+ * Fan one `onWake` out over several sources. Used to add "the network came
+ * back" to the foreground edge; see the README for the expo-network and
+ * NetInfo recipes, which are four lines each and stay in the consumer so this
+ * package needs neither as a dependency.
+ *
+ * A wake is a hint, never a command: the feeds and the video session ignore
+ * one while they are connected or mid-connect, so firing twice costs nothing.
+ */
+export function composeWake(...sources) {
+    return (onWake) => {
+        const unsubscribes = sources.map((source) => source(onWake));
+        return () => {
+            for (const unsubscribe of unsubscribes)
+                unsubscribe();
+        };
+    };
+}
+//# sourceMappingURL=wake.js.map

package/dist/wake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake.js","sourceRoot":"","sources":["../src/wake.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKxC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,MAAkB;IAC7C,MAAM,YAAY,GAAG,QAAQ,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE;QACjE,IAAI,KAAK,KAAK,QAAQ;YAAE,MAAM,EAAE,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,OAAqB;IAClD,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7D,OAAO,GAAG,EAAE;YACV,KAAK,MAAM,WAAW,IAAI,YAAY;gBAAE,WAAW,EAAE,CAAC;QACxD,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/webcrypto.d.ts

@@ -0,0 +1,45 @@
+type Bytes = ArrayBuffer | ArrayBufferView;
+export interface HmacKey {
+    type: "secret";
+    algorithm: {
+        name: "HMAC";
+        hash: {
+            name: "SHA-256";
+        };
+    };
+    extractable: boolean;
+    usages: string[];
+    raw: Uint8Array;
+}
+export declare const subtle: {
+    digest(algorithm: {
+        name: string;
+    } | string, data: Bytes): Promise<ArrayBuffer>;
+    importKey(format: string, keyData: Bytes, algorithm: {
+        name: string;
+        hash?: {
+            name: string;
+        } | string;
+    }, extractable: boolean, usages: string[]): Promise<HmacKey>;
+    sign(_algorithm: {
+        name: string;
+    }, key: HmacKey, data: Bytes): Promise<ArrayBuffer>;
+};
+declare const webcrypto: {
+    subtle: {
+        digest(algorithm: {
+            name: string;
+        } | string, data: Bytes): Promise<ArrayBuffer>;
+        importKey(format: string, keyData: Bytes, algorithm: {
+            name: string;
+            hash?: {
+                name: string;
+            } | string;
+        }, extractable: boolean, usages: string[]): Promise<HmacKey>;
+        sign(_algorithm: {
+            name: string;
+        }, key: HmacKey, data: Bytes): Promise<ArrayBuffer>;
+    };
+};
+export default webcrypto;
+//# sourceMappingURL=webcrypto.d.ts.map

package/dist/webcrypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webcrypto.d.ts","sourceRoot":"","sources":["../src/webcrypto.ts"],"names":[],"mappings":"AAuBA,KAAK,KAAK,GAAG,WAAW,GAAG,eAAe,CAAC;AAc3C,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAE,IAAI,EAAE,SAAS,CAAA;SAAE,CAAA;KAAE,CAAC;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,EAAE,UAAU,CAAC;CACjB;AAED,eAAO,MAAM,MAAM;sBACO;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,QAAQ,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC;sBAW3E,MAAM,WACL,KAAK,aACH;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG,MAAM,CAAA;KAAE,eAChD,OAAO,UACZ,MAAM,EAAE,GACf,OAAO,CAAC,OAAO,CAAC;qBAgBI;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,OAAO,OAAO,QAAQ,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC;CAK1F,CAAC;AAEF,QAAA,MAAM,SAAS;;0BAvCW;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG,MAAM,QAAQ,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC;0BAW3E,MAAM,WACL,KAAK,aACH;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAA;aAAE,GAAG,MAAM,CAAA;SAAE,eAChD,OAAO,UACZ,MAAM,EAAE,GACf,OAAO,CAAC,OAAO,CAAC;yBAgBI;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,OAAO,OAAO,QAAQ,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC;;CAO/D,CAAC;AAC7B,eAAe,SAAS,CAAC"}

package/dist/webcrypto.js

@@ -0,0 +1,62 @@
+/**
+ * `@xorgate/react-native/webcrypto` — the WebCrypto subset the KVS signaling
+ * client's SigV4 signer needs, for Metro to alias `isomorphic-webcrypto` at.
+ * See README "Metro setup"; it is one line of config and is not imported by
+ * anything in this package.
+ *
+ * Why an alias is needed at all: `amazon-kinesis-video-streams-webrtc` signs
+ * its WebSocket URL through `isomorphic-webcrypto`, whose React Native build
+ * evaluates to `undefined` on Hermes — its export is assembled behind an
+ * msrcrypto PRNG promise, and it also wants `expo-random`, removed from the
+ * Expo SDK after 51. The symptom is "Cannot read property 'subtle' of
+ * undefined" the first time a viewer connects.
+ *
+ * Why this is a complete answer rather than a stopgap: the signer makes
+ * exactly three calls — `digest(SHA-256)`, `importKey("raw", HMAC)` and
+ * `sign(HMAC)` — and all three are deterministic hashing over
+ * `@aws-crypto/sha256-js`, which is already in the tree because
+ * `presignIotWssUrl` signs with it. The entropy msrcrypto was providing is
+ * not used on this path. Anything outside those three calls throws by name
+ * instead of returning a wrong answer quietly.
+ */
+import { Sha256 } from "@aws-crypto/sha256-js";
+function toU8(data) {
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+export const subtle = {
+    async digest(algorithm, data) {
+        const name = typeof algorithm === "string" ? algorithm : algorithm.name;
+        if (name.toUpperCase() !== "SHA-256") {
+            throw new Error(`@xorgate/react-native/webcrypto: unsupported digest ${name}`);
+        }
+        const hash = new Sha256();
+        hash.update(toU8(data));
+        return toArrayBuffer(await hash.digest());
+    },
+    async importKey(format, keyData, algorithm, extractable, usages) {
+        if (format !== "raw" || algorithm.name.toUpperCase() !== "HMAC") {
+            throw new Error(`@xorgate/react-native/webcrypto: unsupported importKey ${format}/${algorithm.name}`);
+        }
+        return {
+            type: "secret",
+            algorithm: { name: "HMAC", hash: { name: "SHA-256" } },
+            extractable,
+            usages,
+            // Copied: the caller may reuse its buffer for the next signing step.
+            raw: toU8(keyData).slice(),
+        };
+    },
+    async sign(_algorithm, key, data) {
+        const hash = new Sha256(key.raw);
+        hash.update(toU8(data));
+        return toArrayBuffer(await hash.digest());
+    },
+};
+const webcrypto = { subtle };
+export default webcrypto;
+//# sourceMappingURL=webcrypto.js.map

package/dist/webcrypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webcrypto.js","sourceRoot":"","sources":["../src/webcrypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAI/C,SAAS,IAAI,CAAC,IAAW;IACvB,IAAI,IAAI,YAAY,WAAW;QAAE,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAC7D,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,aAAa,CAAC,KAAiB;IACtC,OAAO,KAAK,CAAC,MAAM,CAAC,KAAK,CACvB,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CACrB,CAAC;AACnB,CAAC;AAUD,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,CAAC,MAAM,CAAC,SAAoC,EAAE,IAAW;QAC5D,MAAM,IAAI,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;QACxE,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,uDAAuD,IAAI,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACxB,OAAO,aAAa,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,SAAS,CACb,MAAc,EACd,OAAc,EACd,SAA6D,EAC7D,WAAoB,EACpB,MAAgB;QAEhB,IAAI,MAAM,KAAK,KAAK,IAAI,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CACb,0DAA0D,MAAM,IAAI,SAAS,CAAC,IAAI,EAAE,CACrF,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;YACtD,WAAW;YACX,MAAM;YACN,qEAAqE;YACrE,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE;SAC3B,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAA4B,EAAE,GAAY,EAAE,IAAW;QAChE,MAAM,IAAI,GAAG,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACxB,OAAO,aAAa,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;CACF,CAAC;AAEF,MAAM,SAAS,GAAG,EAAE,MAAM,EAAE,CAAC;AAC7B,eAAe,SAAS,CAAC"}

package/dist/webrtc-platform.d.ts

@@ -0,0 +1,21 @@
+import type { WebRtcPlatform } from "@xorgate/react";
+/**
+ * The KVS viewer's platform on React Native.
+ *
+ * Only two of the five members differ from the browser: the peer connection
+ * (react-native-webrtc's, which is a real native PeerConnection with hardware
+ * H.264 decode behind it) and the id entropy (Hermes has no `crypto` global).
+ * The three AWS bodies — `getViewerEndpoints`, `getIceServers` and the lazy
+ * `createSignaling` facade — are `@xorgate/react`'s own: the AWS SDK v3
+ * clients and `amazon-kinesis-video-streams-webrtc` both run on Hermes once
+ * Metro resolves them (see README "Metro setup"), so copying them here would
+ * only mean two implementations of the hardened signaling path. The one
+ * addition is the missing-`crypto` guard below, in front of the first of
+ * them.
+ *
+ * `iceTransportPolicy: "all"` matters on a phone: a viewer on a carrier NAT
+ * frequently has no working host or srflx path to the device and lands on the
+ * TURN relay AWS hands out with the ICE server list.
+ */
+export declare function createNativeWebRtcPlatform(randomId: () => string): WebRtcPlatform;
+//# sourceMappingURL=webrtc-platform.d.ts.map

package/dist/webrtc-platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webrtc-platform.d.ts","sourceRoot":"","sources":["../src/webrtc-platform.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAsB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGzE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,MAAM,GAAG,cAAc,CAiBjF"}

package/dist/webrtc-platform.js

@@ -0,0 +1,61 @@
+import { createWebRtcPlatform } from "@xorgate/react";
+import { RTCPeerConnection } from "react-native-webrtc";
+/**
+ * The KVS viewer's platform on React Native.
+ *
+ * Only two of the five members differ from the browser: the peer connection
+ * (react-native-webrtc's, which is a real native PeerConnection with hardware
+ * H.264 decode behind it) and the id entropy (Hermes has no `crypto` global).
+ * The three AWS bodies — `getViewerEndpoints`, `getIceServers` and the lazy
+ * `createSignaling` facade — are `@xorgate/react`'s own: the AWS SDK v3
+ * clients and `amazon-kinesis-video-streams-webrtc` both run on Hermes once
+ * Metro resolves them (see README "Metro setup"), so copying them here would
+ * only mean two implementations of the hardened signaling path. The one
+ * addition is the missing-`crypto` guard below, in front of the first of
+ * them.
+ *
+ * `iceTransportPolicy: "all"` matters on a phone: a viewer on a carrier NAT
+ * frequently has no working host or srflx path to the device and lands on the
+ * TURN relay AWS hands out with the ICE server list.
+ */
+export function createNativeWebRtcPlatform(randomId) {
+    const platform = createWebRtcPlatform({
+        randomId,
+        createPeerConnection: (iceServers) => new RTCPeerConnection({
+            iceServers: iceServers,
+            iceTransportPolicy: "all",
+        }),
+    });
+    return {
+        ...platform,
+        async getViewerEndpoints(channelRef, region, credentials) {
+            assertCryptoGlobal();
+            return platform.getViewerEndpoints(channelRef, region, credentials);
+        },
+    };
+}
+/**
+ * The AWS SDK needs a `crypto` global, and Hermes has none.
+ *
+ * `@smithy/core`'s React Native serde bundle ends its UUID v4 path in
+ * `const _getRandomValues = (array) => crypto.getRandomValues(array)` — a BARE
+ * `crypto` — and that is the fallback `bindV4` selects precisely when
+ * `typeof crypto === "undefined"`, so the guard hands control to the one line
+ * that cannot survive the case it guards against. Without the polyfill the
+ * first signaling call throws `Property 'crypto' doesn't exist`, which the
+ * viewer session reads as a network failure and retries forever.
+ *
+ * Checked here, at the first AWS call, rather than at platform construction:
+ * throwing while the provider mounts would take the whole app down over a
+ * feature the user may not have opened. This way the message lands in the
+ * session's `error` and says what to do.
+ */
+function assertCryptoGlobal() {
+    const c = globalThis.crypto;
+    if (c && typeof c.getRandomValues === "function")
+        return;
+    throw new Error("Live video needs a `crypto` global, which React Native does not have: the AWS SDK " +
+        'calls crypto.getRandomValues(). Add `import "@xorgate/react-native/polyfills"` to the ' +
+        "top of your entry file. (Live telemetry does not need it.)");
+}
+//# sourceMappingURL=webrtc-platform.js.map

package/dist/webrtc-platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webrtc-platform.js","sourceRoot":"","sources":["../src/webrtc-platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAsB;IAC/D,MAAM,QAAQ,GAAG,oBAAoB,CAAC;QACpC,QAAQ;QACR,oBAAoB,EAAE,CAAC,UAAU,EAAsB,EAAE,CACvD,IAAI,iBAAiB,CAAC;YACpB,UAAU,EAAE,UAAmB;YAC/B,kBAAkB,EAAE,KAAK;SAC1B,CAAkC;KACtC,CAAC,CAAC;IAEH,OAAO;QACL,GAAG,QAAQ;QACX,KAAK,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW;YACtD,kBAAkB,EAAE,CAAC;YACrB,OAAO,QAAQ,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;QACtE,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,kBAAkB;IACzB,MAAM,CAAC,GAAI,UAAyD,CAAC,MAAM,CAAC;IAC5E,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,eAAe,KAAK,UAAU;QAAE,OAAO;IACzD,MAAM,IAAI,KAAK,CACb,oFAAoF;QAClF,wFAAwF;QACxF,4DAA4D,CAC/D,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@xorgate/react-native",
+  "version": "0.1.0",
+  "description": "React Native adapters for @xorgate/react: live telemetry over MQTT, live video over WebRTC (react-native-webrtc / RTCView), and the recorded-media replay player over expo-video.",
+  "license": "MIT",
+  "author": "Epye Labs",
+  "homepage": "https://docs.xorgate.io/docs/frontend-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/epyelabs/xorgate-react-native.git"
+  },
+  "bugs": {
+    "url": "https://github.com/epyelabs/xorgate-react-native/issues"
+  },
+  "keywords": [
+    "xorgate",
+    "react-native",
+    "expo",
+    "hooks",
+    "iot",
+    "telemetry",
+    "webrtc",
+    "video",
+    "replay"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": [
+    "./dist/polyfills.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./polyfills": {
+      "types": "./dist/polyfills.d.ts",
+      "import": "./dist/polyfills.js",
+      "default": "./dist/polyfills.js"
+    },
+    "./package.json": "./package.json",
+    "./webcrypto": {
+      "types": "./dist/webcrypto.d.ts",
+      "import": "./dist/webcrypto.js",
+      "default": "./dist/webcrypto.js"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "ci": "npm run typecheck && npm test && npm run build && npm run verify:tarball",
+    "clean": "rm -rf dist .tmp",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify:tarball": "node scripts/verify-tarball.mjs"
+  },
+  "peerDependencies": {
+    "expo-crypto": ">=13.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-native": ">=0.76.0",
+    "react-native-webrtc": ">=124.0.0"
+  },
+  "dependencies": {
+    "@aws-crypto/sha256-js": "^5.2.0",
+    "@xorgate/react": "^0.2.0-next.1"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.3.0",
+    "expo-crypto": "~57.0.3",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.3.0",
+    "react-native": "^0.86.3",
+    "react-native-webrtc": "^124.0.8",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,312 @@
+# @xorgate/react-native
+
+React Native adapters for [`@xorgate/react`](https://www.npmjs.com/package/@xorgate/react).
+Live telemetry over MQTT-over-WebSocket and live video over WebRTC, rendered by
+`react-native-webrtc`'s `RTCView` — a real native video view with hardware
+H.264 decode behind it, not a web player in a shell.
+
+Everything pure or platform-neutral — the KVS session hardening, the telemetry
+feed, the timeline, lanes, the replay clock, the telemetry math, the data hooks
+— lives in `@xorgate/react` and is **re-exported from here**, so your app
+imports from one package. What this package adds is the runtime underneath
+(`nativePlatform`, `XorgateNativeProvider`) and the two things that cannot be
+platform-neutral because they are pixels.
+
+**0.1.0 ships telemetry and live video.** Replay over `expo-video` is 0.2.0.
+
+**Full reference: [docs.xorgate.io/docs/frontend-sdk](https://docs.xorgate.io/docs/frontend-sdk)**
+
+## Install
+
+```bash
+npx expo install @xorgate/react-native react-native-webrtc @config-plugins/react-native-webrtc expo-crypto
+```
+
+Peers: `react`, `react-native`, `react-native-webrtc`, `expo-crypto`.
+`@xorgate/react` is a dependency, not a peer — one resolved copy is what makes
+`instanceof XorgateError` hold across the boundary.
+
+`expo-crypto` is required, not optional: Hermes ships **no `crypto` global at
+all** — not `randomUUID`, not `getRandomValues`, not `subtle` — and every MQTT
+and signaling client id needs entropy, so there is nothing else to default to.
+
+Add the config plugin to `app.json` / `app.config.ts`:
+
+```json
+{ "plugins": ["@config-plugins/react-native-webrtc"] }
+```
+
+**A development build is required.** `react-native-webrtc` is a native module,
+so Expo Go cannot run it.
+
+The plugin writes both an `NSCameraUsageDescription` and an
+`NSMicrophoneUsageDescription`, and on Android adds `CAMERA`, `RECORD_AUDIO`,
+`MODIFY_AUDIO_SETTINGS` and Bluetooth permissions. A **viewer** app uses none
+of them, but Apple's upload check (ITMS-90683) still wants a microphone string
+from any binary that links the microphone APIs, which WebRTC does. Set an
+honest one rather than shipping the plugin's placeholder, and strip the Android
+permissions you do not use:
+
+```ts
+plugins: [["@config-plugins/react-native-webrtc", {
+  cameraPermission: "…",
+  microphonePermission: "This app views live video only and does not record audio.",
+}]],
+android: { blockedPermissions: ["android.permission.RECORD_AUDIO", "android.permission.MODIFY_AUDIO_SETTINGS"] },
+```
+
+## Metro setup
+
+`@xorgate/react`'s AWS / KVS / mqtt tree bundles under Metro with four
+resolver rules. They are mechanical and package-agnostic — they read each
+package's own `package.json` — so paste this into `metro.config.js` once:
+
+```js
+const fs = require("node:fs")
+const path = require("node:path")
+const { getDefaultConfig } = require("expo/metro-config")
+
+const config = getDefaultConfig(__dirname)
+
+const AWS_SCOPES = ["@aws-sdk/", "@smithy/"]
+const esEntry = new Map()
+
+/**
+ * (1) `@aws-sdk/*` and `@smithy/*` packages that ship NO `exports` map fall
+ * through to `main` = `dist-cjs`, which requires `node:https` / `node:stream`.
+ * Their `react-native` and `browser` fields are sub-path maps, not entry
+ * points, so Metro cannot use them: redirect the bare request to the `module`
+ * entry (`dist-es`). Packages that DO have `exports` (`@smithy/core`,
+ * `@aws-sdk/core`, `@aws-sdk/nested-clients`) resolve correctly and must be
+ * left alone — `@smithy/core` actively refuses `./dist-es/index.js`.
+ */
+function awsEsEntry(name) {
+  if (!AWS_SCOPES.some((s) => name.startsWith(s))) return null
+  if (name.split("/").length !== 2) return null // sub-path imports are fine
+  if (esEntry.has(name)) return esEntry.get(name)
+  let result = null
+  try {
+    const dir = path.dirname(require.resolve(`${name}/package.json`, { paths: [__dirname] }))
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"))
+    if (!pkg.exports && typeof pkg.module === "string") result = path.join(dir, pkg.module)
+  } catch {
+    result = null
+  }
+  esEntry.set(name, result)
+  return result
+}
+
+const previous = config.resolver.resolveRequest
+
+config.resolver.resolveRequest = (context, moduleName, platform) => {
+  const es = awsEsEntry(moduleName)
+  if (es) return { type: "sourceFile", filePath: es }
+
+  // (2) `./runtimeConfig` from inside a `dist-es` directory -> the
+  // `runtimeConfig.native.js` sibling, which is what the package's
+  // `react-native` sub-path map would have chosen. Without it the AWS clients
+  // come up with the Node runtime config instead of `FetchHttpHandler`.
+  if (moduleName === "./runtimeConfig" && context.originModulePath.includes(`${path.sep}dist-es${path.sep}`)) {
+    const native = path.join(path.dirname(context.originModulePath), "runtimeConfig.native.js")
+    if (fs.existsSync(native)) return { type: "sourceFile", filePath: native }
+  }
+
+  // (3) The KVS signaling client does `new (WebSocket || require("ws"))(url)`.
+  // React Native has a global `WebSocket`, so the Node implementation only has
+  // to RESOLVE; it never runs.
+  if (moduleName === "ws") {
+    return { type: "sourceFile", filePath: require.resolve("ws/browser.js", { paths: [__dirname] }) }
+  }
+
+  // (4) `isomorphic-webcrypto` -> this package's WebCrypto subset. The real
+  // package's React Native build evaluates to `undefined` on Hermes (its
+  // export is assembled behind an msrcrypto PRNG promise, and it wants
+  // `expo-random`, gone from the Expo SDK after 51), so the KVS signaling
+  // client dies with "Cannot read property 'subtle' of undefined" the first
+  // time a viewer connects.
+  if (moduleName === "isomorphic-webcrypto") {
+    return {
+      type: "sourceFile",
+      filePath: require.resolve("@xorgate/react-native/webcrypto", { paths: [__dirname] }),
+    }
+  }
+
+  return (previous ?? context.resolveRequest)(context, moduleName, platform)
+}
+
+module.exports = config
+```
+
+`@xorgate/react-native/webcrypto` covers exactly the three calls the SigV4
+signer makes — `digest(SHA-256)`, `importKey("raw", HMAC)`, `sign(HMAC)` —
+over `@aws-crypto/sha256-js`, which is already in the tree. All three are
+deterministic hashing, so the entropy msrcrypto was adding is not used on this
+path; anything outside those three throws by name rather than answering wrong.
+
+Nothing else was needed on Expo SDK 57 / Hermes: no `buffer`, `process`,
+`events`, `url`, stream or URL polyfill, measured rather than assumed.
+
+A global `resolverMainFields: ["module", …]` is **not** a shortcut for rule 1:
+it breaks `react-native-safe-area-context`'s codegen spec.
+
+## Polyfill
+
+Add one line at the very top of your entry file, before anything that reaches
+the SDK:
+
+```ts
+import "@xorgate/react-native/polyfills"
+```
+
+It installs `getRandomValues` and `randomUUID` from `expo-crypto` onto
+`globalThis.crypto`, additively (an existing `crypto` keeps everything it
+already has).
+
+**Live video does not work without it.** Not because of this package —
+`nativePlatform()` covers the SDK's own entropy through the `randomId` slot,
+and live telemetry runs with no polyfill at all — but because of the AWS SDK
+underneath the KVS viewer. `@smithy/core`'s React Native serde bundle ends its
+UUID v4 path in
+
+```js
+const _getRandomValues = (array) => crypto.getRandomValues(array)
+```
+
+with a **bare** `crypto`, and that is the fallback `bindV4` selects precisely
+when `typeof crypto === "undefined"` — so the guard hands control to the one
+line that cannot survive the case it guards against. On Hermes the first
+`GetSignalingChannelEndpoint` call then throws `Property 'crypto' doesn't
+exist`, the session treats it as a network error, and the viewer retries
+forever on a backoff. (Measured on Expo SDK 57 / Hermes, `@smithy/core` 3.34.1,
+2026-09-15. The same bug was fixed for the Node build in
+smithy-typescript#2022; the browser and React Native builds were not changed —
+smithy-typescript#2276.)
+
+## Use
+
+```tsx
+import { XorgateNativeProvider } from "@xorgate/react-native"
+
+<XorgateNativeProvider
+  key={organizationId ?? "none"}          // remounting is how you switch tenants
+  auth={{ getLiveCredentials }}
+  organizationId={organizationId}
+>
+  {children}
+</XorgateNativeProvider>
+```
+
+Same props as `@xorgate/react`'s `XorgateProvider`, plus the native slots
+(`randomId`, `wake`, `mqttConnect`, and a `platform` escape hatch).
+
+### Live telemetry
+
+Unchanged from the web package — `mqtt.js` 5 runs on React Native's global
+`WebSocket` as it is:
+
+```tsx
+const { latest, history, status, receivedAt } = useLiveTelemetry(deviceId)
+```
+
+Read freshness off `receivedAt`, not `status`. A phone that loses signal keeps
+a socket that reads `connected` until the OS surfaces the close, which can take
+20 s or more; the age of the last frame is the honest signal, and the web app
+treats it the same way.
+
+### Live video
+
+```tsx
+import { LiveVideo, useVideoChannels } from "@xorgate/react-native"
+
+const { data } = useVideoChannels(deviceId)
+const cam0 = data?.find((c) => c.streamKey === "cam0") ?? null
+
+<LiveVideo channel={cam0} style={{ aspectRatio: 16 / 9 }} />
+```
+
+`useVideoChannels` is a REST read, so it needs an auth mode that HAS a REST
+credential. An app on `auth={{ getLiveCredentials }}` — the vended-direct mode,
+where your own backend mints the credential and your users have no xorgate
+identity — gets `INVALID_CONFIG` from it by design, and should fetch the
+channel list from its own API and hand the `VideoChannel` to `LiveVideo`
+directly. The live and replay planes are the parts that mode reaches.
+
+`LiveVideo` is the view and nothing else: no card, no spinner, no status text,
+no aspect ratio of its own. Take `onStatusChange`, `onStats`,
+`onVideoDimensions` and `onDisplayedStreamChange` for chrome of your own, or
+drop to the hook:
+
+```tsx
+const { streamURL, status, stats, error } = useLiveVideo(cam0)
+```
+
+One behaviour `LiveVideo` adds over a bare `RTCView`: **the reconnect hold**.
+Every reconnect produces a new `MediaStream` with a new `streamURL`, and an
+`RTCView` pointed at a stream that has not decoded a frame is black — so a
+short blip would blank the picture, where a browser's `<video>` simply keeps
+its last frame. `LiveVideo` mounts the new stream underneath at zero opacity
+and promotes it only once the renderer reports its dimensions, falling back to
+the swap after 3 s so a dead stream cannot pin a stale frame. Render `RTCView`
+yourself and you own that.
+
+### Waking the live plane
+
+The foreground edge (`AppState` → `active`) is wired for you, and on a phone it
+matters more than anything else in this package: iOS suspends the app's sockets
+within seconds of it leaving the screen, so both the MQTT connection and the
+peer connection are usually dead when the user comes back. Without the nudge
+the live plane sits out a backoff of up to 30 s in front of them.
+
+Add "the network came back" — four lines, and it stays in your app so this
+package depends on neither network library:
+
+```ts
+import * as Network from "expo-network"
+
+const networkWake = (onWake: () => void) => {
+  const sub = Network.addNetworkStateListener((s) => {
+    if (s.isInternetReachable ?? s.isConnected) onWake()
+  })
+  return () => sub.remove()
+}
+
+<XorgateNativeProvider wake={[networkWake]} …>
+```
+
+With `@react-native-community/netinfo`:
+
+```ts
+const networkWake = (onWake: () => void) =>
+  NetInfo.addEventListener((s) => { if (s.isConnected) onWake() })
+```
+
+A wake is a hint, never a command: a feed that is connected or mid-connect
+ignores one, so firing twice costs nothing.
+
+## What is not here
+
+`@xorgate/react`'s browser-only exports — its `useLiveVideo`, `LiveVideo`,
+`useReplayPlayer`, `ReplayVideo` and the `browser*` platform helpers — are
+deliberately not re-exported: they need `HTMLVideoElement`, `window` or Media
+Source Extensions. `useReplayPlayerCore`, the timeline, the lanes and the clock
+**are** re-exported; the `expo-video` engine that binds them to a player
+arrives in 0.2.0.
+
+## Scripts
+
+`npm run ci` = `typecheck` → `test` → `build` → `verify:tarball` (pack, install
+into an empty project, import it as a consumer with stub peers, check the
+export surface, scan for secret material).
+
+The suite runs under jsdom against doubles for `react-native` and
+`react-native-webrtc`, because neither has a Node build. It proves the wiring —
+which listener is attached, which prop the view gets, what happens across a
+reconnect — and nothing about pixels or hardware decode, which are measured by
+hand on a simulator and a phone.
+
+Publishing is manual (`npm publish --tag next` for pre-releases, `npm publish`
+for a final); CI has no publish job on purpose.
+
+## License
+
+MIT © Epye Labs