@logbrew/sdk 0.1.38 → 0.1.39

package/retry-delay.cjs

@@ -0,0 +1,32 @@
+const MAX_DELIVERY_INTERVAL_MS = 60_000;
+const MIN_RATE_LIMIT_WAIT_MS = 1000;
+const MAX_RATE_LIMIT_WAIT_MS = 3_600_000;
+const MAX_BACKOFF_EXPONENT = 30;
+const FIRST_FAILURE = 1;
+const BACKOFF_BASE = 2;
+const HALF = 2;
+const INCLUSIVE = 1;
+const JITTER_DIVISOR = 10;
+
+/**
+ * @param {number} deliveryIntervalMs
+ * @param {number} consecutiveFailures
+ * @returns {number}
+ */
+function automaticRetryDelayMs(deliveryIntervalMs, consecutiveFailures) {
+  const exponent = Math.min(consecutiveFailures - FIRST_FAILURE, MAX_BACKOFF_EXPONENT);
+  const maximumDelay = Math.min(MAX_DELIVERY_INTERVAL_MS, deliveryIntervalMs * (BACKOFF_BASE ** exponent));
+  const minimumDelay = Math.ceil(maximumDelay / HALF);
+  return minimumDelay + Math.floor(Math.random() * (maximumDelay - minimumDelay + INCLUSIVE));
+}
+
+/**
+ * @param {number} delayMs
+ * @returns {number}
+ */
+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 / JITTER_DIVISOR) + INCLUSIVE)));
+}
+
+module.exports = { MAX_DELIVERY_INTERVAL_MS, automaticRetryDelayMs, rateLimitWaitMs };

package/span-validation.cjs

