@logbrew/sdk 0.1.38 → 0.1.39

package/types/product.d.ts

@@ -0,0 +1,128 @@
+import type { ActionAttributes, Metadata } from "./telemetry.js";
+
+/** Stable product-analytics event categories carried in reserved action metadata. */
+type ProductAnalyticsKind = "page_view" | "screen_view" | "interaction";
+
+/** App-owned product step input for agent-readable action timelines. */
+type ProductActionInput = string | {
+  name: string;
+  status?: ActionAttributes["status"];
+  sessionId?: string;
+  traceId?: string;
+  routeTemplate?: string;
+  screen?: string;
+  funnel?: string;
+  step?: string;
+  metadata?: Metadata;
+};
+
+/** App-owned API milestone input for agent-readable network timelines. */
+type NetworkMilestoneInput = string | {
+  name?: string;
+  routeTemplate: string;
+  method?: string;
+  status?: ActionAttributes["status"];
+  statusCode?: number;
+  durationMs?: number;
+  sessionId?: string;
+  traceId?: string;
+  metadata?: Metadata;
+};
+
+/** Shared timeline helper options for primitive app metadata. */
+type TimelineAttributesOptions = {
+  metadata?: Metadata;
+};
+
+/** Support-ticket sources accepted by explicit draft helpers. */
+type SupportTicketSource = "cli" | "sdk" | "website" | "docs" | "mobile";
+
+/** Support-ticket categories accepted by explicit draft helpers. */
+type SupportTicketCategory =
+  | "sdk_install_failure"
+  | "ingest_failure"
+  | "auth_failure"
+  | "project_setup"
+  | "dashboard_issue"
+  | "docs_confusion"
+  | "cli_issue"
+  | "mobile_issue"
+  | "billing_question"
+  | "other";
+
+/** JSON-like diagnostics input sanitized before a support-ticket draft is returned. */
+type SupportDiagnosticsValue =
+  | string
+  | number
+  | boolean
+  | null
+  | SupportDiagnosticsValue[]
+  | { [key: string]: SupportDiagnosticsValue };
+
+/** Explicit local-only support-ticket draft input. This does not open a ticket. */
+type SupportTicketDraftInput = {
+  source: SupportTicketSource;
+  category: SupportTicketCategory;
+  title: string;
+  description: string;
+  projectId?: string;
+  environment?: string;
+  runtime?: string;
+  framework?: string;
+  sdkPackage?: string;
+  sdkVersion?: string;
+  release?: string;
+  traceId?: string;
+  eventId?: string;
+  diagnostics?: Record<string, unknown>;
+};
+
+/** Support-ticket create body built locally. It sends nothing. */
+type SupportTicketDraft = {
+  source: SupportTicketSource;
+  category: SupportTicketCategory;
+  title: string;
+  description: string;
+  project_id?: string;
+  environment?: string;
+  runtime?: string;
+  framework?: string;
+  sdk_package?: string;
+  sdk_version?: string;
+  release?: string;
+  trace_id?: string;
+  event_id?: string;
+  diagnostics?: Record<string, SupportDiagnosticsValue>;
+};
+
+/** Create safe action attributes for an app-owned product step without automatic UI capture. */
+declare function createProductActionAttributes(
+  action: ProductActionInput,
+  options?: TimelineAttributesOptions
+): ActionAttributes;
+
+/** Create safe action attributes for an app-owned network milestone without HTTP client patching. */
+declare function createNetworkMilestoneAttributes(
+  request: NetworkMilestoneInput,
+  options?: TimelineAttributesOptions
+): ActionAttributes;
+
+/** Build a local-only, token-free support-ticket create payload draft without calling backend routes. */
+declare function createSupportTicketDraft(input: SupportTicketDraftInput): SupportTicketDraft;
+
+export type {
+  NetworkMilestoneInput,
+  ProductActionInput,
+  ProductAnalyticsKind,
+  SupportDiagnosticsValue,
+  SupportTicketCategory,
+  SupportTicketDraft,
+  SupportTicketDraftInput,
+  SupportTicketSource,
+  TimelineAttributesOptions
+};
+export {
+  createNetworkMilestoneAttributes,
+  createProductActionAttributes,
+  createSupportTicketDraft
+};

package/types/recording-transport.d.ts

