@logbrew/sdk 0.1.38 → 0.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",
@@ -45,9 +45,43 @@
     "index.cjs",
     "browser-breadcrumbs.cjs",
     "core.cjs",
+    "capture-support.cjs",
+    "client.cjs",
+    "automatic-delivery.cjs",
+    "batch-sender.cjs",
+    "bounded-number.cjs",
+    "client-options.cjs",
+    "client-report.cjs",
+    "delivery-health.cjs",
+    "event-pipeline.cjs",
+    "event-queue.cjs",
+    "event-store.cjs",
+    "provided-breadcrumbs.cjs",
+    "random-hex.cjs",
+    "retry-delay.cjs",
+    "stored-events.cjs",
+    "utf8.cjs",
+    "console-arguments.cjs",
+    "console-capture.cjs",
+    "error-causes.cjs",
+    "error-details.cjs",
+    "error-issue.cjs",
+    "event-clone.cjs",
+    "event-metadata.cjs",
+    "event-validation.cjs",
+    "exception-chain.cjs",
+    "metric-validation.cjs",
+    "network-milestone.cjs",
+    "null-value.cjs",
+    "pino-destination.cjs",
+    "pino-record.cjs",
+    "product-action.cjs",
+    "recording-transport.cjs",
+    "span-validation.cjs",
     "index.js",
     "index.d.ts",
     "index.d.cts",
+    "types",
     "issue-breadcrumbs.cjs",
     "issue-diagnostics.cjs",
     "issue-evidence.cjs",
@@ -58,6 +92,13 @@
     "issue-text.cjs",
     "log-context.cjs",
     "opentelemetry.cjs",
+    "opentelemetry-bridge.cjs",
+    "opentelemetry-context.cjs",
+    "opentelemetry-exceptions.cjs",
+    "opentelemetry-keys.cjs",
+    "opentelemetry-span.cjs",
+    "opentelemetry-summary.cjs",
+    "opentelemetry-time.cjs",
     "react-native.js",
     "react-native.d.ts",
     "sdk-error.cjs",
@@ -67,12 +108,25 @@
     "transport-error.cjs",
     "validation.cjs",
     "winston.cjs",
+    "winston-info.cjs",
     "release-artifacts-common.js",
     "release-artifacts-build.cjs",
     "release-artifacts.js",
     "release-artifacts-upload.js",
     "release-artifacts-symbolication.js",
+    "release-artifacts-debug-id.js",
+    "release-artifacts-inspect.js",
+    "release-artifacts-issue-event.js",
+    "release-artifacts-manifest.js",
+    "release-artifacts-manifest-artifact.js",
+    "release-artifacts-mappings.js",
+    "release-artifacts-prepare.js",
+    "release-artifacts-source-context.js",
+    "release-artifacts-upload-files.js",
+    "release-artifacts-upload-request.js",
+    "release-artifacts-urls.js",
     "vite-release-artifacts.cjs",
+    "vite-release-artifacts-config.cjs",
     "vite-release-artifacts.js",
     "vite-release-artifacts.d.ts",
     "vite-release-artifacts.d.cts",

package/pino-destination.cjs

