@deeptracer/core 0.3.1 → 0.4.2

package/dist/internal.cjs

@@ -21,7 +21,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var internal_exports = {};
 __export(internal_exports, {
   Logger: () => Logger,
-  _originalConsole: () => _originalConsole
+  Transport: () => Transport,
+  _originalConsole: () => _originalConsole,
+  parseConsoleArgs: () => parseConsoleArgs,
+  parseTraceparent: () => parseTraceparent
 });
 module.exports = __toCommonJS(internal_exports);
 
@@ -60,21 +63,51 @@ var Batcher = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.3.1";
+var SDK_VERSION = "0.4.2";
 var SDK_NAME = "core";
 
 // src/transport.ts
 var Transport = class {
   constructor(config) {
     this.config = config;
+    const hasKey = !!(config.secretKey || config.publicKey);
+    const hasEndpoint = !!config.endpoint;
+    this.disabled = !hasKey || !hasEndpoint;
+    if (config.secretKey?.startsWith("dt_secret_") && typeof globalThis.window !== "undefined") {
+      console.error(
+        "[@deeptracer/core] WARNING: `secretKey` (dt_secret_...) detected in a browser bundle. This exposes your server key to end users. Use `publicKey` (dt_public_...) for client-side code."
+      );
+    }
   }
   inFlightRequests = /* @__PURE__ */ new Set();
+  /**
+   * When true, all send methods become silent no-ops.
+   * Set automatically when no auth key or no endpoint is configured.
+   * This prevents pointless network requests and console noise during
+   * local development without API keys.
+   */
+  disabled;
+  /**
+   * Tracks which send types (logs, error, trace, LLM usage) have already
+   * logged a failure warning. After the first failure for a given type,
+   * subsequent failures are silently dropped to prevent console spam
+   * (e.g., when the ingestion endpoint is unreachable during development).
+   */
+  warnedLabels = /* @__PURE__ */ new Set();
+  /** Resolve the auth key: prefer secretKey (server), fall back to publicKey (client). */
+  get authKey() {
+    return this.config.secretKey ?? this.config.publicKey ?? "";
+  }
   /**
    * Send a request with automatic retry and exponential backoff.
    * Retries up to `maxRetries` times on network errors and 5xx responses.
    * Does NOT retry on 4xx (client errors — bad payload, auth failure, etc.).
+   *
+   * After the first total failure for a given label, subsequent failures
+   * are silently dropped (no more console warnings).
    */
   async sendWithRetry(url, body, label, maxRetries = 3) {
+    if (this.disabled) return;
     const baseDelays = [1e3, 2e3, 4e3];
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
@@ -82,33 +115,45 @@ var Transport = class {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
-            Authorization: `Bearer ${this.config.apiKey}`,
+            Authorization: `Bearer ${this.authKey}`,
             "x-deeptracer-sdk": `${SDK_NAME}/${SDK_VERSION}`
           },
           body: JSON.stringify(body)
         });
-        if (res.ok) return;
+        if (res.ok) {
+          this.warnedLabels.delete(label);
+          return;
+        }
         if (res.status >= 400 && res.status < 500) {
-          console.warn(
-            `[@deeptracer/core] Failed to send ${label}: ${res.status} ${res.statusText}`
-          );
+          if (!this.warnedLabels.has(label)) {
+            this.warnedLabels.add(label);
+            console.warn(
+              `[@deeptracer/core] Failed to send ${label}: ${res.status} ${res.statusText}`
+            );
+          }
           return;
         }
         if (attempt < maxRetries) {
           await this.sleep(this.jitter(baseDelays[attempt]));
           continue;
         }
