@logbrew/sdk 0.1.6 → 0.1.8

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
 
@@ -192,6 +250,7 @@ Use `client.metric()` when application code already knows the measurement name,
 ```js
 client.metric("evt_metric_001", "2026-06-02T10:00:06Z", {
   name: "checkout.requests",
+  description: "Number of checkout requests accepted by the application.",
   kind: "counter",
   value: 42,
   unit: "{request}",
@@ -200,7 +259,7 @@ client.metric("evt_metric_001", "2026-06-02T10:00:06Z", {
 });
 ```
 
-Metric `kind` must be `counter`, `gauge`, or `histogram`. Counters and histograms must be non-negative and use `delta` or `cumulative` temporality; gauges use `instant` temporality and may be negative. Keep metric metadata primitive and low-cardinality, such as service, region, or route template.
+Metric `kind` must be `counter`, `gauge`, or `histogram`. Counters and histograms must be non-negative and use `delta` or `cumulative` temporality; gauges use `instant` temporality and may be negative. An optional `description` gives humans and investigation tools stable meaning for the measurement; keep it generic, single-line, between 1 and 1,024 Unicode characters, and free of identifiers, personal data, or changing values. It is not a query dimension. Keep metric metadata primitive and low-cardinality, such as service, region, or route template.
 
 ## W3C Trace Context
 
@@ -519,7 +578,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:
 

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,7 +19,11 @@ 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 MAX_METRIC_DESCRIPTION_LENGTH = 1024;
 const NON_NEGATIVE_METRIC_KINDS = new Set(["counter", "histogram"]);
 const METRIC_TEMPORALITIES_BY_KIND = new Map([
   ["counter", new Set(["delta", "cumulative"])],
@@ -124,6 +130,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) {
@@ -176,6 +194,7 @@ class LogBrewClient {
     apiKey,
     sdkName,
     sdkVersion,
+    context,
     maxRetries = 2,
     eventFilter,
     maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
@@ -193,6 +212,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");
@@ -240,6 +260,7 @@ class LogBrewClient {
       maxQueueBytes,
       maxQueueSize,
       onEventDropped,
+      context: clientContext,
       sdk: {
         name: sdkName,
         language: "javascript",
@@ -260,6 +281,7 @@ class LogBrewClient {
     maxQueueBytes,
     maxQueueSize,
     onEventDropped,
+    context,
     eventStore,
     eventQueueFactory,
     transport,
@@ -277,6 +299,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;
@@ -351,6 +374,8 @@ class LogBrewClient {
     this.lastAcceptedAtUnixMs = 0;
     this.lastDroppedAtUnixMs = 0;
     this.failedBatch = undefined;
+    this.issueBreadcrumbs = [];
+    this.issueBreadcrumbsTruncated = false;
     this.#scheduleAutomaticDelivery();
   }
 
@@ -454,6 +479,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));
   }
@@ -463,7 +510,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) {
@@ -561,7 +619,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;
     }
@@ -1330,6 +1392,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)
   };
@@ -1355,6 +1422,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}`
@@ -1505,6 +1589,7 @@ function logbrewLevelFromConsoleMethod(method) {
 
 function createProductActionAttributes(action, options = {}) {
   const details = productActionDetails(action);
+  const routeTemplate = sanitizeRouteTemplate(details.routeTemplate);
   return {
     name: details.name,
     status: details.status,
@@ -1512,12 +1597,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)
     })
   };
 }
@@ -2002,7 +2088,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 };
   }
@@ -2012,6 +2098,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 };
 }
 
@@ -2024,7 +2113,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) {
@@ -2032,7 +2121,7 @@ function validateEnvironment(attributes) {
   return withMetadata({
     name: attributes.name,
     ...(attributes.region !== undefined ? { region: attributes.region } : {})
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function validateIssue(attributes) {
@@ -2043,8 +2132,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) {
@@ -2054,7 +2144,7 @@ function validateLog(attributes) {
     message: attributes.message,
     level,
     ...(attributes.logger !== undefined ? { logger: attributes.logger } : {})
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function normalizeSeverity(label, value) {
@@ -2086,7 +2176,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) {
@@ -2169,7 +2259,7 @@ function validateAction(attributes) {
   return withMetadata({
     name: attributes.name,
     status: attributes.status
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function validateMetric(attributes) {
@@ -2183,14 +2273,43 @@ function validateMetric(attributes) {
   if (NON_NEGATIVE_METRIC_KINDS.has(attributes.kind) && attributes.value < 0) {
     throw new SdkError("validation_error", `metric ${attributes.kind} value must be non-negative`);
   }
+  const description = metricDescriptionOrUndefined(attributes.description);
 
   return withMetadata({
     name: attributes.name,
+    ...(description === undefined ? {} : { description }),
     kind: attributes.kind,
     value: attributes.value,
     unit: attributes.unit,
     temporality: attributes.temporality
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
+}
+
+function metricDescriptionOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  const characters = typeof value === "string" ? Array.from(value) : [];
+  if (
+    typeof value !== "string"
+    || value.trim() === ""
+    || characters.length > MAX_METRIC_DESCRIPTION_LENGTH
+    || characters.some((character) => {
+      const code = character.codePointAt(0);
+      return code !== undefined && (
+        code <= 31
+        || (code >= 127 && code <= 159)
+        || code === 0x2028
+        || code === 0x2029
+      );
+    })
+  ) {
+    throw new SdkError(
+      "validation_error",
+      `metric description must be a non-blank string of at most ${MAX_METRIC_DESCRIPTION_LENGTH} non-control characters`
+    );
+  }
+  return value.trim();
 }
 
 function productActionDetails(action) {
@@ -2269,6 +2388,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() === "") {
@@ -2312,11 +2459,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) {
@@ -2367,6 +2517,8 @@ function formatConsoleArgument(value, includeErrorStack) {
 }
 
 module.exports = {
+  PRODUCT_ANALYTICS_KINDS,
+  PRODUCT_ANALYTICS_SCHEMA_VERSION,
   createBaggage,
   createIssueAttributesFromError,
   createNetworkMilestoneAttributes,