@catdoes/watch 1.3.0 → 2.0.0

package/README.md

@@ -1,182 +1,180 @@
 # @catdoes/watch
 
-Error tracking and monitoring SDK for React Native and Expo apps.
+CatDoes Watch reports errors from Expo apps to the Watch dashboard. Version 2 captures React errors, global JavaScript errors, and unhandled promise rejections. It writes each event to local storage before attempting a network request, so a native crash can be sent after the app starts again.
 
-**CatDoes Watch** provides real-time error tracking, crash reporting, and debugging tools for your mobile applications built with React Native and Expo.
+## Requirements
 
-## Features
+Version 2 supports Expo 57 or newer, React Native 0.86 or newer, and React 19.2 or newer. Expo 54 projects must use `@catdoes/watch@1.3.0`.
 
-- **Automatic Error Capture** - Catches unhandled errors and promise rejections
-- **React Error Boundary** - Integrated error boundary component
-- **Breadcrumbs** - Track user actions leading up to errors
-- **Cross-Platform** - Works on iOS, Android, and Web
-- **Offline Support** - Queues events when offline, sends when reconnected
-- **Lightweight** - Minimal impact on app performance
-
-## Installation
+## Install
 
 ```bash
-npm install @catdoes/watch
-# or
-yarn add @catdoes/watch
+npx expo install @catdoes/watch expo-constants expo-device
 ```
 
-### Optional Integrations
-
-The SDK has no hard dependencies beyond React / React Native:
-
-- **Offline queue persistence** — pass an AsyncStorage-compatible object via the `storage` option (see below). Without it, queued events are kept in memory only.
-- **Device metadata** (model, OS build, app version, locale) — enriched automatically when the app uses Expo and has `expo-device` / `expo-constants` / `expo-localization` installed. Read from Expo's native module registry at runtime; never imported by the SDK.
+Expo installs `expo-file-system` and `expo-modules-core`. Install `expo-router` when the app uses the router integration.
 
-## Quick Start
+## Quick start
 
-### 1. Initialize the SDK
+Initialize Watch before the root layout renders:
 
-In your app's entry point (e.g., `_layout.tsx` for Expo Router):
-
-```typescript
-import AsyncStorage from "@react-native-async-storage/async-storage";
-import { Watch, setupGlobalHandlers } from "@catdoes/watch";
+```ts
+import { Watch } from "@catdoes/watch";
 
