autotel 4.1.0 → 4.2.0

package/src/metrics.test.ts

@@ -1,241 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { Metric, getMetrics, resetMetrics } from './metric';
-import { type ILogger } from './logger';
-import { init } from './init';
-import { configure } from './config';
-
-describe('Metrics', () => {
-  let mockLogger: ILogger;
-
-  beforeEach(() => {
-    resetMetrics();
-    init({ service: 'test-app' });
-    configure({
-      meterName: 'test',
-    });
-    mockLogger = {
-      info: vi.fn(),
-      warn: vi.fn(),
-      error: vi.fn(),
-      debug: vi.fn(),
-    };
-  });
-
-  describe('trackEvent', () => {
-    it('should track business events as metrics', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackEvent('order.completed', {
-        orderId: '123',
-        amount: 99.99,
-      });
-
-      // Pino-native: (extra, message)
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        {
-          event: 'order.completed',
-          attributes: { orderId: '123', amount: 99.99 },
-        },
-        'Metric event tracked',
-      );
-    });
-
-    it('should track events without attributes', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackEvent('user.login');
-
-      // Pino-native: (extra, message)
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        {
-          event: 'user.login',
-          attributes: undefined,
-        },
-        'Metric event tracked',
-      );
-    });
-  });
-
-  describe('trackFunnelStep', () => {
-    it('should track funnel progression as metrics', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackFunnelStep('checkout', 'started', { cartValue: 99.99 });
-      metrics.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 });
-
-      expect(mockLogger.info).toHaveBeenCalledTimes(2);
-      // Pino-native: (extra, message)
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        {
-          funnel: 'checkout',
-          status: 'started',
-          attributes: { cartValue: 99.99 },
-        },
-        'Funnel step tracked',
-      );
-    });
-
-    it('should track funnel abandonment', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackFunnelStep('checkout', 'abandoned', { reason: 'timeout' });
-
-      // Pino-native: (extra, message)
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        {
-          funnel: 'checkout',
-          status: 'abandoned',
-          attributes: { reason: 'timeout' },
-        },
-        'Funnel step tracked',
-      );
-    });
-  });
-
-  describe('trackOutcome', () => {
-    it('should track successful outcomes as metrics', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackOutcome('payment.process', 'success', {
-        amount: 99.99,
-      });
-
-      // Pino-native: (extra, message)
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        {
-          operation: 'payment.process',
-          status: 'success',
-          attributes: { amount: 99.99 },
-        },
-        'Outcome tracked',
-      );
-    });
-
-    it('should track failed outcomes', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackOutcome('payment.process', 'failure', {
-        error: 'insufficient_funds',
-      });
-
-      // Pino-native: (extra, message)
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        {
-          operation: 'payment.process',
-          status: 'failure',
-          attributes: { error: 'insufficient_funds' },
-        },
-        'Outcome tracked',
-      );
-    });
-
-    it('should track partial outcomes', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackOutcome('batch.process', 'partial', {
-        successCount: 8,
-        failureCount: 2,
-      });
-
-      // Pino-native: (extra, message)
-      expect(mockLogger.info).toHaveBeenCalledWith(
-        {
-          operation: 'batch.process',
-          status: 'partial',
-          attributes: { successCount: 8, failureCount: 2 },
-        },
-        'Outcome tracked',
-      );
-    });
-  });
-
-  describe('trackValue', () => {
-    it('should track revenue metrics', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackValue('order.revenue', 149.99, {
-        currency: 'USD',
-        productCategory: 'electronics',
-      });
-
-      // Pino-native: (extra, message)
-      expect(mockLogger.debug).toHaveBeenCalledWith(
-        {
-          metric: 'order.revenue',
-          value: 149.99,
-          attributes: { currency: 'USD', productCategory: 'electronics' },
-        },
-        'Value metric tracked',
-      );
-    });
-
-    it('should track processing time', () => {
-      const metrics = new Metric('test-service', { logger: mockLogger });
-
-      metrics.trackValue('application.processing_time', 2500, {
-        unit: 'ms',
-      });
-
-      // Pino-native: (extra, message)
-      expect(mockLogger.debug).toHaveBeenCalledWith(
-        {
-          metric: 'application.processing_time',
-          value: 2500,
-          attributes: { unit: 'ms' },
-        },
-        'Value metric tracked',
-      );
-    });
-  });
-
-  describe('getMetrics', () => {
-    it('should return singleton instance', () => {
-      const metrics1 = getMetrics('test-service');
-      const metrics2 = getMetrics('test-service');
-
-      expect(metrics1).toBe(metrics2);
-    });
-
-    it('should return different instances for different services', () => {
-      const metrics1 = getMetrics('service-1');
-      const metrics2 = getMetrics('service-2');
-
-      expect(metrics1).not.toBe(metrics2);
-    });
-
-    it('should reset instances', () => {
-      const metrics1 = getMetrics('test-service');
-      resetMetrics();
-      const metrics2 = getMetrics('test-service');
-
-      expect(metrics1).not.toBe(metrics2);
-    });
-  });
-
-  describe('real-world usage example', () => {
-    it('should track checkout flow', () => {
-      const metrics = new Metric('checkout', { logger: mockLogger });
-
-      // User starts checkout
-      metrics.trackFunnelStep('checkout', 'started', { cartValue: 99.99 });
-
-      // Order completed
-      metrics.trackEvent('order.completed', {
-        orderId: 'ord_123',
-        amount: 99.99,
-      });
-      metrics.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 });
-
-      // Payment processed successfully
-      metrics.trackOutcome('payment.process', 'success', {
-        amount: 99.99,
-      });
-
-      // Track revenue
-      metrics.trackValue('revenue', 99.99, { currency: 'USD' });
-
-      expect(mockLogger.info).toHaveBeenCalledTimes(4);
-      expect(mockLogger.debug).toHaveBeenCalledTimes(1);
-    });
-  });
-});

