autotel 2.22.0 → 2.23.0

package/src/parse-error.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { createStructuredError } from './structured-error';
+import { parseError } from './parse-error';
+
+describe('parseError', () => {
+  it('parses structured errors with why/fix/link', () => {
+    const err = createStructuredError({
+      message: 'Payment failed',
+      status: 402,
+      why: 'Card declined',
+      fix: 'Use another card',
+      link: 'https://docs.example.com/payment-errors',
+      code: 'PAYMENT_DECLINED',
+    });
+
+    const parsed = parseError(err);
+    expect(parsed).toMatchObject({
+      message: 'Payment failed',
+      status: 402,
+      why: 'Card declined',
+      fix: 'Use another card',
+      link: 'https://docs.example.com/payment-errors',
+      code: 'PAYMENT_DECLINED',
+      raw: err,
+    });
+  });
+
+  it('parses fetch-like nested data payloads', () => {
+    const fetchLikeError = {
+      message: 'Request failed',
+      statusCode: 409,
+      data: {
+        statusText: 'Conflict',
+        data: {
+          why: 'Order already exists',
+          fix: 'Use idempotency key',
+          link: 'https://docs.example.com/idempotency',
+          code: 'ORDER_EXISTS',
+        },
+      },
+    };
+
+    const parsed = parseError(fetchLikeError);
+    expect(parsed).toMatchObject({
+      message: 'Conflict',
+      status: 409,
+      why: 'Order already exists',
+      fix: 'Use idempotency key',
+      link: 'https://docs.example.com/idempotency',
+      code: 'ORDER_EXISTS',
+      raw: fetchLikeError,
+    });
+  });
+
+  it('preserves details from structured errors', () => {
+    const err = createStructuredError({
+      message: 'Export failed',
+      status: 500,
+      details: { retryable: true, provider: 'stripe' },
+    });
+
+    const parsed = parseError(err);
+    expect(parsed.details).toEqual({ retryable: true, provider: 'stripe' });
+  });
+
+  it('falls back for unknown values', () => {
+    expect(parseError('boom')).toMatchObject({
+      message: 'boom',
+      status: 500,
+      raw: 'boom',
+    });
+  });
+});

package/src/parse-error.ts

