autotel 3.1.1 → 3.2.0

package/dist/workflow.cjs

@@ -1,17 +1,17 @@
 'use strict';
 
-var chunkMXO6LXV5_cjs = require('./chunk-MXO6LXV5.cjs');
+var chunk5RZ3NZ2M_cjs = require('./chunk-5RZ3NZ2M.cjs');
 require('./chunk-4P6ZOARG.cjs');
-require('./chunk-KPDIEVVV.cjs');
+require('./chunk-EEQHQKPP.cjs');
 require('./chunk-2GIBANLB.cjs');
 require('./chunk-VQTCQKHQ.cjs');
-require('./chunk-LIYNUGML.cjs');
-require('./chunk-45B2GD4P.cjs');
+require('./chunk-UV64CWMA.cjs');
+require('./chunk-KKIYPZOP.cjs');
 require('./chunk-FEEVB2GV.cjs');
 require('./chunk-CEAQK2QY.cjs');
 require('./chunk-ZNMBW67B.cjs');
 require('./chunk-IOYFAFHJ.cjs');
-require('./chunk-NXLRY2CE.cjs');
+require('./chunk-NEIB3TLD.cjs');
 require('./chunk-CU6IDACR.cjs');
 require('./chunk-6S5RUKU3.cjs');
 require('./chunk-HR5YFXZW.cjs');