-        console.warn(
-          `[@deeptracer/core] Failed to send ${label}: ${res.status} ${res.statusText} (exhausted ${maxRetries} retries)`
-        );
+        if (!this.warnedLabels.has(label)) {
+          this.warnedLabels.add(label);
+          console.warn(
+            `[@deeptracer/core] Failed to send ${label}: ${res.status} ${res.statusText} (exhausted ${maxRetries} retries). Suppressing further warnings.`
+          );
+        }
       } catch {
         if (attempt < maxRetries) {
           await this.sleep(this.jitter(baseDelays[attempt]));
           continue;
         }
-        console.warn(
-          `[@deeptracer/core] Failed to send ${label} (exhausted ${maxRetries} retries)`
-        );
+        if (!this.warnedLabels.has(label)) {
+          this.warnedLabels.add(label);
+          console.warn(
+            `[@deeptracer/core] Failed to send ${label} (exhausted ${maxRetries} retries). Suppressing further warnings.`
+          );
+        }
       }
     }
   }
@@ -129,7 +174,6 @@ var Transport = class {
     const p = this.sendWithRetry(
       `${this.config.endpoint}/ingest/logs`,
       {
-        product: this.config.product,
         service: this.config.service,
         environment: this.config.environment,
         logs
@@ -144,7 +188,6 @@ var Transport = class {
       `${this.config.endpoint}/ingest/errors`,
       {
         ...error,
-        product: this.config.product,
         service: this.config.service,
         environment: this.config.environment
       },
@@ -158,7 +201,6 @@ var Transport = class {
       `${this.config.endpoint}/ingest/traces`,
       {
         ...span,
-        product: this.config.product,
         service: this.config.service,
         environment: this.config.environment
       },
@@ -172,7 +214,6 @@ var Transport = class {
       `${this.config.endpoint}/ingest/llm`,
       {
         ...report,
-        product: this.config.product,
         service: this.config.service,
         environment: this.config.environment
       },
@@ -206,6 +247,15 @@ function createLoggerState(maxBreadcrumbs) {
     maxBreadcrumbs
   };
 }
+function cloneState(state) {
+  return {
+    user: state.user ? { ...state.user } : null,
+    tags: { ...state.tags },
+    contexts: Object.fromEntries(Object.entries(state.contexts).map(([k, v]) => [k, { ...v }])),
+    breadcrumbs: [...state.breadcrumbs],
+    maxBreadcrumbs: state.maxBreadcrumbs
+  };
+}
 function addBreadcrumb(state, breadcrumb) {
   state.breadcrumbs.push(breadcrumb);
   if (state.breadcrumbs.length > state.maxBreadcrumbs) {
@@ -214,11 +264,33 @@ function addBreadcrumb(state, breadcrumb) {
 }
 
 // src/logger.ts
+var LOG_LEVEL_VALUES = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
 function generateId() {
   const bytes = new Uint8Array(8);
   crypto.getRandomValues(bytes);
   return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
+function generateTraceId() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function parseTraceparent(header) {
+  const parts = header.trim().split("-");
+  if (parts.length !== 4) return null;
+  const [version, traceId, parentId, flags] = parts;
+  if (version !== "00") return null;
+  if (traceId.length !== 32 || !/^[0-9a-f]{32}$/.test(traceId)) return null;
+  if (parentId.length !== 16 || !/^[0-9a-f]{16}$/.test(parentId)) return null;
+  if (flags.length !== 2 || !/^[0-9a-f]{2}$/.test(flags)) return null;
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentId)) return null;
+  return { traceId, parentId, flags };
+}
 var _originalConsole = {
   log: console.log,
   info: console.info,
@@ -229,6 +301,7 @@ var _originalConsole = {
 var Logger = class _Logger {
   batcher;
   transport;
+  effectiveLevel;
   contextName;
   config;
   state;
@@ -238,6 +311,20 @@ var Logger = class _Logger {
     this.contextName = contextName;
     this.requestMeta = requestMeta;
     this.state = state ?? createLoggerState(config.maxBreadcrumbs ?? 20);
+    const hasKey = !!(config.secretKey || config.publicKey);
+    const hasEndpoint = !!config.endpoint;
+    if (!hasKey && !hasEndpoint) {
+      _originalConsole.warn(
+        "[@deeptracer/core] No API key or endpoint configured. Running in local-only mode (logging methods work, but events are not sent). Set DEEPTRACER_SECRET_KEY and DEEPTRACER_ENDPOINT to enable."
+      );
+    } else if (!hasKey) {
+      _originalConsole.warn(
+        "[@deeptracer/core] No `secretKey` or `publicKey` provided. Events will not be sent."
+      );
+    } else if (!hasEndpoint) {
+      _originalConsole.warn("[@deeptracer/core] No `endpoint` provided. Events will not be sent.");
+    }
+    this.effectiveLevel = LOG_LEVEL_VALUES[config.level ?? (config.environment === "production" ? "info" : "debug")];
     this.transport = new Transport(config);
     this.batcher = new Batcher(
       { batchSize: config.batchSize, flushIntervalMs: config.flushIntervalMs },
@@ -251,7 +338,8 @@ var Logger = class _Logger {
   // ---------------------------------------------------------------------------
   /**
    * 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
@@ -373,26 +461,13 @@ var Logger = class _Logger {
       };
     }
     metadata = this.mergeStateMetadata(metadata);
-    const entry = {
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      level,
-      message,
-      metadata,
-      context: this.contextName,
-      trace_id: this.requestMeta?.trace_id,
-      span_id: this.requestMeta?.span_id,
-      request_id: this.requestMeta?.request_id,
-      vercel_id: this.requestMeta?.vercel_id
-    };
-    const hookResult = this.applyBeforeSend({ type: "log", data: entry });
-    if (hookResult === null) return;
-    const finalEntry = hookResult.data;
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
     if (this.config.debug) {
       const prefix = this.contextName ? `[${this.contextName}]` : "";
       const lvl = level.toUpperCase().padEnd(5);
       const consoleFn = level === "error" ? _originalConsole.error : level === "warn" ? _originalConsole.warn : level === "debug" ? _originalConsole.debug : _originalConsole.log;
-      if (finalEntry.metadata) {
-        consoleFn(`${lvl} ${prefix} ${message}`, finalEntry.metadata);
+      if (metadata) {
+        consoleFn(`${lvl} ${prefix} ${message}`, metadata);
       } else {
         consoleFn(`${lvl} ${prefix} ${message}`);
       }
@@ -400,9 +475,23 @@ var Logger = class _Logger {
     addBreadcrumb(this.state, {
       type: "log",
       message: `[${level}] ${message}`,
-      timestamp: entry.timestamp
+      timestamp
     });
-    this.batcher.add(finalEntry);
+    if (LOG_LEVEL_VALUES[level] < this.effectiveLevel) return;
+    const entry = {
+      timestamp,
+      level,
+      message,
+      metadata,
+      context: this.contextName,
+      trace_id: this.requestMeta?.trace_id,
+      span_id: this.requestMeta?.span_id,
+      request_id: this.requestMeta?.request_id,
+      vercel_id: this.requestMeta?.vercel_id
+    };
+    const hookResult = this.applyBeforeSend({ type: "log", data: entry });
+    if (hookResult === null) return;
+    this.batcher.add(hookResult.data);
   }
   /** Log a debug message. */
   debug(message, dataOrError, error) {
@@ -423,22 +512,37 @@ var Logger = class _Logger {
   // ---------------------------------------------------------------------------
   // Child loggers
   // ---------------------------------------------------------------------------
-  /** 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) {
-    return new _Logger(this.config, name, this.requestMeta, this.state);
+    return new _Logger(this.config, name, this.requestMeta, cloneState(this.state));
   }
-  /** 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) {
-    const vercelId = request.headers.get("x-vercel-id") || void 0;
+    let traceId;
+    let spanId;
+    const traceparent = request.headers.get("traceparent");
+    if (traceparent) {
+      const parsed = parseTraceparent(traceparent);
+      if (parsed) {
+        traceId = parsed.traceId;
+        spanId = parsed.parentId;
+      }
+    }
+    traceId = traceId || request.headers.get("x-trace-id") || void 0;
+    spanId = spanId || request.headers.get("x-span-id") || void 0;
     const requestId = request.headers.get("x-request-id") || void 0;
-    const traceId = request.headers.get("x-trace-id") || void 0;
-    const spanId = request.headers.get("x-span-id") || void 0;
-    return new _Logger(this.config, this.contextName, {
-      trace_id: traceId,
-      span_id: spanId,
-      request_id: requestId || (vercelId ? vercelId.split("::").pop() : void 0),
-      vercel_id: vercelId
-    }, this.state);
+    const vercelId = request.headers.get("x-vercel-id") || void 0;
+    return new _Logger(
+      this.config,
+      this.contextName,
+      {
+        trace_id: traceId,
+        span_id: spanId,
+        request_id: requestId || (vercelId ? vercelId.split("::").pop() : void 0),
+        vercel_id: vercelId
+      },
+      cloneState(this.state)
+    );
   }
   // ---------------------------------------------------------------------------
   // Error capture
@@ -457,7 +561,8 @@ var Logger = class _Logger {
     const enrichedContext = { ...context?.context };
     if (this.state.user) enrichedContext.user = this.state.user;
     if (Object.keys(this.state.tags).length > 0) enrichedContext._tags = { ...this.state.tags };
-    if (Object.keys(this.state.contexts).length > 0) enrichedContext._contexts = { ...this.state.contexts };
+    if (Object.keys(this.state.contexts).length > 0)
+      enrichedContext._contexts = { ...this.state.contexts };
     const report = {
       error_message: err.message,
       stack_trace: err.stack || "",
@@ -538,7 +643,7 @@ var Logger = class _Logger {
   }
   /** Start a span with manual lifecycle. You must call span.end(). */
   startInactiveSpan(operation) {
-    const traceId = this.requestMeta?.trace_id || generateId();
+    const traceId = this.requestMeta?.trace_id || generateTraceId();
     const parentSpanId = this.requestMeta?.span_id || "";
     const spanId = generateId();
     const startTime = (/* @__PURE__ */ new Date()).toISOString();
@@ -578,10 +683,16 @@ var Logger = class _Logger {
         const childLogger = new _Logger(this.config, this.contextName, childMeta, this.state);
         return childLogger.startInactiveSpan(childOp);
       },
-      getHeaders: () => ({
-        "x-trace-id": traceId,
-        "x-span-id": spanId
-      })
+      getHeaders: () => {
+        const headers = {
+          "x-trace-id": traceId,
+          "x-span-id": spanId
+        };
+        if (/^[0-9a-f]{32}$/.test(traceId)) {
+          headers.traceparent = `00-${traceId}-${spanId}-01`;
+        }
+        return headers;
+      }
     };
     return span;
   }
@@ -615,8 +726,71 @@ var Logger = class _Logger {
     await this.transport.drain(timeoutMs);
   }
 };
+
+// src/internal.ts
+function safeStringify(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return JSON.stringify(value, (_key, val) => {
+    if (val instanceof Error) {
+      return { name: val.name, message: val.message, stack: val.stack };
+    }
+    if (typeof val === "bigint") return val.toString();
+    if (typeof val === "symbol") return val.toString();
+    if (typeof val === "function") return `[Function: ${val.name || "anonymous"}]`;
+    if (val !== null && typeof val === "object") {
+      if (seen.has(val)) return "[Circular]";
+      seen.add(val);
+    }
+    return val;
+  });
+}
+function parseConsoleArgs(args) {
+  if (args.length === 0) return { message: "" };
+  const first = args[0];
+  if (typeof first === "string" && /%[sdifoc%]/.test(first)) {
+    return { message: args.map(String).join(" ") };
+  }
+  if (typeof first === "string") {
+    const messageParts = [first];
+    const metadata = {};
+    let metadataCount = 0;
+    for (let i = 1; i < args.length; i++) {
+      const arg = args[i];
+      if (arg instanceof Error) {
+        metadata[`error${metadataCount > 0 ? `_${metadataCount}` : ""}`] = {
+          name: arg.name,
+          message: arg.message,
+          stack: arg.stack
+        };
+        metadataCount++;
+      } else if (arg !== null && typeof arg === "object") {
+        Object.assign(metadata, arg);
+        metadataCount++;
+      } else if (arg !== void 0) {
+        messageParts.push(String(arg));
+      }
+    }
+    return {
+      message: messageParts.join(" "),
+      metadata: metadataCount > 0 ? metadata : void 0
+    };
+  }
+  if (first instanceof Error) {
+    return {
+      message: first.message,
+      metadata: { error: { name: first.name, message: first.message, stack: first.stack } }
+    };
+  }
+  if (first !== null && typeof first === "object") {
+    return { message: safeStringify(first) };
+  }
+  return { message: String(first) };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Logger,
-  _originalConsole
+  Transport,
+  _originalConsole,
+  parseConsoleArgs,
+  parseTraceparent
 });

package/dist/internal.d.cts

@@ -1 +1,86 @@
-export { d as Logger, e as LoggerConfig, h as LoggerState, M as MiddlewareOptions, _ as _originalConsole } from './internal-DdKQRgCs.cjs';
+import { e as LoggerConfig, b as LogEntry, E as ErrorReport, f as SpanData } from './logger-BDTEt7Gi.cjs';
+export { d as Logger, h as LoggerState, M as MiddlewareOptions, _ as _originalConsole, p as parseTraceparent } from './logger-BDTEt7Gi.cjs';
+
+/**
+ * HTTP transport for sending data to the DeepTracer ingestion API.
+ *
+ * Features:
+ * - Automatic retry with exponential backoff (3 retries, 1s/2s/4s + jitter)
+ * - Only retries on network errors and 5xx (not 4xx client errors)
+ * - SDK version header on every request (`x-deeptracer-sdk: core/0.3.0`)
+ * - In-flight request tracking for graceful shutdown via `drain()`
+ * - Silent no-op when no API key or endpoint is configured (no retries, no console noise)
+ * - Warn-once per failure type — first failure for each send type (logs, error, trace)
+ *   logs a warning, subsequent identical failures are silently dropped
+ */
+declare class Transport {
+    private config;
+    private inFlightRequests;
+    /**
+     * When true, all send methods become silent no-ops.
+     * Set automatically when no auth key or no endpoint is configured.
+     * This prevents pointless network requests and console noise during
+     * local development without API keys.
+     */
+    private readonly disabled;
+    /**
+     * Tracks which send types (logs, error, trace, LLM usage) have already
+     * logged a failure warning. After the first failure for a given type,
+     * subsequent failures are silently dropped to prevent console spam
+     * (e.g., when the ingestion endpoint is unreachable during development).
+     */
+    private warnedLabels;
+    constructor(config: Pick<LoggerConfig, "endpoint" | "secretKey" | "publicKey" | "service" | "environment">);
+    /** Resolve the auth key: prefer secretKey (server), fall back to publicKey (client). */
+    private get authKey();
+    /**
+     * Send a request with automatic retry and exponential backoff.
+     * Retries up to `maxRetries` times on network errors and 5xx responses.
+     * Does NOT retry on 4xx (client errors — bad payload, auth failure, etc.).
+     *
+     * After the first total failure for a given label, subsequent failures
+     * are silently dropped (no more console warnings).
+     */
+    private sendWithRetry;
+    /** Add +/- 20% jitter to a delay to prevent thundering herd. */
+    private jitter;
+    private sleep;
+    /** Track an in-flight request and remove it when done. */
+    private track;
+    sendLogs(logs: LogEntry[]): Promise<void>;
+    sendError(error: ErrorReport): Promise<void>;
+    sendTrace(span: SpanData): Promise<void>;
+    sendLLMUsage(report: {
+        model: string;
+        provider: string;
+        operation: string;
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+        latency_ms: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Wait for all in-flight requests to complete, with a timeout.
+     * Used by `logger.destroy()` to ensure data is sent before process exit.
+     *
+     * @param timeoutMs - Maximum time to wait (default: 2000ms)
+     */
+    drain(timeoutMs?: number): Promise<void>;
+}
+
+/**
+ * Parse console.log/info/warn/error arguments into a structured `{ message, metadata }` pair.
+ *
+ * - First string arg → message; remaining objects → merged into metadata
+ * - If first string has printf patterns (`%s`, `%d`, `%o`, etc.) → join all as string, no metadata
+ * - First non-string arg → `safeStringify` it for message
+ * - Error objects → serialize `{ name, message, stack }` into metadata
+ * - Remaining primitives → append to message string
+ */
+declare function parseConsoleArgs(args: unknown[]): {
+    message: string;
+    metadata?: Record<string, unknown>;
+};
+
+export { LoggerConfig, Transport, parseConsoleArgs };

package/dist/internal.d.ts

@@ -1 +1,86 @@
-export { d as Logger, e as LoggerConfig, h as LoggerState, M as MiddlewareOptions, _ as _originalConsole } from './internal-DdKQRgCs.js';
+import { e as LoggerConfig, b as LogEntry, E as ErrorReport, f as SpanData } from './logger-BDTEt7Gi.js';
+export { d as Logger, h as LoggerState, M as MiddlewareOptions, _ as _originalConsole, p as parseTraceparent } from './logger-BDTEt7Gi.js';
+
+/**
+ * HTTP transport for sending data to the DeepTracer ingestion API.
+ *
+ * Features:
+ * - Automatic retry with exponential backoff (3 retries, 1s/2s/4s + jitter)
+ * - Only retries on network errors and 5xx (not 4xx client errors)
+ * - SDK version header on every request (`x-deeptracer-sdk: core/0.3.0`)
+ * - In-flight request tracking for graceful shutdown via `drain()`
+ * - Silent no-op when no API key or endpoint is configured (no retries, no console noise)
+ * - Warn-once per failure type — first failure for each send type (logs, error, trace)
+ *   logs a warning, subsequent identical failures are silently dropped
+ */
+declare class Transport {
+    private config;
+    private inFlightRequests;
+    /**
+     * When true, all send methods become silent no-ops.
+     * Set automatically when no auth key or no endpoint is configured.
+     * This prevents pointless network requests and console noise during
+     * local development without API keys.
+     */
+    private readonly disabled;
+    /**
+     * Tracks which send types (logs, error, trace, LLM usage) have already
+     * logged a failure warning. After the first failure for a given type,
+     * subsequent failures are silently dropped to prevent console spam
+     * (e.g., when the ingestion endpoint is unreachable during development).
+     */
+    private warnedLabels;
+    constructor(config: Pick<LoggerConfig, "endpoint" | "secretKey" | "publicKey" | "service" | "environment">);
+    /** Resolve the auth key: prefer secretKey (server), fall back to publicKey (client). */
+    private get authKey();
+    /**
+     * Send a request with automatic retry and exponential backoff.
+     * Retries up to `maxRetries` times on network errors and 5xx responses.
+     * Does NOT retry on 4xx (client errors — bad payload, auth failure, etc.).
+     *
+     * After the first total failure for a given label, subsequent failures
+     * are silently dropped (no more console warnings).
+     */
+    private sendWithRetry;
+    /** Add +/- 20% jitter to a delay to prevent thundering herd. */
+    private jitter;
+    private sleep;
+    /** Track an in-flight request and remove it when done. */
+    private track;
+    sendLogs(logs: LogEntry[]): Promise<void>;
+    sendError(error: ErrorReport): Promise<void>;
+    sendTrace(span: SpanData): Promise<void>;
+    sendLLMUsage(report: {
+        model: string;
+        provider: string;
+        operation: string;
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+        latency_ms: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Wait for all in-flight requests to complete, with a timeout.
+     * Used by `logger.destroy()` to ensure data is sent before process exit.
+     *
+     * @param timeoutMs - Maximum time to wait (default: 2000ms)
+     */
+    drain(timeoutMs?: number): Promise<void>;
+}
+
+/**
+ * Parse console.log/info/warn/error arguments into a structured `{ message, metadata }` pair.
+ *
+ * - First string arg → message; remaining objects → merged into metadata
+ * - If first string has printf patterns (`%s`, `%d`, `%o`, etc.) → join all as string, no metadata
+ * - First non-string arg → `safeStringify` it for message
+ * - Error objects → serialize `{ name, message, stack }` into metadata
+ * - Remaining primitives → append to message string
+ */
+declare function parseConsoleArgs(args: unknown[]): {
+    message: string;
+    metadata?: Record<string, unknown>;
+};
+
+export { LoggerConfig, Transport, parseConsoleArgs };