@@ -0,0 +1,191 @@
+const { withMetadata } = require("./event-metadata.cjs");
+const { compactMetadata } = require("./log-context.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { parseTraceparent } = require("./trace-context.cjs");
+const {
+  isRecord,
+  optionalEntry,
+  requireAllowedValue,
+  requireNonEmpty,
+  requireSpanId,
+  requireTimestamp,
+  requireTraceId
+} = require("./validation.cjs");
+
+/**
+ * @import { Metadata, SpanAttributes, SpanEventSummary, SpanLinkSummary } from "./index.cjs"
+ * @import { EventAttributes } from "./event-validation.cjs"
+ */
+
+const MAX_SPAN_EVENTS = 8;
+const MAX_SPAN_LINKS = 8;
+const NO_ENTRIES = 0;
+const MIN_DURATION_MS = 0;
+/** @type {ReadonlySet<SpanAttributes["status"]>} */
+const SPAN_STATUSES = new Set(["ok", "error"]);
+
+/**
+ * @param {unknown} metadata
+ * @returns {Metadata | undefined}
+ */
+function nonEmptyMetadata(metadata) {
+  if (metadata === undefined) {
+    return undefined;
+  }
+  const compacted = compactMetadata(metadata);
+  return Object.keys(compacted).length > NO_ENTRIES ? compacted : undefined;
+}
+
+/**
+ * @param {unknown} durationMs
+ * @returns {number | undefined}
+ */
+function optionalSpanDuration(durationMs) {
+  if (durationMs === undefined) {
+    return undefined;
+  }
+  if (typeof durationMs !== "number" || Number.isNaN(durationMs) || durationMs < MIN_DURATION_MS) {
+    throw new SdkError("validation_error", "span durationMs must be non-negative");
+  }
+  return durationMs;
+}
+
+/**
+ * @param {unknown} list
+ * @param {string} label
+ * @param {number} maxEntries
+ * @returns {readonly unknown[] | undefined}
+ */
+function optionalBoundedList(list, label, maxEntries) {
+  if (list === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(list)) {
+    throw new SdkError("validation_error", `${label} must be an array`);
+  }
+  if (list.length > maxEntries) {
+    throw new SdkError("validation_error", `${label} must contain at most ${maxEntries} entries`);
+  }
+  return list.length === NO_ENTRIES ? undefined : list;
+}
+
+/**
+ * @param {unknown} event
+ * @returns {SpanEventSummary}
+ */
+function validateSpanEvent(event) {
+  if (!isRecord(event)) {
+    throw new SdkError("validation_error", "span event must be an object");
+  }
+  const name = requireNonEmpty("span event name", event["name"]);
+  const timestamp = event["timestamp"] === undefined ? undefined : requireTimestamp(event["timestamp"]);
+  return {
+    name,
+    ...optionalEntry("timestamp", timestamp),
+    ...optionalEntry("metadata", nonEmptyMetadata(event["metadata"]))
+  };
+}
+
+/**
+ * @param {unknown} events
+ * @returns {SpanEventSummary[] | undefined}
+ */
+function validateSpanEvents(events) {
+  return optionalBoundedList(events, "span events", MAX_SPAN_EVENTS)?.map((event) => validateSpanEvent(event));
+}
+
+/**
+ * @param {unknown} link
+ * @returns {SpanLinkSummary}
+ */
+function validateSpanLink(link) {
+  if (!isRecord(link)) {
+    throw new SdkError("validation_error", "span link must be an object");
+  }
+  const traceId = requireTraceId(link["traceId"]);
+  const spanId = requireSpanId("span link spanId", link["spanId"]);
+  const { sampled } = link;
+  if (sampled !== undefined && typeof sampled !== "boolean") {
+    throw new SdkError("validation_error", "span link sampled must be a boolean");
+  }
+  return {
+    traceId: traceId.toLowerCase(),
+
+    spanId: spanId.toLowerCase(),
+    ...optionalEntry("sampled", sampled),
+    ...optionalEntry("metadata", nonEmptyMetadata(link["metadata"]))
+  };
+}
+
+/**
+ * @param {unknown} links
+ * @returns {SpanLinkSummary[] | undefined}
+ */
+function validateSpanLinks(links) {
+  return optionalBoundedList(links, "span links", MAX_SPAN_LINKS)?.map((link) => validateSpanLink(link));
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateSpan(attributes) {
+  const name = requireNonEmpty("span name", attributes["name"]);
+  const traceId = requireNonEmpty("span traceId", attributes["traceId"]);
+  const spanId = requireNonEmpty("span spanId", attributes["spanId"]);
+  const status = requireAllowedValue("span status", attributes["status"], SPAN_STATUSES);
+  const parentSpanId = attributes["parentSpanId"] === undefined
+    ? undefined
+    : requireNonEmpty("span parentSpanId", attributes["parentSpanId"]);
+  const durationMs = optionalSpanDuration(attributes["durationMs"]);
+  const events = validateSpanEvents(attributes["events"]);
+  const links = validateSpanLinks(attributes["links"]);
+  return withMetadata({
+    name,
+
+    traceId,
+
+    spanId,
+
+    status,
+    ...optionalEntry("parentSpanId", parentSpanId),
+    ...optionalEntry("durationMs", durationMs),
+    ...optionalEntry("events", events),
+    ...optionalEntry("links", links)
+  }, attributes["metadata"], attributes["context"]);
+}
+
+/**
+ * @param {unknown} traceparent
+ * @param {unknown} attributes
+ * @returns {SpanAttributes}
+ */
+function spanAttributesFromTraceparent(traceparent, attributes) {
+  if (!isRecord(attributes)) {
+    throw new SdkError("validation_error", "span attributes must be an object");
+  }
+  const context = parseTraceparent(traceparent);
+  const name = requireNonEmpty("span name", attributes["name"]);
+  const spanId = requireSpanId("spanId", attributes["spanId"]);
+  const status = requireAllowedValue("span status", attributes["status"], SPAN_STATUSES);
+  const durationMs = optionalSpanDuration(attributes["durationMs"]);
+  const events = validateSpanEvents(attributes["events"]);
+  const links = validateSpanLinks(attributes["links"]);
+  return {
+    name,
+
+    traceId: context.traceId,
+
+    spanId: spanId.toLowerCase(),
+
+    parentSpanId: context.parentSpanId,
+
+    status,
+    ...optionalEntry("durationMs", durationMs),
+    ...optionalEntry("events", events),
+    ...optionalEntry("links", links),
+    ...optionalEntry("metadata", attributes["metadata"] === undefined ? undefined : compactMetadata(attributes["metadata"]))
+  };
+}
+
+module.exports = { spanAttributesFromTraceparent, validateSpan };

package/stored-events.cjs

@@ -0,0 +1,243 @@
+const { isObjectLike } = require("./error-details.cjs");
+const { cloneEvent } = require("./event-clone.cjs");
+const { EVENT_VALIDATORS, isEventType } = require("./event-validation.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { utf8ByteLength } = require("./utf8.cjs");
+const { isRecord, requireNonEmpty, requireTimestamp } = require("./validation.cjs");
+
+/**
+ * @import { EventType, EventValidator, SdkEvent } from "./event-validation.cjs"
+ * @import { DeepReadonly } from "./validation.cjs"
+ * @typedef {{ event: DeepReadonly<SdkEvent>, eventBytes: number, serializedEvent: string }} StoredRecord
+ * @typedef {Readonly<Record<string, unknown>>} UnknownRecord
+ * @typedef {{
+ *   attributes: UnknownRecord,
+ *   event: UnknownRecord,
+ *   eventBytes: number,
+ *   header: { type: EventType, id: string, timestamp: string },
+ *   serializedEvent: string,
+ *   validator: EventValidator
+ * }} RecordParts
+ */
+
+const MIN_EVENT_BYTES = 0;
+const CONTEXT_SCHEMA_VERSION = 1;
+const KEY_INDEX = 0;
+const STEP = 1;
+
+/**
+ * @returns {InstanceType<typeof SdkError>}
+ */
+function invalidStoredRecord() {
+  return new SdkError("persistence_error", "event store returned an invalid record");
+}
+
+/**
+ * @param {string} operation
+ * @param {unknown} result
+ * @returns {unknown}
+ */
+function requireSynchronousStoreResult(operation, result) {
+  if (isObjectLike(result) && typeof Reflect.get(result, "then") === "function") {
+    throw new SdkError("persistence_error", `eventStore.${operation} must complete synchronously`);
+  }
+  return result;
+}
+
+/**
+ * @param {readonly [string, unknown]} left
+ * @param {readonly [string, unknown]} right
+ * @returns {number}
+ */
+function byKey(left, right) {
+  return left[KEY_INDEX].localeCompare(right[KEY_INDEX]);
+}
+
+/**
+ * @param {string} _key
+ * @param {unknown} entry
+ * @returns {unknown}
+ */
+function sortedEntries(_key, entry) {
+  if (!isRecord(entry)) {
+    return entry;
+  }
+  const entries = Object.entries(entry);
+  entries.sort(byKey);
+  return Object.fromEntries(entries);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function structuralJson(value) {
+  return JSON.stringify(value, sortedEntries);
+}
+
+/**
+ * @param {UnknownRecord} event
+ * @param {UnknownRecord} attributes
+ * @returns {{ event: UnknownRecord, attributes: UnknownRecord }}
+ */
+function recoveredEvent(event, attributes) {
+  const fatalAttributes = event["type"] === "issue" && attributes["level"] === "fatal"
+    ? { ...attributes, level: "critical" }
+    : attributes;
+  const { context } = fatalAttributes;
+  const recoveredAttributes = isRecord(context) && context["schemaVersion"] === undefined
+    ? { ...fatalAttributes, context: { schemaVersion: CONTEXT_SCHEMA_VERSION, ...context } }
+    : fatalAttributes;
+  return { attributes: recoveredAttributes, event: { ...event, attributes: recoveredAttributes } };
+}
+
+/**
+ * @param {unknown} eventBytes
+ * @param {unknown} serializedEvent
+ * @returns {Readonly<{ eventBytes: number, serializedEvent: string }>}
+ */
+function storedPayload(eventBytes, serializedEvent) {
+  if (typeof eventBytes !== "number" || !Number.isSafeInteger(eventBytes) || eventBytes <= MIN_EVENT_BYTES || typeof serializedEvent !== "string") {
+    throw invalidStoredRecord();
+  }
+  return { eventBytes, serializedEvent };
+}
+
+/**
+ * @param {UnknownRecord} event
+ * @param {Readonly<{ eventBytes: number, serializedEvent: string }>} payload
+ * @returns {RecordParts}
+ */
+function storedEventParts(event, payload) {
+  const { type } = event;
+  const validator = isEventType(type) ? EVENT_VALIDATORS.get(type) : undefined;
+  if (!isEventType(type) || validator === undefined) {
+    throw invalidStoredRecord();
+  }
+  const header = {
+    type,
+
+    id: requireNonEmpty("event id", event["id"]),
+
+    timestamp: requireTimestamp(event["timestamp"])
+  };
+  const { attributes } = event;
+  if (!isRecord(attributes)) {
+    throw invalidStoredRecord();
+  }
+  return { ...payload, attributes, event, header, validator };
+}
+
+/**
+ * @param {UnknownRecord} record
+ * @returns {RecordParts}
+ */
+function storedRecordParts(record) {
+  const { event, eventBytes, serializedEvent } = record;
+  if (!isRecord(event)) {
+    throw invalidStoredRecord();
+  }
+  return storedEventParts(event, storedPayload(eventBytes, serializedEvent));
+}
+
+/**
+ * @param {Readonly<RecordParts["header"]>} header
+ * @param {Readonly<{ event: UnknownRecord, attributes: UnknownRecord }>} recovered
+ * @param {EventValidator} validator
+ * @returns {StoredRecord}
+ */
+function normalizedRecord(header, recovered, validator) {
+  /** @type {SdkEvent} */
+  const normalizedEvent = { ...header, attributes: validator(recovered.attributes) };
+  const normalizedSerializedEvent = JSON.stringify(normalizedEvent);
+  if (structuralJson(normalizedEvent) !== structuralJson(recovered.event)) {
+    throw invalidStoredRecord();
+  }
+  return {
+    event: cloneEvent(normalizedEvent),
+    eventBytes: utf8ByteLength(normalizedSerializedEvent),
+    serializedEvent: normalizedSerializedEvent
+  };
+}
+
+/**
+ * @param {unknown} record
+ * @returns {StoredRecord}
+ */
+function normalizeRecord(record) {
+  if (!isRecord(record)) {
+    throw invalidStoredRecord();
+  }
+  const { attributes, event, eventBytes, header, serializedEvent, validator } = storedRecordParts(record);
+  if (JSON.stringify(event) !== serializedEvent || utf8ByteLength(serializedEvent) !== eventBytes) {
+    throw invalidStoredRecord();
+  }
+  return normalizedRecord(header, recoveredEvent(event, attributes), validator);
+}
+
+/**
+ * @param {unknown} record
+ * @returns {StoredRecord}
+ */
+function normalizeStoredRecord(record) {
+  try {
+    return normalizeRecord(record);
+  } catch (error) {
+    if (error instanceof SdkError && error.code === "persistence_error") {
+      throw error;
+    }
+    throw invalidStoredRecord();
+  }
+}
+
+/**
+ * @param {string} serializedEvent
+ * @returns {unknown}
+ */
+function parseStoredEvent(serializedEvent) {
+  try {
+    /** @type {unknown} */
+    const event = JSON.parse(serializedEvent);
+    return event;
+  } catch {
+    throw invalidStoredRecord();
+  }
+}
+
+/**
+ * @param {unknown} serializedEvent
+ * @returns {DeepReadonly<SdkEvent>}
+ */
+function restoreStoredEvent(serializedEvent) {
+  if (typeof serializedEvent !== "string" || serializedEvent === "") {
+    throw invalidStoredRecord();
+  }
+  return normalizeStoredRecord({
+    event: parseStoredEvent(serializedEvent),
+    eventBytes: utf8ByteLength(serializedEvent),
+    serializedEvent
+  }).event;
+}
+
+/**
+ * @param {readonly string[]} expected
+ * @param {readonly string[]} actual
+ * @returns {boolean}
+ */
+function isOrderedSubsequence(expected, actual) {
+  let index = 0;
+  for (const value of actual) {
+    if (value === expected[index]) {
+      index += STEP;
+    }
+  }
+  return index === expected.length;
+}
+
+module.exports = {
+  invalidStoredRecord,
+  isOrderedSubsequence,
+  normalizeStoredRecord,
+  requireSynchronousStoreResult,
+  restoreStoredEvent
+};

package/types/client.d.ts

@@ -0,0 +1,67 @@
+import type { ActionAttributes, EnvironmentAttributes, LogAttributes, MetricAttributes, ReleaseAttributes, SpanAttributes, TelemetryContext } from "./telemetry.js";
+import type { DeliveryHealthSnapshot, DroppedEvent, EventFilter, EventStore, IssueAdmission, Transport, TransportResponse } from "./delivery.js";
+import type { IssueAttributes, IssueBreadcrumbInput } from "./issues.js";
+
+/** Buffered public client for validating, previewing, and flushing LogBrew events. */
+declare class LogBrewClient {
+  /** Create a client from public SDK identity, retry, and API key settings. */
+  public static create(config: {
+    apiKey: string;
+    sdkName: string;
+    sdkVersion: string;
+    /** Versioned context merged into every captured event; event context can override dynamic fields. */
+    context?: TelemetryContext;
+    /** Retry attempts after the first send. Must be a non-negative integer; defaults to 2. */
+    maxRetries?: number;
+    eventFilter?: EventFilter;
+    /** Maximum queued compact event bytes. Defaults to 4 MiB. */
+    maxQueueBytes?: number;
+    maxQueueSize?: number;
+    /** Maximum events per request body. Defaults to 100. */
+    maxBatchEvents?: number;
+    /** Maximum UTF-8 request body bytes. Defaults to 256 KiB. */
+    maxBatchBytes?: number;
+    onEventDropped?: (drop: DroppedEvent) => void;
+    /** Optional app-scoped persistence adapter. Methods must complete synchronously. */
+    eventStore?: EventStore;
+    /** Client-owned transport used by automatic delivery and by flush/shutdown when no argument is supplied. */
+    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 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;
+  }): LogBrewClient;
+  /** Return the queued event count currently buffered in memory. */
+  public pendingEvents(): number;
+  /** Return compact serialized event bytes currently buffered in memory. */
+  public pendingBytes(): number;
+  /** Return the number of events dropped because the bounded in-memory queue was full. */
+  public droppedEvents(): number;
+  /** Return a frozen, content-free snapshot of queue and delivery lifecycle health. */
+  public deliveryHealth(): DeliveryHealthSnapshot;
+  /** Return the queued event batch as stable, pretty-printed JSON. */
+  public previewJson(): string;
+  /** Purge queued events from memory and persistence while no delivery operation is active. */
+  public purgePendingEvents(): number;
+  /** Add one explicit privacy-bounded breadcrumb to the client's 64-entry issue history. */
+  public addBreadcrumb(breadcrumb: IssueBreadcrumbInput, timestamp?: string): void;
+  /** Clear the current issue breadcrumb history and return the number removed. */
+  public clearBreadcrumbs(): number;
+  public release(id: string, timestamp: string, attributes: ReleaseAttributes): void;
+  public environment(id: string, timestamp: string, attributes: EnvironmentAttributes): void;
+  public issue(id: string, timestamp: string, attributes: IssueAttributes): void;
+  /** Capture once and report queue admission. Custom issue overrides run once and return unavailable. */
+  public issueWithAdmission(id: string, timestamp: string, attributes: IssueAttributes): IssueAdmission;
+  public log(id: string, timestamp: string, attributes: LogAttributes): void;
+  public span(id: string, timestamp: string, attributes: SpanAttributes): void;
+  public action(id: string, timestamp: string, attributes: ActionAttributes): void;
+  public metric(id: string, timestamp: string, attributes: MetricAttributes): void;
+  /** Flush one queue snapshot in bounded batches while preserving concurrent captures and retry bodies. */
+  public flush(transport?: Transport): Promise<TransportResponse>;
+  /** Reject new capture, flush queued events, then close; a failed flush reopens the intact remainder. */
+  public shutdown(transport?: Transport): Promise<TransportResponse>;
+}
+
+export { LogBrewClient };

package/types/delivery.d.ts

@@ -0,0 +1,125 @@
+import type { ActionAttributes, EnvironmentAttributes, LogAttributes, MetricAttributes, ReleaseAttributes, SpanAttributes } from "./telemetry.js";
+import type { IssueAttributes } from "./issues.js";
+
+declare const DELIVERY_HEALTH_SCHEMA_VERSION = 1;
+
+/** Public event union used in preview and transport payloads. */
+type Event =
+  | { type: "release"; id: string; timestamp: string; attributes: ReleaseAttributes }
+  | { type: "environment"; id: string; timestamp: string; attributes: EnvironmentAttributes }
+  | { type: "issue"; id: string; timestamp: string; attributes: IssueAttributes }
+  | { type: "log"; id: string; timestamp: string; attributes: LogAttributes }
+  | { type: "span"; id: string; timestamp: string; attributes: SpanAttributes }
+  | { type: "action"; id: string; timestamp: string; attributes: ActionAttributes }
+  | { type: "metric"; id: string; timestamp: string; attributes: MetricAttributes };
+
+/** Drop-only event filter called after validation and before an event is queued. */
+type EventFilter = (event: Event) => boolean | void;
+
+/** Canonical compact event record exchanged with an app-owned synchronous persistence adapter. */
+type StoredEvent = {
+  event: Event;
+  serializedEvent: string;
+  eventBytes: number;
+};
+
+/** Explicit synchronous persistence seam used to recover and acknowledge queued events safely. */
+type EventStore = {
+  load(): StoredEvent[];
+  append(record: StoredEvent): void;
+  acknowledge(count: number): void;
+  /** Removes the records at ascending `load()` indexes; without it, fatal issues cannot evict queued events. */
+  remove?(indexes: number[]): void;
+  purge(): void;
+  close(): void;
+};
+
+/** Queue drop notification emitted when a bounded in-memory queue is full. */
+type DroppedEvent = {
+  reason: "event_too_large" | "evicted_for_fatal" | "queue_bytes_overflow" | "queue_overflow";
+  eventType: Event["type"];
+  eventId: string;
+  droppedEvents: number;
+};
+
+/** Stable transport response returned from flush and shutdown operations. */
+type TransportResponse = {
+  /** Final HTTP-like status returned by the transport. */
+  statusCode: number;
+  /** Number of transport attempts used for the flush. */
+  attempts: number;
+  /** Number of distinct batches acknowledged; client flush/shutdown responses always include it. */
+  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. */
+type Transport = {
+  send(apiKey: string, body: string): TransportResponse | Promise<TransportResponse>;
+};
+
+/** Content-free bounded delivery state with no event or sensitive transport fields. */
+type DeliveryHealthSnapshot = Readonly<{
+  /** Stable schema discriminator for JSON consumers. */
+  schemaVersion: typeof DELIVERY_HEALTH_SCHEMA_VERSION;
+  automaticDelivery: boolean;
+  lifecycle: "active" | "shutting_down" | "closed";
+  deliveryState: "idle" | "queued" | "scheduled" | "in_flight" | "retrying" | "paused" | "accepted" | "failed" | "dropped";
+  storage: "memory" | "persistent";
+  queueEvents: number;
+  queueBytes: number;
+  /** Events and compact bytes loaded from persistence when this client started. */
+  hydratedEvents: number;
+  hydratedBytes: number;
+  droppedEvents: number;
+  droppedByReason: Readonly<{
+    event_too_large: number;
+    evicted_for_fatal: number;
+    queue_bytes_overflow: number;
+    queue_overflow: number;
+  }>;
+  lastDropReason: "none" | "event_too_large" | "evicted_for_fatal" | "queue_bytes_overflow" | "queue_overflow";
+  scheduled: boolean;
+  inFlight: boolean;
+  coalesced: boolean;
+  pendingOperations: number;
+  lastOutcome: "idle" | "empty" | "accepted" | "failed";
+  lastStatusClass: "none" | "success" | "client_error" | "server_error" | "network_error" | "transport_error" | "invalid_response" | "other_status";
+  pausedReason: "none" | "authentication" | "rate_limit" | "non_retryable";
+  consecutiveFailures: number;
+  /** Bounded transient retry delay; zero when no automatic retry is scheduled. */
+  retryDelayMs: number;
+  flushes: number;
+  failures: number;
+  attempts: number;
+  batches: number;
+  /** Events durably acknowledged since this client was created. */
+  acceptedEvents: number;
+  /** Bounded monotonic-within-client Unix milliseconds; zero until the transition occurs. */
+  lastAttemptAtUnixMs: number;
+  lastAcceptedAtUnixMs: number;
+  lastDroppedAtUnixMs: number;
+}>;
+
+/** Synchronous queue admission only; this result does not report delivery or retention. */
+type IssueAdmission = Readonly<
+  | { status: "admitted" }
+  | { status: "filtered" }
+  | { status: "dropped"; reason: DroppedEvent["reason"] }
+  | { status: "unavailable" }
+>;
+
+export type {
+  DeliveryHealthSnapshot,
+  DroppedEvent,
+  Event,
+  EventFilter,
+  EventStore,
+  IssueAdmission,
+  StoredEvent,
+  Transport,
+  TransportResponse
+};