@@ -24,19 +24,19 @@ require('./chunk-YREV3LGG.cjs');
 
 Object.defineProperty(exports, "getCurrentWorkflowContext", {
   enumerable: true,
-  get: function () { return chunkMXO6LXV5_cjs.getCurrentWorkflowContext; }
+  get: function () { return chunk5RZ3NZ2M_cjs.getCurrentWorkflowContext; }
 });
 Object.defineProperty(exports, "isInWorkflow", {
   enumerable: true,
-  get: function () { return chunkMXO6LXV5_cjs.isInWorkflow; }
+  get: function () { return chunk5RZ3NZ2M_cjs.isInWorkflow; }
 });
 Object.defineProperty(exports, "traceStep", {
   enumerable: true,
-  get: function () { return chunkMXO6LXV5_cjs.traceStep; }
+  get: function () { return chunk5RZ3NZ2M_cjs.traceStep; }
 });
 Object.defineProperty(exports, "traceWorkflow", {
   enumerable: true,
-  get: function () { return chunkMXO6LXV5_cjs.traceWorkflow; }
+  get: function () { return chunk5RZ3NZ2M_cjs.traceWorkflow; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map

package/dist/workflow.js

@@ -1,15 +1,15 @@
-export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-PEEUMQ3R.js';
+export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-IS2QJ44P.js';
 import './chunk-KIL5CUN6.js';
-import './chunk-T7CPAGOI.js';
+import './chunk-FVA2YDEQ.js';
 import './chunk-HLZ7H3VZ.js';
 import './chunk-SEO6NAQT.js';
-import './chunk-FTBBBPT6.js';
-import './chunk-MYWQELNY.js';
+import './chunk-7EVW3Z37.js';
+import './chunk-ZKKJQS6R.js';
 import './chunk-643PQG3Y.js';
 import './chunk-A4E5AQFK.js';
 import './chunk-WGWSHJ2N.js';
 import './chunk-GYR5K654.js';
-import './chunk-JVWJDHDB.js';
+import './chunk-RUPKBKUF.js';
 import './chunk-6UQRVUN3.js';
 import './chunk-3QXBFGKP.js';
 import './chunk-KVDA4HX2.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/attribute-redacting-processor.ts

@@ -424,19 +424,22 @@ function createRedactorFromConfig(
     .map((vp) => [cloneRegex(vp.pattern), vp.mask!]);
 
   return (key: string, value: AttributeValue): AttributeValue => {
-    // Check if key matches any sensitive key pattern
-    for (const pattern of keyPatterns) {
-      pattern.lastIndex = 0;
-      if (pattern.test(key)) {
+    // Key-pattern and path-based redaction only applies to string values.
+    // Numbers, booleans and other non-string attributes are not credentials;
+    // replacing them with the string '[REDACTED]' silently changes their
+    // type and corrupts downstream consumers (LLM token counters etc.).
+    if (typeof value === 'string') {
+      for (const pattern of keyPatterns) {
+        pattern.lastIndex = 0;
+        if (pattern.test(key)) {
+          return defaultReplacement;
+        }
+      }
+      if (pathSet.has(key)) {
         return defaultReplacement;
       }
     }
 
-    // Check if key matches any path-based redaction
-    if (pathSet.has(key)) {
-      return defaultReplacement;
-    }
-
     // For non-string values, return as-is
     if (typeof value !== 'string') {
       if (Array.isArray(value)) {

package/src/define-event.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { defineEvent } from './define-event';
+
+describe('defineEvent', () => {
+  it('validates payload and exposes schema metadata when provided', () => {
+    const event = defineEvent(
+      'order.placed',
+      {
+        safeParse(input: unknown) {
+          if (
+            typeof input === 'object' &&
+            input !== null &&
+            'orderId' in input &&
+            typeof (input as Record<string, unknown>).orderId === 'string'
+          ) {
+            return {
+              success: true as const,
+              data: input as { orderId: string },
+            };
+          }
+          return { success: false as const, error: new Error('invalid') };
+        },
+      },
+      {
+        toJsonSchema: () => ({
+          type: 'object',
+          properties: { orderId: { type: 'string' } },
+          required: ['orderId'],
+        }),
+      },
+    );
+
+    expect(event.name).toBe('order.placed');
+    expect(event.schemaMetadata?.source).toBe('zod');
+    expect(event.schemaMetadata?.hash).toMatch(/^[a-f0-9]{64}$/);
+    expect(() => event.track({ orderId: 'o-1' })).not.toThrow();
+    expect(() => event.track({} as { orderId: string })).toThrow(
+      /Schema validation failed/,
+    );
+  });
+});

package/src/define-event.ts

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { track } from './track';
+import type { EventSchemaMetadata } from './event-subscriber';
+
+type SafeParseResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: unknown };
+
+export interface SchemaLike<T> {
+  safeParse(input: unknown): SafeParseResult<T>;
+}
+
+export interface DefineEventOptions<S> {
+  toJsonSchema?: (schema: S) => unknown;
+}
+
+export interface DefinedEvent<Name extends string, Payload> {
+  readonly name: Name;
+  readonly schemaMetadata?: EventSchemaMetadata;
+  track(payload: Payload): void;
+}
+
+export function defineEvent<
+  Name extends string,
+  Payload,
+  S extends SchemaLike<Payload>,
+>(
+  name: Name,
+  schema: S,
+  options: DefineEventOptions<S> = {},
+): DefinedEvent<Name, Payload> {
+  const jsonSchema = options.toJsonSchema?.(schema);
+  const schemaMetadata = jsonSchema
+    ? {
+        source: 'zod' as const,
+        jsonSchema,
+        hash: hashSchema(jsonSchema),
+      }
+    : undefined;
+
+  return {
+    name,
+    schemaMetadata,
+    track(payload: 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 } : undefined,
+      );
+    },
+  };
+}
+
+function hashSchema(schema: unknown): string {
+  return createHash('sha256').update(stableStringify(schema)).digest('hex');
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
+  }
+  const obj = value as Record<string, unknown>;
+  const body = Object.keys(obj)
+    .sort()
+    .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
+    .join(',');
+  return '{' + body + '}';
+}

package/src/event-queue.ts

@@ -22,6 +22,7 @@ import type {
   EventSubscriber,
   EventAttributes,
   AutotelEventContext,
+  EventSchemaMetadata,
 } from './event-subscriber';
 import { getLogger } from './init';
 import { getConfig as getRuntimeConfig } from './config';
@@ -38,6 +39,8 @@ export interface EventData {
   _traceId?: string;
   /** Autotel context for trace correlation (passed to subscribers) */
   autotel?: AutotelEventContext;
+  /** Optional schema metadata for contract-aware subscribers. */
+  schema?: EventSchemaMetadata;
 }
 
 /**
@@ -591,6 +594,7 @@ export class EventQueue {
         try {
           await subscriber.trackEvent(event.name, event.attributes, {
             autotel: event.autotel,
+            schema: event.schema,
           });
           this.recordDelivered(event, subscriberName, startTime);
           return { subscriberName, success: true };

package/src/event-subscriber.ts

@@ -101,12 +101,27 @@ export interface AutotelEventContext {
   linked_trace_ids?: string[];
 }
 
+/**
+ * Optional machine-readable schema metadata attached to an event payload.
+ * Intended for contract-aware subscribers (e.g. architecture snapshot capture).
+ */
+export interface EventSchemaMetadata {
+  /** Schema source format used at the call site. */
+  source: 'zod';
+  /** JSON Schema representation of the payload contract. */
+  jsonSchema: unknown;
+  /** Stable schema hash for change detection and cache keys. */
+  hash: string;
+}
+
 /**
  * Options for event tracking methods
  */
 export interface EventTrackingOptions {
   /** Autotel trace context to include in the event */
   autotel?: AutotelEventContext;
+  /** Optional event payload schema metadata */
+  schema?: EventSchemaMetadata;
 }
 
 /**

package/src/functional.ts

@@ -210,7 +210,8 @@ function hasImmediateExecutionMark(fn: unknown): boolean {
  */
 export function markAsImmediate<F>(fn: F): F {
   if (typeof fn === 'function') {
-    (fn as unknown as ImmediateExecutionFlag)[IMMEDIATE_EXECUTION_SYMBOL] = true;
+    (fn as unknown as ImmediateExecutionFlag)[IMMEDIATE_EXECUTION_SYMBOL] =
+      true;
   }
   return fn;
 }

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 {

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;