@probie-dev/react-native 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+# @probie-dev/react-native
+
+Passive behavioral telemetry for **Expo / React Native** apps. It's the mobile
+counterpart to Probie's browser widget: it captures errors, network failures,
+taps/rage-taps, form friction, and screen views, then batches them to Probie's
+ingest endpoint.
+
+The SDK never reads input values or raw text. Element labels are **hashed**, and
+query strings are dropped by default.
+
+- **Target:** Expo managed workflow, SDK 50+. Expo-Go-safe dependencies.
+- **Zero-config** auto-capture (errors, network, app lifecycle) **plus** opt-in
+  instrumentation for taps, forms, and screens.
+- **Never throws** into your app — telemetry is strictly best-effort.
+
+## Install
+
+```bash
+npx expo install @probie-dev/react-native
+```
+
+Peer/companion modules (installed automatically as dependencies, but let Expo
+pin the versions): `expo-application`, `expo-device`, `expo-constants`,
+`expo-crypto`, `@react-native-async-storage/async-storage`.
+
+## Quick start
+
+Wrap your app once, near the root:
+
+```tsx
+import { ProbieProvider } from '@probie-dev/react-native';
+
+export default function RootLayout() {
+  return (
+    <ProbieProvider config={{ token: 'YOUR_WIDGET_TOKEN', apiBase: 'https://probie.dev' }}>
+      <App />
+    </ProbieProvider>
+  );
+}
+```
+
+That alone gives you JS errors, unhandled rejections, network failures, and app
+lifecycle flushing. Add navigation + interaction capture below.
+
+### Screen views
+
+**Expo Router:**
+
+```tsx
+import { useProbieExpoRouter } from '@probie-dev/react-native';
+
+function ScreenTracking() {
+  useProbieExpoRouter(); // auto pageview on every path change
+  return null;
+}
+// render <ScreenTracking /> inside <ProbieProvider>
+```
+
+**React Navigation:**
+
+```tsx
+import { probieNavigationContainerProps } from '@probie-dev/react-native';
+
+<NavigationContainer {...probieNavigationContainerProps()}>
+  {/* ... */}
+</NavigationContainer>
+```
+
+**Manual:**
+
+```tsx
+import { trackScreen } from '@probie-dev/react-native';
+trackScreen('Checkout');
+```
+
+> The Expo Router adapter captures the route **template** (`/reset/[token]`), not
+> the concrete path (`/reset/abc123`), so dynamic segment values (tokens, invite
+> codes, ids) are never emitted. With `trackScreen(name)` you control the string —
+> pass a stable screen name, not a path containing raw ids.
+
+### Taps
+
+Use `ProbiePressable` (a drop-in for `Pressable`) to capture taps and rage-taps.
+It always calls your `onPress`:
+
+```tsx
+import { ProbiePressable } from '@probie-dev/react-native';
+
+<ProbiePressable testID="buy" accessibilityRole="button" accessibilityLabel="Buy now" onPress={buy}>
+  <Text>Buy now</Text>
+</ProbiePressable>
+```
+
+Or emit a tap explicitly: `track('click', {}, { testID: 'buy' })`.
+
+### Forms
+
+`useProbieForm` is **telemetry-only** — it does not perform your submit. You keep
+writing your own submit logic (a fetch, a mutation, navigation); you just also
+call the two handlers so Probie can observe it.
+
+```tsx
+import { useProbieForm } from '@probie-dev/react-native';
+
+const form = useProbieForm('signup'); // stable key per logical form
+
+<TextInput onFocus={form.onFocus} ... />
+<Button
+  onPress={() => {
+    form.onSubmit();   // tell Probie a submit happened
+    mySubmitFunc();    // your actual work (fetch, etc.)
+  }}
+  title="Sign up"
+/>
+```
+
+Or call Probie inside your own handler and pass it by reference:
+
+```tsx
+async function mySubmitFunc() {
+  form.onSubmit();
+  await fetch('https://api.myapp.com/signup', { method: 'POST', /* ... */ });
+}
+
+<Button onPress={mySubmitFunc} title="Sign up" />   // note: no ()
+```
+
+> ⚠️ `onPress` takes a **function to run on tap**, not the result of calling one.
+> Don't write `onPress={form.onSubmit() && mySubmitFunc()}` — that runs both at
+> render time (once, not on tap), and `&&` short-circuits on `onSubmit()`'s
+> `undefined` return so `mySubmitFunc` never runs. Always wrap multiple calls in
+> an arrow function: `onPress={() => { form.onSubmit(); mySubmitFunc(); }}`.
+
+You don't need to report the request failure yourself: if the request in your
+submit returns 4xx/5xx or throws, the network interceptor already emits a
+`fetch_error`. Combined with `form_retry`, that gives Probie enough context to
+surface frustrated sessions from these two handlers plus auto-capture.
+
+Two submits within 10s → `form_retry`; touched-but-never-submitted → `form_abandon`
+(emitted when the app backgrounds).
+
+### Identity
+
+```tsx
+import { identify, reset } from '@probie-dev/react-native';
+identify(user.id); // on login
+reset();           // on logout (clears user, starts a new session)
+```
+
+## Configuration
+
+| Option | Default | Notes |
+|---|---|---|
+| `token` | — (required) | Project widget token (same as the browser widget). |
+| `apiBase` | — (required) | Probie ingest base URL, e.g. `https://probie.dev`. |
+| `sampleRate` | `1` | 0..1. Sampled once per session; a sampled-out session captures nothing. |
+| `captureQuery` | `false` | Include query strings on captured URLs (PII risk on deep links). |
+| `captureErrors` | `true` | Install the global JS error handler. |
+| `captureNetwork` | `true` | Install the XHR network-error interceptor. |
+| `captureUnhandledRejections` | `true` | Track unhandled promise rejections. See load-order note below. |
+| `idleTimeoutMs` | `null` | Resume the previous session if the app cold-starts within this window. Default: a new session per cold start. |
+| `flushIntervalMs` | `12000` | Batch flush interval. |
+| `appVersion` | auto | Override the version detected from `expo-application`. |
+
+## Events
+
+Eight event types:
+`pageview`, `click`, `rage_click`, `form_submit`, `form_abandon`, `form_retry`,
+`fetch_error`, `js_error`.
+
+Every event also carries a `context` object (platform, os_version, app_version,
+build, device_model, sdk_name, sdk_version, anon_id).
+
+## Notes & gotchas
+
+- **`accessibility`/`testID` drive element quality.** Set `testID` and
+  `accessibilityRole`/`accessibilityLabel` on interactive elements for useful
+  `element_path`s. Labels are hashed, never sent raw.
+- **URLs are PII-scrubbed.** Captured URLs (including `fetch_error` urls) drop the
+  fragment, drop the query unless `captureQuery` is on, and always strip
+  `user:pass@` basic-auth credentials from the host.
+- **Sentry / LogBox load order.** `captureUnhandledRejections` uses RN's promise
+  rejection-tracking, which can collide with Sentry RN. If you see duplicate
+  reports, set `captureUnhandledRejections: false`.
+- **Network is XHR-only.** RN's `fetch` runs over `XMLHttpRequest`, so the SDK
+  patches XHR only (patching both would double-count). The SDK's own POST to the
+  ingest endpoint is excluded to avoid a feedback loop.
+- **Hard kills can lose the last batch.** RN has no `sendBeacon`; the SDK flushes
+  on background/inactive and on an interval. This is best-effort, same as web.
+
+## Example App
+
+`example/` is a minimal Expo Router app with a tracked tap, a rage target, a
+failing fetch, a throw, a tracked form, and a **Send now** (flush) button.
+
+1. Set `example/app.json` → `extra.probieToken` and `extra.probieApiBase`.
+2. `cd example && npm install && npm start`, open in Expo Go, tap around, hit
+   **Send now**.
+3. Confirm events appear in Probie.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test          # jest-expo
+npm run build     # emits dist/ (.js + .d.ts)
+```
+
+## Publishing
+
+The package publishes to public npm under the `@probie-dev` scope. `files`
+ships `dist/` only; `prepublishOnly` runs a clean build.
+
+```bash
+npm run build
+npm publish       # publishConfig.access = public
+```
+
+For a distribution smoke test, install the published package in a fresh Expo app
+and confirm it builds in **EAS Build**, not just locally.

package/dist/appstate.d.ts

@@ -0,0 +1 @@
+export declare function installAppState(onBackground: () => void): () => void;

package/dist/appstate.js

@@ -0,0 +1,31 @@
+export function installAppState(onBackground) {
+    let AppState;
+    try {
+        AppState = require('react-native').AppState;
+    }
+    catch {
+        return () => { };
+    }
+    if (!AppState || typeof AppState.addEventListener !== 'function')
+        return () => { };
+    const handler = (state) => {
+        if (state === 'inactive' || state === 'background') {
+            try {
+                onBackground();
+            }
+            catch {
+            }
+        }
+    };
+    const sub = AppState.addEventListener('change', handler);
+    return () => {
+        try {
+            if (sub && typeof sub.remove === 'function')
+                sub.remove();
+            else if (typeof AppState.removeEventListener === 'function')
+                AppState.removeEventListener('change', handler);
+        }
+        catch {
+        }
+    };
+}

package/dist/buffer.d.ts

@@ -0,0 +1,13 @@
+import type { ProbieEvent } from './types.js';
+export declare const MAX_BUFFER = 50;
+export declare const HARD_CAP = 200;
+export declare class RingBuffer {
+    private readonly max;
+    private readonly hardCap;
+    private items;
+    constructor(max?: number, hardCap?: number);
+    push(e: ProbieEvent): boolean;
+    drain(): ProbieEvent[];
+    peek(): ProbieEvent[];
+    get size(): number;
+}

package/dist/buffer.js

@@ -0,0 +1,27 @@
+export const MAX_BUFFER = 50;
+export const HARD_CAP = 200;
+export class RingBuffer {
+    constructor(max = MAX_BUFFER, hardCap = HARD_CAP) {
+        this.max = max;
+        this.hardCap = hardCap;
+        this.items = [];
+    }
+    push(e) {
+        this.items.push(e);
+        if (this.items.length > this.hardCap) {
+            this.items.splice(0, this.items.length - this.hardCap);
+        }
+        return this.items.length >= this.max;
+    }
+    drain() {
+        const out = this.items;
+        this.items = [];
+        return out;
+    }
+    peek() {
+        return this.items;
+    }
+    get size() {
+        return this.items.length;
+    }
+}

package/dist/capture/forms.d.ts

@@ -0,0 +1,16 @@
+import type { ElementSource } from '../types.js';
+export interface FormAbandon {
+    key: string;
+    source: ElementSource | null;
+}
+export declare class FormTracker {
+    private readonly retryWindowMs;
+    private submits;
+    private touched;
+    private submitted;
+    private sources;
+    constructor(retryWindowMs?: number);
+    touch(key: string, source?: ElementSource | null): void;
+    submit(key: string, source?: ElementSource | null): number;
+    abandons(): FormAbandon[];
+}

package/dist/capture/forms.js

@@ -0,0 +1,33 @@
+export class FormTracker {
+    constructor(retryWindowMs = 10000) {
+        this.retryWindowMs = retryWindowMs;
+        this.submits = {};
+        this.touched = new Set();
+        this.submitted = new Set();
+        this.sources = {};
+    }
+    touch(key, source = null) {
+        this.touched.add(key);
+        if (source && !this.sources[key])
+            this.sources[key] = source;
+    }
+    submit(key, source = null) {
+        this.submitted.add(key);
+        if (source && !this.sources[key])
+            this.sources[key] = source;
+        const now = Date.now();
+        const recent = (this.submits[key] ?? []).filter((t) => now - t < this.retryWindowMs);
+        recent.push(now);
+        this.submits[key] = recent;
+        return recent.length >= 2 ? recent.length : 0;
+    }
+    abandons() {
+        const out = [];
+        for (const key of this.touched) {
+            if (!this.submitted.has(key))
+                out.push({ key, source: this.sources[key] ?? null });
+        }
+        this.touched.clear();
+        return out;
+    }
+}

package/dist/capture/screen.d.ts

@@ -0,0 +1,7 @@
+export declare class ScreenTracker {
+    url: string;
+    route: string;
+    referrer: string;
+    private lastRoute;
+    change(name: string, params: Record<string, unknown> | undefined, captureQuery: boolean): boolean;
+}

package/dist/capture/screen.js

@@ -0,0 +1,30 @@
+function encodeParams(params) {
+    try {
+        return Object.keys(params)
+            .map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(String(params[k]))}`)
+            .join('&');
+    }
+    catch {
+        return '';
+    }
+}
+export class ScreenTracker {
+    constructor() {
+        this.url = '';
+        this.route = '';
+        this.referrer = '';
+        this.lastRoute = null;
+    }
+    change(name, params, captureQuery) {
+        const clean = String(name).replace(/^\/+/, '');
+        const route = '/' + clean;
+        if (this.lastRoute === route)
+            return false;
+        this.referrer = this.url;
+        this.route = route;
+        const query = captureQuery && params && Object.keys(params).length > 0 ? '?' + encodeParams(params) : '';
+        this.url = 'app://' + clean + query;
+        this.lastRoute = route;
+        return true;
+    }
+}

