autotel 3.1.1 → 3.3.0

package/skills/review-otel-patterns/SKILL.md

@@ -7,6 +7,7 @@ description: >
   missing span attributes, manual exporter setup, broken context propagation, exposed PII, and ad-hoc
   error handling. Covers spans, metrics, logs, structured errors, the autotel processor pipeline
   (tail-sampling, attribute redaction, span-name normalisation, filtering, baggage),
+  built-in enrichers (user agent, geo, request size) and custom `defineEnricher`,
   `defineWorkerFetch` for Cloudflare async drains, multi-vendor OTLP backends (Honeycomb, Datadog,
   Grafana Cloud, Sentry, Axiom, HyperDX), `composeSpanProcessors` / `composeSubscribers` /
   `composePostProcessors` for pipelines, AI SDK observability with gen-ai semantic conventions, and
@@ -232,6 +233,46 @@ All options work with `init()`, framework adapters, and `wrapModule` / `defineWo
 
 ---
 
+## Built-in enrichers
+
+Enrichers turn raw request data into standard, low-cardinality span attributes. Import the helpers from `autotel/enrichers` and spread their output onto the active span or request logger. Each returns `undefined` when there is nothing to add, so spreading is safe.
+
+| Helper                                       | Returns attributes                                                   | Source                                  |
+| -------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------- |
+| `userAgent(headers)`                         | `user_agent.raw`, `user_agent.browser`, `user_agent.os`, `user_agent.device` | `user-agent` request header     |
+| `geo(headers)`                               | `geo.country`, `geo.region`, `geo.city`, `geo.latitude`, `geo.longitude`     | Vercel / Cloudflare geo headers |
+| `requestSize(reqHeaders, resHeaders?)`       | `http.request.body.size`, `http.response.body.size`                  | `content-length` headers                |
+
+```typescript
+import { userAgent, geo, requestSize } from 'autotel/enrichers';
+
+export const handler = trace((ctx) => async (request: Request) => {
+  ctx.setAttributes({
+    ...userAgent(request.headers),
+    ...geo(request.headers),
+    ...requestSize(request.headers),
+  });
+  // ... handle request
+});
+```
+
+For your own derived fields on a request's wide event, build a reusable enricher with `defineEnricher` (from `autotel`) instead of scattering ad-hoc field writes. `compute` returns an object that is merged into the named `field`; return `undefined` to skip. Keep the output low-cardinality (bucket or hash high-cardinality values):
+
+```typescript
+import { defineEnricher } from 'autotel';
+
+// Merge a derived, low-cardinality object into event.user on each request.
+const enrichTier = defineEnricher<{ user?: { plan?: string } }, { tier: string }>({
+  name: 'user-tier',
+  field: 'user',
+  compute: ({ event }) => ({ tier: event.user?.plan ?? 'anonymous' }),
+});
+```
+
+**Review checks:** raw `User-Agent` strings stored verbatim (use `userAgent()` to parse), geo data hand-parsed per framework (use `geo()`), and high-cardinality values (full URLs, emails, ids) set directly as attributes instead of being bucketed or hashed.
+
+---
+
 ## Backends (multi-vendor OTLP)
 
 Switch backends with **no code changes** — autotel speaks OTLP HTTP/JSON and HTTP/protobuf out of the box.

package/src/attribute-redacting-processor.ts

@@ -424,19 +424,22 @@ function createRedactorFromConfig(
     .map((vp) => [cloneRegex(vp.pattern), vp.mask!]);
 
   return (key: string, value: AttributeValue): AttributeValue => {
-    // Check if key matches any sensitive key pattern
-    for (const pattern of keyPatterns) {
-      pattern.lastIndex = 0;
-      if (pattern.test(key)) {
+    // Key-pattern and path-based redaction only applies to string values.
+    // Numbers, booleans and other non-string attributes are not credentials;
+    // replacing them with the string '[REDACTED]' silently changes their
+    // type and corrupts downstream consumers (LLM token counters etc.).
+    if (typeof value === 'string') {
+      for (const pattern of keyPatterns) {
+        pattern.lastIndex = 0;
+        if (pattern.test(key)) {
+          return defaultReplacement;
+        }
+      }
+      if (pathSet.has(key)) {
         return defaultReplacement;
       }
     }
 
-    // Check if key matches any path-based redaction
-    if (pathSet.has(key)) {
-      return defaultReplacement;
-    }
-
     // For non-string values, return as-is
     if (typeof value !== 'string') {
       if (Array.isArray(value)) {

package/src/define-event.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { defineEvent } from './define-event';
+
+describe('defineEvent', () => {
+  it('validates payload and exposes schema metadata when provided', () => {
+    const event = defineEvent(
+      'order.placed',
+      {
+        safeParse(input: unknown) {
+          if (
+            typeof input === 'object' &&
+            input !== null &&
+            'orderId' in input &&
+            typeof (input as Record<string, unknown>).orderId === 'string'
+          ) {
+            return {
+              success: true as const,
+              data: input as { orderId: string },
+            };
+          }
+          return { success: false as const, error: new Error('invalid') };
+        },
+      },
+      {
+        toJsonSchema: () => ({
+          type: 'object',
+          properties: { orderId: { type: 'string' } },
+          required: ['orderId'],
+        }),
+      },
+    );
+
+    expect(event.name).toBe('order.placed');
+    expect(event.schemaMetadata?.source).toBe('zod');
+    expect(event.schemaMetadata?.hash).toMatch(/^[a-f0-9]{64}$/);
+    expect(() => event.track({ orderId: 'o-1' })).not.toThrow();
+    expect(() => event.track({} as { orderId: string })).toThrow(
+      /Schema validation failed/,
+    );
+  });
+});

package/src/define-event.ts

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { track } from './track';
+import type { EventSchemaMetadata } from './event-subscriber';
+
+type SafeParseResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: unknown };
+
+export interface SchemaLike<T> {
+  safeParse(input: unknown): SafeParseResult<T>;
+}
+
+export interface DefineEventOptions<S> {
+  toJsonSchema?: (schema: S) => unknown;
+}
+
+export interface DefinedEvent<Name extends string, Payload> {
+  readonly name: Name;
+  readonly schemaMetadata?: EventSchemaMetadata;
+  track(payload: Payload): void;
+}
+
+export function defineEvent<
+  Name extends string,
+  Payload,
+  S extends SchemaLike<Payload>,
+>(
+  name: Name,
+  schema: S,
+  options: DefineEventOptions<S> = {},
+): DefinedEvent<Name, Payload> {
+  const jsonSchema = options.toJsonSchema?.(schema);
+  const schemaMetadata = jsonSchema
+    ? {
+        source: 'zod' as const,
+        jsonSchema,
+        hash: hashSchema(jsonSchema),
+      }
+    : undefined;
+
+  return {
+    name,
+    schemaMetadata,
+    track(payload: Payload) {
+      const parsed = schema.safeParse(payload);
+      if (!parsed.success) {
+        throw new Error(
+          `Invalid payload for event "${name}". Schema validation failed.`,
+        );
+      }
+      track(
+        name,
+        parsed.data,
+        schemaMetadata ? { schema: schemaMetadata } : undefined,
+      );
+    },
+  };
+}
+
+function hashSchema(schema: unknown): string {
+  return createHash('sha256').update(stableStringify(schema)).digest('hex');
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
+  }
+  const obj = value as Record<string, unknown>;
+  const body = Object.keys(obj)
+    .sort()
+    .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
+    .join(',');
+  return '{' + body + '}';
+}

package/src/error-catalog.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest';
+import {
+  defineErrorCatalog,
+  defineAuditCatalog,
+  isCatalogError,
+  getCatalogCode,
+} from './error-catalog';
+
+describe('defineErrorCatalog', () => {
+  const billing = defineErrorCatalog('billing', {
+    PAYMENT_DECLINED: {
+      status: 402,
+      message: 'Card declined',
+      why: 'The issuer rejected the charge',
+      fix: 'Try a different payment method',
+      link: 'https://docs.example.com/billing',
+    },
+    INSUFFICIENT_FUNDS: {
+      status: 402,
+      message: ({ available, required }: { available: number; required: number }) =>
+        `Insufficient funds: $${available} of $${required}`,
+      why: ({ required }: { available: number; required: number }) =>
+        `Needs $${required}`,
+    },
+    LEGACY: {
+      code: 'BILLING_LEGACY_42',
+      message: 'Legacy failure',
+    },
+  });
+
+  it('builds a structured error from a static entry', () => {
+    const err = billing.PAYMENT_DECLINED();
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toBe('Card declined');
+    expect(err.status).toBe(402);
+    expect(err.why).toBe('The issuer rejected the charge');
+    expect(err.fix).toBe('Try a different payment method');
+    expect(err.link).toBe('https://docs.example.com/billing');
+    expect(err.code).toBe('billing.PAYMENT_DECLINED');
+    expect(err.name).toBe('PAYMENT_DECLINED');
+  });
+
+  it('interpolates typed params in message and why', () => {
+    const err = billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });
+    expect(err.message).toBe('Insufficient funds: $5 of $100');
+    expect(err.why).toBe('Needs $100');
+  });
+
+  it('honors a custom code', () => {
+    const err = billing.LEGACY();
+    expect(err.code).toBe('BILLING_LEGACY_42');
+  });
+
+  it('exposes the code on the builder', () => {
+    expect(billing.PAYMENT_DECLINED.code).toBe('billing.PAYMENT_DECLINED');
+    expect(billing.LEGACY.code).toBe('BILLING_LEGACY_42');
+  });
+
+  it('matches its own errors and rejects others', () => {
+    const declined = billing.PAYMENT_DECLINED();
+    const funds = billing.INSUFFICIENT_FUNDS({ available: 1, required: 2 });
+    expect(billing.PAYMENT_DECLINED.match(declined)).toBe(true);
+    expect(billing.PAYMENT_DECLINED.match(funds)).toBe(false);
+    expect(billing.PAYMENT_DECLINED.match(new Error('nope'))).toBe(false);
+    expect(billing.PAYMENT_DECLINED.match(null)).toBe(false);
+  });
+
+  it('tags errors so isCatalogError / getCatalogCode work', () => {
+    const err = billing.PAYMENT_DECLINED();
+    expect(isCatalogError(err)).toBe(true);
+    expect(isCatalogError(new Error('plain'))).toBe(false);
+    expect(getCatalogCode(err)).toBe('billing.PAYMENT_DECLINED');
+    expect(getCatalogCode(new Error('plain'))).toBeUndefined();
+  });
+
+  it('passes cause, details, and internal through build options', () => {
+    const cause = new Error('stripe boom');
+    const err = billing.PAYMENT_DECLINED({
+      cause,
+      details: { attempt: 2 },
+      internal: { stripeId: 'ch_1' },
+    });
+    expect(err.cause).toBe(cause);
+    expect(err.details).toEqual({ attempt: 2 });
+    expect(err.internal).toEqual({ stripeId: 'ch_1' });
+  });
+
+  it('accepts options as the second arg for param entries', () => {
+    const cause = new Error('root');
+    const err = billing.INSUFFICIENT_FUNDS(
+      { available: 5, required: 100 },
+      { cause },
+    );
+    expect(err.message).toBe('Insufficient funds: $5 of $100');
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe('defineAuditCatalog', () => {
+  const audit = defineAuditCatalog('user', {
+    LOGIN: { message: 'User logged in' },
+    ROLE_CHANGED: {
+      severity: 'critical',
+      message: ({ role }: { role: string }) => `Role set to ${role}`,
+    },
+    DELETED: { action: 'user.account.deleted', severity: 'warn' },
+  });
+
+  it('produces typed action descriptors with defaults', () => {
+    const action = audit.LOGIN();
+    expect(action.action).toBe('user.LOGIN');
+    expect(action.severity).toBe('info');
+    expect(action.message).toBe('User logged in');
+  });
+
+  it('interpolates params and respects severity', () => {
+    const action = audit.ROLE_CHANGED({ role: 'admin' });
+    expect(action.action).toBe('user.ROLE_CHANGED');
+    expect(action.severity).toBe('critical');
+    expect(action.message).toBe('Role set to admin');
+  });
+
+  it('honors a custom action name', () => {
+    expect(audit.DELETED.action).toBe('user.account.deleted');
+    expect(audit.DELETED.severity).toBe('warn');
+    expect(audit.DELETED().message).toBeUndefined();
+  });
+});

package/src/error-catalog.ts

@@ -0,0 +1,259 @@
+/**
+ * Typed error and audit catalogs.
+ *
+ * Group related errors into one catalog and get a refactor-safe builder per
+ * code, with autocomplete at every call site and typed message parameters.
+ *
+ * @example
+ * ```typescript
+ * import { defineErrorCatalog } from 'autotel';
+ *
+ * export const billing = defineErrorCatalog('billing', {
+ *   PAYMENT_DECLINED: {
+ *     status: 402,
+ *     message: 'Card declined',
+ *     why: 'The issuer rejected the charge',
+ *     fix: 'Try a different payment method',
+ *   },
+ *   INSUFFICIENT_FUNDS: {
+ *     status: 402,
+ *     message: ({ available, required }: { available: number; required: number }) =>
+ *       `Insufficient funds: $${available} of $${required}`,
+ *   },
+ * });
+ *
+ * throw billing.PAYMENT_DECLINED({ cause: stripeError });
+ * throw billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });
+ *
+ * // In a catch block — refactor-safe, no magic strings:
+ * if (billing.PAYMENT_DECLINED.match(err)) { ... }
+ * ```
+ */
+
+import { createStructuredError, type StructuredError } from './structured-error';
+
+const catalogCodeKey = Symbol.for('autotel.catalog.code');
+
+/** Definition of a single error in a catalog. */
+export interface ErrorCatalogEntry {
+  /**
+   * Human-readable message. Use a function to interpolate typed parameters;
+   * the parameter type flows through to the call site.
+   */
+  message: string | ((params: never) => string);
+  /** HTTP status to surface to clients. */
+  status?: number;
+  /** Stable error code. Defaults to `${namespace}.${KEY}`. */
+  code?: string | number;
+  /** Why it happened. A function receives the same params as `message`. */
+  why?: string | ((params: never) => string);
+  /** What the caller should do next. */
+  fix?: string;
+  /** Docs or runbook link. */
+  link?: string;
+  /** Error name. Defaults to the catalog key. */
+  name?: string;
+}
+
+/** Per-call options passed alongside (or instead of) typed params. */
+export interface ErrorBuildOptions {
+  cause?: unknown;
+  details?: Record<string, unknown>;
+  /** Backend-only context. Never serialized to clients. */
+  internal?: Record<string, unknown>;
+}
+
+type ParamsOf<E> = E extends { message: (params: infer P) => string }
+  ? P
+  : E extends { why: (params: infer P) => string }
+    ? P
+    : void;
+
+type BuilderArgs<E extends ErrorCatalogEntry> = ParamsOf<E> extends void
+  ? [options?: ErrorBuildOptions]
+  : [params: ParamsOf<E>, options?: ErrorBuildOptions];
+
+/** A callable error factory produced by {@link defineErrorCatalog}. */
+export interface ErrorBuilder<E extends ErrorCatalogEntry> {
+  (...args: BuilderArgs<E>): StructuredError;
+  /** Stable code assigned to every error from this entry. */
+  readonly code: string | number;
+  /** True when `error` was produced by this catalog entry. */
+  match(error: unknown): boolean;
+}
+
+export type ErrorCatalog<T extends Record<string, ErrorCatalogEntry>> = {
+  readonly [K in keyof T]: ErrorBuilder<T[K]>;
+};
+
+function readCatalogCode(error: unknown): string | number | undefined {
+  if (error === null || typeof error !== 'object') return undefined;
+  return (error as Record<symbol, unknown>)[catalogCodeKey] as
+    | string
+    | number
+    | undefined;
+}
+
+/** True when `error` was produced by any autotel error catalog. */
+export function isCatalogError(error: unknown): error is StructuredError {
+  return readCatalogCode(error) !== undefined;
+}
+
+/** Returns the catalog code of `error`, or `undefined` if it has none. */
+export function getCatalogCode(error: unknown): string | number | undefined {
+  return readCatalogCode(error);
+}
+
+/**
+ * Define a typed error catalog. Returns an object whose keys are error
+ * builders. Each builder produces a {@link StructuredError} carrying the
+ * entry's message, status, code, why, fix, and link.
+ */
+export function defineErrorCatalog<
+  const T extends Record<string, ErrorCatalogEntry>,
+>(namespace: string, entries: T): ErrorCatalog<T> {
+  const catalog: Record<string, ErrorBuilder<ErrorCatalogEntry>> = {};
+
+  for (const [key, entry] of Object.entries(entries) as [
+    string,
+    ErrorCatalogEntry,
+  ][]) {
+    const code = entry.code ?? `${namespace}.${key}`;
+    const usesParams =
+      typeof entry.message === 'function' || typeof entry.why === 'function';
+
+    const builder = ((
+      paramsOrOptions?: unknown,
+      maybeOptions?: ErrorBuildOptions,
+    ): StructuredError => {
+      const params = usesParams ? paramsOrOptions : undefined;
+      const options = (
+        usesParams ? maybeOptions : paramsOrOptions
+      ) as ErrorBuildOptions | undefined;
+
+      const message =
+        typeof entry.message === 'function'
+          ? (entry.message as (p: unknown) => string)(params)
+          : entry.message;
+      const why =
+        typeof entry.why === 'function'
+          ? (entry.why as (p: unknown) => string)(params)
+          : entry.why;
+
+      const error = createStructuredError({
+        message,
+        name: entry.name ?? key,
+        code,
+        ...(entry.status === undefined ? {} : { status: entry.status }),
+        ...(why === undefined ? {} : { why }),
+        ...(entry.fix === undefined ? {} : { fix: entry.fix }),
+        ...(entry.link === undefined ? {} : { link: entry.link }),
+        ...(options?.cause === undefined ? {} : { cause: options.cause }),
+        ...(options?.details === undefined ? {} : { details: options.details }),
+        ...(options?.internal === undefined
+          ? {}
+          : { internal: options.internal }),
+      });
+
+      Object.defineProperty(error, catalogCodeKey, {
+        value: code,
+        enumerable: false,
+        writable: false,
+        configurable: true,
+      });
+
+      return error;
+    }) as ErrorBuilder<ErrorCatalogEntry>;
+
+    Object.defineProperty(builder, 'code', {
+      value: code,
+      enumerable: true,
+    });
+    Object.defineProperty(builder, 'match', {
+      value: (error: unknown): boolean => readCatalogCode(error) === code,
+      enumerable: false,
+    });
+
+    catalog[key] = builder;
+  }
+
+  return Object.freeze(catalog) as ErrorCatalog<T>;
+}
+
+/** Severity of an audit action. */
+export type AuditSeverity = 'info' | 'warn' | 'critical';
+
+/** Definition of a single action in an audit catalog. */
+export interface AuditCatalogEntry {
+  /** Human-readable description. Use a function for typed params. */
+  message?: string | ((params: never) => string);
+  /** Stable action name. Defaults to `${namespace}.${KEY}`. */
+  action?: string;
+  /** Severity of the action. Defaults to `'info'`. */
+  severity?: AuditSeverity;
+}
+
+/** A resolved audit action descriptor produced by an audit catalog. */
+export interface AuditAction {
+  readonly action: string;
+  readonly severity: AuditSeverity;
+  readonly message?: string;
+}
+
+type AuditDescriptorArgs<E extends AuditCatalogEntry> = ParamsOf<E> extends void
+  ? []
+  : [params: ParamsOf<E>];
+
+/** A callable audit-action descriptor produced by {@link defineAuditCatalog}. */
+export interface AuditDescriptor<E extends AuditCatalogEntry> {
+  (...args: AuditDescriptorArgs<E>): AuditAction;
+  readonly action: string;
+  readonly severity: AuditSeverity;
+}
+
+export type AuditCatalog<T extends Record<string, AuditCatalogEntry>> = {
+  readonly [K in keyof T]: AuditDescriptor<T[K]>;
+};
+
+/**
+ * Define a typed audit catalog. Returns typed action descriptors you can pass
+ * to `track()` or audit helpers without scattering magic strings.
+ */
+export function defineAuditCatalog<
+  const T extends Record<string, AuditCatalogEntry>,
+>(namespace: string, entries: T): AuditCatalog<T> {
+  const catalog: Record<string, AuditDescriptor<AuditCatalogEntry>> = {};
+
+  for (const [key, entry] of Object.entries(entries) as [
+    string,
+    AuditCatalogEntry,
+  ][]) {
+    const action = entry.action ?? `${namespace}.${key}`;
+    const severity: AuditSeverity = entry.severity ?? 'info';
+
+    const descriptor = ((params?: unknown): AuditAction => {
+      const message =
+        typeof entry.message === 'function'
+          ? (entry.message as (p: unknown) => string)(params)
+          : entry.message;
+      return Object.freeze({
+        action,
+        severity,
+        ...(message === undefined ? {} : { message }),
+      });
+    }) as AuditDescriptor<AuditCatalogEntry>;
+
+    Object.defineProperty(descriptor, 'action', {
+      value: action,
+      enumerable: true,
+    });
+    Object.defineProperty(descriptor, 'severity', {
+      value: severity,
+      enumerable: true,
+    });
+
+    catalog[key] = descriptor;
+  }
+
+  return Object.freeze(catalog) as AuditCatalog<T>;
+}

package/src/event-queue.ts

@@ -22,6 +22,7 @@ import type {
   EventSubscriber,
   EventAttributes,
   AutotelEventContext,
+  EventSchemaMetadata,
 } from './event-subscriber';
 import { getLogger } from './init';
 import { getConfig as getRuntimeConfig } from './config';
@@ -38,6 +39,8 @@ export interface EventData {
   _traceId?: string;
   /** Autotel context for trace correlation (passed to subscribers) */
   autotel?: AutotelEventContext;
+  /** Optional schema metadata for contract-aware subscribers. */
+  schema?: EventSchemaMetadata;
 }
 
 /**
@@ -591,6 +594,7 @@ export class EventQueue {
         try {
           await subscriber.trackEvent(event.name, event.attributes, {
             autotel: event.autotel,
+            schema: event.schema,
           });
           this.recordDelivered(event, subscriberName, startTime);
           return { subscriberName, success: true };

package/src/event-subscriber.ts

@@ -101,12 +101,27 @@ export interface AutotelEventContext {
   linked_trace_ids?: string[];
 }
 
+/**
+ * Optional machine-readable schema metadata attached to an event payload.
+ * Intended for contract-aware subscribers (e.g. architecture snapshot capture).
+ */
+export interface EventSchemaMetadata {
+  /** Schema source format used at the call site. */
+  source: 'zod';
+  /** JSON Schema representation of the payload contract. */
+  jsonSchema: unknown;
+  /** Stable schema hash for change detection and cache keys. */
+  hash: string;
+}
+
 /**
  * Options for event tracking methods
  */
 export interface EventTrackingOptions {
   /** Autotel trace context to include in the event */
   autotel?: AutotelEventContext;
+  /** Optional event payload schema metadata */
+  schema?: EventSchemaMetadata;
 }
 
 /**

package/src/functional.ts

@@ -210,7 +210,8 @@ function hasImmediateExecutionMark(fn: unknown): boolean {
  */
 export function markAsImmediate<F>(fn: F): F {
   if (typeof fn === 'function') {
-    (fn as unknown as ImmediateExecutionFlag)[IMMEDIATE_EXECUTION_SYMBOL] = true;
+    (fn as unknown as ImmediateExecutionFlag)[IMMEDIATE_EXECUTION_SYMBOL] =
+      true;
   }
   return fn;
 }