@catdoes/watch 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# @catdoes/watch
+
+Error tracking and monitoring SDK for React Native and Expo apps.
+
+**CatDoes Watch** provides real-time error tracking, crash reporting, and debugging tools for your mobile applications built with React Native and Expo.
+
+## Features
+
+- 🚨 **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
+
+```bash
+npm install @catdoes/watch
+# or
+yarn add @catdoes/watch
+```
+
+### Peer Dependencies
+
+Make sure you have these peer dependencies installed:
+
+```bash
+npx expo install @react-native-async-storage/async-storage expo-crypto
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+
+In your app's entry point (e.g., `_layout.tsx` for Expo Router):
+
+```typescript
+import { Watch, setupGlobalHandlers } 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
+});
+
+// Set up global error handlers
+if (watchClient) {
+  setupGlobalHandlers(watchClient);
+}
+```
+
+### 2. Wrap Your App with Error Boundary
+
+```tsx
+import { ErrorBoundary } from "@/components/ErrorBoundary";
+
+export default function RootLayout() {
+  return (
+    <ErrorBoundary>
+      {/* Your app content */}
+    </ErrorBoundary>
+  );
+}
+```
+
+### 3. Capture Errors Manually (Optional)
+
+```typescript
+import { Watch } from "@catdoes/watch";
+
+try {
+  await riskyOperation();
+} catch (error) {
+  Watch.captureError(error as Error, {
+    context: "riskyOperation",
+    userId: currentUser.id,
+  });
+}
+```
+
+## API Reference
+
+### `Watch.init(config)`
+
+Initializes the Watch client.
+
+```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
+}
+```
+
+### `Watch.captureError(error, extra?)`
+
+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");
+```
+
+### `Watch.addBreadcrumb(breadcrumb)`
+
+Add a breadcrumb for context.
+
+```typescript
+Watch.addBreadcrumb({
+  type: "navigation",
+  message: "User navigated to Settings",
+  data: { screen: "Settings" },
+});
+```
+
+### `Watch.setContext(key, value)`
+
+Set context that will be attached to all future events.
+
+```typescript
+Watch.setContext("appVersion", "1.2.3");
+```
+
+### `Watch.setUser(user)`
+
+Set user information for error correlation.
+
+```typescript
+Watch.setUser({
+  id: "user123",
+  email: "user@example.com",
+});
+```
+
+### `Watch.flush()`
+
+Force flush all queued events to the server.
+
+```typescript
+await Watch.flush();
+```
+
+## Breadcrumb Types
+
+- `navigation` - Route/screen changes
+- `ui` - User interactions (taps, swipes)
+- `http` - Network requests
+- `console` - Console logs
+- `custom` - Custom events
+
+## Environment Variables
+
+Set your API key in your environment:
+
+```env
+EXPO_PUBLIC_CATDOES_WATCH_KEY=your_api_key_here
+```
+
+## Support
+
+- Documentation: https://catdoes.watch/docs
+- Support: support@catdoes.com
+
+## License
+
+Proprietary - All rights reserved by CatDoes.

package/dist/index.d.mts

