@logbrew/sdk 0.1.0 → 0.1.1

package/README.md

@@ -7,36 +7,11 @@ Public JavaScript SDK for creating LogBrew event batches, validating them locall
 ```bash
 npm install @logbrew/sdk
 pnpm add @logbrew/sdk
-npm --prefix node_modules/@logbrew/sdk/examples run
-npm --prefix node_modules/@logbrew/sdk/examples run list
-npm --prefix node_modules/@logbrew/sdk/examples run help
-npm --prefix node_modules/@logbrew/sdk/examples run readme-example
-npm --prefix node_modules/@logbrew/sdk/examples run readme-example:cjs
-npm --prefix node_modules/@logbrew/sdk/examples run real-user-smoke
-npm --prefix node_modules/@logbrew/sdk/examples run real-user-smoke:cjs
-pnpm --dir node_modules/@logbrew/sdk/examples run
-pnpm --dir node_modules/@logbrew/sdk/examples run list
-pnpm --dir node_modules/@logbrew/sdk/examples run help
-pnpm --dir node_modules/@logbrew/sdk/examples run readme-example
-pnpm --dir node_modules/@logbrew/sdk/examples run readme-example:cjs
-pnpm --dir node_modules/@logbrew/sdk/examples run real-user-smoke
-pnpm --dir node_modules/@logbrew/sdk/examples run real-user-smoke:cjs
-node node_modules/@logbrew/sdk/examples/index.mjs --help
-node node_modules/@logbrew/sdk/examples/index.mjs --list
-node node_modules/@logbrew/sdk/examples/index.mjs readme-example
-node node_modules/@logbrew/sdk/examples/index.mjs readme-example:cjs
-node node_modules/@logbrew/sdk/examples/index.mjs real-user-smoke
-node node_modules/@logbrew/sdk/examples/index.mjs
-node node_modules/@logbrew/sdk/examples/index.mjs real-user-smoke:cjs
-node node_modules/@logbrew/sdk/examples/readme-example.mjs
-node node_modules/@logbrew/sdk/examples/readme-example.cjs
-node node_modules/@logbrew/sdk/examples/real-user-smoke.mjs
-node node_modules/@logbrew/sdk/examples/real-user-smoke.cjs
 ```
 
 The package supports both ESM `import` and CommonJS `require`.
 The shipped package also includes `.d.ts` and `.d.cts` declarations so ESM and CommonJS TypeScript consumers can install it directly without a separate build step.
