@bugwatch/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,323 @@
+/**
+ * Configuration options for the Bugwatch SDK
+ */
+interface BugwatchOptions {
+    /** Your project's API key */
+    apiKey: string;
+    /** API endpoint URL (defaults to https://api.bugwatch.dev) */
+    endpoint?: string;
+    /** Application environment (e.g., 'production', 'staging') */
+    environment?: string;
+    /** Application release/version */
+    release?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Sample rate for error events (0.0 to 1.0) */
+    sampleRate?: number;
+    /** Maximum breadcrumbs to capture */
+    maxBreadcrumbs?: number;
+    /** Tags to attach to all events */
+    tags?: Record<string, string>;
+    /** User context */
+    user?: UserContext;
+    /** Before send hook - return null to drop the event */
+    beforeSend?: (event: ErrorEvent) => ErrorEvent | null;
+    /** Patterns to ignore (matches against error message) */
+    ignoreErrors?: (string | RegExp)[];
+}
+/**
+ * User context attached to events
+ */
+interface UserContext {
+    id?: string;
+    email?: string;
+    username?: string;
+    [key: string]: unknown;
+}
+/**
+ * Stack frame in an error stack trace
+ */
+interface StackFrame {
+    filename: string;
+    function: string;
+    lineno: number;
+    colno: number;
+    context_line?: string;
+    pre_context?: string[];
+    post_context?: string[];
+    in_app: boolean;
+}
+/**
+ * Exception/error information
+ */
+interface ExceptionInfo {
+    type: string;
+    value: string;
+    stacktrace: StackFrame[];
+}
+/**
+ * Breadcrumb for tracking events leading to an error
+ */
+interface Breadcrumb {
+    timestamp: string;
+    category: string;
+    message: string;
+    level?: "debug" | "info" | "warning" | "error";
+    data?: Record<string, unknown>;
+}
+/**
+ * Request context for HTTP errors
+ */
+interface RequestContext {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    query_string?: string;
+    data?: unknown;
+}
+/**
+ * Runtime information
+ */
+interface RuntimeInfo {
+    name: string;
+    version: string;
+}
+/**
+ * SDK information
+ */
+interface SdkInfo {
+    name: string;
+    version: string;
+}
+/**
+ * The main error event payload sent to the API
+ */
+interface ErrorEvent {
+    /** Event ID (generated by SDK) */
+    event_id: string;
+    /** Timestamp in ISO format */
+    timestamp: string;
+    /** Platform identifier */
+    platform: string;
+    /** Error level */
+    level: "fatal" | "error" | "warning" | "info" | "debug";
+    /** Error message */
+    message: string;
+    /** Exception information */
+    exception?: ExceptionInfo;
+    /** Breadcrumbs */
+    breadcrumbs?: Breadcrumb[];
+    /** Tags */
+    tags?: Record<string, string>;
+    /** Extra context data */
+    extra?: Record<string, unknown>;
+    /** User context */
+    user?: UserContext;
+    /** Request context */
+    request?: RequestContext;
+    /** Application environment */
+    environment?: string;
+    /** Application release */
+    release?: string;
+    /** Server name / hostname */
+    server_name?: string;
+    /** SDK information */
+    sdk?: SdkInfo;
+    /** Runtime information */
+    runtime?: RuntimeInfo;
+}
+/**
+ * Transport interface for sending events
+ */
+interface Transport {
+    send(event: ErrorEvent): Promise<void>;
+}
+/**
+ * Integration interface for platform-specific functionality
+ */
+interface Integration {
+    name: string;
+    setup(client: BugwatchClient): void;
+}
+/**
+ * Bugwatch client interface
+ */
+interface BugwatchClient {
+    captureException(error: Error, context?: Partial<ErrorEvent>): string;
+    captureMessage(message: string, level?: ErrorEvent["level"]): string;
+    addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
+    setUser(user: UserContext | null): void;
+    setTag(key: string, value: string): void;
+    setExtra(key: string, value: unknown): void;
+    getOptions(): BugwatchOptions;
+}
+
+/**
+ * Core Bugwatch client implementation
+ */
+declare class Bugwatch implements BugwatchClient {
+    private options;
+    private transport;
+    private breadcrumbs;
+    private tags;
+    private extra;
+    private user;
+    private integrations;
+    private initialized;
+    constructor(options: BugwatchOptions);
+    private createTransport;
+    /**
+     * Register an integration
+     */
+    use(integration: Integration): this;
+    /**
+     * Get SDK options
+     */
+    getOptions(): BugwatchOptions;
+    /**
+     * Capture an exception
+     */
+    captureException(error: Error, context?: Partial<ErrorEvent>): string;
+    /**
+     * Capture a message
+     */
+    captureMessage(message: string, level?: ErrorEvent["level"]): string;
+    /**
+     * Add a breadcrumb
+     */
+    addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
+    /**
+     * Set user context
+     */
+    setUser(user: UserContext | null): void;
+    /**
+     * Set a tag
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * Set extra context
+     */
+    setExtra(key: string, value: unknown): void;
+    /**
+     * Clear breadcrumbs
+     */
+    clearBreadcrumbs(): void;
+    /**
+     * Create an event from an Error object
+     */
+    private createEventFromError;
+    /**
+     * Create a base event
+     */
+    private createEvent;
+    /**
+     * Check if error should be ignored
+     */
+    private shouldIgnoreError;
+    /**
+     * Detect the current platform
+     */
+    private detectPlatform;
+}
+
+/**
+ * HTTP transport for sending events to the Bugwatch API
+ */
+declare class HttpTransport implements Transport {
+    private endpoint;
+    private apiKey;
+    private debug;
+    constructor(options: BugwatchOptions);
+    send(event: ErrorEvent): Promise<void>;
+    /**
+     * Abstract fetch to support different environments
+     */
+    private fetch;
+}
+/**
+ * No-op transport for testing or disabled SDK
+ */
+declare class NoopTransport implements Transport {
+    send(_event: ErrorEvent): Promise<void>;
+}
+/**
+ * Console transport for development/debugging
+ */
+declare class ConsoleTransport implements Transport {
+    send(event: ErrorEvent): Promise<void>;
+}
+/**
+ * Batching transport that queues events and sends them in batches
+ */
+declare class BatchTransport implements Transport {
+    private transport;
+    private queue;
+    private maxBatchSize;
+    private flushInterval;
+    private timer;
+    constructor(transport: Transport, options?: {
+        maxBatchSize?: number;
+        flushInterval?: number;
+    });
+    send(event: ErrorEvent): Promise<void>;
+    flush(): Promise<void>;
+    private startTimer;
+    destroy(): void;
+}
+
+/**
+ * Parse an Error's stack trace into structured frames
+ */
+declare function parseStackTrace(error: Error): StackFrame[];
+/**
+ * Extract error name and message from Error object
+ */
+declare function extractErrorInfo(error: Error): {
+    type: string;
+    value: string;
+};
+
+/**
+ * Generate a fingerprint for an error to group similar errors together.
+ * Uses a combination of error type, message patterns, and stack trace.
+ */
+declare function generateFingerprint(errorType: string, message: string, stacktrace?: StackFrame[]): string;
+/**
+ * Generate fingerprint from exception info
+ */
+declare function fingerprintFromException(exception: ExceptionInfo): string;
+
+/**
+ * Initialize the global Bugwatch client
+ */
+declare function init(options: BugwatchOptions): Bugwatch;
+/**
+ * Get the global Bugwatch client
+ */
+declare function getClient(): Bugwatch | null;
+/**
+ * Capture an exception using the global client
+ */
+declare function captureException(error: Error, context?: Partial<ErrorEvent>): string;
+/**
+ * Capture a message using the global client
+ */
+declare function captureMessage(message: string, level?: ErrorEvent["level"]): string;
+/**
+ * Add a breadcrumb using the global client
+ */
+declare function addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
+/**
+ * Set user context on the global client
+ */
+declare function setUser(user: UserContext | null): void;
+/**
+ * Set a tag on the global client
+ */
+declare function setTag(key: string, value: string): void;
+/**
+ * Set extra context on the global client
+ */
+declare function setExtra(key: string, value: unknown): void;
+
+export { BatchTransport, type Breadcrumb, Bugwatch, type BugwatchClient, type BugwatchOptions, ConsoleTransport, type ErrorEvent, type ExceptionInfo, HttpTransport, type Integration, NoopTransport, type RequestContext, type RuntimeInfo, type SdkInfo, type StackFrame, type Transport, type UserContext, addBreadcrumb, captureException, captureMessage, extractErrorInfo, fingerprintFromException, generateFingerprint, getClient, init, parseStackTrace, setExtra, setTag, setUser };

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Configuration options for the Bugwatch SDK
+ */
+interface BugwatchOptions {
+    /** Your project's API key */
+    apiKey: string;
+    /** API endpoint URL (defaults to https://api.bugwatch.dev) */
+    endpoint?: string;
+    /** Application environment (e.g., 'production', 'staging') */
+    environment?: string;
+    /** Application release/version */
+    release?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Sample rate for error events (0.0 to 1.0) */
+    sampleRate?: number;
+    /** Maximum breadcrumbs to capture */
+    maxBreadcrumbs?: number;
+    /** Tags to attach to all events */
+    tags?: Record<string, string>;
+    /** User context */
+    user?: UserContext;
+    /** Before send hook - return null to drop the event */
+    beforeSend?: (event: ErrorEvent) => ErrorEvent | null;
+    /** Patterns to ignore (matches against error message) */
+    ignoreErrors?: (string | RegExp)[];
+}
+/**
+ * User context attached to events
+ */
+interface UserContext {
+    id?: string;
+    email?: string;
+    username?: string;
+    [key: string]: unknown;
+}
+/**
+ * Stack frame in an error stack trace
+ */
+interface StackFrame {
+    filename: string;
+    function: string;
+    lineno: number;
+    colno: number;
+    context_line?: string;
+    pre_context?: string[];
+    post_context?: string[];
+    in_app: boolean;
+}
+/**
+ * Exception/error information
+ */
+interface ExceptionInfo {
+    type: string;
+    value: string;
+    stacktrace: StackFrame[];
+}
+/**
+ * Breadcrumb for tracking events leading to an error
+ */
+interface Breadcrumb {
+    timestamp: string;
+    category: string;
+    message: string;
+    level?: "debug" | "info" | "warning" | "error";
+    data?: Record<string, unknown>;
+}
+/**
+ * Request context for HTTP errors
+ */
+interface RequestContext {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    query_string?: string;
+    data?: unknown;
+}
+/**
+ * Runtime information
+ */
+interface RuntimeInfo {
+    name: string;
+    version: string;
+}
+/**
+ * SDK information
+ */
+interface SdkInfo {
+    name: string;
+    version: string;
+}
+/**
+ * The main error event payload sent to the API
+ */
+interface ErrorEvent {
+    /** Event ID (generated by SDK) */
+    event_id: string;
+    /** Timestamp in ISO format */
+    timestamp: string;
+    /** Platform identifier */
+    platform: string;
+    /** Error level */
+    level: "fatal" | "error" | "warning" | "info" | "debug";
+    /** Error message */
+    message: string;
+    /** Exception information */
+    exception?: ExceptionInfo;
+    /** Breadcrumbs */
+    breadcrumbs?: Breadcrumb[];
+    /** Tags */
+    tags?: Record<string, string>;
+    /** Extra context data */
+    extra?: Record<string, unknown>;
+    /** User context */
+    user?: UserContext;
+    /** Request context */
+    request?: RequestContext;
+    /** Application environment */
+    environment?: string;
+    /** Application release */
+    release?: string;
+    /** Server name / hostname */
+    server_name?: string;
+    /** SDK information */
+    sdk?: SdkInfo;
+    /** Runtime information */
+    runtime?: RuntimeInfo;
+}
+/**
+ * Transport interface for sending events
+ */
+interface Transport {
+    send(event: ErrorEvent): Promise<void>;
+}
+/**
+ * Integration interface for platform-specific functionality
+ */
+interface Integration {
+    name: string;
+    setup(client: BugwatchClient): void;
+}
+/**
+ * Bugwatch client interface
+ */
+interface BugwatchClient {
+    captureException(error: Error, context?: Partial<ErrorEvent>): string;
+    captureMessage(message: string, level?: ErrorEvent["level"]): string;
+    addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
+    setUser(user: UserContext | null): void;
+    setTag(key: string, value: string): void;
+    setExtra(key: string, value: unknown): void;
+    getOptions(): BugwatchOptions;
+}
+
+/**
+ * Core Bugwatch client implementation
+ */
+declare class Bugwatch implements BugwatchClient {
+    private options;
+    private transport;
+    private breadcrumbs;
+    private tags;
+    private extra;
+    private user;
+    private integrations;
+    private initialized;
+    constructor(options: BugwatchOptions);
+    private createTransport;
+    /**
+     * Register an integration
+     */
+    use(integration: Integration): this;
+    /**
+     * Get SDK options
+     */
+    getOptions(): BugwatchOptions;
+    /**
+     * Capture an exception
+     */
+    captureException(error: Error, context?: Partial<ErrorEvent>): string;
+    /**
+     * Capture a message
+     */
+    captureMessage(message: string, level?: ErrorEvent["level"]): string;
+    /**
+     * Add a breadcrumb
+     */
+    addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
+    /**
+     * Set user context
+     */
+    setUser(user: UserContext | null): void;
+    /**
+     * Set a tag
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * Set extra context
+     */
+    setExtra(key: string, value: unknown): void;
+    /**
+     * Clear breadcrumbs
+     */
+    clearBreadcrumbs(): void;
+    /**
+     * Create an event from an Error object
+     */
+    private createEventFromError;
+    /**
+     * Create a base event
+     */
+    private createEvent;
+    /**
+     * Check if error should be ignored
+     */
+    private shouldIgnoreError;
+    /**
+     * Detect the current platform
+     */
+    private detectPlatform;
+}
+
+/**
+ * HTTP transport for sending events to the Bugwatch API
+ */
+declare class HttpTransport implements Transport {
+    private endpoint;
+    private apiKey;
+    private debug;
+    constructor(options: BugwatchOptions);
+    send(event: ErrorEvent): Promise<void>;
+    /**
+     * Abstract fetch to support different environments
+     */
+    private fetch;
+}
+/**
+ * No-op transport for testing or disabled SDK
+ */
+declare class NoopTransport implements Transport {
+    send(_event: ErrorEvent): Promise<void>;
+}
+/**
+ * Console transport for development/debugging
+ */
+declare class ConsoleTransport implements Transport {
+    send(event: ErrorEvent): Promise<void>;
+}
+/**
+ * Batching transport that queues events and sends them in batches
+ */
+declare class BatchTransport implements Transport {
+    private transport;
+    private queue;
+    private maxBatchSize;
+    private flushInterval;
+    private timer;
+    constructor(transport: Transport, options?: {
+        maxBatchSize?: number;
+        flushInterval?: number;
+    });
+    send(event: ErrorEvent): Promise<void>;
+    flush(): Promise<void>;
+    private startTimer;
+    destroy(): void;
+}
+
+/**
+ * Parse an Error's stack trace into structured frames
+ */
+declare function parseStackTrace(error: Error): StackFrame[];
+/**
+ * Extract error name and message from Error object
+ */
+declare function extractErrorInfo(error: Error): {
+    type: string;
+    value: string;
+};
+
+/**
+ * Generate a fingerprint for an error to group similar errors together.
+ * Uses a combination of error type, message patterns, and stack trace.
+ */
+declare function generateFingerprint(errorType: string, message: string, stacktrace?: StackFrame[]): string;
+/**
+ * Generate fingerprint from exception info
+ */
+declare function fingerprintFromException(exception: ExceptionInfo): string;
+
+/**
+ * Initialize the global Bugwatch client
+ */
+declare function init(options: BugwatchOptions): Bugwatch;
+/**
+ * Get the global Bugwatch client
+ */
+declare function getClient(): Bugwatch | null;
+/**
+ * Capture an exception using the global client
+ */
+declare function captureException(error: Error, context?: Partial<ErrorEvent>): string;
+/**
+ * Capture a message using the global client
+ */
+declare function captureMessage(message: string, level?: ErrorEvent["level"]): string;
+/**
+ * Add a breadcrumb using the global client
+ */
+declare function addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
+/**
+ * Set user context on the global client
+ */
+declare function setUser(user: UserContext | null): void;
+/**
+ * Set a tag on the global client
+ */
+declare function setTag(key: string, value: string): void;
+/**
+ * Set extra context on the global client
+ */
+declare function setExtra(key: string, value: unknown): void;
+
+export { BatchTransport, type Breadcrumb, Bugwatch, type BugwatchClient, type BugwatchOptions, ConsoleTransport, type ErrorEvent, type ExceptionInfo, HttpTransport, type Integration, NoopTransport, type RequestContext, type RuntimeInfo, type SdkInfo, type StackFrame, type Transport, type UserContext, addBreadcrumb, captureException, captureMessage, extractErrorInfo, fingerprintFromException, generateFingerprint, getClient, init, parseStackTrace, setExtra, setTag, setUser };