@koderlabs/tasks-sdk-rn 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,143 @@
-# Proprietary Software
+# @koderlabs/tasks-sdk-rn
 
-KoderLabs proprietary. All rights reserved.
+> Runtime: React Native 0.72+ with Hermes or JSC. New Architecture compatible. Expo SDK 50+ recommended. **Browser DOM is not supported** — use `@koderlabs/tasks-sdk-web-errors` / `@koderlabs/tasks-sdk-web-network` instead.
 
-See the bundled `LICENSE` for terms. No grant of any rights, express or
-implied, is conferred by access to or possession of this package. A
-separate signed written licence from KoderLabs is required for any use.
+React Native client for InstantTasks. Wraps the core SDK (`@koderlabs/tasks-sdk`) with mobile-specific instrumentation:
+
+- Global JS error capture via `ErrorUtils.setGlobalHandler`.
+- Unhandled promise rejections (Hermes `enablePromiseRejectionTracker`, JSC fallback).
+- Console-as-breadcrumb capture (`console.error` / `warn`).
+- `fetch()` network breadcrumbs (no bodies — PII guard).
+- `AppState` foreground/background transitions.
+- React Navigation / Expo Router transition breadcrumbs.
+- Native-crash recovery — drains the file written by the previous launch when a native iOS NSException / Android Throwable killed the app (companion package: `@koderlabs/tasks-sdk-rn-native`).
+
+## Install
+
+```bash
+npm install @koderlabs/tasks-sdk @koderlabs/tasks-sdk-rn
+# optional native-crash capture:
+npm install @koderlabs/tasks-sdk-rn-native
+# optional Expo file system (for crash recovery):
+npm install expo-file-system
+```
+
+Using pnpm or yarn:
+
+```bash
+pnpm add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-rn
+# or
+yarn add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-rn
+```
+
+Peer: `react-native`. The Expo config plugin lives at `@koderlabs/tasks-sdk-rn-native` — register it in `app.json#plugins` for native crash capture.
+
+## Usage
+
+```ts
+// App.tsx or earliest possible bootstrap
+import { init } from '@koderlabs/tasks-sdk-rn';
+
+const handle = init({
+  projectId: 'IT-MOBILE',
+  accessKey: 'sk_live_…',
+  release: '1.4.2',
+  environment: 'production',
+  captureGlobalErrors: true,
+  captureUnhandledRejections: true,
+  captureConsole: true,
+  captureNetwork: true,
+  captureAppState: true,
+  captureNativeCrash: true,
+  maxBreadcrumbs: 50,
+  networkSlowThresholdMs: 2000,
+  networkIncludeQueryString: false,
+  onNativeCrashError: (err) => console.warn('[IT native]', err.stage, err.message),
+});
+
+// Manual capture
+handle.captureException(new Error('payment failed'), { level: 'error' });
+
+// Breadcrumbs
+handle.addBreadcrumb({ category: 'user', message: 'tapped Checkout' });
+
+// Flush before app goes to background
+await handle.flush();
+```
+
+### React Navigation integration
+
+```ts
+import { attachReactNavigation } from '@koderlabs/tasks-sdk-rn';
+import { useNavigationContainerRef } from '@react-navigation/native';
+
+const navRef = useNavigationContainerRef();
+useEffect(() => attachReactNavigation(navRef, handle.buffer), []);
+```
+
+### Expo Router
+
+```ts
+import { useExpoRouterReporter } from '@koderlabs/tasks-sdk-rn';
+
+function RootLayout() {
+  useExpoRouterReporter(handle.buffer);
+  return <Slot />;
+}
+```
+
+## `RnInitOptions`
+
+Extends `InitOptions` from `@koderlabs/tasks-sdk`. Mobile-specific additions:
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `captureGlobalErrors` | `boolean` | `true` | `ErrorUtils.setGlobalHandler`. |
+| `captureUnhandledRejections` | `boolean` | `true` | HermesInternal where available; `process.on('unhandledRejection')` fallback. |
+| `captureConsole` | `boolean` | `true` | `console.error` / `console.warn` → breadcrumbs. |
+| `captureNetwork` | `boolean` | `true` | `fetch()` breadcrumbs. Bodies **never** captured. |
+| `networkIncludeUrls` | `RegExp[]` | — | Allowlist. |
+| `networkExcludeUrls` | `RegExp[]` | — | Denylist. The ingest endpoint is always skipped. |
+| `networkSlowThresholdMs` | `number` | `2000` | Tags requests above this as `slow: true`. |
+| `networkIncludeQueryString` | `boolean` | `false` | Off by default — query strings often carry tokens / emails. |
+| `captureAppState` | `boolean` | `true` | Foreground/background breadcrumbs. |
+| `captureNativeCrash` | `boolean` | `true` | Drain previous-launch native crash file. No-op when `expo-file-system` is absent. |
+| `maxBreadcrumbs` | `number` | `50` | Ring buffer. |
+| `onNativeCrashError` | `(err) => void` | — | Surface decode/IO failures. Without this, a failed decode is indistinguishable from "no crash". |
+| `platformOverride` | `{ os?, osVersion?, deviceModel?, bundleId? }` | — | For tests where `react-native` is not loaded. |
+
+## `RnClientHandle`
+
+| Method | Purpose |
+|---|---|
+| `client` | Underlying core `Client`. |
+| `buffer` | Breadcrumb buffer (also accessible via `getBuffer()`). |
+| `captureException(err, { level? })` | Manual capture (`fatal \| error \| warning`). |
+| `addBreadcrumb({ category, message, data?, level? })` | Manual breadcrumb. |
+| `recordNavigation(to, { from?, params? })` | Manual navigation breadcrumb. |
+| `flush()` | Best-effort flush of queued events / spans. |
+| `close()` | Stop all auto-instrumentation. |
+
+Globals: `getClient()`, `getBuffer()`. Re-exports: `BreadcrumbBuffer`, `recordNavigation`, `attachReactNavigation`, `useExpoRouterReporter`, types.
+
+## Caveats
+
+- `init()` tears down any prior instrumentation before installing new wrappers — otherwise multiple wrappers stack on `console` / `fetch` / `ErrorUtils` and prior teardown functions are silently overwritten.
+- Network bodies are **never** captured (PII risk). Only method, URL (optionally query string), status, duration.
+- Native crashes require `@koderlabs/tasks-sdk-rn-native` to be installed *and* registered as an Expo plugin *and* a prebuild — Expo Go cannot load native code. The recovery path no-ops gracefully when the native side is absent.
+- `captureNativeCrash` requires `expo-file-system` for the recovery read. Without it the option silently no-ops.
+- React Navigation integration is opt-in via `attachReactNavigation` — there is no auto-attach.
+- `flush()` covers spans; errors are POSTed inline so there's nothing extra to drain on the error path.
+- Phase 2b will add an in-app reporter (screenshot + annotate) for RN. Until then, in-app reporting is web-only via `@koderlabs/tasks-sdk-web-reporter`.
+
+---
+
+## Suite overview
+
+Full SDK suite map + platform availability matrix: [docs/sdk/overview.md](https://github.com/jawaidgadiwala/instant-tasks/blob/main/docs/sdk/overview.md).
+
+## License
+
+KoderLabs proprietary. See [`LICENSE`](./LICENSE) for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.
 
 Licensing inquiries: jawaidgadiwala@gmail.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koderlabs/tasks-sdk-rn",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React Native adapter for the InstantTasks SDK — errors + network + breadcrumbs + navigation + native crash recovery.",
   "keywords": [
     "instanttasks",
@@ -45,8 +45,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@koderlabs/tasks-sdk": "0.1.0",
-    "@koderlabs/tasks-sdk-types": "0.1.0"
+    "@koderlabs/tasks-sdk": "0.1.2",
+    "@koderlabs/tasks-sdk-types": "0.1.2"
   },
   "peerDependencies": {
     "react-native": ">=0.72.0",
@@ -70,7 +70,7 @@
     "node": ">=20"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "app.plugin.js": "./plugin/dist/index.cjs",
   "scripts": {