@logbrew/sdk 0.1.3 → 0.1.4

package/README.md

@@ -1,5 +1,9 @@
 # @logbrew/sdk
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LogBrewCo/sdk/main/assets/brand/logbrew-logo-transparent-512.png" alt="LogBrew logo" width="96" height="96">
+</p>
+
 Public JavaScript SDK for creating LogBrew event batches, validating them locally, and flushing them through a transport.
 
 ## Install
@@ -11,7 +15,7 @@ pnpm add @logbrew/sdk
 
 The package supports both ESM `import` and CommonJS `require`.
 The shipped package also includes `.d.ts` and `.d.cts` declarations so ESM and CommonJS TypeScript consumers can install it directly without a separate build step.
-The package ships copyable examples under `node_modules/@logbrew/sdk/examples/`. Use the fake `LOGBREW_API_KEY` placeholder in docs, keep the real key in your app configuration, and call `previewJson()` when you want to inspect queued JSON before sending. Type declarations document payload shapes such as `ReleaseAttributes`, `SpanAttributes`, `MetricAttributes`, transport responses, SDK errors, lifecycle helpers, W3C trace helpers, product timeline helpers, console capture, Pino destination, and Winston transport APIs.
+The package ships copyable examples under `node_modules/@logbrew/sdk/examples/`. Use the fake `LOGBREW_API_KEY` placeholder in docs, keep the real key in your app configuration, and call `previewJson()` when you want to inspect queued JSON before sending. Type declarations document payload shapes such as `ReleaseAttributes`, `SpanAttributes`, `MetricAttributes`, transport responses, SDK errors, lifecycle helpers, W3C trace helpers, support-ticket draft helpers, product timeline helpers, console capture, Pino destination, and Winston transport APIs.
 
 After install, discover and run the packaged examples:
 
