autotel 2.23.0 → 2.24.0

package/src/enrichers.ts

@@ -0,0 +1,145 @@
+type Headers = Record<string, string | string[] | undefined>;
+
+function get(headers: Headers, key: string): string | undefined {
+  const lower = key.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === lower) {
+      return Array.isArray(v) ? v[0] : v;
+    }
+  }
+  return undefined;
+}
+
+// --- User Agent ---
+
+export interface UserAgentAttributes {
+  'user_agent.raw': string;
+  'user_agent.browser'?: string;
+  'user_agent.os'?: string;
+  'user_agent.device'?: string;
+}
+
+const BROWSER_RE = /(Firefox|OPR|Edg|Chrome|Safari|MSIE|Trident)[\s/]?([\d.]*)/;
+const OS_RE =
+  /(Windows NT|Mac OS X|Linux|Android|iPhone OS|iPad|CrOS)[\s]?([\d._]*)/;
+
+function parseBrowser(ua: string): string | undefined {
+  const m = BROWSER_RE.exec(ua);
+  if (!m) return undefined;
+  const name =
+    m[1] === 'OPR'
+      ? 'Opera'
+      : m[1] === 'Edg'
+        ? 'Edge'
+        : m[1] === 'Trident'
+          ? 'IE'
+          : m[1];
+  return m[2] ? `${name} ${m[2]}` : name;
+}
+
+function parseOS(ua: string): string | undefined {
+  const m = OS_RE.exec(ua);
+  if (!m) return undefined;
+  const name =
+    m[1] === 'iPhone OS'
+      ? 'iOS'
+      : m[1] === 'Windows NT'
+        ? 'Windows'
+        : m[1] === 'Mac OS X'
+          ? 'macOS'
+          : m[1];
+  const ver = m[2]?.replaceAll('_', '.') || undefined;
+  return ver ? `${name} ${ver}` : name;
+}
+
+function parseDevice(ua: string): string | undefined {
+  if (/Mobi|Android.*Mobile|iPhone/.test(ua)) return 'mobile';
+  if (/iPad|Android(?!.*Mobile)|Tablet/.test(ua)) return 'tablet';
+  if (/Bot|Crawler|Spider|Lighthouse/i.test(ua)) return 'bot';
+  return 'desktop';
+}
+
+export function userAgent(headers: Headers): UserAgentAttributes | undefined {
+  const raw = get(headers, 'user-agent');
+  if (!raw) return undefined;
+
+  const attrs: UserAgentAttributes = { 'user_agent.raw': raw };
+  const browser = parseBrowser(raw);
+  if (browser) attrs['user_agent.browser'] = browser;
+  const os = parseOS(raw);
+  if (os) attrs['user_agent.os'] = os;
+  const device = parseDevice(raw);
+  if (device) attrs['user_agent.device'] = device;
+
+  return attrs;
+}
+
+// --- Geo ---
+
+export interface GeoAttributes {
+  'geo.country'?: string;
+  'geo.region'?: string;
+  'geo.city'?: string;
+  'geo.latitude'?: string;
+  'geo.longitude'?: string;
+}
+
+export function geo(headers: Headers): GeoAttributes | undefined {
+  const country =
+    get(headers, 'x-vercel-ip-country') ?? get(headers, 'cf-ipcountry');
+  const region = get(headers, 'x-vercel-ip-country-region');
+  const city = get(headers, 'x-vercel-ip-city');
+  const latitude = get(headers, 'x-vercel-ip-latitude');
+  const longitude = get(headers, 'x-vercel-ip-longitude');
+
+  if (!country && !region && !city && !latitude && !longitude) return undefined;
+
+  const attrs: GeoAttributes = {};
+  if (country) attrs['geo.country'] = country;
+  if (region) attrs['geo.region'] = region;
+  if (city) {
+    try {
+      attrs['geo.city'] = decodeURIComponent(city);
+    } catch {
+      attrs['geo.city'] = city;
+    }
+  }
+  if (latitude) attrs['geo.latitude'] = latitude;
+  if (longitude) attrs['geo.longitude'] = longitude;
+
+  return attrs;
+}
+
+// --- Request Size ---
+
+export interface RequestSizeAttributes {
+  'http.request.body.size'?: number;
+  'http.response.body.size'?: number;
+}
+
+const DIGITS_RE = /^\d+$/;
+
+function parseContentLength(value: string | undefined): number | undefined {
+  if (!value || !DIGITS_RE.test(value)) return undefined;
+  return Number(value);
+}
+
+export function requestSize(
+  requestHeaders: Headers,
+  responseHeaders?: Headers,
+): RequestSizeAttributes | undefined {
+  const reqLen = get(requestHeaders, 'content-length');
+  const resLen = responseHeaders
+    ? get(responseHeaders, 'content-length')
+    : undefined;
+
+  if (!reqLen && !resLen) return undefined;
+
+  const attrs: RequestSizeAttributes = {};
+  const reqBytes = parseContentLength(reqLen);
+  if (reqBytes !== undefined) attrs['http.request.body.size'] = reqBytes;
+  const resBytes = parseContentLength(resLen);
+  if (resBytes !== undefined) attrs['http.response.body.size'] = resBytes;
+
+  return Object.keys(attrs).length > 0 ? attrs : undefined;
+}

