@logbrew/sdk 0.1.5 → 0.1.7

package/README.md

@@ -134,7 +134,65 @@ try {
 }
 ```
 
-The helper records the error name/message and up to 32 ordered generated `stackFrames`, with query strings, hashes, and local absolute prefixes removed. Each frame carries only filename, positive line/column, and an optional matched Debug ID. Existing first-frame metadata remains available for compatible grouping and tooling. The helper also emits an `issueGroupingKey` based on source, error type, and the sanitized first frame, plus an optional app-owned `issueFingerprint` when you pass a stable, safe, low-cardinality `fingerprint`. Nested `Error.cause` chains and `AggregateError.errors` are summarized as bounded cause counts, types, and sources without copying nested messages or stacks. Raw stack text is included only with `includeErrorStack: true`.
+The helper records the error name/message, a typed exception with capture mechanism and handled state, and up to 32 ordered generated `stackFrames`, with query strings, hashes, and local absolute prefixes removed. Each frame carries filename, positive line/column, a conservatively parsed function name when the runtime provides one, and an optional matched Debug ID. Applications that create frames directly may also provide bounded `function`, `module`, and `inApp` identity. Existing first-frame metadata remains available for compatible grouping and tooling. The helper also emits an `issueGroupingKey` based on source, error type, and the sanitized first frame, plus an optional app-owned `issueFingerprint` when you pass a stable, safe, low-cardinality `fingerprint`. Nested `Error.cause` chains and `AggregateError.errors` are summarized as bounded cause counts, types, and sources without copying nested messages or stacks. Raw stack text is included only with `includeErrorStack: true`.
+
+Use `addBreadcrumb()` for explicit navigation, state, action, or network steps that should appear on later issues. The client keeps only the most recent 64 entries and marks an issue with `breadcrumbsTruncated: true` after older entries are evicted. `clearBreadcrumbs()` removes the current history.
+
+```js
+client.addBreadcrumb({
+  category: "checkout",
+  type: "user",
+  level: "info",
+  message: "Submitted checkout",
+  data: { attempt: 2 }
+});
+```
+
+Breadcrumb timestamps default to the current time. Each entry accepts only fixed keys, a bounded message, and at most eight flat primitive data fields. Nested objects, arrays, invalid timestamps, control characters, and oversized values are rejected. Do not include authentication material, user-entered text, raw identifiers, full URLs, query strings, headers, or request/response bodies. The SDK does not capture console output, DOM text, or network payloads to build breadcrumbs.
+
+## Shared Telemetry Context
+
+Give issues, logs, spans, actions, metrics, releases, and environments the same bounded identity and correlation data with the versioned `context` option. The JavaScript framework clients accept the same option, so middleware-generated and app-created events share one resource, deployment, session, subject, trace, and tag vocabulary.
+
+```js
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-web",
+  sdkVersion: "1.0.0",
+  context: {
+    schemaVersion: 1,
+    resource: {
+      service: { name: "checkout-web", version: "1.0.0" },
+      deployment: { environment: "production", release: "web@1.0.0" },
+      runtime: { name: "browser" },
+      framework: { name: "react", version: "19" }
+    },
+    session: { id: "session_01" },
+    subject: { id: "subject_01", kind: "anonymous" },
+    tags: { plan: "team", region: "eu" }
+  }
+});
+
+client.action("evt_checkout_started", new Date().toISOString(), {
+  name: "checkout.started",
+  status: "success",
+  context: {
+    schemaVersion: 1,
+    trace: {
+      traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+      spanId: "b7ad6b7169203331",
+      sampled: true
+    },
+    tags: { funnel: "checkout" }
+  }
+});
+```
+
+Client context is copied at creation and merged into every event. Event context can replace the current trace, session, or subject and can add or override individual resource fields and tags. Inputs are validated before queueing: unknown fields, all-zero trace identifiers, empty sections, oversized values, and more than 32 tags are rejected.
+
+For span events, the span's required top-level `traceId`, `spanId`, and optional `parentSpanId` remain the canonical span identity. Shared `context.trace` is intended to correlate issues, logs, actions, metrics, releases, and environments that do not already carry a required span identity.
+
+`subject.id` and `session.id` are app-owned correlation identifiers, not profile fields. Use opaque identifiers and never put names, email addresses, IP addresses, authentication values, free-form user input, or other personal data in context or tags. The SDK does not discover a user, device, location, session, or product interaction automatically. Capture only the fields your application has deliberately approved, rotate anonymous identifiers according to your privacy policy, and keep tags low-cardinality.
 
 ## Example
 
@@ -519,7 +577,9 @@ client.action("evt_payment_api", new Date().toISOString(), createNetworkMileston
 }));
 ```
 
