@bugsession/react-native 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,4 @@
+Proprietary Software
+
+All rights reserved. No license is granted for redistribution or modification.
+Contact the package owner for beta evaluation terms.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @bugsession/react-native — beta
 
-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.
+Opt-in screen recording, microphone narration and bounded runtime telemetry for React Native. This beta is for invited testers using non-sensitive test data. It is not ready for general production use. This SDK is proprietary (`UNLICENSED`), with all rights reserved. Beta use requires authorization from the package owner; see LICENSE.
+
+## 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.
+
+## Install
+
+After publication:
+
+```sh
+npm install @bugsession/react-native@beta @bugsession/capture-native@beta
+npx expo install expo-file-system expo-modules-core
+```
+
+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.
+
+## iOS example
+
+```tsx
+import { BugSession } from '@bugsession/react-native';
+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,
+  device: { platform: 'ios', model: 'tester-device' },
+  application: { version: '1.0.0', gitCommit: appSourceCommit },
+  capture: {
+    ...IOSCapture,
+    async upload(url, uri, headers = {}) {
+      const response = await FileSystem.uploadAsync(url, uri, {
+        httpMethod: 'POST',
+        uploadType: FileSystem.FileSystemUploadType.BINARY_CONTENT,
+        headers,
+      });
+      if (response.status !== 200) throw new Error(`Upload failed: ${response.status}`);
+    },
+  },
+});
+
+// Or render <BugSession.Trigger /> for a floating bottom-right record button.
+// Set position to bottom-left, top-right, or top-left; offset defaults to 24.
+// Render it above your navigator, and provide onError to display failures.
+// Stop within 160 seconds.
+await BugSession.start();
+BugSession.trackAction({ name: 'save-profile', screen: 'Profile' });
+BugSession.trackNavigation('Settings');
+const { id } = await BugSession.stop();
+```
+
+Configure once while idle. Wire an automatic stop timer into your recording UI, keep the app foregrounded through upload, and display recording/upload failures. `BugSession.stop()` acknowledges queued processing; it does not promise completed analysis. Poll authenticated `GET /sessions/{id}/status` until `status` is `complete`, `processing-failed`, or `interrupted`, and inspect `processing.warnings`. `complete` with partial processing can mean missing narration.
+
+React Navigation integration: call the function returned by `BugSession.navigationListener(navigationRef)` from both `NavigationContainer.onReady` and `onStateChange`. Expo Router apps can call `trackNavigation` when the committed pathname changes. Use `BugSession.Touchable` to instrument a Pressable, or `trackAction` directly. Send caught errors through `BugSession.captureError(error)`.
+
+`<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.
+
+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.

package/dist/capture.d.ts

@@ -0,0 +1,23 @@
+export type NativeRecording = {
+    uri: string;
+    firstVideoNativeMs: number;
+    firstAudioNativeMs: number | null;
+    droppedVideoFrames: number;
+    droppedAudioBuffers: number;
+};
+export type NativeCaptureAdapter = {
+    clock(): Promise<number>;
+    start(): Promise<void>;
+    stop(): Promise<NativeRecording>;
+    cancel(): Promise<void>;
+    upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;
+};
+export declare function alignNativeRecording(recording: NativeRecording, offsetMs: number, uncertaintyMs: number): {
+    videoStartMs: number;
+    audioStartMs: number;
+    alignment: string;
+    videoAlignmentUncertaintyMs: number;
+    microphoneAvailable: boolean;
+    droppedVideoFrames: number;
+    droppedAudioBuffers: number;
+};

package/dist/capture.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.alignNativeRecording = alignNativeRecording;
+function alignNativeRecording(recording, offsetMs, uncertaintyMs) {
+    const videoStartMs = recording.firstVideoNativeMs + offsetMs;
+    const audioStartMs = recording.firstAudioNativeMs === null ? videoStartMs : recording.firstAudioNativeMs + offsetMs;
+    if (![videoStartMs, audioStartMs, uncertaintyMs].every(Number.isFinite) || videoStartMs < 0 || audioStartMs < videoStartMs || uncertaintyMs < 0) {
+        throw new Error('Invalid ReplayKit clock mapping');
+    }
+    return {
+        videoStartMs, audioStartMs, alignment: 'replaykit-host-clock',
+        videoAlignmentUncertaintyMs: uncertaintyMs,
+        microphoneAvailable: recording.firstAudioNativeMs !== null,
+        droppedVideoFrames: recording.droppedVideoFrames,
+        droppedAudioBuffers: recording.droppedAudioBuffers,
+    };
+}

package/dist/core.d.ts

@@ -0,0 +1,22 @@
+export type Evidence = {
+    timestampMs: number;
+    type: string;
+    [key: string]: unknown;
+};
+export declare function safeUrl(input: string): string;
+export declare function safeText(value: unknown): string;
+export declare class SessionClock {
+    private source;
+    private epoch;
+    constructor(source?: () => number);
+    now(): number;
+}
+export declare class Collector {
+    clock: SessionClock;
+    private limit;
+    events: Evidence[];
+    dropped: number;
+    constructor(clock?: SessionClock, limit?: number);
+    add(type: string, data: Record<string, unknown>): void;
+}
+export declare function instrumentFetch(original: typeof fetch, collector: Collector): typeof fetch;

package/dist/core.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Collector = exports.SessionClock = void 0;
+exports.safeUrl = safeUrl;
+exports.safeText = safeText;
+exports.instrumentFetch = instrumentFetch;
+function safeUrl(input) {
+    try {
+        const u = new URL(input, 'http://relative.invalid');
+        // Paths can contain credentials too; redact common key/value path segments.
+        const path = u.pathname.replace(/\/(token|password|secret|api[-_]?key)\/[^/]+/gi, '/$1/[redacted]');
+        return (u.hostname === 'relative.invalid' ? '' : `${u.protocol}//${u.host}`) + path;
+    }
+    catch {
+        return '[invalid URL]';
+    }
+}
+function safeText(value) {
+    const text = value instanceof Error ? value.message : typeof value === 'string' ? value : '[non-string value omitted]';
+    return text
+        .replace(/https?:\/\/[^\s)"']+/g, (url) => safeUrl(url))
+        .replace(/\bBearer\s+[^\s,;]+/gi, 'Bearer [redacted]')
+        .replace(/((?:authorization|cookie|api[-_]?key|password|secret|token)\s*[=:]\s*)[^\s,;]+/gi, '$1[redacted]')
+        .slice(0, 4000);
+}
+class SessionClock {
+    constructor(source = () => performance.now()) {
+        this.source = source;
+        this.epoch = source();
+    }
+    now() { return Math.max(0, this.source() - this.epoch); }
+}
+exports.SessionClock = SessionClock;
+class Collector {
+    constructor(clock = new SessionClock(), limit = 5000) {
+        this.clock = clock;
+        this.limit = limit;
+        this.events = [];
+        this.dropped = 0;
+    }
+    add(type, data) {
+        if (this.events.length >= this.limit) {
+            this.dropped++;
+            return;
+        }
+        this.events.push({ ...data, type, timestampMs: this.clock.now() });
+    }
+}
+exports.Collector = Collector;
+function instrumentFetch(original, collector) {
+    return (async (input, init) => {
+        const url = safeUrl(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
+        const method = (init?.method ?? (typeof input === 'object' && 'method' in input ? input.method : 'GET')).toUpperCase();
+        const start = collector.clock.now();
+        try {
+            const response = await original(input, init);
+            collector.add('network', { requestTimestampMs: start, method, url, status: response.status, durationMs: collector.clock.now() - start });
+            return response;
+        }
+        catch (error) {
+            collector.add('network', { requestTimestampMs: start, method, url, status: null, durationMs: collector.clock.now() - start, error: safeText(error) });
+            throw error;
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import React from 'react';
+import { type PressableProps, type StyleProp, type ViewStyle } from 'react-native';
+import { type NativeCaptureAdapter } from './capture';
+export type { NativeCaptureAdapter } from './capture';
+export { Collector, SessionClock, safeText, safeUrl } from './core';
+export type AudioAdapter = {
+    prepare(): Promise<void>;
+    start(): void;
+    stop(): Promise<string | null>;
+    upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;
+};
+export type BugSessionOptions = {
+    recorderUrl: string;
+    recorderToken?: string;
+    audio?: AudioAdapter;
+    capture?: NativeCaptureAdapter;
+    device: Record<string, unknown>;
+    application: Record<string, unknown>;
+};
+export type BugSessionTriggerProps = {
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    offset?: number;
+    style?: StyleProp<ViewStyle>;
+    accessibilityLabel?: string;
+    children?: React.ReactNode;
+    onError?: (error: unknown) => void;
+};
+declare function captureError(error: unknown, source?: string): void;
+export declare const BugSession: {
+    configure(config: BugSessionOptions): void;
+    readonly status: "idle" | "starting" | "recording" | "stopping";
+    start(): Promise<string>;
+    stop(): Promise<any>;
+    trackAction(action: {
+        name: string;
+        screen?: string;
+    }): void;
+    trackNavigation(screen: string): void;
+    captureError: typeof captureError;
+    /** Use with NavigationContainer.onStateChange for non-Expo React Navigation apps. */
+    navigationListener(ref: {
+        getCurrentRoute(): {
+            name: string;
+        } | undefined;
+    }): () => void;
+    Touchable({ name, screen, onPress, ...props }: PressableProps & {
+        name: string;
+        screen?: string;
+    }): React.JSX.Element;
+    Trigger({ position, offset, style, accessibilityLabel, children, onError }: BugSessionTriggerProps): React.JSX.Element;
+};

package/dist/index.js

@@ -0,0 +1,234 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BugSession = exports.safeUrl = exports.safeText = exports.SessionClock = exports.Collector = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+const core_1 = require("./core");
+const capture_1 = require("./capture");
+var core_2 = require("./core");
+Object.defineProperty(exports, "Collector", { enumerable: true, get: function () { return core_2.Collector; } });
+Object.defineProperty(exports, "SessionClock", { enumerable: true, get: function () { return core_2.SessionClock; } });
+Object.defineProperty(exports, "safeText", { enumerable: true, get: function () { return core_2.safeText; } });
+Object.defineProperty(exports, "safeUrl", { enumerable: true, get: function () { return core_2.safeUrl; } });
+const globals = globalThis;
+let options;
+let collector = null;
+let session = null;
+let state = 'idle';
+let restore = null;
+let currentScreen = 'Home';
+let rawFetch;
+function authHeaders() {
+    return options.recorderToken ? { Authorization: `Bearer ${options.recorderToken}` } : {};
+}
+async function calibrate(clock, source) {
+    const samples = [];
+    for (let i = 0; i < 5; i++) {
+        const sent = clock.now();
+        const remote = await source();
+        const received = clock.now();
+        if (!Number.isFinite(remote))
+            throw new Error('Invalid capture clock');
+        samples.push({ rtt: received - sent, offset: (sent + received) / 2 - remote });
+    }
+    return samples.sort((a, b) => a.rtt - b.rtt)[0];
+}
+async function request(path, data) {
+    const response = await rawFetch(`${options.recorderUrl}${path}`, {
+        ...(data === undefined ? {} : { method: 'POST', body: JSON.stringify(data) }),
+        headers: { ...authHeaders(), ...(data === undefined ? {} : { 'Content-Type': 'application/json' }) },
+    });
+    if (!response.ok)
+        throw new Error(`Recorder ${response.status}: ${await response.text()}`);
+    return response.json();
+}
+function install(c) {
+    const originalFetch = globalThis.fetch;
+    const wrappedFetch = (0, core_1.instrumentFetch)(rawFetch, c);
+    globalThis.fetch = wrappedFetch;
+    const originals = { log: console.log, warn: console.warn, error: console.error };
+    for (const level of ['log', 'warn', 'error']) {
+        console[level] = (...args) => {
+            c.add(level === 'error' ? 'error' : 'log', { level, message: args.map(core_1.safeText).join(' '), source: 'console', stack: args.find(a => a instanceof Error)?.stack ? (0, core_1.safeText)(args.find(a => a instanceof Error).stack) : undefined });
+            originals[level](...args);
+        };
+    }
+    const utils = globals.ErrorUtils;
+    const handler = utils?.getGlobalHandler();
+    const onError = (error, fatal) => {
+        captureError(error, fatal ? 'fatal' : 'uncaught');
+        handler?.(error, fatal);
+    };
+    if (utils && handler)
+        utils.setGlobalHandler(onError);
+    return () => {
+        if (globalThis.fetch === wrappedFetch)
+            globalThis.fetch = originalFetch;
+        for (const level of ['log', 'warn', 'error'])
+            console[level] = originals[level];
+        if (utils?.getGlobalHandler() === onError && handler)
+            utils.setGlobalHandler(handler);
+    };
+}
+function captureError(error, source = 'boundary') {
+    collector?.add('error', { source, message: (0, core_1.safeText)(error), stack: error instanceof Error ? (0, core_1.safeText)(error.stack ?? '') : undefined, screen: currentScreen });
+}
+exports.BugSession = {
+    configure(config) {
+        if (state !== 'idle')
+            throw new Error('Cannot configure an active BugSession');
+        options = { ...config, recorderUrl: config.recorderUrl.replace(/\/$/, '') };
+    },
+    get status() { return state; },
+    async start() {
+        if (!options)
+            throw new Error('Configure BugSession first');
+        if (react_native_1.Platform.OS !== 'android' && react_native_1.Platform.OS !== 'ios')
+            throw new Error('Recording supports iOS and Android only');
+        if (react_native_1.Platform.OS === 'ios' && !options.capture)
+            throw new Error('iOS needs the ReplayKit capture adapter and a native development build');
+        if (react_native_1.Platform.OS === 'android' && !options.audio)
+            throw new Error('Android needs a microphone adapter');
+        if (state !== 'idle')
+            throw new Error(`BugSession is ${state}`);
+        state = 'starting';
+        rawFetch = globalThis.fetch.bind(globalThis);
+        let createdId = null;
+        let audioStarted = false;
+        try {
+            const isIOS = react_native_1.Platform.OS === 'ios';
+            if (!isIOS)
+                await options.audio.prepare();
+            const clock = new core_1.SessionClock();
+            const nativeClock = isIOS ? 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() });
+            createdId = result.id;
+            let audioStartMs = clock.now();
+            if (isIOS)
+                await options.capture.start();
+            else {
+                options.audio.start();
+                audioStarted = true;
+            }
+            session = {
+                id: result.id, audioStartMs,
+                videoStartMs: isIOS ? 0 : Math.max(0, result.videoHostStartMs + best.offset),
+                uncertaintyMs: best.rtt / 2, captureBackend: isIOS ? 'replaykit' : 'adb',
+                ...(nativeClock ? { nativeOffsetMs: nativeClock.offset, nativeUncertaintyMs: nativeClock.rtt / 2 } : {}),
+            };
+            restore = install(collector);
+            state = 'recording';
+            collector.add('navigation', { from: null, to: currentScreen });
+            return session.id;
+        }
+        catch (error) {
+            if (react_native_1.Platform.OS === 'ios')
+                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;
+        }
+    },
+    async stop() {
+        if (state !== 'recording' || !session || !collector)
+            throw new Error('No recording is active');
+        state = 'stopping';
+        const c = collector;
+        const active = session;
+        c.add('session-stop', {});
+        restore?.();
+        restore = null;
+        try {
+            let media;
+            if (active.captureBackend === 'replaykit') {
+                const recording = await options.capture.stop();
+                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 {
+                const uri = await options.audio.stop();
+                const audioEndMs = c.clock.now();
+                if (!uri)
+                    throw new Error('Microphone recording has no file');
+                await options.audio.upload(`${options.recorderUrl}/sessions/${active.id}/audio`, uri, authHeaders());
+                media = { ...active, audioEndMs };
+            }
+            return await request(`/sessions/${active.id}/stop`, {
+                durationMs: c.clock.now(), events: c.events, droppedEvents: c.dropped,
+                media,
+            });
+        }
+        catch (error) {
+            if (active.captureBackend === 'replaykit')
+                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(() => { });
+            throw error;
+        }
+        finally {
+            collector = null;
+            session = null;
+            state = 'idle';
+        }
+    },
+    trackAction(action) {
+        collector?.add('action', { target: (0, core_1.safeText)(action.name), screen: (0, core_1.safeText)(action.screen ?? currentScreen) });
+    },
+    trackNavigation(screen) {
+        if (currentScreen !== screen)
+            collector?.add('navigation', { from: currentScreen, to: screen });
+        currentScreen = screen;
+    },
+    captureError,
+    /** Use with NavigationContainer.onStateChange for non-Expo React Navigation apps. */
+    navigationListener(ref) {
+        return () => { const route = ref.getCurrentRoute(); if (route)
+            exports.BugSession.trackNavigation(route.name); };
+    },
+    Touchable({ name, screen, onPress, ...props }) {
+        return (0, jsx_runtime_1.jsx)(react_native_1.Pressable, { ...props, onPress: e => { exports.BugSession.trackAction({ name, screen }); onPress?.(e); } });
+    },
+    Trigger({ position = 'bottom-right', offset = 24, style, accessibilityLabel, children, onError }) {
+        const [busy, setBusy] = react_1.default.useState(false);
+        const recording = state === 'recording';
+        const edge = position.includes('right') ? { right: offset } : { left: offset };
+        const vertical = position.includes('bottom') ? { bottom: offset } : { top: offset };
+        const toggle = async () => {
+            if (busy)
+                return;
+            setBusy(true);
+            try {
+                if (state === 'recording')
+                    await exports.BugSession.stop();
+                else
+                    await exports.BugSession.start();
+            }
+            catch (error) {
+                onError?.(error);
+            }
+            finally {
+                setBusy(false);
+            }
+        };
+        return (0, jsx_runtime_1.jsx)(react_native_1.View, { pointerEvents: "box-none", style: [styles.triggerLayer, edge, vertical], children: (0, jsx_runtime_1.jsx)(react_native_1.Pressable, { accessibilityRole: "button", accessibilityLabel: accessibilityLabel ?? (recording ? 'Stop BugSession recording' : 'Start BugSession recording'), accessibilityState: { busy, selected: recording }, disabled: busy, onPress: () => { void toggle(); }, style: [styles.trigger, recording && styles.triggerRecording, style], children: children ?? (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.triggerMark, children: "b" }), (0, jsx_runtime_1.jsx)(react_native_1.View, { style: [styles.triggerDot, recording && styles.triggerDotRecording] })] }) }) });
+    },
+};
+const styles = react_native_1.StyleSheet.create({
+    triggerLayer: { position: 'absolute', zIndex: 9999 },
+    trigger: { width: 58, height: 58, borderRadius: 29, backgroundColor: '#173B34', alignItems: 'center', justifyContent: 'center', elevation: 8, shadowColor: '#000', shadowOpacity: 0.24, shadowRadius: 8, shadowOffset: { width: 0, height: 4 } },
+    triggerRecording: { backgroundColor: '#B9382F' },
+    triggerMark: { color: '#F4F4EC', fontSize: 31, fontWeight: '800', lineHeight: 38 },
+    triggerDot: { position: 'absolute', right: 9, bottom: 9, width: 10, height: 10, borderRadius: 5, backgroundColor: '#D8F36A', borderWidth: 1, borderColor: '#173B34' },
+    triggerDotRecording: { backgroundColor: '#FFF', borderColor: '#B9382F' },
+});

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@bugsession/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "peerDependencies": {
+    "react": ">=19.3.0 <20",
+    "react-native": ">=0.88.0 <0.89"
+  },
+  "description": "Opt-in React Native runtime evidence SDK",
+  "license": "UNLICENSED",
+  "react-native": "src/index.tsx",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.tsx",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Anis-Ghliss/bugsession.git",
+    "directory": "packages/react-native"
+  },
+  "homepage": "https://github.com/Anis-Ghliss/bugsession/tree/main/packages/react-native#readme",
+  "bugs": {
+    "url": "https://github.com/Anis-Ghliss/bugsession/issues"
+  }
+}