@@ -0,0 +1,15 @@
+import type { TransportResponse } from "./delivery.js";
+
+/** Scripted transport for previewing, accepting, or failing queued event flushes. */
+declare class RecordingTransport {
+  public constructor(scriptedResponses?: ({ statusCode: number; retryAfterMs?: number; errorCode?: string } | Error)[]);
+  /** Every request body sent through this transport instance. */
+  public sentBodies: string[];
+  /** Create a transport that accepts queued flushes with a 202 response. */
+  public static alwaysAccept(): RecordingTransport;
+  /** Return the most recent request body sent through this transport. */
+  public lastBody(): string | null;
+  public send(apiKey: string, body: string): Promise<TransportResponse>;
+}
+
+export { RecordingTransport };

package/types/sdk-error.d.ts

@@ -0,0 +1,9 @@
+/** Stable public SDK error with parseable code and message fields. */
+declare class SdkError extends Error {
+  public code: string;
+  public retryAfterMs?: number;
+  public retryable?: boolean;
+  public constructor(code: string, message: string, details?: { retryAfterMs?: number; retryable?: boolean });
+}
+
+export { SdkError };

package/types/telemetry.d.ts

@@ -0,0 +1,171 @@
+declare const TELEMETRY_CONTEXT_SCHEMA_VERSION = 1;
+
+/** Metadata values that can be attached to public LogBrew event payloads. */
+type MetadataValue = string | number | boolean | null;
+
+/** Structured metadata map shared by public LogBrew event attribute types. */
+type Metadata = Record<string, MetadataValue>;
+
+/** Bounded service, runtime, or framework identity shared by telemetry signals. */
+type TelemetryNamedVersion = {
+  name: string;
+  version?: string;
+};
+
+/** Privacy-bounded resource identity shared by telemetry signals. */
+type TelemetryResource = {
+  service?: TelemetryNamedVersion;
+  deployment?: { environment?: string; release?: string };
+  runtime?: TelemetryNamedVersion;
+  framework?: TelemetryNamedVersion;
+  operatingSystem?: TelemetryNamedVersion & { build?: string };
+  device?: { family?: string; model?: string; architecture?: string };
+  application?: { name?: string; version?: string; build?: string };
+};
+
+/** W3C-compatible correlation identity shared by non-span telemetry. */
+type TelemetryTraceContext = {
+  traceId: string;
+  spanId?: string;
+  parentSpanId?: string;
+  sampled?: boolean;
+};
+
+/** Opaque application session identity. */
+type TelemetrySessionContext = {
+  id: string;
+  previousId?: string;
+};
+
+/** Explicit app-owned subject identity; do not send names, email addresses, or IP addresses. */
+type TelemetrySubjectContext = {
+  id: string;
+  kind: "anonymous" | "user";
+};
+
+/** Versioned shared context available on every LogBrew event type. */
+type TelemetryContext = {
+  schemaVersion: typeof TELEMETRY_CONTEXT_SCHEMA_VERSION;
+  resource?: TelemetryResource;
+  trace?: TelemetryTraceContext;
+  session?: TelemetrySessionContext;
+  subject?: TelemetrySubjectContext;
+  /** Up to 32 low-cardinality string dimensions with safe machine keys. */
+  tags?: Record<string, string>;
+};
+
+/** Canonical user-facing severity categories accepted by LogBrew. */
+type Severity = "info" | "warning" | "error" | "critical";
+
+/** Runtime-level aliases accepted for compatibility and normalized before send. */
+type SeverityAlias = "trace" | "debug" | "warn" | "fatal";
+
+/** Public severity input accepted by issue and log attributes. */
+type SeverityInput = Severity | SeverityAlias;
+
+/** Public release event attributes. */
+type ReleaseAttributes = {
+  version: string;
+  commit?: string;
+  notes?: string;
+  metadata?: Metadata;
+  context?: TelemetryContext;
+};
+
+/** Public environment event attributes. */
+type EnvironmentAttributes = {
+  name: string;
+  region?: string;
+  metadata?: Metadata;
+  context?: TelemetryContext;
+};
+
+/** Public log event attributes. */
+type LogAttributes = {
+  message: string;
+  level: SeverityInput;
+  logger?: string;
+  metadata?: Metadata;
+  context?: TelemetryContext;
+};
+
+/** Privacy-bounded milestone recorded inside a span. */
+type SpanEventSummary = {
+  name: string;
+  timestamp?: string;
+  metadata?: Metadata;
+};
+
+/** Privacy-bounded reference from this span to another trace/span. */
+type SpanLinkSummary = {
+  traceId: string;
+  spanId: string;
+  sampled?: boolean;
+  metadata?: Metadata;
+};
+
+/** Public span event attributes. */
+type SpanAttributes = {
+  name: string;
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  status: "ok" | "error";
+  durationMs?: number;
+  events?: SpanEventSummary[];
+  links?: SpanLinkSummary[];
+  metadata?: Metadata;
+  context?: TelemetryContext;
+};
+
+/** Public action event attributes. */
+type ActionAttributes = {
+  name: string;
+  status: "queued" | "running" | "success" | "failure";
+  metadata?: Metadata;
+  context?: TelemetryContext;
+};
+
+/** Public metric event attributes. Use low-cardinality metadata only. */
+type MetricAttributes = {
+  name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
+  kind: "counter" | "histogram";
+  value: number;
+  unit: string;
+  temporality: "delta" | "cumulative";
+  metadata?: Metadata;
+  context?: TelemetryContext;
+} | {
+  name: string;
+  /** Optional stable, single-line meaning; 1 to 1,024 Unicode characters. */
+  description?: string;
+  kind: "gauge";
+  value: number;
+  unit: string;
+  temporality: "instant";
+  metadata?: Metadata;
+};
+
+export type {
+  ActionAttributes,
+  EnvironmentAttributes,
+  LogAttributes,
+  Metadata,
+  MetadataValue,
+  MetricAttributes,
+  ReleaseAttributes,
+  Severity,
+  SeverityAlias,
+  SeverityInput,
+  SpanAttributes,
+  SpanEventSummary,
+  SpanLinkSummary,
+  TelemetryContext,
+  TelemetryNamedVersion,
+  TelemetryResource,
+  TelemetrySessionContext,
+  TelemetrySubjectContext,
+  TelemetryTraceContext
+};

