@error-explorer/react 1.1.1

package/dist/index.d.cts

@@ -0,0 +1,458 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1, { ReactNode, Component, ComponentType } from 'react';
+import { InitOptions, CaptureContext, Breadcrumb, UserContext } from '@error-explorer/browser';
+export { Breadcrumb, CaptureContext, ErrorExplorer, InitOptions, UserContext } from '@error-explorer/browser';
+
+/**
+ * Types for @error-explorer/react
+ */
+
+/**
+ * React-specific initialization options
+ */
+interface ReactErrorExplorerOptions extends InitOptions {
+    /**
+     * Whether to capture React component stack traces
+     * @default true
+     */
+    captureComponentStack?: boolean;
+    /**
+     * Hook called before capturing a React error
+     * Return false to skip capturing
+     */
+    beforeReactCapture?: (error: Error, errorInfo: React.ErrorInfo) => boolean;
+}
+/**
+ * React component context captured with errors
+ */
+interface ReactComponentContext {
+    /**
+     * Component name
+     */
+    name?: string;
+    /**
+     * React component stack
+     */
+    componentStack?: string;
+    /**
+     * Additional component info
+     */
+    info?: string;
+}
+/**
+ * ErrorBoundary component props
+ */
+interface ErrorBoundaryProps {
+    /**
+     * Child components to wrap
+     */
+    children: ReactNode;
+    /**
+     * Fallback UI to render when an error occurs
+     */
+    fallback?: ReactNode | ((props: FallbackProps) => ReactNode);
+    /**
+     * Callback when an error is caught
+     */
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    /**
+     * Callback when the error is reset
+     */
+    onReset?: () => void;
+    /**
+     * Whether to capture the error to Error Explorer
+     * @default true
+     */
+    capture?: boolean;
+    /**
+     * Additional tags to add when capturing
+     */
+    tags?: Record<string, string>;
+    /**
+     * Additional context to add when capturing
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Reset keys - when these change, the error boundary resets
+     */
+    resetKeys?: unknown[];
+}
+/**
+ * Props passed to the fallback component
+ */
+interface FallbackProps {
+    /**
+     * The error that was caught
+     */
+    error: Error;
+    /**
+     * Error info including component stack
+     */
+    errorInfo: React.ErrorInfo | null;
+    /**
+     * Function to reset the error boundary
+     */
+    resetErrorBoundary: () => void;
+}
+/**
+ * ErrorBoundary state
+ */
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: React.ErrorInfo | null;
+}
+/**
+ * Provider props for ErrorExplorerProvider
+ */
+interface ErrorExplorerProviderProps {
+    /**
+     * SDK initialization options
+     */
+    options: ReactErrorExplorerOptions;
+    /**
+     * Child components
+     */
+    children: ReactNode;
+}
+/**
+ * Context value exposed by ErrorExplorerProvider
+ */
+interface ErrorExplorerContextValue {
+    /**
+     * Check if SDK is initialized
+     */
+    isInitialized: boolean;
+    /**
+     * Capture an exception
+     */
+    captureException: (error: Error, context?: CaptureContext) => string;
+    /**
+     * Capture a message
+     */
+    captureMessage: (message: string, level?: 'debug' | 'info' | 'warning' | 'error' | 'critical') => string;
+    /**
+     * Add a breadcrumb
+     */
+    addBreadcrumb: (breadcrumb: Breadcrumb) => void;
+    /**
+     * Set user context
+     */
+    setUser: (user: UserContext) => void;
+    /**
+     * Clear user context
+     */
+    clearUser: () => void;
+    /**
+     * Set a tag
+     */
+    setTag: (key: string, value: string) => void;
+    /**
+     * Set multiple tags
+     */
+    setTags: (tags: Record<string, string>) => void;
+    /**
+     * Set extra context
+     */
+    setExtra: (extra: Record<string, unknown>) => void;
+    /**
+     * Set named context
+     */
+    setContext: (name: string, context: Record<string, unknown>) => void;
+    /**
+     * Flush pending events
+     */
+    flush: (timeout?: number) => Promise<boolean>;
+    /**
+     * Close the SDK
+     */
+    close: (timeout?: number) => Promise<boolean>;
+}
+/**
+ * HOC options for withErrorBoundary
+ */
+interface WithErrorBoundaryOptions {
+    /**
+     * Fallback UI to render when an error occurs
+     */
+    fallback?: ReactNode | ((props: FallbackProps) => ReactNode);
+    /**
+     * Callback when an error is caught
+     */
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    /**
+     * Whether to capture the error to Error Explorer
+     * @default true
+     */
+    capture?: boolean;
+    /**
+     * Additional tags to add when capturing
+     */
+    tags?: Record<string, string>;
+    /**
+     * Additional context to add when capturing
+     */
+    context?: Record<string, unknown>;
+}
+
+/**
+ * React Context for Error Explorer
+ */
+declare const ErrorExplorerContext: React$1.Context<ErrorExplorerContextValue | null>;
+/**
+ * Error Explorer Provider Component
+ *
+ * Initializes the Error Explorer SDK and provides context to child components.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ErrorExplorerProvider
+ *       options={{
+ *         token: 'ee_your_token',
+ *         project: 'my-react-app',
+ *         environment: 'production',
+ *       }}
+ *     >
+ *       <MainContent />
+ *     </ErrorExplorerProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function ErrorExplorerProvider({ options, children, }: {
+    options: ReactErrorExplorerOptions;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * Initialize Error Explorer directly (without provider)
+ *
+ * Use this if you don't need the React Context and just want to initialize
+ * the SDK globally.
+ *
+ * @example
+ * ```tsx
+ * // In your entry file (main.tsx)
+ * import { initErrorExplorer } from '@error-explorer/react';
+ *
+ * initErrorExplorer({
+ *   token: 'ee_your_token',
+ *   project: 'my-react-app',
+ *   environment: 'production',
+ * });
+ *
+ * ReactDOM.createRoot(root).render(<App />);
+ * ```
+ */
+declare function initErrorExplorer(options: ReactErrorExplorerOptions): void;
+
+/**
+ * ErrorBoundary component for React
+ * Catches errors in child components and reports them to Error Explorer
+ */
+
+/**
+ * ErrorBoundary class component
+ *
+ * React Error Boundaries must be class components - there's no hook equivalent.
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary fallback={<ErrorFallback />}>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @example
+ * With render prop fallback:
+ * ```tsx
+ * <ErrorBoundary
+ *   fallback={({ error, resetErrorBoundary }) => (
+ *     <div>
+ *       <p>Error: {error.message}</p>
+ *       <button onClick={resetErrorBoundary}>Retry</button>
+ *     </div>
+ *   )}
+ * >
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ */
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    static defaultProps: {
+        capture: boolean;
+        tags: {};
+        context: {};
+    };
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: React$1.ErrorInfo): void;
+    componentDidUpdate(prevProps: ErrorBoundaryProps): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+/**
+ * Higher-order component to wrap a component with ErrorBoundary
+ *
+ * @example
+ * ```tsx
+ * const SafeComponent = withErrorBoundary(MyComponent, {
+ *   fallback: <ErrorFallback />,
+ *   onError: (error) => console.error(error),
+ * });
+ * ```
+ */
+declare function withErrorBoundary<P extends object>(Component: ComponentType<P>, options?: WithErrorBoundaryOptions): ComponentType<P>;
+/**
+ * useErrorBoundary hook for functional components
+ *
+ * Note: This doesn't create an error boundary - those must be class components.
+ * Instead, this provides a way to show/trigger the nearest error boundary.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { showBoundary } = useErrorBoundary();
+ *
+ *   const handleClick = async () => {
+ *     try {
+ *       await riskyOperation();
+ *     } catch (error) {
+ *       showBoundary(error);
+ *     }
+ *   };
+ * }
+ * ```
+ */
+declare function useErrorBoundary(): {
+    /**
+     * Trigger the nearest error boundary with the given error
+     */
+    showBoundary: (err: Error) => void;
+    /**
+     * Reset the error state
+     */
+    resetBoundary: () => void;
+};
+
+/**
+ * Use Error Explorer instance
+ *
+ * Returns the Error Explorer SDK methods for capturing errors and managing context.
+ *
+ * @example
+ * ```tsx
+ * const { captureException, addBreadcrumb, setUser } = useErrorExplorer();
+ *
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   captureException(error);
+ * }
+ * ```
+ */
+declare function useErrorExplorer(): ErrorExplorerContextValue;
+/**
+ * Error handler hook for async operations
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { handleError, wrapAsync } = useErrorHandler();
+ *
+ *   // Option 1: Wrap async function
+ *   const safeSubmit = wrapAsync(async () => {
+ *     await api.submit(data);
+ *   });
+ *
+ *   // Option 2: Manual handling
+ *   const handleClick = async () => {
+ *     try {
+ *       await riskyOperation();
+ *     } catch (error) {
+ *       handleError(error, { tags: { operation: 'risky' } });
+ *     }
+ *   };
+ * }
+ * ```
+ */
+declare function useErrorHandler(defaultContext?: CaptureContext): {
+    handleError: (error: unknown, context?: CaptureContext) => Error;
+    wrapAsync: <T extends (...args: any[]) => Promise<any>>(fn: T, context?: CaptureContext) => ((...args: Parameters<T>) => Promise<Awaited<ReturnType<T>> | undefined>);
+    tryCatch: <T>(fn: () => T, context?: CaptureContext) => T | undefined;
+};
+/**
+ * User context hook
+ *
+ * Sets the user context and cleans up on unmount.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const user = useCurrentUser();
+ *
+ *   useUserContext(user ? {
+ *     id: user.id,
+ *     email: user.email,
+ *     name: user.name,
+ *   } : null);
+ *
+ *   return <MainContent />;
+ * }
+ * ```
+ */
+declare function useUserContext(user: UserContext | null): {
+    setUser: (user: UserContext) => void;
+    clearUser: () => void;
+};
+/**
+ * Action tracker hook for user interactions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { trackAction, trackInteraction } = useActionTracker();
+ *
+ *   const handleSubmit = () => {
+ *     trackAction('form_submitted', { formId: 'contact' });
+ *     // ... actual submit logic
+ *   };
+ *
+ *   return (
+ *     <button
+ *       onClick={() => {
+ *         trackInteraction('submit-button', 'click');
+ *         handleSubmit();
+ *       }}
+ *     >
+ *       Submit
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useActionTracker(componentName?: string): {
+    trackAction: (action: string, data?: Record<string, unknown>) => void;
+    trackInteraction: (element: string, action: "click" | "input" | "focus" | "blur" | "submit", data?: Record<string, unknown>) => void;
+};
+/**
+ * Component lifecycle tracking hook
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useComponentBreadcrumbs('MyComponent');
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useComponentBreadcrumbs(componentName: string): void;
+
+/**
+ * @error-explorer/react
+ * Error Explorer SDK for React - Automatic error tracking with React integration
+ */
+
+export { ErrorBoundary, type ErrorBoundaryProps, type ErrorBoundaryState, ErrorExplorerContext, type ErrorExplorerContextValue, ErrorExplorerProvider, type ErrorExplorerProviderProps, type FallbackProps, type ReactComponentContext, type ReactErrorExplorerOptions, type WithErrorBoundaryOptions, ErrorExplorerProvider as default, initErrorExplorer, useActionTracker, useComponentBreadcrumbs, useErrorBoundary, useErrorExplorer, useErrorHandler, useUserContext, withErrorBoundary };