@@ -21,6 +25,117 @@ node node_modules/@logbrew/sdk/examples/index.mjs agent-timeline
 npm --prefix node_modules/@logbrew/sdk/examples run agent-timeline
 ```
 
+For Vite apps, add the build-time release-artifact plugin to `vite.config.js`. It enables hidden source maps when your config has not chosen a source-map mode, injects matching Debug IDs after the build, strips embedded source text and local source prefixes, writes a privacy-bounded manifest, and can upload the prepared artifacts before the build completes:
+
+```js
+import { createLogBrewViteReleaseArtifactsPlugin } from "@logbrew/sdk/vite-release-artifacts";
+
+export default {
+  plugins: [
+    createLogBrewViteReleaseArtifactsPlugin({
+      release: "web@1.2.3",
+      environment: "production",
+      service: "checkout-web",
+      projectId: "550e8400-e29b-41d4-a716-446655440000",
+      minifiedPathPrefix: "https://cdn.example/assets",
+      upload: {
+        endpoint: "https://api.logbrew.com/api/release-artifacts",
+        allowHostedUpload: true,
+        maxRetries: 2
+      }
+    })
+  ]
+};
+```
+
+Set `LOGBREW_RELEASE_ARTIFACT_TOKEN` in the build environment to a dedicated release-artifact token. Use `tokenEnv` when your CI uses a different environment variable name, or `dryRun: true` to prepare the complete build output without a network request. The plugin runs only during Vite builds, keeps upload disabled when `upload` is omitted, and fails the build when preparation or upload cannot complete safely. It never uses normal SDK ingest keys or account/session API values.
+
+The package also ships the dependency-free `logbrew-release-artifacts` command for JavaScript source-map preparation and upload. Use it after your frontend build to inject matching Debug IDs, strip embedded source text by default, and create a privacy-bounded manifest that can be inspected before upload:
+
+```bash
+npx logbrew-release-artifacts prepare-js \
+  --build-dir dist \
+  --strip-sources-content \
+  --strip-source-prefix "$PWD" \
+  --write
+
+npx logbrew-release-artifacts manifest-js \
+  --build-dir dist \
+  --project-id 550e8400-e29b-41d4-a716-446655440000 \
+  --release web@1.2.3 \
+  --environment production \
+  --service checkout-web \
+  --minified-path-prefix https://cdn.example/assets \
+  > logbrew-release-artifacts.json
+
+npx logbrew-release-artifacts symbolicate-js \
+  --build-dir dist \
+  --manifest logbrew-release-artifacts.json \
+  --stack-frame "at checkout (https://cdn.example/assets/app.js:1:1)"
+
+npx logbrew-release-artifacts symbolicate-js \
+  --build-dir dist \
+  --manifest logbrew-release-artifacts.json \
+  --issue-event ./captured-logbrew-issue.json \
+  --source-root "$PWD" \
+  --context-lines 1
+
+npx logbrew-release-artifacts upload-js \
+  --build-dir dist \
+  --manifest logbrew-release-artifacts.json \
+  --endpoint http://127.0.0.1:4319/release-artifacts \
+  --dry-run
+```
+
+The `symbolicate-js` command resolves either one generated stack frame or a captured LogBrew issue event with `attributes.metadata.releaseArtifactDebugId`, `releaseArtifactCodeFile`, `errorFrameLine`, and `errorFrameColumn` through the prepared manifest. Use it to catch bad path prefixes, mismatched release/environment/service values, embedded source content, and local source-path leaks before deploy. Add `--source-root` only when you want the local report to include bounded app-owned source context; the source lines stay in the local command output and are not added to runtime SDK events or upload payloads. The `upload-js` command revalidates the manifest and can post the manifest/minified/source-map parts to a local loopback intake. For a hosted release-artifact endpoint, opt in explicitly and keep the release-artifact auth value in an environment variable:
+
+```bash
+export LOGBREW_RELEASE_ARTIFACT_AUTH="<release-artifact-auth>"
+
+npx logbrew-release-artifacts upload-js \
+  --build-dir dist \
+  --manifest logbrew-release-artifacts.json \
+  --endpoint https://api.logbrew.com/api/release-artifacts \
+  --token-env LOGBREW_RELEASE_ARTIFACT_AUTH \
+  --allow-hosted
+```
+
+Non-loopback endpoints require `--allow-hosted`, a UUID `projectId` created by `manifest-js --project-id`, HTTPS, and no embedded auth values, query strings, or fragments. Local loopback preparation remains valid without a project ID. The upload command never uses normal SDK ingest keys or account/session API auth values. Full backend-symbolicated issue support is separate from artifact upload until your project has completed hosted symbolication for its release.
+
+When you capture a JavaScript error, use `createIssueAttributesFromError()` to keep error metadata structured and source-map-friendly without sending raw stack text by default. Pass a Debug ID map from your app-owned build setup when you want the issue event to carry release-artifact metadata:
+
+```js
+import { createIssueAttributesFromError, LogBrewClient } from "@logbrew/sdk";
+
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-web",
+  sdkVersion: "1.0.0"
+});
+
+try {
+  checkout();
+} catch (error) {
+  client.issue(
+    "evt_checkout_error",
+    new Date().toISOString(),
+    createIssueAttributesFromError(error, {
+      release: "web@1.2.3",
+      environment: "production",
+      service: "checkout-web",
+      runtime: "browser",
+      fingerprint: "checkout-runtime-error",
+      debugIdMap: {
+        "https://cdn.example/assets/app.js": "11111111-2222-4333-8444-555555555555"
+      },
+      metadata: { routeTemplate: "/checkout" }
+    })
+  );
+}
+```
+
+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`.
+
 ## Example
 
 ```js
@@ -93,6 +208,7 @@ Use `parseTraceparent()`, `createTraceparent()`, and `spanAttributesFromTracepar
 
 ```js
 import {
+  createTraceContextHeaders,
   createTraceparentHeaders,
   LogBrewClient,
   RecordingTransport,
@@ -111,6 +227,13 @@ const span = spanAttributesFromTraceparent(incomingTraceparent, {
   spanId: "b7ad6b7169203331",
   status: "ok",
   durationMs: 18.4,
+  events: [{ name: "cache.lookup", metadata: { hit: false, system: "redis" } }],
+  links: [{
+    traceId: "11111111111111111111111111111111",
+    spanId: "2222222222222222",
+    sampled: true,
+    metadata: { relation: "batch_item" }
+  }],
   metadata: { service: "checkout" }
 });
 client.span("evt_checkout_span", "2026-06-02T10:00:04Z", span);
@@ -123,10 +246,123 @@ await fetch("https://example.invalid/payments", {
   })
 });
 
+await fetch("https://example.invalid/fulfillment", {
+  headers: createTraceContextHeaders({
+    traceId: span.traceId,
+    spanId: span.spanId,
+    traceFlags: "01",
+    tracestate: [{ key: "rojo", value: "00f067aa0ba902b7" }],
+    baggage: [{ key: "release", value: "checkout@1.2.3" }]
+  })
+});
+
 await client.flush(RecordingTransport.alwaysAccept());
 ```
 