package/types/trace-context.d.ts

@@ -0,0 +1,110 @@
+import type { Metadata, SpanAttributes, SpanEventSummary, SpanLinkSummary } from "./telemetry.js";
+
+/** Parsed W3C trace context from a traceparent value. */
+type TraceparentContext = {
+  version: string;
+  traceId: string;
+  parentSpanId: string;
+  traceFlags: string;
+  sampled: boolean;
+};
+
+/** Minimal active trace shape accepted by logger adapters for correlation metadata. */
+type LogCorrelationTraceContext = {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  sampled?: boolean;
+};
+
+/** Inputs for creating a W3C traceparent value from known trace/span ids. */
+type TraceparentInput = {
+  traceId: string;
+  spanId: string;
+  traceFlags?: string;
+};
+
+/** Privacy-bounded W3C tracestate entry for explicit propagation. */
+type TracestateEntry = {
+  key: string;
+  value: string;
+};
+
+/** W3C baggage entry for explicit propagation. */
+type BaggageEntry = {
+  key: string;
+  value: string;
+  properties?: string[];
+};
+
+/** Inputs for creating an explicit W3C trace context header carrier. */
+type TraceContextInput = TraceparentInput & {
+  tracestate?: string | TracestateEntry[];
+  baggage?: string | BaggageEntry[];
+};
+
+/** Span fields supplied when deriving LogBrew span attributes from traceparent. */
+type TraceparentSpanInput = {
+  name: string;
+  spanId: string;
+  status: "ok" | "error";
+  durationMs?: number;
+  links?: SpanLinkSummary[];
+  metadata?: Metadata;
+  events?: SpanEventSummary[];
+};
+
+/** Parse a W3C traceparent value into normalized trace/span context. */
+declare function parseTraceparent(traceparent: string): TraceparentContext;
+
+/** Create a W3C traceparent value from explicit trace/span ids. */
+declare function createTraceparent(input: TraceparentInput): string;
+
+/** Create an explicit outbound header carrier containing only traceparent. */
+declare function createTraceparentHeaders(input: TraceparentInput): { traceparent: string };
+
+/** Parse a W3C tracestate header into normalized entries. */
+declare function parseTracestate(tracestate: string): TracestateEntry[];
+
+/** Create a normalized W3C tracestate header from explicit entries. */
+declare function createTracestate(entries: TracestateEntry[]): string;
+
+/** Parse a W3C baggage header into decoded entries. */
+declare function parseBaggage(baggage: string): BaggageEntry[];
+
+/** Create a W3C baggage header from explicit entries. */
+declare function createBaggage(entries: BaggageEntry[]): string;
+
+/** Create an explicit outbound carrier for traceparent plus optional tracestate and baggage. */
+declare function createTraceContextHeaders(input: TraceContextInput): {
+  traceparent: string;
+  tracestate?: string;
+  baggage?: string;
+};
+
+/** Build LogBrew span attributes that continue an incoming W3C traceparent value. */
+declare function spanAttributesFromTraceparent(
+  traceparent: string,
+  attributes: TraceparentSpanInput
+): SpanAttributes;
+
+export type {
+  BaggageEntry,
+  LogCorrelationTraceContext,
+  TraceContextInput,
+  TraceparentContext,
+  TraceparentInput,
+  TraceparentSpanInput,
+  TracestateEntry
+};
+export {
+  createBaggage,
+  createTraceContextHeaders,
+  createTraceparent,
+  createTraceparentHeaders,
+  createTracestate,
+  parseBaggage,
+  parseTraceparent,
+  parseTracestate,
+  spanAttributesFromTraceparent
+};

