@bugwatch/core 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -131,6 +131,16 @@ interface ErrorEvent {
  */
 interface Transport {
     send(event: ErrorEvent): Promise<void>;
+    /**
+     * Flush any pending events.
+     * Ensures all queued events are sent before the promise resolves.
+     */
+    flush?(): Promise<void>;
+    /**
+     * Close the transport and release any resources.
+     * After calling this method, the transport should not be used again.
+     */
+    close?(): Promise<void>;
 }
 /**
  * Integration interface for platform-specific functionality
@@ -150,6 +160,16 @@ interface BugwatchClient {
     setTag(key: string, value: string): void;
     setExtra(key: string, value: unknown): void;
     getOptions(): BugwatchOptions;
+    /**
+     * Flush any pending events.
+     * Call this before process exit to ensure no events are lost.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the client and release any resources.
+     * This flushes any pending events and closes the transport.
+     */
+    close(): Promise<void>;
 }
 
 /**
@@ -218,6 +238,17 @@ declare class Bugwatch implements BugwatchClient {
      * Detect the current platform
      */
     private detectPlatform;
+    /**
+     * Flush any pending events.
+     * Call this before process exit to ensure no events are lost.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the client and release any resources.
+     * This flushes any pending events and closes the transport.
+     * After calling this method, the client should not be used again.
+     */
+    close(): Promise<void>;
 }
 
 /**
@@ -263,6 +294,10 @@ declare class BatchTransport implements Transport {
     flush(): Promise<void>;
     private startTimer;
     destroy(): void;
+    /**
+     * Close the transport, flushing any remaining events and stopping the timer.
+     */
+    close(): Promise<void>;
 }
 
 /**
@@ -288,36 +323,228 @@ declare function generateFingerprint(errorType: string, message: string, stacktr
 declare function fingerprintFromException(exception: ExceptionInfo): string;
 
 /**
- * Initialize the global Bugwatch client
+ * Environment variable utilities for Bugwatch SDK.
+ *
+ * This module provides functions for reading configuration from environment
+ * variables and validating API keys.
  */
