autotel 2.1.0

package/src/track.ts

@@ -0,0 +1,120 @@
+/**
+ * Global track() function for business events
+ *
+ * Simple, no instantiation needed, auto-attaches trace context
+ */
+
+import { trace } from '@opentelemetry/api';
+import { EventQueue } from './event-queue';
+import {
+  getConfig,
+  warnIfNotInitialized,
+  isInitialized,
+  getValidationConfig,
+} from './init';
+import { validateEvent } from './validation';
+
+// Global events queue (initialized on first track call)
+let eventsQueue: EventQueue | null = null;
+
+/**
+ * Initialize events queue lazily
+ */
+function getOrCreateQueue(): EventQueue | null {
+  if (!isInitialized()) {
+    warnIfNotInitialized('track()');
+    return null;
+  }
+
+  if (!eventsQueue) {
+    const config = getConfig();
+    if (!config?.subscribers || config.subscribers.length === 0) {
+      // No subscribers configured - no-op
+      return null;
+    }
+
+    eventsQueue = new EventQueue(config.subscribers);
+  }
+
+  return eventsQueue;
+}
+
+/**
+ * Track a business events event
+ *
+ * Features:
+ * - Auto-attaches traceId and spanId if in active span
+ * - Batched sending with retry
+ * - Type-safe with optional generic
+ * - No-op if init() not called or no subscribers configured
+ *
+ * @example Basic usage
+ * ```typescript
+ * track('user.signup', { userId: '123', plan: 'pro' })
+ * ```
+ *
+ * @example With type safety
+ * ```typescript
+ * interface EventDatas {
+ *   'user.signup': { userId: string; plan: string }
+ *   'plan.upgraded': { userId: string; revenue: number }
+ * }
+ *
+ * track<EventDatas>('user.signup', { userId: '123', plan: 'pro' })
+ * ```
+ *
+ * @example Trace correlation (automatic)
+ * ```typescript
+ * @Instrumented()
+ * class UserService {
+ *   async createUser(data: CreateUserData) {
+ *     // This track call automatically includes traceId + spanId
+ *     track('user.signup', { userId: data.id })
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function track<Events extends Record<string, any> = Record<string, any>>(
+  event: keyof Events & string,
+  data?: Events[typeof event],
+): void {
+  const queue = getOrCreateQueue();
+  if (!queue) return; // No-op if not initialized or no subscribers
+
+  // Validate and sanitize input (with custom config if provided)
+  const validationConfig = getValidationConfig();
+  const validated = validateEvent(event, data, validationConfig || undefined);
+
+  // Auto-attach trace context if available (free win!)
+  const span = trace.getActiveSpan();
+  const enrichedData = span
+    ? {
+        ...validated.attributes,
+        traceId: span.spanContext().traceId,
+        spanId: span.spanContext().spanId,
+      }
+    : validated.attributes;
+
+  queue.enqueue({
+    name: validated.eventName,
+    attributes: enrichedData,
+    timestamp: Date.now(),
+  });
+}
+
+/**
+ * Get events queue (for flush/shutdown)
+ * @internal
+ */
+export function getEventQueue(): EventQueue | null {
+  return eventsQueue;
+}
+
+/**
+ * Reset events queue (for shutdown/cleanup)
+ * @internal
+ */
+export function resetEventQueue(): void {
+  eventsQueue = null;
+}

package/src/validation.test.ts

