@deeptracer/core 0.3.1 → 0.4.1

package/dist/{internal-DdKQRgCs.d.cts → logger-BDTEt7Gi.d.cts}

@@ -1,32 +1,56 @@
 /**
  * Configuration for creating a DeepTracer logger instance.
  *
+ * All fields are optional when environment variables are set.
+ * Server packages read `DEEPTRACER_SECRET_KEY`, `DEEPTRACER_ENDPOINT`, etc.
+ * Client packages read `NEXT_PUBLIC_DEEPTRACER_KEY`, `NEXT_PUBLIC_DEEPTRACER_ENDPOINT`, etc.
+ *
  * @example
+ * Server (Node.js / Next.js instrumentation):
  * ```ts
  * const config: LoggerConfig = {
- *   product: "my-app",
- *   service: "api-server",
+ *   secretKey: "dt_secret_xxx",
+ *   endpoint: "https://deeptracer.example.com",
+ *   service: "api",
  *   environment: "production",
+ * }
+ * ```
+ *
+ * @example
+ * Client (browser / React):
+ * ```ts
+ * const config: LoggerConfig = {
+ *   publicKey: "dt_public_xxx",
  *   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";
+    /** Server-side API key (prefix: `dt_secret_`). Never expose in client bundles. */
+    secretKey?: string;
+    /** Client-side API key (prefix: `dt_public_`). Safe for browser bundles. */
+    publicKey?: string;
+    /** Service name (e.g., "api", "worker", "web"). Default varies by package. */
+    service?: string;
+    /** Deployment environment (any string). Default: `NODE_ENV` or `"production"` */
+    environment?: string;
     /** DeepTracer ingestion endpoint URL */
-    endpoint: string;
-    /** DeepTracer API key for authentication */
-    apiKey: string;
+    endpoint?: string;
     /** Number of log entries to batch before sending. Default: 50 */
     batchSize?: number;
     /** Milliseconds between automatic batch flushes. Default: 5000 */
     flushIntervalMs?: number;
+    /**
+     * Minimum log level to send to DeepTracer.
+     *
+     * Logs below this level are silently filtered — they won't be batched or
+     * sent to the backend. Breadcrumbs are still recorded for filtered logs
+     * (so error reports retain full context).
+     *
+     * Default: `"info"` when `environment` is `"production"`, `"debug"` otherwise.
+     * Override via `DEEPTRACER_LOG_LEVEL` (server) or `NEXT_PUBLIC_DEEPTRACER_LOG_LEVEL` (client).
+     */
+    level?: LogLevel;
     /** Enable console output for all log calls (useful for local development) */
     debug?: boolean;
     /** Maximum breadcrumbs to retain for error reports. Default: 20 */