-declare function init(options: BugwatchOptions): Bugwatch;
+
+/**
+ * Supported environment variables for Bugwatch configuration.
+ */
+declare const ENV_VARS: {
+    readonly API_KEY: "BUGWATCH_API_KEY";
+    readonly ENVIRONMENT: "BUGWATCH_ENVIRONMENT";
+    readonly RELEASE: "BUGWATCH_RELEASE";
+    readonly DEBUG: "BUGWATCH_DEBUG";
+    readonly ENDPOINT: "BUGWATCH_ENDPOINT";
+};
+/**
+ * Read Bugwatch configuration from environment variables.
+ *
+ * Supported environment variables:
+ * - `BUGWATCH_API_KEY` - API key (required unless passed explicitly)
+ * - `BUGWATCH_ENVIRONMENT` - Environment tag (e.g., 'production', 'staging')
+ * - `BUGWATCH_RELEASE` - Release version
+ * - `BUGWATCH_DEBUG` - Enable debug mode ('true' to enable)
+ * - `BUGWATCH_ENDPOINT` - Custom API endpoint
+ *
+ * @returns Partial configuration from environment variables
+ *
+ * @example
+ * ```typescript
+ * // Set environment variables
+ * // BUGWATCH_API_KEY=bw_live_xxxxx
+ * // BUGWATCH_ENVIRONMENT=production
+ *
+ * const envConfig = getEnvConfig();
+ * // { apiKey: 'bw_live_xxxxx', environment: 'production' }
+ * ```
+ */
+declare function getEnvConfig(): Partial<BugwatchOptions>;
+/**
+ * Validate an API key and throw a clear error if invalid.
+ *
+ * @param key - The API key to validate
+ * @throws Error if the API key is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * // Missing API key
+ * validateApiKey(undefined);
+ * // throws: "Bugwatch: API key required. Set BUGWATCH_API_KEY environment variable or pass { apiKey: '...' }"
+ *
+ * // Invalid format (logs warning but doesn't throw)
+ * validateApiKey("invalid-key");
+ * // warns: "Bugwatch: API key should start with 'bw_'. Got 'invali...'"
+ * ```
+ */
+declare function validateApiKey(key: string | undefined): asserts key is string;
+/**
+ * Check if API key is available (either in env or passed explicitly).
+ *
+ * @param explicitKey - Explicitly provided API key
+ * @returns true if an API key is available
+ */
+declare function hasApiKey(explicitKey?: string): boolean;
+
+/**
+ * Request-scoped context using AsyncLocalStorage.
+ *
+ * This module provides thread-safe, request-isolated context storage
+ * for Node.js environments. Each concurrent request gets its own
+ * isolated context that won't leak to other requests.
+ */
+
+/**
+ * Request-scoped context that is isolated per request
+ */
+interface ScopedContext {
+    user: UserContext | null;
+    tags: Record<string, string>;
+    extra: Record<string, unknown>;
+    breadcrumbs: Breadcrumb[];
+}
+/**
+ * Create a new empty scoped context
+ */
+declare function createScopedContext(): ScopedContext;
+/**
+ * Run a function within an isolated context.
+ *
+ * All context operations (setUser, setTag, etc.) within this function
+ * will be scoped to this context and won't affect other concurrent requests.
+ *
+ * @param context - The initial context for this scope
+ * @param fn - The function to run within the context
+ * @returns The result of the function
+ */
+declare function runWithContext<T>(context: ScopedContext, fn: () => T): T;
+/**
+ * Run an async function within an isolated context.
+ */
+declare function runWithContextAsync<T>(context: ScopedContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Get the current request-scoped context.
+ * Returns undefined if not running within a context scope.
+ */
+declare function getRequestContext(): ScopedContext | undefined;
+/**
+ * Check if we're currently running within a scoped context
+ */
+declare function hasRequestContext(): boolean;
+/**
+ * Set user in the current request context (if available)
+ * Returns true if the user was set in request context, false otherwise
+ */
+declare function setRequestUser(user: UserContext | null): boolean;
+/**
+ * Set a tag in the current request context (if available)
+ * Returns true if the tag was set in request context, false otherwise
+ */
+declare function setRequestTag(key: string, value: string): boolean;
+/**
+ * Set extra data in the current request context (if available)
+ * Returns true if the extra was set in request context, false otherwise
+ */
+declare function setRequestExtra(key: string, value: unknown): boolean;
+/**
+ * Add a breadcrumb to the current request context (if available)
+ * Returns true if the breadcrumb was added to request context, false otherwise
+ */
+declare function addRequestBreadcrumb(breadcrumb: Breadcrumb, maxBreadcrumbs?: number): boolean;
+/**
+ * Get the merged context from request scope and global scope
+ */
+declare function getMergedContext(globalUser: UserContext | null, globalTags: Record<string, string>, globalExtra: Record<string, unknown>, globalBreadcrumbs: Breadcrumb[]): {
+    user: UserContext | null;
+    tags: Record<string, string>;
+    extra: Record<string, unknown>;
+    breadcrumbs: Breadcrumb[];
+};
+
+/**
+ * Initialize the global Bugwatch client.
+ *
+ * Reads configuration from environment variables if not explicitly provided:
+ * - `BUGWATCH_API_KEY` - API key (required)
+ * - `BUGWATCH_ENVIRONMENT` - Environment tag
+ * - `BUGWATCH_RELEASE` - Release version
+ * - `BUGWATCH_DEBUG` - Enable debug mode ('true')
+ *
+ * @param options - Configuration options (optional if BUGWATCH_API_KEY env var is set)
+ * @throws Error if no API key is provided and BUGWATCH_API_KEY is not set
+ *
+ * @example
+ * ```typescript
+ * // With env var BUGWATCH_API_KEY set
+ * init();
+ *
+ * // Or explicit configuration
+ * init({ apiKey: "bw_live_xxxxx" });
+ *
+ * // Mix of env vars and explicit options
+ * init({ environment: "staging" }); // Uses BUGWATCH_API_KEY from env
+ * ```
+ */
+declare function init(options?: Partial<BugwatchOptions>): Bugwatch;
 /**
  * Get the global Bugwatch client
  */
 declare function getClient(): Bugwatch | null;
 /**
- * Capture an exception using the global client
+ * Capture an exception using the global client.
+ *
+ * If the SDK is not initialized but BUGWATCH_API_KEY environment variable is set,
+ * the SDK will auto-initialize before capturing.
  */
 declare function captureException(error: Error, context?: Partial<ErrorEvent>): string;
 /**
- * Capture a message using the global client
+ * Capture a message using the global client.
+ *
+ * If the SDK is not initialized but BUGWATCH_API_KEY environment variable is set,
+ * the SDK will auto-initialize before capturing.
  */
 declare function captureMessage(message: string, level?: ErrorEvent["level"]): string;
 /**
- * Add a breadcrumb using the global client
+ * Add a breadcrumb using the global client.
+ * If called within a request context, adds to the request-scoped breadcrumbs.
  */
 declare function addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
 /**
- * Set user context on the global client
+ * Set user context.
+ * If called within a request context, sets the request-scoped user.
+ * Otherwise sets the global user context.
  */
 declare function setUser(user: UserContext | null): void;
 /**
- * Set a tag on the global client
+ * Set a tag.
+ * If called within a request context, sets the request-scoped tag.
+ * Otherwise sets the global tag.
  */
 declare function setTag(key: string, value: string): void;
 /**
- * Set extra context on the global client
+ * Set extra context.
+ * If called within a request context, sets the request-scoped extra.
+ * Otherwise sets the global extra context.
  */
 declare function setExtra(key: string, value: unknown): void;
+/**
+ * Flush any pending events using the global client.
+ * Call this before process exit to ensure no events are lost.
+ */
+declare function flush(): Promise<void>;
+/**
+ * Close the global client and release any resources.
+ * This flushes any pending events and closes the transport.
+ * After calling this method, the client should not be used again.
+ */
+declare function close(): Promise<void>;
+/**
+ * Reset the SDK state completely.
+ * Use this for testing or to allow re-initialization.
+ * Note: This does NOT flush pending events - call close() first if needed.
+ */
+declare function reset(): 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 };
+export { BatchTransport, type Breadcrumb, Bugwatch, type BugwatchClient, type BugwatchOptions, ConsoleTransport, ENV_VARS, type ErrorEvent, type ExceptionInfo, HttpTransport, type Integration, NoopTransport, type RequestContext, type RuntimeInfo, type ScopedContext, type SdkInfo, type StackFrame, type Transport, type UserContext, addBreadcrumb, addRequestBreadcrumb, captureException, captureMessage, close, createScopedContext, extractErrorInfo, fingerprintFromException, flush, generateFingerprint, getClient, getEnvConfig, getMergedContext, getRequestContext, hasApiKey, hasRequestContext, init, parseStackTrace, reset, runWithContext, runWithContextAsync, setExtra, setRequestExtra, setRequestTag, setRequestUser, setTag, setUser, validateApiKey };