-Timeline helpers keep only primitive metadata, strip query strings and hashes from route templates, normalize HTTP methods, infer failed network milestones from status codes `400` and above, and serialize through the existing `action` event type. Keep metadata low-cardinality, such as `sessionId`, `traceId`, `routeTemplate`, `method`, `statusCode`, `durationMs`, `screen`, `funnel`, and `step`.
+Timeline helpers keep only primitive metadata, strip query strings and hashes from route templates, normalize HTTP methods, infer failed network milestones from status codes `400` and above, and serialize through the existing `action` event type. Product actions also carry the reserved version-1 `interaction` analytics classification; network milestones do not. Keep metadata low-cardinality, such as `sessionId`, `traceId`, `routeTemplate`, `method`, `statusCode`, `durationMs`, `screen`, `funnel`, and `step`.
+
+`PRODUCT_ANALYTICS_SCHEMA_VERSION` and `PRODUCT_ANALYTICS_KINDS` expose the classification values supported by the installed package. The reserved analytics fields cannot be replaced through caller metadata. See the repository [product analytics capture contract](../../docs/product-analytics-contract.md) before constructing those fields directly.
 
 The packaged `agent-timeline` example shows a two-event checkout timeline that an AI assistant can inspect without session replay or payload capture. It combines product action metadata, network milestone metadata, explicit `traceparent` propagation, and a drop-only `eventFilter` that removes low-value info logs:
 