package/src/index.ts

@@ -68,6 +68,9 @@ export {
   type ValuePatternConfig,
 } from './attribute-redacting-processor';
 
+// String redaction utility
+export { createStringRedactor, type StringRedactor } from './redact-values';
+
 // Functional API (re-export for convenience)
 export type {
   TraceContext,
@@ -113,6 +116,7 @@ export { flush, shutdown } from './shutdown';
 // Request logger
 export {
   getRequestLogger,
+  runWithRequestContext,
   type RequestLogger,
   type RequestLogSnapshot,
   type RequestLoggerOptions,

package/src/init-redactor.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest';
+import { getStringRedactor } from './init';
+
+describe('getStringRedactor', () => {
+  it('returns null when no attributeRedactor configured', () => {
+    expect(getStringRedactor()).toBeNull();
+  });
+});

package/src/init.ts

@@ -36,6 +36,7 @@ import { OTLPMetricExporter as OTLPMetricExporterHTTP } from '@opentelemetry/exp
 import { OTLPTraceExporter as OTLPTraceExporterHTTP } from '@opentelemetry/exporter-trace-otlp-http';
 import type { PushMetricExporter } from '@opentelemetry/sdk-metrics';
 import type { LogRecordProcessor } from '@opentelemetry/sdk-logs';
+import { buildPostHogLogProcessors } from './posthog-logs';
 import { TailSamplingSpanProcessor } from './tail-sampling-processor';
 import { BaggageSpanProcessor } from './baggage-span-processor';
 import {
@@ -51,6 +52,7 @@ import {
   type AttributeRedactorConfig,
   type AttributeRedactorPreset,
 } from './attribute-redacting-processor';
+import { createStringRedactor, type StringRedactor } from './redact-values';
 import { PrettyConsoleExporter } from './pretty-console-exporter';
 import { resolveConfigFromEnv } from './env-config';
 import { loadYamlConfig } from './yaml-config';
@@ -409,6 +411,21 @@ export interface AutotelConfig {
    */
   logRecordProcessors?: LogRecordProcessor[];
 
+  /**
+   * PostHog integration - auto-configures OTLP log exporter.
+   *
+   * @example
+   * ```typescript
+   * init({
+   *   service: 'my-app',
+   *   posthog: { url: 'https://us.i.posthog.com/i/v1/logs?token=phc_xxx' }
+   * });
+   * ```
+   *
+   * Also reads from POSTHOG_LOGS_URL environment variable as fallback.
+   */
+  posthog?: { url: string };
+
   /** Additional resource attributes to merge with defaults. */
   resourceAttributes?: Attributes;
 
@@ -1004,6 +1021,7 @@ let warnedOnce = false;
 let logger: Logger = silentLogger; // Silent by default - no spam
 let validationConfig: Partial<ValidationConfig> | null = null;
 let eventsConfig: EventsConfig | null = null;
+let _stringRedactor: StringRedactor | null = null;
 
 /**
  * Resolve metrics flag with env var override support
@@ -1287,6 +1305,23 @@ export function init(cfg: AutotelConfig): void {
     );
   }
 
+  // Store string redactor for use by PostHog log/subscriber paths
+  if (mergedConfig.attributeRedactor) {
+    _stringRedactor = createStringRedactor(mergedConfig.attributeRedactor);
+  }
+
+  // Wire string redactor to subscribers that support it (e.g., PostHogSubscriber)
+  if (_stringRedactor && mergedConfig.subscribers) {
+    for (const subscriber of mergedConfig.subscribers) {
+      if (
+        'setStringRedactor' in subscriber &&
+        typeof (subscriber as any).setStringRedactor === 'function'
+      ) {
+        (subscriber as any).setStringRedactor(_stringRedactor);
+      }
+    }
+  }
+
   // Step 2: Wrap with SpanNameNormalizingProcessor (middle)
   // Normalizer runs in onStart(), so span names are normalized before any onEnd processing
   if (mergedConfig.spanNameNormalizer && spanProcessors.length > 0) {
@@ -1337,6 +1372,19 @@ export function init(cfg: AutotelConfig): void {
     logRecordProcessors = [...mergedConfig.logRecordProcessors];
   }
 
+  // PostHog OTLP logs integration
+  const posthogProcessors = buildPostHogLogProcessors(
+    mergedConfig.posthog,
+    _stringRedactor,
+  );
+  if (posthogProcessors.length > 0) {
+    if (!logRecordProcessors) {
+      logRecordProcessors = [];
+    }
+    logRecordProcessors.push(...posthogProcessors);
+    logger.info({}, '[autotel] PostHog OTLP logs configured');
+  }
+
   // Handle instrumentations: merge manual instrumentations with auto-instrumentations
   let finalInstrumentations: NodeSDKConfiguration['instrumentations'] =
     mergedConfig.instrumentations ? [...mergedConfig.instrumentations] : [];
@@ -1777,6 +1825,14 @@ function detectHostname(): string | undefined {
   }
 }
 
+/**
+ * Get the string redactor configured via init({ attributeRedactor }).
+ * Returns null if no redactor was configured.
+ */
+export function getStringRedactor(): StringRedactor | null {
+  return _stringRedactor;
+}
+
 /**
  * Get SDK instance (for shutdown)
  */

package/src/package-manifest.test.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = resolve(here, '../package.json');
+
+interface PackageJson {
+  bin?: Record<string, string>;
+  dependencies?: Record<string, string>;
+}
+
+describe('package manifest', () => {
+  it('declares runtime deps required by published bin scripts', () => {
+    const pkg = JSON.parse(
+      readFileSync(packageJsonPath, 'utf8'),
+    ) as PackageJson;
+
+    if (pkg.bin?.intent) {
+      expect(pkg.dependencies?.['@tanstack/intent']).toBeDefined();
+    }
+  });
+});

package/src/posthog-logs.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+const mockBatchLogRecordProcessor = vi.fn();
+const mockOTLPLogExporter = vi.fn();
+
+vi.mock('./node-require', () => ({
+  safeRequire: vi.fn((id: string) => {
+    if (id === '@opentelemetry/sdk-logs') {
+      return { BatchLogRecordProcessor: mockBatchLogRecordProcessor };
+    }
+    if (id === '@opentelemetry/exporter-logs-otlp-http') {
+      return { OTLPLogExporter: mockOTLPLogExporter };
+    }
+    return undefined;
+  }),
+}));
+
+import { buildPostHogLogProcessors } from './posthog-logs';
+
+describe('buildPostHogLogProcessors', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('returns processor when posthog.url is configured', () => {
+    const result = buildPostHogLogProcessors({
+      url: 'https://us.i.posthog.com/i/v1/logs?token=phc_test',
+    });
+    expect(result).toHaveLength(1);
+    expect(mockOTLPLogExporter).toHaveBeenCalledWith({
+      url: 'https://us.i.posthog.com/i/v1/logs?token=phc_test',
+    });
+    expect(mockBatchLogRecordProcessor).toHaveBeenCalled();
+  });
+
+  it('returns processor from POSTHOG_LOGS_URL env var', () => {
+    process.env.POSTHOG_LOGS_URL =
+      'https://eu.i.posthog.com/i/v1/logs?token=phc_eu';
+    const result = buildPostHogLogProcessors(undefined);
+    expect(result).toHaveLength(1);
+    expect(mockOTLPLogExporter).toHaveBeenCalledWith({
+      url: 'https://eu.i.posthog.com/i/v1/logs?token=phc_eu',
+    });
+  });
+
+  it('config.url takes precedence over env var', () => {
+    process.env.POSTHOG_LOGS_URL = 'https://env-url.com';
+    const result = buildPostHogLogProcessors({ url: 'https://config-url.com' });
+    expect(result).toHaveLength(1);
+    expect(mockOTLPLogExporter).toHaveBeenCalledWith({
+      url: 'https://config-url.com',
+    });
+  });
+
+  it('returns empty array when no url configured', () => {
+    const result = buildPostHogLogProcessors(undefined);
+    expect(result).toHaveLength(0);
+    expect(mockOTLPLogExporter).not.toHaveBeenCalled();
+  });
+
+  it('accepts a second stringRedactor parameter without error', () => {
+    const redactor = (s: string) => s.replace(/secret/g, '***');
+    const result = buildPostHogLogProcessors(
+      { url: 'https://us.i.posthog.com/i/v1/logs?token=phc_test' },
+      redactor,
+    );
+    expect(result).toHaveLength(1);
+  });
+
+  it('returns empty array when called with undefined, undefined', () => {
+    const result = buildPostHogLogProcessors(undefined, undefined);
+    expect(result).toHaveLength(0);
+  });
+
+  it('redacts string values inside attribute arrays before emitting', () => {
+    const wrappedOnEmit = vi.fn();
+    mockBatchLogRecordProcessor.mockImplementation(function () {
+      return {
+        onEmit: wrappedOnEmit,
+        shutdown: vi.fn().mockResolvedValue(undefined),
+        forceFlush: vi.fn().mockResolvedValue(undefined),
+      };
+    });
+
+    const [processor] = buildPostHogLogProcessors(
+      { url: 'https://us.i.posthog.com/i/v1/logs?token=phc_test' },
+      (value: string) => value.replace(/secret/g, '***'),
+    );
+
+    const record = {
+      body: 'ok',
+      attributes: {
+        tags: ['public', 'secret'],
+      },
+    };
+
+    processor.onEmit(record as any);
+
+    expect(wrappedOnEmit).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: {
+          tags: ['public', '***'],
+        },
+      }),
+      undefined,
+    );
+  });
+});