package/src/capture.ts

@@ -0,0 +1,28 @@
+export type NativeRecording = {
+  uri: string;
+  firstVideoNativeMs: number;
+  firstAudioNativeMs: number | null;
+  droppedVideoFrames: number;
+  droppedAudioBuffers: number;
+};
+export type NativeCaptureAdapter = {
+  clock(): Promise<number>;
+  start(): Promise<void>;
+  stop(): Promise<NativeRecording>;
+  cancel(): Promise<void>;
+  upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;
+};
+export function alignNativeRecording(recording: NativeRecording, offsetMs: number, uncertaintyMs: number) {
+  const videoStartMs = recording.firstVideoNativeMs + offsetMs;
+  const audioStartMs = recording.firstAudioNativeMs === null ? videoStartMs : recording.firstAudioNativeMs + offsetMs;
+  if (![videoStartMs, audioStartMs, uncertaintyMs].every(Number.isFinite) || videoStartMs < 0 || audioStartMs < videoStartMs || uncertaintyMs < 0) {
+    throw new Error('Invalid ReplayKit clock mapping');
+  }
+  return {
+    videoStartMs, audioStartMs, alignment: 'replaykit-host-clock',
+    videoAlignmentUncertaintyMs: uncertaintyMs,
+    microphoneAvailable: recording.firstAudioNativeMs !== null,
+    droppedVideoFrames: recording.droppedVideoFrames,
+    droppedAudioBuffers: recording.droppedAudioBuffers,
+  };
+}

