autotel 3.0.0 → 3.0.4

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/functional.test.ts

@@ -62,6 +62,24 @@ describe('Functional API', () => {
       expect(promise).toBeInstanceOf(Promise);
       await expect(promise).resolves.toBe(84);
     });
+
+    it('accepts a string name as first argument (sync)', () => {
+      const result = span('sync-name-shorthand', () => 'ok');
+      expect(result).toBe('ok');
+    });
+
+    it('accepts a string name as first argument (async)', async () => {
+      await expect(
+        span('async-name-shorthand', async () => 'ok'),
+      ).resolves.toBe('ok');
+    });
+
+    it('records spans created via the string-name shorthand', async () => {
+      const collector = createTraceCollector();
+      await span('shorthand.recorded', async () => undefined);
+      const names = collector.getSpans().map((s) => s.name);
+      expect(names).toContain('shorthand.recorded');
+    });
   });
 
   describe('trace()', () => {

package/src/functional.ts

@@ -2124,44 +2124,56 @@ export interface SpanOptions {
  * Useful for adding tracing to specific code blocks without wrapping
  * the entire function. Supports both synchronous and asynchronous functions.
  *
+ * Mirrors `trace()`: pass a span name as the first argument for the common
+ * case, or full `SpanOptions` when you need to attach attributes.
+ *
  * @example
  * ```typescript
- * // Async function
- * async function processOrder(order: Order) {
- *   await span({
- *     name: 'payment.charge',
- *     attributes: { amount: order.total }
- *   }, async (span) => {
+ * // Name shorthand
+ * await span('payment.charge', async (span) => {
+ *   await chargeCustomer(order);
+ * })
+ *
+ * // Full options when attributes are needed
+ * await span(
+ *   { name: 'payment.charge', attributes: { amount: order.total } },
+ *   async (span) => {
  *     await chargeCustomer(order);
- *   })
- * }
+ *   },
+ * )
  *
- * // Sync function
- * function calculateTotal(items: Item[]) {
- *   return span({
- *     name: 'calculateTotal',
- *     attributes: { itemCount: items.length }
- *   }, (span) => {
- *     return items.reduce((sum, item) => sum + item.price, 0);
- *   })
- * }
+ * // Sync
+ * const total = span('calculateTotal', (span) => {
+ *   return items.reduce((sum, item) => sum + item.price, 0);
+ * })
  * ```
  */
-// Overload for sync functions (more specific - should come first)
+// Overloads — sync first (more specific match), then async.
+// Each shape is offered with a string name OR a full SpanOptions object so
+// span() aligns with trace()'s argument flexibility.
+export function span<T = unknown>(
+  name: string,
+  fn: (span: Span) => T,
+): T;
+export function span<T = unknown>(
+  name: string,
+  fn: (span: Span) => Promise<T>,
+): Promise<T>;
 export function span<T = unknown>(
   options: SpanOptions,
   fn: (span: Span) => T,
 ): T;
-// Overload for async functions
 export function span<T = unknown>(
   options: SpanOptions,
   fn: (span: Span) => Promise<T>,
 ): Promise<T>;
 // Implementation
 export function span<T = unknown>(
-  options: SpanOptions,
+  nameOrOptions: string | SpanOptions,
   fn: (span: Span) => T | Promise<T>,
 ): T | Promise<T> {
+  const options: SpanOptions =
+    typeof nameOrOptions === 'string' ? { name: nameOrOptions } : nameOrOptions;
   const config = getConfig();
   const tracer = config.tracer;
   const { name, attributes } = options;

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;
   };