autotel 3.1.1 → 3.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AutotelConfig, i as init, a as isLoggerLocked, l as lockLogger } from './init-BSyIyDs5.js';
+export { A as AutotelConfig, i as init, a as isLoggerLocked, l as lockLogger } from './init-DyE43paw.js';
 import { Span, Context, trace as trace$2 } from '@opentelemetry/api';
 export { AttributeValue, Attributes, Baggage, BaggageEntry, Context, Exception, HrTime, Link, ROOT_CONTEXT, Span, SpanAttributes, SpanContext, SpanKind, Link as SpanLink, SpanStatusCode, TextMapGetter, TextMapSetter, TimeInput, TraceFlags, TraceState, Tracer, TracerProvider, context, trace as otelTrace, propagation } from '@opentelemetry/api';
 import { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
@@ -8,7 +8,7 @@ import { AttributeRedactorConfig, AttributeRedactorPreset } from './attribute-re
 export { AttributeRedactingProcessor, AttributeRedactingProcessorOptions, AttributeRedactorFn, BuiltinPatternName, MaskFn, REDACTOR_PATTERNS, REDACTOR_PRESETS, ValuePatternConfig, builtinPatterns, createAttributeRedactor, createRedactedSpan, normalizeAttributeRedactorConfig } from './attribute-redacting-processor.js';
 import { trace as trace$1 } from './functional.js';
 export { InstrumentOptions, SpanOptions, WithBaggageOptions, WithNewContextOptions, ctx, instrument, markAsImmediate, span, withBaggage, withNewContext, withTracing } from './functional.js';
-import { EventSubscriber, EventAttributes, AutotelEventContext } from './event-subscriber.js';
+import { EventSubscriber, EventAttributes, AutotelEventContext, EventSchemaMetadata, EventTrackingOptions } from './event-subscriber.js';
 export { FunnelStatus, OutcomeStatus } from './event-subscriber.js';
 export { CORRELATION_ID_BAGGAGE_KEY, generateCorrelationId, getCorrelationId, getOrCreateCorrelationId, runWithCorrelationId, setCorrelationId, setCorrelationIdInBaggage } from './correlation-id.js';
 import { T as TraceContext, A as AttributeValue } from './trace-context-DbGKd1Rn.js';
@@ -202,6 +202,8 @@ interface EventData {
     _traceId?: string;
     /** Autotel context for trace correlation (passed to subscribers) */
     autotel?: AutotelEventContext;
+    /** Optional schema metadata for contract-aware subscribers. */
+    schema?: EventSchemaMetadata;
 }
 interface QueueConfig {
     maxSize: number;
@@ -368,13 +370,33 @@ declare class EventQueue {
  * }
  * ```
  */
-declare function track<Events extends Record<string, any> = Record<string, any>>(event: keyof Events & string, data?: Events[typeof event]): void;
+declare function track<Events extends Record<string, any> = Record<string, any>>(event: keyof Events & string, data?: Events[typeof event], options?: EventTrackingOptions): void;
 /**
  * Get events queue (for flush/shutdown)
  * @internal
  */
 declare function getEventQueue(): EventQueue | null;
 
+type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: unknown;
+};
+interface SchemaLike<T> {
+    safeParse(input: unknown): SafeParseResult<T>;
+}
+interface DefineEventOptions<S> {
+    toJsonSchema?: (schema: S) => unknown;
+}
+interface DefinedEvent<Name extends string, Payload> {
+    readonly name: Name;
+    readonly schemaMetadata?: EventSchemaMetadata;
+    track(payload: Payload): void;
+}
+declare function defineEvent<Name extends string, Payload, S extends SchemaLike<Payload>>(name: Name, schema: S, options?: DefineEventOptions<S>): DefinedEvent<Name, Payload>;
+
 /**
  * Graceful shutdown with flush and cleanup
  */
@@ -499,6 +521,125 @@ declare function structuredErrorToJSON(error: StructuredError): Record<string, u
 declare function getStructuredErrorAttributes(error: Error): Record<string, AttributeValue>;
 declare function recordStructuredError(ctx: Pick<TraceContext, 'setAttributes' | 'setStatus'>, error: Error): void;
 
+/**
+ * Typed error and audit catalogs.
+ *
+ * Group related errors into one catalog and get a refactor-safe builder per
+ * code, with autocomplete at every call site and typed message parameters.
+ *
+ * @example
+ * ```typescript
+ * import { defineErrorCatalog } from 'autotel';
+ *
+ * export const billing = defineErrorCatalog('billing', {
+ *   PAYMENT_DECLINED: {
+ *     status: 402,
+ *     message: 'Card declined',
+ *     why: 'The issuer rejected the charge',
+ *     fix: 'Try a different payment method',
+ *   },
+ *   INSUFFICIENT_FUNDS: {
+ *     status: 402,
+ *     message: ({ available, required }: { available: number; required: number }) =>
+ *       `Insufficient funds: $${available} of $${required}`,
+ *   },
+ * });
+ *
+ * throw billing.PAYMENT_DECLINED({ cause: stripeError });
+ * throw billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });
+ *
+ * // In a catch block — refactor-safe, no magic strings:
+ * if (billing.PAYMENT_DECLINED.match(err)) { ... }
+ * ```
+ */
+
+/** Definition of a single error in a catalog. */
+interface ErrorCatalogEntry {
+    /**
+     * Human-readable message. Use a function to interpolate typed parameters;
+     * the parameter type flows through to the call site.
+     */
+    message: string | ((params: never) => string);
+    /** HTTP status to surface to clients. */
+    status?: number;
+    /** Stable error code. Defaults to `${namespace}.${KEY}`. */
+    code?: string | number;
+    /** Why it happened. A function receives the same params as `message`. */
+    why?: string | ((params: never) => string);
+    /** What the caller should do next. */
+    fix?: string;
+    /** Docs or runbook link. */
+    link?: string;
+    /** Error name. Defaults to the catalog key. */
+    name?: string;
+}
+/** Per-call options passed alongside (or instead of) typed params. */
+interface ErrorBuildOptions {
+    cause?: unknown;
+    details?: Record<string, unknown>;
+    /** Backend-only context. Never serialized to clients. */
+    internal?: Record<string, unknown>;
+}
+type ParamsOf<E> = E extends {
+    message: (params: infer P) => string;
+} ? P : E extends {
+    why: (params: infer P) => string;
+} ? P : void;
+type BuilderArgs<E extends ErrorCatalogEntry> = ParamsOf<E> extends void ? [options?: ErrorBuildOptions] : [params: ParamsOf<E>, options?: ErrorBuildOptions];
+/** A callable error factory produced by {@link defineErrorCatalog}. */
+interface ErrorBuilder<E extends ErrorCatalogEntry> {
+    (...args: BuilderArgs<E>): StructuredError;
+    /** Stable code assigned to every error from this entry. */
+    readonly code: string | number;
+    /** True when `error` was produced by this catalog entry. */
+    match(error: unknown): boolean;
+}
+type ErrorCatalog<T extends Record<string, ErrorCatalogEntry>> = {
+    readonly [K in keyof T]: ErrorBuilder<T[K]>;
+};
+/** True when `error` was produced by any autotel error catalog. */
+declare function isCatalogError(error: unknown): error is StructuredError;
+/** Returns the catalog code of `error`, or `undefined` if it has none. */
+declare function getCatalogCode(error: unknown): string | number | undefined;
+/**
+ * Define a typed error catalog. Returns an object whose keys are error
+ * builders. Each builder produces a {@link StructuredError} carrying the
+ * entry's message, status, code, why, fix, and link.
+ */
+declare function defineErrorCatalog<const T extends Record<string, ErrorCatalogEntry>>(namespace: string, entries: T): ErrorCatalog<T>;
+/** Severity of an audit action. */
+type AuditSeverity = 'info' | 'warn' | 'critical';
+/** Definition of a single action in an audit catalog. */
+interface AuditCatalogEntry {
+    /** Human-readable description. Use a function for typed params. */
+    message?: string | ((params: never) => string);
+    /** Stable action name. Defaults to `${namespace}.${KEY}`. */
+    action?: string;
+    /** Severity of the action. Defaults to `'info'`. */
+    severity?: AuditSeverity;
+}
+/** A resolved audit action descriptor produced by an audit catalog. */
+interface AuditAction {
+    readonly action: string;
+    readonly severity: AuditSeverity;
+    readonly message?: string;
+}
+type AuditDescriptorArgs<E extends AuditCatalogEntry> = ParamsOf<E> extends void ? [] : [params: ParamsOf<E>];
+/** A callable audit-action descriptor produced by {@link defineAuditCatalog}. */
+interface AuditDescriptor<E extends AuditCatalogEntry> {
+    (...args: AuditDescriptorArgs<E>): AuditAction;
+    readonly action: string;
+    readonly severity: AuditSeverity;
+}
+type AuditCatalog<T extends Record<string, AuditCatalogEntry>> = {
+    readonly [K in keyof T]: AuditDescriptor<T[K]>;
+};
+/**
+ * Define a typed audit catalog. Returns typed action descriptors you can pass
+ * to `track()` or audit helpers without scattering magic strings.
+ */
+declare function defineAuditCatalog<const T extends Record<string, AuditCatalogEntry>>(namespace: string, entries: T): AuditCatalog<T>;
+
 /**
  * Convert an unknown value to an OTel-compatible AttributeValue.
  * Returns undefined when the value cannot be represented.
@@ -767,4 +908,68 @@ declare function recordToolCall(ctx: TraceContext, event: ToolCallEvent): void;
  */
 declare function recordStreamFirstToken(ctx: TraceContext, event?: StreamFirstTokenEvent): void;
 
-export { AttributeRedactorConfig, AttributeRedactorPreset, BaggageSpanProcessor, type BaggageSpanProcessorOptions, type DrainOptions, type EnrichContext, type EnricherDefinition, type EnricherOptions, EventAttributes, EventSubscriber, type ForkLifecycle, type ForkOptions, GEN_AI_COST_USD_BUCKETS, GEN_AI_DURATION_BUCKETS_SECONDS, GEN_AI_TOKEN_USAGE_BUCKETS, type HttpDrainOptions, type HttpDrainRequest, type OperationContext, type PromptSentEvent, type RequestLogSnapshot, type RequestLogger, type RequestLoggerOptions, type ResponseReceivedEvent, type RetryEvent, type StreamFirstTokenEvent, type StringRedactor, type StructuredError, type StructuredErrorInput, type ToolCallEvent, TraceContext, createStringRedactor, createStructuredError, defineDrain, defineEnricher, defineHttpDrain, flattenToAttributes, flush, formatDuration, genAiMetricViews, getEventQueue, getOperationContext, getRequestLogger, getStructuredErrorAttributes, llmHistogramAdvice, recordPromptSent, recordResponseReceived, recordRetry, recordStreamFirstToken, recordStructuredError, recordToolCall, runInOperationContext, runWithRequestContext, shutdown, structuredErrorToJSON, toAttributeValue, trace, track };
+/**
+ * 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;
+ * });
+ * ```
+ */
+
+/** Span attribute key autotel sets for an estimated call cost. */
+declare const GEN_AI_COST_ATTRIBUTE = "gen_ai.usage.cost.usd";
+/** Pricing for a single model, in USD per 1,000,000 tokens. */
+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. */
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    /** Cached input tokens, billed at {@link ModelPricing.cachedInputPer1M}. */
+    cachedInputTokens?: number;
+}
+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`).
+ */
+declare const MODEL_PRICING: Record<string, ModelPricing>;
+/**
+ * Estimate the USD cost of an LLM call. Returns `undefined` when the model has
+ * no known pricing (supply one via `options.pricing`).
+ */
+declare function estimateLLMCost(model: string, usage: TokenUsage, options?: EstimateCostOptions): number | undefined;
+/**
+ * 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).
+ */
+declare function recordLLMCost(ctx: Pick<TraceContext, 'setAttribute'>, model: string, usage: TokenUsage, options?: EstimateCostOptions): number | undefined;
+
+export { AttributeRedactorConfig, AttributeRedactorPreset, type AuditAction, type AuditCatalog, type AuditCatalogEntry, type AuditDescriptor, type AuditSeverity, BaggageSpanProcessor, type BaggageSpanProcessorOptions, type DefineEventOptions, type DefinedEvent, type DrainOptions, type EnrichContext, type EnricherDefinition, type EnricherOptions, type ErrorBuildOptions, type ErrorBuilder, type ErrorCatalog, type ErrorCatalogEntry, type EstimateCostOptions, EventAttributes, EventSubscriber, type ForkLifecycle, type ForkOptions, GEN_AI_COST_ATTRIBUTE, GEN_AI_COST_USD_BUCKETS, GEN_AI_DURATION_BUCKETS_SECONDS, GEN_AI_TOKEN_USAGE_BUCKETS, type HttpDrainOptions, type HttpDrainRequest, MODEL_PRICING, type ModelPricing, type OperationContext, type PromptSentEvent, type RequestLogSnapshot, type RequestLogger, type RequestLoggerOptions, type ResponseReceivedEvent, type RetryEvent, type SchemaLike, type StreamFirstTokenEvent, type StringRedactor, type StructuredError, type StructuredErrorInput, type TokenUsage, type ToolCallEvent, TraceContext, createStringRedactor, createStructuredError, defineAuditCatalog, defineDrain, defineEnricher, defineErrorCatalog, defineEvent, defineHttpDrain, estimateLLMCost, flattenToAttributes, flush, formatDuration, genAiMetricViews, getCatalogCode, getEventQueue, getOperationContext, getRequestLogger, getStructuredErrorAttributes, isCatalogError, llmHistogramAdvice, recordLLMCost, recordPromptSent, recordResponseReceived, recordRetry, recordStreamFirstToken, recordStructuredError, recordToolCall, runInOperationContext, runWithRequestContext, shutdown, structuredErrorToJSON, toAttributeValue, trace, track };

package/dist/index.js

@@ -1,34 +1,34 @@
 export { createDrainPipeline } from './chunk-KFOHQK7X.js';
-export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-PEEUMQ3R.js';
-export { attrs, autoRedactPII, dbClient, httpClient, httpServer, identify, mergeAttrs, mergeServiceResource, request, safeSetAttributes, setDevice, setError, setException, setSession, setUser, validateAttribute } from './chunk-DDXIUZEG.js';
+export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-FZROHTZZ.js';
+export { attrs, autoRedactPII, dbClient, httpClient, httpServer, identify, mergeAttrs, mergeServiceResource, request, safeSetAttributes, setDevice, setError, setException, setSession, setUser, validateAttribute } from './chunk-454CH4OV.js';
 export { httpRequestHeaderAttribute, httpResponseHeaderAttribute } from './chunk-7552UTQW.js';
 export { HTTPAttributes, ServiceAttributes, URLAttributes } from './chunk-4A53YIAX.js';
 export { parseError } from './chunk-J7VGRIAJ.js';
-export { traceConsumer, traceProducer } from './chunk-6TFJF7SS.js';
+export { traceConsumer, traceProducer } from './chunk-4TAQQZDU.js';
 import { emitCorrelatedEvent } from './chunk-KIL5CUN6.js';
 export { BusinessBaggage, createSafeBaggageSchema } from './chunk-4IFSYQVX.js';
 import { resetMetrics } from './chunk-7SAWIN74.js';
 export { Metric, getMetrics, resetMetrics } from './chunk-7SAWIN74.js';
 import './chunk-5ZN622AO.js';
 export { createCounter, createHistogram, createObservableGauge, createUpDownCounter, getMeter } from './chunk-TQ5UWA7S.js';
-export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-52ALHU7T.js';
-import { trace as trace$1 } from './chunk-T7CPAGOI.js';
-export { ctx, instrument, markAsImmediate, span, withBaggage, withNewContext, withTracing } from './chunk-T7CPAGOI.js';
+export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-OPCTN527.js';
+import { trace as trace$1 } from './chunk-U4D5IBSB.js';
+export { ctx, instrument, markAsImmediate, span, withBaggage, withNewContext, withTracing } from './chunk-U4D5IBSB.js';
 export { createDeterministicTraceId, enrichWithTraceContext, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTraceContext, getTracer, isTracing, resolveTraceUrl, runWithSpan } from './chunk-HLZ7H3VZ.js';
-import { resetEvents } from './chunk-MHPYLMQS.js';
-export { Event, getEvents, resetEvents } from './chunk-MHPYLMQS.js';
+import { resetEvents } from './chunk-OACAWYLR.js';
+export { Event, getEvents, resetEvents } from './chunk-OACAWYLR.js';
 import './chunk-LITNXTTT.js';
 import './chunk-BZHG5IZ4.js';
 export { getOperationContext, runInOperationContext } from './chunk-SEO6NAQT.js';
-import { getEventQueue, resetEventQueue, createTraceContext, flattenToAttributes, recordStructuredError } from './chunk-FTBBBPT6.js';
-export { CORRELATION_ID_BAGGAGE_KEY, createStructuredError, defineBaggageSchema, flattenToAttributes, generateCorrelationId, getCorrelationId, getEventQueue, getOrCreateCorrelationId, getStructuredErrorAttributes, recordStructuredError, runWithCorrelationId, setCorrelationId, setCorrelationIdInBaggage, structuredErrorToJSON, toAttributeValue, track } from './chunk-FTBBBPT6.js';
-import { getLogger, getSdk, _closeEmbeddedDevtools } from './chunk-MYWQELNY.js';
-export { BaggageSpanProcessor, createStringRedactor, init, isLoggerLocked, lockLogger } from './chunk-MYWQELNY.js';
+import { getEventQueue, resetEventQueue, track, createTraceContext, flattenToAttributes, recordStructuredError, createStructuredError } from './chunk-TGV2XF57.js';
+export { CORRELATION_ID_BAGGAGE_KEY, createStructuredError, defineBaggageSchema, flattenToAttributes, generateCorrelationId, getCorrelationId, getEventQueue, getOrCreateCorrelationId, getStructuredErrorAttributes, recordStructuredError, runWithCorrelationId, setCorrelationId, setCorrelationIdInBaggage, structuredErrorToJSON, toAttributeValue, track } from './chunk-TGV2XF57.js';
+import { getLogger, getSdk, _closeEmbeddedDevtools } from './chunk-32AXF4MA.js';
+export { BaggageSpanProcessor, createStringRedactor, init, isLoggerLocked, lockLogger } from './chunk-32AXF4MA.js';
 import './chunk-643PQG3Y.js';
 import './chunk-A4E5AQFK.js';
 export { FilteringSpanProcessor } from './chunk-WGWSHJ2N.js';
 export { NORMALIZER_PATTERNS, NORMALIZER_PRESETS, SpanNameNormalizingProcessor } from './chunk-GYR5K654.js';
-export { AttributeRedactingProcessor, REDACTOR_PATTERNS, REDACTOR_PRESETS, builtinPatterns, createAttributeRedactor, createRedactedSpan, normalizeAttributeRedactorConfig } from './chunk-JVWJDHDB.js';
+export { AttributeRedactingProcessor, REDACTOR_PATTERNS, REDACTOR_PRESETS, builtinPatterns, createAttributeRedactor, createRedactedSpan, normalizeAttributeRedactorConfig } from './chunk-RUPKBKUF.js';
 import './chunk-6UQRVUN3.js';
 export { formatDuration } from './chunk-3QXBFGKP.js';
 import './chunk-KVDA4HX2.js';
@@ -38,6 +38,7 @@ import './chunk-J5QENANM.js';
 export { getAutotelTracer, getAutotelTracerProvider, setAutotelTracerProvider } from './chunk-HA2WBOGQ.js';
 import { trace } from '@opentelemetry/api';
 export { ROOT_CONTEXT, SpanKind, SpanStatusCode, context, trace as otelTrace, propagation } from '@opentelemetry/api';
+import { createHash } from 'crypto';
 import { AsyncLocalStorage } from 'async_hooks';
 import { AggregationType } from '@opentelemetry/sdk-metrics';
 
@@ -61,6 +62,45 @@ var trace2 = Object.assign(
   trace$1,
   otelMethods
 );
+function defineEvent(name, schema, options = {}) {
+  const jsonSchema = options.toJsonSchema?.(schema);
+  const schemaMetadata = jsonSchema ? {
+    source: "zod",
+    jsonSchema,
+    hash: hashSchema(jsonSchema)
+  } : void 0;
+  return {
+    name,
+    schemaMetadata,
+    track(payload) {
+      const parsed = schema.safeParse(payload);
+      if (!parsed.success) {
+        throw new Error(
+          `Invalid payload for event "${name}". Schema validation failed.`
+        );
+      }
+      track(
+        name,
+        parsed.data,
+        schemaMetadata ? { schema: schemaMetadata } : void 0
+      );
+    }
+  };
+}
+function hashSchema(schema) {
+  return createHash("sha256").update(stableStringify(schema)).digest("hex");
+}
+function stableStringify(value) {
+  if (value === null || value === void 0 || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => stableStringify(v)).join(",") + "]";
+  }
+  const obj = value;
+  const body = Object.keys(obj).sort().map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",");
+  return "{" + body + "}";
+}
 
 // src/shutdown.ts
 async function flush(options) {
@@ -369,6 +409,86 @@ function getRequestLogger(ctx2, options) {
   };
 }
 
+// src/error-catalog.ts
+var catalogCodeKey = /* @__PURE__ */ Symbol.for("autotel.catalog.code");
+function readCatalogCode(error) {
+  if (error === null || typeof error !== "object") return void 0;
+  return error[catalogCodeKey];
+}
+function isCatalogError(error) {
+  return readCatalogCode(error) !== void 0;
+}
+function getCatalogCode(error) {
+  return readCatalogCode(error);
+}
+function defineErrorCatalog(namespace, entries) {
+  const catalog = {};
+  for (const [key, entry] of Object.entries(entries)) {
+    const code = entry.code ?? `${namespace}.${key}`;
+    const usesParams = typeof entry.message === "function" || typeof entry.why === "function";
+    const builder = ((paramsOrOptions, maybeOptions) => {
+      const params = usesParams ? paramsOrOptions : void 0;
+      const options = usesParams ? maybeOptions : paramsOrOptions;
+      const message = typeof entry.message === "function" ? entry.message(params) : entry.message;
+      const why = typeof entry.why === "function" ? entry.why(params) : entry.why;
+      const error = createStructuredError({
+        message,
+        name: entry.name ?? key,
+        code,
+        ...entry.status === void 0 ? {} : { status: entry.status },
+        ...why === void 0 ? {} : { why },
+        ...entry.fix === void 0 ? {} : { fix: entry.fix },
+        ...entry.link === void 0 ? {} : { link: entry.link },
+        ...options?.cause === void 0 ? {} : { cause: options.cause },
+        ...options?.details === void 0 ? {} : { details: options.details },
+        ...options?.internal === void 0 ? {} : { internal: options.internal }
+      });
+      Object.defineProperty(error, catalogCodeKey, {
+        value: code,
+        enumerable: false,
+        writable: false,
+        configurable: true
+      });
+      return error;
+    });
+    Object.defineProperty(builder, "code", {
+      value: code,
+      enumerable: true
+    });
+    Object.defineProperty(builder, "match", {
+      value: (error) => readCatalogCode(error) === code,
+      enumerable: false
+    });
+    catalog[key] = builder;
+  }
+  return Object.freeze(catalog);
+}
+function defineAuditCatalog(namespace, entries) {
+  const catalog = {};
+  for (const [key, entry] of Object.entries(entries)) {
+    const action = entry.action ?? `${namespace}.${key}`;
+    const severity = entry.severity ?? "info";
+    const descriptor = ((params) => {
+      const message = typeof entry.message === "function" ? entry.message(params) : entry.message;
+      return Object.freeze({
+        action,
+        severity,
+        ...message === void 0 ? {} : { message }
+      });
+    });
+    Object.defineProperty(descriptor, "action", {
+      value: action,
+      enumerable: true
+    });
+    Object.defineProperty(descriptor, "severity", {
+      value: severity,
+      enumerable: true
+    });
+    catalog[key] = descriptor;
+  }
+  return Object.freeze(catalog);
+}
+
 // src/drain-toolkit.ts
 var DEFAULT_TIMEOUT_MS = 5e3;
 var DEFAULT_RETRIES = 2;
@@ -605,6 +725,63 @@ function buildStreamFirstTokenAttrs(event) {
   return attrs2;
 }
 
-export { GEN_AI_COST_USD_BUCKETS, GEN_AI_DURATION_BUCKETS_SECONDS, GEN_AI_TOKEN_USAGE_BUCKETS, defineDrain, defineEnricher, defineHttpDrain, flush, genAiMetricViews, getRequestLogger, llmHistogramAdvice, recordPromptSent, recordResponseReceived, recordRetry, recordStreamFirstToken, recordToolCall, runWithRequestContext, shutdown, trace2 as trace };
+// src/gen-ai-cost.ts
+var GEN_AI_COST_ATTRIBUTE = "gen_ai.usage.cost.usd";
+var MODEL_PRICING = {
+  // 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, model) {
+  const exact = table[model];
+  if (exact) return exact;
+  let best;
+  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) {
+  return Math.round(value * 1e6) / 1e6;
+}
+function estimateLLMCost(model, usage, options) {
+  const table = options?.pricing ? { ...MODEL_PRICING, ...options.pricing } : MODEL_PRICING;
+  const price = resolvePricing(table, model);
+  if (!price) return void 0;
+  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 / 1e6 * price.inputPer1M + cachedInput / 1e6 * cachedRate + output / 1e6 * price.outputPer1M;
+  return round(cost);
+}
+function recordLLMCost(ctx2, model, usage, options) {
+  const cost = estimateLLMCost(model, usage, options);
+  if (cost !== void 0) {
+    ctx2.setAttribute(GEN_AI_COST_ATTRIBUTE, cost);
+  }
+  return cost;
+}
+
+export { GEN_AI_COST_ATTRIBUTE, GEN_AI_COST_USD_BUCKETS, GEN_AI_DURATION_BUCKETS_SECONDS, GEN_AI_TOKEN_USAGE_BUCKETS, MODEL_PRICING, defineAuditCatalog, defineDrain, defineEnricher, defineErrorCatalog, defineEvent, defineHttpDrain, estimateLLMCost, flush, genAiMetricViews, getCatalogCode, getRequestLogger, isCatalogError, llmHistogramAdvice, recordLLMCost, recordPromptSent, recordResponseReceived, recordRetry, recordStreamFirstToken, recordToolCall, runWithRequestContext, shutdown, trace2 as trace };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map