@logbrew/sdk 0.1.29 → 0.1.31

package/README.md

@@ -456,7 +456,7 @@ Prefer removing sensitive values at the source before calling LogBrew. `eventFil
 
 ## Automatic Delivery
 
-When a client owns a `transport`, it automatically sends queued work after 5 seconds or when 50 events are waiting, whichever happens first. The one-shot timer starts only after capture, is `unref()`'d on Node.js, and is cancelled by manual flush, purge, or shutdown. Automatic sends reuse the same serialized flush path, immutable retry body, accepted-prefix acknowledgement, and persistent queue as manual calls. They do not install process, signal, page, or exit hooks.
+When a client owns a `transport`, it automatically sends queued work 1 second after the first queued event or when 50 events are waiting, whichever happens first, so a single event is readable in about a second while bursts still share one request. The one-shot timer starts only after capture, later events do not restart it, is `unref()`'d on Node.js, and is cancelled by manual flush, purge, or shutdown. Automatic sends reuse the same serialized flush path, immutable retry body, accepted-prefix acknowledgement, and persistent queue as manual calls. They do not install process, signal, page, or exit hooks.
 
 ```js
 const transport = RecordingTransport.alwaysAccept();
@@ -465,7 +465,7 @@ const client = LogBrewClient.create({
   sdkName: "checkout-api",
   sdkVersion: "1.0.0",
   transport,
-  deliveryIntervalMs: 5000,
+  deliveryIntervalMs: 1000,
   deliveryQueueThreshold: 50
 });
 

package/core.cjs

@@ -88,7 +88,8 @@ const DEFAULT_MAX_QUEUE_SIZE = 1000;
 const DEFAULT_MAX_QUEUE_BYTES = 4 * 1024 * 1024;
 const DEFAULT_MAX_BATCH_EVENTS = 100;
 const DEFAULT_MAX_BATCH_BYTES = 256 * 1024;
-const DEFAULT_DELIVERY_INTERVAL_MS = 5000;
+// One second matches the OpenTelemetry log processor default, so a lone event becomes readable quickly.
+const DEFAULT_DELIVERY_INTERVAL_MS = 1000;
 const MAX_DELIVERY_INTERVAL_MS = 60 * 1000;
 const DEFAULT_DELIVERY_QUEUE_THRESHOLD = 50;
 const MAX_CLIENT_REPORT_REASONS = 16;
@@ -96,6 +97,8 @@ const MAX_CLIENT_REPORT_COUNT = 1_000_000_000;
 const DELIVERY_HEALTH_SCHEMA_VERSION = 1;
 const EVENT_QUEUE_FACTORY = Symbol.for("@logbrew/sdk.eventQueueFactory");
 const CONTEXT_PROVIDER = Symbol.for("@logbrew/sdk.contextProvider");