@@ -0,0 +1,112 @@
+import type { StructuredError } from './structured-error';
+
+export interface ParsedError {
+  message: string;
+  status: number;
+  why?: string;
+  fix?: string;
+  link?: string;
+  code?: string | number;
+  details?: Record<string, unknown>;
+  raw: unknown;
+}
+
+type ErrorLike = {
+  message?: unknown;
+  status?: unknown;
+  statusCode?: unknown;
+  data?: unknown;
+  code?: unknown;
+  why?: unknown;
+  fix?: unknown;
+  link?: unknown;
+  details?: unknown;
+};
+
+function toStatus(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  return undefined;
+}
+
+function pickString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function pickCode(value: unknown): string | number | undefined {
+  if (typeof value === 'string' || typeof value === 'number') return value;
+  return undefined;
+}
+
+function pickDetails(value: unknown): Record<string, unknown> | undefined {
+  if (value && typeof value === 'object' && value.constructor === Object) {
+    return value as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+export function parseError(error: unknown): ParsedError {
+  if (error instanceof Error) {
+    const structured = error as StructuredError;
+    return {
+      message: error.message || 'An error occurred',
+      status: toStatus(structured.status) ?? 500,
+      why: pickString(structured.why),
+      fix: pickString(structured.fix),
+      link: pickString(structured.link),
+      code: pickCode(structured.code),
+      details: pickDetails(structured.details),
+      raw: error,
+    };
+  }
+
+  if (error && typeof error === 'object') {
+    const err = error as ErrorLike;
+    const data =
+      err.data && typeof err.data === 'object'
+        ? (err.data as Record<string, unknown>)
+        : undefined;
+    const nested =
+      data?.data && typeof data.data === 'object'
+        ? (data.data as Record<string, unknown>)
+        : undefined;
+    const payload = nested ?? data;
+
+    const message =
+      pickString(data?.statusText) ||
+      pickString(data?.statusMessage) ||
+      pickString(data?.message) ||
+      pickString(payload?.statusText) ||
+      pickString(payload?.statusMessage) ||
+      pickString(payload?.message) ||
+      pickString(err.message) ||
+      'An error occurred';
+
+    const status =
+      toStatus(payload?.status) ||
+      toStatus(payload?.statusCode) ||
+      toStatus(err.status) ||
+      toStatus(err.statusCode) ||
+      500;
+
+    return {
+      message,
+      status,
+      why: pickString(payload?.why) || pickString(err.why),
+      fix: pickString(payload?.fix) || pickString(err.fix),
+      link: pickString(payload?.link) || pickString(err.link),
+      code: pickCode(payload?.code) || pickCode(err.code),
+      details: pickDetails(payload?.details) || pickDetails(err.details),
+      raw: error,
+    };
+  }
+
+  return {
+    message: String(error),
+    status: 500,
+    raw: error,
+  };
+}

package/src/pretty-log-formatter.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it, vi } from 'vitest';
+import { formatDuration, formatPrettyLogLine } from './pretty-log-formatter';
+import type { CanonicalLogLineEvent } from './processors/canonical-log-line-processor';
+
+describe('formatDuration', () => {
+  it('formats sub-second durations as ms', () => {
+    expect(formatDuration(0)).toBe('0ms');
+    expect(formatDuration(45)).toBe('45ms');
+    expect(formatDuration(999)).toBe('999ms');
+  });
+
+  it('formats seconds with one decimal under 10s', () => {
+    expect(formatDuration(1234)).toBe('1.2s');
+    expect(formatDuration(9500)).toBe('9.5s');
+  });
+
+  it('rounds seconds above 10s', () => {
+    expect(formatDuration(12345)).toBe('12s');
+  });
+
+  it('formats minutes', () => {
+    expect(formatDuration(65000)).toBe('1m 5s');
+    expect(formatDuration(120000)).toBe('2m');
+  });
+});
+
+describe('formatPrettyLogLine', () => {
+  const originalEnv = process.env.NO_COLOR;
+
+  beforeEach(() => {
+    process.env.NO_COLOR = '1';
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.NO_COLOR;
+    } else {
+      process.env.NO_COLOR = originalEnv;
+    }
+  });
+
+  it('formats a basic request line', () => {
+    const ctx: CanonicalLogLineEvent = {
+      span: {} as any,
+      level: 'info',
+      message: '[checkout] Request completed',
+      event: {
+        timestamp: '2025-01-24T16:45:31.060Z',
+        'service.name': 'my-app',
+        'http.request.method': 'GET',
+        'http.route': '/api/checkout',
+        'http.response.status_code': 200,
+        duration_ms: 234,
+        status_code: 0,
+        operation: 'checkout',
+        traceId: 'abc123',
+        spanId: 'def456',
+        correlationId: 'abc1',
+      },
+    };
+
+    const output = formatPrettyLogLine(ctx);
+    expect(output).toContain('INFO');
+    expect(output).toContain('[my-app]');
+    expect(output).toContain('GET');
+    expect(output).toContain('/api/checkout');
+    expect(output).toContain('200');
+    expect(output).toContain('234ms');
+  });
+
+  it('includes context attributes as tree', () => {
+    const ctx: CanonicalLogLineEvent = {
+      span: {} as any,
+      level: 'info',
+      message: 'Request completed',
+      event: {
+        timestamp: '2025-01-24T16:45:31.060Z',
+        duration_ms: 100,
+        status_code: 0,
+        operation: 'checkout',
+        traceId: 'abc',
+        spanId: 'def',
+        correlationId: 'abc',
+        'user.id': '123',
+        'user.plan': 'premium',
+        'cart.items': 3,
+      },
+    };
+
+    const output = formatPrettyLogLine(ctx);
+    expect(output).toContain('user');
+    expect(output).toContain('id=123');
+    expect(output).toContain('plan=premium');
+    expect(output).toContain('cart');
+    expect(output).toContain('items');
+  });
+
+  it('skips internal telemetry attributes', () => {
+    const ctx: CanonicalLogLineEvent = {
+      span: {} as any,
+      level: 'info',
+      message: 'Request completed',
+      event: {
+        timestamp: '2025-01-24T16:45:31.060Z',
+        duration_ms: 50,
+        status_code: 0,
+        operation: 'test',
+        traceId: 'abc',
+        spanId: 'def',
+        correlationId: 'abc',
+        'telemetry.sdk.name': 'autotel',
+        'otel.scope.name': 'my-scope',
+        'service.name': 'my-app',
+        custom_field: 'visible',
+      },
+    };
+
+    const output = formatPrettyLogLine(ctx);
+    expect(output).not.toContain('telemetry.sdk.name');
+    expect(output).not.toContain('otel.scope.name');
+    expect(output).toContain('custom_field');
+  });
+});

package/src/pretty-log-formatter.ts