@@ -198,10 +222,10 @@ type BeforeSendEvent = {
 };
 
 /**
- * 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.
+ * Mutable state for a Logger instance.
+ * The root Logger creates this; `withContext()` and `forRequest()` clone it
+ * so each child logger gets an independent snapshot. Mutations on a child
+ * (setUser, setTags, addBreadcrumb, etc.) do not affect the parent or siblings.
  */
 interface LoggerState {
     /** Current user context, set via setUser() */
@@ -216,6 +240,18 @@ interface LoggerState {
     maxBreadcrumbs: number;
 }
 
+/**
+ * Parse a W3C traceparent header.
+ * Format: `{version}-{trace-id}-{parent-id}-{trace-flags}`
+ * Example: `00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01`
+ *
+ * @returns Parsed components or `null` if the header is invalid.
+ */
+declare function parseTraceparent(header: string): {
+    traceId: string;
+    parentId: string;
+    flags: string;
+} | null;
 /**
  * Original console methods, preserved before any interception.
  * Used internally by the Logger's debug output to avoid infinite loops
@@ -238,11 +274,10 @@ declare const _originalConsole: {
  * import { createLogger } from "@deeptracer/core"
  *
  * const logger = createLogger({
- *   product: "my-app",
+ *   secretKey: "dt_secret_xxx",
+ *   endpoint: "https://deeptracer.example.com",
  *   service: "api",
  *   environment: "production",
- *   endpoint: "https://deeptracer.example.com",
- *   apiKey: "dt_live_xxx",
  * })
  *
  * logger.setUser({ id: "u_123", email: "user@example.com" })
@@ -253,6 +288,7 @@ declare const _originalConsole: {
 declare class Logger {
     private batcher;
     private transport;
+    private effectiveLevel;
     protected contextName?: string;
     protected config: LoggerConfig;
     protected state: LoggerState;
@@ -270,7 +306,8 @@ declare class Logger {
     }, state?: LoggerState);
     /**
      * Set the current user context. Attached to all subsequent logs, errors, spans, and LLM reports.
-     * Shared across all child loggers (withContext, forRequest).
+     * Only affects this logger instance — child loggers created via `withContext()` or `forRequest()`
+     * have their own independent state.
      *
      * @example
      * ```ts
@@ -331,9 +368,9 @@ declare class Logger {
     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. */
+    /** Create a context-scoped logger. All logs include the context name. Gets an independent copy of state. */
     withContext(name: string): Logger;
-    /** Create a request-scoped logger that extracts trace context from headers. Shares state with parent. */
+    /** Create a request-scoped logger that extracts trace context from headers. Gets an independent copy of state. */
     forRequest(request: Request): Logger;
     /**
      * Capture and report an error immediately (not batched).
@@ -372,4 +409,4 @@ declare class Logger {
 /** 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 };
+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, parseTraceparent as p };

package/dist/{internal-DdKQRgCs.d.ts → logger-BDTEt7Gi.d.ts}

@@ -1,32 +1,56 @@
 /**
  * Configuration for creating a DeepTracer logger instance.
  *
+ * All fields are optional when environment variables are set.
+ * Server packages read `DEEPTRACER_SECRET_KEY`, `DEEPTRACER_ENDPOINT`, etc.
+ * Client packages read `NEXT_PUBLIC_DEEPTRACER_KEY`, `NEXT_PUBLIC_DEEPTRACER_ENDPOINT`, etc.
+ *
  * @example
+ * Server (Node.js / Next.js instrumentation):
  * ```ts
  * const config: LoggerConfig = {
- *   product: "my-app",
- *   service: "api-server",
+ *   secretKey: "dt_secret_xxx",
+ *   endpoint: "https://deeptracer.example.com",
+ *   service: "api",
  *   environment: "production",
+ * }
+ * ```
+ *
+ * @example
+ * Client (browser / React):
+ * ```ts
+ * const config: LoggerConfig = {
+ *   publicKey: "dt_public_xxx",
  *   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";
+    /** Server-side API key (prefix: `dt_secret_`). Never expose in client bundles. */
+    secretKey?: string;
+    /** Client-side API key (prefix: `dt_public_`). Safe for browser bundles. */
+    publicKey?: string;
+    /** Service name (e.g., "api", "worker", "web"). Default varies by package. */
+    service?: string;
+    /** Deployment environment (any string). Default: `NODE_ENV` or `"production"` */
+    environment?: string;
     /** DeepTracer ingestion endpoint URL */
-    endpoint: string;
-    /** DeepTracer API key for authentication */
-    apiKey: string;
+    endpoint?: string;
     /** Number of log entries to batch before sending. Default: 50 */
     batchSize?: number;
     /** Milliseconds between automatic batch flushes. Default: 5000 */
     flushIntervalMs?: number;
+    /**
+     * Minimum log level to send to DeepTracer.
+     *
+     * Logs below this level are silently filtered — they won't be batched or
+     * sent to the backend. Breadcrumbs are still recorded for filtered logs
+     * (so error reports retain full context).
+     *
+     * Default: `"info"` when `environment` is `"production"`, `"debug"` otherwise.
+     * Override via `DEEPTRACER_LOG_LEVEL` (server) or `NEXT_PUBLIC_DEEPTRACER_LOG_LEVEL` (client).
+     */
+    level?: LogLevel;
     /** Enable console output for all log calls (useful for local development) */
     debug?: boolean;
     /** Maximum breadcrumbs to retain for error reports. Default: 20 */
@@ -198,10 +222,10 @@ type BeforeSendEvent = {
 };
 
 /**
- * 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.
+ * Mutable state for a Logger instance.
+ * The root Logger creates this; `withContext()` and `forRequest()` clone it
+ * so each child logger gets an independent snapshot. Mutations on a child
+ * (setUser, setTags, addBreadcrumb, etc.) do not affect the parent or siblings.
  */
 interface LoggerState {
     /** Current user context, set via setUser() */
@@ -216,6 +240,18 @@ interface LoggerState {
     maxBreadcrumbs: number;
 }
 
+/**
+ * Parse a W3C traceparent header.
+ * Format: `{version}-{trace-id}-{parent-id}-{trace-flags}`
+ * Example: `00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01`
+ *
+ * @returns Parsed components or `null` if the header is invalid.
+ */
+declare function parseTraceparent(header: string): {
+    traceId: string;
+    parentId: string;
+    flags: string;
+} | null;
 /**
  * Original console methods, preserved before any interception.
  * Used internally by the Logger's debug output to avoid infinite loops
@@ -238,11 +274,10 @@ declare const _originalConsole: {
  * import { createLogger } from "@deeptracer/core"
  *
  * const logger = createLogger({
- *   product: "my-app",
+ *   secretKey: "dt_secret_xxx",
+ *   endpoint: "https://deeptracer.example.com",
  *   service: "api",
  *   environment: "production",
- *   endpoint: "https://deeptracer.example.com",
- *   apiKey: "dt_live_xxx",
  * })
  *
  * logger.setUser({ id: "u_123", email: "user@example.com" })
@@ -253,6 +288,7 @@ declare const _originalConsole: {
 declare class Logger {
     private batcher;
     private transport;
+    private effectiveLevel;
     protected contextName?: string;
     protected config: LoggerConfig;
     protected state: LoggerState;
@@ -270,7 +306,8 @@ declare class Logger {
     }, state?: LoggerState);
     /**
      * Set the current user context. Attached to all subsequent logs, errors, spans, and LLM reports.
-     * Shared across all child loggers (withContext, forRequest).
+     * Only affects this logger instance — child loggers created via `withContext()` or `forRequest()`
+     * have their own independent state.
      *
      * @example
      * ```ts
@@ -331,9 +368,9 @@ declare class Logger {
     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. */
+    /** Create a context-scoped logger. All logs include the context name. Gets an independent copy of state. */
     withContext(name: string): Logger;
-    /** Create a request-scoped logger that extracts trace context from headers. Shares state with parent. */
+    /** Create a request-scoped logger that extracts trace context from headers. Gets an independent copy of state. */
     forRequest(request: Request): Logger;
     /**
      * Capture and report an error immediately (not batched).
@@ -372,4 +409,4 @@ declare class Logger {
 /** 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 };
+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, parseTraceparent as p };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeptracer/core",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Core SDK for DeepTracer — Logger class, types, transport, batcher, tracing",
   "type": "module",
   "main": "dist/index.cjs",
@@ -18,9 +18,17 @@
       "require": "./dist/internal.cjs"
     }
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "sideEffects": false,
-  "keywords": ["logging", "observability", "tracing", "deeptracer"],
+  "keywords": [
+    "logging",
+    "observability",
+    "tracing",
+    "deeptracer"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/getdeeptracer/deeptracer-js.git",