@@ -585,7 +645,7 @@ logger.error(new Error("payment failed"), "checkout failed");
 await destination.flush();
 ```
 
-The Pino adapter reads JSON log lines, maps Pino `trace`/`debug` to LogBrew `info`, `warn` to `warning`, `error` to `error`, and `fatal` to `critical`, captures primitive Pino fields as `context.*`, captures serialized error name/message, skips noisy runtime defaults, and omits stack text unless `includeErrorStack: true` is set. It does not patch Pino or replace application logger ownership.
+The Pino adapter reads JSON log lines, maps Pino `trace`/`debug` to LogBrew `info`, `warn` to `warning`, `error` to `error`, and `fatal` to `critical`, captures safe primitive Pino fields as `context.*`, captures serialized error name/message, skips noisy runtime defaults, and omits stack text unless `includeErrorStack: true` is set. Credential, authorization, cookie, body, payload, query, raw-URL, propagation-header, local-path, and stack fields are excluded even when they are primitive. It does not patch Pino or replace application logger ownership. The log message itself is telemetry, so retain normal Pino redaction and keep secrets or user-entered text out of messages.
 
 When the app also uses a LogBrew Node or framework request helper, pass `traceProvider: getActiveLogBrewTrace` from `@logbrew/node` to add the current active `traceId`, `spanId`, optional `parentSpanId`, and `sampled` flag to each captured log. The provider is called per record, invalid or missing contexts are ignored, and no raw propagation headers, request data, payloads, or stack traces are captured.
 

package/core.cjs

@@ -1,7 +1,9 @@
 const { buildCreateSupportTicketDraft } = require("./support-ticket.cjs");
+const { buildIssueDiagnosticsHelpers } = require("./issue-diagnostics.cjs");
 const { buildIssueStackHelpers } = require("./issue-stack.cjs");
 const { buildLogContextHelpers } = require("./log-context.cjs");
 const { buildOpenTelemetryHelpers } = require("./opentelemetry.cjs");
+const { buildTelemetryContextHelpers } = require("./telemetry-context.cjs");
 const { buildTraceContextHelpers } = require("./trace-context.cjs");
 
 const SEVERITY_ALIASES = new Map([
@@ -17,6 +19,9 @@ const SEVERITY_ALIASES = new Map([
 const SEVERITY_VALUES = new Set(SEVERITY_ALIASES.keys());
 const SPAN_STATUSES = new Set(["ok", "error"]);
 const ACTION_STATUSES = new Set(["queued", "running", "success", "failure"]);
+const PRODUCT_ANALYTICS_SCHEMA_VERSION = 1;
+const PRODUCT_ANALYTICS_KINDS = Object.freeze(["page_view", "screen_view", "interaction"]);
+const MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH = 256;
 const METRIC_KINDS = new Set(["counter", "gauge", "histogram"]);
 const NON_NEGATIVE_METRIC_KINDS = new Set(["counter", "histogram"]);
 const METRIC_TEMPORALITIES_BY_KIND = new Map([
@@ -28,6 +33,44 @@ const CONSOLE_METHODS = new Set(["debug", "info", "log", "warn", "error"]);
 const DEFAULT_CONSOLE_LEVELS = ["debug", "info", "log", "warn", "error"];
 const PINO_HOST_FIELD = ["host", "name"].join("");
 const PINO_RESERVED_FIELDS = new Set(["level", "time", "timestamp", "msg", "message", "err", "error", "pid", PINO_HOST_FIELD, "v"]);
+const PINO_SENSITIVE_CONTEXT_FIELDS = new Set([
+  "apikey",
+  "authorization",
+  "baggage",
+  "body",
+  "cookie",
+  "credentials",
+  "cwd",
+  "directory",
+  "dirname",
+  "errorstack",
+  "file",
+  "filename",
+  "filepath",
+  "headers",
+  "href",
+  "key",
+  "password",
+  "payload",
+  "proxyauthorization",
+  "query",
+  "querystring",
+  "requestbody",
+  "requestheaders",
+  "requesturl",
+  "responsebody",
+  "responseheaders",
+  "responseurl",
+  "search",
+  "secret",
+  "setcookie",
+  "stack",
+  "token",
+  "traceparent",
+  "tracestate",
+  "uri",
+  "url"
+]);
 const TRACEPARENT_PATTERN = /^([0-9a-fA-F]{2})-([0-9a-fA-F]{32})-([0-9a-fA-F]{16})-([0-9a-fA-F]{2})$/u;
 const ZERO_TRACE_ID = "00000000000000000000000000000000";
 const ZERO_SPAN_ID = "0000000000000000";
@@ -86,6 +129,18 @@ const {
 } = buildLogContextHelpers({ SdkError });
 
 const { javascriptStackFrames, validateIssueStackFrames } = buildIssueStackHelpers({ SdkError });
+const {
+  MAX_ISSUE_BREADCRUMBS,
+  cloneIssueDiagnostics,
+  createIssueException,
+  validateIssueBreadcrumb,
+  validateIssueDiagnostics
+} = buildIssueDiagnosticsHelpers({ SdkError, requireTimestamp });
+const {
+  cloneTelemetryContext,
+  mergeTelemetryContexts,
+  validateTelemetryContext
+} = buildTelemetryContextHelpers({ SdkError });
 
 class TransportError extends Error {
   constructor(code, message, retryable = false) {
@@ -138,6 +193,7 @@ class LogBrewClient {
     apiKey,
     sdkName,
     sdkVersion,
+    context,
     maxRetries = 2,
     eventFilter,
     maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
@@ -155,6 +211,7 @@ class LogBrewClient {
     requireNonEmpty("apiKey", apiKey);
     requireNonEmpty("sdkName", sdkName);
     requireNonEmpty("sdkVersion", sdkVersion);
+    const clientContext = validateTelemetryContext(context, "client telemetry context");
     requireNonNegativeInteger("maxRetries", maxRetries);
     if (eventFilter !== undefined && typeof eventFilter !== "function") {
       throw new SdkError("validation_error", "eventFilter must be a function");
@@ -202,6 +259,7 @@ class LogBrewClient {
       maxQueueBytes,
       maxQueueSize,
       onEventDropped,
+      context: clientContext,
       sdk: {
         name: sdkName,
         language: "javascript",
@@ -222,6 +280,7 @@ class LogBrewClient {
     maxQueueBytes,
     maxQueueSize,
     onEventDropped,
+    context,
     eventStore,
     eventQueueFactory,
     transport,
@@ -239,6 +298,7 @@ class LogBrewClient {
     this.maxQueueBytes = maxQueueBytes;
     this.maxQueueSize = maxQueueSize;
     this.onEventDropped = onEventDropped;
+    this.context = cloneTelemetryContext(context);
     this.transport = transport;
     this.sdk = sdk;
     this.maxRetries = maxRetries;
@@ -313,6 +373,8 @@ class LogBrewClient {
     this.lastAcceptedAtUnixMs = 0;
     this.lastDroppedAtUnixMs = 0;
     this.failedBatch = undefined;
+    this.issueBreadcrumbs = [];
+    this.issueBreadcrumbsTruncated = false;
     this.#scheduleAutomaticDelivery();
   }
 
@@ -416,6 +478,28 @@ class LogBrewClient {
     return purgedEvents;
   }
 
+  addBreadcrumb(breadcrumb, timestamp = new Date().toISOString()) {
+    if (this.closed) {
+      throw new SdkError("shutdown_error", "client is already shut down");
+    }
+    if (this.closing) {
+      throw new SdkError("shutdown_error", "client is shutting down");
+    }
+    const validated = validateIssueBreadcrumb(breadcrumb, timestamp);
+    if (this.issueBreadcrumbs.length === MAX_ISSUE_BREADCRUMBS) {
+      this.issueBreadcrumbs.shift();
+      this.issueBreadcrumbsTruncated = true;
+    }
+    this.issueBreadcrumbs.push(validated);
+  }
+
+  clearBreadcrumbs() {
+    const cleared = this.issueBreadcrumbs.length;
+    this.issueBreadcrumbs.splice(0, cleared);
+    this.issueBreadcrumbsTruncated = false;
+    return cleared;
+  }
+
   release(id, timestamp, attributes) {
     this.#pushEvent("release", id, timestamp, validateRelease(attributes));
   }
@@ -425,7 +509,18 @@ class LogBrewClient {
   }
 
   issue(id, timestamp, attributes) {
-    this.#pushEvent("issue", id, timestamp, validateIssue(attributes));
+    const withBreadcrumbs = attributes.breadcrumbs !== undefined || this.issueBreadcrumbs.length === 0
+      ? attributes
+      : {
+          ...attributes,
+          breadcrumbs: this.issueBreadcrumbs,
+          ...(
+            attributes.breadcrumbsTruncated === true || this.issueBreadcrumbsTruncated
+              ? { breadcrumbsTruncated: true }
+              : {}
+          )
+        };
+    this.#pushEvent("issue", id, timestamp, validateIssue(withBreadcrumbs));
   }
 
   log(id, timestamp, attributes) {
@@ -523,7 +618,11 @@ class LogBrewClient {
     }
     requireNonEmpty("event id", id);
     requireTimestamp(timestamp);
-    const event = { type: eventType, id, timestamp, attributes };
+    const context = mergeTelemetryContexts(this.context, attributes.context);
+    const eventAttributes = context === undefined
+      ? attributes
+      : { ...attributes, context };
+    const event = { type: eventType, id, timestamp, attributes: eventAttributes };
     if (this.eventFilter && this.eventFilter(cloneEvent(event)) === false) {
       return;
     }
@@ -1292,6 +1391,11 @@ function createIssueAttributesFromError(error, options = {}) {
     title: stringOrUndefined(options.title) ?? details.name,
     level: normalizeSeverity("issue level", options.level ?? "error"),
     ...(stringOrUndefined(options.message) ? { message: options.message } : details.message ? { message: details.message } : {}),
+    exception: createIssueException(
+      boundedIssueExceptionType(details.name),
+      stringOrUndefined(options.mechanism) ?? "javascript.error",
+      options.handled === undefined ? true : options.handled
+    ),
     ...(stackFrames.length > 0 ? { stackFrames } : {}),
     metadata: compactMetadata(metadata)
   };
@@ -1317,6 +1421,23 @@ function errorDetails(error) {
   return { name: "Error" };
 }
 
+function boundedIssueExceptionType(value) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  const characters = Array.from(normalized);
+  if (
+    normalized === ""
+    || characters.length > 256
+    || /[?#]/u.test(normalized)
+    || characters.some((character) => {
+      const code = character.codePointAt(0);
+      return code !== undefined && (code <= 31 || (code >= 127 && code <= 159));
+    })
+  ) {
+    return "Error";
+  }
+  return normalized;
+}
+
 function issueGroupingMetadata(source, details, frame, fingerprint) {
   const groupingKey = frame
     ? `${source}:${details.name}:${frame.filename}`
@@ -1467,6 +1588,7 @@ function logbrewLevelFromConsoleMethod(method) {
 
 function createProductActionAttributes(action, options = {}) {
   const details = productActionDetails(action);
+  const routeTemplate = sanitizeRouteTemplate(details.routeTemplate);
   return {
     name: details.name,
     status: details.status,
@@ -1474,12 +1596,13 @@ function createProductActionAttributes(action, options = {}) {
       source: "product.action",
       ...compactMetadata(options.metadata),
       ...compactMetadata(details.metadata),
-      routeTemplate: sanitizeRouteTemplate(details.routeTemplate),
+      routeTemplate,
       sessionId: stringOrUndefined(details.sessionId),
       traceId: stringOrUndefined(details.traceId),
       screen: stringOrUndefined(details.screen),
       funnel: stringOrUndefined(details.funnel),
-      step: stringOrUndefined(details.step)
+      step: stringOrUndefined(details.step),
+      ...productAnalyticsMetadata("interaction", routeTemplate || details.screen)
     })
   };
 }
@@ -1798,13 +1921,35 @@ function pinoMessage(record) {
 function pinoContextMetadata(record) {
   const metadata = {};
   for (const [key, value] of Object.entries(record)) {
-    if (!PINO_RESERVED_FIELDS.has(key) && isMetadataValue(value)) {
+    if (!PINO_RESERVED_FIELDS.has(key) && !isSensitivePinoContextField(key) && isMetadataValue(value)) {
       metadata[`context.${key}`] = value;
     }
   }
   return metadata;
 }
 
+function isSensitivePinoContextField(key) {
+  const normalized = key.toLowerCase().replace(/[^a-z0-9]+/gu, "");
+  return (
+    PINO_SENSITIVE_CONTEXT_FIELDS.has(normalized)
+    || normalized.endsWith("accesskey")
+    || normalized.endsWith("apikey")
+    || normalized.endsWith("authorization")
+    || normalized.endsWith("body")
+    || normalized.endsWith("cookie")
+    || normalized.endsWith("credentials")
+    || normalized.endsWith("headers")
+    || normalized.endsWith("password")
+    || normalized.endsWith("payload")
+    || normalized.endsWith("privatekey")
+    || normalized.endsWith("query")
+    || normalized.endsWith("secret")
+    || normalized.endsWith("stack")
+    || normalized.endsWith("token")
+    || normalized.endsWith("url")
+  );
+}
+
 function addPinoErrorMetadata(metadata, error, includeErrorStack) {
   if (!error) {
     return;
@@ -1942,7 +2087,7 @@ function cloneSpanLinks(links) {
 }
 
 function cloneEvent(event) {
-  const attributes = { ...event.attributes };
+  const attributes = { ...event.attributes, ...cloneIssueDiagnostics(event.attributes) };
   if (event.attributes.metadata !== undefined) {
     attributes.metadata = { ...event.attributes.metadata };
   }
@@ -1952,6 +2097,9 @@ function cloneEvent(event) {
   if (Array.isArray(event.attributes.links)) {
     attributes.links = cloneSpanLinks(event.attributes.links);
   }
+  if (event.attributes.context !== undefined) {
+    attributes.context = cloneTelemetryContext(event.attributes.context);
+  }
   return { ...event, attributes };
 }
 
@@ -1964,7 +2112,7 @@ function validateRelease(attributes) {
     version: attributes.version,
     ...(attributes.commit ? { commit: attributes.commit } : {}),
     ...(attributes.notes !== undefined ? { notes: attributes.notes } : {})
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function validateEnvironment(attributes) {
@@ -1972,7 +2120,7 @@ function validateEnvironment(attributes) {
   return withMetadata({
     name: attributes.name,
     ...(attributes.region !== undefined ? { region: attributes.region } : {})
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function validateIssue(attributes) {
@@ -1983,8 +2131,9 @@ function validateIssue(attributes) {
     title: attributes.title,
     level,
     ...(attributes.message !== undefined ? { message: attributes.message } : {}),
-    ...(stackFrames !== undefined ? { stackFrames } : {})
-  }, attributes.metadata);
+    ...(stackFrames !== undefined ? { stackFrames } : {}),
+    ...validateIssueDiagnostics(attributes)
+  }, attributes.metadata, attributes.context);
 }
 
 function validateLog(attributes) {
@@ -1994,7 +2143,7 @@ function validateLog(attributes) {
     message: attributes.message,
     level,
     ...(attributes.logger !== undefined ? { logger: attributes.logger } : {})
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function normalizeSeverity(label, value) {
@@ -2026,7 +2175,7 @@ function validateSpan(attributes) {
     ...(attributes.durationMs !== undefined ? { durationMs: attributes.durationMs } : {}),
     ...(events !== undefined ? { events } : {}),
     ...(links !== undefined ? { links } : {})
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function validateSpanEvents(events) {
@@ -2109,7 +2258,7 @@ function validateAction(attributes) {
   return withMetadata({
     name: attributes.name,
     status: attributes.status
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function validateMetric(attributes) {
@@ -2130,7 +2279,7 @@ function validateMetric(attributes) {
     value: attributes.value,
     unit: attributes.unit,
     temporality: attributes.temporality
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function productActionDetails(action) {
@@ -2209,6 +2358,34 @@ function sanitizeRouteTemplate(routeTemplate) {
   }
 }
 
+function productAnalyticsMetadata(kind, surface) {
+  const normalizedSurface = boundedProductAnalyticsSurface(surface);
+  return {
+    analyticsSchemaVersion: PRODUCT_ANALYTICS_SCHEMA_VERSION,
+    analyticsKind: kind,
+    analyticsSurface: normalizedSurface
+  };
+}
+
+function boundedProductAnalyticsSurface(surface) {
+  if (typeof surface !== "string") {
+    return undefined;
+  }
+  const normalized = surface.trim();
+  const characters = Array.from(normalized);
+  if (
+    normalized === ""
+    || characters.length > MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH
+    || characters.some((character) => {
+      const code = character.codePointAt(0);
+      return code !== undefined && (code <= 31 || (code >= 127 && code <= 159));
+    })
+  ) {
+    return undefined;
+  }
+  return normalized;
+}
+
 function normalizeHttpMethod(method) {
   const value = method === undefined ? "GET" : method;
   if (typeof value !== "string" || value.trim() === "") {
@@ -2252,11 +2429,14 @@ function stringOrUndefined(value) {
   return typeof value === "string" && value.trim() !== "" ? value : undefined;
 }
 
-function withMetadata(attributes, metadata) {
+function withMetadata(attributes, metadata, context) {
   const safeMetadata = cloneMetadata(metadata);
-  return safeMetadata === undefined
-    ? attributes
-    : { ...attributes, metadata: safeMetadata };
+  const safeContext = validateTelemetryContext(context);
+  return {
+    ...attributes,
+    ...(safeMetadata === undefined ? {} : { metadata: safeMetadata }),
+    ...(safeContext === undefined ? {} : { context: safeContext })
+  };
 }
 
 function normalizeConsoleLevels(levels) {
@@ -2307,6 +2487,8 @@ function formatConsoleArgument(value, includeErrorStack) {
 }
 
 module.exports = {
+  PRODUCT_ANALYTICS_KINDS,
+  PRODUCT_ANALYTICS_SCHEMA_VERSION,
   createBaggage,
   createIssueAttributesFromError,
   createNetworkMilestoneAttributes,