@logbrew/sdk 0.1.34 → 0.1.36

package/README.md

@@ -100,9 +100,9 @@ npx logbrew-release-artifacts upload-js \
   --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.
+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. Issues show symbolicated frames after LogBrew processes the matching release artifacts.
 
-When you capture a JavaScript error, use `createIssueAttributesFromError()` to keep error metadata structured and source-map-friendly without sending raw stack text by default. The helper also follows `Error.cause` and `AggregateError.errors` into a bounded parent-first exception graph. Automatic messages are marked redacted, every node reports whether frames were captured, truncated, or unavailable, and unsafe accessors, cycles, or the eight-node cap mark the graph truncated instead of inventing evidence. React, browser, Node, Next.js, and React Native helpers reuse this same core projection. See the shared [exception-chain contract](../../docs/exception-chain-evidence.md). A bundle prepared by the Vite plugin registers its Debug ID automatically; use `debugIdMap` only for a different app-owned build flow:
+When you capture a JavaScript error, use `createIssueAttributesFromError()` to keep error metadata structured and source-map-friendly without sending raw stack text by default. The helper also follows `Error.cause` and `AggregateError.errors` into a bounded parent-first exception graph. Automatic messages are marked redacted, every node reports whether frames were captured, truncated, or unavailable, and unsafe accessors, cycles, or the eight-node cap mark the graph truncated instead of inventing evidence. React, browser, Node, Next.js, and React Native helpers reuse this same core projection. See the shared [exception-chain contract](../../README.md#exception-chains). A bundle prepared by the Vite plugin registers its Debug ID automatically; use `debugIdMap` only for a different app-owned build flow:
 
 ```js
 import { createIssueAttributesFromError, LogBrewClient } from "@logbrew/sdk";
@@ -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.
@@ -434,7 +452,7 @@ These examples use `@opentelemetry/sdk-trace` 3. With `@opentelemetry/sdk-trace-
 
 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).