package/src/posthog-logs.ts

@@ -0,0 +1,77 @@
+import type { LogRecordProcessor } from '@opentelemetry/sdk-logs';
+import { safeRequire } from './node-require';
+import type { StringRedactor } from './redact-values';
+
+class RedactingLogRecordProcessor implements LogRecordProcessor {
+  constructor(
+    private wrapped: LogRecordProcessor,
+    private redact: StringRedactor,
+  ) {}
+
+  onEmit(logRecord: any, context?: any): void {
+    if (logRecord.body && typeof logRecord.body === 'string') {
+      logRecord.body = this.redact(logRecord.body);
+    }
+    if (logRecord.attributes) {
+      for (const [key, value] of Object.entries(logRecord.attributes)) {
+        if (typeof value === 'string') {
+          logRecord.attributes[key] = this.redact(value);
+        } else if (Array.isArray(value)) {
+          logRecord.attributes[key] = value.map((item: unknown) =>
+            typeof item === 'string' ? this.redact(item) : item,
+          );
+        }
+      }
+    }
+    this.wrapped.onEmit(logRecord, context);
+  }
+
+  shutdown(): Promise<void> {
+    return this.wrapped.shutdown();
+  }
+
+  forceFlush(): Promise<void> {
+    return this.wrapped.forceFlush();
+  }
+}
+
+export interface PostHogConfig {
+  /** OTLP logs endpoint URL (e.g., https://us.i.posthog.com/i/v1/logs?token=phc_xxx) */
+  url: string;
+}
+
+/**
+ * Build log record processors for PostHog OTLP logs integration.
+ *
+ * Resolution order:
+ * 1. config.url if provided
+ * 2. POSTHOG_LOGS_URL env var
+ * 3. Empty array (disabled)
+ */
+export function buildPostHogLogProcessors(
+  config: PostHogConfig | undefined,
+  stringRedactor?: StringRedactor | null,
+): LogRecordProcessor[] {
+  const url = config?.url || process.env.POSTHOG_LOGS_URL;
+  if (!url) return [];
+
+  const sdkLogs = safeRequire<{
+    BatchLogRecordProcessor: new (exporter: unknown) => LogRecordProcessor;
+  }>('@opentelemetry/sdk-logs');
+
+  const exporterModule = safeRequire<{
+    OTLPLogExporter: new (config: { url: string }) => unknown;
+  }>('@opentelemetry/exporter-logs-otlp-http');
+
+  if (!sdkLogs || !exporterModule) return [];
+
+  const exporter = new exporterModule.OTLPLogExporter({ url });
+  let processor: LogRecordProcessor = new sdkLogs.BatchLogRecordProcessor(
+    exporter,
+  );
+  if (stringRedactor) {
+    processor = new RedactingLogRecordProcessor(processor, stringRedactor);
+  }
+
+  return [processor];
+}

