autotel 3.0.0 → 3.0.3

package/src/drain-toolkit.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { defineDrain, defineHttpDrain } from './drain-toolkit';
+
+describe('defineDrain', () => {
+  it('calls send with transformed payloads', async () => {
+    const send = vi.fn(async () => {});
+    const drain = defineDrain<
+      { event: { id: string } },
+      { key: string },
+      string
+    >({
+      name: 'test',
+      resolve: async () => ({ key: 'k' }),
+      transform: (contexts) => contexts.map((c) => c.event.id),
+      send,
+    });
+
+    await drain({ event: { id: 'a' } });
+    expect(send).toHaveBeenCalledWith(['a'], { key: 'k' });
+  });
+
+  it('skips send when resolve returns null', async () => {
+    const send = vi.fn(async () => {});
+    const drain = defineDrain({
+      name: 'test',
+      resolve: async () => null,
+      send,
+    });
+
+    await drain({ event: { id: 'a' } });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it('isolates send errors', async () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const drain = defineDrain({
+      name: 'test',
+      resolve: async () => ({ ok: true }),
+      send: async () => {
+        throw new Error('fail');
+      },
+    });
+
+    await expect(drain({ event: { id: 'a' } })).resolves.toBeUndefined();
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe('defineHttpDrain', () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('encodes payload and posts via fetch', async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const drain = defineHttpDrain<
+      { event: { id: string } },
+      { token: string },
+      { id: string }
+    >({
+      name: 'http-drain',
+      resolve: async () => ({ token: 't' }),
+      transform: (contexts) => contexts.map((c) => c.event),
+      encode: (payloads, config) => ({
+        url: 'https://example.com/ingest',
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(payloads),
+      }),
+      retries: 1,
+      timeoutMs: 2000,
+    });
+
+    await drain({ event: { id: 'evt_1' } });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe('https://example.com/ingest');
+  });
+
+  it('retries failed requests', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('network'))
+      .mockResolvedValueOnce(new Response(null, { status: 200 }));
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const drain = defineHttpDrain({
+      name: 'http-drain',
+      resolve: async () => ({ ok: true }),
+      encode: () => ({
+        url: 'https://example.com/ingest',
+        headers: { 'content-type': 'application/json' },
+        body: '[]',
+      }),
+      retries: 2,
+      timeoutMs: 2000,
+    });
+
+    await drain({ event: { id: 'evt_1' } });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});

package/src/drain-toolkit.ts

@@ -0,0 +1,129 @@
+export interface DrainOptions<TContext, TConfig, TPayload = TContext> {
+  /** Stable identifier used in error logs. */
+  name: string;
+  /** Return null to skip draining (e.g. missing API key in dev). */
+  resolve: () => TConfig | null | Promise<TConfig | null>;
+  /** Transform contexts into payloads. Defaults to identity. */
+  transform?: (contexts: TContext[]) => TPayload[];
+  /** Transport implementation. */
+  send: (payloads: TPayload[], config: TConfig) => Promise<void>;
+}
+
+export interface HttpDrainRequest {
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+export interface HttpDrainOptions<
+  TContext,
+  TConfig,
+  TPayload = TContext,
+> extends Omit<DrainOptions<TContext, TConfig, TPayload>, 'send'> {
+  encode: (payloads: TPayload[], config: TConfig) => HttpDrainRequest | null;
+  timeoutMs?: number;
+  retries?: number;
+  resolveTimeoutMs?: (config: TConfig) => number | undefined;
+  resolveRetries?: (config: TConfig) => number | undefined;
+}
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_RETRIES = 2;
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+  });
+}
+
+async function postWithRetry(options: {
+  name: string;
+  request: HttpDrainRequest;
+  timeoutMs: number;
+  retries: number;
+}): Promise<void> {
+  const { name, request, timeoutMs, retries } = options;
+  const attempts = Math.max(1, retries);
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    timeout.unref?.();
+    try {
+      const response = await fetch(request.url, {
+        method: 'POST',
+        headers: request.headers,
+        body: request.body,
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        throw new Error(
+          `[autotel/${name}] HTTP ${response.status} draining ${request.url}`,
+        );
+      }
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt < attempts) {
+        await delay(100 * attempt);
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  throw lastError;
+}
+
+export function defineDrain<TContext, TConfig, TPayload = TContext>(
+  options: DrainOptions<TContext, TConfig, TPayload>,
+): (ctx: TContext | TContext[]) => Promise<void> {
+  return async (ctx: TContext | TContext[]) => {
+    const contexts = Array.isArray(ctx) ? ctx : [ctx];
+    if (contexts.length === 0) return;
+
+    const config = await options.resolve();
+    if (!config) return;
+
+    const payloads = options.transform
+      ? options.transform(contexts)
+      : (contexts as unknown as TPayload[]);
+
+    if (payloads.length === 0) return;
+
+    try {
+      await options.send(payloads, config);
+    } catch (error) {
+      console.error(`[autotel/${options.name}] drain failed:`, error);
+    }
+  };
+}
+
+export function defineHttpDrain<TContext, TConfig, TPayload = TContext>(
+  options: HttpDrainOptions<TContext, TConfig, TPayload>,
+): (ctx: TContext | TContext[]) => Promise<void> {
+  return defineDrain<TContext, TConfig, TPayload>({
+    name: options.name,
+    resolve: options.resolve,
+    transform: options.transform,
+    send: async (payloads, config) => {
+      const request = options.encode(payloads, config);
+      if (!request) return;
+      const timeoutMs =
+        options.resolveTimeoutMs?.(config) ??
+        options.timeoutMs ??
+        DEFAULT_TIMEOUT_MS;
+      const retries =
+        options.resolveRetries?.(config) ?? options.retries ?? DEFAULT_RETRIES;
+
+      await postWithRetry({
+        name: options.name,
+        request,
+        timeoutMs,
+        retries,
+      });
+    },
+  });
+}

package/src/enricher-toolkit.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi } from 'vitest';
+import { defineEnricher } from './enricher-toolkit';
+
+describe('defineEnricher', () => {
+  it('merges computed values into existing field by default', () => {
+    const enricher = defineEnricher({
+      name: 'tenant-enricher',
+      field: 'tenant',
+      compute: () => ({ plan: 'pro' }),
+    });
+
+    const ctx = {
+      event: { tenant: { id: 't_1' } },
+    };
+
+    enricher(ctx);
+    expect(ctx.event).toEqual({ tenant: { id: 't_1', plan: 'pro' } });
+  });
+
+  it('overwrites field when overwrite=true', () => {
+    const enricher = defineEnricher(
+      {
+        name: 'tenant-enricher',
+        field: 'tenant',
+        compute: () => ({ plan: 'pro' }),
+      },
+      { overwrite: true },
+    );
+
+    const ctx = {
+      event: { tenant: { id: 't_1' } },
+    };
+
+    enricher(ctx);
+    expect(ctx.event).toEqual({ tenant: { plan: 'pro' } });
+  });
+
+  it('skips enrichment when compute returns undefined', () => {
+    const enricher = defineEnricher({
+      name: 'noop-enricher',
+      field: 'tenant',
+      compute: () => undefined,
+    });
+
+    const ctx = { event: { a: 1 } as Record<string, unknown> };
+    enricher(ctx);
+    expect(ctx.event).toEqual({ a: 1 });
+  });
+
+  it('isolates compute errors and logs them', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const enricher = defineEnricher({
+      name: 'broken-enricher',
+      field: 'tenant',
+      compute: () => {
+        throw new Error('boom');
+      },
+    });
+
+    const ctx = { event: {} as Record<string, unknown> };
+    enricher(ctx);
+
+    expect(ctx.event).toEqual({});
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});

package/src/enricher-toolkit.ts

@@ -0,0 +1,79 @@
+export interface EnrichContext<TEvent extends Record<string, unknown>> {
+  event: TEvent;
+  request?: {
+    method?: string;
+    path?: string;
+    requestId?: string;
+  };
+  response?: {
+    status?: number;
+  };
+  headers?: Record<string, string>;
+}
+
+export interface EnricherDefinition<
+  TEvent extends Record<string, unknown>,
+  TValue extends object,
+> {
+  /** Stable identifier used in error logs. */
+  name: string;
+  /** Top-level field to merge computed values into. */
+  field: keyof TEvent & string;
+  /** Return undefined to skip enrichment. */
+  compute: (ctx: EnrichContext<TEvent>) => TValue | undefined;
+}
+
+export interface EnricherOptions {
+  /** Replace existing field value instead of merge. Default false. */
+  overwrite?: boolean;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeInto(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): void {
+  for (const key in source) {
+    const sourceVal = source[key];
+    if (sourceVal === undefined) continue;
+    const targetVal = target[key];
+    if (isPlainObject(sourceVal) && isPlainObject(targetVal)) {
+      mergeInto(targetVal, sourceVal);
+    } else {
+      target[key] = sourceVal;
+    }
+  }
+}
+
+export function defineEnricher<
+  TEvent extends Record<string, unknown>,
+  TValue extends object,
+>(
+  def: EnricherDefinition<TEvent, TValue>,
+  options: EnricherOptions = {},
+): (ctx: EnrichContext<TEvent>) => void {
+  return (ctx: EnrichContext<TEvent>) => {
+    let computed: TValue | undefined;
+    try {
+      computed = def.compute(ctx);
+    } catch (error) {
+      console.error(`[autotel/${def.name}] enrich failed:`, error);
+      return;
+    }
+
+    if (!computed) return;
+
+    if (options.overwrite || !isPlainObject(ctx.event[def.field])) {
+      (ctx.event as Record<string, unknown>)[def.field] = computed;
+      return;
+    }
+
+    mergeInto(
+      ctx.event[def.field] as unknown as Record<string, unknown>,
+      computed as unknown as Record<string, unknown>,
+    );
+  };
+}

package/src/index.ts

@@ -60,12 +60,16 @@ export {
   AttributeRedactingProcessor,
   REDACTOR_PATTERNS,
   REDACTOR_PRESETS,
+  builtinPatterns,
   createAttributeRedactor,
   createRedactedSpan,
+  normalizeAttributeRedactorConfig,
   type AttributeRedactorFn,
   type AttributeRedactorPreset,
   type AttributeRedactorConfig,
   type AttributeRedactingProcessorOptions,
+  type BuiltinPatternName,
+  type MaskFn,
   type ValuePatternConfig,
 } from './attribute-redacting-processor';
 
@@ -123,6 +127,8 @@ export {
   type RequestLogger,
   type RequestLogSnapshot,
   type RequestLoggerOptions,
+  type ForkLifecycle,
+  type ForkOptions,
 } from './request-logger';
 
 // Structured errors
@@ -147,6 +153,19 @@ export {
   type DrainPipelineOptions,
   type PipelineDrainFn,
 } from './drain-pipeline';
+export {
+  defineDrain,
+  defineHttpDrain,
+  type DrainOptions,
+  type HttpDrainOptions,
+  type HttpDrainRequest,
+} from './drain-toolkit';
+export {
+  defineEnricher,
+  type EnricherDefinition,
+  type EnrichContext,
+  type EnricherOptions,
+} from './enricher-toolkit';
 
 // Pretty log formatting
 export { formatDuration } from './pretty-log-formatter';

package/src/redact-values.test.ts

@@ -10,18 +10,32 @@ describe('createStringRedactor', () => {
       redact = createStringRedactor('default');
     });
 
-    it('redacts emails', () => {
+    it('smart-masks emails', () => {
       expect(redact('Contact user@example.com for info')).toBe(
-        'Contact [REDACTED] for info',
+        'Contact u***@***.com for info',
       );
     });
 
-    it('redacts phone numbers', () => {
-      expect(redact('Call 555-123-4567 now')).toBe('Call [REDACTED] now');
+    it('smart-masks international phone numbers (country code + last 2 digits)', () => {
+      expect(redact('Call +33 1 23 45 67 89 now')).toBe('Call +33******89 now');
     });
 
-    it('redacts credit card numbers', () => {
-      expect(redact('Card: 4111-1111-1111-1111')).toBe('Card: [REDACTED]');
+    it('smart-masks phone numbers with parens (last 2 digits)', () => {
+      expect(redact('Call (415) 555-1234 now')).toBe('Call ********34 now');
+    });
+
+    it('smart-masks common US phone formats', () => {
+      expect(redact('Call 555-123-4567 now')).toBe('Call ********67 now');
+      expect(redact('Call 5551234567 now')).toBe('Call ********67 now');
+    });
+
+    it('does not mistake bare digit runs for phone numbers', () => {
+      // UUIDs, order ids etc. should pass through untouched.
+      expect(redact('Order: 12345678 ok')).toBe('Order: 12345678 ok');
+    });
+
+    it('smart-masks credit card numbers (last four digits preserved)', () => {
+      expect(redact('Card: 4111-1111-1111-1111')).toBe('Card: ****1111');
     });
 
     it('returns input unchanged when no patterns match', () => {
@@ -36,15 +50,15 @@ describe('createStringRedactor', () => {
       redact = createStringRedactor('strict');
     });
 
-    it('redacts JWTs', () => {
+    it('smart-masks JWTs', () => {
       const jwt =
         'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.abc123_-def';
-      expect(redact(`Token: ${jwt}`)).toBe('Token: [REDACTED]');
+      expect(redact(`Token: ${jwt}`)).toBe('Token: eyJ***.***');
     });
 
-    it('redacts bearer tokens', () => {
+    it('smart-masks bearer tokens', () => {
       expect(redact('Authorization: Bearer abc123.xyz')).toBe(
-        'Authorization: [REDACTED]',
+        'Authorization: Bearer ***',
       );
     });
   });

package/src/redact-values.ts

@@ -18,9 +18,16 @@ export function createStringRedactor(
 
   return (value: string): string => {
     let result = value;
-    for (const { pattern, replacement } of valuePatterns) {
+    for (const { pattern, replacement, mask } of valuePatterns) {
       pattern.lastIndex = 0;
-      result = result.replaceAll(pattern, replacement ?? defaultReplacement);
+      // Smart masks (e.g. email → a***@***.com) take precedence over the
+      // static replacement so callers see the same output as the
+      // span-attribute redactor does.
+      if (mask) {
+        result = result.replaceAll(pattern, (match) => mask(match));
+      } else {
+        result = result.replaceAll(pattern, replacement ?? defaultReplacement);
+      }
     }
     return result;
   };

package/src/request-logger.test.ts

@@ -254,6 +254,97 @@ describe('log.fork()', () => {
     expect(ctx.setAttributes).not.toHaveBeenCalled();
     expect(childSpan.end).toHaveBeenCalledTimes(1);
   });
+
+  it('fork lifecycle hooks fire around child handler', async () => {
+    const ctx = createMockContext();
+    const log = getRequestLogger(ctx);
+    const childSpan = {
+      spanContext: () => ({
+        traceId: 'a'.repeat(32),
+        spanId: 'b'.repeat(16),
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      addEvent: vi.fn(),
+      addLink: vi.fn(),
+      addLinks: vi.fn(),
+      updateName: vi.fn(),
+      isRecording: vi.fn(() => true),
+      end: vi.fn(),
+    };
+
+    vi.spyOn(otelTrace, 'getTracer').mockReturnValue({
+      startActiveSpan: (
+        _name: string,
+        cb: (span: typeof childSpan) => Promise<void>,
+      ) => cb(childSpan),
+    } as unknown as ReturnType<typeof otelTrace.getTracer>);
+
+    const calls: string[] = [];
+    const onChildEnter = vi.fn(() => calls.push('enter'));
+    const onChildExit = vi.fn(() => calls.push('exit'));
+
+    log.fork(
+      'bg',
+      async () => {
+        calls.push('handler');
+      },
+      { lifecycle: { onChildEnter, onChildExit } },
+    );
+
+    await new Promise((resolve) => setImmediate(resolve));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(onChildEnter).toHaveBeenCalledTimes(1);
+    expect(onChildExit).toHaveBeenCalledTimes(1);
+    expect(calls).toEqual(['enter', 'handler', 'exit']);
+  });
+
+  it('fork onChildExit hook errors do not crash fork cleanup', async () => {
+    const ctx = createMockContext();
+    const log = getRequestLogger(ctx);
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const childSpan = {
+      spanContext: () => ({
+        traceId: 'a'.repeat(32),
+        spanId: 'b'.repeat(16),
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      addEvent: vi.fn(),
+      addLink: vi.fn(),
+      addLinks: vi.fn(),
+      updateName: vi.fn(),
+      isRecording: vi.fn(() => true),
+      end: vi.fn(),
+    };
+
+    vi.spyOn(otelTrace, 'getTracer').mockReturnValue({
+      startActiveSpan: (
+        _name: string,
+        cb: (span: typeof childSpan) => Promise<void>,
+      ) => cb(childSpan),
+    } as unknown as ReturnType<typeof otelTrace.getTracer>);
+
+    log.fork('bg', async () => {}, {
+      lifecycle: {
+        onChildExit: () => {
+          throw new Error('hook exploded');
+        },
+      },
+    });
+
+    await new Promise((resolve) => setImmediate(resolve));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(childSpan.end).toHaveBeenCalledTimes(1);
+    expect(consoleSpy).toHaveBeenCalled();
+    consoleSpy.mockRestore();
+  });
 });
 
 describe('getRequestLogger', () => {

package/src/request-logger.ts

@@ -56,7 +56,11 @@ export interface RequestLogger {
   error(error: Error | string, fields?: Record<string, unknown>): void;
   getContext(): Record<string, unknown>;
   emitNow(overrides?: Record<string, unknown>): RequestLogSnapshot;
-  fork(label: string, fn: () => void | Promise<void>): void;
+  fork(
+    label: string,
+    fn: () => void | Promise<void>,
+    options?: ForkOptions,
+  ): void;
 }
 
 export interface RequestLogSnapshot {
@@ -72,6 +76,21 @@ export interface RequestLoggerOptions {
   onEmit?: (snapshot: RequestLogSnapshot) => void | Promise<void>;
 }
 
+/**
+ * Optional lifecycle hooks for adapters that need to track child loggers
+ * spawned by `log.fork()` (e.g. active logger maps in framework integrations).
+ */
+export interface ForkLifecycle {
+  /** Called after the child logger is created, before `fn` runs. */
+  onChildEnter?: (child: RequestLogger) => void;
+  /** Called after the child has finished (emit + drain), success or failure. */
+  onChildExit?: (child: RequestLogger) => void;
+}
+
+export interface ForkOptions {
+  lifecycle?: ForkLifecycle;
+}
+
 function resolveContext(ctx?: TraceContext): TraceContext {
   if (ctx) return ctx;
 
@@ -207,7 +226,11 @@ export function getRequestLogger(
       return snapshot;
     },
 
-    fork(label: string, fn: () => void | Promise<void>): void {
+    fork(
+      label: string,
+      fn: () => void | Promise<void>,
+      forkOptions?: ForkOptions,
+    ): void {
       const parentRequestId = activeContext.correlationId;
       if (typeof parentRequestId !== 'string' || parentRequestId.length === 0) {
         throw new Error(
@@ -217,6 +240,7 @@ export function getRequestLogger(
       }
 
       const tracer = otelTrace.getTracer('autotel.request-logger');
+      const lifecycle = forkOptions?.lifecycle;
       void tracer.startActiveSpan(`request.fork:${label}`, (childSpan) => {
         const childContext: TraceContext = {
           ...createTraceContext(childSpan),
@@ -230,6 +254,8 @@ export function getRequestLogger(
             _parentCorrelationId: parentRequestId,
           });
 
+          lifecycle?.onChildEnter?.(childLog);
+
           void Promise.resolve()
             .then(() => fn())
             .then(() => {
@@ -241,6 +267,14 @@ export function getRequestLogger(
               childLog.emitNow();
             })
             .finally(() => {
+              try {
+                lifecycle?.onChildExit?.(childLog);
+              } catch (hookError) {
+                console.warn(
+                  '[autotel] fork onChildExit hook threw:',
+                  hookError,
+                );
+              }
               childSpan.end();
             });
         });