@logbrew/sdk 0.1.38 → 0.1.39

package/event-store.cjs

@@ -0,0 +1,237 @@
+const { isObjectLike } = require("./error-details.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const {
+  invalidStoredRecord,
+  normalizeStoredRecord,
+  requireSynchronousStoreResult,
+  restoreStoredEvent
+} = require("./stored-events.cjs");
+const { isRecord } = require("./validation.cjs");
+
+/**
+ * @import { SdkEvent } from "./event-validation.cjs"
+ * @import { StoredRecord } from "./stored-events.cjs"
+ * @import { Callable, DeepReadonly } from "./validation.cjs"
+ * @typedef {Readonly<{
+ *   loadClientReport: () => unknown,
+ *   saveClientReport: (state: unknown) => unknown
+ * }>} ClientReportStore
+ * @typedef {Readonly<{
+ *   load: () => unknown,
+ *   append: (record: Readonly<StoredRecord>) => unknown,
+ *   acknowledge: (count: number) => unknown,
+ *   purge: () => unknown,
+ *   close: () => unknown,
+ *   remove?: (indexes: readonly number[]) => unknown,
+ *   loadClientReport?: () => unknown,
+ *   saveClientReport?: (state: unknown) => unknown
+ * }>} EventStore
+ * @typedef {Readonly<{
+ *   acknowledge: (count: unknown) => unknown,
+ *   append: (record: unknown) => unknown,
+ *   byteCount: () => unknown,
+ *   close: () => unknown,
+ *   eventBytesAt: (index: number) => unknown,
+ *   events: () => unknown,
+ *   length: () => unknown,
+ *   serializedAt: (index: number) => unknown,
+ *   remove?: (indexes: readonly number[]) => unknown,
+ *   loadClientReport?: () => unknown,
+ *   saveClientReport?: (state: unknown) => unknown
+ * }>} EventQueueBackend
+ * @typedef {Readonly<{
+ *   batchPrefixBytes: number,
+ *   batchSuffixBytes: number,
+ *   maxBatchBytes: number,
+ *   maxQueueBytes: number,
+ *   maxQueueSize: number
+ * }>} StoreLimits
+ */
+
+const EVENT_STORE_METHODS = Object.freeze(["load", "append", "acknowledge", "purge", "close"]);
+const EVENT_QUEUE_METHODS = Object.freeze(["acknowledge", "append", "byteCount", "close", "eventBytesAt", "events", "length", "serializedAt"]);
+
+/**
+ * @param {unknown} store
+ * @returns {store is ClientReportStore}
+ */
+function isClientReportStore(store) {
+  return isObjectLike(store)
+    && typeof Reflect.get(store, "loadClientReport") === "function"
+    && typeof Reflect.get(store, "saveClientReport") === "function";
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} value
+ * @param {readonly string[]} methods
+ * @returns {string | undefined}
+ */
+function missingMethod(value, methods) {
+  return methods.find((method) => typeof value[method] !== "function");
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} value
+ * @returns {value is EventStore}
+ */
+function isEventStore(value) {
+  return missingMethod(value, EVENT_STORE_METHODS) === undefined;
+}
+
+/**
+ * @param {unknown} eventStore
+ * @returns {EventStore | undefined}
+ */
+function validateEventStore(eventStore) {
+  if (eventStore === undefined) {
+    return undefined;
+  }
+  if (!isRecord(eventStore)) {
+    throw new SdkError("validation_error", "eventStore must be an object");
+  }
+  const missing = missingMethod(eventStore, EVENT_STORE_METHODS);
+  if (missing !== undefined) {
+    throw new SdkError("validation_error", `eventStore.${missing} must be a function`);
+  }
+  return isEventStore(eventStore) ? eventStore : undefined;
+}
+
+/**
+ * @param {unknown} queue
+ * @returns {queue is EventQueueBackend}
+ */
+function isEventQueueBackend(queue) {
+  return isRecord(queue) && missingMethod(queue, EVENT_QUEUE_METHODS) === undefined;
+}
+
+/**
+ * @param {EventQueueBackend} queue
+ * @returns {unknown[]}
+ */
+function loadQueueRecords(queue) {
+  const events = queue.events();
+  const count = queue.length();
+  if (!Array.isArray(events) || events.length !== count) {
+    throw invalidStoredRecord();
+  }
+  /** @type {readonly unknown[]} */
+  const loaded = events;
+  return loaded.map((event, index) => ({
+    event,
+    eventBytes: queue.eventBytesAt(index),
+    serializedEvent: queue.serializedAt(index)
+  }));
+}
+
+/**
+ * @param {EventQueueBackend} queue
+ * @returns {Partial<EventStore>}
+ */
+function optionalQueueMethods(queue) {
+  const { remove } = queue;
+  return {
+    ...(typeof remove === "function" ? { remove: (indexes) => queue.remove?.(indexes) } : {}),
+    ...(isClientReportStore(queue)
+      ? { loadClientReport: () => queue.loadClientReport(), saveClientReport: (state) => queue.saveClientReport(state) }
+      : {})
+  };
+}
+
+/**
+ * @param {Callable} eventQueueFactory
+ * @param {StoreLimits} limits
+ * @returns {EventStore}
+ */
+function createEventStoreFromQueueFactory(eventQueueFactory, limits) {
+  /** @type {unknown} */
+  const queue = Reflect.apply(eventQueueFactory, undefined, [{ ...limits, restoreEvent: restoreStoredEvent }]);
+  if (!isEventQueueBackend(queue)) {
+    throw new SdkError("validation_error", "event queue factory returned an invalid queue");
+  }
+  return {
+    load: () => loadQueueRecords(queue),
+
+    append: (record) => queue.append({
+      event: record.event,
+
+      byteCount: record.eventBytes,
+
+      serialized: record.serializedEvent
+    }),
+
+    acknowledge: (count) => queue.acknowledge(count),
+
+    purge: () => queue.acknowledge(queue.length()),
+
+    close: () => queue.close(),
+    ...optionalQueueMethods(queue)
+  };
+}
+
+class RecoveredEvents {
+  /**
+   * @param {StoreLimits} limits
+   */
+  constructor(limits) {
+    this.limits = limits;
+    /** @type {DeepReadonly<SdkEvent>[]} */
+    this.events = [];
+    this.queuedEventBytes = 0;
+    /** @type {number[]} */
+    this.serializedEventBytes = [];
+    /** @type {string[]} */
+    this.serializedEvents = [];
+  }
+
+  /**
+   * @param {Readonly<StoredRecord>} normalized
+   * @returns {void}
+   */
+  add(normalized) {
+    const { limits } = this;
+    if (limits.batchPrefixBytes + normalized.eventBytes + limits.batchSuffixBytes > limits.maxBatchBytes) {
+      throw new SdkError("persistence_error", "recovered event exceeds maxBatchBytes");
+    }
+    this.queuedEventBytes += normalized.eventBytes;
+    if (this.queuedEventBytes > limits.maxQueueBytes) {
+      throw new SdkError("persistence_error", "recovered event bytes exceed maxQueueBytes");
+    }
+    this.events.push(normalized.event);
+    this.serializedEvents.push(normalized.serializedEvent);
+    this.serializedEventBytes.push(normalized.eventBytes);
+  }
+}
+
+/**
+ * @param {EventStore} eventStore
+ * @param {number} maxQueueSize
+ * @returns {readonly unknown[]}
+ */
+function storedRecords(eventStore, maxQueueSize) {
+  const records = requireSynchronousStoreResult("load", eventStore.load());
+  if (!Array.isArray(records)) {
+    throw invalidStoredRecord();
+  }
+  if (records.length > maxQueueSize) {
+    throw new SdkError("persistence_error", "recovered event count exceeds maxQueueSize");
+  }
+  /** @type {readonly unknown[]} */
+  const loaded = records;
+  return loaded;
+}
+
+/**
+ * @param {EventStore | undefined} eventStore
+ * @param {StoreLimits} limits
+ * @returns {RecoveredEvents}
+ */
+function loadStoredEvents(eventStore, limits) {
+  const recovered = new RecoveredEvents(limits);
+  const records = eventStore === undefined ? [] : storedRecords(eventStore, limits.maxQueueSize);
+  for (const record of records) {
+    recovered.add(normalizeStoredRecord(record));
+  }
+  return recovered;
+}
+
+module.exports = { createEventStoreFromQueueFactory, isClientReportStore, loadStoredEvents, validateEventStore };