package/dist/capture/tap.d.ts

@@ -0,0 +1,11 @@
+export declare class RageTracker {
+    private readonly onRage;
+    private readonly windowMs;
+    private readonly threshold;
+    private lastKey;
+    private count;
+    private timer;
+    constructor(onRage: (count: number, key: string) => void, windowMs?: number, threshold?: number);
+    record(key: string): void;
+    dispose(): void;
+}

package/dist/capture/tap.js

@@ -0,0 +1,37 @@
+export class RageTracker {
+    constructor(onRage, windowMs = 1000, threshold = 3) {
+        this.onRage = onRage;
+        this.windowMs = windowMs;
+        this.threshold = threshold;
+        this.lastKey = null;
+        this.count = 0;
+        this.timer = null;
+    }
+    record(key) {
+        if (key === this.lastKey) {
+            this.count++;
+        }
+        else {
+            this.lastKey = key;
+            this.count = 1;
+        }
+        if (this.timer)
+            clearTimeout(this.timer);
+        if (this.count >= this.threshold) {
+            const firedKey = this.lastKey ?? key;
+            this.onRage(this.count, firedKey);
+            this.count = 0;
+            this.lastKey = null;
+        }
+        this.timer = setTimeout(() => {
+            this.count = 0;
+            this.lastKey = null;
+            this.timer = null;
+        }, this.windowMs);
+    }
+    dispose() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { ElementInfo, ElementSource, EventType, ProbieClient, ProbieConfig } from './types.js';
+import { type NormalizedConfig } from './config.js';
+export declare class ProbieClientImpl implements ProbieClient {
+    readonly config: NormalizedConfig;
+    private readonly sampled;
+    private readonly buffer;
+    private readonly session;
+    private readonly identity;
+    private readonly context;
+    private readonly screen;
+    private readonly rage;
+    private readonly forms;
+    private userId;
+    private flushTimer;
+    private readonly uninstallers;
+    readonly ready: Promise<void>;
+    constructor(config: ProbieConfig);
+    private init;
+    private backfill;
+    private isOwnEndpoint;
+    private emit;
+    identify(userId: string | null): void;
+    reset(): void;
+    trackScreen(name: string, params?: Record<string, unknown>): void;
+    track(type: EventType, payload?: Record<string, unknown>, element?: ElementSource | ElementInfo | null): void;
+    recordTap(element: ElementSource | ElementInfo | null): void;
+    touchForm(key: string, source?: ElementSource | null): void;
+    submitForm(key: string, source?: ElementSource | null): void;
+    private emitAbandons;
+    private onBackground;
+    flush(): Promise<void>;
+    dispose(): void;
+}

package/dist/client.js

@@ -0,0 +1,165 @@
+import { normalizeConfig } from './config.js';
+import { RingBuffer } from './buffer.js';
+import { sendEvents } from './transport.js';
+import { sanitizeUrl } from './url.js';
+import { elementInfoFrom, elementKey } from './element.js';
+import { buildDeviceContext } from './deviceContext.js';
+import { createSession } from './session.js';
+import { createIdentity } from './identity.js';
+import { installErrors } from './interceptors/errors.js';
+import { installNetwork } from './interceptors/network.js';
+import { installAppState } from './appstate.js';
+import { RageTracker } from './capture/tap.js';
+import { FormTracker } from './capture/forms.js';
+import { ScreenTracker } from './capture/screen.js';
+export class ProbieClientImpl {
+    constructor(config) {
+        this.screen = new ScreenTracker();
+        this.userId = null;
+        this.flushTimer = null;
+        this.uninstallers = [];
+        this.config = normalizeConfig(config);
+        this.sampled = Math.random() < this.config.sampleRate;
+        this.buffer = new RingBuffer();
+        this.context = buildDeviceContext(this.config.appVersion);
+        this.session = createSession(this.config.storage, this.config.idleTimeoutMs);
+        this.identity = createIdentity(this.config.storage);
+        this.rage = new RageTracker((count, key) => this.emit('rage_click', { count }, { path: key }));
+        this.forms = new FormTracker();
+        this.ready = this.init();
+    }
+    async init() {
+        if (!this.sampled)
+            return;
+        if (this.config.captureErrors) {
+            this.uninstallers.push(installErrors((type, payload) => this.emit(type, payload), this.config.captureUnhandledRejections));
+        }
+        if (this.config.captureNetwork) {
+            this.uninstallers.push(installNetwork((type, payload) => this.emit(type, payload), (url) => this.isOwnEndpoint(url), (url) => sanitizeUrl(url, this.config.captureQuery)));
+        }
+        this.uninstallers.push(installAppState(() => void this.onBackground()));
+        this.flushTimer = setInterval(() => {
+            void this.flush();
+        }, this.config.flushIntervalMs);
+        await Promise.all([this.session.ready, this.identity.ready]);
+        this.backfill();
+    }
+    backfill() {
+        const sid = this.session.getId();
+        this.context.anon_id = this.identity.getAnonId();
+        for (const e of this.buffer.peek()) {
+            e.session_id = sid;
+        }
+    }
+    isOwnEndpoint(url) {
+        return typeof url === 'string' && url.indexOf(this.config.ownPrefix) === 0;
+    }
+    emit(type, payload = {}, element) {
+        try {
+            if (!this.sampled)
+                return;
+            const el = element === undefined ? null : elementInfoFrom(element);
+            const ev = {
+                type,
+                ts: Date.now(),
+                session_id: this.session.getId(),
+                user_id: this.userId,
+                url: this.screen.url,
+                route: this.screen.route,
+                referrer: this.screen.referrer,
+                element: el,
+                payload: payload || {},
+                context: this.context,
+            };
+            const shouldFlush = this.buffer.push(ev);
+            if (shouldFlush)
+                void this.flush();
+        }
+        catch {
+        }
+    }
+    identify(userId) {
+        this.userId = userId == null ? null : String(userId);
+    }
+    reset() {
+        this.userId = null;
+        this.session.rotate();
+    }
+    trackScreen(name, params) {
+        try {
+            if (this.screen.change(name, params, this.config.captureQuery)) {
+                this.emit('pageview', {});
+            }
+        }
+        catch {
+        }
+    }
+    track(type, payload, element) {
+        if (type === 'click') {
+            this.recordTap(element ?? null);
+            return;
+        }
+        this.emit(type, payload ?? {}, element);
+    }
+    recordTap(element) {
+        this.emit('click', {}, element);
+        try {
+            this.rage.record(elementKey(element));
+        }
+        catch {
+        }
+    }
+    touchForm(key, source = null) {
+        try {
+            this.forms.touch(key, source);
+        }
+        catch {
+        }
+    }
+    submitForm(key, source = null) {
+        try {
+            const el = source ?? { path: key };
+            this.emit('form_submit', {}, el);
+            const retry = this.forms.submit(key, source);
+            if (retry >= 2)
+                this.emit('form_retry', { count: retry }, el);
+        }
+        catch {
+        }
+    }
+    emitAbandons() {
+        for (const { key, source } of this.forms.abandons()) {
+            this.emit('form_abandon', {}, source ?? { path: key });
+        }
+    }
+    async onBackground() {
+        this.emitAbandons();
+        await this.flush();
+    }
+    async flush() {
+        try {
+            await this.ready;
+            const events = this.buffer.drain();
+            if (events.length === 0)
+                return;
+            await sendEvents(this.config.endpoint, this.config.token, events, this.config.fetchImpl);
+        }
+        catch {
+        }
+    }
+    dispose() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        for (const un of this.uninstallers) {
+            try {
+                un();
+            }
+            catch {
+            }
+        }
+        this.uninstallers.length = 0;
+        this.rage.dispose();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+import type { AsyncStorageLike, ProbieConfig } from './types.js';
+export interface NormalizedConfig {
+    token: string;
+    apiBase: string;
+    endpoint: string;
+    ownPrefix: string;
+    sampleRate: number;
+    captureQuery: boolean;
+    captureErrors: boolean;
+    captureNetwork: boolean;
+    captureUnhandledRejections: boolean;
+    idleTimeoutMs: number | null;
+    flushIntervalMs: number;
+    appVersion?: string;
+    storage: AsyncStorageLike;
+    fetchImpl: (url: string, init: unknown) => Promise<unknown>;
+}
+export declare function normalizeConfig(config: ProbieConfig): NormalizedConfig;