@catdoes/watch 1.3.0 → 2.0.0

package/dist/index.d.mts

@@ -1,431 +1,202 @@
 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.
- */
-/**
- * Minimal async key-value storage used to persist the event queue across
- * launches. Compatible with `@react-native-async-storage/async-storage`'s
- * default export and `window.localStorage`-style wrappers.
- *
- * The SDK never imports a storage module itself — dynamic `require()` of
- * optional dependencies is reported as a fatal error by Metro in release
- * builds. Pass an implementation explicitly:
- *
- * ```ts
- * import AsyncStorage from "@react-native-async-storage/async-storage";
- * initCatDoesWatch({ apiKey, storage: AsyncStorage });
- * ```
- */
-interface WatchStorage {
-    getItem(key: string): Promise<string | null>;
-    setItem(key: string, value: string): Promise<void>;
-    removeItem(key: string): Promise<void>;
+interface QueueStore {
+    read(): string | null;
+    write(value: string): void;
+    remove(): void;
 }
-/**
- * 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
-     */
+    debug?: boolean;
+    installGlobalHandlers?: boolean;
     captureConsoleErrors?: boolean;
-    /**
-     * Maximum number of breadcrumbs to store.
-     * @default 20
-     */
+    captureHttpBreadcrumbs?: boolean;
     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.
-     */
+    fatalFlushTimeoutMs?: number;
     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;
-    /**
-     * Storage implementation used to persist queued events across launches
-     * (e.g. AsyncStorage). Persistence is disabled when omitted.
-     */
-    storage?: WatchStorage;
+    storage?: QueueStore;
 }
-/**
- * Required configuration with defaults applied.
- */
 interface WatchConfigResolved {
     apiKey: string;
     endpoint: string;
     environment: "development" | "production";
+    debug: boolean;
+    installGlobalHandlers: boolean;
     captureConsoleErrors: boolean;
+    captureHttpBreadcrumbs: boolean;
     maxBreadcrumbs: number;
     maxBufferSize: number;
     flushInterval: number;
+    fatalFlushTimeoutMs: number;
     beforeSend: (event: WatchEvent) => WatchEvent | null;
-    debug: boolean;
     dedupWindowMs: number;
     dedupMaxEntries: number;
-    storage: WatchStorage | null;
+    storage?: QueueStore;
 }
-/**
- * Device and environment information collected automatically.
- */
 interface DeviceInfo {
-    deviceModel?: string;
-    deviceName?: string;
-    deviceType?: string;
     brand?: string;
     manufacturer?: string;
     modelName?: string;
+    modelId?: string;
+    designName?: string;
+    productName?: string;
+    deviceName?: string;
+    deviceType?: "unknown" | "phone" | "tablet" | "desktop" | "tv";
+    deviceYearClass?: number;
+    memoryTotal?: number;
+    supportedCpuArchitectures?: string[];
     isDevice?: boolean;
-    isEmulator?: boolean;
-    isTablet?: boolean;
     osName?: string;
     osVersion?: string;
     osBuildId?: string;
+    osInternalBuildId?: string;
+    osBuildFingerprint?: string;
     platformApiLevel?: number;
+    appName?: string;
+    appSlug?: string;
     appVersion?: string;
     appBuildNumber?: string;
-    appName?: string;
     bundleId?: string;
+    expoSdkVersion?: string;
     runtimeVersion?: string;
+    expoRuntimeVersion?: string;
     expoVersion?: string;
-    nativeAppVersion?: string;
-    nativeBuildVersion?: string;
+    executionEnvironment?: string;
+    jsEngine?: "hermes" | "jsc" | "unknown";
     screenWidth?: number;
     screenHeight?: number;
     screenScale?: number;
+    fontScale?: 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.
-     */
+    eventId?: string;
     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 LastFlush {
+    at: string;
+    status: number | null;
+    accepted: number | null;
+    error?: string;
+}
+interface TransportStats {
+    disabledReason: "auth" | "failures" | null;
+    backoffUntil: number | null;
+    consecutiveFailures: number;
+    lastFlush: LastFlush | null;
+}
+interface WatchStats {
+    queueSize: number;
+    sessionId: string;
+    transport: TransportStats;
+}
 
 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 readonly config;
+    private readonly transport;
+    private readonly breadcrumbs;
     private context;
     private user;
-    private isInitialized;
-    private recentErrors;
+    private readonly 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.
-     */
+    captureError(error: unknown, extra?: Record<string, unknown>): void;
     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.
-     */
+    flushWithTimeout(timeoutMs: number): Promise<void>;
+    commit(): void;
+    getStats(): WatchStats;
     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 markErrorAsSeen;
     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;
+    captureError(error: unknown, extra?: Record<string, unknown>): void;
     captureMessage(message: string, level?: "info" | "warning" | "error"): void;
     addBreadcrumb(breadcrumb: BreadcrumbInput): void;
     setContext(key: string, value: unknown): void;
+    clearContext(key: string): void;
     setUser(user: {
         id?: string;
         [key: string]: unknown;
     } | null): void;
     flush(options?: FlushOptions): Promise<void>;
+    flushWithTimeout(timeoutMs: number): Promise<void>;
+    getStats(): WatchStats | null;
 };
 
-/**
- * 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 installHttpBreadcrumbs(client: WatchClient): void;
+declare function removeHttpBreadcrumbs(): void;
+
 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;
+declare function getDeviceInfo(): DeviceInfo;
 
 /**
  * CatDoes Watch SDK - Breadcrumb Management
@@ -484,28 +255,11 @@ declare function createConsoleBreadcrumb(level: "log" | "warn" | "error" | "info
  */
 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.3.0";
+declare const SDK_VERSION = "2.0.0";
 
-export { type Breadcrumb, type BreadcrumbInput, BreadcrumbManager, type DeviceInfo, type IngestResponse, SDK_VERSION, Watch, WatchClient, type WatchConfig, type WatchConfigResolved, type WatchEvent, type WatchStorage, clearDeviceInfoCache, collectDeviceInfo, createConsoleBreadcrumb, createCustomBreadcrumb, createHttpBreadcrumb, createNavigationBreadcrumb, createUIBreadcrumb, deriveReadableFile, getCachedDeviceInfo, getEnvironment, getPlatform, getSessionId, isUsableFilename, removeGlobalHandlers, resetSession, setSessionId, setupConsoleErrorCapture, setupGlobalHandlers };
+export { type Breadcrumb, type BreadcrumbInput, BreadcrumbManager, type DeviceInfo, type IngestResponse, type QueueStore, SDK_VERSION, Watch, WatchClient, type WatchConfig, type WatchConfigResolved, type WatchEvent, type WatchStats, createConsoleBreadcrumb, createCustomBreadcrumb, createHttpBreadcrumb, createNavigationBreadcrumb, createUIBreadcrumb, getDeviceInfo, getEnvironment, getPlatform, getSessionId, installHttpBreadcrumbs, removeGlobalHandlers, removeHttpBreadcrumbs, resetSession, setSessionId, setupGlobalHandlers };