-The helpers validate the W3C `version-traceId-parentSpanId-traceFlags` shape, reject all-zero trace/span ids, normalize valid ids to lowercase, expose the sampled flag from `traceFlags`, and keep span metadata primitive-only. `createTraceparentHeaders()` returns an explicit outbound carrier with only `traceparent`. The helpers do not install OpenTelemetry or patch HTTP clients; use them when you need explicit interop in code you own.
+The helpers validate the W3C `version-traceId-parentSpanId-traceFlags` shape, reject all-zero trace/span ids, normalize valid ids to lowercase, expose the sampled flag from `traceFlags`, and keep span metadata primitive-only. Optional span `events` record up to eight low-cardinality milestones with optional timestamps and primitive metadata only. Optional span `links` record up to eight privacy-bounded references to related trace/span IDs for batch, fan-out, queue, or retry workflows. `createTraceparentHeaders()` returns an explicit outbound carrier with only `traceparent`. `parseTracestate()`, `createTracestate()`, `parseBaggage()`, `createBaggage()`, and `createTraceContextHeaders()` add opt-in W3C `tracestate` and `baggage` propagation with bounded entry counts and header sizes. The helpers do not install OpenTelemetry, patch HTTP clients, infer baggage/tracestate automatically, or capture payloads; use them when you need explicit interop in code you own.
+
+If your app already installs OpenTelemetry JS, use `logbrewTraceContextFromCurrentOpenTelemetrySpan()` to copy the current active OTel span into a LogBrew child trace before recording logs, spans, or actions:
+
+```js
+import {
+  LogBrewClient,
+  logbrewTraceContextFromCurrentOpenTelemetrySpan
+} from "@logbrew/sdk";
+
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-web",
+  sdkVersion: "1.0.0"
+});
+
+const trace = logbrewTraceContextFromCurrentOpenTelemetrySpan();
+if (trace) {
+  client.log("evt_checkout_log", "2026-06-02T10:00:03Z", {
+    message: "checkout step rendered",
+    level: "info",
+    logger: "checkout",
+    metadata: {
+      release: "checkout@1.2.3",
+      environment: "production",
+      traceId: trace.traceId,
+      spanId: trace.spanId,
+      parentSpanId: trace.parentSpanId,
+      sampled: trace.sampled
+    }
+  });
+}
+```
+
+The OpenTelemetry helpers also accept explicit `spanContext` and `span` objects through `logbrewTraceContextFromOpenTelemetrySpanContext()` and `logbrewTraceContextFromOpenTelemetrySpan()`. They duck-type the public OTel shape, return `null` when OpenTelemetry is absent or invalid, create a fresh LogBrew child span ID by default, and copy only valid trace ID, parent span ID, and sampled state.
+
+If your app already owns an OpenTelemetry provider, `createLogBrewOpenTelemetrySpanProcessor()` can convert ended OTel `ReadableSpan` objects into queued LogBrew spans without making LogBrew own your provider, exporter, or instrumentation setup:
+
+```js
+import { SpanKind } from "@opentelemetry/api";
+import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import {
+  createLogBrewOpenTelemetrySpanProcessor,
+  LogBrewClient,
+  RecordingTransport
+} from "@logbrew/sdk";
+
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-api",
+  sdkVersion: "1.0.0"
+});
+const processor = createLogBrewOpenTelemetrySpanProcessor({
+  client,
+  transport: RecordingTransport.alwaysAccept(),
+  eventAttributeKeys: ["cache.hit"],
+  includeTraceSummary: true,
+  linkAttributeKeys: ["messaging.operation.name"],
+  metadata: { release: "checkout@1.2.3", environment: "production" }
+});
+const provider = new BasicTracerProvider({ spanProcessors: [processor] });
+const tracer = provider.getTracer("checkout-api");
+
+const span = tracer.startSpan("GET /orders/:id", {
+  kind: SpanKind.CLIENT,
+  attributes: {
+    "http.request.method": "GET",
+    "http.response.status_code": 200,
+    "http.route": "/orders/:id"
+  }
+});
+span.addEvent("cache.lookup", { "cache.hit": false });
+span.end();
+
+await processor.forceFlush();
+```
+
+If your OpenTelemetry setup already uses standard processors such as `SimpleSpanProcessor` or `BatchSpanProcessor`, use `createLogBrewOpenTelemetrySpanExporter()` instead:
+
+```js
+import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import {
+  createLogBrewOpenTelemetrySpanExporter,
+  LogBrewClient,
+  RecordingTransport
+} from "@logbrew/sdk";
+
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-api",
+  sdkVersion: "1.0.0"
+});
+const exporter = createLogBrewOpenTelemetrySpanExporter({
+  client,
+  transport: RecordingTransport.alwaysAccept(),
+  includeTraceSummary: true,
+  metadata: { release: "checkout@1.2.3", environment: "production" }
+});
+const provider = new BasicTracerProvider({
+  spanProcessors: [new SimpleSpanProcessor(exporter)]
+});
+```
+
+The OTel processor and exporter follow normal OTel sampled-span behavior by default and summarize up to eight span events and eight links. Set `includeTraceSummary: true` when you also want one synthetic `opentelemetry.trace:<root-name>` span per trace on processor `forceFlush()`/`shutdown()` or exporter `export()`/`forceFlush()`/`shutdown()`; the summary carries the trace ID, span count, error count, root span ID/name/kind, duration, and safe service/environment/route metadata so a batch reads like one request or transaction. They copy only a small safe default set such as service, environment, route, method, status code, span kind, instrumentation scope, exception type, exception event count, escaped exception count, and dropped-count metadata. Exception counts scan the readable span's events, while emitted exception type lists stay bounded. Escaped exception events on unset-status spans mark the LogBrew span as `error`; explicit OTel `OK` status stays `ok`. Additional event/link/span/resource attributes require explicit allowlists, and high-risk keys such as full URLs, headers, query strings, payloads, cookies, private auth values, DB statements, exception messages, and stacks stay blocked. Concurrent flush calls use one active send and one coalesced trailing drain: later spans leave the queue before their caller completes, while a failed active send consumes no extra retry budget. These helpers do not add an OpenTelemetry dependency, patch clients, own tracer providers, serialize baggage or tracestate, copy raw propagation headers, or capture request/response bodies.
 
 LogBrew severity categories are `info`, `warning`, `error`, and `critical`. The JavaScript SDK accepts common runtime aliases such as `trace`, `debug`, `warn`, and `fatal` for compatibility, then serializes canonical values before queued events are sent. The shared mapping is documented in the [LogBrew severity contract](../../docs/severity-contract.md).
 