package/event-validation.cjs

@@ -0,0 +1,159 @@
+const { withMetadata } = require("./event-metadata.cjs");
+const { validateIssueDiagnostics } = require("./issue-diagnostics.cjs");
+const { validateIssueStackFrames, validateNativeStackFrames } = require("./issue-stack.cjs");
+const { validateMetric } = require("./metric-validation.cjs");
+const { validateSpan } = require("./span-validation.cjs");
+const { optionalEntry, requireAllowedValue, requireNonEmpty } = require("./validation.cjs");
+
+/**
+ * @import {
+ *   ActionAttributes,
+ *   IssueStackFrame,
+ *   NativeStackFrame,
+ *   Severity,
+ *   SeverityInput,
+ *   SpanEventSummary,
+ *   SpanLinkSummary,
+ *   TelemetryContext
+ * } from "./index.cjs"
+ * @import { IssueDiagnostics } from "./issue-diagnostics.cjs"
+ * @typedef {"release" | "environment" | "issue" | "log" | "span" | "action" | "metric"} EventType
+ * @typedef {IssueDiagnostics & {
+ *   [key: string]: unknown,
+ *   context?: TelemetryContext,
+ *   events?: SpanEventSummary[],
+ *   links?: SpanLinkSummary[],
+ *   metadata?: Record<string, unknown>,
+ *   nativeStackFrames?: NativeStackFrame[],
+ *   stackFrames?: IssueStackFrame[]
+ * }} EventAttributes
+ * @typedef {{ type: EventType, id: string, timestamp: string, attributes: EventAttributes }} SdkEvent
+ * @typedef {(attributes: Readonly<Record<string, unknown>>) => EventAttributes} EventValidator
+ */
+
+/** @type {ReadonlyMap<SeverityInput, Severity>} */
+const SEVERITY_ALIASES = new Map([
+  ["trace", "info"],
+  ["debug", "info"],
+  ["info", "info"],
+  ["warn", "warning"],
+  ["warning", "warning"],
+  ["error", "error"],
+  ["fatal", "critical"],
+  ["critical", "critical"]
+]);
+const SEVERITY_VALUES = new Set(SEVERITY_ALIASES.keys());
+/** @type {ReadonlySet<ActionAttributes["status"]>} */
+const ACTION_STATUSES = new Set(["queued", "running", "success", "failure"]);
+
+/**
+ * @param {string} label
+ * @param {unknown} value
+ * @returns {Severity}
+ */
+function normalizeSeverity(label, value) {
+  const severity = requireAllowedValue(label, value, SEVERITY_VALUES);
+  return SEVERITY_ALIASES.get(severity) ?? "info";
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateRelease(attributes) {
+  const version = requireNonEmpty("release version", attributes["version"]);
+  const commit = attributes["commit"] === undefined ? undefined : requireNonEmpty("release commit", attributes["commit"]);
+  return withMetadata({
+    version,
+    ...optionalEntry("commit", commit),
+    ...optionalEntry("notes", attributes["notes"])
+  }, attributes["metadata"], attributes["context"]);
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateEnvironment(attributes) {
+  const name = requireNonEmpty("environment name", attributes["name"]);
+  return withMetadata({
+    name,
+    ...optionalEntry("region", attributes["region"])
+  }, attributes["metadata"], attributes["context"]);
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateIssue(attributes) {
+  const title = requireNonEmpty("issue title", attributes["title"]);
+  const level = normalizeSeverity("issue level", attributes["level"]);
+  const stackFrames = validateIssueStackFrames(attributes["stackFrames"]);
+  const nativeStackFrames = validateNativeStackFrames(attributes["nativeStackFrames"]);
+  return withMetadata({
+    title,
+
+    level,
+    ...optionalEntry("message", attributes["message"]),
+    ...optionalEntry("stackFrames", stackFrames),
+    ...optionalEntry("nativeStackFrames", nativeStackFrames),
+    ...validateIssueDiagnostics(attributes)
+  }, attributes["metadata"], attributes["context"]);
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateLog(attributes) {
+  const message = requireNonEmpty("log message", attributes["message"]);
+  const level = normalizeSeverity("log level", attributes["level"]);
+  return withMetadata({
+    message,
+
+    level,
+    ...optionalEntry("logger", attributes["logger"])
+  }, attributes["metadata"], attributes["context"]);
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateAction(attributes) {
+  const name = requireNonEmpty("action name", attributes["name"]);
+  const status = requireAllowedValue("action status", attributes["status"], ACTION_STATUSES);
+  return withMetadata({ name, status }, attributes["metadata"], attributes["context"]);
+}
+
+/** @type {ReadonlyMap<string, EventValidator>} */
+const EVENT_VALIDATORS = new Map([
+  ["release", validateRelease],
+  ["environment", validateEnvironment],
+  ["issue", validateIssue],
+  ["log", validateLog],
+  ["span", validateSpan],
+  ["action", validateAction],
+  ["metric", validateMetric]
+]);
+
+/**
+ * @param {unknown} type
+ * @returns {type is EventType}
+ */
+function isEventType(type) {
+  return typeof type === "string" && EVENT_VALIDATORS.has(type);
+}
+
+module.exports = {
+  ACTION_STATUSES,
+  EVENT_VALIDATORS,
+  isEventType,
+  normalizeSeverity,
+  validateAction,
+  validateEnvironment,
+  validateIssue,
+  validateLog,
+  validateRelease
+};

package/examples/agent-timeline.cjs

@@ -1,87 +1,98 @@
-let sdk;
-try {
-  sdk = require("@logbrew/sdk");
-} catch (error) {
-  if (error && error.code === "MODULE_NOT_FOUND") {
-    sdk = require("../index.cjs");
-  } else {
-    throw error;
-  }
-}
-
 const {
+  LogBrewClient,
+  RecordingTransport,
   createNetworkMilestoneAttributes,
   createProductActionAttributes,
-  createTraceparentHeaders,
-  LogBrewClient,
-  RecordingTransport
-} = sdk;
+  createTraceparentHeaders
+} = require("../index.cjs");
+const { inspect } = require("node:util");
+const process = require("node:process");
 
 const traceId = "4bf92f3577b34da6a3ce929d0e0e4736";
 const spanId = "b7ad6b7169203331";
 const sessionId = "sess_checkout_001";
 const timestamp = "2026-06-02T10:00:00Z";
+const RETAINED_EVENTS = 2;
 
 const client = LogBrewClient.create({
   apiKey: "LOGBREW_API_KEY",
-  sdkName: "checkout-agent-timeline",
-  sdkVersion: "1.0.0",
   eventFilter(event) {
     return !(event.type === "log" && event.attributes.level === "info");
-  }
+  },
+  sdkName: "checkout-agent-timeline",
+  sdkVersion: "1.0.0"
 });
 
 client.action("evt_checkout_started", timestamp, createProductActionAttributes({
+  funnel: "checkout",
+  metadata: {
+    service: "checkout",
+
+    plan: "pro"
+  },
   name: "checkout.started",
-  status: "success",
-  sessionId,
-  traceId,
   routeTemplate: "/checkout/:step?coupon=private#payment",
-  funnel: "checkout",
+  sessionId,
+  status: "success",
   step: "start",
-  metadata: { service: "checkout", plan: "pro" }
+  traceId
 }));
 
 client.action("evt_payment_api", "2026-06-02T10:00:01Z", createNetworkMilestoneAttributes({
-  routeTemplate: "https://api.example.invalid/payments/123?card=private#retry",
-  method: "POST",
-  statusCode: 503,
   durationMs: 241.5,
+  metadata: {
+    service: "payments",
+
+    retryable: true
+  },
+  method: "POST",
+  routeTemplate: "https://api.example.invalid/payments/123?card=private#retry",
   sessionId,
-  traceId,
-  metadata: { service: "payments", retryable: true }
+  statusCode: 503,
+  traceId
 }));
 
 client.log("evt_debug_noise", "2026-06-02T10:00:02Z", {
-  message: "debug heartbeat",
   level: "info",
-  logger: "checkout"
+  logger: "checkout",
+  message: "debug heartbeat"
 });
 
 const headers = createTraceparentHeaders({
-  traceId,
   spanId,
-  traceFlags: "01"
+  traceFlags: "01",
+  traceId
 });
 
 const preview = client.previewJson();
 if (preview.includes("card=private") || preview.includes("coupon=private") || preview.includes("#payment")) {
   throw new Error("agent timeline leaked query or hash metadata");
 }
-if (client.pendingEvents() !== 2) {
-  throw new Error(`expected two retained timeline events, got ${client.pendingEvents()}`);
+if (client.pendingEvents() !== RETAINED_EVENTS) {
+  throw new Error(`expected two retained timeline events, got ${String(client.pendingEvents())}`);
 }
 
-console.log(preview);
+process.stdout.write(`${preview}\n`);
 
-client.shutdown(RecordingTransport.alwaysAccept()).then((response) => {
-  console.error(JSON.stringify({
-    ok: true,
-    events: 2,
-    traceparent: headers.traceparent,
-    status: response.statusCode
-  }));
-}).catch((error) => {
-  console.error(error);
-  process.exit(1);
-});
+/**
+ * @returns {Promise<void>}
+ */
+async function deliver() {
+  try {
+    const response = await client.shutdown(RecordingTransport.alwaysAccept());
+    process.stderr.write(`${JSON.stringify({
+      ok: true,
+
+      events: RETAINED_EVENTS,
+
+      traceparent: headers.traceparent,
+
+      status: response.statusCode
+    })}\n`);
+  } catch (error) {
+    process.stderr.write(`${inspect(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+void deliver();

package/examples/agent-timeline.mjs

@@ -1,79 +1,85 @@
-const sdk = await import("@logbrew/sdk").catch(async (error) => {
-  if (error && error.code === "ERR_MODULE_NOT_FOUND") {
-    return import("../index.js");
-  }
-  throw error;
-});
-
-const {
+import {
+  LogBrewClient,
+  RecordingTransport,
   createNetworkMilestoneAttributes,
   createProductActionAttributes,
-  createTraceparentHeaders,
-  LogBrewClient,
-  RecordingTransport
-} = sdk;
+  createTraceparentHeaders
+} from "../index.js";
+import process from "node:process";
 
 const traceId = "4bf92f3577b34da6a3ce929d0e0e4736";
 const spanId = "b7ad6b7169203331";
 const sessionId = "sess_checkout_001";
 const timestamp = "2026-06-02T10:00:00Z";
+const RETAINED_EVENTS = 2;
 
 const client = LogBrewClient.create({
   apiKey: "LOGBREW_API_KEY",
-  sdkName: "checkout-agent-timeline",
-  sdkVersion: "1.0.0",
   eventFilter(event) {
     return !(event.type === "log" && event.attributes.level === "info");
-  }
+  },
+  sdkName: "checkout-agent-timeline",
+  sdkVersion: "1.0.0"
 });
 
 client.action("evt_checkout_started", timestamp, createProductActionAttributes({
+  funnel: "checkout",
+  metadata: {
+    service: "checkout",
+
+    plan: "pro"
+  },
   name: "checkout.started",
-  status: "success",
-  sessionId,
-  traceId,
   routeTemplate: "/checkout/:step?coupon=private#payment",
-  funnel: "checkout",
+  sessionId,
+  status: "success",
   step: "start",
-  metadata: { service: "checkout", plan: "pro" }
+  traceId
 }));
 
 client.action("evt_payment_api", "2026-06-02T10:00:01Z", createNetworkMilestoneAttributes({
-  routeTemplate: "https://api.example.invalid/payments/123?card=private#retry",
-  method: "POST",
-  statusCode: 503,
   durationMs: 241.5,
+  metadata: {
+    service: "payments",
+
+    retryable: true
+  },
+  method: "POST",
+  routeTemplate: "https://api.example.invalid/payments/123?card=private#retry",
   sessionId,
-  traceId,
-  metadata: { service: "payments", retryable: true }
+  statusCode: 503,
+  traceId
 }));
 
 client.log("evt_debug_noise", "2026-06-02T10:00:02Z", {
-  message: "debug heartbeat",
   level: "info",
-  logger: "checkout"
+  logger: "checkout",
+  message: "debug heartbeat"
 });
 
 const headers = createTraceparentHeaders({
-  traceId,
   spanId,
-  traceFlags: "01"
+  traceFlags: "01",
+  traceId
 });
 
 const preview = client.previewJson();
 if (preview.includes("card=private") || preview.includes("coupon=private") || preview.includes("#payment")) {
   throw new Error("agent timeline leaked query or hash metadata");
 }
-if (client.pendingEvents() !== 2) {
-  throw new Error(`expected two retained timeline events, got ${client.pendingEvents()}`);
+if (client.pendingEvents() !== RETAINED_EVENTS) {
+  throw new Error(`expected two retained timeline events, got ${String(client.pendingEvents())}`);
 }
 
-console.log(preview);
+process.stdout.write(`${preview}\n`);
 
 const response = await client.shutdown(RecordingTransport.alwaysAccept());
-console.error(JSON.stringify({
+process.stderr.write(`${JSON.stringify({
   ok: true,
-  events: 2,
+
+  events: RETAINED_EVENTS,
+
   traceparent: headers.traceparent,
+
   status: response.statusCode
-}));
+})}\n`);