autotel 4.1.0 → 4.2.0

package/src/structured-error.test.ts

@@ -1,191 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import type { Span, SpanContext } from '@opentelemetry/api';
-import {
-  createStructuredError,
-  getStructuredErrorAttributes,
-  recordStructuredError,
-} from './structured-error';
-import { createTraceContext, type TraceContext } from './trace-context';
-
-function createFakeSpan(): {
-  span: Span;
-  recordException: ReturnType<typeof vi.fn>;
-  setStatus: ReturnType<typeof vi.fn>;
-  setAttributes: ReturnType<typeof vi.fn>;
-} {
-  const recordException = vi.fn();
-  const setStatus = vi.fn();
-  const setAttributes = vi.fn();
-  const spanContext: SpanContext = {
-    traceId: '0123456789abcdef0123456789abcdef',
-    spanId: '0123456789abcdef',
-    traceFlags: 1,
-  };
-  const span = {
-    spanContext: () => spanContext,
-    setAttribute: vi.fn(),
-    setAttributes,
-    setStatus,
-    recordException,
-    addEvent: vi.fn(),
-    addLink: vi.fn(),
-    addLinks: vi.fn(),
-    updateName: vi.fn(),
-    isRecording: () => true,
-    end: vi.fn(),
-  } as unknown as Span;
-  return { span, recordException, setStatus, setAttributes };
-}
-
-describe('structured-error helpers', () => {
-  it('creates an error with structured diagnostic fields', () => {
-    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,
-      details: { retryable: false, provider: 'stripe' },
-    });
-
-    expect(err.message).toBe('Payment failed');
-    expect(err.why).toBe('Card declined by issuer');
-    expect(err.fix).toBe('Use a different card');
-    expect(err.link).toBe('https://docs.example.com/errors/card-declined');
-    expect(err.code).toBe('PAYMENT_DECLINED');
-    expect(err.status).toBe(402);
-    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',
-      why: 'Template not found',
-      fix: 'Upload template and retry',
-      details: { export: { format: 'pdf' } },
-    });
-
-    const attrs = getStructuredErrorAttributes(err);
-    expect(attrs).toMatchObject({
-      'error.type': 'StructuredError',
-      'error.message': 'Export failed',
-      'error.why': 'Template not found',
-      'error.fix': 'Upload template and retry',
-      'error.details.export.format': 'pdf',
-    });
-  });
-
-  it('records structured error onto trace context', () => {
-    const ctx = {
-      recordException: vi.fn(),
-      setStatus: vi.fn(),
-      setAttributes: vi.fn(),
-    } as unknown as TraceContext;
-
-    const err = createStructuredError({
-      message: 'Checkout failed',
-      why: 'Inventory mismatch',
-      fix: 'Re-sync inventory and retry',
-    });
-
-    recordStructuredError(ctx, err);
-
-    expect(ctx.recordException).toHaveBeenCalledWith(err);
-    expect(ctx.setStatus).toHaveBeenCalledWith({
-      code: 2,
-      message: 'Checkout failed',
-    });
-    expect(ctx.setAttributes).toHaveBeenCalledWith(
-      expect.objectContaining({
-        'error.message': 'Checkout failed',
-        'error.why': 'Inventory mismatch',
-        'error.fix': 'Re-sync inventory and retry',
-      }),
-    );
-  });
-});
-
-describe('ctx.recordError', () => {
-  it('records a structured error onto the underlying span', () => {
-    const { span, recordException, setStatus, setAttributes } =
-      createFakeSpan();
-    const ctx = createTraceContext(span);
-    const err = createStructuredError({
-      message: 'Order failed',
-      why: 'Inventory unavailable',
-      fix: 'Retry after restock',
-    });
-
-    ctx.recordError(err);
-
-    expect(recordException).toHaveBeenCalledWith(err);
-    expect(setStatus).toHaveBeenCalledWith({
-      code: 2,
-      message: 'Order failed',
-    });
-    expect(setAttributes).toHaveBeenCalledWith(
-      expect.objectContaining({
-        'error.message': 'Order failed',
-        'error.why': 'Inventory unavailable',
-        'error.fix': 'Retry after restock',
-      }),
-    );
-  });
-
-  it('coerces non-Error values to Error so it is safe in catch blocks', () => {
-    const { span, recordException, setStatus, setAttributes } =
-      createFakeSpan();
-    const ctx = createTraceContext(span);
-
-    ctx.recordError('boom');
-
-    expect(recordException).toHaveBeenCalledTimes(1);
-    const recorded = recordException.mock.calls[0][0];
-    expect(recorded).toBeInstanceOf(Error);
-    expect(recorded.message).toBe('boom');
-    expect(setStatus).toHaveBeenCalledWith({ code: 2, message: 'boom' });
-    expect(setAttributes).toHaveBeenCalled();
-  });
-});
-
-describe('ctx.track', () => {
-  it('exposes track on the trace context as the ergonomic replacement for ctx.addEvent', () => {
-    const { span } = createFakeSpan();
-    const ctx = createTraceContext(span);
-
-    expect(typeof ctx.track).toBe('function');
-    // Smoke test — should not throw without init() (track is a no-op when no queue is configured)
-    expect(() => ctx.track('test.event', { foo: 'bar' })).not.toThrow();
-  });
-});