package/types/transport-error.d.ts

@@ -0,0 +1,10 @@
+/** Transport error that can optionally be marked retryable by the caller. */
+declare class TransportError extends Error {
+  public code: string;
+  public retryable: boolean;
+  public constructor(code: string, message: string, retryable?: boolean);
+  /** Create a retryable network failure that preserves queued events. */
+  public static network(message: string): TransportError;
+}
+
+export { TransportError };

package/utf8.cjs

@@ -0,0 +1,37 @@
+const ONE_BYTE_LIMIT = 0x80;
+const TWO_BYTE_LIMIT = 0x8_00;
+const THREE_BYTE_LIMIT = 0x1_00_00;
+const ONE_BYTE = 1;
+const TWO_BYTES = 2;
+const THREE_BYTES = 3;
+const FOUR_BYTES = 4;
+const NO_BYTES = 0;
+
+/**
+ * @param {string} character
+ * @returns {number}
+ */
+function characterBytes(character) {
+  const codePoint = character.codePointAt(NO_BYTES) ?? NO_BYTES;
+  if (codePoint < ONE_BYTE_LIMIT) {
+    return ONE_BYTE;
+  }
+  if (codePoint < TWO_BYTE_LIMIT) {
+    return TWO_BYTES;
+  }
+  return codePoint < THREE_BYTE_LIMIT ? THREE_BYTES : FOUR_BYTES;
+}
+
+/**
+ * @param {string} value
+ * @returns {number}
+ */
+function utf8ByteLength(value) {
+  let bytes = NO_BYTES;
+  for (const character of value) {
+    bytes += characterBytes(character);
+  }
+  return bytes;
+}
+
+module.exports = { utf8ByteLength };

package/validation.cjs

@@ -7,6 +7,10 @@ const { SdkError } = require("./sdk-error.cjs");
  *   : Value extends object ? { readonly [Key in keyof Value]: DeepReadonly<Value[Key]> } : Value} DeepReadonly
  */
 
+/**
+ * @typedef {(...args: readonly never[]) => unknown} Callable
+ */
+
 const ZERO_TRACE_ID = "00000000000000000000000000000000";
 const ZERO_SPAN_ID = "0000000000000000";
 const TRACE_ID_PATTERN = /^[0-9a-fA-F]{32}$/u;
@@ -107,6 +111,45 @@ function requireNonEmpty(label, value) {
   return value;
 }
 