@@ -0,0 +1,108 @@
+const { callableOrUndefined, captureSettings, settledFlush } = require("./capture-support.cjs");
+const { LogBrewClient } = require("./client.cjs");
+const { traceFromProvider } = require("./log-context.cjs");
+const { NULL_VALUE } = require("./null-value.cjs");
+const { logAttributesFromPinoRecord, timestampFromPinoRecord } = require("./pino-record.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { isObjectValue, isTruthy } = require("./validation.cjs");
+
+/**
+ * @import { CaptureClient } from "./capture-support.cjs"
+ * @typedef {{
+ *   write: (chunk: unknown) => boolean,
+ *   flush: () => Promise<unknown>,
+ *   end: () => Promise<unknown>
+ * }} PinoDestination
+ */
+
+const NO_PENDING_EVENTS = 0;
+const LINE_BREAK_PATTERN = /\r?\n/u;
+
+class PinoDestinationState {
+  /**
+   * @param {Readonly<Record<string, unknown>>} config
+   * @param {CaptureClient} client
+   */
+  constructor(config, client) {
+    this.client = client;
+    this.settings = captureSettings(config, "flushOnWrite", "pino");
+    this.traceProvider = callableOrUndefined(config["traceProvider"]);
+    this.captured = 0;
+    /** @type {Promise<unknown>} */
+    this.pendingFlush = Promise.resolve(NULL_VALUE);
+  }
+
+  /**
+   * @param {string} line
+   * @returns {void}
+   */
+  writeLine(line) {
+    const { settings } = this;
+    try {
+      /** @type {unknown} */
+      const record = JSON.parse(line);
+      this.captured += 1;
+      this.client.log(
+        `${String(settings.eventIdPrefix)}_${this.captured}`,
+        timestampFromPinoRecord(record, settings.timestamp),
+        logAttributesFromPinoRecord(record, {
+          includeErrorStack: settings.includeErrorStack,
+          logger: settings.logger,
+          metadata: settings.metadata,
+          trace: traceFromProvider(this.traceProvider, settings.onError)
+        })
+      );
+      if (settings.flushOnEvent && isTruthy(settings.transport)) {
+        this.pendingFlush = settledFlush(this.client.flush(settings.transport), settings.onError);
+      }
+    } catch (error) {
+      settings.onError(error);
+    }
+  }
+
+  /**
+   * @returns {void}
+   */
+  flushPending() {
+    const { settings } = this;
+    if (isTruthy(settings.transport) && this.client.pendingEvents() > NO_PENDING_EVENTS) {
+      this.pendingFlush = settledFlush(this.client.flush(settings.transport), settings.onError);
+    }
+  }
+}
+
+/**
+ * @param {unknown} config
+ * @returns {PinoDestination}
+ */
+function createLogBrewPinoDestination(config) {
+  if (!isObjectValue(config)) {
+    throw new SdkError("validation_error", "Pino destination config must be an object");
+  }
+  const { client } = config;
+  if (!(client instanceof LogBrewClient)) {
+    throw new SdkError("validation_error", "Pino destination client must be a LogBrewClient");
+  }
+  const state = new PinoDestinationState(config, client);
+  return {
+    write(chunk) {
+      for (const line of String(chunk).split(LINE_BREAK_PATTERN)) {
+        if (line.trim() !== "") {
+          state.writeLine(line);
+        }
+      }
+      return true;
+    },
+
+    async flush() {
+      state.flushPending();
+      return state.pendingFlush;
+    },
+
+    async end() {
+      return this.flush();
+    }
+  };
+}
+
+module.exports = { createLogBrewPinoDestination };

package/pino-record.cjs

@@ -0,0 +1,237 @@
+const { compactMetadata, isMetadataValue, traceMetadataFromLogContext } = require("./log-context.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { isObjectValue, isRecord, isTruthy, stringOrUndefined } = require("./validation.cjs");
+
+/**
+ * @import { Severity } from "./index.cjs"
+ * @typedef {Readonly<{ includeErrorStack?: unknown, logger?: unknown, metadata?: unknown, trace?: unknown }>} PinoRecordOptions
+ * @typedef {{ message: string, level: Severity, logger?: unknown, metadata: Record<string, unknown> }} PinoLogAttributes
+ */
+
+const CRITICAL_LEVEL = 60;
+const ERROR_LEVEL = 50;
+const WARNING_LEVEL = 40;
+const TRACE_LEVEL = 10;
+const DEBUG_LEVEL = 20;
+const INFO_LEVEL = 30;
+/** @type {ReadonlyMap<number, string>} */
+const PINO_LEVEL_LABELS = new Map([
+  [TRACE_LEVEL, "trace"],
+  [DEBUG_LEVEL, "debug"],
+  [INFO_LEVEL, "info"],
+  [WARNING_LEVEL, "warn"],
+  [ERROR_LEVEL, "error"],
+  [CRITICAL_LEVEL, "fatal"]
+]);
+/** @type {ReadonlyMap<string, Severity>} */
+const PINO_LEVEL_NAMES = new Map([
+  ["trace", "info"],
+  ["debug", "info"],
+  ["warn", "warning"],
+  ["warning", "warning"],
+  ["error", "error"],
+  ["fatal", "critical"],
+  ["critical", "critical"]
+]);
+const PINO_HOST_FIELD = ["host", "name"].join("");
+const PINO_RESERVED_FIELDS = new Set(["level", "time", "timestamp", "msg", "message", "err", "error", "pid", PINO_HOST_FIELD, "v"]);
+const PINO_SENSITIVE_CONTEXT_FIELDS = new Set([
+  "apikey",
+  "authorization",
+  "baggage",
+  "body",
+  "cookie",
+  "credentials",
+  "cwd",
+  "directory",
+  "dirname",
+  "errorstack",
+  "file",
+  "filename",
+  "filepath",
+  "headers",
+  "href",
+  "key",
+  "password",
+  "payload",
+  "proxyauthorization",
+  "query",
+  "querystring",
+  "requestbody",
+  "requestheaders",
+  "requesturl",
+  "responsebody",
+  "responseheaders",
+  "responseurl",
+  "search",
+  "secret",
+  "setcookie",
+  "stack",
+  "token",
+  "traceparent",
+  "tracestate",
+  "uri",
+  "url"
+]);
+const PINO_SENSITIVE_FIELD_SUFFIXES = [
+  "accesskey",
+  "apikey",
+  "authorization",
+  "body",
+  "cookie",
+  "credentials",
+  "headers",
+  "password",
+  "payload",
+  "privatekey",
+  "query",
+  "secret",
+  "stack",
+  "token",
+  "url"
+];
+const FIELD_SEPARATOR_PATTERN = /[^a-z0-9]+/gu;
+
+/**
+ * @param {unknown} level
+ * @returns {Severity}
+ */
+function logbrewLevelFromPinoLevel(level) {
+  if (typeof level === "number" && Number.isFinite(level)) {
+    if (level >= CRITICAL_LEVEL) {
+      return "critical";
+    }
+    if (level >= ERROR_LEVEL) {
+      return "error";
+    }
+    return level >= WARNING_LEVEL ? "warning" : "info";
+  }
+  return PINO_LEVEL_NAMES.get(String(level).toLowerCase()) ?? "info";
+}
+
+/**
+ * @param {unknown} level
+ * @returns {string}
+ */
+function pinoLevelLabel(level) {
+  if (typeof level === "string" && level.trim() !== "") {
+    return level;
+  }
+  if (typeof level !== "number" || !Number.isFinite(level)) {
+    return "info";
+  }
+  return PINO_LEVEL_LABELS.get(level) ?? String(level);
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} record
+ * @returns {string}
+ */
+function pinoMessage(record) {
+  const { msg, message } = record;
+  const error = record["err"] ?? record["error"];
+  const errorMessage = isObjectValue(error) ? error["message"] : undefined;
+  return stringOrUndefined(msg) ?? stringOrUndefined(message) ?? stringOrUndefined(errorMessage) ?? "pino event";
+}
+
+/**
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isSensitivePinoContextField(key) {
+  const normalized = key.toLowerCase().replaceAll(FIELD_SEPARATOR_PATTERN, "");
+  return PINO_SENSITIVE_CONTEXT_FIELDS.has(normalized)
+    || PINO_SENSITIVE_FIELD_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} record
+ * @returns {Record<string, unknown>}
+ */
+function pinoContextMetadata(record) {
+  /** @type {Record<string, unknown>} */
+  const metadata = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (!PINO_RESERVED_FIELDS.has(key) && !isSensitivePinoContextField(key) && isMetadataValue(value)) {
+      metadata[`context.${key}`] = value;
+    }
+  }
+  return metadata;
+}
+
+/**
+ * @param {unknown} error
+ * @param {boolean} includeErrorStack
+ * @returns {Record<string, unknown>}
+ */
+function pinoErrorMetadata(error, includeErrorStack) {
+  if (error instanceof Error) {
+    return {
+      errorName: isTruthy(error.name) ? error.name : "Error",
+      ...(isTruthy(error.message) ? { errorMessage: error.message } : {}),
+      ...(includeErrorStack && isTruthy(error.stack) ? { errorStack: error.stack } : {})
+    };
+  }
+  if (isObjectValue(error)) {
+    const name = stringOrUndefined(error["type"] ?? error["name"]);
+    const message = stringOrUndefined(error["message"]);
+    const stack = stringOrUndefined(error["stack"]);
+    return {
+      ...(name === undefined ? {} : { errorName: name }),
+      ...(message === undefined ? {} : { errorMessage: message }),
+      ...(includeErrorStack && stack !== undefined ? { errorStack: stack } : {})
+    };
+  }
+  return typeof error === "string" && error.trim() !== "" ? { errorMessage: error } : {};
+}
+
+/**
+ * @param {unknown} record
+ * @param {PinoRecordOptions} [options]
+ * @returns {PinoLogAttributes}
+ */
+function logAttributesFromPinoRecord(record, options = {}) {
+  if (!isRecord(record)) {
+    throw new SdkError("validation_error", "Pino record must be an object");
+  }
+  const level = logbrewLevelFromPinoLevel(record["level"]);
+  const metadata = {
+    ...compactMetadata(options.metadata),
+    pinoLevel: pinoLevelLabel(record["level"]),
+    ...pinoContextMetadata(record),
+    ...traceMetadataFromLogContext(options.trace)
+  };
+  const pinoLevelNumber = record["level"];
+  const errorMetadata = pinoErrorMetadata(record["err"] ?? record["error"], options.includeErrorStack === true);
+  return {
+    message: pinoMessage(record),
+
+    level,
+    ...(isTruthy(options.logger) ? { logger: options.logger } : {}),
+
+    metadata: {
+      ...metadata,
+      ...(typeof pinoLevelNumber === "number" && Number.isFinite(pinoLevelNumber) ? { pinoLevelNumber } : {}),
+      ...errorMetadata
+    }
+  };
+}
+
+/**
+ * @param {unknown} record
+ * @param {() => unknown} fallbackTimestamp
+ * @returns {unknown}
+ */
+function timestampFromPinoRecord(record, fallbackTimestamp) {
+  const value = isObjectValue(record) ? record["time"] ?? record["timestamp"] : undefined;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.valueOf()) ? value : parsed.toISOString();
+  }
+  return fallbackTimestamp();
+}
+
+module.exports = { logAttributesFromPinoRecord, timestampFromPinoRecord };