-The packed tarball and installed package both ship `README.md`, package metadata, an explicit ESM/CommonJS `exports` map, runnable `examples/readme-example.mjs`, `examples/readme-example.cjs`, `examples/real-user-smoke.mjs`, and `examples/real-user-smoke.cjs` files, a tiny `examples/package.json` helper surface, a packaged `examples/index.mjs` launcher, declaration comments in `index.d.ts`, and the CommonJS `index.d.cts` declaration path that TypeScript-aware tools can inspect. Those packed and installed README, example, and declaration surfaces should still include the normal `npm` and `pnpm` install commands, the fake `LOGBREW_API_KEY` placeholder guidance, the `previewJson()` usage note, the optional `parseTraceparent()`, `createTraceparent()`, `spanAttributesFromTraceparent()`, `installLogBrewConsoleCapture()`, `createLogBrewPinoDestination()`, and `createLogBrewWinstonTransport()` guidance, the helper discovery commands, helper runtime commands, and launcher commands shown above, and the typed API docs for shapes like `ReleaseAttributes`, `SpanAttributes`, `TraceparentContext`, `TraceparentInput`, `TraceparentSpanInput`, `Event`, `ConsoleCaptureConfig`, `ConsoleCaptureHandle`, `PinoDestinationConfig`, `PinoDestinationHandle`, `PinoLogRecord`, `WinstonTransportConfig`, `WinstonTransportHandle`, `WinstonLogInfo`, `SdkError`, `TransportError`, `TransportResponse`, `alwaysAccept()`, `lastBody()`, `pendingEvents()`, `flush()`, and `shutdown()`. Real installs should also start from a package-manager-native app bootstrap, using `npm init -y` on the npm path and `pnpm init` on the pnpm path, then rewrite the temp app `package.json` dependencies plus the lockfiles so they point back to the packed `.tgz` with the expected file target and integrity metadata, while npm’s own `npm pack --dry-run --json` and `npm pack --json` outputs still report the expected tarball name, integrity, shasum, and file list, and those generated lockfiles should retain that same tarball integrity value before recreating the install through `npm ci` and `pnpm install --frozen-lockfile`. The temp app should also survive a package-manager-native removal step, with `npm uninstall @logbrew/sdk` and `pnpm remove @logbrew/sdk` dropping the SDK from `package.json`, the top-level installed-package list, and `node_modules` before the tarball is added back. The consumer graph should also stay explicit in package-manager-native output, with plain `npm ls @logbrew/sdk` and `pnpm ls @logbrew/sdk` showing the direct installed SDK tree a user reads in the terminal, `npm explain @logbrew/sdk` showing the direct root-project edge, `pnpm why @logbrew/sdk` showing the temp app dependency relationship, plain `npm list --depth=0` and `pnpm list --depth=0` showing the top-level installed dependency summary, and `npm list --json --depth=0` plus `pnpm list --json --depth=0` still listing the temp app and direct installed dependencies, while small installed-user script entries in the temp app still exercise the shipped package through `npm run` and `pnpm run`, including a TypeScript typecheck script that compiles both an ESM `.ts` consumer and a CommonJS `.cts` consumer plus a script that mirrors the published README example before and after reinstall. The installed package should also let a consumer run the shipped README-style and stronger happy-path ESM and CommonJS example files directly from `node_modules/@logbrew/sdk/examples/`, and it now ships a small Node launcher at `node node_modules/@logbrew/sdk/examples/index.mjs` so users can discover packaged examples through `--help`, list them through `--list`, run the default no-argument `real-user-smoke` path, or select named examples like `readme-example` and `real-user-smoke` without going through package-manager scripts. The helper commands in `node_modules/@logbrew/sdk/examples/package.json` should still be discoverable enough that plain `npm --prefix node_modules/@logbrew/sdk/examples run` and `pnpm --dir node_modules/@logbrew/sdk/examples run` list the available example entrypoints before users run `npm --prefix node_modules/@logbrew/sdk/examples run help`, where that help output should print copy-pasteable installed-user commands for both npm and pnpm across the README and `real-user-smoke` default, ESM, and CommonJS example paths, including `npm --prefix node_modules/@logbrew/sdk/examples run readme-example` or `pnpm --dir node_modules/@logbrew/sdk/examples run readme-example`, `npm --prefix node_modules/@logbrew/sdk/examples run readme-example:esm` or `pnpm --dir node_modules/@logbrew/sdk/examples run readme-example:esm`, `npm --prefix node_modules/@logbrew/sdk/examples run readme-example:cjs` or `pnpm --dir node_modules/@logbrew/sdk/examples run readme-example:cjs`, `npm --prefix node_modules/@logbrew/sdk/examples run real-user-smoke` or `pnpm --dir node_modules/@logbrew/sdk/examples run real-user-smoke`, `npm --prefix node_modules/@logbrew/sdk/examples run real-user-smoke:esm` or `pnpm --dir node_modules/@logbrew/sdk/examples run real-user-smoke:esm`, and `npm --prefix node_modules/@logbrew/sdk/examples run real-user-smoke:cjs` or `pnpm --dir node_modules/@logbrew/sdk/examples run real-user-smoke:cjs`, while the launcher surface itself should still reveal `node node_modules/@logbrew/sdk/examples/index.mjs --help`, `node node_modules/@logbrew/sdk/examples/index.mjs --list`, `node node_modules/@logbrew/sdk/examples/index.mjs`, `node node_modules/@logbrew/sdk/examples/index.mjs readme-example`, `node node_modules/@logbrew/sdk/examples/index.mjs real-user-smoke`, and `node node_modules/@logbrew/sdk/examples/index.mjs real-user-smoke:cjs`.
+The package ships copyable examples under `node_modules/@logbrew/sdk/examples/`. Use the fake `LOGBREW_API_KEY` placeholder in docs, keep the real key in your app configuration, and call `previewJson()` when you want to inspect queued JSON before sending. Type declarations document payload shapes such as `ReleaseAttributes`, `SpanAttributes`, `MetricAttributes`, transport responses, SDK errors, lifecycle helpers, W3C trace helpers, product timeline helpers, console capture, Pino destination, and Winston transport APIs.
 
 ## Example
 