package/src/structured-error.ts

@@ -1,157 +0,0 @@
-import { SpanStatusCode } from '@opentelemetry/api';
-import type { AttributeValue, TraceContext } from './trace-context';
-import { flattenToAttributes } from './flatten-attributes';
-
-const internalKey = Symbol.for('autotel.error.internal');
-
-export interface StructuredErrorInput {
-  message: string;
-  why?: string;
-  fix?: string;
-  link?: string;
-  code?: string | number;
-  status?: number;
-  cause?: unknown;
-  details?: Record<string, unknown>;
-  name?: string;
-  /** Backend-only context. Omitted from toJSON() and never serialized to clients. */
-  internal?: Record<string, unknown>;
-}
-
-export interface StructuredError extends Error {
-  why?: string;
-  fix?: string;
-  link?: string;
-  code?: string | number;
-  status?: number;
-  details?: Record<string, unknown>;
-  /** Backend-only context. Omitted from toJSON() and never serialized to clients. */
-  readonly internal?: Record<string, unknown>;
-}
-
-export function createStructuredError(
-  input: StructuredErrorInput,
-): StructuredError {
-  const error = new Error(input.message, {
-    cause: input.cause,
-  }) as StructuredError;
-
-  error.name = input.name ?? 'StructuredError';
-  if (input.why !== undefined) error.why = input.why;
-  if (input.fix !== undefined) error.fix = input.fix;
-  if (input.link !== undefined) error.link = input.link;
-  if (input.code !== undefined) error.code = input.code;
-  if (input.status !== undefined) error.status = input.status;
-  if (input.details !== undefined) error.details = input.details;
-
-  if (input.internal !== undefined) {
-    Object.defineProperty(error, internalKey, {
-      value: input.internal,
-      enumerable: false,
-      writable: false,
-      configurable: true,
-    });
-  }
-
-  Object.defineProperty(error, 'internal', {
-    get() {
-      return (
-        this as StructuredError & { [internalKey]?: Record<string, unknown> }
-      )[internalKey];
-    },
-    enumerable: false,
-    configurable: true,
-  });
-
-  error.toString = () => {
-    const lines = [`${error.name}: ${error.message}`];
-    if (error.why) lines.push(`  Why: ${error.why}`);
-    if (error.fix) lines.push(`  Fix: ${error.fix}`);
-    if (error.link) lines.push(`  Link: ${error.link}`);
-    if (error.code !== undefined) lines.push(`  Code: ${error.code}`);
-    if (error.status !== undefined) lines.push(`  Status: ${error.status}`);
-    if (error.cause) {
-      const cause = error.cause as Error;
-      lines.push(`  Caused by: ${cause.name}: ${cause.message}`);
-    }
-    return lines.join('\n');
-  };
-
-  return error;
-}
-
-export function structuredErrorToJSON(
-  error: StructuredError,
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {
-    name: error.name,
-    message: error.message,
-  };
-
-  if (error.status !== undefined) result.status = error.status;
-  if (error.why || error.fix || error.link) {
-    result.data = {
-      ...(error.why && { why: error.why }),
-      ...(error.fix && { fix: error.fix }),
-      ...(error.link && { link: error.link }),
-    };
-  }
-  if (error.code !== undefined) result.code = error.code;
-  if (error.details) result.details = error.details;
-  if (error.cause instanceof Error) {
-    result.cause = { name: error.cause.name, message: error.cause.message };
-  }
-
-  return result;
-}
-
-export function getStructuredErrorAttributes(
-  error: Error,
-): Record<string, AttributeValue> {
-  const structured = error as StructuredError;
-  const attributes: Record<string, AttributeValue> = {
-    'error.type': error.name || 'Error',
-    'error.message': error.message,
-  };
-
-  if (error.stack) attributes['error.stack'] = error.stack;
-  if (structured.why) attributes['error.why'] = structured.why;
-  if (structured.fix) attributes['error.fix'] = structured.fix;
-  if (structured.link) attributes['error.link'] = structured.link;
-  if (structured.code !== undefined) {
-    attributes['error.code'] =
-      typeof structured.code === 'string'
-        ? structured.code
-        : String(structured.code);
-  }
-  if (structured.status !== undefined) {
-    attributes['error.status'] = structured.status;
-  }
-  if (structured.details) {
-    Object.assign(
-      attributes,
-      flattenToAttributes(structured.details, 'error.details'),
-    );
-  }
-
-  return attributes;
-}
-
-export function recordStructuredError(
-  ctx: Pick<TraceContext, 'setAttributes' | 'setStatus'>,
-  error: Error,
-): void {
-  const maybeRecordException = (
-    ctx as unknown as {
-      recordException?: (e: Error) => void;
-    }
-  ).recordException;
-  if (typeof maybeRecordException === 'function') {
-    maybeRecordException(error);
-  }
-  ctx.setStatus({
-    code: SpanStatusCode.ERROR,
-    message: error.message,
-  });
-  ctx.setAttributes(getStructuredErrorAttributes(error));
-}