@@ -0,0 +1,306 @@
+/**
+ * Tests for input validation
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  validateEventName,
+  validateAttributes,
+  validateEvent,
+  ValidationError,
+  getDefaultValidationConfig,
+} from './validation';
+
+describe('validateEventName()', () => {
+  it('should accept valid event names', () => {
+    expect(validateEventName('user.signup')).toBe('user.signup');
+    expect(validateEventName('order_completed')).toBe('order_completed');
+    expect(validateEventName('feature-used')).toBe('feature-used');
+    expect(validateEventName('app123.event456')).toBe('app123.event456');
+  });
+
+  it('should trim whitespace', () => {
+    expect(validateEventName('  user.signup  ')).toBe('user.signup');
+  });
+
+  it('should reject empty event names', () => {
+    expect(() => validateEventName('')).toThrow(ValidationError);
+    expect(() => validateEventName('   ')).toThrow(ValidationError);
+  });
+
+  it('should reject non-string event names', () => {
+    expect(() => validateEventName(123 as any)).toThrow(ValidationError);
+
+    expect(() => validateEventName(null as any)).toThrow(ValidationError);
+
+    expect(() => validateEventName(undefined as any)).toThrow(ValidationError);
+  });
+
+  it('should reject event names that are too long', () => {
+    const longName = 'a'.repeat(101);
+    expect(() => validateEventName(longName)).toThrow(ValidationError);
+  });
+
+  it('should reject event names with invalid characters', () => {
+    expect(() => validateEventName('user signup')).toThrow(ValidationError);
+    expect(() => validateEventName('user@signup')).toThrow(ValidationError);
+    expect(() => validateEventName('user/signup')).toThrow(ValidationError);
+    expect(() => validateEventName(String.raw`user\signup`)).toThrow(
+      ValidationError,
+    );
+  });
+});
+
+describe('validateAttributes()', () => {
+  it('should accept valid attributes', () => {
+    const attrs = {
+      userId: '123',
+      plan: 'pro',
+      count: 5,
+      active: true,
+    };
+
+    expect(validateAttributes(attrs)).toEqual(attrs);
+  });
+
+  it('should handle undefined attributes', () => {
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    expect(validateAttributes(undefined)).toBeUndefined();
+  });
+
+  it('should reject non-object attributes', () => {
+    expect(() => validateAttributes('string' as any)).toThrow(ValidationError);
+
+    expect(() => validateAttributes(123 as any)).toThrow(ValidationError);
+
+    expect(() => validateAttributes([] as any)).toThrow(ValidationError);
+  });
+
+  it('should reject too many attributes', () => {
+    const config = getDefaultValidationConfig();
+    const attrs: Record<string, unknown> = {};
+    for (let i = 0; i < config.maxAttributeCount + 1; i++) {
+      attrs[`key${i}`] = 'value';
+    }
+
+    expect(() =>
+      validateAttributes(attrs as Record<string, string | number | boolean>),
+    ).toThrow(ValidationError);
+  });
+
+  it('should reject attribute keys that are too long', () => {
+    const longKey = 'a'.repeat(101);
+    const attrs = { [longKey]: 'value' };
+
+    expect(() => validateAttributes(attrs)).toThrow(ValidationError);
+  });
+
+  it('should truncate long string values', () => {
+    const longValue = 'a'.repeat(1500);
+    const attrs = { field: longValue };
+
+    const result = validateAttributes(attrs);
+    expect(result?.field).toBe('a'.repeat(1000) + '...');
+  });
+
+  it('should redact sensitive fields', () => {
+    const attrs = {
+      email: 'user@example.com',
+      password: 'secret123',
+      apiKey: 'abc123',
+      normalField: 'value',
+    };
+
+    const result = validateAttributes(attrs);
+    expect(result?.email).toBe('user@example.com');
+    expect(result?.password).toBe('[REDACTED]');
+    expect(result?.apiKey).toBe('[REDACTED]');
+    expect(result?.normalField).toBe('value');
+  });
+
+  it('should handle nested objects within depth limit', () => {
+    const attrs = {
+      user: {
+        profile: {
+          name: 'John',
+        },
+      },
+    };
+
+    const result = validateAttributes(
+      attrs as unknown as Record<string, string | number | boolean>,
+    );
+    expect(result).toEqual(attrs);
+  });
+
+  it('should truncate deeply nested objects', () => {
+    const attrs = {
+      level1: {
+        level2: {
+          level3: {
+            level4: {
+              tooDeep: 'value',
+            },
+          },
+        },
+      },
+    };
+
+    const result = validateAttributes(attrs as any) as any;
+    expect(result.level1.level2.level3.level4).toBe('[MAX_DEPTH_EXCEEDED]');
+  });
+
+  it('should handle arrays', () => {
+    const attrs = {
+      tags: ['tag1', 'tag2', 'tag3'],
+      scores: [1, 2, 3],
+    };
+
+    const result = validateAttributes(attrs as any);
+    expect(result).toEqual(attrs);
+  });
+
+  it('should handle circular references', () => {
+    const circular: any = { name: 'test' };
+    circular.self = circular;
+
+    const attrs = { data: circular };
+
+    const result = validateAttributes(attrs) as any;
+    expect(result.data).toBe('[CIRCULAR]');
+  });
+
+  it('should handle null and undefined values', () => {
+    const attrs = {
+      nullable: null,
+      undefinedField: undefined,
+      normalField: 'value',
+    };
+
+    const result = validateAttributes(attrs as any);
+    expect(result?.nullable).toBeNull();
+    expect(result?.undefinedField).toBeUndefined();
+    expect(result?.normalField).toBe('value');
+  });
+
+  it('should handle unsupported types', () => {
+    const attrs = {
+      func: () => {},
+      symbol: Symbol('test'),
+      normalField: 'value',
+    };
+
+    const result = validateAttributes(attrs as any);
+    expect(result?.func).toBe('[function]');
+    expect(result?.symbol).toBe('[symbol]');
+    expect(result?.normalField).toBe('value');
+  });
+});
+
+describe('validateEvent()', () => {
+  it('should validate both event name and attributes', () => {
+    const result = validateEvent('user.signup', {
+      userId: '123',
+      password: 'secret',
+    });
+
+    expect(result.eventName).toBe('user.signup');
+    expect(result.attributes?.userId).toBe('123');
+    expect(result.attributes?.password).toBe('[REDACTED]');
+  });
+
+  it('should handle events without attributes', () => {
+    const result = validateEvent('page.viewed');
+
+    expect(result.eventName).toBe('page.viewed');
+    expect(result.attributes).toBeUndefined();
+  });
+
+  it('should allow custom validation config', () => {
+    const result = validateEvent(
+      'test.event',
+      { field: 'value' },
+      { maxEventNameLength: 50 },
+    );
+
+    expect(result.eventName).toBe('test.event');
+    expect(result.attributes?.field).toBe('value');
+  });
+
+  it('should throw on invalid event name', () => {
+    expect(() => validateEvent('', { userId: '123' })).toThrow(ValidationError);
+  });
+
+  it('should throw on invalid attributes', () => {
+    expect(() => validateEvent('user.signup', 'invalid' as any)).toThrow(
+      ValidationError,
+    );
+  });
+});
+
+describe('Sensitive data patterns', () => {
+  it('should redact password fields', () => {
+    const attrs = {
+      password: 'secret',
+      userPassword: 'secret',
+      PASSWORD: 'secret',
+    };
+
+    const result = validateAttributes(attrs);
+    expect(result?.password).toBe('[REDACTED]');
+    expect(result?.userPassword).toBe('[REDACTED]');
+    expect(result?.PASSWORD).toBe('[REDACTED]');
+  });
+
+  it('should redact token fields', () => {
+    const attrs = {
+      token: 'abc123',
+      accessToken: 'abc123',
+      auth_token: 'abc123',
+    };
+
+    const result = validateAttributes(attrs);
+    expect(result?.token).toBe('[REDACTED]');
+    expect(result?.accessToken).toBe('[REDACTED]');
+    expect(result?.auth_token).toBe('[REDACTED]');
+  });
+
+  it('should redact API key fields', () => {
+    const attrs = {
+      apiKey: 'abc123',
+      api_key: 'abc123',
+      API_KEY: 'abc123',
+    };
+
+    const result = validateAttributes(attrs);
+    expect(result?.apiKey).toBe('[REDACTED]');
+    expect(result?.api_key).toBe('[REDACTED]');
+    expect(result?.API_KEY).toBe('[REDACTED]');
+  });
+
+  it('should redact auth fields', () => {
+    const attrs = {
+      auth: 'abc123',
+      authorization: 'Bearer token',
+      authenticated: true, // Contains "auth" but should still be redacted
+    };
+
+    const result = validateAttributes(attrs);
+    expect(result?.auth).toBe('[REDACTED]');
+    expect(result?.authorization).toBe('[REDACTED]');
+    expect(result?.authenticated).toBe('[REDACTED]');
+  });
+
+  it('should not redact non-sensitive fields with similar names', () => {
+    const attrs = {
+      email: 'user@example.com',
+      username: 'john',
+      userId: '123',
+    };
+
+    const result = validateAttributes(attrs);
+    expect(result?.email).toBe('user@example.com');
+    expect(result?.username).toBe('john');
+    expect(result?.userId).toBe('123');
+  });
+});

package/src/validation.ts

@@ -0,0 +1,239 @@
+/**
+ * Input validation for events events and attributes
+ *
+ * Prevents:
+ * - Invalid event names
+ * - Oversized payloads
+ * - Circular references
+ * - Sensitive data leaks
+ */
+
+import type { EventAttributes } from './event-subscriber';
+
+export interface ValidationConfig {
+  /** Max event name length (default: 100) */
+  maxEventNameLength: number;
+  /** Max attribute key length (default: 100) */
+  maxAttributeKeyLength: number;
+  /** Max attribute value length for strings (default: 1000) */
+  maxAttributeValueLength: number;
+  /** Max total attributes per event (default: 50) */
+  maxAttributeCount: number;
+  /** Max nesting depth for objects (default: 3) */
+  maxNestingDepth: number;
+  /** Sensitive field patterns to redact */
+  sensitivePatterns: RegExp[];
+}
+
+const DEFAULT_CONFIG: ValidationConfig = {
+  maxEventNameLength: 100,
+  maxAttributeKeyLength: 100,
+  maxAttributeValueLength: 1000,
+  maxAttributeCount: 50,
+  maxNestingDepth: 3,
+  sensitivePatterns: [
+    /password/i,
+    /secret/i,
+    /token/i,
+    /api[_-]?key/i,
+    /access[_-]?key/i,
+    /private[_-]?key/i,
+    /auth/i,
+    /credential/i,
+    /ssn/i,
+    /credit[_-]?card/i,
+  ],
+};
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Validate and sanitize event name
+ * Throws ValidationError if invalid
+ */
+export function validateEventName(
+  eventName: string,
+  config: ValidationConfig = DEFAULT_CONFIG,
+): string {
+  // Check type
+  if (typeof eventName !== 'string') {
+    throw new ValidationError(
+      `Event name must be a string, got ${typeof eventName}`,
+    );
+  }
+
+  // Check non-empty
+  const trimmed = eventName.trim();
+  if (trimmed.length === 0) {
+    throw new ValidationError('Event name cannot be empty');
+  }
+
+  // Check length
+  if (trimmed.length > config.maxEventNameLength) {
+    throw new ValidationError(
+      `Event name too long (${trimmed.length} chars). ` +
+        `Max: ${config.maxEventNameLength}`,
+    );
+  }
+
+  // Check valid characters (alphanumeric, dots, underscores, hyphens)
+  if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+    throw new ValidationError(
+      `Event name contains invalid characters: "${trimmed}". ` +
+        'Use only letters, numbers, dots, underscores, and hyphens.',
+    );
+  }
+
+  return trimmed;
+}
+
+/**
+ * Validate and sanitize attributes
+ * Returns sanitized attributes (sensitive data redacted)
+ */
+export function validateAttributes(
+  attributes: EventAttributes | undefined,
+  config: ValidationConfig = DEFAULT_CONFIG,
+): EventAttributes | undefined {
+  if (attributes === undefined || attributes === null) {
+    return undefined;
+  }
+
+  // Check type
+  if (typeof attributes !== 'object' || Array.isArray(attributes)) {
+    throw new ValidationError('Attributes must be an object');
+  }
+
+  // Count attributes
+  const keys = Object.keys(attributes);
+  if (keys.length > config.maxAttributeCount) {
+    throw new ValidationError(
+      `Too many attributes (${keys.length}). ` +
+        `Max: ${config.maxAttributeCount}`,
+    );
+  }
+
+  // Validate and sanitize each attribute
+  const sanitized: EventAttributes = {};
+
+  for (const key of keys) {
+    // Validate key
+    if (key.length > config.maxAttributeKeyLength) {
+      throw new ValidationError(
+        `Attribute key too long: "${key.slice(0, 20)}..." ` +
+          `(${key.length} chars). Max: ${config.maxAttributeKeyLength}`,
+      );
+    }
+
+    // Check for sensitive field
+    const isSensitive = 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
+      | boolean;
+  }
+
+  return sanitized;
+}
+
+/**
+ * Sanitize attribute value (recursive)
+ */
+function sanitizeValue(
+  value: unknown,
+  config: ValidationConfig,
+  depth: number,
+): unknown {
+  // Check nesting depth
+  if (depth > config.maxNestingDepth) {
+    return '[MAX_DEPTH_EXCEEDED]';
+  }
+
+  // Handle null/undefined
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // Handle primitives
+  if (typeof value === 'string') {
+    if (value.length > config.maxAttributeValueLength) {
+      return value.slice(0, config.maxAttributeValueLength) + '...';
+    }
+    return value;
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return value;
+  }
+
+  // Handle arrays
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeValue(item, config, depth + 1));
+  }
+
+  // Handle objects
+  if (typeof value === 'object') {
+    try {
+      // Check for circular references
+      JSON.stringify(value);
+
+      const sanitized: Record<string, unknown> = {};
+      for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          sanitized[key] = sanitizeValue(
+            (value as Record<string, unknown>)[key],
+            config,
+            depth + 1,
+          );
+        }
+      }
+      return sanitized;
+    } catch {
+      // Circular reference detected
+      return '[CIRCULAR]';
+    }
+  }
+
+  // Unsupported type (function, symbol, etc.)
+  return `[${typeof value}]`;
+}
+
+/**
+ * Validate and sanitize an events event
+ * Returns { eventName, attributes } with sanitized values
+ */
+export function validateEvent(
+  eventName: string,
+  attributes?: EventAttributes,
+  config?: Partial<ValidationConfig>,
+): { eventName: string; attributes?: EventAttributes } {
+  const fullConfig = { ...DEFAULT_CONFIG, ...config };
+
+  return {
+    eventName: validateEventName(eventName, fullConfig),
+    attributes: validateAttributes(attributes, fullConfig),
+  };
+}
+
+/**
+ * Get default validation config (for testing/customization)
+ */
+export function getDefaultValidationConfig(): ValidationConfig {
+  return { ...DEFAULT_CONFIG };
+}