package/src/redact-values.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createStringRedactor } from './redact-values';
+import type { StringRedactor } from './redact-values';
+
+describe('createStringRedactor', () => {
+  describe('default preset', () => {
+    let redact: StringRedactor;
+
+    beforeEach(() => {
+      redact = createStringRedactor('default');
+    });
+
+    it('redacts emails', () => {
+      expect(redact('Contact user@example.com for info')).toBe(
+        'Contact [REDACTED] for info',
+      );
+    });
+
+    it('redacts phone numbers', () => {
+      expect(redact('Call 555-123-4567 now')).toBe('Call [REDACTED] now');
+    });
+
+    it('redacts credit card numbers', () => {
+      expect(redact('Card: 4111-1111-1111-1111')).toBe('Card: [REDACTED]');
+    });
+
+    it('returns input unchanged when no patterns match', () => {
+      expect(redact('hello world')).toBe('hello world');
+    });
+  });
+
+  describe('strict preset', () => {
+    let redact: StringRedactor;
+
+    beforeEach(() => {
+      redact = createStringRedactor('strict');
+    });
+
+    it('redacts JWTs', () => {
+      const jwt =
+        'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.abc123_-def';
+      expect(redact(`Token: ${jwt}`)).toBe('Token: [REDACTED]');
+    });
+
+    it('redacts bearer tokens', () => {
+      expect(redact('Authorization: Bearer abc123.xyz')).toBe(
+        'Authorization: [REDACTED]',
+      );
+    });
+  });
+
+  describe('custom config', () => {
+    it('accepts custom config with custom patterns', () => {
+      const redact = createStringRedactor({
+        valuePatterns: [{ name: 'customId', pattern: /CUST-\d{8}/g }],
+        replacement: '***',
+      });
+      expect(redact('Customer CUST-12345678 logged in')).toBe(
+        'Customer *** logged in',
+      );
+    });
+
+    it('uses custom replacement string', () => {
+      const redact = createStringRedactor({
+        valuePatterns: [
+          {
+            name: 'email',
+            pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/gi,
+          },
+        ],
+        replacement: '<HIDDEN>',
+      });
+      expect(redact('Email: test@example.com')).toBe('Email: <HIDDEN>');
+    });
+  });
+});

