@bugsession/react-native 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -4,7 +4,7 @@ Opt-in screen recording, microphone narration and bounded runtime telemetry for
 
 ## Compatibility
 
-The prepared beta targets React 19.3, React Native 0.88 and Expo SDK 58. Other versions have not been validated. iOS requires a native build on a physical iPhone, iOS 16.4+, and the optional `@bugsession/capture-native` package. Expo Go cannot record iOS video. Android currently needs a local recorder with an ADB-connected device; a VPS cannot capture Android screens. The recorder admits one session at a time.
+The SDK supports React 18.3.1–19.x and React Native 0.76–0.88. Expo SDK 54–58 are supported; SDK 52–53 are best effort. CI builds Android against SDK 52, 53, 54, 57 and 58. Each Expo SDK selects its matching React and React Native versions; do not mix versions manually. iOS and Android require a native build and `@bugsession/capture-native`; Expo Go cannot capture screen video. Android uses MediaProjection and asks for screen-capture consent every session. The hosted recorder admits one session at a time.
 
 ## Install
 
@@ -12,10 +12,10 @@ After publication:
 
 ```sh
 npm install @bugsession/react-native@beta @bugsession/capture-native@beta
-npx expo install expo-file-system expo-modules-core
+npx expo install expo-audio expo-file-system
 ```
 
-For local evaluation, install the generated `.tgz` files instead. Add `ios.infoPlist.NSMicrophoneUsageDescription` to your Expo app config and rebuild the native app. Explain recording to the tester and start only after their explicit action.
+For local evaluation, install the generated `.tgz` files instead. Configure microphone permission through your audio library and rebuild the native app. Explain recording to the tester and start only after their explicit action.
 
 ## iOS example
 