+/** @type {(value: unknown) => boolean} */
+const isTruthy = Boolean;
+
+/**
+ * @param {unknown} value
+ * @returns {value is Callable}
+ */
+function isCallable(value) {
+  return typeof value === "function";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Readonly<Record<string, unknown>>}
+ */
+function isObjectValue(value) {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} key
+ * @returns {unknown}
+ */
+function optionalProperty(value, key) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  return Reflect.get(new Object(value), key);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function stringOrUndefined(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
 /**
  * @template {string} Allowed
  * @param {string} value
@@ -262,9 +305,13 @@ module.exports = {
   ZERO_TRACE_ID,
   hasUnicodeControlCharacter,
   isAllowedValue,
+  isCallable,
   isList,
+  isObjectValue,
   isRecord,
+  isTruthy,
   optionalEntry,
+  optionalProperty,
   rejectUnknownKeys,
   requireAllowedValue,
   requireFiniteNumber,
@@ -275,5 +322,6 @@ module.exports = {
   requireSpanId,
   requireTimestamp,
   requireTraceFlags,
-  requireTraceId
+  requireTraceId,
+  stringOrUndefined
 };

package/vite-release-artifacts-config.cjs

@@ -0,0 +1,120 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+/**
+ * @typedef {{ readonly build?: unknown, readonly esbuild?: unknown, readonly root?: unknown }} ViteUserConfig
+ * @typedef {{
+ *   build?: { rolldownOptions?: { output: { keepNames: true } }, sourcemap?: "hidden" },
+ *   esbuild?: { keepNames: true }
+ * }} ViteConfigChanges
+ */
+
+const ROLLDOWN_VITE_MAJOR = 8;
+const UNKNOWN_VITE_MAJOR = 0;
+const DECIMAL = 10;
+
+/**
+ * @param {unknown} manifest
+ * @returns {unknown}
+ */
+function packageVersion(manifest) {
+  return typeof manifest === "object" && manifest !== null ? Reflect.get(manifest, "version") : undefined;
+}
+
+/**
+ * @param {unknown} root
+ * @returns {string | undefined}
+ */
+function lookupRoot(root) {
+  const hasRoot = Boolean(root);
+  if (!hasRoot) {
+    return process.cwd();
+  }
+  return typeof root === "string" ? path.resolve(root) : undefined;
+}
+
+/**
+ * @param {unknown} root
+ * @returns {number}
+ */
+function viteMajorVersion(root) {
+  const lookup = lookupRoot(root);
+  if (lookup === undefined) {
+    return UNKNOWN_VITE_MAJOR;
+  }
+  try {
+    const manifestPath = require.resolve("vite/package.json", { paths: [lookup] });
+    /** @type {unknown} */
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const major = Number.parseInt(String(packageVersion(manifest)), DECIMAL);
+    return Number.isNaN(major) ? UNKNOWN_VITE_MAJOR : major;
+  } catch {
+    return UNKNOWN_VITE_MAJOR;
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} key
+ * @returns {unknown}
+ */
+function field(value, key) {
+  return typeof value === "object" && value !== null ? Reflect.get(value, key) : undefined;
+}
+
+/**
+ * @param {unknown} build
+ * @param {number} viteMajor
+ * @returns {boolean}
+ */
+function needsRolldownKeepNames(build, viteMajor) {
+  const output = field(field(build, "rolldownOptions"), "output");
+  return viteMajor >= ROLLDOWN_VITE_MAJOR && !Array.isArray(output) && field(output, "keepNames") === undefined;
+}
+
+/**
+ * @param {unknown} esbuild
+ * @param {number} viteMajor
+ * @returns {boolean}
+ */
+function needsEsbuildKeepNames(esbuild, viteMajor) {
+  return viteMajor < ROLLDOWN_VITE_MAJOR && esbuild !== false && field(esbuild, "keepNames") === undefined;
+}
+
+/**
+ * @param {boolean} sourceMap
+ * @param {boolean} modernNames
+ * @returns {ViteConfigChanges}
+ */
+function buildChanges(sourceMap, modernNames) {
+  if (!sourceMap && !modernNames) {
+    return {};
+  }
+  return {
+    build: {
+      ...(sourceMap ? { sourcemap: "hidden" } : {}),
+      ...(modernNames ? { rolldownOptions: { output: { keepNames: true } } } : {})
+    }
+  };
+}
+
+/**
+ * @param {ViteUserConfig} config
+ * @param {boolean} enableSourceMaps
+ * @returns {ViteConfigChanges | null}
+ */
+function viteConfigChanges(config, enableSourceMaps) {
+  const sourceMap = enableSourceMaps && field(config.build, "sourcemap") === undefined;
+  const keepNames = field(config.build, "minify") === undefined;
+  const viteMajor = viteMajorVersion(config.root);
+  const modernNames = keepNames && needsRolldownKeepNames(config.build, viteMajor);
+  const legacyNames = keepNames && needsEsbuildKeepNames(config.esbuild, viteMajor);
+  if (!sourceMap && !modernNames && !legacyNames) {
+    return null;
+  }
+  return { ...buildChanges(sourceMap, modernNames), ...(legacyNames ? { esbuild: { keepNames: true } } : {}) };
+}
+
+module.exports = { viteConfigChanges };