@error-explorer/vue 1.1.1

package/dist/index.d.ts

@@ -0,0 +1,433 @@
+import * as vue from 'vue';
+import { App, ComponentPublicInstance, Plugin, PropType, VNode } from 'vue';
+import { InitOptions, ErrorExplorer, CaptureContext, Breadcrumb, UserContext } from '@error-explorer/browser';
+export { Breadcrumb, CaptureContext, ErrorExplorer, InitOptions, UserContext } from '@error-explorer/browser';
+export { RouterIntegrationOptions, createRouterIntegration, setupRouterIntegration } from './router.js';
+import 'vue-router';
+
+/**
+ * Types for @error-explorer/vue
+ */
+
+/**
+ * Vue-specific initialization options
+ */
+interface VueErrorExplorerOptions extends InitOptions {
+    /**
+     * Vue application instance (optional - can be set via plugin install)
+     */
+    app?: App;
+    /**
+     * Enable Vue error handler integration
+     * @default true
+     */
+    vueErrorHandler?: boolean;
+    /**
+     * Enable Vue warning handler integration
+     * @default true in development, false in production
+     */
+    vueWarnHandler?: boolean;
+    /**
+     * Enable Vue Router integration for navigation breadcrumbs
+     * @default true
+     */
+    router?: boolean;
+    /**
+     * Capture component name in error context
+     * @default true
+     */
+    captureComponentName?: boolean;
+    /**
+     * Capture component props in error context (be careful with sensitive data)
+     * @default false
+     */
+    captureComponentProps?: boolean;
+    /**
+     * Maximum depth for serializing component props
+     * @default 2
+     */
+    propsDepth?: number;
+    /**
+     * Hook called before capturing a Vue error
+     * Return false to skip capturing
+     */
+    beforeVueCapture?: (error: Error, instance: ComponentPublicInstance | null, info: string) => boolean;
+}
+/**
+ * Vue component context captured with errors
+ */
+interface VueComponentContext {
+    /**
+     * Component name
+     */
+    name?: string;
+    /**
+     * Component file path (if available)
+     */
+    file?: string;
+    /**
+     * Component props (if enabled)
+     */
+    props?: Record<string, unknown>;
+    /**
+     * Vue error info string (e.g., "render function", "watcher callback")
+     */
+    info?: string;
+    /**
+     * Component trace (parent hierarchy)
+     */
+    trace?: string[];
+}
+/**
+ * Vue plugin install function type
+ */
+type VuePluginInstall = (app: App, options?: VueErrorExplorerOptions) => void;
+/**
+ * ErrorBoundary component props
+ */
+interface ErrorBoundaryProps {
+    /**
+     * Callback when an error is caught
+     */
+    onError?: (error: Error, info: string) => 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>;
+    /**
+     * Fallback content to render when an error occurs
+     * Can be a VNode or a render function receiving error and reset callback
+     */
+    fallback?: unknown;
+}
+/**
+ * ErrorBoundary exposed methods
+ */
+interface ErrorBoundaryExposed {
+    /**
+     * Reset the error state
+     */
+    reset: () => void;
+    /**
+     * Current error (if any)
+     */
+    error: Error | null;
+}
+
+/**
+ * Vue Plugin for Error Explorer
+ */
+
+/**
+ * Restore original handlers
+ */
+declare function restoreHandlers(app: App): void;
+/**
+ * Create Vue plugin for Error Explorer
+ */
+declare function createErrorExplorerPlugin(options?: VueErrorExplorerOptions): Plugin;
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        $errorExplorer: typeof ErrorExplorer;
+    }
+}
+
+/**
+ * ErrorBoundary component
+ *
+ * Usage:
+ * ```vue
+ * <ErrorBoundary @error="handleError" :fallback="ErrorFallback">
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ *
+ * Or with scoped slot for fallback:
+ * ```vue
+ * <ErrorBoundary>
+ *   <template #default>
+ *     <MyComponent />
+ *   </template>
+ *   <template #fallback="{ error, reset }">
+ *     <div>
+ *       <p>Error: {{ error.message }}</p>
+ *       <button @click="reset">Retry</button>
+ *     </div>
+ *   </template>
+ * </ErrorBoundary>
+ * ```
+ */
+declare const ErrorBoundary: vue.DefineComponent<vue.ExtractPropTypes<{
+    /**
+     * Whether to capture the error to Error Explorer
+     */
+    capture: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * Additional tags to add when capturing
+     */
+    tags: {
+        type: PropType<Record<string, string>>;
+        default: () => {};
+    };
+    /**
+     * Additional context to add when capturing
+     */
+    context: {
+        type: PropType<Record<string, unknown>>;
+        default: () => {};
+    };
+    /**
+     * Fallback component to render when an error occurs
+     */
+    fallback: {
+        type: PropType<VNode | (() => VNode) | null>;
+        default: null;
+    };
+    /**
+     * Whether to stop error propagation
+     */
+    stopPropagation: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}> | VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    /**
+     * Emitted when an error is caught
+     */
+    error: (error: Error, info: string) => true;
+    /**
+     * Emitted when the error state is reset
+     */
+    reset: () => true;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    /**
+     * Whether to capture the error to Error Explorer
+     */
+    capture: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /**
+     * Additional tags to add when capturing
+     */
+    tags: {
+        type: PropType<Record<string, string>>;
+        default: () => {};
+    };
+    /**
+     * Additional context to add when capturing
+     */
+    context: {
+        type: PropType<Record<string, unknown>>;
+        default: () => {};
+    };
+    /**
+     * Fallback component to render when an error occurs
+     */
+    fallback: {
+        type: PropType<VNode | (() => VNode) | null>;
+        default: null;
+    };
+    /**
+     * Whether to stop error propagation
+     */
+    stopPropagation: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onError?: ((error: Error, info: string) => any) | undefined;
+    onReset?: (() => any) | undefined;
+}>, {
+    capture: boolean;
+    tags: Record<string, string>;
+    context: Record<string, unknown>;
+    fallback: VNode<vue.RendererNode, vue.RendererElement, {
+        [key: string]: any;
+    }> | (() => VNode) | null;
+    stopPropagation: boolean;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+/**
+ * Higher-order component to wrap a component with ErrorBoundary
+ */
+declare function withErrorBoundary<T extends {
+    new (): any;
+}>(Component: T, options?: {
+    capture?: boolean;
+    tags?: Record<string, string>;
+    context?: Record<string, unknown>;
+    fallback?: VNode | (() => VNode);
+    onError?: (error: Error, info: string) => void;
+}): vue.DefineComponent<{}, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+type ErrorBoundaryInstance = InstanceType<typeof ErrorBoundary>;
+
+/**
+ * Vue 3 Composables for Error Explorer
+ */
+
+/**
+ * Injection key for Error Explorer
+ */
+declare const ErrorExplorerKey: unique symbol;
+/**
+ * Use Error Explorer instance
+ *
+ * @example
+ * ```ts
+ * const { captureException, addBreadcrumb } = useErrorExplorer();
+ *
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   captureException(error);
+ * }
+ * ```
+ */
+declare function useErrorExplorer(): {
+    /**
+     * Check if Error Explorer 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>;
+};
+/**
+ * Track component lifecycle for debugging
+ *
+ * @example
+ * ```ts
+ * // In setup()
+ * useComponentBreadcrumbs();
+ * ```
+ */
+declare function useComponentBreadcrumbs(): void;
+/**
+ * Create a breadcrumb tracker for user actions
+ *
+ * @example
+ * ```ts
+ * const { trackAction } = useActionTracker();
+ *
+ * const handleClick = () => {
+ *   trackAction('button_clicked', { buttonId: 'submit' });
+ *   // ... actual handler
+ * };
+ * ```
+ */
+declare function useActionTracker(): {
+    /**
+     * Track a user action
+     */
+    trackAction: (action: string, data?: Record<string, unknown>) => void;
+    /**
+     * Track a UI interaction
+     */
+    trackInteraction: (element: string, action: "click" | "input" | "focus" | "blur" | "submit", data?: Record<string, unknown>) => void;
+};
+/**
+ * Create an error handler for async operations
+ *
+ * @example
+ * ```ts
+ * const { wrapAsync, handleError } = useErrorHandler();
+ *
+ * // Option 1: Wrap async function
+ * const safeSubmit = wrapAsync(async () => {
+ *   await api.submit(data);
+ * });
+ *
+ * // Option 2: Manual handling
+ * 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;
+};
+/**
+ * Set user context from a reactive source
+ *
+ * @example
+ * ```ts
+ * const user = ref({ id: '123', email: 'user@example.com' });
+ * useUserContext(user);
+ * ```
+ */
+declare function useUserContext(user: {
+    value: UserContext | null;
+} | UserContext | null): {
+    setUser: (newUser: UserContext) => void;
+    clearUser: () => void;
+};
+
+/**
+ * @error-explorer/vue
+ * Error Explorer SDK for Vue.js 3 - Automatic error tracking with Vue integration
+ */
+
+export { ErrorBoundary, type ErrorBoundaryExposed, type ErrorBoundaryInstance, type ErrorBoundaryProps, ErrorExplorerKey, type VueComponentContext, type VueErrorExplorerOptions, type VuePluginInstall, createErrorExplorerPlugin, createErrorExplorerPlugin as default, restoreHandlers, useActionTracker, useComponentBreadcrumbs, useErrorExplorer, useErrorHandler, useUserContext, withErrorBoundary };