+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](../../README.md#what-you-can-capture).
 
 ## Event Filtering
 
@@ -481,7 +499,7 @@ 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.
+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. A `429` that carries a `Retry-After` delay or `code: "rate_limited"` waits that long, from 1 second to 1 hour plus up to 10 percent jitter, then resends the same batch on its own. Authentication failures, a `429` with `code: "usage_limit_exceeded"` or with neither signal, 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.
 
@@ -518,11 +536,11 @@ Flush requests are also bounded. Core and Node default to 100 events and 256 KiB
 
 `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.
+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. Transports can also return `errorCode` from the `429` body. A `429` with `retryAfterMs` or `errorCode: "rate_limited"` raises a retryable error and automatic delivery waits it out; `errorCode: "usage_limit_exceeded"` or a `429` with neither signal pauses automatic delivery, like a `401`. 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.
+Use `createSupportTicketDraft()` to build the JSON body for a LogBrew support ticket. The helper validates the source and category, converts JavaScript camelCase inputs to the ticket fields, and redacts token-like diagnostics before returning the object.
 
 ```js
 import { createSupportTicketDraft } from "@logbrew/sdk";
@@ -552,7 +570,7 @@ const draft = createSupportTicketDraft({
 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.
+The helper sends nothing. To open the ticket, send it to `POST /api/support/tickets` or run `logbrew support create`. See [Report a problem](https://docs.logbrew.co/guides/report-a-problem). 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
 
@@ -595,7 +613,7 @@ client.action("evt_payment_api", new Date().toISOString(), createNetworkMileston
 
 Timeline helpers keep only primitive metadata, strip query strings and hashes from route templates, normalize HTTP methods, infer failed network milestones from status codes `400` and above, and serialize through the existing `action` event type. Product actions also carry the reserved version-1 `interaction` analytics classification; network milestones do not. Keep metadata low-cardinality, such as `sessionId`, `traceId`, `routeTemplate`, `method`, `statusCode`, `durationMs`, `screen`, `funnel`, and `step`.
 
-`PRODUCT_ANALYTICS_SCHEMA_VERSION` and `PRODUCT_ANALYTICS_KINDS` expose the classification values supported by the installed package. The reserved analytics fields cannot be replaced through caller metadata. See the repository [product analytics capture contract](../../docs/product-analytics-contract.md) before constructing those fields directly.
+`PRODUCT_ANALYTICS_SCHEMA_VERSION` and `PRODUCT_ANALYTICS_KINDS` expose the classification values supported by the installed package. The reserved analytics fields cannot be replaced through caller metadata. See the repository [product analytics capture contract](../../README.md#product-analytics-capture) before constructing those fields directly.
 
 The packaged `agent-timeline` example shows a two-event checkout timeline that an AI assistant can inspect without session replay or payload capture. It combines product action metadata, network milestone metadata, explicit `traceparent` propagation, and a drop-only `eventFilter` that removes low-value info logs:
 

package/core.cjs

@@ -91,6 +91,9 @@ const DEFAULT_MAX_BATCH_BYTES = 256 * 1024;
 // 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;
+// A rate-limited batch waits from 1 second to 1 hour, plus up to 10 percent jitter, before it is sent again.
+const MIN_RATE_LIMIT_WAIT_MS = 1000;
+const MAX_RATE_LIMIT_WAIT_MS = 60 * 60 * 1000;
 const DEFAULT_DELIVERY_QUEUE_THRESHOLD = 50;
 const MAX_CLIENT_REPORT_REASONS = 16;
 const MAX_CLIENT_REPORT_COUNT = 1_000_000_000;
@@ -208,9 +211,12 @@ class RecordingTransport {
     }
 
     const retryAfterMs = retryAfterMsOrUndefined(next.retryAfterMs);
-    return retryAfterMs === undefined
-      ? { statusCode: next.statusCode, attempts: 1 }
-      : { statusCode: next.statusCode, attempts: 1, retryAfterMs };
+    return {
+      statusCode: next.statusCode,
+      attempts: 1,
+      ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+      ...(typeof next.errorCode === "string" ? { errorCode: next.errorCode } : {})
+    };
   }
 }
 
@@ -1101,6 +1107,13 @@ class LogBrewClient {
       return;
     }
     if (error instanceof SdkError && error.code === "rate_limited") {
+      if (error.retryable === true) {
+        this.automaticPauseReason = "none";
+        this.retryDelayMs = rateLimitWaitMs(
+          error.retryAfterMs ?? automaticRetryDelayMs(this.deliveryIntervalMs, this.consecutiveDeliveryFailures)
+        );
+        return;
+      }
       this.automaticPauseReason = "rate_limit";
       return;
     }
@@ -1151,7 +1164,9 @@ class LogBrewClient {
         }
         if (response.statusCode === 429) {
           throw new SdkError("rate_limited", "transport rate limited the batch", {
-            retryAfterMs: response.retryAfterMs
+            retryAfterMs: response.retryAfterMs,
+            retryable: response.errorCode !== "usage_limit_exceeded"
+              && (retryAfterMsOrUndefined(response.retryAfterMs) !== undefined || response.errorCode === "rate_limited")
           });
         }
         if (response.statusCode >= 200 && response.statusCode < 300) {
@@ -1191,6 +1206,11 @@ function automaticRetryDelayMs(deliveryIntervalMs, consecutiveFailures) {
   return minimumDelay + Math.floor(Math.random() * (maximumDelay - minimumDelay + 1));
 }
 
+function rateLimitWaitMs(delayMs) {
+  const bounded = Math.min(MAX_RATE_LIMIT_WAIT_MS, Math.max(MIN_RATE_LIMIT_WAIT_MS, delayMs));
+  return Math.min(MAX_RATE_LIMIT_WAIT_MS, bounded + Math.floor(Math.random() * (Math.floor(bounded / 10) + 1)));
+}
+
 function statusClass(statusCode) {
   if (statusCode >= 200 && statusCode < 300) {
     return "success";

package/index.d.ts

@@ -643,10 +643,10 @@ export type TimelineAttributesOptions = {
   metadata?: Metadata;
 };
 
-/** Planned backend support-ticket sources accepted by explicit draft helpers. */
+/** Support-ticket sources accepted by explicit draft helpers. */
 export type SupportTicketSource = "cli" | "sdk" | "website" | "docs" | "mobile";
 
-/** Planned backend support-ticket categories accepted by explicit draft helpers. */
+/** Support-ticket categories accepted by explicit draft helpers. */
 export type SupportTicketCategory =
   | "sdk_install_failure"
   | "ingest_failure"
@@ -686,7 +686,7 @@ export type SupportTicketDraftInput = {
   diagnostics?: Record<string, unknown>;
 };
 
-/** Planned backend create payload produced locally for explicit user or agent action. */
+/** Support-ticket create body built locally. It sends nothing. */
 export type SupportTicketDraft = {
   source: SupportTicketSource;
   category: SupportTicketCategory;
@@ -775,6 +775,8 @@ export type TransportResponse = {
   batches?: number;
   /** Optional retry delay from a rate-limit response, in milliseconds. */
   retryAfterMs?: number;
+  /** Optional `code` from a 429 response body, such as `rate_limited` or `usage_limit_exceeded`. */
+  errorCode?: string;
 };
 
 /** Minimal transport interface accepted by flush and shutdown operations. */
@@ -844,7 +846,7 @@ export declare class TransportError extends Error {
 
 /** Scripted transport for previewing, accepting, or failing queued event flushes. */
 export declare class RecordingTransport {
-  constructor(scriptedResponses?: Array<{ statusCode: number; retryAfterMs?: number } | Error>);
+  constructor(scriptedResponses?: Array<{ statusCode: number; retryAfterMs?: number; errorCode?: string } | Error>);
   /** Every request body sent through this transport instance. */
   sentBodies: string[];
   /** Create a transport that accepts queued flushes with a 202 response. */

package/package.json

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