@deeptracer/core 0.3.1 → 0.4.2

package/README.md

@@ -47,11 +47,10 @@ The package ships as both ESM and CJS with full TypeScript declarations. Zero ru
 import { createLogger } from "@deeptracer/core"
 
 const logger = createLogger({
-  product: "my-app",
   service: "api",
   environment: "production",
   endpoint: "https://your-deeptracer.example.com",
-  apiKey: "dt_live_xxx",
+  secretKey: "dt_secret_xxx",
 })
 
 // Structured logging (batched -- sent in groups of 50 or every 5 seconds)
@@ -85,11 +84,10 @@ Pass a `LoggerConfig` object to `createLogger()`:
 ```ts
 const logger = createLogger({
   // Required
-  product: "spotbeam",           // Product name for grouping in the dashboard
   service: "api",                // Service name within the product
   environment: "production",     // "production" or "staging"
   endpoint: "https://dt.co",     // DeepTracer ingestion endpoint URL
-  apiKey: "dt_live_xxx",         // API key for authentication
+  secretKey: "dt_secret_xxx",    // Server-side API key for authentication
 
   // Optional
   batchSize: 50,                 // Logs to buffer before sending (default: 50)
@@ -100,11 +98,11 @@ const logger = createLogger({
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
-| `product` | `string` | Yes | -- | Product name (e.g., `"spotbeam"`, `"macro"`) |
 | `service` | `string` | Yes | -- | Service name (e.g., `"api"`, `"worker"`, `"web"`) |
 | `environment` | `"production" \| "staging"` | Yes | -- | Deployment environment |
 | `endpoint` | `string` | Yes | -- | DeepTracer ingestion endpoint URL |
-| `apiKey` | `string` | Yes | -- | DeepTracer API key |
+| `secretKey` | `string` | Yes | -- | Server-side API key (prefix: `dt_secret_`) |
+| `publicKey` | `string` | No | -- | Client-side API key (prefix: `dt_public_`) |
 | `batchSize` | `number` | No | `50` | Number of log entries to buffer before flushing |
 | `flushIntervalMs` | `number` | No | `5000` | Milliseconds between automatic flushes |
 | `debug` | `boolean` | No | `false` | When `true`, all log calls also print to the console |
@@ -119,11 +117,10 @@ Create a new `Logger` instance. This is the main entry point.
 import { createLogger } from "@deeptracer/core"
 
 const logger = createLogger({
-  product: "my-app",
   service: "api",
   environment: "production",
   endpoint: "https://your-deeptracer.example.com",
-  apiKey: "dt_live_xxx",
+  secretKey: "dt_secret_xxx",
 })
 ```
 
@@ -439,11 +436,11 @@ process.on("SIGTERM", () => {
 
 ```ts
 interface LoggerConfig {
-  product: string
   service: string
   environment: "production" | "staging"
   endpoint: string
-  apiKey: string
+  secretKey: string
+  publicKey?: string
   batchSize?: number          // default: 50
   flushIntervalMs?: number    // default: 5000
   debug?: boolean             // default: false
@@ -587,9 +584,9 @@ The transport layer sends data to four DeepTracer ingestion endpoints:
 | `POST /ingest/llm` | Immediate | LLM usage reports |
 
 All requests include:
-- `Authorization: Bearer <apiKey>` header
+- `Authorization: Bearer <secretKey>` header
 - `Content-Type: application/json` header
-- `product`, `service`, and `environment` fields in the JSON body
+- `service` and `environment` fields in the JSON body
 
 If a request fails, a warning is logged to the console. The SDK does not retry failed requests -- it is designed to be non-blocking and never crash your application.
 

package/dist/{chunk-XVDM75HZ.js → chunk-IWPXOBZV.js}

@@ -1,53 +1,49 @@
 // src/version.ts
-var SDK_VERSION = "0.3.1";
+var SDK_VERSION = "0.4.2";
 var SDK_NAME = "core";
 
-// src/batcher.ts
-var Batcher = class {
-  constructor(config, onFlush) {
-    this.onFlush = onFlush;
-    this.batchSize = config.batchSize ?? 50;
-    this.flushIntervalMs = config.flushIntervalMs ?? 5e3;
-    this.startTimer();
-  }
-  buffer = [];
-  timer = null;
-  batchSize;
-  flushIntervalMs;
-  add(entry) {
-    this.buffer.push(entry);
-    if (this.buffer.length >= this.batchSize) {
-      this.flush();
-    }
-  }
-  flush() {
-    if (this.buffer.length === 0) return;
-    const entries = [...this.buffer];
-    this.buffer = [];
-    this.onFlush(entries);
-  }
-  startTimer() {
-    this.timer = setInterval(() => this.flush(), this.flushIntervalMs);
-  }
-  async destroy() {
-    if (this.timer) clearInterval(this.timer);
-    this.timer = null;
-    this.flush();
-  }
-};
-
 // 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 {
@@ -55,33 +51,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.`
+          );
+        }
       }
     }
   }
@@ -102,7 +110,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
@@ -117,7 +124,6 @@ var Transport = class {
       `${this.config.endpoint}/ingest/errors`,
       {
         ...error,
-        product: this.config.product,
         service: this.config.service,
         environment: this.config.environment
       },
@@ -131,7 +137,6 @@ var Transport = class {
       `${this.config.endpoint}/ingest/traces`,
       {
         ...span,
-        product: this.config.product,
         service: this.config.service,
         environment: this.config.environment
       },
@@ -145,7 +150,6 @@ var Transport = class {
       `${this.config.endpoint}/ingest/llm`,
       {
         ...report,
-        product: this.config.product,
         service: this.config.service,
         environment: this.config.environment
       },
@@ -169,6 +173,40 @@ var Transport = class {
   }
 };
 
+// src/batcher.ts
+var Batcher = class {
+  constructor(config, onFlush) {
+    this.onFlush = onFlush;
+    this.batchSize = config.batchSize ?? 50;
+    this.flushIntervalMs = config.flushIntervalMs ?? 5e3;
+    this.startTimer();
+  }
+  buffer = [];
+  timer = null;
+  batchSize;
+  flushIntervalMs;
+  add(entry) {
+    this.buffer.push(entry);
+    if (this.buffer.length >= this.batchSize) {
+      this.flush();
+    }
+  }
+  flush() {
+    if (this.buffer.length === 0) return;
+    const entries = [...this.buffer];
+    this.buffer = [];
+    this.onFlush(entries);
+  }
+  startTimer() {
+    this.timer = setInterval(() => this.flush(), this.flushIntervalMs);
+  }
+  async destroy() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.flush();
+  }
+};
+
 // src/state.ts
 function createLoggerState(maxBreadcrumbs) {
   return {
@@ -179,6 +217,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) {
@@ -187,11 +234,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,
@@ -202,6 +271,7 @@ var _originalConsole = {
 var Logger = class _Logger {
   batcher;
   transport;
+  effectiveLevel;
   contextName;
   config;
   state;
@@ -211,6 +281,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 },
@@ -224,7 +308,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
@@ -346,26 +431,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}`);
       }
@@ -373,9 +445,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) {
@@ -396,22 +482,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
@@ -430,7 +531,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 || "",
@@ -511,7 +613,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();
@@ -551,10 +653,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;
   }
@@ -595,6 +703,8 @@ function createLogger(config) {
 export {
   SDK_VERSION,
   SDK_NAME,
+  Transport,
+  parseTraceparent,
   _originalConsole,
   Logger,
   createLogger