@@ -87,13 +62,30 @@ const response = await client.shutdown(transport);
 console.error(JSON.stringify({ ok: true, status: response.statusCode, attempts: response.attempts, events: 6 }));
 ```
 
+## 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.
+
+```js
+client.metric("evt_metric_001", "2026-06-02T10:00:06Z", {
+  name: "checkout.requests",
+  kind: "counter",
+  value: 42,
+  unit: "{request}",
+  temporality: "delta",
+  metadata: { service: "checkout" }
+});
+```
+
+Metric `kind` must be `counter`, `gauge`, or `histogram`. Counters and histograms must be non-negative and use `delta` or `cumulative` temporality; gauges use `instant` temporality and may be negative. Keep metric metadata primitive and low-cardinality, such as service, region, or route template.
+
 ## W3C Trace Context
 
 Use `parseTraceparent()`, `createTraceparent()`, and `spanAttributesFromTraceparent()` when a JavaScript service needs to continue trace context from OpenTelemetry-compatible services or pass a W3C `traceparent` value downstream.
 
 ```js
 import {
-  createTraceparent,
+  createTraceparentHeaders,
   LogBrewClient,
   RecordingTransport,
   spanAttributesFromTraceparent
@@ -115,19 +107,61 @@ const span = spanAttributesFromTraceparent(incomingTraceparent, {
 });
 client.span("evt_checkout_span", "2026-06-02T10:00:04Z", span);
 
-const downstreamTraceparent = createTraceparent({
-  traceId: span.traceId,
-  spanId: span.spanId,
-  traceFlags: "01"
-});
 await fetch("https://example.invalid/payments", {
-  headers: { traceparent: downstreamTraceparent }
+  headers: createTraceparentHeaders({
+    traceId: span.traceId,
+    spanId: span.spanId,
+    traceFlags: "01"
+  })
 });
 
 await client.flush(RecordingTransport.alwaysAccept());
 ```
 
-The helpers validate the W3C `version-traceId-parentSpanId-traceFlags` shape, reject all-zero trace/span ids, normalize valid ids to lowercase, expose the sampled flag from `traceFlags`, and keep span metadata primitive-only. They do not install OpenTelemetry or patch HTTP clients; use them when you need explicit interop in code you own.
+The helpers validate the W3C `version-traceId-parentSpanId-traceFlags` shape, reject all-zero trace/span ids, normalize valid ids to lowercase, expose the sampled flag from `traceFlags`, and keep span metadata primitive-only. `createTraceparentHeaders()` returns an explicit outbound carrier with only `traceparent`. The helpers do not install OpenTelemetry or patch HTTP clients; use them when you need explicit interop in code you own.
+
+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.
+
+## Agent-Readable Timelines
+
+Use `createProductActionAttributes()` and `createNetworkMilestoneAttributes()` when a service already knows important product steps or API milestones. The helpers create normal `action` event attributes with primitive metadata that can be analyzed across many sessions without visual replay, global HTTP patching, payload capture, or header capture.
+
+```js
+import {
+  createNetworkMilestoneAttributes,
+  createProductActionAttributes,
+  LogBrewClient
+} from "@logbrew/sdk";
+
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-api",
+  sdkVersion: "1.0.0"
+});
+
+client.action("evt_checkout_submit", new Date().toISOString(), createProductActionAttributes({
+  name: "checkout.submit",
+  status: "running",
+  sessionId: "sess_123",
+  traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+  routeTemplate: "/checkout/:step",
+  funnel: "checkout",
+  step: "submit",
+  metadata: { service: "checkout" }
+}));
+
+client.action("evt_payment_api", new Date().toISOString(), createNetworkMilestoneAttributes({
+  routeTemplate: "/payments/:id",
+  method: "POST",
+  statusCode: 202,
+  durationMs: 94,
+  sessionId: "sess_123",
+  traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+  metadata: { service: "checkout" }
+}));
+```
+
+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. Keep metadata low-cardinality, such as `sessionId`, `traceId`, `routeTemplate`, `method`, `statusCode`, `durationMs`, `screen`, `funnel`, and `step`.
 
 ## Console Capture
 
@@ -186,7 +220,7 @@ logger.error(new Error("payment failed"), "checkout failed");
 await destination.flush();
 ```
 
-The Pino adapter reads JSON log lines, maps `trace`/`debug`/`info`/`warn`/`error`/`fatal` into LogBrew levels, captures primitive Pino fields as `context.*`, captures serialized error name/message, skips noisy runtime defaults, and omits stack text unless `includeErrorStack: true` is set. It does not patch Pino or replace application logger ownership.
+The Pino adapter reads JSON log lines, maps Pino `trace`/`debug` to LogBrew `info`, `warn` to `warning`, `error` to `error`, and `fatal` to `critical`, captures primitive Pino fields as `context.*`, captures serialized error name/message, skips noisy runtime defaults, and omits stack text unless `includeErrorStack: true` is set. It does not patch Pino or replace application logger ownership.
 
 ## Winston Transport
 
