autotel 3.1.1 → 3.3.0

package/src/gen-ai-cost.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  estimateLLMCost,
+  recordLLMCost,
+  GEN_AI_COST_ATTRIBUTE,
+} from './gen-ai-cost';
+
+describe('estimateLLMCost', () => {
+  it('estimates cost from input and output tokens', () => {
+    // claude-sonnet-4: $3 / 1M in, $15 / 1M out
+    const cost = estimateLLMCost('claude-sonnet-4', {
+      inputTokens: 1_000_000,
+      outputTokens: 1_000_000,
+    });
+    expect(cost).toBe(18);
+  });
+
+  it('matches versioned model ids by longest prefix', () => {
+    const cost = estimateLLMCost('claude-sonnet-4-6-20251101', {
+      inputTokens: 1_000_000,
+      outputTokens: 0,
+    });
+    expect(cost).toBe(3);
+  });
+
+  it('returns undefined for an unknown model', () => {
+    expect(
+      estimateLLMCost('totally-made-up', { inputTokens: 1000 }),
+    ).toBeUndefined();
+  });
+
+  it('bills cached input tokens at the cached rate', () => {
+    const pricing = {
+      custom: { inputPer1M: 10, outputPer1M: 30, cachedInputPer1M: 1 },
+    };
+    // 1M input, of which 800k cached: 200k @ $10/M + 800k @ $1/M = 2 + 0.8
+    const cost = estimateLLMCost(
+      'custom',
+      { inputTokens: 1_000_000, cachedInputTokens: 800_000 },
+      { pricing },
+    );
+    expect(cost).toBeCloseTo(2.8, 6);
+  });
+
+  it('accepts a pricing override and extends the table', () => {
+    const cost = estimateLLMCost(
+      'my-model',
+      { inputTokens: 500_000, outputTokens: 500_000 },
+      { pricing: { 'my-model': { inputPer1M: 4, outputPer1M: 8 } } },
+    );
+    expect(cost).toBe(6);
+  });
+
+  it('handles partial usage without throwing', () => {
+    expect(estimateLLMCost('gpt-4o-mini', {})).toBe(0);
+    expect(estimateLLMCost('gpt-4o-mini', { outputTokens: 1_000_000 })).toBe(
+      0.6,
+    );
+  });
+});
+
+describe('recordLLMCost', () => {
+  it('sets the cost attribute on the context for a known model', () => {
+    const setAttribute = vi.fn();
+    const cost = recordLLMCost({ setAttribute }, 'gpt-4o', {
+      inputTokens: 1_000_000,
+      outputTokens: 0,
+    });
+    expect(cost).toBe(2.5);
+    expect(setAttribute).toHaveBeenCalledWith(GEN_AI_COST_ATTRIBUTE, 2.5);
+  });
+
+  it('sets no attribute for an unknown model', () => {
+    const setAttribute = vi.fn();
+    const cost = recordLLMCost({ setAttribute }, 'unknown-model', {
+      inputTokens: 100,
+    });
+    expect(cost).toBeUndefined();
+    expect(setAttribute).not.toHaveBeenCalled();
+  });
+});

package/src/gen-ai-cost.ts