package/dist/index.d.ts

@@ -131,6 +131,16 @@ interface ErrorEvent {
  */
 interface Transport {
     send(event: ErrorEvent): Promise<void>;
+    /**
+     * Flush any pending events.
+     * Ensures all queued events are sent before the promise resolves.
+     */
+    flush?(): Promise<void>;
+    /**
+     * Close the transport and release any resources.
+     * After calling this method, the transport should not be used again.
+     */
+    close?(): Promise<void>;
 }
 /**
  * Integration interface for platform-specific functionality
@@ -150,6 +160,16 @@ interface BugwatchClient {
     setTag(key: string, value: string): void;
     setExtra(key: string, value: unknown): void;
     getOptions(): BugwatchOptions;
+    /**
+     * Flush any pending events.
+     * Call this before process exit to ensure no events are lost.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the client and release any resources.
+     * This flushes any pending events and closes the transport.
+     */
+    close(): Promise<void>;
 }
 
 /**
@@ -218,6 +238,17 @@ declare class Bugwatch implements BugwatchClient {
      * Detect the current platform
      */
     private detectPlatform;
+    /**
+     * Flush any pending events.
+     * Call this before process exit to ensure no events are lost.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the client and release any resources.
+     * This flushes any pending events and closes the transport.
+     * After calling this method, the client should not be used again.
+     */
+    close(): Promise<void>;
 }
 
 /**
@@ -263,6 +294,10 @@ declare class BatchTransport implements Transport {
     flush(): Promise<void>;
     private startTimer;
     destroy(): void;
+    /**
+     * Close the transport, flushing any remaining events and stopping the timer.
+     */
+    close(): Promise<void>;
 }
 
 /**
@@ -288,36 +323,228 @@ declare function generateFingerprint(errorType: string, message: string, stacktr
 declare function fingerprintFromException(exception: ExceptionInfo): string;
 
 /**
- * Initialize the global Bugwatch client
+ * Environment variable utilities for Bugwatch SDK.
+ *
+ * This module provides functions for reading configuration from environment
+ * variables and validating API keys.
  */
