autotel 4.1.0 → 4.2.0

package/src/event-subscriber.ts

@@ -1,262 +0,0 @@
-/**
- * Event Subscriber Interface (Type-only)
- *
- * Import this interface to create custom subscribers without importing implementations.
- * Keeps core package focused on OpenTelemetry with zero extra dependencies.
- *
- * For ready-made subscribers (PostHog, Mixpanel, Amplitude, Segment),
- * see the separate `autotel-subscribers` package.
- *
- * @example Custom subscriber
- * ```typescript
- * import { EventSubscriber } from 'autotel/event-subscriber';
- *
- * class MyCustomSubscriber implements EventSubscriber {
- *   trackEvent(name: string, attributes?: Record<string, any>): void {
- *     // Send to your events platform
- *   }
- *   // ... implement other methods
- * }
- * ```
- *
- * @example Use pre-built subscribers
- * ```typescript
- * import { Events } from 'autotel/events';
- * import { PostHogSubscriber } from 'autotel-subscribers/posthog';
- * import { MixpanelSubscriber } from 'autotel-subscribers/mixpanel';
- *
- * const event =new Event('checkout', {
- *   subscribers: [
- *     new PostHogSubscriber({ apiKey: 'phc_...' }),
- *     new MixpanelSubscriber({ token: '...' })
- *   ]
- * });
- * ```
- */
-
-/**
- * Event attributes (supports any JSON-serializable values)
- *
- * Allows primitive types for flat attributes and unknown for flexibility
- * with nested objects when using subscribers that support JSON payloads
- * (e.g., WebhookSubscriber).
- */
-export type EventAttributes = Record<string, unknown>;
-
-/**
- * Permissive input type for event attributes
- *
- * Accepts undefined/null values which will be filtered out before sending.
- * This improves DX when working with optional properties from objects.
- *
- * @example
- * ```typescript
- * // No need to filter out undefined values manually
- * event.trackEvent('user.action', {
- *   userId: user.id,
- *   email: user.email,        // might be undefined
- *   plan: user.subscription,  // might be null
- * });
- * ```
- */
-export type EventAttributesInput = Record<
-  string,
-  string | number | boolean | undefined | null
->;
-
-/**
- * Funnel step status
- */
-export type FunnelStatus = 'started' | 'completed' | 'abandoned' | 'failed';
-
-/**
- * Outcome status
- */
-export type OutcomeStatus = 'success' | 'failure' | 'partial';
-
-/**
- * Autotel event context for trace correlation
- *
- * This structured object contains trace context and correlation IDs.
- * Subscribers decide how to map/flatten these for their platform.
- */
-export interface AutotelEventContext {
-  /** Trace ID (32 hex chars) - present when inside a trace */
-  trace_id?: string;
-  /** Span ID (16 hex chars) - present when inside a span */
-  span_id?: string;
-  /** Trace flags (2 hex chars, e.g., '01' for sampled) */
-  trace_flags?: string;
-  /** Raw tracestate string - present if tracestate exists */
-  trace_state?: string;
-  /** Clickable trace URL - present if traceUrl config is set */
-  trace_url?: string;
-  /** Correlation ID (always present, 16 hex chars) */
-  correlation_id: string;
-  /** Number of linked parent traces (batch/fan-in scenarios) */
-  linked_trace_id_count?: number;
-  /** Stable hash of linked trace IDs (default for batch/fan-in) */
-  linked_trace_id_hash?: string;
-  /** Full array of linked trace IDs (only if includeLinkedTraceIds: true) */
-  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;
-}
-
-/**
- * Event subscriber interface
- *
- * Implement this to send events to any platform.
- * Zero runtime dependencies - just types.
- *
- * All tracking methods are async to support:
- * - Backpressure signaling (buffer full)
- * - Streaming platforms (Kafka, Kinesis, Pub/Sub)
- * - Await delivery confirmation
- * - Proper error propagation
- */
-export interface EventSubscriber {
-  /**
-   * Track an event (e.g., "user.registered", "order.created")
-   *
-   * @param name - Event name
-   * @param attributes - Optional event attributes
-   * @param options - Optional tracking options including autotel context
-   * @returns Promise that resolves when event is sent (or buffered)
-   */
-  trackEvent(
-    name: string,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void>;
-
-  /**
-   * Track a funnel step (e.g., checkout: started → completed)
-   *
-   * @param funnelName - Funnel name
-   * @param step - Funnel step status
-   * @param attributes - Optional event attributes
-   * @param options - Optional tracking options including autotel context
-   * @returns Promise that resolves when event is sent (or buffered)
-   */
-  trackFunnelStep(
-    funnelName: string,
-    step: FunnelStatus,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void>;
-
-  /**
-   * Track an outcome (e.g., "payment.processing" → success/failure)
-   *
-   * @param operationName - Operation name
-   * @param outcome - Outcome status
-   * @param attributes - Optional event attributes
-   * @param options - Optional tracking options including autotel context
-   * @returns Promise that resolves when event is sent (or buffered)
-   */
-  trackOutcome(
-    operationName: string,
-    outcome: OutcomeStatus,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void>;
-
-  /**
-   * Track a value/metric (e.g., revenue, cart value)
-   *
-   * @param name - Metric name
-   * @param value - Numeric value
-   * @param attributes - Optional event attributes
-   * @param options - Optional tracking options including autotel context
-   * @returns Promise that resolves when event is sent (or buffered)
-   */
-  trackValue(
-    name: string,
-    value: number,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void>;
-
-  /**
-   * Track funnel progression with custom step names
-   *
-   * Unlike trackFunnelStep which uses FunnelStatus enum values,
-   * this method allows any string as the step name for flexible funnel tracking.
-   *
-   * @param funnelName - Name of the funnel (e.g., "checkout", "onboarding")
-   * @param stepName - Custom step name (e.g., "cart_viewed", "payment_entered")
-   * @param stepNumber - Optional numeric position in the funnel
-   * @param attributes - Optional event attributes
-   * @param options - Optional tracking options including autotel context
-   *
-   * @example
-   * ```typescript
-   * // Track custom checkout steps
-   * await subscriber.trackFunnelProgression('checkout', 'cart_viewed', 1);
-   * await subscriber.trackFunnelProgression('checkout', 'shipping_selected', 2);
-   * await subscriber.trackFunnelProgression('checkout', 'payment_entered', 3);
-   * await subscriber.trackFunnelProgression('checkout', 'order_confirmed', 4);
-   * ```
-   */
-  trackFunnelProgression?(
-    funnelName: string,
-    stepName: string,
-    stepNumber?: number,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void>;
-
-  /**
-   * Optional: Flush pending events and clean up resources
-   *
-   * Implement this if your subscriber buffers events, maintains connections,
-   * or needs cleanup before shutdown. Called during graceful shutdown.
-   *
-   * @example
-   * ```typescript
-   * class MySubscriber implements EventSubscriber {
-   *   async shutdown(): Promise<void> {
-   *     await this.flushBuffer();
-   *     await this.closeConnections();
-   *   }
-   * }
-   * ```
-   */
-  shutdown?(): Promise<void>;
-
-  /**
-   * Optional: Subscriber name for debugging and error reporting
-   *
-   * @example "PostHogSubscriber", "SnowflakeSubscriber", "CustomWebhookSubscriber"
-   */
-  readonly name?: string;
-
-  /**
-   * Optional: Subscriber version for debugging
-   *
-   * @example "1.0.0"
-   */
-  readonly version?: string;
-}

package/src/event-testing.ts

@@ -1,197 +0,0 @@
-/**
- * Testing utilities for Events
- *
- * Provides in-memory collection of events for testing purposes.
- */
-
-import type {
-  EventAttributes,
-  FunnelStatus,
-  OutcomeStatus,
-} from './event-subscriber';
-
-export interface EventData {
-  event: string;
-  attributes?: EventAttributes;
-  service: string;
-  timestamp: number;
-}
-
-export interface EventsFunnelStep {
-  funnel: string;
-  status: FunnelStatus;
-  attributes?: EventAttributes;
-  service: string;
-  timestamp: number;
-}
-
-export interface EventsOutcome {
-  operation: string;
-  status: OutcomeStatus;
-  attributes?: EventAttributes;
-  service: string;
-  timestamp: number;
-}
-
-export interface EventsValue {
-  metric: string;
-  value: number;
-  attributes?: EventAttributes;
-  service: string;
-  timestamp: number;
-}
-
-/**
- * In-memory events collector for testing
- */
-export interface EventCollector {
-  /** Get all collected events */
-  getEvents(): EventData[];
-  /** Get all collected funnel steps */
-  getFunnelSteps(): EventsFunnelStep[];
-  /** Get all collected outcomes */
-  getOutcomes(): EventsOutcome[];
-  /** Get all collected values */
-  getValues(): EventsValue[];
-  /** Clear all collected events */
-  clear(): void;
-  /** Record an event (internal use) */
-  recordEvent(event: EventData): void;
-  /** Record a funnel step (internal use) */
-  recordFunnelStep(step: EventsFunnelStep): void;
-  /** Record an outcome (internal use) */
-  recordOutcome(outcome: EventsOutcome): void;
-  /** Record a value (internal use) */
-  recordValue(value: EventsValue): void;
-}
-
-/**
- * Create an in-memory events collector for testing
- *
- * @example
- * ```typescript
- * const collector = createEventCollector()
- *
- * const events = new Event('test-service', { collector })
- * events.trackEvent('application.submitted', { jobId: '123' })
- *
- * const event =collector.getEvents()
- * expect(events).toHaveLength(1)
- * expect(events[0].event).toBe('application.submitted')
- * ```
- */
-export function createEventCollector(): EventCollector {
-  const events: EventData[] = [];
-  const funnelSteps: EventsFunnelStep[] = [];
-  const outcomes: EventsOutcome[] = [];
-  const values: EventsValue[] = [];
-
-  return {
-    getEvents(): EventData[] {
-      return [...events];
-    },
-
-    getFunnelSteps(): EventsFunnelStep[] {
-      return [...funnelSteps];
-    },
-
-    getOutcomes(): EventsOutcome[] {
-      return [...outcomes];
-    },
-
-    getValues(): EventsValue[] {
-      return [...values];
-    },
-
-    clear(): void {
-      events.length = 0;
-      funnelSteps.length = 0;
-      outcomes.length = 0;
-      values.length = 0;
-    },
-
-    recordEvent(event: EventData): void {
-      events.push(event);
-    },
-
-    recordFunnelStep(step: EventsFunnelStep): void {
-      funnelSteps.push(step);
-    },
-
-    recordOutcome(outcome: EventsOutcome): void {
-      outcomes.push(outcome);
-    },
-
-    recordValue(value: EventsValue): void {
-      values.push(value);
-    },
-  };
-}
-
-/**
- * Assert that an events event was tracked
- *
- * @example
- * ```typescript
- * assertEventTracked({
- *   collector,
- *   eventName: 'application.submitted',
- *   attributes: { jobId: '123' }
- * })
- * ```
- */
-export function assertEventTracked(options: {
-  collector: EventCollector;
-  eventName: string;
-  attributes?: Record<string, unknown>;
-}): void {
-  const events = options.collector.getEvents();
-  const matching = events.filter((e) => e.event === options.eventName);
-
-  if (matching.length === 0) {
-    throw new Error(`No events found with name: ${options.eventName}`);
-  }
-
-  if (options.attributes) {
-    const matchingWithAttrs = matching.filter((e) =>
-      Object.entries(options.attributes!).every(
-        ([key, value]) => e.attributes && e.attributes[key] === value,
-      ),
-    );
-
-    if (matchingWithAttrs.length === 0) {
-      throw new Error(
-        `Event ${options.eventName} found but attributes don't match: ${JSON.stringify(options.attributes)}`,
-      );
-    }
-  }
-}
-
-/**
- * Assert that an outcome was tracked
- *
- * @example
- * ```typescript
- * assertOutcomeTracked({
- *   collector,
- *   operation: 'email.delivery',
- *   status: 'success'
- * })
- * ```
- */
-export function assertOutcomeTracked(options: {
-  collector: EventCollector;
-  operation: string;
-  status: 'success' | 'failure' | 'partial';
-}): void {
-  const outcomes = options.collector.getOutcomes();
-  const matching = outcomes.filter(
-    (o) => o.operation === options.operation && o.status === options.status,
-  );
-
-  if (matching.length === 0) {
-    throw new Error(
-      `No outcomes found with operation: ${options.operation} and status: ${options.status}`,
-    );
-  }
-}