package/src/redact-values.ts

@@ -0,0 +1,27 @@
+/** Standalone string redaction for use outside the span processor pipeline. */
+
+import {
+  REDACTOR_PRESETS,
+  type AttributeRedactorConfig,
+  type AttributeRedactorPreset,
+  type ValuePatternConfig,
+} from './attribute-redacting-processor';
+
+export type StringRedactor = (value: string) => string;
+export function createStringRedactor(
+  config: AttributeRedactorConfig | AttributeRedactorPreset,
+): StringRedactor {
+  const resolved =
+    typeof config === 'string' ? REDACTOR_PRESETS[config] : config;
+  const valuePatterns: ValuePatternConfig[] = resolved.valuePatterns ?? [];
+  const defaultReplacement = resolved.replacement ?? '[REDACTED]';
+
+  return (value: string): string => {
+    let result = value;
+    for (const { pattern, replacement } of valuePatterns) {
+      pattern.lastIndex = 0;
+      result = result.replaceAll(pattern, replacement ?? defaultReplacement);
+    }
+    return result;
+  };
+}

package/src/request-logger.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { getRequestLogger } from './request-logger';
+import { getRequestLogger, runWithRequestContext } from './request-logger';
 import type { TraceContext } from './trace-context';
 
 function createMockContext(): TraceContext {
@@ -121,4 +121,17 @@ describe('getRequestLogger', () => {
     await new Promise((resolve) => setImmediate(resolve));
     expect(onEmit).toHaveBeenCalledWith(snapshot);
   });
+
+  it('resolves context from AsyncLocalStorage when no args given', () => {
+    const ctx = createMockContext();
+
+    runWithRequestContext(ctx, () => {
+      const log = getRequestLogger();
+      log.set({ user: { id: 'als-user' } });
+
+      expect(ctx.setAttributes).toHaveBeenCalledWith({
+        'user.id': 'als-user',
+      });
+    });
+  });
 });