package/src/node-require.ts

@@ -1,123 +0,0 @@
-/**
- * Cross-format require() helper for CJS and ESM compatibility
- *
- * Provides a synchronous `require()` function that works in both:
- * - CJS builds: Uses native `require`
- * - ESM builds: Uses `createRequire(import.meta.url)`
- *
- * This allows optional peer dependencies and dynamic module loading
- * to work synchronously in both module formats.
- */
-
-import { createRequire } from 'node:module';
-
-// `__filename` is provided by CJS and by esbuild's CJS output wrapper, but
-// is undefined under pure ESM. `import.meta.url` is provided by ESM. Pick
-// whichever is available so the helper works in:
-//   - native CJS (autotel's published `.cjs`)
-//   - native ESM (autotel's published `.js`)
-//   - ESM-bundled-into-CJS by a downstream consumer (e.g. CDK's
-//     `aws-lambda-nodejs` → esbuild with `format: cjs`). esbuild rewrites
-//     `import.meta` to `{}` in this case, so `createRequire(import.meta.url)`
-//     alone collapses to `createRequire(undefined)` and crashes at load.
-// `typeof __filename` does NOT throw when the identifier is undeclared, so
-// the ESM build evaluates the conditional safely.
-declare const __filename: string | undefined;
-
-// Build the Node `require` lazily on first use. Calling `createRequire`
-// eagerly at module load crashes in runtimes where neither `__filename` nor
-// `import.meta.url` resolves to a path — e.g. Cloudflare Workers / workerd,
-// where the bundle has no module path and `createRequire(undefined)` throws
-// synchronously at import. Deferring the call keeps merely importing this
-// module (and therefore anything that re-exports it, such as `track`)
-// side-effect-free; Node/CJS/ESM still get a real `require` on first call.
-let cachedRequire: NodeRequire | undefined;
-
-function getNodeRequire(): NodeRequire {
-  if (cachedRequire) return cachedRequire;
-  const base = typeof __filename === 'string' ? __filename : import.meta.url;
-  if (!base) {
-    // No module path in this runtime. Surface as a missing-module error so
-    // optional lookups via `safeRequire()` degrade gracefully to `undefined`.
-    throw Object.assign(
-      new Error('node require() is unavailable in this runtime'),
-      { code: 'MODULE_NOT_FOUND' },
-    );
-  }
-  cachedRequire = createRequire(base);
-  return cachedRequire;
-}
-
-/**
- * Synchronously require a module (works in both CJS and ESM)
- *
- * @param id - Module ID to require
- * @returns The required module
- * @throws Error if module cannot be loaded
- *
- * @example
- * ```typescript
- * import { safeRequire } from './node-require';
- *
- * const traceloop = safeRequire('@traceloop/node-server-sdk');
- * if (traceloop) {
- *   traceloop.initialize({ ... });
- * }
- * ```
- */
-export function safeRequire<T = unknown>(id: string): T | undefined {
-  try {
-    return getNodeRequire()(id) as T;
-  } catch (error) {
-    if (error && (error as NodeJS.ErrnoException).code === 'MODULE_NOT_FOUND') {
-      // Optional dependency missing – return undefined
-      return undefined;
-    }
-    // Any other error is a real bug: rethrow
-    throw error;
-  }
-}
-
-/**
- * Synchronously require a module (throws if not found)
- *
- * Use this when the module is required (not optional).
- *
- * @param id - Module ID to require
- * @returns The required module
- * @throws Error if module cannot be loaded
- *
- * @example
- * ```typescript
- * import { requireModule } from './node-require';
- *
- * const fs = requireModule<typeof import('node:fs')>('node:fs');
- * const content = fs.readFileSync('file.txt', 'utf8');
- * ```
- */
-export function requireModule<T = unknown>(id: string): T {
-  return getNodeRequire()(id) as T;
-}
-
-/**
- * Direct access to the nodeRequire function (for advanced use cases).
- *
- * Lazily resolves the underlying Node `require` on first call, so importing
- * this binding never triggers `createRequire` in runtimes that lack a module
- * path (e.g. Cloudflare Workers).
- *
- * Only the call signature and `resolve` (including `resolve.paths`) are
- * forwarded. The live, mutable members of a real `require` — `.cache`,
- * `.main`, `.extensions` — are intentionally NOT exposed: a lazy wrapper
- * can't mirror that shared state without resolving eagerly, which would
- * reintroduce the workerd crash. Use `createRequire` directly if you need
- * them.
- */
-const nodeRequire = ((id: string) => getNodeRequire()(id)) as NodeRequire;
-const lazyResolve = ((id: string, options?: { paths?: string[] }) =>
-  getNodeRequire().resolve(id, options)) as NodeRequire['resolve'];
-lazyResolve.paths = (request: string) =>
-  getNodeRequire().resolve.paths(request);
-nodeRequire.resolve = lazyResolve;
-
-export { nodeRequire };

