bugstack-sdk 1.0.0

package/README.md

@@ -0,0 +1,317 @@
+# bugstack-sdk
+
+Error capture SDK for Next.js 14+ App Router API routes. Automatically captures errors with full context and reports them to the BugStack service for AI-powered fix generation.
+
+**Get your API key at:** https://dashboard.bugstack.ai
+
+## Features
+
+- **Zero-config wrapping** - Simply wrap your route handlers with `withErrorCapture`
+- **Full error context** - Captures stack traces, request body, headers, query params
+- **Automatic sanitization** - Sensitive data (passwords, tokens, etc.) is automatically redacted
+- **Non-blocking** - Error reporting happens asynchronously without slowing down responses
+- **TypeScript first** - Full type safety with comprehensive type definitions
+- **Production ready** - Configurable timeouts, error handling, and kill switches
+
+## Installation
+
+```bash
+npm install bugstack-sdk
+# or
+pnpm add bugstack-sdk
+# or
+yarn add bugstack-sdk
+```
+
+## Quick Start
+
+### 1. Initialize the client (once, in a shared file)
+
+```typescript
+// lib/bugstack.ts
+import { ErrorCaptureClient } from "bugstack-sdk";
+
+export const bugstack = ErrorCaptureClient.init({
+  apiKey: process.env.BUGSTACK_API_KEY!,
+  projectId: "my-project",
+  // Optional: customize endpoint
+  // endpoint: "https://your-bugstack-server.com/api/capture",
+});
+```
+
+### 2. Wrap your API routes
+
+```typescript
+// app/api/users/route.ts
+import { NextResponse } from "next/server";
+import { withErrorCapture } from "bugstack-sdk";
+import "@/lib/bugstack"; // Ensure client is initialized
+
+export const GET = withErrorCapture(async (request) => {
+  const users = await db.users.findMany();
+  return NextResponse.json({ users });
+});
+
+export const POST = withErrorCapture(async (request) => {
+  const body = await request.json();
+  const user = await db.users.create({ data: body });
+  return NextResponse.json({ user }, { status: 201 });
+});
+```
+
+### 3. Dynamic routes with params
+
+```typescript
+// app/api/users/[id]/route.ts
+import { NextResponse } from "next/server";
+import { withErrorCapture } from "bugstack-sdk";
+import "@/lib/bugstack";
+
+export const GET = withErrorCapture<{ id: string }>(
+  async (request, { params }) => {
+    const user = await db.users.findUnique({
+      where: { id: params.id },
+    });
+
+    if (!user) {
+      throw new Error("User not found");
+    }
+
+    return NextResponse.json({ user });
+  }
+);
+```
+
+## Configuration
+
+### Full Configuration Options
+
+```typescript
+import { ErrorCaptureClient } from "bugstack-sdk";
+
+ErrorCaptureClient.init({
+  // Required
+  apiKey: "your-api-key",
+
+  // Optional - defaults shown
+  endpoint: "http://localhost:3001/api/capture",
+  projectId: "",
+  environment: process.env.NODE_ENV, // "development", "production", etc.
+  enabled: true, // Set to false to disable capture
+
+  // Request capture options
+  captureRequestBody: true,
+  captureQueryParams: true,
+  captureHeaders: true,
+  maxBodySize: 10000, // 10KB max body capture
+
+  // Additional fields to redact (added to defaults)
+  redactFields: ["customSecret", "internalToken"],
+
+  // Custom metadata included with every error
+  metadata: {
+    service: "api",
+    version: "1.0.0",
+  },
+
+  // Network options
+  timeout: 5000, // 5 second timeout for error reporting
+
+  // Debug logging (defaults to true in development)
+  debug: true,
+
+  // Custom filter - return false to skip certain errors
+  shouldCapture: (error, request) => {
+    // Don't capture 404s
+    if (error.message.includes("not found")) {
+      return false;
+    }
+    return true;
+  },
+
+  // Transform errors before sending
+  beforeSend: (capturedError) => {
+    // Add custom data
+    capturedError.metadata = {
+      ...capturedError.metadata,
+      customField: "value",
+    };
+    return capturedError;
+    // Return null to skip this error
+  },
+});
+```
+
+### Environment Variables
+
+The SDK automatically reads these environment variables:
+
+```bash
+# Required
+BUGSTACK_API_KEY=your-api-key
+
+# Optional
+BUGSTACK_ENDPOINT=https://bugstack-error-service.onrender.com/api/capture
+BUGSTACK_PROJECT_ID=my-project
+NODE_ENV=production
+```
+
+**Note:** The default endpoint is `http://localhost:3001/api/capture` for local development. Set `BUGSTACK_ENDPOINT` to the production URL shown above for deployed applications.
+
+### Per-Route Options
+
+You can override options for specific routes:
+
+```typescript
+export const POST = withErrorCapture(
+  async (request) => {
+    // handler code
+  },
+  undefined, // Use existing client config
+  {
+    // Route-specific options
+    statusCode: 400, // Report as 400 instead of 500
+    metadata: {
+      operation: "createUser",
+      critical: true,
+    },
+    shouldCapture: (error) => {
+      // Route-specific filter
+      return error.name !== "ValidationError";
+    },
+  }
+);
+```
+
+## Captured Error Data
+
+Each error report includes:
+
+```typescript
+interface CapturedError {
+  id: string;                    // Unique error ID (err_xxx_xxx)
+  name: string;                  // Error name (TypeError, etc.)
+  message: string;               // Error message
+  stack: string;                 // Full stack trace
+  stackFrames: StackFrame[];     // Parsed stack frames
+  timestamp: string;             // ISO 8601 timestamp
+  route: string;                 // API route path
+  method: string;                // HTTP method
+  statusCode: number;            // HTTP status code
+  url: string;                   // Full request URL
+  queryParams: object;           // Query parameters (sanitized)
+  requestBody: unknown;          // Request body (sanitized)
+  requestHeaders: object;        // Headers (sanitized)
+  routeParams: object;           // Dynamic route params
+  environment: string;           // Environment name
+  projectId: string;             // Project identifier
+  sdkVersion: string;            // SDK version
+  nodeVersion: string;           // Node.js version
+  nextVersion: string;           // Next.js version
+  metadata: object;              // Custom metadata
+}
+```
+
+## Automatic Data Sanitization
+
+The SDK automatically redacts sensitive fields from:
+- Request headers (Authorization, Cookie, etc.)
+- Request body
+- Query parameters
+
+**Default redacted fields:**
+- password, secret, token
+- apikey, api_key, apiKey
+- authorization, auth, credential
+- credit_card, creditcard, card_number
+- cvv, ssn, social_security
+
+Add custom fields via `redactFields` config option.
+
+## Error Handling
+
+The SDK is designed to never interfere with your application:
+
+- **Network failures** - Silently ignored, your app continues normally
+- **Timeouts** - Configurable, defaults to 5 seconds
+- **SDK errors** - Caught and logged (in debug mode), never thrown
+- **Re-throws original error** - Next.js still handles the error response
+
+## Advanced Usage
+
+### Manual Error Reporting
+
+```typescript
+import { ErrorCaptureClient } from "bugstack-sdk";
+
+const client = ErrorCaptureClient.getInstance();
+
+if (client) {
+  await client.reportError({
+    id: "manual_001",
+    name: "CustomError",
+    message: "Something went wrong",
+    timestamp: new Date().toISOString(),
+    route: "/api/custom",
+    method: "POST",
+    statusCode: 500,
+    url: "https://example.com/api/custom",
+    environment: "production",
+    sdkVersion: "1.0.0",
+    nodeVersion: process.version,
+  });
+}
+```
+
+### Stack Trace Utilities
+
+```typescript
+import {
+  parseStackTrace,
+  getFirstAppFrame,
+  getAppFrames,
+} from "bugstack-sdk";
+
+const frames = parseStackTrace(error.stack);
+const firstAppFrame = getFirstAppFrame(frames); // First non-node_modules frame
+const appFrames = getAppFrames(frames); // All application frames
+```
+
+### Sanitization Utilities
+
+```typescript
+import {
+  sanitizeHeaders,
+  sanitizeQueryParams,
+  sanitizeObject,
+} from "bugstack-sdk";
+
+const safeHeaders = sanitizeHeaders(request.headers);
+const safeParams = sanitizeQueryParams(new URL(request.url));
+const safeBody = sanitizeObject(requestBody);
+```
+
+## TypeScript Support
+
+Full type definitions are included:
+
+```typescript
+import type {
+  ErrorCaptureConfig,
+  CapturedError,
+  StackFrame,
+  RouteOptions,
+  NextRouteHandler,
+  RouteContext,
+} from "bugstack-sdk";
+```
+
+## Compatibility
+
+- **Next.js**: 14.0.0+
+- **Node.js**: 18.0.0+
+- **TypeScript**: 5.0.0+ (optional)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,391 @@
+import { NextRequest } from 'next/server';
+
+/**
+ * Configuration options for the BugStack error capture SDK
+ */
+interface ErrorCaptureConfig {
+    /**
+     * API key for authenticating with the BugStack error service
+     */
+    apiKey: string;
+    /**
+     * URL of the BugStack error service endpoint
+     * @default process.env.BUGSTACK_ENDPOINT || "http://localhost:3001/api/errors"
+     */
+    endpoint?: string;
+    /**
+     * Unique identifier for your project
+     */
+    projectId?: string;
+    /**
+     * Environment name (e.g., "production", "staging", "development")
+     * @default process.env.NODE_ENV || "development"
+     */
+    environment?: string;
+    /**
+     * Enable or disable error capture
+     * Useful for disabling in certain environments
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to capture request body in error reports
+     * @default true
+     */
+    captureRequestBody?: boolean;
+    /**
+     * Whether to capture query parameters in error reports
+     * @default true
+     */
+    captureQueryParams?: boolean;
+    /**
+     * Whether to capture request headers in error reports
+     * @default true
+     */
+    captureHeaders?: boolean;
+    /**
+     * Maximum size of request body to capture (in bytes)
+     * Bodies larger than this will be truncated
+     * @default 10000 (10KB)
+     */
+    maxBodySize?: number;
+    /**
+     * Additional fields to redact from request body and headers
+     * Common sensitive fields are redacted by default
+     */
+    redactFields?: string[];
+    /**
+     * Custom metadata to include with every error report
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Timeout for sending error reports (in milliseconds)
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * Whether to log SDK errors to console
+     * @default true in development, false in production
+     */
+    debug?: boolean;
+    /**
+     * Custom error filter function
+     * Return false to skip reporting certain errors
+     */
+    shouldCapture?: (error: Error, request: NextRequest) => boolean;
+    /**
+     * Hook called before sending error report
+     * Can be used to modify or enrich error data
+     */
+    beforeSend?: (error: CapturedError) => CapturedError | null;
+}
+/**
+ * Resolved configuration with all defaults applied
+ */
+interface ResolvedConfig {
+    apiKey: string;
+    endpoint: string;
+    projectId: string;
+    environment: string;
+    enabled: boolean;
+    captureRequestBody: boolean;
+    captureQueryParams: boolean;
+    captureHeaders: boolean;
+    maxBodySize: number;
+    redactFields: string[];
+    metadata: Record<string, unknown>;
+    timeout: number;
+    debug: boolean;
+    shouldCapture?: (error: Error, request: NextRequest) => boolean;
+    beforeSend?: (error: CapturedError) => CapturedError | null;
+}
+/**
+ * Captured error data sent to the error service
+ */
+interface CapturedError {
+    /**
+     * Unique identifier for this error instance
+     */
+    id: string;
+    /**
+     * Error message
+     */
+    message: string;
+    /**
+     * Error name/type (e.g., "TypeError", "ReferenceError")
+     */
+    name: string;
+    /**
+     * Full stack trace
+     */
+    stack?: string;
+    /**
+     * Parsed stack frames for easier analysis
+     */
+    stackFrames?: StackFrame[];
+    /**
+     * ISO 8601 timestamp when the error occurred
+     */
+    timestamp: string;
+    /**
+     * API route path (e.g., "/api/users/[id]")
+     */
+    route: string;
+    /**
+     * HTTP method (GET, POST, etc.)
+     */
+    method: string;
+    /**
+     * HTTP status code
+     * @default 500
+     */
+    statusCode: number;
+    /**
+     * Full request URL
+     */
+    url: string;
+    /**
+     * Query parameters (sanitized)
+     */
+    queryParams?: Record<string, string>;
+    /**
+     * Request body (sanitized and truncated)
+     */
+    requestBody?: unknown;
+    /**
+     * Request headers (sanitized)
+     */
+    requestHeaders?: Record<string, string>;
+    /**
+     * Environment (production, staging, development)
+     */
+    environment: string;
+    /**
+     * Project identifier
+     */
+    projectId?: string;
+    /**
+     * Route parameters (e.g., { id: "123" })
+     */
+    routeParams?: Record<string, string>;
+    /**
+     * Additional custom metadata
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * SDK version that captured this error
+     */
+    sdkVersion: string;
+    /**
+     * Node.js version
+     */
+    nodeVersion: string;
+    /**
+     * Next.js version (if available)
+     */
+    nextVersion?: string;
+}
+/**
+ * Parsed stack frame for easier debugging
+ */
+interface StackFrame {
+    /**
+     * Function name
+     */
+    function?: string;
+    /**
+     * File path
+     */
+    file?: string;
+    /**
+     * Line number
+     */
+    line?: number;
+    /**
+     * Column number
+     */
+    column?: number;
+    /**
+     * Whether this frame is from node_modules
+     */
+    isNodeModule?: boolean;
+    /**
+     * Whether this frame is from internal Node.js code
+     */
+    isInternal?: boolean;
+}
+/**
+ * Payload sent to the error service
+ */
+interface ErrorReportPayload {
+    /**
+     * The captured error data
+     */
+    error: CapturedError;
+    /**
+     * Source code context around the error (if available)
+     */
+    sourceContext?: SourceContext;
+}
+/**
+ * Source code context around the error location
+ */
+interface SourceContext {
+    /**
+     * File path
+     */
+    filePath: string;
+    /**
+     * Line number where error occurred
+     */
+    lineNumber: number;
+    /**
+     * Lines of code before the error line
+     */
+    preContext: string[];
+    /**
+     * The line where the error occurred
+     */
+    contextLine: string;
+    /**
+     * Lines of code after the error line
+     */
+    postContext: string[];
+}
+/**
+ * Next.js App Router route handler type
+ */
+type NextRouteHandler<T = unknown> = (request: NextRequest, context: RouteContext<T>) => Response | Promise<Response>;
+/**
+ * Route context passed to Next.js handlers
+ */
+interface RouteContext<T = unknown> {
+    params: T extends Record<string, string> ? T : Record<string, string>;
+}
+/**
+ * Options that can be passed to withErrorCapture per-route
+ */
+interface RouteOptions {
+    /**
+     * Override the status code reported for errors in this route
+     */
+    statusCode?: number;
+    /**
+     * Additional metadata specific to this route
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Custom error filter for this route
+     */
+    shouldCapture?: (error: Error) => boolean;
+}
+type BugStackConfig = ErrorCaptureConfig;
+
+/**
+ * Type for the wrapped handler function
+ */
+type WrappedHandler<T> = (request: NextRequest, context: RouteContext<T>) => Response | Promise<Response>;
+/**
+ * Wrap a Next.js App Router API route handler with error capture
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * export const GET = withErrorCapture(async (request) => {
+ *   return NextResponse.json({ data: "hello" });
+ * });
+ *
+ * // With configuration (first call only)
+ * export const GET = withErrorCapture(
+ *   async (request) => {
+ *     return NextResponse.json({ data: "hello" });
+ *   },
+ *   { apiKey: "your-api-key" }
+ * );
+ *
+ * // With route-specific options
+ * export const POST = withErrorCapture(
+ *   async (request) => {
+ *     return NextResponse.json({ data: "created" });
+ *   },
+ *   undefined,
+ *   { statusCode: 400, metadata: { operation: "create" } }
+ * );
+ * ```
+ */
+declare function withErrorCapture<T = Record<string, string>>(handler: WrappedHandler<T>, config?: ErrorCaptureConfig, routeOptions?: RouteOptions): WrappedHandler<T>;
+declare const withBugStack: typeof withErrorCapture;
+
+/**
+ * BugStack Error Capture Client
+ *
+ * Singleton client for capturing and reporting errors to the BugStack service.
+ */
+declare class ErrorCaptureClient {
+    private config;
+    private static instance;
+    constructor(config: ErrorCaptureConfig);
+    /**
+     * Initialize the singleton client instance
+     */
+    static init(config: ErrorCaptureConfig): ErrorCaptureClient;
+    /**
+     * Get the singleton client instance
+     */
+    static getInstance(): ErrorCaptureClient | null;
+    /**
+     * Check if the client has been initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Reset the client (mainly for testing)
+     */
+    static reset(): void;
+    /**
+     * Report an error to the BugStack service
+     */
+    reportError(error: CapturedError, sourceContext?: SourceContext): Promise<boolean>;
+    /**
+     * Get the resolved configuration
+     */
+    getConfig(): ResolvedConfig;
+    /**
+     * Check if a field should be redacted
+     */
+    shouldRedact(fieldName: string): boolean;
+    /**
+     * Get the SDK version
+     */
+    static getVersion(): string;
+    private log;
+    private logError;
+}
+declare const BugStackClient: typeof ErrorCaptureClient;
+
+/**
+ * Parse a V8 stack trace into structured frames
+ */
+declare function parseStackTrace(stack: string | undefined): StackFrame[];
+/**
+ * Get the first application frame (non-node_modules, non-internal)
+ */
+declare function getFirstAppFrame(frames: StackFrame[]): StackFrame | undefined;
+/**
+ * Filter stack frames to only include application code
+ */
+declare function getAppFrames(frames: StackFrame[]): StackFrame[];
+
+/**
+ * Sanitize headers by removing sensitive values
+ */
+declare function sanitizeHeaders(headers: Headers, client?: ErrorCaptureClient | null): Record<string, string>;
+/**
+ * Sanitize query parameters by redacting sensitive values
+ */
+declare function sanitizeQueryParams(url: URL, client?: ErrorCaptureClient | null): Record<string, string>;
+/**
+ * Recursively sanitize an object by redacting sensitive fields
+ */
+declare function sanitizeObject(obj: unknown, client?: ErrorCaptureClient | null, maxDepth?: number, currentDepth?: number): unknown;
+
+export { BugStackClient, type BugStackConfig, type CapturedError, ErrorCaptureClient, type ErrorCaptureConfig, type ErrorReportPayload, type NextRouteHandler, type ResolvedConfig, type RouteContext, type RouteOptions, type SourceContext, type StackFrame, getAppFrames, getFirstAppFrame, parseStackTrace, sanitizeHeaders, sanitizeObject, sanitizeQueryParams, withBugStack, withErrorCapture };