@@ -25,8 +25,8 @@ import { IOSCapture } from '@bugsession/capture-native';
 import * as FileSystem from 'expo-file-system/legacy';
 
 BugSession.configure({
-  recorderUrl: 'https://beta.bugsession.dev', // available after DNS + deployment
-  recorderToken: betaRecorderToken,
+  recorderUrl: 'https://beta.bugsession.dev',
+  recorderToken: projectIngestionKey, // Generate in dashboard → project → Connect your SDK.
   device: { platform: 'ios', model: 'tester-device' },
   application: { version: '1.0.0', gitCommit: appSourceCommit },
   capture: {
@@ -58,6 +58,16 @@ React Navigation integration: call the function returned by `BugSession.navigati
 
 `<BugSession.Trigger />` renders a floating logo button that starts and stops sessions. Its default position is `bottom-right`; configure `position` as `bottom-left`, `top-right`, or `top-left`, and adjust `offset` in points. Render it as an overlay above the app navigator. Pass `onError` to surface permission, recorder, and upload failures. Supply `children` to replace the default mark.
 
-Android requires an `audio` adapter implementing `prepare`, `start`, `stop` (returns a local URI), and `upload`; prepare must request microphone permission. `expo-audio` can provide this adapter. Point Android at the local recorder, not the hosted URL.
+Android uses `AndroidCapture` from `@bugsession/capture-native` plus an `audio` adapter implementing `prepare`, `start`, `stop` (returns a local URI), and `upload`. `prepare` must request microphone permission. `expo-audio` can provide this adapter. Android shows a system screen-capture prompt each session and a persistent capture notification; keep the app foregrounded through upload.
 
-Fetch instrumentation omits request/response bodies, headers, URL credentials and query strings. Free-text redaction is best effort. Video, audio, screen labels, URL paths and arbitrary logs can contain private information. Record only test data and stop before entering credentials. Native crashes and process termination can lose in-memory telemetry. A maximum of 5,000 events is retained. The shared beta token is extractable from an app build: use it only in invited builds, rotate it, and isolate each tester group into its own recorder and storage.
+Fetch instrumentation omits request/response bodies, headers, URL credentials and query strings. Free-text redaction is best effort. Video, audio, screen labels, URL paths and arbitrary logs can contain private information. Record only test data and stop before entering credentials. Native crashes and process termination can lose in-memory telemetry. A maximum of 5,000 events is retained. Project SDK keys are extractable from an app build, so share them only with invited testers. Each key scopes uploads to one project; it cannot read recordings. Revoke unused keys. Keep recorder operator and Clerk secrets server-side.
+
+## Project-scoped beta uploads
+
+Generate an SDK key from your dashboard project. Copy it into `recorderToken`; the backend derives project scope from the key. No SDK `projectId` option is needed. A project ID alone never authorizes uploads. Never distribute recorder operator or Clerk secret keys.
+
+Keys allow recording creation, media/telemetry submission and processing status only for their project. They cannot list or download recordings. Revoking a key rejects subsequent requests, including an unfinished upload sequence; an already accepted upload or processing job can finish. Replace the app configuration before revoking a key still used by testers.
+
+Hosted beta accepts native iOS ReplayKit and Android MediaProjection uploads. Limits are 3 active keys per project, 20 accepted recording starts per project per recorder hour, 600 requests per project per minute, 128 MiB per video, 32 MiB per audio upload, and 4 MiB telemetry bodies. The recorder still runs one recording or processing job at a time. Rate counters reset on restart. Mobile keys are extractable; treat them as limited ingestion capabilities, not account credentials.
+
+After stopping, open the same project in the dashboard and refresh its recordings list to see status. Status polling using an SDK key returns a warning count, not raw processing warnings; inspect the dashboard/operator tools for processing details.

package/dist/capture.d.ts

@@ -6,8 +6,11 @@ export type NativeRecording = {
     droppedAudioBuffers: number;
 };
 export type NativeCaptureAdapter = {
+    prepare?(): Promise<void>;
     clock(): Promise<number>;
-    start(): Promise<void>;
+    start(): Promise<void | {
+        firstVideoNativeMs: number;
+    }>;
     stop(): Promise<NativeRecording>;
     cancel(): Promise<void>;
     upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;

package/dist/index.js

@@ -99,27 +99,33 @@ exports.BugSession = {
         rawFetch = globalThis.fetch.bind(globalThis);
         let createdId = null;
         let audioStarted = false;
+        const isIOS = react_native_1.Platform.OS === 'ios';
+        const useNativeCapture = isIOS || (react_native_1.Platform.OS === 'android' && !!options.capture);
         try {
-            const isIOS = react_native_1.Platform.OS === 'ios';
+            if (react_native_1.Platform.OS === 'android' && options.capture?.prepare)
+                await options.capture.prepare();
             if (!isIOS)
                 await options.audio.prepare();
             const clock = new core_1.SessionClock();
-            const nativeClock = isIOS ? await calibrate(clock, () => options.capture.clock()) : null;
+            const nativeClock = useNativeCapture ? await calibrate(clock, () => options.capture.clock()) : null;
             const best = await calibrate(clock, async () => (await request('/clock')).monoMs);
             collector = new core_1.Collector(clock);
-            const result = await request('/sessions/start', { device: options.device, application: options.application, captureBackend: isIOS ? 'replaykit' : 'adb', startedAt: new Date(Date.now() - clock.now()).toISOString() });
+            const captureBackend = isIOS ? 'replaykit' : useNativeCapture ? 'mediaprojection' : 'adb';
+            const result = await request('/sessions/start', { device: options.device, application: options.application, captureBackend, startedAt: new Date(Date.now() - clock.now()).toISOString() });
             createdId = result.id;
-            let audioStartMs = clock.now();
-            if (isIOS)
-                await options.capture.start();
-            else {
+            const nativeStart = useNativeCapture ? await options.capture.start() : undefined;
+            const audioStartMs = clock.now();
+            if (!isIOS) {
                 options.audio.start();
                 audioStarted = true;
             }
+            const nativeVideoStartMs = nativeStart && 'firstVideoNativeMs' in nativeStart
+                ? nativeStart.firstVideoNativeMs + nativeClock.offset
+                : undefined;
             session = {
                 id: result.id, audioStartMs,
-                videoStartMs: isIOS ? 0 : Math.max(0, result.videoHostStartMs + best.offset),
-                uncertaintyMs: best.rtt / 2, captureBackend: isIOS ? 'replaykit' : 'adb',
+                videoStartMs: isIOS ? 0 : Math.max(0, nativeVideoStartMs ?? result.videoHostStartMs + best.offset),
+                uncertaintyMs: best.rtt / 2, captureBackend,
                 ...(nativeClock ? { nativeOffsetMs: nativeClock.offset, nativeUncertaintyMs: nativeClock.rtt / 2 } : {}),
             };
             restore = install(collector);
@@ -128,7 +134,7 @@ exports.BugSession = {
             return session.id;
         }
         catch (error) {
-            if (react_native_1.Platform.OS === 'ios')
+            if (useNativeCapture)
                 await options.capture?.cancel().catch(() => { });
             if (audioStarted)
                 await options.audio.stop().catch(() => null);
@@ -156,6 +162,20 @@ exports.BugSession = {
                 media = { ...active, ...(0, capture_1.alignNativeRecording)(recording, active.nativeOffsetMs, active.nativeUncertaintyMs) };
                 await options.capture.upload(`${options.recorderUrl}/sessions/${active.id}/video`, recording.uri, authHeaders());
             }
+            else if (active.captureBackend === 'mediaprojection') {
+                const recording = await options.capture.stop();
+                const uri = await options.audio.stop();
+                const audioEndMs = c.clock.now();
+                if (!uri)
+                    throw new Error('Microphone recording has no file');
+                await options.capture.upload(`${options.recorderUrl}/sessions/${active.id}/video`, recording.uri, authHeaders());
+                await options.audio.upload(`${options.recorderUrl}/sessions/${active.id}/audio`, uri, authHeaders());
+                media = {
+                    ...active, audioEndMs, alignment: 'mediaprojection-host-clock',
+                    videoAlignmentUncertaintyMs: Math.max(250, active.nativeUncertaintyMs ?? 0),
+                    microphoneAvailable: true, droppedVideoFrames: recording.droppedVideoFrames,
+                };
+            }
             else {
                 const uri = await options.audio.stop();
                 const audioEndMs = c.clock.now();
@@ -170,7 +190,7 @@ exports.BugSession = {
             });
         }
         catch (error) {
-            if (active.captureBackend === 'replaykit')
+            if (active.captureBackend !== 'adb')
                 await options.capture.cancel().catch(() => { });
             // Release the device recorder, but preserve partial files for recovery.
             await request(`/sessions/${active.id}/abort`, { reason: (0, core_1.safeText)(error), events: c.events, media: active, durationMs: c.clock.now() }).catch(() => { });

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@bugsession/react-native",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "peerDependencies": {
-    "react": ">=19.3.0 <20",
-    "react-native": ">=0.88.0 <0.89"
+    "react": ">=18.3.1 <20",
+    "react-native": ">=0.76.0 <0.89"
   },
   "description": "Opt-in React Native runtime evidence SDK",
   "license": "UNLICENSED",

package/src/capture.ts

@@ -6,8 +6,9 @@ export type NativeRecording = {
   droppedAudioBuffers: number;
 };
 export type NativeCaptureAdapter = {
+  prepare?(): Promise<void>;
   clock(): Promise<number>;
-  start(): Promise<void>;
+  start(): Promise<void | { firstVideoNativeMs: number }>;
   stop(): Promise<NativeRecording>;
   cancel(): Promise<void>;
   upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;

package/src/index.tsx

@@ -24,7 +24,7 @@ type ErrorUtilsType = { getGlobalHandler(): (e: Error, fatal?: boolean) => void;
 const globals = globalThis as typeof globalThis & { ErrorUtils?: ErrorUtilsType };
 let options: BugSessionOptions;
 let collector: Collector | null = null;
-let session: { id: string; videoStartMs: number; audioStartMs: number; uncertaintyMs: number; captureBackend: 'adb' | 'replaykit'; nativeOffsetMs?: number; nativeUncertaintyMs?: number } | null = null;
+let session: { id: string; videoStartMs: number; audioStartMs: number; uncertaintyMs: number; captureBackend: 'adb' | 'replaykit' | 'mediaprojection'; nativeOffsetMs?: number; nativeUncertaintyMs?: number } | null = null;
 let state: 'idle' | 'starting' | 'recording' | 'stopping' = 'idle';
 let restore: (() => void) | null = null;
 let currentScreen = 'Home';
@@ -93,22 +93,28 @@ export const BugSession = {
     rawFetch = globalThis.fetch.bind(globalThis);
     let createdId: string | null = null;
     let audioStarted = false;
+    const isIOS = Platform.OS === 'ios';
+    const useNativeCapture = isIOS || (Platform.OS === 'android' && !!options.capture);
     try {
-      const isIOS = Platform.OS === 'ios';
+      if (Platform.OS === 'android' && options.capture?.prepare) await options.capture.prepare();
       if (!isIOS) await options.audio!.prepare();
       const clock = new SessionClock();
-      const nativeClock = isIOS ? await calibrate(clock, () => options.capture!.clock()) : null;
+      const nativeClock = useNativeCapture ? await calibrate(clock, () => options.capture!.clock()) : null;
       const best = await calibrate(clock, async () => (await request('/clock')).monoMs);
       collector = new Collector(clock);
-      const result = await request('/sessions/start', { device: options.device, application: options.application, captureBackend: isIOS ? 'replaykit' : 'adb', startedAt: new Date(Date.now() - clock.now()).toISOString() });
+      const captureBackend = isIOS ? 'replaykit' : useNativeCapture ? 'mediaprojection' : 'adb';
+      const result = await request('/sessions/start', { device: options.device, application: options.application, captureBackend, startedAt: new Date(Date.now() - clock.now()).toISOString() });
       createdId = result.id;
-      let audioStartMs = clock.now();
-      if (isIOS) await options.capture!.start();
-      else { options.audio!.start(); audioStarted = true; }
+      const nativeStart = useNativeCapture ? await options.capture!.start() : undefined;
+      const audioStartMs = clock.now();
+      if (!isIOS) { options.audio!.start(); audioStarted = true; }
+      const nativeVideoStartMs = nativeStart && 'firstVideoNativeMs' in nativeStart
+        ? nativeStart.firstVideoNativeMs + nativeClock!.offset
+        : undefined;
       session = {
         id: result.id, audioStartMs,
-        videoStartMs: isIOS ? 0 : Math.max(0, result.videoHostStartMs + best.offset),
-        uncertaintyMs: best.rtt / 2, captureBackend: isIOS ? 'replaykit' : 'adb',
+        videoStartMs: isIOS ? 0 : Math.max(0, nativeVideoStartMs ?? result.videoHostStartMs + best.offset),
+        uncertaintyMs: best.rtt / 2, captureBackend,
         ...(nativeClock ? { nativeOffsetMs: nativeClock.offset, nativeUncertaintyMs: nativeClock.rtt / 2 } : {}),
       };
       restore = install(collector);
@@ -116,7 +122,7 @@ export const BugSession = {
       collector.add('navigation', { from: null, to: currentScreen });
       return session.id;
     } catch (error) {
-      if (Platform.OS === 'ios') await options.capture?.cancel().catch(() => {});
+      if (useNativeCapture) await options.capture?.cancel().catch(() => {});
       if (audioStarted) await options.audio!.stop().catch(() => null);
       if (createdId) await request(`/sessions/${createdId}/abort`, {}).catch(() => {});
       collector = null; session = null; state = 'idle'; throw error;
@@ -135,6 +141,18 @@ export const BugSession = {
         const recording = await options.capture!.stop();
         media = { ...active, ...alignNativeRecording(recording, active.nativeOffsetMs!, active.nativeUncertaintyMs!) };
         await options.capture!.upload(`${options.recorderUrl}/sessions/${active.id}/video`, recording.uri, authHeaders());
+      } else if (active.captureBackend === 'mediaprojection') {
+        const recording = await options.capture!.stop();
+        const uri = await options.audio!.stop();
+        const audioEndMs = c.clock.now();
+        if (!uri) throw new Error('Microphone recording has no file');
+        await options.capture!.upload(`${options.recorderUrl}/sessions/${active.id}/video`, recording.uri, authHeaders());
+        await options.audio!.upload(`${options.recorderUrl}/sessions/${active.id}/audio`, uri, authHeaders());
+        media = {
+          ...active, audioEndMs, alignment: 'mediaprojection-host-clock',
+          videoAlignmentUncertaintyMs: Math.max(250, active.nativeUncertaintyMs ?? 0),
+          microphoneAvailable: true, droppedVideoFrames: recording.droppedVideoFrames,
+        };
       } else {
         const uri = await options.audio!.stop();
         const audioEndMs = c.clock.now();
@@ -147,7 +165,7 @@ export const BugSession = {
         media,
       });
     } catch (error) {
-      if (active.captureBackend === 'replaykit') await options.capture!.cancel().catch(() => {});
+      if (active.captureBackend !== 'adb') await options.capture!.cancel().catch(() => {});
       // Release the device recorder, but preserve partial files for recovery.
       await request(`/sessions/${active.id}/abort`, { reason: safeText(error), events: c.events, media: active, durationMs: c.clock.now() }).catch(() => {});
       throw error;