package/src/operation-context.ts

@@ -1,93 +0,0 @@
-/**
- * Operation context tracking using AsyncLocalStorage
- *
- * This module provides a way to track operation names across async boundaries
- * so they can be automatically captured in events events.
- *
- * We cannot read span attributes from OpenTelemetry's API (it's write-only),
- * so we maintain our own async context storage.
- */
-
-import { AsyncLocalStorage } from 'node:async_hooks';
-
-/**
- * Operation context that flows through async operations
- */
-export interface OperationContext {
-  /**
-   * The name of the current operation
-   * This is set by trace() or span() and can be read by events
-   */
-  name: string;
-}
-
-/**
- * AsyncLocalStorage instance for tracking operation context
- */
-const operationStorage = new AsyncLocalStorage<OperationContext>();
-
-/**
- * Get the current operation context (if any)
- *
- * @returns The current operation context, or undefined if not in an operation
- *
- * @example
- * ```typescript
- * const ctx = getOperationContext();
- * if (ctx) {
- *   console.log('Current operation:', ctx.name);
- * }
- * ```
- */
-export function getOperationContext(): OperationContext | undefined {
-  return operationStorage.getStore();
-}
-
-/**
- * Run a function within an operation context
- *
- * This sets the operation name for the duration of the function execution,
- * including all async operations spawned from it.
- *
- * @param name - The operation name to set
- * @param fn - The function to execute within the context
- * @returns The result of the function
- *
- * @example
- * ```typescript
- * const result = await runInOperationContext('user.create', async () => {
- *   // Any events.trackEvent() calls here will automatically capture
- *   // 'operation.name': 'user.create'
- *   await createUser();
- *   return 'success';
- * });
- * ```
- */
-export function runInOperationContext<T>(name: string, fn: () => T): T {
-  return operationStorage.run({ name }, fn);
-}
-
-/**
- * Update the operation name in the current context
- *
- * This is useful when you want to change the operation name within
- * an already-established context (e.g., when entering a nested span).
- *
- * @param name - The new operation name
- *
- * @example
- * ```typescript
- * runInOperationContext('parent.operation', () => {
- *   // operation.name is 'parent.operation'
- *
- *   updateOperationName('nested.operation');
- *   // operation.name is now 'nested.operation'
- * });
- * ```
- */
-export function updateOperationName(name: string): void {
-  const store = operationStorage.getStore();
-  if (store) {
-    store.name = name;
-  }
-}

package/src/parse-error.test.ts

@@ -1,73 +0,0 @@
-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

@@ -1,112 +0,0 @@
-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,
-  };
-}