@@ -150,6 +386,100 @@ const client = LogBrewClient.create({
 
 Prefer removing sensitive values at the source before calling LogBrew. `eventFilter` is intentionally drop-only: it avoids broad mutable event processing, global scopes, and hidden context that can make observability payloads harder to reason about.
 
+## 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.
+
+```js
+const transport = RecordingTransport.alwaysAccept();
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-api",
+  sdkVersion: "1.0.0",
+  transport,
+  deliveryIntervalMs: 5000,
+  deliveryQueueThreshold: 50
+});
+
+client.log("evt_checkout_ready", new Date().toISOString(), {
+  level: "info",
+  message: "checkout ready"
+});
+
+const health = client.deliveryHealth();
+console.log(JSON.stringify(health));
+await client.shutdown();
+```
+
+Set `automaticDelivery: false` for explicit manual-only operation; the owned transport still lets you call `flush()` and `shutdown()` without passing it again. Lower-level clients without an owned transport remain manual and continue to accept `flush(transport)` and `shutdown(transport)`. Retryable automatic failures use equal-jitter exponential backoff capped at 60 seconds. Authentication, rate-limit, and other non-retryable failures pause automatic sends while retaining the exact failed batch; an explicit successful `flush()` with the owned transport clears the pause.
+
+`deliveryHealth()` returns a frozen, JSON-serializable schema. It reports lifecycle and delivery states, memory or persistent storage, current and startup-hydrated queue counts/bytes, in-flight and coalesced work, client-lifetime accepted totals, fixed drop reasons, bounded retry state, transport status classes, and monotonic-within-client transition timestamps. Counters saturate instead of overflowing. The snapshot never includes event content or IDs, messages or attributes, authentication material, transport destinations or headers, filesystem paths, arbitrary metadata, numeric HTTP status, response text, or raw errors.
+
+## Queue Bounds
+
+`LogBrewClient` keeps a count-and-byte-bounded in-memory queue so heavy logging bursts cannot grow without limit before the next flush. The defaults are 1000 events and 4 MiB of compact serialized event data. `pendingEvents()` and `pendingBytes()` expose the retained amount without exposing event content.
+
+```js
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-api",
+  sdkVersion: "1.0.0",
+  maxQueueSize: 500,
+  maxQueueBytes: 2 * 1024 * 1024,
+  maxBatchEvents: 100,
+  maxBatchBytes: 256 * 1024,
+  onEventDropped(drop) {
+    console.warn("LogBrew dropped telemetry", drop.reason, drop.eventType);
+  }
+});
+```
+
+When either queue limit is full, LogBrew drops the incoming event and keeps earlier context unchanged. `queue_overflow` means the event-count limit was reached, `queue_bytes_overflow` means the compact event-byte limit was reached, and `event_too_large` means one event could not fit a request body by itself. 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.
+
+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.
+
+Flush requests are also bounded. Core and Node default to 100 events and 256 KiB of exact UTF-8 JSON per request. The browser factory defaults to 64 KiB so its normal request body cannot exceed the existing keepalive transport ceiling. A flush sends one queue snapshot in order, splitting it on either limit. The response reports total `attempts` and acknowledged `batches`. Existing clients that only set `maxQueueSize` keep working; the byte and batch settings are additive and are also accepted by the Node and browser client factories.
+
+## Flush Failures
+
+`flush()` calls are serialized so concurrent callers cannot send the same queue prefix. Each call owns the events present when its turn starts. Events captured while its transport is awaiting remain queued for the next flush. A 2xx response removes only that acknowledged prefix; if a later batch fails, the failed batch and every later event remain in their original order. Retries reuse the exact same request body.
+
+A `401` transport response raises `SdkError` with code `unauthenticated`; a `429` response raises code `rate_limited` and includes `retryAfterMs` when the transport exposes a `Retry-After` delay. Those outcomes pause automatic delivery because authentication and account usage are app/service-owned recovery states, not SDK retry loops. HTTP `408`, `5xx`, and retryable `TransportError` exhaustion retain the failed bytes and schedule bounded equal-jitter backoff. `maxRetries` is the number of immediate retries after the first attempt and must be a non-negative integer. `shutdown()` cancels automatic scheduling, rejects new capture while it drains once, closes only after success, and reopens the intact unsent remainder after failure. LogBrew does not derive account usage locally, sleep inside transport retries, or drop queued events on rate limits.
+
+## Support Ticket Drafts
+
+Use `createSupportTicketDraft()` when a developer or support agent needs a local JSON payload for the planned LogBrew support-ticket API. The helper validates the public source/category contract, converts JavaScript camelCase inputs to the planned backend create payload fields, and redacts token-like diagnostics before returning the object.
+
+```js
+import { createSupportTicketDraft } from "@logbrew/sdk";
+
+const draft = createSupportTicketDraft({
+  source: "sdk",
+  category: "ingest_failure",
+  title: "Telemetry flush failed",
+  description: "Flush returned usage_limit_exceeded",
+  projectId: "proj_123",
+  environment: "production",
+  runtime: "node@22",
+  framework: "express",
+  sdkPackage: "@logbrew/sdk",
+  sdkVersion: "0.1.3",
+  release: "checkout@1.2.3",
+  traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+  eventId: "evt_checkout_flush",
+  diagnostics: {
+    attemptCount: 2,
+    retryable: false,
+    endpoint: "https://api.example/ingest?debug=true",
+    apiKey: "redacted by helper"
+  }
+});
+
+console.log(JSON.stringify(draft, null, 2));
+```
+
+This helper does not send data, open support tickets, call `POST /api/support/tickets`, use account/session API credentials, or infer backend usage/quota state. Support routes are backend-owned and should only be called by an explicit user or agent action after backend reports deployed support-ticket routes. Diagnostics are bounded to JSON-like values; auth values, cookies, tokens, local paths, URL origins, hidden payloads, and unsupported objects are redacted or omitted.
+
 ## Agent-Readable Timelines
 
 Use `createProductActionAttributes()` and `createNetworkMilestoneAttributes()` when a service already knows important product steps or API milestones. The helpers create normal `action` event attributes with primitive metadata that can be analyzed across many sessions without visual replay, global HTTP patching, payload capture, or header capture.
@@ -257,6 +587,8 @@ await destination.flush();
 
 The Pino adapter reads JSON log lines, maps Pino `trace`/`debug` to LogBrew `info`, `warn` to `warning`, `error` to `error`, and `fatal` to `critical`, captures primitive Pino fields as `context.*`, captures serialized error name/message, skips noisy runtime defaults, and omits stack text unless `includeErrorStack: true` is set. It does not patch Pino or replace application logger ownership.
 
+When the app also uses a LogBrew Node or framework request helper, pass `traceProvider: getActiveLogBrewTrace` from `@logbrew/node` to add the current active `traceId`, `spanId`, optional `parentSpanId`, and `sampled` flag to each captured log. The provider is called per record, invalid or missing contexts are ignored, and no raw propagation headers, request data, payloads, or stack traces are captured.
+
 ## Winston Transport
 
 If a Node app already uses Winston, add the dependency-free LogBrew transport to the app-owned logger:
@@ -291,4 +623,6 @@ 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.
 
+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/examples/real-user-smoke.cjs

@@ -9,7 +9,7 @@ try {
   }
 }
 
-const { createTraceparentHeaders, LogBrewClient, RecordingTransport } = sdk;
+const { createTraceContextHeaders, createTraceparentHeaders, LogBrewClient, RecordingTransport } = sdk;
 
 const outgoingHeaders = createTraceparentHeaders({
   traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
@@ -19,6 +19,20 @@ const outgoingHeaders = createTraceparentHeaders({
 if (outgoingHeaders.traceparent !== "00-4bf92f3577b34da6a3ce929d0e0e4736-b7ad6b7169203331-01") {
   throw new Error("createTraceparentHeaders produced an unexpected carrier");
 }
+const outgoingContextHeaders = createTraceContextHeaders({
+  traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+  spanId: "b7ad6b7169203331",
+  traceFlags: "01",
+  tracestate: [{ key: "rojo", value: "00f067aa0ba902b7" }],
+  baggage: [{ key: "release", value: "checkout@1.2.3" }]
+});
+if (
+  outgoingContextHeaders.traceparent !== outgoingHeaders.traceparent
+  || outgoingContextHeaders.tracestate !== "rojo=00f067aa0ba902b7"
+  || outgoingContextHeaders.baggage !== "release=checkout%401.2.3"
+) {
+  throw new Error("createTraceContextHeaders produced an unexpected carrier");
+}
 
 const client = LogBrewClient.create({
   apiKey: "LOGBREW_API_KEY",

package/examples/real-user-smoke.mjs

@@ -5,7 +5,7 @@ const sdk = await import("@logbrew/sdk").catch(async (error) => {
   throw error;
 });
 
-const { createTraceparentHeaders, LogBrewClient, RecordingTransport } = sdk;
+const { createTraceContextHeaders, createTraceparentHeaders, LogBrewClient, RecordingTransport } = sdk;
 
 const outgoingHeaders = createTraceparentHeaders({
   traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
@@ -15,6 +15,20 @@ const outgoingHeaders = createTraceparentHeaders({
 if (outgoingHeaders.traceparent !== "00-4bf92f3577b34da6a3ce929d0e0e4736-b7ad6b7169203331-01") {
   throw new Error("createTraceparentHeaders produced an unexpected carrier");
 }
+const outgoingContextHeaders = createTraceContextHeaders({
+  traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+  spanId: "b7ad6b7169203331",
+  traceFlags: "01",
+  tracestate: [{ key: "rojo", value: "00f067aa0ba902b7" }],
+  baggage: [{ key: "release", value: "checkout@1.2.3" }]
+});
+if (
+  outgoingContextHeaders.traceparent !== outgoingHeaders.traceparent
+  || outgoingContextHeaders.tracestate !== "rojo=00f067aa0ba902b7"
+  || outgoingContextHeaders.baggage !== "release=checkout%401.2.3"
+) {
+  throw new Error("createTraceContextHeaders produced an unexpected carrier");
+}
 
 const client = LogBrewClient.create({
   apiKey: "LOGBREW_API_KEY",