@logbrew/sdk 0.1.6 → 0.1.8

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;
@@ -510,13 +623,18 @@ export type SupportTicketDraft = {
 /** Public metric event attributes. Use low-cardinality metadata only. */
 export type MetricAttributes = {
   name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
   kind: "counter" | "histogram";
   value: number;
   unit: string;
   temporality: "delta" | "cumulative";
   metadata?: Metadata;
+  context?: TelemetryContext;
 } | {
   name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
   kind: "gauge";
   value: number;
   unit: string;
@@ -656,6 +774,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 +810,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;

package/index.d.ts

@@ -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;
@@ -510,13 +623,18 @@ export type SupportTicketDraft = {
 /** Public metric event attributes. Use low-cardinality metadata only. */
 export type MetricAttributes = {
   name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
   kind: "counter" | "histogram";
   value: number;
   unit: string;
   temporality: "delta" | "cumulative";
   metadata?: Metadata;
+  context?: TelemetryContext;
 } | {
   name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
   kind: "gauge";
   value: number;
   unit: string;
@@ -656,6 +774,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 +810,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;

package/index.js

@@ -1,6 +1,8 @@
 import sdk from "./index.cjs";
 
 export const {
+  PRODUCT_ANALYTICS_KINDS,
+  PRODUCT_ANALYTICS_SCHEMA_VERSION,
   createBaggage,
   createIssueAttributesFromError,
   createNetworkMilestoneAttributes,