@bugsession/react-native 0.1.0-beta.3 → 0.1.0-beta.5

package/README.md

@@ -56,7 +56,17 @@ Configure once while idle. Wire an automatic stop timer into your recording UI,
 
 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. It is draggable by default, stays within screen bounds, and remembers its moved position across screen changes and trigger remounts while the app remains open. Render it once above the app navigator so it stays visible during navigation. Configure its initial corner with `position` (`bottom-right` by default; also `bottom-left`, `top-right`, or `top-left`) and adjust `offset` in points. Set `draggable={false}` to lock it. Pass `onError` to surface permission, recorder, and upload failures. Supply `children` to replace the default mark.
+Render errors are caught by Expo Router before they reach the global handler. Export the SDK's boundary from your root layout so they are captured: `export const ErrorBoundary = BugSession.ErrorBoundary;`. Unhandled promise rejections are captured in every build; in development they still reach LogBox.
+
+`configure()` installs fetch, XMLHttpRequest (axios and most HTTP clients), console (`log`, `info`, `debug`, `warn`, `error`), error and rejection hooks for the app's lifetime; each request is recorded once, and the SDK's own uploads are skipped. By default the SDK keeps the last 60 seconds of these app events (at most 500; never video or audio) in memory. When a recording starts, they are attached with negative timestamps and `preRecording: true`, so a bug that happened just before the tester pressed record keeps its context. After Stop, events keep being collected for `postRecordSeconds` (default 5, maximum 30, `0` disables) while the video uploads, and are attached with `postRecording: true`, so the response to the tester's last tap is kept. Nothing leaves the device unless a recording starts. Set `preRecordSeconds` (maximum 300) to change the earlier window, or `0` to collect only while recording. Recorders deployed before pre- or post-record support accept the recording and ignore these events.
+
+Failed requests (status 400 or higher, text or JSON responses) include `responseExcerpt`: the first 1,000 characters of the response body, with JSON fields named like passwords, tokens, secrets, keys, cookies and sessions masked, plus the usual bearer and URL redaction. Successful responses and request bodies are never captured.
+
+Wrap your navigator once in `<BugSession.Capture>` to record every tap as an `action` event with `auto: true`, the tap position in points, the current screen and, when one can be read, the touched element's label (accessibility label, `aria-label`, title, placeholder, visible text or `testID`; never a text field's value). It only observes touches and never blocks gestures. `BugSession.Touchable` and `trackAction` remain available for explicit names.
+
+`<BugSession.Trigger />` renders a slim tab docked to a screen edge, so it never covers bottom buttons or tab bars. Tap it to start recording. Drag it along the edge or across to the other side; it remembers its placement while the app is open. Render it once above the app navigator. `position` picks the initial edge and half (`bottom-right` by default), `offset` the distance from the top or bottom safe area, and `draggable={false}` locks it. Supply `children` to replace the idle record mark.
+
+While recording, the tab shows a pulsing dot, elapsed time and live microphone levels. Tap it for the options panel: **Draw on screen** and **Stop & send**. The panel hides itself after a few seconds so it stays out of the video as much as possible; the tab itself is part of the screen recording. Draw opens a pen layer over the app: testers circle the problem while narrating, then use Undo, Clear or Done. Drawings appear in the video, and each stroke is recorded as an `annotation` event with its bounds in screen points. After stopping, a toast at the top shows sending progress, then "Report sent" or "Not sent" with the reason; it also reflects `BugSession.start()`/`stop()` called directly. Recording stops automatically after `maxDurationSeconds` (default 150) so uploads stay within the recorder limit. Pass `onError` to also receive permission, recorder, and upload failures. With `react-native-screens` installed (included with Expo Router), the tab renders above native modals. Live levels and exact safe-area placement need `@bugsession/capture-native` 0.1.0-beta.4 or later in a rebuilt native app; older builds show static bars.
 
 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.
 

package/dist/capture.d.ts

