@logbrew/sdk 0.1.6 → 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:
 

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([
@@ -124,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) {
@@ -176,6 +193,7 @@ class LogBrewClient {
     apiKey,
     sdkName,
     sdkVersion,
+    context,
     maxRetries = 2,
     eventFilter,
     maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
@@ -193,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");
@@ -240,6 +259,7 @@ class LogBrewClient {
       maxQueueBytes,
       maxQueueSize,
       onEventDropped,
+      context: clientContext,
       sdk: {
         name: sdkName,
         language: "javascript",
@@ -260,6 +280,7 @@ class LogBrewClient {
     maxQueueBytes,
     maxQueueSize,
     onEventDropped,
+    context,
     eventStore,
     eventQueueFactory,
     transport,
@@ -277,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;
@@ -351,6 +373,8 @@ class LogBrewClient {
     this.lastAcceptedAtUnixMs = 0;
     this.lastDroppedAtUnixMs = 0;
     this.failedBatch = undefined;
+    this.issueBreadcrumbs = [];
+    this.issueBreadcrumbsTruncated = false;
     this.#scheduleAutomaticDelivery();
   }
 
@@ -454,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));
   }
@@ -463,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) {
@@ -561,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;
     }
@@ -1330,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)
   };
@@ -1355,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}`
@@ -1505,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,
@@ -1512,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)
     })
   };
 }
@@ -2002,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 };
   }
@@ -2012,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 };
 }
 
@@ -2024,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) {
@@ -2032,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) {
@@ -2043,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) {
@@ -2054,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) {
@@ -2086,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) {
@@ -2169,7 +2258,7 @@ function validateAction(attributes) {
   return withMetadata({
     name: attributes.name,
     status: attributes.status
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function validateMetric(attributes) {
@@ -2190,7 +2279,7 @@ function validateMetric(attributes) {
     value: attributes.value,
     unit: attributes.unit,
     temporality: attributes.temporality
-  }, attributes.metadata);
+  }, attributes.metadata, attributes.context);
 }
 
 function productActionDetails(action) {
@@ -2269,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() === "") {
@@ -2312,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) {
@@ -2367,6 +2487,8 @@ function formatConsoleArgument(value, includeErrorStack) {
 }
 
 module.exports = {
+  PRODUCT_ANALYTICS_KINDS,
+  PRODUCT_ANALYTICS_SCHEMA_VERSION,
   createBaggage,
   createIssueAttributesFromError,
   createNetworkMilestoneAttributes,

package/index.d.cts

@@ -2,6 +2,48 @@
 export type MetadataValue = string | number | boolean | null;
 /** Structured metadata map shared by public LogBrew event attribute types. */
 export type Metadata = Record<string, MetadataValue>;
+/** Bounded service, runtime, or framework identity shared by telemetry signals. */
+export type TelemetryNamedVersion = {
+  name: string;
+  version?: string;
+};
+/** Privacy-bounded resource identity shared by telemetry signals. */
+export type TelemetryResource = {
+  service?: TelemetryNamedVersion;
+  deployment?: { environment?: string; release?: string };
+  runtime?: TelemetryNamedVersion;
+  framework?: TelemetryNamedVersion;
+  operatingSystem?: TelemetryNamedVersion & { build?: string };
+  device?: { family?: string; model?: string; architecture?: string };
+  application?: { name?: string; version?: string; build?: string };
+};
+/** W3C-compatible correlation identity shared by non-span telemetry. */
+export type TelemetryTraceContext = {
+  traceId: string;
+  spanId?: string;
+  parentSpanId?: string;
+  sampled?: boolean;
+};
+/** Opaque application session identity. */
+export type TelemetrySessionContext = {
+  id: string;
+  previousId?: string;
+};
+/** Explicit app-owned subject identity; do not send names, email addresses, or IP addresses. */
+export type TelemetrySubjectContext = {
+  id: string;
+  kind: "anonymous" | "user";
+};
+/** Versioned shared context available on every LogBrew event type. */
+export type TelemetryContext = {
+  schemaVersion: 1;
+  resource?: TelemetryResource;
+  trace?: TelemetryTraceContext;
+  session?: TelemetrySessionContext;
+  subject?: TelemetrySubjectContext;
+  /** Up to 32 low-cardinality string dimensions with safe machine keys. */
+  tags?: Record<string, string>;
+};
 /** Canonical user-facing severity categories accepted by LogBrew. */
 export type Severity = "info" | "warning" | "error" | "critical";
 /** Runtime-level aliases accepted for compatibility and normalized before send. */
@@ -211,6 +253,7 @@ export type ReleaseAttributes = {
   commit?: string;
   notes?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Public environment event attributes. */
@@ -218,6 +261,7 @@ export type EnvironmentAttributes = {
   name: string;
   region?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Privacy-bounded generated JavaScript frame attached to an issue. */
@@ -228,18 +272,71 @@ export type IssueStackFrame = {
   line: number;
   /** One-based generated source column. */
   column: number;
+  /** Optional bounded function or method identity. */
+  function?: string;
+  /** Optional bounded module, package, or namespace identity. */
+  module?: string;
+  /** Whether application code classified this frame as app-owned. */
+  inApp?: boolean;
   /** Optional release-artifact Debug ID matched to this generated file. */
   debugId?: string;
 };
 
+/** Runtime path that captured an exception and whether it escaped that path. */
+export type IssueExceptionMechanism = {
+  /** Stable low-cardinality capture mechanism, such as `react.error_boundary`. */
+  type: string;
+  /** False when the exception escaped the capture boundary. */
+  handled: boolean;
+};
+
+/** Structured exception identity attached to an issue. */
+export type IssueException = {
+  /** Bounded runtime exception class or error type. */
+  type: string;
+  /** Capture mechanism when the SDK can determine it. */
+  mechanism?: IssueExceptionMechanism;
+};
+
+export type IssueBreadcrumbLevel = "debug" | "info" | "warning" | "error" | "critical";
+export type IssueBreadcrumbLevelInput = IssueBreadcrumbLevel | "trace" | "log" | "warn" | "fatal";
+export type IssueBreadcrumbDataValue = string | number | boolean | null;
+
+/** One privacy-bounded step that happened before an issue. */
+export type IssueBreadcrumb = {
+  /** RFC 3339 timestamp with an explicit timezone. */
+  timestamp: string;
+  /** Optional stable breadcrumb kind, such as `navigation` or `http`. */
+  type?: string;
+  /** Required low-cardinality source category. */
+  category: string;
+  level?: IssueBreadcrumbLevel;
+  /** Optional bounded display-safe description. */
+  message?: string;
+  /** At most eight flat primitive fields. Never include authentication material or raw request data. */
+  data?: Record<string, IssueBreadcrumbDataValue>;
+};
+
+/** Input accepted by `addBreadcrumb`; the client supplies the current timestamp when omitted. */
+export type IssueBreadcrumbInput = Omit<IssueBreadcrumb, "timestamp" | "level"> & {
+  timestamp?: string;
+  level?: IssueBreadcrumbLevelInput;
+};
+
 /** Public issue event attributes. */
 export type IssueAttributes = {
   title: string;
   level: SeverityInput;
   message?: string;
+  exception?: IssueException;
   /** Ordered privacy-bounded generated frames, capped at 32. */
   stackFrames?: IssueStackFrame[];
+  /** Oldest-to-newest issue history, capped at the most recent 64 entries. */
+  breadcrumbs?: IssueBreadcrumb[];
+  /** True when older or invalid history was omitted before capture. */
+  breadcrumbsTruncated?: boolean;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Options for creating privacy-bounded issue attributes from a JavaScript error. */
@@ -248,6 +345,10 @@ export type JavaScriptErrorIssueOptions = {
   level?: SeverityInput;
   message?: string;
   metadata?: Metadata;
+  /** Stable low-cardinality capture mechanism. Defaults to `javascript.error`. */
+  mechanism?: string;
+  /** Whether the error was handled by the capture boundary. Defaults to true. */
+  handled?: boolean;
   /** Metadata source label. Defaults to `javascript.error`. */
   source?: string;
   /** Active trace copied into primitive correlation metadata. */
@@ -276,6 +377,7 @@ export type LogAttributes = {
   level: SeverityInput;
   logger?: string;
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Console method names supported by the opt-in console capture helper. */
@@ -406,6 +508,7 @@ export type SpanAttributes = {
   events?: SpanEventSummary[];
   links?: SpanLinkSummary[];
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
 /** Public action event attributes. */
@@ -413,8 +516,18 @@ export type ActionAttributes = {
   name: string;
   status: "queued" | "running" | "success" | "failure";
   metadata?: Metadata;
+  context?: TelemetryContext;
 };
 
+/** Stable product-analytics event categories carried in reserved action metadata. */
+export type ProductAnalyticsKind = "page_view" | "screen_view" | "interaction";
+
+/** Current version of the reserved product-analytics metadata vocabulary. */
+export declare const PRODUCT_ANALYTICS_SCHEMA_VERSION: 1;
+
+/** Product-analytics categories understood by this SDK version. */
+export declare const PRODUCT_ANALYTICS_KINDS: readonly ProductAnalyticsKind[];
+
 /** App-owned product step input for agent-readable action timelines. */
 export type ProductActionInput = string | {
   name: string;
@@ -515,6 +628,7 @@ export type MetricAttributes = {
   unit: string;
   temporality: "delta" | "cumulative";
   metadata?: Metadata;
+  context?: TelemetryContext;
 } | {
   name: string;
   kind: "gauge";
@@ -656,6 +770,8 @@ export declare class LogBrewClient {
     apiKey: string;
     sdkName: string;
     sdkVersion: string;
+    /** Versioned context merged into every captured event; event context can override dynamic fields. */
+    context?: TelemetryContext;
     /** Retry attempts after the first send. Must be a non-negative integer; defaults to 2. */
     maxRetries?: number;
     eventFilter?: EventFilter;
@@ -690,6 +806,10 @@ export declare class LogBrewClient {
   previewJson(): string;
   /** Purge queued events from memory and persistence while no delivery operation is active. */
   purgePendingEvents(): number;
+  /** Add one explicit privacy-bounded breadcrumb to the client's 64-entry issue history. */
+  addBreadcrumb(breadcrumb: IssueBreadcrumbInput, timestamp?: string): void;
+  /** Clear the current issue breadcrumb history and return the number removed. */
+  clearBreadcrumbs(): number;
   release(id: string, timestamp: string, attributes: ReleaseAttributes): void;
   environment(id: string, timestamp: string, attributes: EnvironmentAttributes): void;
   issue(id: string, timestamp: string, attributes: IssueAttributes): void;