-// Initialize Watch with your API key
-const watchClient = Watch.init({
-  apiKey: process.env.EXPO_PUBLIC_CATDOES_WATCH_KEY || "",
-  debug: __DEV__, // Enable debug logging in development
-  storage: AsyncStorage, // Optional: persist the event queue across launches
+Watch.init({
+  apiKey: process.env.EXPO_PUBLIC_CATDOES_WATCH_KEY ?? "",
+  debug: __DEV__,
 });
-
-// Set up global error handlers
-if (watchClient) {
-  setupGlobalHandlers(watchClient);
-}
 ```
 
-### 2. Wrap Your App with Error Boundary
+Global handlers, queue persistence, session IDs, and device context are automatic. An empty API key disables capture and installs no hooks.
+
+## React error boundary
+
+`WatchErrorBoundary` catches errors thrown while React renders its descendants:
 
 ```tsx
-import { ErrorBoundary } from "@/components/ErrorBoundary";
+import { WatchErrorBoundary } from "@catdoes/watch/react";
 
-export default function RootLayout() {
+export function AppBoundary({ children }: { children: React.ReactNode }) {
   return (
-    <ErrorBoundary>
-      {/* Your app content */}
-    </ErrorBoundary>
+    <WatchErrorBoundary
+      fallback={({ error, resetError }) => (
+        <ErrorScreen message={error.message} onRetry={resetError} />
+      )}
+    >
+      {children}
+    </WatchErrorBoundary>
   );
 }
 ```
 
-### 3. Capture Errors Manually (Optional)
+The fallback also receives React's `errorInfo`, including its component stack.
 
-```typescript
-import { Watch } from "@catdoes/watch";
-
-try {
-  await riskyOperation();
-} catch (error) {
-  Watch.captureError(error as Error, {
-    context: "riskyOperation",
-    userId: currentUser.id,
-  });
-}
-```
-
-## API Reference
+## Expo Router
 
-### `Watch.init(config)`
+Mount `WatchNavigation` once inside the root layout. It records path changes as breadcrumbs and adds the current route to event context.
 
-Initializes the Watch client.
+```tsx
+import { WatchNavigation } from "@catdoes/watch/expo-router";
 
-```typescript
-interface WatchConfig {
-  apiKey: string;                    // Your CatDoes Watch API key
-  endpoint?: string;                 // Custom endpoint (default: CatDoes servers)
-  environment?: "development" | "production";
-  captureConsoleErrors?: boolean;    // Capture console.error (default: false)
-  maxBreadcrumbs?: number;           // Max breadcrumbs to store (default: 20)
-  debug?: boolean;                   // Enable debug logging
-  beforeSend?: (event) => event | null; // Modify or drop events
+export default function RootLayout() {
+  return (
+    <Providers>
+      <WatchNavigation />
+      <Stack />
+    </Providers>
+  );
 }
 ```
 
-### `Watch.captureError(error, extra?)`
+A route can use the built-in boundary:
 
-Manually capture an error.
-
-```typescript
-Watch.captureError(new Error("Something went wrong"), {
-  userId: "123",
-  action: "checkout",
-});
-```
-
-### `Watch.captureMessage(message, level?)`
-
-Capture a message as an error.
-
-```typescript
-Watch.captureMessage("User attempted invalid action", "warning");
+```ts
+export {
+  WatchRouteErrorBoundary as ErrorBoundary,
+} from "@catdoes/watch/expo-router";
 ```
 
-### `Watch.addBreadcrumb(breadcrumb)`
+Use the app's own fallback without duplicating capture:
 
-Add a breadcrumb for context.
+```tsx
+import { createRouteErrorBoundary } from "@catdoes/watch/expo-router";
 
-```typescript
-Watch.addBreadcrumb({
-  type: "navigation",
-  message: "User navigated to Settings",
-  data: { screen: "Settings" },
-});
+export const ErrorBoundary = createRouteErrorBoundary(RouteErrorFallback);
 ```
 
-### `Watch.setContext(key, value)`
+The fallback receives `{ error, retry }`, matching Expo Router's boundary contract.
 
-Set context that will be attached to all future events.
+## Manual API
 
-```typescript
-Watch.setContext("appVersion", "1.2.3");
-```
+```ts
+Watch.captureError(error, { operation: "save" });
+Watch.captureMessage("Import took too long", "warning");
 
-### `Watch.setUser(user)`
-
-Set user information for error correlation.
-
-```typescript
-Watch.setUser({
-  id: "user123",
-  email: "user@example.com",
+Watch.addBreadcrumb({
+  type: "ui",
+  message: "Pressed save",
+  data: { screen: "editor" },
 });
-```
-
-### `Watch.flush()`
 
-Force flush all queued events to the server.
+Watch.setContext("document", { id: "doc_123" });
+Watch.clearContext("document");
+Watch.setUser({ id: "user_123" });
 
-```typescript
 await Watch.flush();
+const stats = Watch.getStats();
 ```
 
-## Breadcrumb Types
-
-- `navigation` - Route/screen changes
-- `ui` - User interactions (taps, swipes)
-- `http` - Network requests
-- `console` - Console logs
-- `custom` - Custom events
-
-## Environment Variables
+`captureError` accepts any thrown value. Strings and error-like objects become `Error` instances without losing their supplied message, name, or stack.
+
+`flush()` sends batches until the queue is empty or a batch fails. Retryable failures leave events queued and schedule the next attempt. Authentication failures disable the transport.
+
+## Configuration
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `apiKey` | Required | Watch project key. An empty string disables the SDK. |
+| `endpoint` | `https://app.catdoes.com/api/watch/ingest` | Ingestion endpoint. |
+| `environment` | `development` when `__DEV__`, otherwise `production` | Event environment. |
+| `debug` | `false` | Writes SDK diagnostics to the console. |
+| `installGlobalHandlers` | `true` | Installs native or browser global error hooks. |
+| `captureConsoleErrors` | `false` | Reports eligible `console.error` calls. |
+| `captureHttpBreadcrumbs` | `false` | Wraps `fetch` and records request outcomes. Queries are removed. |
+| `maxBreadcrumbs` | `20` | Number of recent breadcrumbs attached to an event. |
+| `maxBufferSize` | `10` | Events sent in one request. |
+| `flushInterval` | `5000` | Delay before an automatic flush, in milliseconds. |
+| `fatalFlushTimeoutMs` | `2000` | Maximum production wait before handing a native fatal to React Native. Use `0` for no wait. |
+| `beforeSend` | Identity function | Changes an event or returns `null` to drop it. |
+| `initialContext` | `{}` | Context copied into every event. |
+| `dedupWindowMs` | `5000` | Time in which matching errors count as duplicates. |
+| `dedupMaxEntries` | `500` | Maximum recent deduplication keys in memory. |
+| `storage` | Platform default | Synchronous `QueueStore` replacement for persistence. |
+
+## Automatic capture
+
+| Source | Native | Web |
+| --- | --- | --- |
+| React error boundary | Yes | Yes |
+| Expo Router error boundary | Yes | Yes |
+| Global JavaScript errors | Yes | Yes |
+| Unhandled promise rejections | Yes, in development and release | Yes |
+| Fatal render errors outside a boundary | Yes | Browser global error event |
+| `console.error` | Opt in | Opt in |
+| HTTP breadcrumbs | Opt in | Opt in |
+
+On native production builds, Watch persists a fatal event synchronously, tries to flush for at most `fatalFlushTimeoutMs`, then calls React Native's original fatal handler. The app still crashes as React Native intended. If the request does not finish, Watch sends the stored event on the next launch.
+
+## Persistence
+
+Native apps store up to 100 events and 512 KB in Expo's cache directory. Web apps use `localStorage`. The oldest events leave the queue first when either limit is reached. Watch removes an event only after a successful response.
+
+Watch writes the first queue change immediately, then combines writes made within the next 500 milliseconds. Fatal errors and app lifecycle handoffs force an immediate write before flushing.
+
+You can provide a synchronous store:
+
+```ts
+import type { QueueStore } from "@catdoes/watch";
+
+const store: QueueStore = {
+  read: () => null,
+  write: (value) => saveImmediately(value),
+  remove: () => removeImmediately(),
+};
+```
 
-Set your API key in your environment:
+## Privacy
 
-```env
-EXPO_PUBLIC_CATDOES_WATCH_KEY=your_api_key_here
-```
+Device context may include hardware model, OS and build identifiers, app metadata, screen dimensions, locale, timezone, JavaScript engine, and the web browser user agent. It does not collect network addresses or AsyncStorage contents. Use `beforeSend` to remove application context your product should not transmit.
 
-## Support
+## Migrating from 1.x
 
-- Documentation: https://catdoes.watch/docs
-- Support: support@catdoes.com
+- Remove the AsyncStorage import and the `storage: AsyncStorage` option unless you provide a custom synchronous `QueueStore`.
+- Remove manual `setupGlobalHandlers(client)` calls. `Watch.init` now installs handlers. Set `installGlobalHandlers: false` only when another integration owns them.
+- Replace `setupConsoleErrorCapture` with `captureConsoleErrors: true`.
+- Replace `getCachedDeviceInfo()` with `getDeviceInfo()`.
+- Expect the old 1.x AsyncStorage queue to be left behind. Watch does not import AsyncStorage to migrate it.
 
 ## License
 
-Proprietary - All rights reserved by CatDoes.
+MIT

package/dist/expo-router.d.mts

@@ -0,0 +1,15 @@
+import { ErrorBoundaryProps } from 'expo-router';
+import React from 'react';
+
+declare function useWatchNavigation(): void;
+declare function WatchNavigation(): null;
+type WatchRouteFallbackProps = {
+    error: Error;
+    retry: () => Promise<void>;
+};
+declare function createRouteErrorBoundary(Fallback: React.ComponentType<WatchRouteFallbackProps>, options?: {
+    captureErrors?: boolean;
+}): React.ComponentType<ErrorBoundaryProps>;
+declare const WatchRouteErrorBoundary: React.ComponentType<ErrorBoundaryProps>;
+
+export { WatchNavigation, WatchRouteErrorBoundary, type WatchRouteFallbackProps, createRouteErrorBoundary, useWatchNavigation };

package/dist/expo-router.d.ts

@@ -0,0 +1,15 @@
+import { ErrorBoundaryProps } from 'expo-router';
+import React from 'react';
+
+declare function useWatchNavigation(): void;
+declare function WatchNavigation(): null;
+type WatchRouteFallbackProps = {
+    error: Error;
+    retry: () => Promise<void>;
+};
+declare function createRouteErrorBoundary(Fallback: React.ComponentType<WatchRouteFallbackProps>, options?: {
+    captureErrors?: boolean;
+}): React.ComponentType<ErrorBoundaryProps>;
+declare const WatchRouteErrorBoundary: React.ComponentType<ErrorBoundaryProps>;
+
+export { WatchNavigation, WatchRouteErrorBoundary, type WatchRouteFallbackProps, createRouteErrorBoundary, useWatchNavigation };

package/dist/expo-router.js

@@ -0,0 +1 @@
+"use strict";var e=require("expo-router"),t=require("react"),r=require("react-native"),n=require("react/jsx-runtime"),o=Symbol.for("@catdoes/watch/runtime-state-v2");function i(){const e=globalThis;return e[o]||(e[o]={capturedErrors:new WeakSet,handoffDepth:0,activeClient:null,clientInstance:null}),e[o]}function c(){return i().activeClient}function l(){const r=e.usePathname(),n=`/${e.useSegments().join("/")}`,o=t.useRef(null);t.useEffect(()=>{const e=o.current;if(e===r)return;const t=c();t?.addBreadcrumb({type:"navigation",message:null===e?`Initial route ${r}`:`${e} → ${r}`,data:{from:e,to:r,pattern:n,initial:null===e}}),t?.setContext("route",{pathname:r,pattern:n}),o.current=r},[r,n])}function u(r,o){const l=({error:l,retry:u})=>{const a=e.usePathname();return t.useEffect(()=>{!1===o?.captureErrors||function(e){return("object"==typeof e&&null!==e||"function"==typeof e)&&i().capturedErrors.has(e)}(l)||c()?.captureError(l,{source:"expo-router.ErrorBoundary",route:a})},[l]),n.jsx(r,{error:l,retry:u})};return l.displayName=`WatchRouteErrorBoundary(${r.displayName??r.name??"Fallback"})`,l}var a=u(function({error:e,retry:t}){return n.jsxs(r.View,{style:s.container,children:[n.jsx(r.View,{style:s.icon,children:n.jsx(r.Text,{style:s.iconText,children:"!"})}),n.jsx(r.Text,{style:s.title,children:"Something went wrong"}),n.jsx(r.Text,{style:s.message,children:e.message||"An unexpected error occurred."}),n.jsx(r.Pressable,{accessibilityRole:"button",onPress:()=>{t()},style:({pressed:e})=>[s.button,e&&s.buttonPressed],children:n.jsx(r.Text,{style:s.buttonText,children:"Try again"})})]})}),s=r.StyleSheet.create({container:{flex:1,alignItems:"center",justifyContent:"center",padding:24,backgroundColor:"#ffffff"},icon:{width:48,height:48,borderRadius:24,alignItems:"center",justifyContent:"center",backgroundColor:"#fee2e2",marginBottom:16},iconText:{color:"#b91c1c",fontSize:28,fontWeight:"700"},title:{color:"#111827",fontSize:22,fontWeight:"700"},message:{color:"#6b7280",fontSize:15,lineHeight:22,textAlign:"center",marginTop:8},button:{minHeight:44,justifyContent:"center",borderRadius:12,backgroundColor:"#111827",paddingHorizontal:20,marginTop:24},buttonPressed:{transform:[{scale:.97}],opacity:.9},buttonText:{color:"#ffffff",fontSize:15,fontWeight:"600"}});exports.WatchNavigation=function(){return l(),null},exports.WatchRouteErrorBoundary=a,exports.createRouteErrorBoundary=u,exports.useWatchNavigation=l;

package/dist/expo-router.mjs

@@ -0,0 +1 @@
+import{usePathname as t,useSegments as e}from"expo-router";import{useRef as r,useEffect as n}from"react";import{StyleSheet as o,View as i,Text as c,Pressable as l}from"react-native";import{jsx as a,jsxs as u}from"react/jsx-runtime";var f=Symbol.for("@catdoes/watch/runtime-state-v2");function s(){const t=globalThis;return t[f]||(t[f]={capturedErrors:new WeakSet,handoffDepth:0,activeClient:null,clientInstance:null}),t[f]}function d(){return s().activeClient}function g(){const o=t(),i=`/${e().join("/")}`,c=r(null);n(()=>{const t=c.current;if(t===o)return;const e=d();e?.addBreadcrumb({type:"navigation",message:null===t?`Initial route ${o}`:`${t} → ${o}`,data:{from:t,to:o,pattern:i,initial:null===t}}),e?.setContext("route",{pathname:o,pattern:i}),c.current=o},[o,i])}function m(){return g(),null}function h(e,r){const o=({error:o,retry:i})=>{const c=t();return n(()=>{!1===r?.captureErrors||function(t){return("object"==typeof t&&null!==t||"function"==typeof t)&&s().capturedErrors.has(t)}(o)||d()?.captureError(o,{source:"expo-router.ErrorBoundary",route:c})},[o]),a(e,{error:o,retry:i})};return o.displayName=`WatchRouteErrorBoundary(${e.displayName??e.name??"Fallback"})`,o}var p=h(function({error:t,retry:e}){return u(i,{style:y.container,children:[a(i,{style:y.icon,children:a(c,{style:y.iconText,children:"!"})}),a(c,{style:y.title,children:"Something went wrong"}),a(c,{style:y.message,children:t.message||"An unexpected error occurred."}),a(l,{accessibilityRole:"button",onPress:()=>{e()},style:({pressed:t})=>[y.button,t&&y.buttonPressed],children:a(c,{style:y.buttonText,children:"Try again"})})]})}),y=o.create({container:{flex:1,alignItems:"center",justifyContent:"center",padding:24,backgroundColor:"#ffffff"},icon:{width:48,height:48,borderRadius:24,alignItems:"center",justifyContent:"center",backgroundColor:"#fee2e2",marginBottom:16},iconText:{color:"#b91c1c",fontSize:28,fontWeight:"700"},title:{color:"#111827",fontSize:22,fontWeight:"700"},message:{color:"#6b7280",fontSize:15,lineHeight:22,textAlign:"center",marginTop:8},button:{minHeight:44,justifyContent:"center",borderRadius:12,backgroundColor:"#111827",paddingHorizontal:20,marginTop:24},buttonPressed:{transform:[{scale:.97}],opacity:.9},buttonText:{color:"#ffffff",fontSize:15,fontWeight:"600"}});export{m as WatchNavigation,p as WatchRouteErrorBoundary,h as createRouteErrorBoundary,g as useWatchNavigation};