@logbrew/sdk 0.1.31 → 0.1.33

package/README.md

@@ -506,7 +506,7 @@ When either queue limit is full, LogBrew drops the incoming event and keeps earl
 
 A fatal crash report (an issue with `fatal` or `critical` level) is the exception. When it does not fit, LogBrew removes the oldest queued events that are not fatal until it fits, and counts each removed event as `evicted_for_fatal`. It never removes events in a batch that is being sent or retried, and it removes nothing if the fatal still cannot fit. So a full queue drops a fatal only when everything else in it is fatal or in a batch that is being sent; that fatal is counted as `queue_overflow` or `queue_bytes_overflow`. A fatal larger than one request body is still dropped as `event_too_large`. Drop callbacks are advisory and must not interrupt application logging. The default queue remains memory-only; automatic delivery reduces normal flush work, while the app still calls `shutdown()` at its owned graceful-lifecycle boundary.
 
-LogBrew sees these drops too. The next request body carries the per-reason counts since the last accepted report, such as `"client_report":{"dropped_events":{"queue_overflow":3}}`. The client clears exactly those counts after a `2xx` response for that request; drops recorded while it is in flight, and counts in a failed or retried request, wait for the next one. A report never sends a request of its own, is left out when nothing was dropped, lists at most 16 reasons, caps each count at 1,000,000,000, and fits inside `maxBatchBytes`. Counts live in memory only, so drops not yet reported are lost when the process restarts.
+LogBrew sees these drops too. The next request body carries the per-reason counts since the last accepted report, such as `"client_report":{"report_id":"5f0c6a1e9b2d4c7a8e3f1b6d0a9c2e4f","dropped_events":{"queue_overflow":3}}`. The counts keep one `report_id` until a `2xx` response acknowledges a request that carried them, and LogBrew counts every resend of one report ID once, even when the resend carries different events. Drops recorded while a request is in flight wait for the next report. A report never sends a request of its own, is left out when nothing was dropped, lists at most 16 reasons, caps each count at 1,000,000,000, and fits inside `maxBatchBytes`. Without an `eventStore`, counts live in memory and drops not yet reported are lost when the process restarts. A store that also provides synchronous `loadClientReport()` and `saveClientReport(state)` keeps them: the client saves at once for a new report or reason and at most once a second during a drop burst, and after a restart resends a pending report under its original `report_id`. The Node and React Native persistent queues and browser `persistOffline` do this for you.
 
 Server runtimes can supply an explicit synchronous `eventStore` when they need restart recovery. The core loads and revalidates compact records during client creation, persists each accepted event before adding it to memory, persists an accepted prefix before removing it from memory, and closes the store only after successful shutdown. `purgePendingEvents()` clears both layers only while no flush or shutdown is queued or active. Implementations must provide synchronous `load`, `append`, `acknowledge`, `purge`, and `close` methods; use the encrypted `persistentQueue` adapter in `@logbrew/node` instead of writing a filesystem adapter from scratch. A store can also provide a synchronous `remove(indexes)` that deletes the records at those ascending `load()` positions. Fatal eviction needs it: a full queue on a store without `remove` drops the fatal as before.
 
@@ -697,6 +697,8 @@ await logbrewTransport.flush();
 
 The Winston adapter receives Winston `info` objects, maps `debug`/`silly` to LogBrew `info`, `warn` to `warning`, `error` to `error`, `fatal`/`critical` to `critical`, and other common Winston levels to `info`. It captures primitive info fields as `context.*`, captures nested `err`/`error` objects or formatted error stack name/message, omits stack text unless `includeErrorStack: true` is set, and exposes `onError` for capture failures. It does not mutate Winston globals or replace the app's logger.
 
