@deeptracer/core 0.2.0 → 0.3.1

package/dist/internal-DdKQRgCs.d.cts

@@ -0,0 +1,375 @@
+/**
+ * Configuration for creating a DeepTracer logger instance.
+ *
+ * @example
+ * ```ts
+ * const config: LoggerConfig = {
+ *   product: "my-app",
+ *   service: "api-server",
+ *   environment: "production",
+ *   endpoint: "https://deeptracer.example.com",
+ *   apiKey: "dt_live_xxx",
+ * }
+ * ```
+ */
+interface LoggerConfig {
+    /** Product name (e.g., "spotbeam", "macro") */
+    product: string;
+    /** Service name (e.g., "api", "worker", "web") */
+    service: string;
+    /** Deployment environment */
+    environment: "production" | "staging";
+    /** DeepTracer ingestion endpoint URL */
+    endpoint: string;
+    /** DeepTracer API key for authentication */
+    apiKey: string;
+    /** Number of log entries to batch before sending. Default: 50 */
+    batchSize?: number;
+    /** Milliseconds between automatic batch flushes. Default: 5000 */
+    flushIntervalMs?: number;
+    /** Enable console output for all log calls (useful for local development) */
+    debug?: boolean;
+    /** Maximum breadcrumbs to retain for error reports. Default: 20 */
+    maxBreadcrumbs?: number;
+    /**
+     * Hook to inspect, modify, or drop events before they are sent to DeepTracer.
+     * Return the event (possibly modified) to send it, or return `null` to drop it.
+     *
+     * @example
+     * ```ts
+     * beforeSend: (event) => {
+     *   // Scrub PII
+     *   if (event.type === "error" && event.data.context?.password) {
+     *     delete event.data.context.password
+     *   }
+     *   // Drop health-check logs
+     *   if (event.type === "log" && event.data.message.includes("/health")) {
+     *     return null
+     *   }
+     *   return event
+     * }
+     * ```
+     */
+    beforeSend?: (event: BeforeSendEvent) => BeforeSendEvent | null;
+}
+/** Log severity level */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * A single log entry sent to the DeepTracer backend.
+ * Created internally by the Logger — you don't construct these manually.
+ */
+interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    metadata?: Record<string, unknown>;
+    trace_id?: string;
+    span_id?: string;
+    request_id?: string;
+    vercel_id?: string;
+    context?: string;
+}
+/**
+ * A breadcrumb entry — a trail of events leading up to an error.
+ * Automatically captured by the SDK; also settable manually via `addBreadcrumb()`.
+ *
+ * Dashboard icon mapping: `http`, `db`, `function`, `user`, `error` → specific icons.
+ */
+interface Breadcrumb {
+    /** Activity category (http, db, function, user, error, log, or custom) */
+    type: string;
+    /** Human-readable description (e.g., "POST /api/cart", "User loaded dashboard") */
+    message: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+/**
+ * Error report sent to DeepTracer for tracking and alerting.
+ */
+interface ErrorReport {
+    error_message: string;
+    stack_trace: string;
+    severity: "low" | "medium" | "high" | "critical";
+    context?: Record<string, unknown>;
+    trace_id?: string;
+    user_id?: string;
+    breadcrumbs?: Breadcrumb[];
+}
+/**
+ * LLM usage report for tracking AI costs and performance.
+ */
+interface LLMUsageReport {
+    model: string;
+    provider: string;
+    operation: string;
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+    costUsd?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Raw span data sent to the DeepTracer backend.
+ */
+interface SpanData {
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string;
+    operation: string;
+    start_time: string;
+    duration_ms: number;
+    status: "ok" | "error";
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A span representing a unit of work within a trace.
+ * Returned by the callback-based `startSpan()` — lifecycle is managed automatically.
+ */
+interface Span {
+    /** Trace ID linking all spans in a distributed trace */
+    traceId: string;
+    /** Unique ID for this span */
+    spanId: string;
+    /** ID of the parent span (empty string if root span) */
+    parentSpanId: string;
+    /** Operation name (e.g., "db-query", "fetch-user") */
+    operation: string;
+    /** Returns headers for propagating trace context to downstream services */
+    getHeaders(): Record<string, string>;
+}
+/**
+ * A span with manual lifecycle control. You must call `.end()` when done.
+ */
+interface InactiveSpan extends Span {
+    /** End the span and send timing data to DeepTracer */
+    end(options?: {
+        status?: "ok" | "error";
+        metadata?: Record<string, unknown>;
+    }): void;
+    /** Create a child span with callback-based lifecycle (auto-ends) */
+    startSpan<T>(operation: string, fn: (span: Span) => T): T;
+    /** Create a child span with manual lifecycle (you must call .end()) */
+    startInactiveSpan(operation: string): InactiveSpan;
+}
+/**
+ * Options for HTTP middleware (Hono, Express).
+ */
+interface MiddlewareOptions {
+    /** Custom function to generate the span operation name. Default: "{METHOD} {path}" */
+    operationName?: (method: string, path: string) => string;
+    /** Paths to exclude from tracing (e.g., ["/health", "/ready"]) */
+    ignorePaths?: string[];
+}
+/**
+ * User context attached to all outgoing events.
+ * Set via `logger.setUser()`, cleared via `logger.clearUser()`.
+ *
+ * @example
+ * ```ts
+ * logger.setUser({ id: "u_123", email: "user@example.com" })
+ * ```
+ */
+interface User {
+    /** Unique user identifier (required) */
+    id: string;
+    /** User's email address */
+    email?: string;
+    /** Display name or username */
+    username?: string;
+    /** Any additional user attributes */
+    [key: string]: unknown;
+}
+/**
+ * Discriminated union for the `beforeSend` hook. Wraps every event type
+ * so the hook can inspect and modify events before they are sent.
+ */
+type BeforeSendEvent = {
+    type: "log";
+    data: LogEntry;
+} | {
+    type: "error";
+    data: ErrorReport;
+} | {
+    type: "trace";
+    data: SpanData;
+} | {
+    type: "llm";
+    data: LLMUsageReport;
+};
+
+/**
+ * Shared mutable state across a Logger and all its child loggers.
+ * The root Logger creates this; `withContext()` and `forRequest()` pass
+ * the same reference so mutations (setUser, addBreadcrumb, etc.) are
+ * visible everywhere.
+ */
+interface LoggerState {
+    /** Current user context, set via setUser() */
+    user: User | null;
+    /** Global tags (flat string key-values), merged as metadata._tags */
+    tags: Record<string, string>;
+    /** Named context blocks, merged as metadata._contexts.{name} */
+    contexts: Record<string, Record<string, unknown>>;
+    /** Ring buffer of breadcrumbs for error reports */
+    breadcrumbs: Breadcrumb[];
+    /** Max breadcrumbs to retain */
+    maxBreadcrumbs: number;
+}
+
+/**
+ * Original console methods, preserved before any interception.
+ * Used internally by the Logger's debug output to avoid infinite loops
+ * when captureConsole() is active.
+ *
+ * @internal Exported for use by @deeptracer/node and @deeptracer/browser.
+ */
+declare const _originalConsole: {
+    log: (...data: any[]) => void;
+    info: (...data: any[]) => void;
+    warn: (...data: any[]) => void;
+    error: (...data: any[]) => void;
+    debug: (...data: any[]) => void;
+};
+/**
+ * DeepTracer Logger — lightweight observability SDK for logging, errors, tracing, and LLM usage.
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from "@deeptracer/core"
+ *
+ * const logger = createLogger({
+ *   product: "my-app",
+ *   service: "api",
+ *   environment: "production",
+ *   endpoint: "https://deeptracer.example.com",
+ *   apiKey: "dt_live_xxx",
+ * })
+ *
+ * logger.setUser({ id: "u_123", email: "user@example.com" })
+ * logger.setTags({ release: "1.2.3" })
+ * logger.info("Server started", { port: 3000 })
+ * ```
+ */
+declare class Logger {
+    private batcher;
+    private transport;
+    protected contextName?: string;
+    protected config: LoggerConfig;
+    protected state: LoggerState;
+    protected requestMeta?: {
+        trace_id?: string;
+        span_id?: string;
+        request_id?: string;
+        vercel_id?: string;
+    };
+    constructor(config: LoggerConfig, contextName?: string, requestMeta?: {
+        trace_id?: string;
+        span_id?: string;
+        request_id?: string;
+        vercel_id?: string;
+    }, state?: LoggerState);
+    /**
+     * Set the current user context. Attached to all subsequent logs, errors, spans, and LLM reports.
+     * Shared across all child loggers (withContext, forRequest).
+     *
+     * @example
+     * ```ts
+     * logger.setUser({ id: "u_123", email: "user@example.com", plan: "pro" })
+     * ```
+     */
+    setUser(user: User): void;
+    /** Clear the current user context. */
+    clearUser(): void;
+    /**
+     * Set global tags (flat string key-values). Merged into all events' metadata as `_tags`.
+     * Tags are indexed and searchable on the dashboard.
+     *
+     * @example
+     * ```ts
+     * logger.setTags({ release: "1.2.3", region: "us-east-1" })
+     * ```
+     */
+    setTags(tags: Record<string, string>): void;
+    /** Clear all global tags. */
+    clearTags(): void;
+    /**
+     * Set a named context block. Merged into metadata as `_contexts.{name}`.
+     * Contexts are structured objects attached for reference (not necessarily indexed).
+     *
+     * @example
+     * ```ts
+     * logger.setContext("server", { hostname: "web-3", memory: "4gb" })
+     * ```
+     */
+    setContext(name: string, data: Record<string, unknown>): void;
+    /** Clear a specific context block, or all contexts if no name is given. */
+    clearContext(name?: string): void;
+    /**
+     * Manually add a breadcrumb to the trail.
+     * Breadcrumbs are also recorded automatically for every log, span, and error.
+     *
+     * @example
+     * ```ts
+     * logger.addBreadcrumb({ type: "http", message: "POST /api/checkout" })
+     * ```
+     */
+    addBreadcrumb(breadcrumb: {
+        type: string;
+        message: string;
+        timestamp?: string;
+    }): void;
+    /** Merge user, tags, and contexts from shared state into event metadata. */
+    private mergeStateMetadata;
+    /** Run the beforeSend hook. If the hook throws, pass the event through. */
+    private applyBeforeSend;
+    private log;
+    /** Log a debug message. */
+    debug(message: string, dataOrError?: Record<string, unknown> | unknown, error?: unknown): void;
+    /** Log an informational message. */
+    info(message: string, dataOrError?: Record<string, unknown> | unknown, error?: unknown): void;
+    /** Log a warning. */
+    warn(message: string, dataOrError?: Record<string, unknown> | unknown, error?: unknown): void;
+    /** Log an error. */
+    error(message: string, dataOrError?: Record<string, unknown> | unknown, error?: unknown): void;
+    /** Create a context-scoped logger. All logs include the context name. Shares state with parent. */
+    withContext(name: string): Logger;
+    /** Create a request-scoped logger that extracts trace context from headers. Shares state with parent. */
+    forRequest(request: Request): Logger;
+    /**
+     * Capture and report an error immediately (not batched).
+     * Automatically attaches breadcrumbs from the buffer and user context.
+     */
+    captureError(error: Error | unknown, context?: {
+        severity?: "low" | "medium" | "high" | "critical";
+        userId?: string;
+        context?: Record<string, unknown>;
+        breadcrumbs?: Breadcrumb[];
+    }): void;
+    /** Track LLM usage. Sends to /ingest/llm and logs for visibility. */
+    llmUsage(report: LLMUsageReport): void;
+    /** Start a span with automatic lifecycle (callback-based, recommended). */
+    startSpan<T>(operation: string, fn: (span: Span) => T): T;
+    /** Start a span with manual lifecycle. You must call span.end(). */
+    startInactiveSpan(operation: string): InactiveSpan;
+    /** Wrap a function with automatic tracing and error capture. */
+    wrap<TArgs extends unknown[], TReturn>(operation: string, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+    /** Immediately flush all batched log entries. */
+    flush(): void;
+    /**
+     * Stop the batch timer, flush remaining logs, and wait for in-flight requests.
+     *
+     * @param timeoutMs - Max time to wait for in-flight requests (default: 2000ms)
+     * @returns Promise that resolves when all data is sent or timeout is reached
+     *
+     * @example
+     * ```ts
+     * await logger.destroy()
+     * process.exit(0) // safe — data is confirmed sent
+     * ```
+     */
+    destroy(timeoutMs?: number): Promise<void>;
+}
+/** Create a new DeepTracer logger instance. */
+declare function createLogger(config: LoggerConfig): Logger;
+
+export { type BeforeSendEvent as B, type ErrorReport as E, type InactiveSpan as I, type LLMUsageReport as L, type MiddlewareOptions as M, type Span as S, type User as U, _originalConsole as _, type Breadcrumb as a, type LogEntry as b, type LogLevel as c, Logger as d, type LoggerConfig as e, type SpanData as f, createLogger as g, type LoggerState as h };