@fixprompt/react-native 0.0.1

package/README.md

@@ -0,0 +1,119 @@
+# @fixprompt/react-native
+
+React Native SDK for the [FixPrompt](https://github.com/Geos-LLC/FixPrompt) broker. Captures uncaught JS errors, unhandled promise rejections, and tagged `console.error` / `console.warn` output. Buffers events when offline; drains on the next successful send.
+
+## Install
+
+```bash
+npm install github:Geos-LLC/FixPrompt#path:react-native-sdk \
+            @react-native-async-storage/async-storage
+```
+
+Optional but recommended for stable per-device IDs:
+
+```bash
+npx expo install expo-secure-store
+```
+
+## Wire it up
+
+```ts
+// App.tsx — call once before any render
+import { initFixPrompt } from '@fixprompt/react-native';
+
+initFixPrompt({
+  projectKey: process.env.EXPO_PUBLIC_FIXPROMPT_KEY!,
+  source:     process.env.EXPO_PUBLIC_FIXPROMPT_SOURCE!,
+  service: 'my-app',
+  app:     'my-app',
+  env: __DEV__ ? 'dev' : 'prod',
+
+  // Optional — empty list (the default) captures every console.error;
+  // pass regex prefixes to only capture intentional tagged lines.
+  captureTags: [/^\[CRM\b/, /^\[Analytics\b/],
+});
+```
+
+## Public API
+
+```ts
+// Manual error report — call from a try/catch
+captureException(err, { attrs: { extra: 'context' } });
+
+// Attach user context to every subsequent event
+setUser({ id: userId, email });
+setUser(null); // clear on logout
+```
+
+## Native crash forwarding (optional)
+
+The SDK only sees the JS bridge. If a native module deref crashes the app
+(common: native-side TurboModule null pointer), wire up
+`react-native-exception-handler`:
+
+```bash
+npm install react-native-exception-handler
+```
+
+```ts
+import { setNativeExceptionHandler } from 'react-native-exception-handler';
+import { captureException } from '@fixprompt/react-native';
+
+setNativeExceptionHandler((exceptionString) => {
+  // Synchronous — runs once before the app process dies.
+  // Best we can do is push to the offline buffer; transport will flush on
+  // next app launch via AsyncStorage replay.
+  captureException(new Error(exceptionString), {
+    attrs: { kind: 'native_crash', fatal: true },
+  });
+});
+```
+
+## Offline buffer
+
+When the broker is unreachable (network down, 5xx, or 8s timeout), events
+queue in an in-memory ring buffer of 200, persisted to `AsyncStorage` key
+`@fixprompt/buffer`. On the next successful send the whole queue drains in
+order. Events older than 7 days are dropped. 4xx responses are dropped
+immediately (those are bugs on our side, not transient failures).
+
+## Auto-attached attrs
+
+Every event ships with:
+
+| attr | source |
+|------|--------|
+| `sdk`, `sdk_version` | this package |
+| `platform` | `Platform.OS` (ios / android / web / ...) |
+| `os_version` | `Platform.Version` |
+| `rn_version` | `Platform.constants.reactNativeVersion` |
+| `release` | passed to `initFixPrompt({ release })` or `null` |
+| `session_id` | uuid per cold start, in-memory |
+| `device_id` | uuid per device, persisted (SecureStore → AsyncStorage) |
+| `user_id`, `user_email` | last `setUser({...})` call |
+
+The broker promotes `sdk` + `sdk_version` into `project_sdk_installations`, so the dashboard's support copy ("you're on RN SDK 0.0.1") lights up automatically.
+
+## Tag-based capture (advanced)
+
+The `captureTags` option mirrors the pattern from the original ProofPix `errorLogger.js`. When set, only `console.error` / `console.warn` lines whose first argument matches one of the regexes get forwarded:
+
+```ts
+initFixPrompt({
+  // ...
+  captureTags: [
+    /^\[Auth\b/,
+    /^\[Sync\b/,
+    /^\[CRM\b/,
+  ],
+});
+
+console.error('[Auth] refresh token expired');  // → broker
+console.error('plain message, untagged');       // → original console only
+```
+
+Leave `captureTags` unset to capture every console.error (broader, noisier).
+
+## License
+
+UNLICENSED (closed beta).

package/dist/__mocks__/async-storage.d.ts

@@ -0,0 +1,9 @@
+declare const AsyncStorage: {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /** Tests only. */
+    __reset(): void;
+};
+export default AsyncStorage;

package/dist/__mocks__/react-native.d.ts

@@ -0,0 +1,11 @@
+export declare const Platform: {
+    OS: string;
+    Version: string;
+    constants: {
+        reactNativeVersion: {
+            major: number;
+            minor: number;
+            patch: number;
+        };
+    };
+};

package/dist/buffer.d.ts

@@ -0,0 +1,23 @@
+import type { EventPayload } from './types';
+/**
+ * In-memory ring buffer with AsyncStorage persistence.
+ *
+ * Events accumulate when the broker is unreachable (network error / 5xx /
+ * timeout). On the next successful send, the whole buffer drains in order.
+ * On cold start, any persisted buffer from a prior crash is replayed.
+ */
+declare class OfflineBuffer {
+    private items;
+    private loaded;
+    private persistTimer;
+    /** Load the persisted buffer once, on first use. */
+    load(): Promise<void>;
+    push(payload: EventPayload): void;
+    drain(): Promise<EventPayload[]>;
+    size(): number;
+    private schedulePersist;
+    /** Tests only. */
+    _resetForTests(): void;
+}
+export declare const offlineBuffer: OfflineBuffer;
+export {};

package/dist/console.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedConfig } from './types';
+/**
+ * Wrap console.error so tagged calls forward to the broker as warning-severity
+ * events. The original console.error still runs (so RedBox / Metro logs still
+ * show up).
+ *
+ * Pattern is intentional — ProofPix's existing log lines look like
+ * `console.error('[Analytics] tracking failure', err)`. Devs prefix their
+ * intentional captures and the broker only sees tagged ones.
+ */
+export declare function patchConsoleError(config: ResolvedConfig): () => void;
+export declare function patchConsoleWarn(config: ResolvedConfig): () => void;

package/dist/device.d.ts

@@ -0,0 +1,7 @@
+export interface DeviceAttrs {
+    platform: string;
+    os_version: string;
+    /** RN runtime version (Hermes / JSC). Used for triage. */
+    rn_version?: string;
+}
+export declare function getDeviceAttrs(): DeviceAttrs;

package/dist/handlers.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedConfig } from './types';
+export declare function installGlobalErrorHandler(config: ResolvedConfig): () => void;
+/**
+ * Hook unhandled-promise-rejection tracking. Uses the bundled
+ * `promise/setimmediate/rejection-tracking` module that ships with RN.
+ */
+export declare function installRejectionHandler(config: ResolvedConfig): () => void;