-declare function init(options: BugwatchOptions): Bugwatch;
+
+/**
+ * Supported environment variables for Bugwatch configuration.
+ */
+declare const ENV_VARS: {
+    readonly API_KEY: "BUGWATCH_API_KEY";
+    readonly ENVIRONMENT: "BUGWATCH_ENVIRONMENT";
+    readonly RELEASE: "BUGWATCH_RELEASE";
+    readonly DEBUG: "BUGWATCH_DEBUG";
+    readonly ENDPOINT: "BUGWATCH_ENDPOINT";
+};
+/**
+ * Read Bugwatch configuration from environment variables.
+ *
+ * Supported environment variables:
+ * - `BUGWATCH_API_KEY` - API key (required unless passed explicitly)
+ * - `BUGWATCH_ENVIRONMENT` - Environment tag (e.g., 'production', 'staging')
+ * - `BUGWATCH_RELEASE` - Release version
+ * - `BUGWATCH_DEBUG` - Enable debug mode ('true' to enable)
+ * - `BUGWATCH_ENDPOINT` - Custom API endpoint
+ *
+ * @returns Partial configuration from environment variables
+ *
+ * @example
+ * ```typescript
+ * // Set environment variables
+ * // BUGWATCH_API_KEY=bw_live_xxxxx
+ * // BUGWATCH_ENVIRONMENT=production
+ *
+ * const envConfig = getEnvConfig();
+ * // { apiKey: 'bw_live_xxxxx', environment: 'production' }
+ * ```
+ */
+declare function getEnvConfig(): Partial<BugwatchOptions>;
+/**
+ * Validate an API key and throw a clear error if invalid.
+ *
+ * @param key - The API key to validate
+ * @throws Error if the API key is missing or invalid
+ *
+ * @example
+ * ```typescript
+ * // Missing API key
+ * validateApiKey(undefined);
+ * // throws: "Bugwatch: API key required. Set BUGWATCH_API_KEY environment variable or pass { apiKey: '...' }"
+ *
+ * // Invalid format (logs warning but doesn't throw)
+ * validateApiKey("invalid-key");
+ * // warns: "Bugwatch: API key should start with 'bw_'. Got 'invali...'"
+ * ```
+ */
+declare function validateApiKey(key: string | undefined): asserts key is string;
+/**
+ * Check if API key is available (either in env or passed explicitly).
+ *
+ * @param explicitKey - Explicitly provided API key
+ * @returns true if an API key is available
+ */
+declare function hasApiKey(explicitKey?: string): boolean;
+
+/**
+ * Request-scoped context using AsyncLocalStorage.
+ *
+ * This module provides thread-safe, request-isolated context storage
+ * for Node.js environments. Each concurrent request gets its own
+ * isolated context that won't leak to other requests.
+ */
+
+/**
+ * Request-scoped context that is isolated per request
+ */
+interface ScopedContext {
+    user: UserContext | null;
+    tags: Record<string, string>;
+    extra: Record<string, unknown>;
+    breadcrumbs: Breadcrumb[];
+}
+/**
+ * Create a new empty scoped context
+ */
+declare function createScopedContext(): ScopedContext;
+/**
+ * Run a function within an isolated context.
+ *
+ * All context operations (setUser, setTag, etc.) within this function
+ * will be scoped to this context and won't affect other concurrent requests.
+ *
+ * @param context - The initial context for this scope
+ * @param fn - The function to run within the context
+ * @returns The result of the function
+ */
+declare function runWithContext<T>(context: ScopedContext, fn: () => T): T;
+/**
+ * Run an async function within an isolated context.
+ */
+declare function runWithContextAsync<T>(context: ScopedContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Get the current request-scoped context.
+ * Returns undefined if not running within a context scope.
+ */
+declare function getRequestContext(): ScopedContext | undefined;
+/**
+ * Check if we're currently running within a scoped context
+ */
+declare function hasRequestContext(): boolean;
+/**
+ * Set user in the current request context (if available)
+ * Returns true if the user was set in request context, false otherwise
+ */
+declare function setRequestUser(user: UserContext | null): boolean;
+/**
+ * Set a tag in the current request context (if available)
+ * Returns true if the tag was set in request context, false otherwise
+ */
+declare function setRequestTag(key: string, value: string): boolean;
+/**
+ * Set extra data in the current request context (if available)
+ * Returns true if the extra was set in request context, false otherwise
+ */
+declare function setRequestExtra(key: string, value: unknown): boolean;
+/**
+ * Add a breadcrumb to the current request context (if available)
+ * Returns true if the breadcrumb was added to request context, false otherwise
+ */
+declare function addRequestBreadcrumb(breadcrumb: Breadcrumb, maxBreadcrumbs?: number): boolean;
+/**
+ * Get the merged context from request scope and global scope
+ */
+declare function getMergedContext(globalUser: UserContext | null, globalTags: Record<string, string>, globalExtra: Record<string, unknown>, globalBreadcrumbs: Breadcrumb[]): {
+    user: UserContext | null;
+    tags: Record<string, string>;
+    extra: Record<string, unknown>;
+    breadcrumbs: Breadcrumb[];
+};
+
+/**
+ * Initialize the global Bugwatch client.
+ *
+ * Reads configuration from environment variables if not explicitly provided:
+ * - `BUGWATCH_API_KEY` - API key (required)
+ * - `BUGWATCH_ENVIRONMENT` - Environment tag
+ * - `BUGWATCH_RELEASE` - Release version
+ * - `BUGWATCH_DEBUG` - Enable debug mode ('true')
+ *
+ * @param options - Configuration options (optional if BUGWATCH_API_KEY env var is set)
+ * @throws Error if no API key is provided and BUGWATCH_API_KEY is not set
+ *
+ * @example
+ * ```typescript
+ * // With env var BUGWATCH_API_KEY set
+ * init();
+ *
+ * // Or explicit configuration
+ * init({ apiKey: "bw_live_xxxxx" });
+ *
+ * // Mix of env vars and explicit options
+ * init({ environment: "staging" }); // Uses BUGWATCH_API_KEY from env
+ * ```
+ */
+declare function init(options?: Partial<BugwatchOptions>): Bugwatch;
 /**
  * Get the global Bugwatch client
  */
 declare function getClient(): Bugwatch | null;
 /**
- * Capture an exception using the global client
+ * Capture an exception using the global client.
+ *
+ * If the SDK is not initialized but BUGWATCH_API_KEY environment variable is set,
+ * the SDK will auto-initialize before capturing.
  */
 declare function captureException(error: Error, context?: Partial<ErrorEvent>): string;
 /**
- * Capture a message using the global client
+ * Capture a message using the global client.
+ *
+ * If the SDK is not initialized but BUGWATCH_API_KEY environment variable is set,
+ * the SDK will auto-initialize before capturing.
  */
 declare function captureMessage(message: string, level?: ErrorEvent["level"]): string;
 /**
- * Add a breadcrumb using the global client
+ * Add a breadcrumb using the global client.
+ * If called within a request context, adds to the request-scoped breadcrumbs.
  */
 declare function addBreadcrumb(breadcrumb: Omit<Breadcrumb, "timestamp">): void;
 /**
- * Set user context on the global client
+ * Set user context.
+ * If called within a request context, sets the request-scoped user.
+ * Otherwise sets the global user context.
  */
 declare function setUser(user: UserContext | null): void;
 /**
- * Set a tag on the global client
+ * Set a tag.
+ * If called within a request context, sets the request-scoped tag.
+ * Otherwise sets the global tag.
  */
 declare function setTag(key: string, value: string): void;
 /**
- * Set extra context on the global client
+ * Set extra context.
+ * If called within a request context, sets the request-scoped extra.
+ * Otherwise sets the global extra context.
  */
 declare function setExtra(key: string, value: unknown): void;
+/**
+ * Flush any pending events using the global client.
+ * Call this before process exit to ensure no events are lost.
+ */
+declare function flush(): Promise<void>;
+/**
+ * Close the global client and release any resources.
+ * This flushes any pending events and closes the transport.
+ * After calling this method, the client should not be used again.
+ */
+declare function close(): Promise<void>;
+/**
+ * Reset the SDK state completely.
+ * Use this for testing or to allow re-initialization.
+ * Note: This does NOT flush pending events - call close() first if needed.
+ */
+declare function reset(): 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 };
+export { BatchTransport, type Breadcrumb, Bugwatch, type BugwatchClient, type BugwatchOptions, ConsoleTransport, ENV_VARS, type ErrorEvent, type ExceptionInfo, HttpTransport, type Integration, NoopTransport, type RequestContext, type RuntimeInfo, type ScopedContext, type SdkInfo, type StackFrame, type Transport, type UserContext, addBreadcrumb, addRequestBreadcrumb, captureException, captureMessage, close, createScopedContext, extractErrorInfo, fingerprintFromException, flush, generateFingerprint, getClient, getEnvConfig, getMergedContext, getRequestContext, hasApiKey, hasRequestContext, init, parseStackTrace, reset, runWithContext, runWithContextAsync, setExtra, setRequestExtra, setRequestTag, setRequestUser, setTag, setUser, validateApiKey };