package/src/request-logger.ts

@@ -1,9 +1,16 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { trace as otelTrace } from '@opentelemetry/api';
 import type { TraceContext } from './trace-context';
 import { createTraceContext } from './trace-context';
 import { recordStructuredError } from './structured-error';
 import { flattenToAttributes } from './flatten-attributes';
 
+const requestContextStore = new AsyncLocalStorage<TraceContext>();
+
+export function runWithRequestContext<T>(ctx: TraceContext, fn: () => T): T {
+  return requestContextStore.run(ctx, fn);
+}
+
 export interface RequestLogger {
   set(fields: Record<string, unknown>): void;
   info(message: string, fields?: Record<string, unknown>): void;
@@ -29,10 +36,13 @@ export interface RequestLoggerOptions {
 function resolveContext(ctx?: TraceContext): TraceContext {
   if (ctx) return ctx;
 
+  const stored = requestContextStore.getStore();
+  if (stored) return stored;
+
   const span = otelTrace.getActiveSpan();
   if (!span) {
     throw new Error(
-      '[autotel] getRequestLogger() requires an active span. Wrap your handler with trace().',
+      '[autotel] getRequestLogger() requires an active span or runWithRequestContext(). Wrap your handler with trace() or use runWithRequestContext().',
     );
   }
   return createTraceContext(span);

package/src/structured-error.test.ts

@@ -27,6 +27,36 @@ describe('structured-error helpers', () => {
     expect(err.details).toEqual({ retryable: false, provider: 'stripe' });
   });
 
+  it('toString() renders a human-readable diagnostic summary', () => {
+    const err = createStructuredError({
+      message: 'Payment failed',
+      why: 'Card declined by issuer',
+      fix: 'Use a different card',
+      link: 'https://docs.example.com/errors/card-declined',
+      code: 'PAYMENT_DECLINED',
+      status: 402,
+      cause: new Error('upstream timeout'),
+    });
+
+    const output = err.toString();
+    expect(output).toBe(
+      [
+        'StructuredError: Payment failed',
+        '  Why: Card declined by issuer',
+        '  Fix: Use a different card',
+        '  Link: https://docs.example.com/errors/card-declined',
+        '  Code: PAYMENT_DECLINED',
+        '  Status: 402',
+        '  Caused by: Error: upstream timeout',
+      ].join('\n'),
+    );
+  });
+
+  it('toString() omits undefined fields', () => {
+    const err = createStructuredError({ message: 'Something broke' });
+    expect(err.toString()).toBe('StructuredError: Something broke');
+  });
+
   it('extracts canonical attributes for span logging', () => {
     const err = createStructuredError({
       message: 'Export failed',