package/product-action.cjs

@@ -0,0 +1,163 @@
+const { ACTION_STATUSES } = require("./event-validation.cjs");
+const { compactMetadata } = require("./log-context.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { hasUnicodeControlCharacter, isRecord, requireAllowedValue, requireNonEmpty, stringOrUndefined } = require("./validation.cjs");
+
+/**
+ * @import { ActionAttributes, MetadataValue, ProductAnalyticsKind } from "./index.cjs"
+ * @typedef {ActionAttributes["status"]} ActionStatus
+ * @typedef {Readonly<{ metadata?: unknown }>} TimelineOptions
+ * @typedef {{ name: string, status: ActionStatus, metadata: Record<string, MetadataValue> }} TimelineAttributes
+ * @typedef {{
+ *   funnel?: unknown,
+ *   metadata?: unknown,
+ *   name: string,
+ *   routeTemplate?: unknown,
+ *   screen?: unknown,
+ *   sessionId?: unknown,
+ *   status: ActionStatus,
+ *   step?: unknown,
+ *   traceId?: unknown
+ * }} ProductActionDetails
+ */
+
+/** @type {1} */
+const PRODUCT_ANALYTICS_SCHEMA_VERSION = 1;
+/** @type {readonly ProductAnalyticsKind[]} */
+const PRODUCT_ANALYTICS_KINDS = Object.freeze(["page_view", "screen_view", "interaction"]);
+const MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH = 256;
+const ROUTE_BASE_URL = "https://logbrew.example";
+const ROUTE_LOCATION_PATTERN = /[?#]/u;
+
+/**
+ * @param {string} trimmed
+ * @returns {string}
+ */
+function routePathname(trimmed) {
+  try {
+    const { pathname } = new URL(trimmed, ROUTE_BASE_URL);
+    return pathname === "" ? "/" : pathname;
+  } catch {
+    const [path] = trimmed.split(ROUTE_LOCATION_PATTERN);
+    return path === undefined || path === "" ? "/" : path;
+  }
+}
+
+/**
+ * @param {unknown} routeTemplate
+ * @returns {string | undefined}
+ */
+function sanitizeRouteTemplate(routeTemplate) {
+  if (routeTemplate === undefined) {
+    return undefined;
+  }
+  if (typeof routeTemplate !== "string") {
+    throw new SdkError("validation_error", "routeTemplate must be a string");
+  }
+  const trimmed = routeTemplate.trim();
+  return trimmed === "" ? "" : routePathname(trimmed);
+}
+
+/**
+ * @param {unknown} surface
+ * @returns {string | undefined}
+ */
+function boundedProductAnalyticsSurface(surface) {
+  if (typeof surface !== "string") {
+    return undefined;
+  }
+  const normalized = surface.trim();
+  if (
+    normalized === ""
+    || [...normalized].length > MAX_PRODUCT_ANALYTICS_SURFACE_LENGTH
+    || hasUnicodeControlCharacter(normalized)
+  ) {
+    return undefined;
+  }
+  return normalized;
+}
+
+/**
+ * @param {ProductAnalyticsKind} kind
+ * @param {unknown} surface
+ * @returns {Record<string, unknown>}
+ */
+function productAnalyticsMetadata(kind, surface) {
+  return {
+    analyticsSchemaVersion: PRODUCT_ANALYTICS_SCHEMA_VERSION,
+
+    analyticsKind: kind,
+    analyticsSurface: boundedProductAnalyticsSurface(surface)
+  };
+}
+
+/**
+ * @param {unknown} action
+ * @returns {ProductActionDetails}
+ */
+function productActionDetails(action) {
+  if (typeof action === "string") {
+    return { name: action, status: "success" };
+  }
+  if (!isRecord(action)) {
+    throw new SdkError("validation_error", "product action must be a string or object");
+  }
+  const name = requireNonEmpty("product action name", action["name"]);
+  const status = requireAllowedValue(
+    "product action status",
+    action["status"] === undefined ? "success" : action["status"],
+    ACTION_STATUSES
+  );
+  return {
+    funnel: action["funnel"],
+    metadata: action["metadata"],
+    name,
+    routeTemplate: action["routeTemplate"],
+    screen: action["screen"],
+    sessionId: action["sessionId"],
+    status,
+    step: action["step"],
+    traceId: action["traceId"]
+  };
+}
+
+/**
+ * @param {unknown} action
+ * @param {TimelineOptions} [options]
+ * @returns {TimelineAttributes}
+ */
+function createProductActionAttributes(action, options = {}) {
+  const details = productActionDetails(action);
+  const routeTemplate = sanitizeRouteTemplate(details.routeTemplate);
+  const surface = routeTemplate === undefined || routeTemplate === "" ? details.screen : routeTemplate;
+  return {
+    name: details.name,
+
+    status: details.status,
+
+    metadata: compactMetadata({
+      source: "product.action",
+      ...compactMetadata(options.metadata),
+      ...compactMetadata(details.metadata),
+      routeTemplate,
+
+      sessionId: stringOrUndefined(details.sessionId),
+
+      traceId: stringOrUndefined(details.traceId),
+
+      screen: stringOrUndefined(details.screen),
+
+      funnel: stringOrUndefined(details.funnel),
+
+      step: stringOrUndefined(details.step),
+      ...productAnalyticsMetadata("interaction", surface)
+    })
+  };
+}
+
+module.exports = {
+  PRODUCT_ANALYTICS_KINDS,
+  PRODUCT_ANALYTICS_SCHEMA_VERSION,
+  createProductActionAttributes,
+  sanitizeRouteTemplate
+};