package/src/stub.integration.test.ts

@@ -1,361 +0,0 @@
-/**
- * Integration tests for autotel
- *
- * Tests end-to-end flows with all components working together
- */
-
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { init } from './init';
-import { trace } from './functional';
-import { track, resetEventQueue } from './track';
-import { Event, resetEvents } from './event';
-import { flush, shutdown } from './shutdown';
-import { resetMetrics } from './metric';
-import { resetConfig } from './config';
-import { EventAttributes, EventSubscriber } from './event-subscriber';
-
-// Test adapter that collects events
-class TestAdapter implements EventSubscriber {
-  name = 'test-adapter';
-  events: Array<{ type: string; name: string; attributes?: EventAttributes }> =
-    [];
-
-  async trackEvent(name: string, attributes?: EventAttributes): Promise<void> {
-    this.events.push({ type: 'event', name, attributes });
-  }
-
-  async trackFunnelStep(
-    funnel: string,
-    status: string,
-    attributes?: EventAttributes,
-  ): Promise<void> {
-    this.events.push({
-      type: 'funnel',
-      name: `${funnel}.${status}`,
-      attributes,
-    });
-  }
-
-  async trackOutcome(
-    operation: string,
-    status: string,
-    attributes?: EventAttributes,
-  ): Promise<void> {
-    this.events.push({
-      type: 'outcome',
-      name: `${operation}.${status}`,
-      attributes,
-    });
-  }
-
-  async trackValue(
-    metric: string,
-    value: number,
-    attributes?: EventAttributes,
-  ): Promise<void> {
-    this.events.push({
-      type: 'value',
-      name: metric,
-      attributes: { ...attributes, value },
-    });
-  }
-
-  async shutdown(): Promise<void> {
-    // Cleanup if needed
-  }
-
-  reset(): void {
-    this.events = [];
-  }
-}
-
-describe('Integration Test Suite', () => {
-  let testAdapter: TestAdapter;
-
-  beforeEach(() => {
-    // Reset all global state between tests
-    resetEventQueue();
-    resetEvents();
-    resetMetrics();
-    resetConfig();
-    testAdapter = new TestAdapter();
-  });
-
-  afterEach(async () => {
-    // Clean up after each test
-    await shutdown();
-  });
-
-  describe('Full stack initialization', () => {
-    it('should initialize all components together', () => {
-      init({
-        service: 'test-app',
-        subscribers: [testAdapter],
-        version: '1.0.0',
-        environment: 'test',
-      });
-
-      expect(true).toBe(true); // Should not throw
-    });
-  });
-
-  describe('Tracing + Events integration', () => {
-    it('should correlate traces with events events', async () => {
-      init({
-        service: 'user-service',
-        subscribers: [testAdapter],
-      });
-
-      // Create trace function
-      const createUser = trace(async (userId: string, plan: string) => {
-        // Track events event inside trace function
-        track('user.signup', { userId, plan });
-        return { id: userId, plan };
-      });
-
-      // Execute
-      const result = await createUser('user123', 'pro');
-
-      // Should return expected result
-      expect(result).toEqual({ id: 'user123', plan: 'pro' });
-
-      // Flush to send events
-      await flush();
-
-      // Events event should be tracked
-      // (traceId correlation happens automatically)
-      const event = testAdapter.events.filter((e) => e.name === 'user.signup');
-      expect(event.length).toBeGreaterThan(0);
-    });
-
-    it('should handle nested trace functions', async () => {
-      init({
-        service: 'order-service',
-        subscribers: [testAdapter],
-      });
-
-      const validateOrder = trace(async (orderId: string) => {
-        track('order.validated', { orderId });
-        return true;
-      });
-
-      const processPayment = trace(async (orderId: string, amount: number) => {
-        track('payment.processed', { orderId, amount });
-        return { success: true };
-      });
-
-      const createOrder = trace(async (orderId: string, amount: number) => {
-        await validateOrder(orderId);
-        await processPayment(orderId, amount);
-        track('order.completed', { orderId, amount });
-        return { orderId, status: 'completed' };
-      });
-
-      await createOrder('order123', 99.99);
-      await flush();
-
-      // All events should be tracked
-      expect(testAdapter.events.length).toBeGreaterThanOrEqual(3);
-      expect(testAdapter.events.map((e) => e.name)).toContain(
-        'order.validated',
-      );
-      expect(testAdapter.events.map((e) => e.name)).toContain(
-        'payment.processed',
-      );
-      expect(testAdapter.events.map((e) => e.name)).toContain(
-        'order.completed',
-      );
-    });
-  });
-
-  describe('Events class integration', () => {
-    it('should track all events event types', async () => {
-      const event = new Event('checkout', {
-        subscribers: [testAdapter],
-      });
-
-      // Track different event types
-      event.trackEvent('checkout.started', { cartValue: 149.99 });
-      event.trackFunnelStep('checkout', 'started', { userId: '123' });
-      event.trackFunnelStep('checkout', 'started', {
-        userId: '123',
-        step: 'payment_info',
-      });
-      event.trackFunnelStep('checkout', 'completed', { userId: '123' });
-      event.trackOutcome('payment.process', 'success', { amount: 149.99 });
-      event.trackValue('revenue', 149.99, { currency: 'USD' });
-
-      // Flush adapters
-      await event.flush();
-
-      // All events should be captured
-      expect(testAdapter.events.length).toBe(6);
-      expect(testAdapter.events.map((e) => e.type)).toEqual([
-        'event',
-        'funnel',
-        'funnel',
-        'funnel',
-        'outcome',
-        'value',
-      ]);
-    });
-  });
-
-  describe('Error handling integration', () => {
-    it('should handle adapter failures gracefully', async () => {
-      const failingAdapter: EventSubscriber = {
-        name: 'failing-adapter',
-        trackEvent: async () => {
-          throw new Error('Adapter error');
-        },
-        trackFunnelStep: async () => {},
-        trackOutcome: async () => {},
-        trackValue: async () => {},
-      };
-
-      const event = new Event('test', {
-        subscribers: [failingAdapter, testAdapter], // Mix failing and working
-      });
-
-      // Should not throw even though one adapter fails
-      event.trackEvent('test.event', { foo: 'bar' });
-
-      await event.flush();
-
-      // Working adapter should still receive events
-      expect(testAdapter.events.length).toBeGreaterThan(0);
-    });
-
-    it('should handle circuit breaker opening', async () => {
-      let callCount = 0;
-
-      const unreliableAdapter: EventSubscriber = {
-        name: 'unreliable-adapter',
-        trackEvent: async () => {
-          callCount++;
-          // Fail first 5 times to trip circuit breaker
-          if (callCount <= 5) {
-            throw new Error('Service unavailable');
-          }
-        },
-        trackFunnelStep: async () => {},
-        trackOutcome: async () => {},
-        trackValue: async () => {},
-      };
-
-      const event = new Event('test', {
-        subscribers: [unreliableAdapter],
-      });
-
-      // Send events one at a time to allow circuit breaker to open
-      for (let i = 0; i < 10; i++) {
-        event.trackEvent(`event.${i}`, { index: i });
-        // Wait a bit to allow circuit breaker to process
-        await new Promise((resolve) => setTimeout(resolve, 10));
-      }
-
-      await event.flush();
-
-      // Circuit should open after 5 failures
-      // Remaining calls should be fast-failed
-      expect(callCount).toBeLessThanOrEqual(6); // 5 failures + maybe 1 half-open test
-    });
-  });
-
-  describe('Input validation integration', () => {
-    it('should sanitize sensitive data across all components', async () => {
-      init({
-        service: 'auth-service',
-        subscribers: [testAdapter],
-      });
-
-      // Track with sensitive data
-      track('user.login', {
-        email: 'user@example.com',
-        password: 'secret123', // Should be redacted
-        apiKey: 'abc123', // Should be redacted
-        userId: '123', // Should NOT be redacted
-      });
-
-      await flush();
-
-      const event = testAdapter.events.find((e) => e.name === 'user.login');
-      expect(event?.attributes?.email).toBe('user@example.com');
-      expect(event?.attributes?.password).toBe('[REDACTED]');
-      expect(event?.attributes?.apiKey).toBe('[REDACTED]');
-      expect(event?.attributes?.userId).toBe('123');
-    });
-
-    it('should validate event names', () => {
-      const event = new Event('test', {
-        subscribers: [testAdapter],
-      });
-
-      // Invalid event names should throw
-      expect(() => {
-        event.trackEvent('', { foo: 'bar' });
-      }).toThrow();
-
-      expect(() => {
-        event.trackEvent('invalid event name', { foo: 'bar' });
-      }).toThrow();
-    });
-  });
-
-  describe('Graceful shutdown integration', () => {
-    it('should shutdown all components cleanly', async () => {
-      init({
-        service: 'test-service',
-        subscribers: [testAdapter],
-      });
-
-      track('test.event', { foo: 'bar' });
-
-      await shutdown();
-
-      // Events should be flushed
-      expect(testAdapter.events.length).toBeGreaterThan(0);
-    });
-  });
-
-  describe('Performance under load', () => {
-    it('should handle high event volume', async () => {
-      init({
-        service: 'high-volume-service',
-        subscribers: [testAdapter],
-      });
-
-      // Send 1000 events
-      for (let i = 0; i < 1000; i++) {
-        track(`event.${i}`, { index: i });
-      }
-
-      await flush({ timeout: 10_000 }); // 10s timeout for high-volume test
-
-      // All events should be captured
-      expect(testAdapter.events.length).toBeGreaterThanOrEqual(1000);
-    });
-
-    it('should batch events efficiently', async () => {
-      init({
-        service: 'batch-test',
-        subscribers: [testAdapter],
-      });
-
-      const startTime = Date.now();
-
-      // Track 500 events
-      for (let i = 0; i < 500; i++) {
-        track(`event.${i}`, { index: i });
-      }
-
-      await flush({ timeout: 10_000 }); // 10s timeout for high-volume test
-
-      const duration = Date.now() - startTime;
-
-      // Should complete in reasonable time (batching improves performance)
-      // This is a sanity check - actual threshold depends on hardware
-      expect(duration).toBeLessThan(10_000); // 10 seconds (increased for CI/CD reliability)
-    });
-  });
-});