@@ -0,0 +1,145 @@
+/**
+ * Per-model LLM cost estimation.
+ *
+ * Estimate the USD cost of an LLM call from its token usage and record it as a
+ * span attribute (`gen_ai.usage.cost.usd`). Pair with the
+ * `gen_ai.client.cost.usd` metric bucket advice in `gen-ai-metrics`.
+ *
+ * @example
+ * ```typescript
+ * import { trace, recordLLMCost } from 'autotel';
+ *
+ * export const chat = trace((ctx) => async (prompt: string) => {
+ *   const res = await client.messages.create({ model, ... });
+ *   recordLLMCost(ctx, model, {
+ *     inputTokens: res.usage.input_tokens,
+ *     outputTokens: res.usage.output_tokens,
+ *   });
+ *   return res;
+ * });
+ * ```
+ */
+
+import type { TraceContext } from './trace-context';
+
+/** Span attribute key autotel sets for an estimated call cost. */
+export const GEN_AI_COST_ATTRIBUTE = 'gen_ai.usage.cost.usd';
+
+/** Pricing for a single model, in USD per 1,000,000 tokens. */
+export interface ModelPricing {
+  /** USD per 1M input (prompt) tokens. */
+  inputPer1M: number;
+  /** USD per 1M output (completion) tokens. */
+  outputPer1M: number;
+  /** USD per 1M cached input tokens. Defaults to {@link ModelPricing.inputPer1M}. */
+  cachedInputPer1M?: number;
+}
+
+/** Token counts for a single LLM call. */
+export interface TokenUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  /** Cached input tokens, billed at {@link ModelPricing.cachedInputPer1M}. */
+  cachedInputTokens?: number;
+}
+
+export interface EstimateCostOptions {
+  /** Override or extend {@link MODEL_PRICING}. Keys are matched first. */
+  pricing?: Record<string, ModelPricing>;
+}
+
+/**
+ * Approximate public list prices (USD per 1M tokens) at the time of writing.
+ * Prices change; treat these as convenience defaults, not a billing source of
+ * truth. Override per call via `options.pricing` or mutate this table at init.
+ * Matching is exact first, then by longest key prefix, so versioned model ids
+ * (`claude-sonnet-4-6-20251101`) resolve to a base entry (`claude-sonnet-4-6`).
+ */
+export const MODEL_PRICING: Record<string, ModelPricing> = {
+  // OpenAI
+  'gpt-4o': { inputPer1M: 2.5, outputPer1M: 10 },
+  'gpt-4o-mini': { inputPer1M: 0.15, outputPer1M: 0.6 },
+  'gpt-4.1': { inputPer1M: 2, outputPer1M: 8 },
+  'gpt-4.1-mini': { inputPer1M: 0.4, outputPer1M: 1.6 },
+  'gpt-4.1-nano': { inputPer1M: 0.1, outputPer1M: 0.4 },
+  'o3-mini': { inputPer1M: 1.1, outputPer1M: 4.4 },
+  // Anthropic Claude
+  'claude-opus-4': { inputPer1M: 15, outputPer1M: 75 },
+  'claude-sonnet-4': { inputPer1M: 3, outputPer1M: 15 },
+  'claude-3-5-sonnet': { inputPer1M: 3, outputPer1M: 15 },
+  'claude-3-5-haiku': { inputPer1M: 0.8, outputPer1M: 4 },
+  'claude-3-opus': { inputPer1M: 15, outputPer1M: 75 },
+  'claude-3-haiku': { inputPer1M: 0.25, outputPer1M: 1.25 },
+  // Google Gemini
+  'gemini-1.5-pro': { inputPer1M: 1.25, outputPer1M: 5 },
+  'gemini-1.5-flash': { inputPer1M: 0.075, outputPer1M: 0.3 },
+  'gemini-2.0-flash': { inputPer1M: 0.1, outputPer1M: 0.4 },
+};
+
+function resolvePricing(
+  table: Record<string, ModelPricing>,
+  model: string,
+): ModelPricing | undefined {
+  const exact = table[model];
+  if (exact) return exact;
+
+  let best: ModelPricing | undefined;
+  let bestLength = 0;
+  for (const key of Object.keys(table)) {
+    if (model.startsWith(key) && key.length > bestLength) {
+      best = table[key];
+      bestLength = key.length;
+    }
+  }
+  return best;
+}
+
+function round(value: number): number {
+  return Math.round(value * 1e6) / 1e6;
+}
+
+/**
+ * Estimate the USD cost of an LLM call. Returns `undefined` when the model has
+ * no known pricing (supply one via `options.pricing`).
+ */
+export function estimateLLMCost(
+  model: string,
+  usage: TokenUsage,
+  options?: EstimateCostOptions,
+): number | undefined {
+  const table = options?.pricing
+    ? { ...MODEL_PRICING, ...options.pricing }
+    : MODEL_PRICING;
+  const price = resolvePricing(table, model);
+  if (!price) return undefined;
+
+  const cachedInput = usage.cachedInputTokens ?? 0;
+  const billedInput = Math.max(0, (usage.inputTokens ?? 0) - cachedInput);
+  const output = usage.outputTokens ?? 0;
+  const cachedRate = price.cachedInputPer1M ?? price.inputPer1M;
+
+  const cost =
+    (billedInput / 1_000_000) * price.inputPer1M +
+    (cachedInput / 1_000_000) * cachedRate +
+    (output / 1_000_000) * price.outputPer1M;
+
+  return round(cost);
+}
+
+/**
+ * Estimate cost and record it on `ctx` as the `gen_ai.usage.cost.usd` span
+ * attribute. Returns the estimated cost, or `undefined` when the model is
+ * unknown (in which case no attribute is set).
+ */
+export function recordLLMCost(
+  ctx: Pick<TraceContext, 'setAttribute'>,
+  model: string,
+  usage: TokenUsage,
+  options?: EstimateCostOptions,
+): number | undefined {
+  const cost = estimateLLMCost(model, usage, options);
+  if (cost !== undefined) {
+    ctx.setAttribute(GEN_AI_COST_ATTRIBUTE, cost);
+  }
+  return cost;
+}