package/src/core.ts

@@ -0,0 +1,47 @@
+export type Evidence = { timestampMs: number; type: string; [key: string]: unknown };
+
+export function safeUrl(input: string): string {
+  try {
+    const u = new URL(input, 'http://relative.invalid');
+    // Paths can contain credentials too; redact common key/value path segments.
+    const path = u.pathname.replace(/\/(token|password|secret|api[-_]?key)\/[^/]+/gi, '/$1/[redacted]');
+    return (u.hostname === 'relative.invalid' ? '' : `${u.protocol}//${u.host}`) + path;
+  } catch { return '[invalid URL]'; }
+}
+export function safeText(value: unknown): string {
+  const text = value instanceof Error ? value.message : typeof value === 'string' ? value : '[non-string value omitted]';
+  return text
+    .replace(/https?:\/\/[^\s)"']+/g, (url) => safeUrl(url))
+    .replace(/\bBearer\s+[^\s,;]+/gi, 'Bearer [redacted]')
+    .replace(/((?:authorization|cookie|api[-_]?key|password|secret|token)\s*[=:]\s*)[^\s,;]+/gi, '$1[redacted]')
+    .slice(0, 4000);
+}
+export class SessionClock {
+  private epoch: number;
+  constructor(private source = () => performance.now()) { this.epoch = source(); }
+  now() { return Math.max(0, this.source() - this.epoch); }
+}
+export class Collector {
+  events: Evidence[] = [];
+  dropped = 0;
+  constructor(public clock = new SessionClock(), private limit = 5000) {}
+  add(type: string, data: Record<string, unknown>) {
+    if (this.events.length >= this.limit) { this.dropped++; return; }
+    this.events.push({ ...data, type, timestampMs: this.clock.now() });
+  }
+}
+export function instrumentFetch(original: typeof fetch, collector: Collector): typeof fetch {
+  return (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+    const url = safeUrl(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
+    const method = (init?.method ?? (typeof input === 'object' && 'method' in input ? input.method : 'GET')).toUpperCase();
+    const start = collector.clock.now();
+    try {
+      const response = await original(input, init);
+      collector.add('network', { requestTimestampMs: start, method, url, status: response.status, durationMs: collector.clock.now() - start });
+      return response;
+    } catch (error) {
+      collector.add('network', { requestTimestampMs: start, method, url, status: null, durationMs: collector.clock.now() - start, error: safeText(error) });
+      throw error;
+    }
+  }) as typeof fetch;
+}

package/src/index.tsx

@@ -0,0 +1,207 @@
+import React from 'react';
+import { Pressable, StyleSheet, Text, View, type PressableProps, type StyleProp, type ViewStyle, Platform } from 'react-native';
+import { Collector, instrumentFetch, safeText, safeUrl, SessionClock } from './core';
+import { alignNativeRecording, type NativeCaptureAdapter } from './capture';
+export type { NativeCaptureAdapter } from './capture';
+export { Collector, SessionClock, safeText, safeUrl } from './core';
+
+export type AudioAdapter = {
+  prepare(): Promise<void>;
+  start(): void;
+  stop(): Promise<string | null>;
+  upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;
+};
+export type BugSessionOptions = { recorderUrl: string; recorderToken?: string; audio?: AudioAdapter; capture?: NativeCaptureAdapter; device: Record<string, unknown>; application: Record<string, unknown> };
+export type BugSessionTriggerProps = {
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  offset?: number;
+  style?: StyleProp<ViewStyle>;
+  accessibilityLabel?: string;
+  children?: React.ReactNode;
+  onError?: (error: unknown) => void;
+};
+type ErrorUtilsType = { getGlobalHandler(): (e: Error, fatal?: boolean) => void; setGlobalHandler(handler: (e: Error, fatal?: boolean) => void): 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 state: 'idle' | 'starting' | 'recording' | 'stopping' = 'idle';
+let restore: (() => void) | null = null;
+let currentScreen = 'Home';
+let rawFetch: typeof fetch;
+function authHeaders(): Record<string, string> {
+  return options.recorderToken ? { Authorization: `Bearer ${options.recorderToken}` } : {};
+}
+async function calibrate(clock: SessionClock, source: () => Promise<number>) {
+  const samples: { rtt: number; offset: number }[] = [];
+  for (let i = 0; i < 5; i++) {
+    const sent = clock.now(); const remote = await source(); const received = clock.now();
+    if (!Number.isFinite(remote)) throw new Error('Invalid capture clock');
+    samples.push({ rtt: received - sent, offset: (sent + received) / 2 - remote });
+  }
+  return samples.sort((a, b) => a.rtt - b.rtt)[0];
+}
+async function request(path: string, data?: unknown) {
+  const response = await rawFetch(`${options.recorderUrl}${path}`, {
+    ...(data === undefined ? {} : { method: 'POST', body: JSON.stringify(data) }),
+    headers: { ...authHeaders(), ...(data === undefined ? {} : { 'Content-Type': 'application/json' }) },
+  });
+  if (!response.ok) throw new Error(`Recorder ${response.status}: ${await response.text()}`);
+  return response.json();
+}
+function install(c: Collector) {
+  const originalFetch = globalThis.fetch;
+  const wrappedFetch = instrumentFetch(rawFetch, c);
+  globalThis.fetch = wrappedFetch;
+  const originals = { log: console.log, warn: console.warn, error: console.error };
+  for (const level of ['log', 'warn', 'error'] as const) {
+    console[level] = (...args: unknown[]) => {
+      c.add(level === 'error' ? 'error' : 'log', { level, message: args.map(safeText).join(' '), source: 'console', stack: args.find(a => a instanceof Error)?.stack ? safeText((args.find(a => a instanceof Error) as Error).stack) : undefined });
+      originals[level](...args);
+    };
+  }
+  const utils = globals.ErrorUtils;
+  const handler = utils?.getGlobalHandler();
+  const onError = (error: Error, fatal?: boolean) => {
+    captureError(error, fatal ? 'fatal' : 'uncaught');
+    handler?.(error, fatal);
+  };
+  if (utils && handler) utils.setGlobalHandler(onError);
+  return () => {
+    if (globalThis.fetch === wrappedFetch) globalThis.fetch = originalFetch;
+    for (const level of ['log', 'warn', 'error'] as const) console[level] = originals[level];
+    if (utils?.getGlobalHandler() === onError && handler) utils.setGlobalHandler(handler);
+  };
+}
+function captureError(error: unknown, source = 'boundary') {
+  collector?.add('error', { source, message: safeText(error), stack: error instanceof Error ? safeText(error.stack ?? '') : undefined, screen: currentScreen });
+}
+
+export const BugSession = {
+  configure(config: BugSessionOptions) {
+    if (state !== 'idle') throw new Error('Cannot configure an active BugSession');
+    options = { ...config, recorderUrl: config.recorderUrl.replace(/\/$/, '') };
+  },
+  get status() { return state; },
+  async start() {
+    if (!options) throw new Error('Configure BugSession first');
+    if (Platform.OS !== 'android' && Platform.OS !== 'ios') throw new Error('Recording supports iOS and Android only');
+    if (Platform.OS === 'ios' && !options.capture) throw new Error('iOS needs the ReplayKit capture adapter and a native development build');
+    if (Platform.OS === 'android' && !options.audio) throw new Error('Android needs a microphone adapter');
+    if (state !== 'idle') throw new Error(`BugSession is ${state}`);
+    state = 'starting';
+    rawFetch = globalThis.fetch.bind(globalThis);
+    let createdId: string | null = null;
+    let audioStarted = false;
+    try {
+      const isIOS = Platform.OS === 'ios';
+      if (!isIOS) await options.audio!.prepare();
+      const clock = new SessionClock();
+      const nativeClock = isIOS ? 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() });
+      createdId = result.id;
+      let audioStartMs = clock.now();
+      if (isIOS) await options.capture!.start();
+      else { options.audio!.start(); audioStarted = true; }
+      session = {
+        id: result.id, audioStartMs,
+        videoStartMs: isIOS ? 0 : Math.max(0, result.videoHostStartMs + best.offset),
+        uncertaintyMs: best.rtt / 2, captureBackend: isIOS ? 'replaykit' : 'adb',
+        ...(nativeClock ? { nativeOffsetMs: nativeClock.offset, nativeUncertaintyMs: nativeClock.rtt / 2 } : {}),
+      };
+      restore = install(collector);
+      state = 'recording';
+      collector.add('navigation', { from: null, to: currentScreen });
+      return session.id;
+    } catch (error) {
+      if (Platform.OS === 'ios') 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;
+    }
+  },
+  async stop() {
+    if (state !== 'recording' || !session || !collector) throw new Error('No recording is active');
+    state = 'stopping';
+    const c = collector;
+    const active = session;
+    c.add('session-stop', {});
+    restore?.(); restore = null;
+    try {
+      let media: Record<string, unknown>;
+      if (active.captureBackend === 'replaykit') {
+        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 {
+        const uri = await options.audio!.stop();
+        const audioEndMs = c.clock.now();
+        if (!uri) throw new Error('Microphone recording has no file');
+        await options.audio!.upload(`${options.recorderUrl}/sessions/${active.id}/audio`, uri, authHeaders());
+        media = { ...active, audioEndMs };
+      }
+      return await request(`/sessions/${active.id}/stop`, {
+        durationMs: c.clock.now(), events: c.events, droppedEvents: c.dropped,
+        media,
+      });
+    } catch (error) {
+      if (active.captureBackend === 'replaykit') 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;
+    } finally { collector = null; session = null; state = 'idle'; }
+  },
+  trackAction(action: { name: string; screen?: string }) {
+    collector?.add('action', { target: safeText(action.name), screen: safeText(action.screen ?? currentScreen) });
+  },
+  trackNavigation(screen: string) {
+    if (currentScreen !== screen) collector?.add('navigation', { from: currentScreen, to: screen });
+    currentScreen = screen;
+  },
+  captureError,
+  /** Use with NavigationContainer.onStateChange for non-Expo React Navigation apps. */
+  navigationListener(ref: { getCurrentRoute(): { name: string } | undefined }) {
+    return () => { const route = ref.getCurrentRoute(); if (route) BugSession.trackNavigation(route.name); };
+  },
+  Touchable({ name, screen, onPress, ...props }: PressableProps & { name: string; screen?: string }) {
+    return <Pressable {...props} onPress={e => { BugSession.trackAction({ name, screen }); onPress?.(e); }} />;
+  },
+  Trigger({ position = 'bottom-right', offset = 24, style, accessibilityLabel, children, onError }: BugSessionTriggerProps) {
+    const [busy, setBusy] = React.useState(false);
+    const recording = state === 'recording';
+    const edge = position.includes('right') ? { right: offset } : { left: offset };
+    const vertical = position.includes('bottom') ? { bottom: offset } : { top: offset };
+    const toggle = async () => {
+      if (busy) return;
+      setBusy(true);
+      try {
+        if (state === 'recording') await BugSession.stop();
+        else await BugSession.start();
+      } catch (error) { onError?.(error); }
+      finally { setBusy(false); }
+    };
+    return <View pointerEvents="box-none" style={[styles.triggerLayer, edge, vertical]}>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel ?? (recording ? 'Stop BugSession recording' : 'Start BugSession recording')}
+        accessibilityState={{ busy, selected: recording }}
+        disabled={busy}
+        onPress={() => { void toggle(); }}
+        style={[styles.trigger, recording && styles.triggerRecording, style]}
+      >
+        {children ?? <><Text style={styles.triggerMark}>b</Text><View style={[styles.triggerDot, recording && styles.triggerDotRecording]} /></>}
+      </Pressable>
+    </View>;
+  },
+};
+
+const styles = StyleSheet.create({
+  triggerLayer: { position: 'absolute', zIndex: 9999 },
+  trigger: { width: 58, height: 58, borderRadius: 29, backgroundColor: '#173B34', alignItems: 'center', justifyContent: 'center', elevation: 8, shadowColor: '#000', shadowOpacity: 0.24, shadowRadius: 8, shadowOffset: { width: 0, height: 4 } },
+  triggerRecording: { backgroundColor: '#B9382F' },
+  triggerMark: { color: '#F4F4EC', fontSize: 31, fontWeight: '800', lineHeight: 38 },
+  triggerDot: { position: 'absolute', right: 9, bottom: 9, width: 10, height: 10, borderRadius: 5, backgroundColor: '#D8F36A', borderWidth: 1, borderColor: '#173B34' },
+  triggerDotRecording: { backgroundColor: '#FFF', borderColor: '#B9382F' },
+});