@logbrew/sdk 0.1.33 → 0.1.35

package/README.md

@@ -252,6 +252,24 @@ const response = await client.shutdown(transport);
 console.error(JSON.stringify({ ok: true, status: response.statusCode, attempts: response.attempts, events: 6 }));
 ```
 
+## Read Events Back
+
+A successful send shows that LogBrew accepted the request. It does not show
+that you can read the event. After your app sends one event, read it
+back with a project read key:
+
+```bash
+logbrew projects keys create "<project_id>" --kind read \
+  --ingest-key-file "$HOME/.logbrew/setup-check.read" --json
+export LOGBREW_TOKEN="$(< "$HOME/.logbrew/setup-check.read")"
+logbrew read logs --since 1h --json
+logbrew issues --since 1h --json
+```
+
+A read key reads 1 project and cannot send telemetry. Run `unset LOGBREW_TOKEN`
+when you finish. [Read your events back](https://docs.logbrew.co/guides/verify-setup)
+covers key kinds, empty results, and how to revoke the key.
+
 ## Explicit Metrics
 
 Use `client.metric()` when application code already knows the measurement name, value, unit, and aggregation shape. Metrics are queued like other events and are not collected automatically.
@@ -367,7 +385,7 @@ If your app already owns an OpenTelemetry provider, `createLogBrewOpenTelemetryS
 
 ```js
 import { SpanKind } from "@opentelemetry/api";
-import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import { TracerProvider } from "@opentelemetry/sdk-trace";
 import {
   createLogBrewOpenTelemetrySpanProcessor,
   LogBrewClient,
@@ -387,7 +405,7 @@ const processor = createLogBrewOpenTelemetrySpanProcessor({
   linkAttributeKeys: ["messaging.operation.name"],
   metadata: { release: "checkout@1.2.3", environment: "production" }
 });
-const provider = new BasicTracerProvider({ spanProcessors: [processor] });
+const provider = new TracerProvider({ spanProcessors: [processor] });
 const tracer = provider.getTracer("checkout-api");
 
 const span = tracer.startSpan("GET /orders/:id", {
@@ -407,7 +425,7 @@ 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 { TracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace";
 import {
   createLogBrewOpenTelemetrySpanExporter,
   LogBrewClient,
@@ -425,11 +443,13 @@ const exporter = createLogBrewOpenTelemetrySpanExporter({
   includeTraceSummary: true,
   metadata: { release: "checkout@1.2.3", environment: "production" }
 });
-const provider = new BasicTracerProvider({
-  spanProcessors: [new SimpleSpanProcessor(exporter)]
+const provider = new TracerProvider({
+  spanProcessors: [new SimpleSpanProcessor({ exporter })]
 });
 ```
 
+These examples use `@opentelemetry/sdk-trace` 3. With `@opentelemetry/sdk-trace-base` 2, use `BasicTracerProvider` and `new SimpleSpanProcessor(exporter)`; the LogBrew processor and exporter work the same with both.
+
 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).

package/browser-breadcrumbs.cjs

@@ -49,6 +49,7 @@ function patchConsole(target, add) {
     return [];
   }
   return Object.entries(CONSOLE_LEVELS).flatMap(([method, level]) => replaceMethod(target, method, (original) => (
+    /** @this {Console} */
     function logBrewConsoleBreadcrumb(...args) {
       const message = boundedText(consoleTemplate(args), MAX_MESSAGE_LENGTH);
       if (message) {
@@ -60,7 +61,7 @@ function patchConsole(target, add) {
 }
 
 function patchFetch(browserWindow, add, ignored) {
-  return replaceMethod(browserWindow, "fetch", (original) => async function logBrewFetchBreadcrumb(input, init) {
+  return replaceMethod(browserWindow, "fetch", (original) => /** @this {*} */ 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 {
@@ -85,11 +86,11 @@ function patchXhr(browserWindow, add, ignored) {
   }
   const state = new WeakMap();
   return [
-    ...replaceMethod(prototype, "open", (original) => function logBrewXhrOpen(method, url, ...rest) {
+    ...replaceMethod(prototype, "open", (original) => /** @this {XMLHttpRequest} */ 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) {
+    ...replaceMethod(prototype, "send", (original) => /** @this {XMLHttpRequest} */ function logBrewXhrSend(...args) {
       const request = state.get(this);
       if (request && !ignored.has(request.url) && typeof this.addEventListener === "function") {
         this.addEventListener("loadend", () => {
@@ -115,6 +116,7 @@ function patchNavigation(browserWindow, add) {
     }
   };
   const restores = ["pushState", "replaceState"].flatMap((method) => replaceMethod(history, method, (original) => (
+    /** @this {History} */
     function logBrewNavigationBreadcrumb(...args) {
       const result = original.apply(this, args);
       record();

package/core.cjs

@@ -1595,6 +1595,7 @@ function installLogBrewConsoleCapture(config) {
 }
 
 function createConsoleCaptureMethod(config) {
+  /** @this {*} */
   return function logBrewConsoleMethod(...args) {
     config.original.apply(this, args);
     if (!config.state.installed) {

package/package.json

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