@@ -220,6 +254,6 @@ logger.error(new Error("payment failed"));
 await logbrewTransport.flush();
 ```
 
-The Winston adapter receives Winston `info` objects, maps `debug`/`silly` to `debug`, `warn` to `warning`, `error`/`fatal` to `error`, and other common Winston levels to `info`. It captures primitive info fields as `context.*`, captures nested `err`/`error` objects or formatted error stack name/message, omits stack text unless `includeErrorStack: true` is set, and exposes `onError` for capture failures. It does not mutate Winston globals or replace the app's logger.
+The Winston adapter receives Winston `info` objects, maps `debug`/`silly` to LogBrew `info`, `warn` to `warning`, `error` to `error`, `fatal`/`critical` to `critical`, and other common Winston levels to `info`. It captures primitive info fields as `context.*`, captures nested `err`/`error` objects or formatted error stack name/message, omits stack text unless `includeErrorStack: true` is set, and exposes `onError` for capture failures. It does not mutate Winston globals or replace the app's logger.
 
-Use a clearly fake placeholder like `LOGBREW_API_KEY` in local examples and tests. Call `flush` or `shutdown` to send queued events through a transport, and use `previewJson()` when you want a stable local JSON preview without sending anything.
+Use a clearly fake placeholder like `LOGBREW_API_KEY` in examples. Call `flush` or `shutdown` to send queued events through a transport, and use `previewJson()` when you want a stable local JSON preview before sending anything.

package/examples/real-user-smoke.cjs

@@ -9,7 +9,16 @@ try {
   }
 }
 
-const { LogBrewClient, RecordingTransport } = sdk;
+const { createTraceparentHeaders, LogBrewClient, RecordingTransport } = sdk;
+
+const outgoingHeaders = createTraceparentHeaders({
+  traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+  spanId: "b7ad6b7169203331",
+  traceFlags: "01"
+});
+if (outgoingHeaders.traceparent !== "00-4bf92f3577b34da6a3ce929d0e0e4736-b7ad6b7169203331-01") {
+  throw new Error("createTraceparentHeaders produced an unexpected carrier");
+}
 
 const client = LogBrewClient.create({
   apiKey: "LOGBREW_API_KEY",

package/examples/real-user-smoke.mjs

@@ -5,7 +5,16 @@ const sdk = await import("@logbrew/sdk").catch(async (error) => {
   throw error;
 });
 
-const { LogBrewClient, RecordingTransport } = sdk;
+const { createTraceparentHeaders, LogBrewClient, RecordingTransport } = sdk;
+
+const outgoingHeaders = createTraceparentHeaders({
+  traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+  spanId: "b7ad6b7169203331",
+  traceFlags: "01"
+});
+if (outgoingHeaders.traceparent !== "00-4bf92f3577b34da6a3ce929d0e0e4736-b7ad6b7169203331-01") {
+  throw new Error("createTraceparentHeaders produced an unexpected carrier");
+}
 
 const client = LogBrewClient.create({
   apiKey: "LOGBREW_API_KEY",

package/index.cjs

@@ -1,7 +1,23 @@
-const ISSUE_LEVELS = new Set(["info", "warning", "error", "critical"]);
-const LOG_LEVELS = new Set(["debug", "info", "warning", "error"]);
+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());
 const SPAN_STATUSES = new Set(["ok", "error"]);
 const ACTION_STATUSES = new Set(["queued", "running", "success", "failure"]);
+const METRIC_KINDS = new Set(["counter", "gauge", "histogram"]);
+const NON_NEGATIVE_METRIC_KINDS = new Set(["counter", "histogram"]);
+const METRIC_TEMPORALITIES_BY_KIND = new Map([
+  ["counter", new Set(["delta", "cumulative"])],
+  ["gauge", new Set(["instant"])],
+  ["histogram", new Set(["delta", "cumulative"])]
+]);
 const CONSOLE_METHODS = new Set(["debug", "info", "log", "warn", "error"]);
 const DEFAULT_CONSOLE_LEVELS = ["debug", "info", "log", "warn", "error"];
 const PINO_HOST_FIELD = ["host", "name"].join("");
@@ -119,6 +135,10 @@ class LogBrewClient {
     this.#pushEvent("action", id, timestamp, validateAction(attributes));
   }
 
+  metric(id, timestamp, attributes) {
+    this.#pushEvent("metric", id, timestamp, validateMetric(attributes));
+  }
+
   async flush(transport) {
     if (this.closed) {
       throw new SdkError("shutdown_error", "client is already shut down");
@@ -326,7 +346,7 @@ function logAttributesFromConsoleArgs(method, args, options = {}) {
 function logbrewLevelFromConsoleMethod(method) {
   switch (method) {
     case "debug":
-      return "debug";
+      return "info";
     case "warn":
       return "warning";
     case "error":
@@ -339,6 +359,44 @@ function logbrewLevelFromConsoleMethod(method) {
   }
 }
 
+function createProductActionAttributes(action, options = {}) {
+  const details = productActionDetails(action);
+  return {
+    name: details.name,
+    status: details.status,
+    metadata: compactMetadata({
+      source: "product.action",
+      ...compactMetadata(options.metadata),
+      ...compactMetadata(details.metadata),
+      routeTemplate: sanitizeRouteTemplate(details.routeTemplate),
+      sessionId: stringOrUndefined(details.sessionId),
+      traceId: stringOrUndefined(details.traceId),
+      screen: stringOrUndefined(details.screen),
+      funnel: stringOrUndefined(details.funnel),
+      step: stringOrUndefined(details.step)
+    })
+  };
+}
+
+function createNetworkMilestoneAttributes(request, options = {}) {
+  const details = networkMilestoneDetails(request);
+  return {
+    name: details.name,
+    status: details.status,
+    metadata: compactMetadata({
+      source: "network.milestone",
+      ...compactMetadata(options.metadata),
+      ...compactMetadata(details.metadata),
+      routeTemplate: details.routeTemplate,
+      method: details.method,
+      statusCode: details.statusCode,
+      durationMs: details.durationMs,
+      sessionId: stringOrUndefined(details.sessionId),
+      traceId: stringOrUndefined(details.traceId)
+    })
+  };
+}
+
 function parseTraceparent(traceparent) {
   if (typeof traceparent !== "string" || traceparent.trim() === "") {
     throw new SdkError("validation_error", "traceparent must be non-empty");
@@ -379,6 +437,10 @@ function createTraceparent({ traceId, spanId, traceFlags = "01" }) {
   return `00-${traceId.toLowerCase()}-${spanId.toLowerCase()}-${traceFlags.toLowerCase()}`;
 }
 
+function createTraceparentHeaders(input) {
+  return { traceparent: createTraceparent(input) };
+}
+
 function spanAttributesFromTraceparent(traceparent, attributes) {
   if (!attributes || Array.isArray(attributes) || typeof attributes !== "object") {
     throw new SdkError("validation_error", "span attributes must be an object");
@@ -646,15 +708,16 @@ function logbrewLevelFromWinstonLevel(level) {
   switch (String(level).toLowerCase()) {
     case "debug":
     case "silly":
-      return "debug";
+      return "info";
     case "warn":
     case "warning":
       return "warning";
     case "error":
+      return "error";
     case "crit":
     case "critical":
     case "fatal":
-      return "error";
+      return "critical";
     case "http":
     case "verbose":
     case "info":
@@ -757,6 +820,9 @@ function timestampFromPinoRecord(record, fallbackTimestamp) {
 
 function logbrewLevelFromPinoLevel(level) {
   if (typeof level === "number" && Number.isFinite(level)) {
+    if (level >= 60) {
+      return "critical";
+    }
     if (level >= 50) {
       return "error";
     }
@@ -766,19 +832,21 @@ function logbrewLevelFromPinoLevel(level) {
     if (level >= 30) {
       return "info";
     }
-    return "debug";
+    return "info";
   }
 
   switch (String(level).toLowerCase()) {
     case "trace":
     case "debug":
-      return "debug";
+      return "info";
     case "warn":
     case "warning":
       return "warning";
     case "error":
-    case "fatal":
       return "error";
+    case "fatal":
+    case "critical":
+      return "critical";
     case "info":
     default:
       return "info";
@@ -881,6 +949,12 @@ function requireAllowedValue(label, value, allowedValues) {
   }
 }
 
+function requireFiniteNumber(label, value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new SdkError("validation_error", `${label} must be a finite number`);
+  }
+}
+
 function requireTraceId(traceId) {
   if (typeof traceId !== "string" || !/^[0-9a-fA-F]{32}$/u.test(traceId)) {
     throw new SdkError("validation_error", "traceId must be 32 lowercase or uppercase hex characters");
@@ -952,24 +1026,29 @@ function validateEnvironment(attributes) {
 
 function validateIssue(attributes) {
   requireNonEmpty("issue title", attributes.title);
-  requireAllowedValue("issue level", attributes.level, ISSUE_LEVELS);
+  const level = normalizeSeverity("issue level", attributes.level);
   return withMetadata({
     title: attributes.title,
-    level: attributes.level,
+    level,
     ...(attributes.message !== undefined ? { message: attributes.message } : {})
   }, attributes.metadata);
 }
 
 function validateLog(attributes) {
   requireNonEmpty("log message", attributes.message);
-  requireAllowedValue("log level", attributes.level, LOG_LEVELS);
+  const level = normalizeSeverity("log level", attributes.level);
   return withMetadata({
     message: attributes.message,
-    level: attributes.level,
+    level,
     ...(attributes.logger !== undefined ? { logger: attributes.logger } : {})
   }, attributes.metadata);
 }
 
+function normalizeSeverity(label, value) {
+  requireAllowedValue(label, value, SEVERITY_VALUES);
+  return SEVERITY_ALIASES.get(value);
+}
+
 function validateSpan(attributes) {
   requireNonEmpty("span name", attributes.name);
   requireNonEmpty("span traceId", attributes.traceId);
@@ -1002,6 +1081,146 @@ function validateAction(attributes) {
   }, attributes.metadata);
 }
 
+function validateMetric(attributes) {
+  requireNonEmpty("metric name", attributes.name);
+  requireAllowedValue("metric kind", attributes.kind, METRIC_KINDS);
+  requireFiniteNumber("metric value", attributes.value);
+  requireNonEmpty("metric unit", attributes.unit);
+
+  const allowedTemporalities = METRIC_TEMPORALITIES_BY_KIND.get(attributes.kind);
+  requireAllowedValue(`metric temporality for ${attributes.kind}`, attributes.temporality, allowedTemporalities);
+  if (NON_NEGATIVE_METRIC_KINDS.has(attributes.kind) && attributes.value < 0) {
+    throw new SdkError("validation_error", `metric ${attributes.kind} value must be non-negative`);
+  }
+
+  return withMetadata({
+    name: attributes.name,
+    kind: attributes.kind,
+    value: attributes.value,
+    unit: attributes.unit,
+    temporality: attributes.temporality
+  }, attributes.metadata);
+}
+
+function productActionDetails(action) {
+  if (typeof action === "string") {
+    return { name: action, status: "success" };
+  }
+  if (!action || Array.isArray(action) || typeof action !== "object") {
+    throw new SdkError("validation_error", "product action must be a string or object");
+  }
+  requireNonEmpty("product action name", action.name);
+  const status = action.status === undefined ? "success" : action.status;
+  requireAllowedValue("product action status", status, ACTION_STATUSES);
+  return {
+    funnel: action.funnel,
+    metadata: action.metadata,
+    name: action.name,
+    routeTemplate: action.routeTemplate,
+    screen: action.screen,
+    sessionId: action.sessionId,
+    status,
+    step: action.step,
+    traceId: action.traceId
+  };
+}
+
+function networkMilestoneDetails(request) {
+  if (typeof request === "string") {
+    return networkMilestoneDetails({ routeTemplate: request });
+  }
+  if (!request || Array.isArray(request) || typeof request !== "object") {
+    throw new SdkError("validation_error", "network milestone must be a string or object");
+  }
+
+  const routeTemplate = sanitizeRouteTemplate(request.routeTemplate);
+  requireNonEmpty("network milestone routeTemplate", routeTemplate);
+  const method = normalizeHttpMethod(request.method);
+  const statusCode = statusCodeOrUndefined(request.statusCode);
+  const status = request.status === undefined
+    ? statusFromStatusCode(statusCode)
+    : request.status;
+  requireAllowedValue("network milestone status", status, ACTION_STATUSES);
+  const durationMs = nonNegativeNumberOrUndefined("network milestone durationMs", request.durationMs);
+  const name = typeof request.name === "string" && request.name.trim() !== ""
+    ? request.name
+    : `network.${method.toLowerCase()} ${routeTemplate}`;
+
+  return {
+    durationMs,
+    metadata: request.metadata,
+    method,
+    name,
+    routeTemplate,
+    sessionId: request.sessionId,
+    status,
+    statusCode,
+    traceId: request.traceId
+  };
+}
+
+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();
+  if (trimmed === "") {
+    return "";
+  }
+  try {
+    const url = new URL(trimmed, "https://logbrew.example");
+    return url.pathname || "/";
+  } catch {
+    return trimmed.split(/[?#]/u)[0] || "/";
+  }
+}
+
+function normalizeHttpMethod(method) {
+  const value = method === undefined ? "GET" : method;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new SdkError("validation_error", "network milestone method must be a non-empty string");
+  }
+  const normalized = value.trim().toUpperCase();
+  if (!/^[A-Z][A-Z0-9_-]*$/u.test(normalized)) {
+    throw new SdkError("validation_error", "network milestone method must be a valid HTTP method");
+  }
+  return normalized;
+}
+
+function statusCodeOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Number.isInteger(value) || value < 100 || value > 599) {
+    throw new SdkError("validation_error", "network milestone statusCode must be an integer from 100 to 599");
+  }
+  return value;
+}
+
+function statusFromStatusCode(statusCode) {
+  if (statusCode !== undefined && statusCode >= 400) {
+    return "failure";
+  }
+  return "success";
+}
+
+function nonNegativeNumberOrUndefined(label, value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new SdkError("validation_error", `${label} must be a non-negative number`);
+  }
+  return value;
+}
+
+function stringOrUndefined(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
 function withMetadata(attributes, metadata) {
   const safeMetadata = cloneMetadata(metadata);
   return safeMetadata === undefined
@@ -1082,7 +1301,10 @@ function formatConsoleArgument(value, includeErrorStack) {
 }
 
 module.exports = {
+  createNetworkMilestoneAttributes,
+  createProductActionAttributes,
   createTraceparent,
+  createTraceparentHeaders,
   createLogBrewPinoDestination,
   createLogBrewWinstonTransport,
   installLogBrewConsoleCapture,

package/index.d.cts

@@ -2,6 +2,12 @@
 export type MetadataValue = string | number | boolean | null;
 /** Structured metadata map shared by public LogBrew event attribute types. */
 export type Metadata = Record<string, MetadataValue>;
+/** Canonical user-facing severity categories accepted by LogBrew. */
+export type Severity = "info" | "warning" | "error" | "critical";
+/** Runtime-level aliases accepted for compatibility and normalized before send. */
+export type SeverityAlias = "trace" | "debug" | "warn" | "fatal";
+/** Public severity input accepted by issue and log attributes. */
+export type SeverityInput = Severity | SeverityAlias;
 
 /** Parsed W3C trace context from a traceparent value. */
 export type TraceparentContext = {
@@ -46,7 +52,7 @@ export type EnvironmentAttributes = {
 /** Public issue event attributes. */
 export type IssueAttributes = {
   title: string;
-  level: "info" | "warning" | "error" | "critical";
+  level: SeverityInput;
   message?: string;
   metadata?: Metadata;
 };
@@ -54,7 +60,7 @@ export type IssueAttributes = {
 /** Public log event attributes. */
 export type LogAttributes = {
   message: string;
-  level: "debug" | "info" | "warning" | "error";
+  level: SeverityInput;
   logger?: string;
   metadata?: Metadata;
 };
@@ -177,6 +183,54 @@ export type ActionAttributes = {
   metadata?: Metadata;
 };
 
+/** App-owned product step input for agent-readable action timelines. */
+export 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. */
+export 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. */
+export type TimelineAttributesOptions = {
+  metadata?: Metadata;
+};
+
+/** Public metric event attributes. Use low-cardinality metadata only. */
+export type MetricAttributes = {
+  name: string;
+  kind: "counter" | "histogram";
+  value: number;
+  unit: string;
+  temporality: "delta" | "cumulative";
+  metadata?: Metadata;
+} | {
+  name: string;
+  kind: "gauge";
+  value: number;
+  unit: string;
+  temporality: "instant";
+  metadata?: Metadata;
+};
+
 /** Public event union used in preview and transport payloads. */
 export type Event =
   | { type: "release"; id: string; timestamp: string; attributes: ReleaseAttributes }
@@ -184,7 +238,8 @@ export type Event =
   | { 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: "action"; id: string; timestamp: string; attributes: ActionAttributes }
+  | { type: "metric"; id: string; timestamp: string; attributes: MetricAttributes };
 
 /** Stable transport response returned from flush and shutdown operations. */
 export type TransportResponse = {
@@ -245,6 +300,7 @@ export declare class LogBrewClient {
   log(id: string, timestamp: string, attributes: LogAttributes): void;
   span(id: string, timestamp: string, attributes: SpanAttributes): void;
   action(id: string, timestamp: string, attributes: ActionAttributes): void;
+  metric(id: string, timestamp: string, attributes: MetricAttributes): void;
   /** Flush queued events through a transport while preserving retry semantics. */
   flush(transport: Transport): Promise<TransportResponse>;
   /** Flush queued events, then mark the client closed so later writes fail. */
@@ -254,6 +310,18 @@ export declare class LogBrewClient {
 /** Install explicit console capture while preserving the target console's normal output behavior. */
 export declare function installLogBrewConsoleCapture(config: ConsoleCaptureConfig): ConsoleCaptureHandle;
 
+/** Create safe action attributes for an app-owned product step without automatic UI capture. */
+export declare function createProductActionAttributes(
+  action: ProductActionInput,
+  options?: TimelineAttributesOptions
+): ActionAttributes;
+
+/** Create safe action attributes for an app-owned network milestone without HTTP client patching. */
+export declare function createNetworkMilestoneAttributes(
+  request: NetworkMilestoneInput,
+  options?: TimelineAttributesOptions
+): ActionAttributes;
+
 /** Convert console arguments into safe LogBrew log attributes without installing capture. */
 export declare function logAttributesFromConsoleArgs(
   method: ConsoleMethodName,
@@ -274,6 +342,9 @@ export declare function parseTraceparent(traceparent: string): TraceparentContex
 /** Create a W3C traceparent value from explicit trace/span ids. */
 export declare function createTraceparent(input: TraceparentInput): string;
 
+/** Create an explicit outbound header carrier containing only traceparent. */
+export declare function createTraceparentHeaders(input: TraceparentInput): { traceparent: string };
+
 /** Build LogBrew span attributes that continue an incoming W3C traceparent value. */
 export declare function spanAttributesFromTraceparent(
   traceparent: string,

package/index.d.ts

@@ -2,6 +2,12 @@
 export type MetadataValue = string | number | boolean | null;
 /** Structured metadata map shared by public LogBrew event attribute types. */
 export type Metadata = Record<string, MetadataValue>;
+/** Canonical user-facing severity categories accepted by LogBrew. */
+export type Severity = "info" | "warning" | "error" | "critical";
+/** Runtime-level aliases accepted for compatibility and normalized before send. */
+export type SeverityAlias = "trace" | "debug" | "warn" | "fatal";
+/** Public severity input accepted by issue and log attributes. */
+export type SeverityInput = Severity | SeverityAlias;
 
 /** Parsed W3C trace context from a traceparent value. */
 export type TraceparentContext = {
@@ -46,7 +52,7 @@ export type EnvironmentAttributes = {
 /** Public issue event attributes. */
 export type IssueAttributes = {
   title: string;
-  level: "info" | "warning" | "error" | "critical";
+  level: SeverityInput;
   message?: string;
   metadata?: Metadata;
 };
@@ -54,7 +60,7 @@ export type IssueAttributes = {
 /** Public log event attributes. */
 export type LogAttributes = {
   message: string;
-  level: "debug" | "info" | "warning" | "error";
+  level: SeverityInput;
   logger?: string;
   metadata?: Metadata;
 };
@@ -177,6 +183,54 @@ export type ActionAttributes = {
   metadata?: Metadata;
 };
 
+/** App-owned product step input for agent-readable action timelines. */
+export 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. */
+export 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. */
+export type TimelineAttributesOptions = {
+  metadata?: Metadata;
+};
+
+/** Public metric event attributes. Use low-cardinality metadata only. */
+export type MetricAttributes = {
+  name: string;
+  kind: "counter" | "histogram";
+  value: number;
+  unit: string;
+  temporality: "delta" | "cumulative";
+  metadata?: Metadata;
+} | {
+  name: string;
+  kind: "gauge";
+  value: number;
+  unit: string;
+  temporality: "instant";
+  metadata?: Metadata;
+};
+
 /** Public event union used in preview and transport payloads. */
 export type Event =
   | { type: "release"; id: string; timestamp: string; attributes: ReleaseAttributes }
@@ -184,7 +238,8 @@ export type Event =
   | { 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: "action"; id: string; timestamp: string; attributes: ActionAttributes }
+  | { type: "metric"; id: string; timestamp: string; attributes: MetricAttributes };
 
 /** Stable transport response returned from flush and shutdown operations. */
 export type TransportResponse = {
@@ -245,6 +300,7 @@ export declare class LogBrewClient {
   log(id: string, timestamp: string, attributes: LogAttributes): void;
   span(id: string, timestamp: string, attributes: SpanAttributes): void;
   action(id: string, timestamp: string, attributes: ActionAttributes): void;
+  metric(id: string, timestamp: string, attributes: MetricAttributes): void;
   /** Flush queued events through a transport while preserving retry semantics. */
   flush(transport: Transport): Promise<TransportResponse>;
   /** Flush queued events, then mark the client closed so later writes fail. */
@@ -254,6 +310,18 @@ export declare class LogBrewClient {
 /** Install explicit console capture while preserving the target console's normal output behavior. */
 export declare function installLogBrewConsoleCapture(config: ConsoleCaptureConfig): ConsoleCaptureHandle;
 
+/** Create safe action attributes for an app-owned product step without automatic UI capture. */
+export declare function createProductActionAttributes(
+  action: ProductActionInput,
+  options?: TimelineAttributesOptions
+): ActionAttributes;
+
+/** Create safe action attributes for an app-owned network milestone without HTTP client patching. */
+export declare function createNetworkMilestoneAttributes(
+  request: NetworkMilestoneInput,
+  options?: TimelineAttributesOptions
+): ActionAttributes;
+
 /** Convert console arguments into safe LogBrew log attributes without installing capture. */
 export declare function logAttributesFromConsoleArgs(
   method: ConsoleMethodName,
@@ -274,6 +342,9 @@ export declare function parseTraceparent(traceparent: string): TraceparentContex
 /** Create a W3C traceparent value from explicit trace/span ids. */
 export declare function createTraceparent(input: TraceparentInput): string;
 
+/** Create an explicit outbound header carrier containing only traceparent. */
+export declare function createTraceparentHeaders(input: TraceparentInput): { traceparent: string };
+
 /** Build LogBrew span attributes that continue an incoming W3C traceparent value. */
 export declare function spanAttributesFromTraceparent(
   traceparent: string,

package/index.js

@@ -1,7 +1,10 @@
 import sdk from "./index.cjs";
 
 export const {
+  createNetworkMilestoneAttributes,
+  createProductActionAttributes,
   createTraceparent,
+  createTraceparentHeaders,
   createLogBrewPinoDestination,
   createLogBrewWinstonTransport,
   installLogBrewConsoleCapture,

package/package.json

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