@@ -0,0 +1,210 @@
+import type { CanonicalLogLineEvent } from './processors/canonical-log-line-processor';
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const GRAY = '\x1b[90m';
+
+const LEVEL_COLORS: Record<string, string> = {
+  debug: GRAY,
+  info: GREEN,
+  warn: YELLOW,
+  error: RED,
+};
+
+/** Internal OTel attributes to skip in pretty output. */
+const SKIP_PREFIXES = [
+  'telemetry.',
+  'otel.',
+  'process.',
+  'os.',
+  'host.',
+  'service.',
+  'autotel.',
+];
+
+const SKIP_KEYS = new Set([
+  'operation',
+  'traceId',
+  'spanId',
+  'correlationId',
+  'duration_ms',
+  'duration',
+  'status_code',
+  'status_message',
+  'timestamp',
+  'http.request.method',
+  'url.path',
+  'http.route',
+  'http.response.status_code',
+]);
+
+function useColor(): boolean {
+  if (typeof process !== 'undefined') {
+    if (process.env.NO_COLOR) return false;
+    if (process.env.FORCE_COLOR) return true;
+    if (process.stdout?.isTTY) return true;
+  }
+  return false;
+}
+
+function c(color: string, text: string): string {
+  return useColor() ? `${color}${text}${RESET}` : text;
+}
+
+/**
+ * Format milliseconds into a human-readable duration string.
+ *
+ * @example
+ * formatDuration(45)     // "45ms"
+ * formatDuration(1234)   // "1.2s"
+ * formatDuration(65000)  // "1m 5s"
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  if (ms < 60_000) {
+    const seconds = ms / 1000;
+    return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+  }
+  const minutes = Math.floor(ms / 60_000);
+  const seconds = Math.round((ms % 60_000) / 1000);
+  return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+}
+
+function formatTime(iso: string): string {
+  try {
+    const d = new Date(iso);
+    return d.toLocaleTimeString('en-GB', { hour12: false });
+  } catch {
+    return iso.slice(11, 19);
+  }
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean')
+    return String(value);
+  if (value == null) return '';
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Group flat dot-notation attributes into a nested tree for pretty display.
+ * e.g. { 'user.id': '1', 'user.plan': 'pro' } → { user: { id: '1', plan: 'pro' } }
+ */
+function groupAttributes(
+  event: Record<string, unknown>,
+): Record<string, unknown> {
+  const tree: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(event)) {
+    if (SKIP_KEYS.has(key)) continue;
+    if (SKIP_PREFIXES.some((p) => key.startsWith(p))) continue;
+    if (value == null || value === '') continue;
+
+    const parts = key.split('.');
+    if (parts.length === 1) {
+      tree[key] = value;
+    } else {
+      let current = tree;
+      for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i]!;
+        if (!(part in current) || typeof current[part] !== 'object') {
+          current[part] = {};
+        }
+        current = current[part] as Record<string, unknown>;
+      }
+      current[parts[parts.length - 1]!] = value;
+    }
+  }
+
+  return tree;
+}
+
+function renderTree(
+  obj: Record<string, unknown>,
+  indent: string,
+  isLast: boolean[],
+): string[] {
+  const lines: string[] = [];
+  const entries = Object.entries(obj);
+
+  entries.forEach(([key, value], idx) => {
+    const last = idx === entries.length - 1;
+    const connector = last ? '\u2514\u2500' : '\u251c\u2500';
+    const prefix = indent + connector + ' ';
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const nested = value as Record<string, unknown>;
+      const flatValues = Object.entries(nested).filter(
+        ([, v]) => typeof v !== 'object' || v === null,
+      );
+      const nestedObjs = Object.entries(nested).filter(
+        ([, v]) => typeof v === 'object' && v !== null && !Array.isArray(v),
+      );
+
+      if (nestedObjs.length === 0) {
+        const inline = flatValues
+          .map(([k, v]) => `${c(CYAN, k)}=${formatValue(v)}`)
+          .join(' ');
+        lines.push(`${prefix}${c(BOLD, key)}: ${inline}`);
+      } else {
+        lines.push(`${prefix}${c(BOLD, key)}:`);
+        const nextIndent = indent + (last ? '   ' : '\u2502  ');
+        lines.push(...renderTree(nested, nextIndent, [...isLast, last]));
+      }
+    } else {
+      lines.push(`${prefix}${c(CYAN, key)}: ${c(DIM, formatValue(value))}`);
+    }
+  });
+
+  return lines;
+}
+
+/**
+ * Format a canonical log line event as a pretty tree for development output.
+ */
+export function formatPrettyLogLine(ctx: CanonicalLogLineEvent): string {
+  const { event, level, message } = ctx;
+
+  const timestamp = formatTime(String(event.timestamp ?? ''));
+  const service = event['service.name'] || event.service || '';
+  const method = event['http.request.method'] || '';
+  const path = event['http.route'] || event['url.path'] || '';
+  const status = event['http.response.status_code'] || event.status_code || '';
+  const durationMs = Number(event.duration_ms ?? 0);
+  const duration = formatDuration(durationMs);
+
+  const levelColor = LEVEL_COLORS[level] ?? '';
+  const levelStr = c(levelColor, level.toUpperCase().padEnd(5));
+
+  const parts = [c(DIM, timestamp), levelStr];
+  if (service) parts.push(c(DIM, `[${service}]`));
+  if (method) parts.push(c(BOLD, String(method)));
+  if (path) parts.push(String(path));
+  if (status) {
+    const statusNum = Number(status);
+    const statusColor =
+      statusNum >= 500 ? RED : statusNum >= 400 ? YELLOW : GREEN;
+    parts.push(c(statusColor, String(status)));
+  }
+  parts.push(c(DIM, `in ${duration}`));
+
+  const header = parts.join(' ');
+
+  const tree = groupAttributes(event);
+  if (Object.keys(tree).length === 0) {
+    return header;
+  }
+
+  const treeLines = renderTree(tree, '  ', []);
+  return [header, ...treeLines].join('\n');
+}