+// Runtime packages supply request-scoped breadcrumbs through this seam; core merges them into issues.
+const BREADCRUMB_PROVIDER = Symbol.for("@logbrew/sdk.breadcrumbProvider");
 const MAX_ERROR_CAUSES = 5;
 const BUILTIN_ERROR_NAMES = new Set([
   "AggregateError",
@@ -215,6 +218,7 @@ class LogBrewClient {
     sdkVersion,
     context,
     [CONTEXT_PROVIDER]: contextProvider,
+    [BREADCRUMB_PROVIDER]: breadcrumbProvider,
     maxRetries = 2,
     eventFilter,
     maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
@@ -236,6 +240,9 @@ class LogBrewClient {
     if (contextProvider !== undefined && typeof contextProvider !== "function") {
       throw new SdkError("validation_error", "context provider must be a function");
     }
+    if (breadcrumbProvider !== undefined && typeof breadcrumbProvider !== "function") {
+      throw new SdkError("validation_error", "breadcrumb provider must be a function");
+    }
     requireNonNegativeInteger("maxRetries", maxRetries);
     if (eventFilter !== undefined && typeof eventFilter !== "function") {
       throw new SdkError("validation_error", "eventFilter must be a function");
@@ -285,6 +292,7 @@ class LogBrewClient {
       onEventDropped,
       context: clientContext,
       contextProvider,
+      breadcrumbProvider,
       sdk: {
         name: sdkName,
         language: "javascript",
@@ -307,6 +315,7 @@ class LogBrewClient {
     onEventDropped,
     context,
     contextProvider,
+    breadcrumbProvider,
     eventStore,
     eventQueueFactory,
     transport,
@@ -326,6 +335,7 @@ class LogBrewClient {
     this.onEventDropped = onEventDropped;
     this.context = cloneTelemetryContext(context);
     this.contextProvider = contextProvider;
+    this.breadcrumbProvider = breadcrumbProvider;
     this.transport = transport;
     this.sdk = sdk;
     this.maxRetries = maxRetries;
@@ -631,20 +641,46 @@ class LogBrewClient {
   }
 
   #pushIssue(id, timestamp, attributes) {
-    const withBreadcrumbs = attributes.breadcrumbs !== undefined || this.issueBreadcrumbs.length === 0
+    if (attributes.breadcrumbs !== undefined) {
+      return this.#pushEvent("issue", id, timestamp, validateIssue(attributes));
+    }
+    const provided = this.#providedBreadcrumbs();
+    const merged = provided.breadcrumbs.length === 0
+      ? this.issueBreadcrumbs
+      : [...this.issueBreadcrumbs, ...provided.breadcrumbs]
+        .sort((left, right) => Date.parse(left.timestamp) - Date.parse(right.timestamp));
+    const breadcrumbs = merged.slice(-MAX_ISSUE_BREADCRUMBS);
+    const truncated = attributes.breadcrumbsTruncated === true || this.issueBreadcrumbsTruncated
+      || provided.truncated || merged.length > breadcrumbs.length;
+    const withBreadcrumbs = breadcrumbs.length === 0
       ? attributes
-      : {
-          ...attributes,
-          breadcrumbs: this.issueBreadcrumbs,
-          ...(
-            attributes.breadcrumbsTruncated === true || this.issueBreadcrumbsTruncated
-              ? { breadcrumbsTruncated: true }
-              : {}
-          )
-        };
+      : { ...attributes, breadcrumbs, ...(truncated ? { breadcrumbsTruncated: true } : {}) };
     return this.#pushEvent("issue", id, timestamp, validateIssue(withBreadcrumbs));
   }
 
+  // Provider failures and invalid entries never cost the issue itself.
+  #providedBreadcrumbs() {
+    let provided;
+    try {
+      provided = this.breadcrumbProvider?.();
+    } catch {
+      return { breadcrumbs: [], truncated: false };
+    }
+    if (!provided || !Array.isArray(provided.breadcrumbs)) {
+      return { breadcrumbs: [], truncated: false };
+    }
+    const breadcrumbs = [];
+    let truncated = provided.truncated === true || provided.breadcrumbs.length > MAX_ISSUE_BREADCRUMBS;
+    for (const breadcrumb of provided.breadcrumbs.slice(-MAX_ISSUE_BREADCRUMBS)) {
+      try {
+        breadcrumbs.push(validateIssueBreadcrumb(breadcrumb));
+      } catch {
+        truncated = true;
+      }
+    }
+    return { breadcrumbs, truncated };
+  }
+
   #pushEvent(eventType, id, timestamp, attributes) {
     if (this.closed) {
       throw new SdkError("shutdown_error", "client is already shut down");

package/index.d.ts

@@ -886,7 +886,7 @@ export declare class LogBrewClient {
     transport?: Transport;
     /** Enable interval and queue-threshold delivery. Defaults to true when transport is supplied. */
     automaticDelivery?: boolean;
-    /** One-shot delivery interval in milliseconds. Defaults to 5000 and must not exceed 60000. */
+    /** One-shot delivery interval in milliseconds. Defaults to 1000 and must not exceed 60000. */
     deliveryIntervalMs?: number;
     /** Queue count that triggers delivery without waiting for the interval. Defaults to min(50, maxQueueSize). */
     deliveryQueueThreshold?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",