@@ -0,0 +1,486 @@
+export { WatchErrorBoundary, WatchErrorBoundaryProps, withWatchErrorBoundary } from './react.mjs';
+import 'react';
+
+/**
+ * CatDoes Watch SDK - Type Definitions
+ *
+ * These types define the structure of error events, configuration,
+ * and other data used by the Watch SDK.
+ */
+/**
+ * Configuration options for initializing the Watch client.
+ */
+interface WatchConfig {
+    /**
+     * The API key for authenticating with CatDoes Watch.
+     * Format: cd_watch_xxxxx
+     */
+    apiKey: string;
+    /**
+     * The endpoint URL for the ingestion API.
+     * @default "https://app.catdoes.com/api/watch/ingest"
+     */
+    endpoint?: string;
+    /**
+     * The environment to report errors for.
+     * Auto-detected from __DEV__ if not specified.
+     * @default Auto-detected
+     */
+    environment?: "development" | "production";
+    /**
+     * Whether to capture console.error calls as errors.
+     * This can be noisy and is disabled by default.
+     * @default false
+     */
+    captureConsoleErrors?: boolean;
+    /**
+     * Maximum number of breadcrumbs to store.
+     * @default 20
+     */
+    maxBreadcrumbs?: number;
+    /**
+     * Maximum number of events to buffer before flushing.
+     * @default 10
+     */
+    maxBufferSize?: number;
+    /**
+     * Interval in milliseconds between automatic flushes.
+     * @default 5000
+     */
+    flushInterval?: number;
+    /**
+     * Callback invoked before sending an event.
+     * Return null to drop the event, or modify and return it.
+     */
+    beforeSend?: (event: WatchEvent) => WatchEvent | null;
+    /**
+     * Enable debug logging to console.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Initial context to attach to all events.
+     */
+    initialContext?: Record<string, unknown>;
+    /**
+     * Time window in milliseconds to consider errors as duplicates.
+     * Errors with the same key occurring within this window will be deduplicated.
+     * @default 5000
+     */
+    dedupWindowMs?: number;
+    /**
+     * Maximum number of recent error keys to keep in memory for deduplication.
+     * When exceeded, the oldest keys will be evicted.
+     * @default 500
+     */
+    dedupMaxEntries?: number;
+}
+/**
+ * Required configuration with defaults applied.
+ */
+interface WatchConfigResolved {
+    apiKey: string;
+    endpoint: string;
+    environment: "development" | "production";
+    captureConsoleErrors: boolean;
+    maxBreadcrumbs: number;
+    maxBufferSize: number;
+    flushInterval: number;
+    beforeSend: (event: WatchEvent) => WatchEvent | null;
+    debug: boolean;
+    dedupWindowMs: number;
+    dedupMaxEntries: number;
+}
+/**
+ * Device and environment information collected automatically.
+ */
+interface DeviceInfo {
+    deviceModel?: string;
+    deviceName?: string;
+    deviceType?: string;
+    brand?: string;
+    manufacturer?: string;
+    modelName?: string;
+    isDevice?: boolean;
+    isEmulator?: boolean;
+    isTablet?: boolean;
+    osName?: string;
+    osVersion?: string;
+    osBuildId?: string;
+    platformApiLevel?: number;
+    appVersion?: string;
+    appBuildNumber?: string;
+    appName?: string;
+    bundleId?: string;
+    runtimeVersion?: string;
+    expoVersion?: string;
+    nativeAppVersion?: string;
+    nativeBuildVersion?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    screenScale?: number;
+    locale?: string;
+    timezone?: string;
+    networkType?: string;
+    isConnected?: boolean;
+    browserName?: string;
+    browserVersion?: string;
+    userAgent?: string;
+}
+/**
+ * A breadcrumb representing an action or event before an error.
+ */
+interface Breadcrumb {
+    /**
+     * The type of breadcrumb.
+     */
+    type: "navigation" | "ui" | "http" | "console" | "custom";
+    /**
+     * A human-readable message describing the breadcrumb.
+     */
+    message: string;
+    /**
+     * ISO 8601 timestamp of when the breadcrumb was created.
+     */
+    timestamp: string;
+    /**
+     * Additional data associated with the breadcrumb.
+     */
+    data?: Record<string, unknown>;
+}
+/**
+ * An error event to be sent to CatDoes Watch.
+ */
+interface WatchEvent {
+    /**
+     * The error message.
+     */
+    message: string;
+    /**
+     * The stack trace of the error.
+     */
+    stack?: string;
+    /**
+     * React component stack trace.
+     */
+    componentStack?: string;
+    /**
+     * The filename where the error occurred.
+     */
+    filename?: string;
+    /**
+     * The line number where the error occurred.
+     */
+    lineno?: number;
+    /**
+     * The column number where the error occurred.
+     */
+    colno?: number;
+    /**
+     * ISO 8601 timestamp of when the error occurred.
+     */
+    timestamp: string;
+    /**
+     * The environment where the error occurred.
+     */
+    environment: "development" | "production";
+    /**
+     * The platform where the error occurred.
+     */
+    platform: "ios" | "android" | "web";
+    /**
+     * A unique identifier for the current session.
+     */
+    sessionId: string;
+    /**
+     * Device and environment information.
+     */
+    deviceInfo?: DeviceInfo;
+    /**
+     * Additional context data.
+     */
+    extra?: Record<string, unknown>;
+    /**
+     * Breadcrumbs leading up to the error.
+     */
+    breadcrumbs?: Breadcrumb[];
+    /**
+     * SDK version for debugging. Helps correlate reports across SDK releases.
+     */
+    sdkVersion?: string;
+}
+/**
+ * Input for adding a breadcrumb (timestamp is auto-generated).
+ */
+type BreadcrumbInput = Omit<Breadcrumb, "timestamp">;
+/**
+ * Response from the ingestion API.
+ */
+interface IngestResponse {
+    accepted?: number;
+    filtered?: boolean;
+    error?: string;
+    retryAfter?: number;
+}
+
+/**
+ * CatDoes Watch SDK - Transport Layer
+ *
+ * Handles HTTP communication with the CatDoes Watch ingestion API.
+ * Features:
+ * - Batching: Groups multiple events into single requests
+ * - Retry with exponential backoff on failures
+ * - Respects rate limiting (429 responses)
+ * - Silent failures (never throws to avoid breaking the app)
+ */
+
+interface FlushOptions {
+    /**
+     * Hint browsers to allow the request to outlive the page lifecycle.
+     */
+    keepalive?: boolean;
+}
+
+/**
+ * CatDoes Watch SDK - Main Client
+ *
+ * The primary interface for the CatDoes Watch error tracking SDK.
+ * Implements a singleton pattern for ease of use.
+ */
+
+/**
+ * The main CatDoes Watch client class.
+ */
+declare class WatchClient {
+    private static instance;
+    private config;
+    private transport;
+    private breadcrumbs;
+    private context;
+    private user;
+    private isInitialized;
+    private recentErrors;
+    private recentErrorsCleanupTimer;
+    private constructor();
+    /**
+     * Initializes the Watch client with the given configuration.
+     */
+    static init(config: WatchConfig): WatchClient;
+    /**
+     * Gets the existing Watch client instance, or null if not initialized.
+     */
+    static getInstance(): WatchClient | null;
+    /**
+     * Captures an error and sends it to CatDoes Watch.
+     */
+    captureError(error: Error, extra?: Record<string, unknown>): void;
+    /**
+     * Captures a message as an error.
+     */
+    captureMessage(message: string, level?: "info" | "warning" | "error"): void;
+    /**
+     * Adds a breadcrumb to the trail.
+     */
+    addBreadcrumb(breadcrumb: BreadcrumbInput): void;
+    /**
+     * Sets a context value that will be attached to all future events.
+     */
+    setContext(key: string, value: unknown): void;
+    /**
+     * Clears a context value.
+     */
+    clearContext(key: string): void;
+    /**
+     * Sets user information to attach to events.
+     */
+    setUser(user: {
+        id?: string;
+        [key: string]: unknown;
+    } | null): void;
+    /**
+     * Flushes all queued events immediately.
+     */
+    flush(options?: FlushOptions): Promise<void>;
+    /**
+     * Gets the current configuration.
+     */
+    getConfig(): Readonly<WatchConfigResolved>;
+    /**
+     * Checks if the client is initialized and ready to capture events.
+     */
+    get initialized(): boolean;
+    private buildEvent;
+    private shouldCapture;
+    private ensureStack;
+    private getErrorKey;
+    private markErrorAsSeen;
+    private hasSeenErrorRecently;
+    private scheduleRecentErrorsCleanup;
+    private pruneRecentErrors;
+}
+/**
+ * Static interface for convenience methods.
+ */
+declare const Watch: {
+    init(config: WatchConfig): WatchClient;
+    getInstance(): WatchClient | null;
+    captureError(error: Error, extra?: Record<string, unknown>): void;
+    captureMessage(message: string, level?: "info" | "warning" | "error"): void;
+    addBreadcrumb(breadcrumb: BreadcrumbInput): void;
+    setContext(key: string, value: unknown): void;
+    setUser(user: {
+        id?: string;
+        [key: string]: unknown;
+    } | null): void;
+    flush(options?: FlushOptions): Promise<void>;
+};
+
+/**
+ * CatDoes Watch SDK - Global Error Handlers
+ *
+ * Sets up global error handlers to automatically capture unhandled errors.
+ * Supports both web (window.onerror) and React Native (ErrorUtils).
+ */
+
+/**
+ * Sets up global error handlers for the given Watch client.
+ */
+declare function setupGlobalHandlers(client: WatchClient): void;
+/**
+ * Sets up console.error interception (optional, can be noisy).
+ */
+declare function setupConsoleErrorCapture(client: WatchClient): void;
+/**
+ * Removes all installed global handlers.
+ */
+declare function removeGlobalHandlers(): void;
+
+/**
+ * CatDoes Watch SDK - Session Management
+ *
+ * Generates and manages a unique session ID for the current app session.
+ * The session ID is used to group errors from the same user session.
+ */
+/**
+ * Gets the current session ID, generating one if it doesn't exist.
+ * The session ID persists for the lifetime of the app process.
+ */
+declare function getSessionId(): string;
+/**
+ * Resets the session ID, forcing a new one to be generated.
+ * This can be called when a user logs out or the app wants to start fresh.
+ */
+declare function resetSession(): void;
+/**
+ * Sets a specific session ID (useful for testing or migration).
+ */
+declare function setSessionId(sessionId: string): void;
+
+/**
+ * CatDoes Watch SDK - Context Collection
+ *
+ * Collects device and environment information to attach to error events.
+ * Uses Expo and React Native APIs where available.
+ */
+
+/**
+ * Gets the current platform: 'ios', 'android', or 'web'.
+ */
+declare function getPlatform(): "ios" | "android" | "web";
+/**
+ * Gets the current environment based on __DEV__ flag.
+ */
+declare function getEnvironment(): "development" | "production";
+/**
+ * Collects device and environment information.
+ * Only includes fields that are in the server's allowlist.
+ */
+declare function collectDeviceInfo(): DeviceInfo;
+declare function getCachedDeviceInfo(): DeviceInfo;
+/**
+ * Clears the cached device info, forcing re-collection on next call.
+ */
+declare function clearDeviceInfoCache(): void;
+
+/**
+ * CatDoes Watch SDK - Breadcrumb Management
+ *
+ * Manages a rolling buffer of breadcrumbs that are attached to error events.
+ * Breadcrumbs help understand the sequence of events leading to an error.
+ */
+
+/**
+ * Manages a collection of breadcrumbs with a maximum size.
+ */
+declare class BreadcrumbManager {
+    private breadcrumbs;
+    private maxBreadcrumbs;
+    constructor(maxBreadcrumbs?: number);
+    /**
+     * Adds a new breadcrumb to the collection.
+     * If the collection is at max capacity, the oldest breadcrumb is removed.
+     */
+    add(input: BreadcrumbInput): void;
+    /**
+     * Gets a copy of all current breadcrumbs.
+     */
+    getAll(): Breadcrumb[];
+    /**
+     * Clears all breadcrumbs.
+     */
+    clear(): void;
+    /**
+     * Gets the current count of breadcrumbs.
+     */
+    get count(): number;
+    /**
+     * Updates the maximum number of breadcrumbs.
+     */
+    setMaxBreadcrumbs(max: number): void;
+}
+/**
+ * Creates a navigation breadcrumb.
+ */
+declare function createNavigationBreadcrumb(from: string, to: string): BreadcrumbInput;
+/**
+ * Creates a UI interaction breadcrumb.
+ */
+declare function createUIBreadcrumb(action: string, target?: string): BreadcrumbInput;
+/**
+ * Creates an HTTP request breadcrumb.
+ */
+declare function createHttpBreadcrumb(method: string, url: string, statusCode?: number): BreadcrumbInput;
+/**
+ * Creates a console breadcrumb.
+ */
+declare function createConsoleBreadcrumb(level: "log" | "warn" | "error" | "info", message: string): BreadcrumbInput;
+/**
+ * Creates a custom breadcrumb.
+ */
+declare function createCustomBreadcrumb(message: string, data?: Record<string, unknown>): BreadcrumbInput;
+
+/**
+ * CatDoes Watch SDK - Symbolication Helpers
+ *
+ * Utilities for processing stack traces and file paths.
+ */
+/**
+ * Produces a readable file path from a Metro/URL-style file reference.
+ * - Strips query params
+ * - Prefers repo-relative paths like app/... or src/...
+ * - Falls back to URL pathname
+ */
+declare function deriveReadableFile(file: string): string;
+/**
+ * Checks if a derived filename is usable (not a noisy bundle/node_modules path)
+ */
+declare function isUsableFilename(filename: string): boolean;
+
+/**
+ * CatDoes Watch SDK - Version
+ *
+ * Keep this value updated when making SDK changes.
+ */
+declare const SDK_VERSION = "1.0.0";
+
+export { type Breadcrumb, type BreadcrumbInput, BreadcrumbManager, type DeviceInfo, type IngestResponse, SDK_VERSION, Watch, WatchClient, type WatchConfig, type WatchConfigResolved, type WatchEvent, clearDeviceInfoCache, collectDeviceInfo, createConsoleBreadcrumb, createCustomBreadcrumb, createHttpBreadcrumb, createNavigationBreadcrumb, createUIBreadcrumb, deriveReadableFile, getCachedDeviceInfo, getEnvironment, getPlatform, getSessionId, isUsableFilename, removeGlobalHandlers, resetSession, setSessionId, setupConsoleErrorCapture, setupGlobalHandlers };