@@ -14,6 +14,18 @@ export type NativeCaptureAdapter = {
     stop(): Promise<NativeRecording>;
     cancel(): Promise<void>;
     upload(url: string, uri: string, headers?: Record<string, string>): Promise<void>;
+    /** Optional: live microphone level (0-1) for the recording indicator. Returns an unsubscribe function. */
+    onAudioLevel?(listener: (level: number) => void): () => void;
+    /** Optional: safe-area insets in points, used to place the recording controls above the home indicator. */
+    safeAreaInsets?(): Promise<{
+        top: number;
+        bottom: number;
+    } | null>;
+    /** Optional: native app and device facts merged into each recording's metadata. */
+    appContext?(): Promise<{
+        application: Record<string, unknown>;
+        device: Record<string, unknown>;
+    } | null>;
 };
 export declare function alignNativeRecording(recording: NativeRecording, offsetMs: number, uncertaintyMs: number): {
     videoStartMs: number;

package/dist/core.d.ts

@@ -10,6 +10,8 @@ export declare class SessionClock {
     private epoch;
     constructor(source?: () => number);
     now(): number;
+    /** Monotonic source reading at which this clock reads zero. */
+    get origin(): number;
 }
 export declare class Collector {
     clock: SessionClock;
@@ -18,5 +20,53 @@ export declare class Collector {
     dropped: number;
     constructor(clock?: SessionClock, limit?: number);
     add(type: string, data: Record<string, unknown>): void;
+    addAt(type: string, data: Record<string, unknown>, timestampMs: number): void;
 }
-export declare function instrumentFetch(original: typeof fetch, collector: Collector): typeof fetch;
+export type TelemetrySink = {
+    add(type: string, data: Record<string, unknown>): void;
+    clock: {
+        now(): number;
+    };
+};
+export declare const MAX_PRE_RECORD_MS = 300000;
+/**
+ * Routes app events to the active session, or, between sessions, into a bounded
+ * in-memory buffer of the last `preRecordMs`. The buffer never leaves the device
+ * unless a recording starts. Timestamps are kept on one app-lifetime clock and
+ * converted to the session clock, so requests spanning the start stay consistent.
+ */
+export declare class Telemetry implements TelemetrySink {
+    private maxBuffered;
+    readonly clock: SessionClock;
+    private buffer;
+    private session;
+    private preRecordMs;
+    constructor(preRecordMs?: number, maxBuffered?: number, source?: () => number);
+    /** False when nothing would be kept, so callers can skip formatting work. */
+    get active(): boolean;
+    configure(preRecordMs: number, maxBuffered?: number): void;
+    add(type: string, data: Record<string, unknown>): void;
+    /** Routes events to `collector` and returns the buffered events on its clock (negative times). */
+    begin(collector: Collector): Evidence[];
+    end(): void;
+    private prune;
+}
+/** Response excerpt for a failed request: text only, at most 1000 characters, secrets masked. */
+export declare function safeBody(text: unknown): string | undefined;
+/** Requests to these URLs (the recorder itself) are never recorded. */
+export declare function ignoreRequests(match: (url: string) => boolean): void;
+export declare function instrumentFetch(original: typeof fetch, collector: TelemetrySink): typeof fetch;
+type XhrLike = {
+    open(method: string, url: string | URL, ...rest: unknown[]): void;
+    send(body?: unknown): void;
+    addEventListener(type: string, listener: () => void): void;
+    status: number;
+    responseType?: string;
+    responseText?: string;
+    getResponseHeader?(name: string): string | null;
+};
+/** Records XMLHttpRequest traffic (axios and most HTTP libraries) that does not go through fetch. */
+export declare function instrumentXhr(Xhr: {
+    prototype: XhrLike;
+} | undefined, collector: TelemetrySink): void;
+export {};

package/dist/core.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Collector = exports.SessionClock = void 0;
+exports.Telemetry = exports.MAX_PRE_RECORD_MS = exports.Collector = exports.SessionClock = void 0;
 exports.safeUrl = safeUrl;
 exports.safeText = safeText;
+exports.safeBody = safeBody;
+exports.ignoreRequests = ignoreRequests;
 exports.instrumentFetch = instrumentFetch;
+exports.instrumentXhr = instrumentXhr;
 function safeUrl(input) {
     try {
         const u = new URL(input, 'http://relative.invalid');
@@ -29,6 +32,8 @@ class SessionClock {
         this.epoch = source();
     }
     now() { return Math.max(0, this.source() - this.epoch); }
+    /** Monotonic source reading at which this clock reads zero. */
+    get origin() { return this.epoch; }
 }
 exports.SessionClock = SessionClock;
 class Collector {
@@ -39,22 +44,117 @@ class Collector {
         this.dropped = 0;
     }
     add(type, data) {
+        this.addAt(type, data, this.clock.now());
+    }
+    addAt(type, data, timestampMs) {
         if (this.events.length >= this.limit) {
             this.dropped++;
             return;
         }
-        this.events.push({ ...data, type, timestampMs: this.clock.now() });
+        this.events.push({ ...data, type, timestampMs });
     }
 }
 exports.Collector = Collector;
+exports.MAX_PRE_RECORD_MS = 300000;
+/**
+ * Routes app events to the active session, or, between sessions, into a bounded
+ * in-memory buffer of the last `preRecordMs`. The buffer never leaves the device
+ * unless a recording starts. Timestamps are kept on one app-lifetime clock and
+ * converted to the session clock, so requests spanning the start stay consistent.
+ */
+class Telemetry {
+    constructor(preRecordMs = 60000, maxBuffered = 500, source = () => performance.now()) {
+        this.maxBuffered = maxBuffered;
+        this.buffer = [];
+        this.session = null;
+        this.clock = new SessionClock(source);
+        this.preRecordMs = Math.max(0, Math.min(preRecordMs, exports.MAX_PRE_RECORD_MS));
+    }
+    /** False when nothing would be kept, so callers can skip formatting work. */
+    get active() { return !!this.session || this.preRecordMs > 0; }
+    configure(preRecordMs, maxBuffered = this.maxBuffered) {
+        this.preRecordMs = Math.max(0, Math.min(preRecordMs, exports.MAX_PRE_RECORD_MS));
+        this.maxBuffered = maxBuffered;
+        this.prune(this.clock.now());
+    }
+    add(type, data) {
+        const now = this.clock.now();
+        if (this.session) {
+            const { collector, offsetMs } = this.session;
+            collector.addAt(type, shiftRequestTime(data, offsetMs), now - offsetMs);
+            return;
+        }
+        if (this.preRecordMs <= 0)
+            return;
+        this.buffer.push({ ...data, type, timestampMs: now });
+        this.prune(now);
+    }
+    /** Routes events to `collector` and returns the buffered events on its clock (negative times). */
+    begin(collector) {
+        const offsetMs = collector.clock.origin - this.clock.origin;
+        this.prune(this.clock.now());
+        const before = this.buffer.map(e => ({ ...shiftRequestTime(e, offsetMs), timestampMs: e.timestampMs - offsetMs, preRecording: true }));
+        this.buffer = [];
+        this.session = { collector, offsetMs };
+        return before;
+    }
+    end() { this.session = null; }
+    prune(now) {
+        const cutoff = now - this.preRecordMs;
+        let drop = 0;
+        while (drop < this.buffer.length && this.buffer[drop].timestampMs < cutoff)
+            drop++;
+        drop = Math.max(drop, this.buffer.length - this.maxBuffered);
+        if (drop > 0)
+            this.buffer.splice(0, drop);
+    }
+}
+exports.Telemetry = Telemetry;
+function shiftRequestTime(data, offsetMs) {
+    return typeof data.requestTimestampMs === 'number' ? { ...data, requestTimestampMs: data.requestTimestampMs - offsetMs } : data;
+}
+/** Response excerpt for a failed request: text only, at most 1000 characters, secrets masked. */
+function safeBody(text) {
+    if (typeof text !== 'string' || !text.trim())
+        return undefined;
+    return safeText(text.slice(0, 4000)
+        .replace(/("(?:[\w-]*(?:password|passwd|secret|token|authorization|cookie|api[-_]?key|session)[\w-]*)"\s*:\s*)("(?:[^"\\]|\\.)*"|[^,}\s]+)/gi, '$1"[redacted]"'))
+        .slice(0, 1000);
+}
+const textual = /json|text|xml|html|problem/i;
+const sdkRequests = { ignored: (_url) => false };
+/** Requests to these URLs (the recorder itself) are never recorded. */
+function ignoreRequests(match) { sdkRequests.ignored = match; }
+// React Native's fetch is built on XMLHttpRequest. While a fetch call creates its
+// request synchronously, the XHR hook skips it so each request is recorded once.
+let insideFetch = 0;
 function instrumentFetch(original, collector) {
     return (async (input, init) => {
-        const url = safeUrl(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
+        const rawUrl = 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();
+        let pending;
+        insideFetch++;
         try {
-            const response = await original(input, init);
-            collector.add('network', { requestTimestampMs: start, method, url, status: response.status, durationMs: collector.clock.now() - start });
+            pending = original(input, init);
+        }
+        finally {
+            insideFetch--;
+        }
+        if (sdkRequests.ignored(rawUrl))
+            return pending;
+        const url = safeUrl(rawUrl);
+        try {
+            const response = await pending;
+            const durationMs = collector.clock.now() - start;
+            let responseExcerpt;
+            if (response.status >= 400 && textual.test(response.headers?.get?.('content-type') ?? 'text')) {
+                responseExcerpt = await Promise.race([
+                    response.clone().text().then(safeBody, () => undefined),
+                    new Promise(resolve => setTimeout(() => resolve(undefined), 500)),
+                ]);
+            }
+            collector.add('network', { requestTimestampMs: start, method, url, status: response.status, durationMs, ...(responseExcerpt ? { responseExcerpt } : {}) });
             return response;
         }
         catch (error) {
@@ -63,3 +163,40 @@ function instrumentFetch(original, collector) {
         }
     });
 }
+/** Records XMLHttpRequest traffic (axios and most HTTP libraries) that does not go through fetch. */
+function instrumentXhr(Xhr, collector) {
+    if (!Xhr?.prototype?.open || !Xhr.prototype.send)
+        return;
+    const proto = Xhr.prototype;
+    const open = proto.open, send = proto.send;
+    const meta = new WeakMap();
+    proto.open = function (method, url, ...rest) {
+        const href = String(url);
+        if (!insideFetch && !sdkRequests.ignored(href))
+            meta.set(this, { method: String(method || 'GET').toUpperCase(), url: safeUrl(href) });
+        else
+            meta.delete(this);
+        return open.call(this, method, url, ...rest);
+    };
+    proto.send = function (body) {
+        const request = meta.get(this);
+        if (request) {
+            const start = collector.clock.now();
+            let error;
+            for (const type of ['error', 'timeout', 'abort'])
+                this.addEventListener(type, () => { error ?? (error = `Request ${type}`); });
+            this.addEventListener('loadend', () => {
+                const status = error || !this.status ? null : this.status;
+                let responseExcerpt;
+                try {
+                    if (status !== null && status >= 400 && (!this.responseType || this.responseType === 'text') && textual.test(this.getResponseHeader?.('content-type') ?? 'text'))
+                        responseExcerpt = safeBody(this.responseText);
+                }
+                catch { /* response not readable */ }
+                collector.add('network', { requestTimestampMs: start, method: request.method, url: request.url, status, durationMs: collector.clock.now() - start, client: 'xhr',
+                    ...(error ? { error } : {}), ...(responseExcerpt ? { responseExcerpt } : {}) });
+            });
+        }
+        return send.call(this, body);
+    };
+}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import React from 'react';
-import { type PressableProps, type StyleProp, type ViewStyle } from 'react-native';
+import { type PressableProps } from 'react-native';
+export type { Annotation, BugSessionTriggerProps, IndicatorPhase } from './trigger';
 import { type NativeCaptureAdapter } from './capture';
 export type { NativeCaptureAdapter } from './capture';
-export { Collector, SessionClock, safeText, safeUrl } from './core';
+export { Collector, SessionClock, Telemetry, safeText, safeUrl } from './core';
 export type AudioAdapter = {
     prepare(): Promise<void>;
     start(): void;
@@ -16,15 +17,20 @@ export type BugSessionOptions = {
     capture?: NativeCaptureAdapter;
     device: Record<string, unknown>;
     application: Record<string, unknown>;
+    /**
+     * Seconds of app events (logs, errors, network metadata, actions, navigation; never video or audio)
+     * kept in memory before a recording starts and attached to it. Defaults to 60, max 300; 0 disables.
+     */
+    preRecordSeconds?: number;
+    /**
+     * Seconds of app events still collected after the tester stops, while the video uploads,
+     * so a request or error that lands just after Stop is kept. Defaults to 5, max 30; 0 disables.
+     */
+    postRecordSeconds?: number;
 };
-export type BugSessionTriggerProps = {
-    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-    offset?: number;
-    draggable?: boolean;
-    style?: StyleProp<ViewStyle>;
-    accessibilityLabel?: string;
-    children?: React.ReactNode;
-    onError?: (error: unknown) => void;
+export type BugSessionErrorBoundaryProps = {
+    error: Error;
+    retry: () => void | Promise<void>;
 };
 declare function captureError(error: unknown, source?: string): void;
 export declare const BugSession: {
@@ -38,6 +44,20 @@ export declare const BugSession: {
     }): void;
     trackNavigation(screen: string): void;
     captureError: typeof captureError;
+    /**
+     * Wrap the app once (inside the navigator's container, around your screens) to record
+     * every tap automatically: position, current screen and the element's label when available.
+     */
+    Capture: ({ children, style, ...props }: import("react-native").ViewProps & {
+        children?: React.ReactNode;
+    }) => React.JSX.Element;
+    Trigger: ({ position, offset, draggable, style, accessibilityLabel, children, onError, maxDurationSeconds }: import("./trigger").BugSessionTriggerProps) => React.JSX.Element;
+    /**
+     * Expo Router error boundary that reports render errors (which never reach the
+     * global error handler). In a route or layout file:
+     * `export const ErrorBoundary = BugSession.ErrorBoundary;`
+     */
+    ErrorBoundary({ error, retry }: BugSessionErrorBoundaryProps): React.JSX.Element;
     /** Use with NavigationContainer.onStateChange for non-Expo React Navigation apps. */
     navigationListener(ref: {
         getCurrentRoute(): {
@@ -48,5 +68,4 @@ export declare const BugSession: {
         name: string;
         screen?: string;
     }): React.JSX.Element;
-    Trigger({ position, offset, draggable, style, accessibilityLabel, children, onError }: BugSessionTriggerProps): React.JSX.Element;
 };