package/src/index.ts

@@ -106,6 +106,12 @@ export {
 
 // Global track function
 export { track, getEventQueue } from './track';
+export {
+  defineEvent,
+  type SchemaLike,
+  type DefineEventOptions,
+  type DefinedEvent,
+} from './define-event';
 
 // Correlation ID utilities
 export {
@@ -145,6 +151,23 @@ export {
 // parseError
 export { parseError, type ParsedError } from './parse-error';
 
+// Typed error + audit catalogs
+export {
+  defineErrorCatalog,
+  defineAuditCatalog,
+  isCatalogError,
+  getCatalogCode,
+  type ErrorCatalog,
+  type ErrorCatalogEntry,
+  type ErrorBuilder,
+  type ErrorBuildOptions,
+  type AuditCatalog,
+  type AuditCatalogEntry,
+  type AuditDescriptor,
+  type AuditAction,
+  type AuditSeverity,
+} from './error-catalog';
+
 // Attribute flattening
 export { toAttributeValue, flattenToAttributes } from './flatten-attributes';
 
@@ -235,6 +258,18 @@ export {
   type StreamFirstTokenEvent,
 } from './gen-ai-events';
 
+// Per-model LLM cost estimation — estimate USD cost from token usage and
+// record it as the gen_ai.usage.cost.usd span attribute.
+export {
+  estimateLLMCost,
+  recordLLMCost,
+  MODEL_PRICING,
+  GEN_AI_COST_ATTRIBUTE,
+  type ModelPricing,
+  type TokenUsage,
+  type EstimateCostOptions,
+} from './gen-ai-cost';
+
 // Tracer helpers for custom spans
 export {
   getTracer,

package/src/init-auto-redactor.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { resolveAttributeRedactor } from './init';
+
+const ORIGINAL = process.env.AUTOTEL_REDACT_PII;
+
+afterEach(() => {
+  if (ORIGINAL === undefined) {
+    delete process.env.AUTOTEL_REDACT_PII;
+  } else {
+    process.env.AUTOTEL_REDACT_PII = ORIGINAL;
+  }
+});
+
+describe('resolveAttributeRedactor', () => {
+  it('auto-enables the default preset in production', () => {
+    delete process.env.AUTOTEL_REDACT_PII;
+    expect(resolveAttributeRedactor(undefined, 'production')).toBe('default');
+  });
+
+  it('stays off in non-production environments', () => {
+    delete process.env.AUTOTEL_REDACT_PII;
+    expect(resolveAttributeRedactor(undefined, 'development')).toBeUndefined();
+    expect(resolveAttributeRedactor(undefined, 'test')).toBeUndefined();
+  });
+
+  it('honors an explicit preset in any environment', () => {
+    expect(resolveAttributeRedactor('strict', 'development')).toBe('strict');
+  });
+
+  it('honors an explicit custom config object', () => {
+    const config = { keyPatterns: [/password/i] };
+    expect(resolveAttributeRedactor(config, 'production')).toBe(config);
+  });
+
+  it('disables redaction when explicitly set to false, even in production', () => {
+    expect(resolveAttributeRedactor(false, 'production')).toBeUndefined();
+  });
+
+  it('lets AUTOTEL_REDACT_PII=off disable auto-enable in production', () => {
+    process.env.AUTOTEL_REDACT_PII = 'off';
+    expect(resolveAttributeRedactor(undefined, 'production')).toBeUndefined();
+  });
+
+  it('lets AUTOTEL_REDACT_PII select a preset in any environment', () => {
+    process.env.AUTOTEL_REDACT_PII = 'strict';
+    expect(resolveAttributeRedactor(undefined, 'development')).toBe('strict');
+  });
+
+  it('treats AUTOTEL_REDACT_PII truthy flags as the default preset', () => {
+    process.env.AUTOTEL_REDACT_PII = 'true';
+    expect(resolveAttributeRedactor(undefined, 'development')).toBe('default');
+  });
+});

package/src/init.ts

@@ -1023,7 +1023,12 @@ export interface AutotelConfig {
    * Automatically redact PII and sensitive data from span attributes before export.
    * Critical for compliance (GDPR, PCI-DSS, HIPAA) and data security.
    *
-   * Can be a preset name or custom configuration:
+   * Auto-enabled in production: when this is left unset and the resolved
+   * environment is `production`, the `'default'` preset is applied. Override
+   * with the `AUTOTEL_REDACT_PII` env var (`off` / `strict` / `pci-dss` / ...)
+   * or pass `false` to disable redaction entirely.
+   *
+   * Can be a preset name, custom configuration, or `false` to disable:
    * - `'default'`: Emails, phones, SSNs, credit cards, sensitive keys (password, secret, token)
    * - `'strict'`: Default + Bearer tokens, JWTs, API keys in values
    * - `'pci-dss'`: Payment card industry focus (credit cards, CVV, card-related keys)
@@ -1064,7 +1069,7 @@ export interface AutotelConfig {
    * })
    * ```
    */
-  attributeRedactor?: AttributeRedactorConfig | AttributeRedactorPreset;
+  attributeRedactor?: AttributeRedactorConfig | AttributeRedactorPreset | false;
 
   /**
    * OpenLLMetry integration for LLM observability.
@@ -1264,6 +1269,34 @@ function wrapLogger(
   };
 }
 
+/**
+ * Resolve the effective attribute redactor. Explicit config wins (`false`
+ * disables). Otherwise the `AUTOTEL_REDACT_PII` env var controls it, and as a
+ * final default PII redaction is auto-enabled in production.
+ */
+export function resolveAttributeRedactor(
+  explicit: AttributeRedactorConfig | AttributeRedactorPreset | false | undefined,
+  environment: string,
+): AttributeRedactorConfig | AttributeRedactorPreset | undefined {
+  if (explicit === false) return undefined;
+  if (explicit !== undefined) return explicit;
+
+  const flag = process.env.AUTOTEL_REDACT_PII?.trim().toLowerCase();
+  if (flag) {
+    if (['off', 'false', '0', 'none', 'disabled'].includes(flag)) {
+      return undefined;
+    }
+    if (flag === 'default' || flag === 'strict' || flag === 'pci-dss') {
+      return flag;
+    }
+    if (['on', 'true', '1', 'enabled'].includes(flag)) {
+      return 'default';
+    }
+  }
+
+  return environment === 'production' ? 'default' : undefined;
+}
+
 function detectEnvironmentAttributes(): Record<string, string> {
   const attrs: Record<string, string> = {};
 
@@ -1456,10 +1489,15 @@ export function init(cfg: AutotelConfig): void {
     headers: cfg.headers ?? yamlConfig.headers ?? envConfig.headers,
   } as AutotelConfig;
 
-  if (mergedConfig.attributeRedactor !== undefined) {
-    const normalizedRedactor = normalizeAttributeRedactorConfig(
-      mergedConfig.attributeRedactor,
-    );
+  const resolvedRedactor = resolveAttributeRedactor(
+    mergedConfig.attributeRedactor,
+    mergedConfig.environment || process.env.NODE_ENV || 'development',
+  );
+  if (resolvedRedactor === undefined) {
+    mergedConfig.attributeRedactor = undefined;
+  } else {
+    const normalizedRedactor =
+      normalizeAttributeRedactorConfig(resolvedRedactor);
     if (!normalizedRedactor) {
       throw new Error('Invalid attributeRedactor config');
     }
@@ -1664,10 +1702,11 @@ export function init(cfg: AutotelConfig): void {
 
   // Step 1: Wrap with AttributeRedactingProcessor (innermost - executes last in onEnd)
   if (mergedConfig.attributeRedactor && spanProcessors.length > 0) {
+    const redactor = mergedConfig.attributeRedactor;
     spanProcessors = spanProcessors.map(
       (processor) =>
         new AttributeRedactingProcessor(processor, {
-          redactor: mergedConfig.attributeRedactor!,
+          redactor,
         }),
     );
   }

package/src/track.ts

@@ -15,6 +15,7 @@ import {
 } from './init';
 import { validateEvent } from './validation';
 import { getOrCreateCorrelationId } from './correlation-id';
+import type { EventTrackingOptions } from './event-subscriber';
 import type { AutotelEventContext } from './event-subscriber';
 
 // Global events queue (initialized on first track call)
@@ -167,6 +168,7 @@ function getOrCreateQueue(): EventQueue | null {
 export function track<Events extends Record<string, any> = Record<string, any>>(
   event: keyof Events & string,
   data?: Events[typeof event],
+  options?: EventTrackingOptions,
 ): void {
   const queue = getOrCreateQueue();
   if (!queue) return; // No-op if not initialized or no subscribers
@@ -193,6 +195,7 @@ export function track<Events extends Record<string, any> = Record<string, any>>(
     attributes: enrichedData,
     timestamp: Date.now(),
     autotel: autotelContext,
+    schema: options?.schema,
   });
 }
 

package/src/validation.test.ts

@@ -298,17 +298,21 @@ describe('Sensitive data patterns', () => {
     expect(result?.API_KEY).toBe('[REDACTED]');
   });
 
-  it('should redact auth fields', () => {
+  it('should redact auth fields (strings only)', () => {
     const attrs = {
       auth: 'abc123',
       authorization: 'Bearer token',
-      authenticated: true, // Contains "auth" but should still be redacted
+      // `authenticated` matches the /auth/i key pattern, but `true` is a
+      // boolean status — not a credential — so it passes through unchanged.
+      // Redacting it to the string '[REDACTED]' would silently corrupt its
+      // type without protecting any secret.
+      authenticated: true,
     };
 
     const result = validateAttributes(attrs);
     expect(result?.auth).toBe('[REDACTED]');
     expect(result?.authorization).toBe('[REDACTED]');
-    expect(result?.authenticated).toBe('[REDACTED]');
+    expect(result?.authenticated).toBe(true);
   });
 
   it('should not redact non-sensitive fields with similar names', () => {

package/src/validation.ts

@@ -130,19 +130,22 @@ export function validateAttributes(
       );
     }
 
-    // Check for sensitive field
-    const isSensitive = config.sensitivePatterns.some((pattern) =>
-      pattern.test(key),
-    );
+    const value = attributes[key];
+
+    // Redact sensitive *strings* only. Numeric/boolean values are not
+    // credentials and replacing them with the literal string '[REDACTED]'
+    // both leaks no useful signal and breaks downstream type expectations
+    // (e.g. an LLM `promptTokens` counter becoming a string poisons every
+    // consumer that treats it as a number).
+    const isSensitive =
+      typeof value === 'string' &&
+      config.sensitivePatterns.some((pattern) => pattern.test(key));
 
     if (isSensitive) {
-      // Redact sensitive data
       sanitized[key] = '[REDACTED]';
       continue;
     }
 
-    // Sanitize value
-    const value = attributes[key];
     sanitized[key] = sanitizeValue(value, config, 1) as
       | string
       | number
@@ -196,20 +199,15 @@ function sanitizeValue(
       const sanitized: Record<string, unknown> = {};
       for (const key in value) {
         if (Object.prototype.hasOwnProperty.call(value, key)) {
-          // Check for sensitive field in nested objects
-          const isSensitive = config.sensitivePatterns.some((pattern) =>
-            pattern.test(key),
-          );
-
-          if (isSensitive) {
-            sanitized[key] = '[REDACTED]';
-          } else {
-            sanitized[key] = sanitizeValue(
-              (value as Record<string, unknown>)[key],
-              config,
-              depth + 1,
-            );
-          }
+          const nested = (value as Record<string, unknown>)[key];
+          // See top-level branch above: only string values are redacted.
+          const isSensitive =
+            typeof nested === 'string' &&
+            config.sensitivePatterns.some((pattern) => pattern.test(key));
+
+          sanitized[key] = isSensitive
+            ? '[REDACTED]'
+            : sanitizeValue(nested, config, depth + 1);
         }
       }
       return sanitized;