+Each Winston message is also kept as an issue breadcrumb (category `log.winston`, message capped at 512 characters, no info fields), so the next issue shows the log lines that led to it. With `@logbrew/node`, breadcrumbs written during a request stay with that request's issues. Pass `breadcrumbs: false` to turn this off.
+
 Use the same `traceProvider: getActiveLogBrewTrace` option with LogBrew Node/framework helpers when you want Winston logs to carry the active request trace. The adapter only copies normalized W3C-shaped IDs and sampled state; it does not patch Winston globally or serialize arbitrary active context.
 
 Use a clearly fake placeholder like `LOGBREW_API_KEY` in examples. Call `flush` or `shutdown` to send queued events through a transport, and use `previewJson()` when you want a stable local JSON preview before sending anything.

package/browser-breadcrumbs.cjs

@@ -0,0 +1,194 @@
+"use strict";
+
+const MAX_MESSAGE_LENGTH = 512;
+const MAX_URL_LENGTH = 256;
+const CONSOLE_LEVELS = Object.freeze({
+  debug: "debug",
+  error: "error",
+  info: "info",
+  log: "info",
+  warn: "warning"
+});
+
+// Records console calls, fetch and XHR requests, and route changes as issue breadcrumbs.
+// Browser-safe and shared by @logbrew/browser and @logbrew/next/client. Returns an uninstall function
+// that puts back every patched method it still owns.
+function installBrowserBreadcrumbs(browserWindow, client, {
+  console: captureConsole = true,
+  ignoredUrls = [],
+  navigation = true,
+  network = true
+} = {}) {
+  const ignored = new Set(ignoredUrls.map((url) => sanitizeUrl(url, browserWindow)).filter(Boolean));
+  const add = (breadcrumb) => {
+    try {
+      client.addBreadcrumb(breadcrumb);
+    } catch {
+      // Breadcrumbs are advisory and never reach application code.
+    }
+  };
+  const restores = [];
+  if (captureConsole) {
+    restores.push(...patchConsole(browserWindow.console ?? globalThis.console, add));
+  }
+  if (network) {
+    restores.push(...patchFetch(browserWindow, add, ignored), ...patchXhr(browserWindow, add, ignored));
+  }
+  if (navigation) {
+    restores.push(...patchNavigation(browserWindow, add));
+  }
+  return () => {
+    for (const restore of restores.splice(0).reverse()) {
+      restore();
+    }
+  };
+}
+
+function patchConsole(target, add) {
+  if (!target) {
+    return [];
+  }
+  return Object.entries(CONSOLE_LEVELS).flatMap(([method, level]) => replaceMethod(target, method, (original) => (
+    function logBrewConsoleBreadcrumb(...args) {
+      const message = boundedText(consoleTemplate(args), MAX_MESSAGE_LENGTH);
+      if (message) {
+        add({ type: "debug", category: "console", level, message });
+      }
+      return original.apply(this, args);
+    }
+  )));
+}
+
+function patchFetch(browserWindow, add, ignored) {
+  return replaceMethod(browserWindow, "fetch", (original) => async function logBrewFetchBreadcrumb(input, init) {
+    const method = String(init?.method ?? input?.method ?? "GET").toUpperCase();
+    const url = sanitizeUrl(typeof input === "string" || input instanceof URL ? input : input?.url, browserWindow);
+    try {
+      const response = await original.call(this, input, init);
+      if (!ignored.has(url)) {
+        add(httpBreadcrumb("fetch", method, url, response?.status));
+      }
+      return response;
+    } catch (error) {
+      if (!ignored.has(url)) {
+        add({ ...httpBreadcrumb("fetch", method, url), level: "error" });
+      }
+      throw error;
+    }
+  });
+}
+
+function patchXhr(browserWindow, add, ignored) {
+  const prototype = browserWindow.XMLHttpRequest?.prototype;
+  if (!prototype) {
+    return [];
+  }
+  const state = new WeakMap();
+  return [
+    ...replaceMethod(prototype, "open", (original) => function logBrewXhrOpen(method, url, ...rest) {
+      state.set(this, { method: String(method ?? "GET").toUpperCase(), url: sanitizeUrl(url, browserWindow) });
+      return original.call(this, method, url, ...rest);
+    }),
+    ...replaceMethod(prototype, "send", (original) => function logBrewXhrSend(...args) {
+      const request = state.get(this);
+      if (request && !ignored.has(request.url) && typeof this.addEventListener === "function") {
+        this.addEventListener("loadend", () => {
+          add(httpBreadcrumb("xhr", request.method, request.url, this.status || undefined));
+        });
+      }
+      return original.apply(this, args);
+    })
+  ];
+}
+
+function patchNavigation(browserWindow, add) {
+  const history = browserWindow.history;
+  if (!history) {
+    return [];
+  }
+  let from = currentPath(browserWindow);
+  const record = () => {
+    const to = currentPath(browserWindow);
+    if (to && to !== from) {
+      add({ type: "navigation", category: "navigation", data: { ...(from ? { from } : {}), to } });
+      from = to;
+    }
+  };
+  const restores = ["pushState", "replaceState"].flatMap((method) => replaceMethod(history, method, (original) => (
+    function logBrewNavigationBreadcrumb(...args) {
+      const result = original.apply(this, args);
+      record();
+      return result;
+    }
+  )));
+  if (typeof browserWindow.addEventListener === "function") {
+    browserWindow.addEventListener("popstate", record);
+    restores.push(() => browserWindow.removeEventListener?.("popstate", record));
+  }
+  return restores;
+}
+
+function replaceMethod(target, name, wrap) {
+  const original = target?.[name];
+  if (typeof original !== "function") {
+    return [];
+  }
+  const replacement = wrap(original);
+  target[name] = replacement;
+  return [() => {
+    if (target[name] === replacement) {
+      target[name] = original;
+    }
+  }];
+}
+
+function httpBreadcrumb(category, method, url, status) {
+  const statusCode = Number.isInteger(status) && status > 0 ? status : undefined;
+  return {
+    type: "http",
+    category,
+    level: statusCode === undefined || statusCode < 400 ? "info" : statusCode >= 500 ? "error" : "warning",
+    data: {
+      method: method.slice(0, 16) || "GET",
+      ...(url ? { url } : {}),
+      ...(statusCode === undefined ? {} : { status_code: statusCode })
+    }
+  };
+}
+
+// Records the message template, never the interpolated arguments.
+function consoleTemplate(args) {
+  const [first] = args;
+  if (typeof first === "string") {
+    return first;
+  }
+  return first instanceof Error ? first.name || "Error" : "";
+}
+
+function currentPath(browserWindow) {
+  const pathname = browserWindow.location?.pathname;
+  return typeof pathname === "string" ? boundedText(pathname, MAX_URL_LENGTH) : undefined;
+}
+
+// Keeps scheme, host, and path; drops user info, query, and fragment.
+function sanitizeUrl(value, browserWindow) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  try {
+    const url = new URL(String(value), String(browserWindow.location?.href ?? "http://localhost/"));
+    return boundedText(`${url.protocol}//${url.host}${url.pathname}`, MAX_URL_LENGTH) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function boundedText(value, limit) {
+  const characters = Array.from(String(value), (character) => {
+    const code = character.codePointAt(0);
+    return code <= 31 || (code >= 127 && code <= 159) ? " " : character;
+  });
+  return Array.from(characters.join("").replace(/\s+/gu, " ").trim()).slice(0, limit).join("");
+}
+
+module.exports = { installBrowserBreadcrumbs };

package/core.cjs

@@ -96,6 +96,11 @@ const MAX_CLIENT_REPORT_REASONS = 16;
 const MAX_CLIENT_REPORT_COUNT = 1_000_000_000;
 const DELIVERY_HEALTH_SCHEMA_VERSION = 1;
 const EVENT_QUEUE_FACTORY = Symbol.for("@logbrew/sdk.eventQueueFactory");
+// Runtimes without an event store (browser storage) persist unreported drop counts through this seam.
+const CLIENT_REPORT_STORE = Symbol.for("@logbrew/sdk.clientReportStore");
+const CLIENT_REPORT_SAVE_INTERVAL_MS = 1_000;
+const CLIENT_REPORT_ID_PATTERN = /^[A-Za-z0-9_-]{16,64}$/u;
+const CLIENT_REPORT_REASON_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
 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");
@@ -228,6 +233,7 @@ class LogBrewClient {
     onEventDropped,
     eventStore,
     [EVENT_QUEUE_FACTORY]: eventQueueFactory,
+    [CLIENT_REPORT_STORE]: clientReportStore,
     transport,
     automaticDelivery = transport !== undefined,
     deliveryIntervalMs = DEFAULT_DELIVERY_INTERVAL_MS,
@@ -261,6 +267,9 @@ class LogBrewClient {
     if (eventStore !== undefined && eventQueueFactory !== undefined) {
       throw new SdkError("validation_error", "eventStore and event queue factory are mutually exclusive");
     }
+    if (clientReportStore !== undefined && !isClientReportStore(clientReportStore)) {
+      throw new SdkError("validation_error", "client report store must provide loadClientReport and saveClientReport");
+    }
     validateTransport(transport);
     if (typeof automaticDelivery !== "boolean") {
       throw new SdkError("validation_error", "automaticDelivery must be a boolean");
@@ -284,6 +293,7 @@ class LogBrewClient {
       deliveryQueueThreshold,
       eventStore,
       eventQueueFactory,
+      clientReportStore,
       eventFilter,
       maxBatchBytes,
       maxBatchEvents,
@@ -318,6 +328,7 @@ class LogBrewClient {
     breadcrumbProvider,
     eventStore,
     eventQueueFactory,
+    clientReportStore,
     transport,
     automaticDelivery,
     deliveryIntervalMs,
@@ -382,8 +393,14 @@ class LogBrewClient {
       queue_bytes_overflow: 0,
       queue_overflow: 0
     };
-    // In memory only: counts not yet acknowledged by a 2xx are lost on restart.
-    this.unreportedDropsByReason = {};
+    // A persistent store keeps counts not yet acknowledged by a 2xx across restarts.
+    this.clientReportStore = clientReportStore
+      ?? (isClientReportStore(resolvedEventStore) ? resolvedEventStore : undefined);
+    this.clientReportSavedAtMs = 0;
+    const restoredReport = loadClientReport(this.clientReportStore);
+    this.unreportedDropsByReason = restoredReport.unreported;
+    // Drop counts frozen under one report ID until a 2xx acknowledges a body that carried them.
+    this.pendingClientReport = restoredReport.pending;
     this.lastDropReason = "none";
     this.storage = resolvedEventStore ? "persistent" : "memory";
     this.hydratedEventCount = recovered.events.length;
@@ -618,6 +635,7 @@ class LogBrewClient {
       if (controlsAutomaticDelivery) {
         this.#recordAutomaticSuccess();
       }
+      this.#saveClientReport(true);
       if (this.eventStore) {
         try {
           requireSynchronousStoreResult("close", this.eventStore.close());
@@ -784,7 +802,9 @@ class LogBrewClient {
   #recordDroppedEvent(event, reason) {
     this.droppedEventCount = incrementBounded(this.droppedEventCount);
     this.droppedEventsByReason[reason] = incrementBounded(this.droppedEventsByReason[reason]);
+    const firstOfReason = this.unreportedDropsByReason[reason] === undefined;
     this.unreportedDropsByReason[reason] = Math.min(MAX_CLIENT_REPORT_COUNT, (this.unreportedDropsByReason[reason] ?? 0) + 1);
+    this.#saveClientReport(firstOfReason);
     this.lastDropReason = reason;
     this.lastDroppedAtUnixMs = nextBoundedTimestamp(this.lastDroppedAtUnixMs);
     if (!this.onEventDropped) {
@@ -949,9 +969,10 @@ class LogBrewClient {
       const batch = this.unacknowledgedBatch;
       const response = await this.#sendBatch(transport, batch.body);
       this.unacknowledgedBatch = undefined;
-      // Clear only what this body carried; drops recorded while it was in flight stay pending.
-      for (const [reason, count] of Object.entries(batch.droppedEvents ?? {})) {
-        this.unreportedDropsByReason[reason] -= count;
+      // Drops recorded while this body was in flight stay pending under a new report ID.
+      if (batch.carriesClientReport) {
+        this.pendingClientReport = undefined;
+        this.#saveClientReport(true);
       }
       this.#acknowledge(batch.eventsCount);
       this.acceptedBatchCount = incrementBounded(this.acceptedBatchCount);
@@ -979,11 +1000,8 @@ class LogBrewClient {
   }
 
   #nextBatch(maxEvents) {
-    const reported = Object.entries(this.unreportedDropsByReason).filter(([, count]) => count > 0);
-    const droppedEvents = reported.length > 0
-      ? Object.fromEntries(reported.slice(0, MAX_CLIENT_REPORT_REASONS))
-      : undefined;
-    const reportSuffix = droppedEvents && `],"client_report":${JSON.stringify({ dropped_events: droppedEvents })}}`;
+    const report = this.#pendingClientReport();
+    const reportSuffix = report && `],"client_report":${JSON.stringify(report)}}`;
     const reportedEvents = reportSuffix ? this.#batchEventCount(maxEvents, utf8ByteLength(reportSuffix)) : 0;
     const eventsCount = reportedEvents || this.#batchEventCount(maxEvents, this.batchSuffixBytes);
     if (eventsCount === 0) {
@@ -991,11 +1009,45 @@ class LogBrewClient {
     }
     return {
       body: `${this.batchPrefix}${this.serializedEvents.slice(0, eventsCount).join(",")}${reportedEvents ? reportSuffix : this.batchSuffix}`,
-      droppedEvents: reportedEvents ? droppedEvents : undefined,
+      carriesClientReport: reportedEvents > 0,
       eventsCount
     };
   }
 
+  // Freezes unreported drops under one stable ID, so every resend of them is counted once.
+  #pendingClientReport() {
+    if (this.pendingClientReport === undefined) {
+      const reported = Object.entries(this.unreportedDropsByReason).filter(([, count]) => count > 0);
+      if (reported.length === 0) {
+        return undefined;
+      }
+      const droppedEvents = Object.fromEntries(reported.slice(0, MAX_CLIENT_REPORT_REASONS));
+      for (const reason of Object.keys(droppedEvents)) {
+        delete this.unreportedDropsByReason[reason];
+      }
+      this.pendingClientReport = Object.freeze({ report_id: randomHex(16), dropped_events: droppedEvents });
+      this.#saveClientReport(true);
+    }
+    return this.pendingClientReport;
+  }
+
+  // Saves at once for a new report or reason, and at most once a second during a drop burst.
+  #saveClientReport(immediately) {
+    const now = Date.now();
+    if (!this.clientReportStore || (!immediately && now - this.clientReportSavedAtMs < CLIENT_REPORT_SAVE_INTERVAL_MS)) {
+      return;
+    }
+    this.clientReportSavedAtMs = now;
+    try {
+      requireSynchronousStoreResult("saveClientReport", this.clientReportStore.saveClientReport({
+        pending: this.pendingClientReport ?? null,
+        unreported: { ...this.unreportedDropsByReason }
+      }));
+    } catch {
+      // Drop counts are advisory: a failed save keeps them in memory and never blocks capture.
+    }
+  }
+
   #batchEventCount(maxEvents, suffixBytes) {
     let bodyBytes = this.batchPrefixBytes + suffixBytes;
     let eventsCount = 0;
@@ -1193,6 +1245,50 @@ function isFatalEvent(event) {
   return event.type === "issue" && event.attributes.level === "critical";
 }
 
+// Report IDs only need uniqueness, so runtimes without Web Crypto fall back to Math.random.
+function randomHex(byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  if (typeof globalThis.crypto?.getRandomValues === "function") {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function isClientReportStore(store) {
+  return typeof store?.loadClientReport === "function" && typeof store.saveClientReport === "function";
+}
+
+// Restores saved drop counts; anything unreadable or out of bounds is ignored, never fatal.
+function loadClientReport(store) {
+  let state;
+  try {
+    state = store ? requireSynchronousStoreResult("loadClientReport", store.loadClientReport()) : undefined;
+  } catch {
+    state = undefined;
+  }
+  const pending = state?.pending;
+  const pendingCounts = validClientReportCounts(pending?.dropped_events);
+  return {
+    pending: CLIENT_REPORT_ID_PATTERN.test(pending?.report_id ?? "") && Object.keys(pendingCounts).length > 0
+      ? Object.freeze({ report_id: pending.report_id, dropped_events: pendingCounts })
+      : undefined,
+    unreported: validClientReportCounts(state?.unreported)
+  };
+}
+
+function validClientReportCounts(counts) {
+  if (!counts || typeof counts !== "object" || Array.isArray(counts)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(counts).filter(([reason, count]) => (
+    CLIENT_REPORT_REASON_PATTERN.test(reason) && Number.isSafeInteger(count) && count >= 1 && count <= MAX_CLIENT_REPORT_COUNT
+  )).slice(0, MAX_CLIENT_REPORT_REASONS));
+}
+
 function incrementBounded(value) {
   return value >= Number.MAX_SAFE_INTEGER ? Number.MAX_SAFE_INTEGER : value + 1;
 }
@@ -1226,7 +1322,7 @@ function createEventStoreFromQueueFactory(eventQueueFactory, config) {
     restoreEvent: restoreStoredEvent
   });
   validateEventQueue(queue);
-  return {
+  const eventStore = {
     load() {
       const events = queue.events();
       const count = queue.length();
@@ -1256,6 +1352,14 @@ function createEventStoreFromQueueFactory(eventQueueFactory, config) {
       return queue.close();
     }
   };
+  if (typeof queue.remove === "function") {
+    eventStore.remove = (indexes) => queue.remove(indexes);
+  }
+  if (isClientReportStore(queue)) {
+    eventStore.loadClientReport = () => queue.loadClientReport();
+    eventStore.saveClientReport = (state) => queue.saveClientReport(state);
+  }
+  return eventStore;
 }
 
 function validateEventQueue(queue) {
@@ -2864,8 +2968,11 @@ function formatConsoleArgument(value, includeErrorStack) {
   }
 }
 
+const { installBrowserBreadcrumbs } = require("./browser-breadcrumbs.cjs");
+
 module.exports = {
   PRODUCT_ANALYTICS_KINDS,
+  installBrowserBreadcrumbs,
   PRODUCT_ANALYTICS_SCHEMA_VERSION,
   createBaggage,
   createIssueAttributesFromError,

package/index.d.ts

@@ -535,6 +535,8 @@ export type WinstonLogInfo = Record<string, unknown> & {
 /** Configuration for the dependency-free Winston transport adapter. */
 export type WinstonTransportConfig = {
   client: LogBrewClient;
+  /** Record each Winston message as an issue breadcrumb (category `log.winston`). Defaults to true. */
+  breadcrumbs?: boolean;
   logger?: string;
   metadata?: Metadata;
   traceProvider?: () => LogCorrelationTraceContext | null | undefined;
@@ -925,6 +927,25 @@ export declare class LogBrewClient {
 /** Install explicit console capture while preserving the target console's normal output behavior. */
 export declare function installLogBrewConsoleCapture(config: ConsoleCaptureConfig): ConsoleCaptureHandle;
 
+/** Options for automatic browser breadcrumbs. Every source defaults to true. */
+export type BrowserBreadcrumbOptions = {
+  console?: boolean;
+  network?: boolean;
+  navigation?: boolean;
+  /** URLs whose requests are not recorded, such as the LogBrew ingest endpoint. */
+  ignoredUrls?: string[];
+};
+
+/**
+ * Record console calls, fetch and XHR requests, and route changes in a browser window as issue
+ * breadcrumbs on the client. The wrappers only observe calls. Returns an uninstall function.
+ */
+export declare function installBrowserBreadcrumbs(
+  browserWindow: unknown,
+  client: LogBrewClient,
+  options?: BrowserBreadcrumbOptions
+): () => void;
+
 /** Create safe action attributes for an app-owned product step without automatic UI capture. */
 export declare function createProductActionAttributes(
   action: ProductActionInput,

package/index.js

@@ -16,6 +16,7 @@ export const {
   createTracestate,
   createLogBrewPinoDestination,
   createLogBrewWinstonTransport,
+  installBrowserBreadcrumbs,
   installLogBrewConsoleCapture,
   LogBrewClient,
   logbrewTraceContextFromCurrentOpenTelemetrySpan,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",
@@ -43,6 +43,7 @@
   },
   "files": [
     "index.cjs",
+    "browser-breadcrumbs.cjs",
     "core.cjs",
     "index.js",
     "index.d.ts",

package/react-native.d.ts

@@ -81,6 +81,7 @@ export {
   createTraceparent,
   createTraceparentHeaders,
   createTracestate,
+  installBrowserBreadcrumbs,
   installLogBrewConsoleCapture,
   LogBrewClient,
   logAttributesFromConsoleArgs,

package/react-native.js

@@ -3,6 +3,7 @@ import sdk from "./core.cjs";
 export const {
   PRODUCT_ANALYTICS_KINDS,
   PRODUCT_ANALYTICS_SCHEMA_VERSION,
+  installBrowserBreadcrumbs,
   createBaggage,
   createIssueAttributesFromError,
   createNetworkMilestoneAttributes,

package/winston.cjs

@@ -3,6 +3,10 @@ const { Writable } = require("node:stream");
 const { LogBrewClient, SdkError } = require("./core.cjs");
 const { buildLogContextHelpers } = require("./log-context.cjs");
 
+// Runtime packages with request scopes (such as @logbrew/node) register a recorder that keeps
+// breadcrumbs with the active request instead of the whole client.
+const BREADCRUMB_RECORDER = Symbol.for("@logbrew/sdk.breadcrumbRecorder");
+const MAX_BREADCRUMB_MESSAGE_LENGTH = 512;
 const WINSTON_RESERVED_FIELDS = new Set([
   "level",
   "message",
@@ -30,6 +34,7 @@ function createLogBrewWinstonTransport(config) {
   }
 
   const transport = config.transport;
+  const breadcrumbs = config.breadcrumbs !== false;
   const flushOnWrite = config.flushOnWrite === true;
   const includeErrorStack = config.includeErrorStack === true;
   const logger = config.logger ?? "winston";
@@ -49,6 +54,9 @@ function createLogBrewWinstonTransport(config) {
     objectMode: true,
     write(info, _encoding, callback) {
       try {
+        if (breadcrumbs) {
+          recordWinstonBreadcrumb(client, info);
+        }
         captureWinstonInfo({
           client,
           eventIdPrefix,
@@ -128,6 +136,49 @@ function captureWinstonInfo(config) {
   }
 }
 
+function recordWinstonBreadcrumb(client, info) {
+  if (!info || Array.isArray(info) || typeof info !== "object" || info.silent === true) {
+    return;
+  }
+  const breadcrumb = {
+    type: "debug",
+    category: "log.winston",
+    level: winstonBreadcrumbLevel(info.level),
+    message: Array.from(winstonMessage(info)).slice(0, MAX_BREADCRUMB_MESSAGE_LENGTH).join("")
+  };
+  const recorder = client.breadcrumbProvider ? globalThis[BREADCRUMB_RECORDER] : undefined;
+  try {
+    if (typeof recorder === "function") {
+      recorder(breadcrumb);
+    } else {
+      client.addBreadcrumb(breadcrumb);
+    }
+  } catch {
+    // Breadcrumbs are advisory; the log event below still goes out.
+  }
+}
+
+function winstonBreadcrumbLevel(level) {
+  switch (String(level).toLowerCase()) {
+    case "error":
+    case "crit":
+    case "critical":
+    case "fatal":
+    case "alert":
+    case "emerg":
+      return "error";
+    case "warn":
+    case "warning":
+      return "warning";
+    case "verbose":
+    case "debug":
+    case "silly":
+      return "debug";
+    default:
+      return "info";
+  }
+}
+
 function logAttributesFromWinstonInfo(info, options = {}) {
   if (!info || Array.isArray(info) || typeof info !== "object") {
     throw new SdkError("validation_error", "Winston info must be an object");