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

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,73 @@
-# 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 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
+
+After publication:
+
+```sh
+npm install @bugsession/react-native@beta @bugsession/capture-native@beta
+npx expo install expo-audio expo-file-system
+```
+
+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
+
+```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',
+  recorderToken: projectIngestionKey, // Generate in dashboard → project → Connect your SDK.
+  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 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. 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

@@ -0,0 +1,26 @@
+export type NativeRecording = {
+    uri: string;
+    firstVideoNativeMs: number;
+    firstAudioNativeMs: number | null;
+    droppedVideoFrames: number;
+    droppedAudioBuffers: number;
+};
+export type NativeCaptureAdapter = {
+    prepare?(): Promise<void>;
+    clock(): Promise<number>;
+    start(): Promise<void | {
+        firstVideoNativeMs: number;
+    }>;
+    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,254 @@
+"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;
+        const isIOS = react_native_1.Platform.OS === 'ios';
+        const useNativeCapture = isIOS || (react_native_1.Platform.OS === 'android' && !!options.capture);
+        try {
+            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 = 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 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;
+            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, nativeVideoStartMs ?? result.videoHostStartMs + best.offset),
+                uncertaintyMs: best.rtt / 2, captureBackend,
+                ...(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 (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;
+        }
+    },
+    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 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();
+                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 !== '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(() => { });
+            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.2",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "peerDependencies": {
+    "react": ">=18.3.1 <20",
+    "react-native": ">=0.76.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,29 @@
+export type NativeRecording = {
+  uri: string;
+  firstVideoNativeMs: number;
+  firstAudioNativeMs: number | null;
+  droppedVideoFrames: number;
+  droppedAudioBuffers: number;
+};
+export type NativeCaptureAdapter = {
+  prepare?(): Promise<void>;
+  clock(): Promise<number>;
+  start(): Promise<void | { firstVideoNativeMs: number }>;
+  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,225 @@
+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' | 'mediaprojection'; 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;
+    const isIOS = Platform.OS === 'ios';
+    const useNativeCapture = isIOS || (Platform.OS === 'android' && !!options.capture);
+    try {
+      if (Platform.OS === 'android' && options.capture?.prepare) await options.capture.prepare();
+      if (!isIOS) await options.audio!.prepare();
+      const clock = new SessionClock();
+      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 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;
+      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, nativeVideoStartMs ?? result.videoHostStartMs + best.offset),
+        uncertaintyMs: best.rtt / 2, captureBackend,
+        ...(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 (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;
+    }
+  },
+  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 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();
+        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 !== '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;
+    } 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' },
+});