autotel-subscribers 4.0.0

package/src/amplitude.test.ts

@@ -0,0 +1,231 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { AmplitudeSubscriber } from './amplitude';
+
+// Mock the @amplitude/analytics-node module
+const mockTrack = vi.fn();
+const mockTrackEvent = vi.fn();
+const mockFlush = vi.fn(() => Promise.resolve());
+
+// Create a mock init function that returns instances with mocked methods
+const mockInit = vi.fn(() => ({
+  track: mockTrack,
+  trackEvent: mockTrackEvent,
+  flush: mockFlush,
+}));
+
+vi.mock('@amplitude/analytics-node', () => ({
+  init: mockInit,
+}));
+
+describe('AmplitudeSubscriber', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockTrack.mockClear();
+    mockTrackEvent.mockClear();
+    mockFlush.mockClear();
+  });
+
+  describe('initialization', () => {
+    it('should initialize with valid config', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(adapter).toBeDefined();
+    });
+
+    it('should not initialize when disabled', () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+        enabled: false,
+      });
+
+      expect(adapter).toBeDefined();
+    });
+  });
+
+  describe('trackEvent', () => {
+    it('should track event with attributes', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      await adapter.trackEvent('order.completed', {
+        userId: 'user-123',
+        amount: 99.99,
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(mockTrack).toHaveBeenCalledWith({
+        event_type: 'order.completed',
+        user_id: 'user-123',
+        event_properties: {
+          userId: 'user-123',
+          amount: 99.99,
+        },
+      });
+    });
+
+    it('should use user_id if userId is not present', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      await adapter.trackEvent('order.completed', {
+        user_id: 'user-456',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(mockTrack).toHaveBeenCalledWith({
+        event_type: 'order.completed',
+        user_id: 'user-456',
+        event_properties: {
+          user_id: 'user-456',
+        },
+      });
+    });
+
+    it('should use anonymous if no userId is present', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      await adapter.trackEvent('page.viewed');
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(mockTrack).toHaveBeenCalledWith({
+        event_type: 'page.viewed',
+        user_id: 'anonymous',
+        event_properties: undefined,
+      });
+    });
+
+    it('should not track when disabled', () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+        enabled: false,
+      });
+
+      adapter.trackEvent('order.completed', { userId: 'user-123' });
+
+      // Should not throw
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('trackFunnelStep', () => {
+    it('should track funnel step', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      await adapter.trackFunnelStep('checkout', 'started', {
+        userId: 'user-123',
+        cartValue: 150,
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(mockTrackEvent).toHaveBeenCalledWith({
+        event_type: 'checkout.started',
+        user_id: 'user-123',
+        event_properties: {
+          funnel: 'checkout',
+          step: 'started',
+          userId: 'user-123',
+          cartValue: 150,
+        },
+      });
+    });
+  });
+
+  describe('trackOutcome', () => {
+    it('should track outcome', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      await adapter.trackOutcome('payment.processing', 'success', {
+        userId: 'user-123',
+        transactionId: 'txn-789',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(mockTrackEvent).toHaveBeenCalledWith({
+        event_type: 'payment.processing.success',
+        user_id: 'user-123',
+        event_properties: {
+          operation: 'payment.processing',
+          outcome: 'success',
+          userId: 'user-123',
+          transactionId: 'txn-789',
+        },
+      });
+    });
+  });
+
+  describe('trackValue', () => {
+    it('should track value', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      await adapter.trackValue('revenue', 99.99, {
+        userId: 'user-123',
+        currency: 'USD',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(mockTrackEvent).toHaveBeenCalledWith({
+        event_type: 'revenue',
+        user_id: 'user-123',
+        event_properties: {
+          value: 99.99,
+          userId: 'user-123',
+          currency: 'USD',
+        },
+      });
+    });
+  });
+
+  describe('shutdown', () => {
+    it('should call flush on Amplitude instance', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      await adapter.shutdown();
+
+      expect(mockFlush).toHaveBeenCalled();
+    });
+
+    it('should not throw when shutting down disabled adapter', async () => {
+      const adapter = new AmplitudeSubscriber({
+        apiKey: 'test_api_key',
+        enabled: false,
+      });
+
+      await expect(adapter.shutdown()).resolves.not.toThrow();
+    });
+  });
+});

package/src/amplitude.ts

@@ -0,0 +1,148 @@
+/**
+ * Amplitude Subscriber for autotel
+ *
+ * Send events to Amplitude for product events.
+ *
+ * @example
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { AmplitudeSubscriber } from 'autotel-subscribers/amplitude';
+ *
+ * const events = new Events('checkout', {
+ *   subscribers: [
+ *     new AmplitudeSubscriber({
+ *       apiKey: process.env.AMPLITUDE_API_KEY!
+ *     })
+ *   ]
+ * });
+ *
+ * events.trackEvent('order.completed', { userId: '123', amount: 99.99 });
+ * ```
+ */
+
+import type {
+  EventSubscriber,
+  EventAttributes,
+  FunnelStatus,
+  OutcomeStatus,
+} from 'autotel/event-subscriber';
+
+export interface AmplitudeConfig {
+  /** Amplitude API key */
+  apiKey: string;
+  /** Enable/disable the subscriber */
+  enabled?: boolean;
+}
+
+export class AmplitudeSubscriber implements EventSubscriber {
+  readonly name = 'AmplitudeSubscriber';
+  readonly version = '1.0.0';
+
+  private amplitude: any;
+  private enabled: boolean;
+  private config: AmplitudeConfig;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(config: AmplitudeConfig) {
+    this.enabled = config.enabled ?? true;
+    this.config = config;
+
+    if (this.enabled) {
+      // Start initialization immediately but don't block constructor
+      this.initPromise = this.initialize();
+    }
+  }
+
+  private async initialize(): Promise<void> {
+    try {
+      // Dynamic import to avoid adding @amplitude/events-node as a hard dependency
+      const { init } = await import('@amplitude/analytics-node');
+      this.amplitude = init(this.config.apiKey);
+    } catch (error) {
+      console.error(
+        'Amplitude subscriber failed to initialize. Install @amplitude/events-node: pnpm add @amplitude/events-node',
+        error,
+      );
+      this.enabled = false;
+    }
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.initPromise) {
+      await this.initPromise;
+      this.initPromise = null;
+    }
+  }
+
+  async trackEvent(name: string, attributes?: EventAttributes): Promise<void> {
+    if (!this.enabled) return;
+
+    await this.ensureInitialized();
+    this.amplitude?.track({
+      event_type: name,
+      user_id: attributes?.userId || attributes?.user_id || 'anonymous',
+      event_properties: attributes,
+    });
+  }
+
+  async trackFunnelStep(
+    funnelName: string,
+    step: FunnelStatus,
+    attributes?: EventAttributes,
+  ): Promise<void> {
+    if (!this.enabled) return;
+
+    await this.ensureInitialized();
+    this.amplitude?.trackEvent({
+      event_type: `${funnelName}.${step}`,
+      user_id: attributes?.userId || attributes?.user_id || 'anonymous',
+      event_properties: {
+        funnel: funnelName,
+        step,
+        ...attributes,
+      },
+    });
+  }
+
+  async trackOutcome(
+    operationName: string,
+    outcome: OutcomeStatus,
+    attributes?: EventAttributes,
+  ): Promise<void> {
+    if (!this.enabled) return;
+
+    await this.ensureInitialized();
+    this.amplitude?.trackEvent({
+      event_type: `${operationName}.${outcome}`,
+      user_id: attributes?.userId || attributes?.user_id || 'anonymous',
+      event_properties: {
+        operation: operationName,
+        outcome,
+        ...attributes,
+      },
+    });
+  }
+
+  async trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void> {
+    if (!this.enabled) return;
+
+    await this.ensureInitialized();
+    this.amplitude?.trackEvent({
+      event_type: name,
+      user_id: attributes?.userId || attributes?.user_id || 'anonymous',
+      event_properties: {
+        value,
+        ...attributes,
+      },
+    });
+  }
+
+  /** Flush pending events before shutdown */
+  async shutdown(): Promise<void> {
+    await this.ensureInitialized();
+    if (this.amplitude) {
+      await this.amplitude.flush();
+    }
+  }
+}
+

package/src/event-subscriber-base.ts

@@ -0,0 +1,325 @@
+/**
+ * EventSubscriber - Standard base class for building custom subscribers
+ *
+ * This is the recommended base class for creating custom events subscribers.
+ * It provides production-ready features out of the box:
+ *
+ * **Built-in Features:**
+ * - **Error Handling**: Automatic error catching with customizable handlers
+ * - **Pending Request Tracking**: Ensures all requests complete during shutdown
+ * - **Graceful Shutdown**: Drains pending requests before closing
+ * - **Enable/Disable**: Runtime control to turn subscriber on/off
+ * - **Normalized Payload**: Consistent event structure across all event types
+ *
+ * **When to use:**
+ * - Building custom subscribers for any platform
+ * - Production deployments requiring reliability
+ * - Need graceful shutdown and error handling
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { EventSubscriber, EventPayload } from 'autotel-subscribers';
+ *
+ * class SnowflakeSubscriber extends EventSubscriber {
+ *   name = 'SnowflakeSubscriber';
+ *   version = '1.0.0';
+ *
+ *   protected async sendToDestination(payload: EventPayload): Promise<void> {
+ *     await snowflakeClient.execute(
+ *       `INSERT INTO events VALUES (?, ?, ?)`,
+ *       [payload.type, payload.name, JSON.stringify(payload.attributes)]
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @example With buffering
+ * ```typescript
+ * class BufferedSubscriber extends EventSubscriber {
+ *   name = 'BufferedSubscriber';
+ *   private buffer: EventPayload[] = [];
+ *
+ *   protected async sendToDestination(payload: EventPayload): Promise<void> {
+ *     this.buffer.push(payload);
+ *
+ *     if (this.buffer.length >= 100) {
+ *       await this.flush();
+ *     }
+ *   }
+ *
+ *   async shutdown(): Promise<void> {
+ *     await super.shutdown(); // Drain pending requests first
+ *     await this.flush(); // Then flush buffer
+ *   }
+ *
+ *   private async flush(): Promise<void> {
+ *     if (this.buffer.length === 0) return;
+ *
+ *     const batch = [...this.buffer];
+ *     this.buffer = [];
+ *
+ *     await apiClient.sendBatch(batch);
+ *   }
+ * }
+ * ```
+ */
+
+import type {
+  EventSubscriber as IEventSubscriber,
+  EventAttributes,
+  FunnelStatus,
+  OutcomeStatus,
+} from 'autotel/event-subscriber';
+
+// Re-export types for convenience
+
+
+/**
+ * Payload sent to destination
+ */
+export interface EventPayload {
+  /** Event type: 'event', 'funnel', 'outcome', or 'value' */
+  type: 'event' | 'funnel' | 'outcome' | 'value';
+
+  /** Event name or metric name */
+  name: string;
+
+  /** Optional attributes */
+  attributes?: EventAttributes;
+
+  /** For funnel events: funnel name */
+  funnel?: string;
+
+  /** For funnel events: step status */
+  step?: FunnelStatus;
+
+  /** For outcome events: operation name */
+  operation?: string;
+
+  /** For outcome events: outcome status */
+  outcome?: OutcomeStatus;
+
+  /** For value events: numeric value */
+  value?: number;
+
+  /** Timestamp (ISO 8601) */
+  timestamp: string;
+}
+
+/**
+ * Standard base class for building custom events subscribers
+ *
+ * **What it provides:**
+ * - Consistent payload structure (normalized across all event types)
+ * - Enable/disable flag (runtime control)
+ * - Automatic error handling (with customizable error handlers)
+ * - Pending requests tracking (ensures no lost events during shutdown)
+ * - Graceful shutdown (drains pending requests before closing)
+ *
+ * **Usage:**
+ * Extend this class and implement `sendToDestination()`. All other methods
+ * (trackEvent, trackFunnelStep, trackOutcome, trackValue, shutdown) are handled automatically.
+ *
+ * For high-throughput streaming platforms (Kafka, Kinesis, Pub/Sub), use `StreamingEventSubscriber` instead.
+ */
+export abstract class EventSubscriber implements IEventSubscriber {
+  /**
+   * Subscriber name (required for debugging)
+   */
+  abstract readonly name: string;
+
+  /**
+   * Subscriber version (optional)
+   */
+  readonly version?: string;
+
+  /**
+   * Enable/disable the subscriber (default: true)
+   */
+  protected enabled: boolean = true;
+
+  /**
+   * Track pending requests for graceful shutdown
+   */
+  private pendingRequests: Set<Promise<void>> = new Set();
+
+  /**
+   * Send payload to destination
+   *
+   * Override this method to implement your destination-specific logic.
+   * This is called for all event types (event, funnel, outcome, value).
+   *
+   * @param payload - Normalized event payload
+   */
+  protected abstract sendToDestination(payload: EventPayload): Promise<void>;
+
+  /**
+   * Optional: Handle errors
+   *
+   * Override this to customize error handling (logging, retries, etc.).
+   * Default behavior: log to console.error
+   *
+   * @param error - Error that occurred
+   * @param payload - Event payload that failed
+   */
+  protected handleError(error: Error, payload: EventPayload): void {
+    console.error(
+      `[${this.name}] Failed to send ${payload.type}:`,
+      error,
+      payload,
+    );
+  }
+
+  /**
+   * Track an event
+   */
+  async trackEvent(name: string, attributes?: EventAttributes): Promise<void> {
+    if (!this.enabled) return;
+
+    const payload: EventPayload = {
+      type: 'event',
+      name,
+      attributes,
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.send(payload);
+  }
+
+  /**
+   * Track a funnel step
+   */
+  async trackFunnelStep(
+    funnelName: string,
+    step: FunnelStatus,
+    attributes?: EventAttributes,
+  ): Promise<void> {
+    if (!this.enabled) return;
+
+    const payload: EventPayload = {
+      type: 'funnel',
+      name: `${funnelName}.${step}`,
+      funnel: funnelName,
+      step,
+      attributes,
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.send(payload);
+  }
+
+  /**
+   * Track an outcome
+   */
+  async trackOutcome(
+    operationName: string,
+    outcome: OutcomeStatus,
+    attributes?: EventAttributes,
+  ): Promise<void> {
+    if (!this.enabled) return;
+
+    const payload: EventPayload = {
+      type: 'outcome',
+      name: `${operationName}.${outcome}`,
+      operation: operationName,
+      outcome,
+      attributes,
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.send(payload);
+  }
+
+  /**
+   * Track a value/metric
+   */
+  async trackValue(
+    name: string,
+    value: number,
+    attributes?: EventAttributes,
+  ): Promise<void> {
+    if (!this.enabled) return;
+
+    const payload: EventPayload = {
+      type: 'value',
+      name,
+      value,
+      attributes,
+      timestamp: new Date().toISOString(),
+    };
+
+    await this.send(payload);
+  }
+
+  /**
+   * Flush pending requests and clean up
+   *
+   * CRITICAL: Prevents race condition during shutdown
+   * 1. Disables subscriber to stop new events
+   * 2. Drains all pending requests (with retry logic)
+   * 3. Ensures flush guarantee
+   *
+   * Override this if you need custom cleanup logic (close connections, flush buffers, etc.),
+   * but ALWAYS call super.shutdown() first to drain pending requests.
+   */
+  async shutdown(): Promise<void> {
+    // 1. Stop accepting new events (prevents race condition)
+    this.enabled = false;
+
+    // 2. Drain pending requests with retry logic
+    // Loop until empty to handle race where new requests added during Promise.allSettled
+    const maxDrainAttempts = 10;
+    const drainIntervalMs = 50;
+
+    for (let attempt = 0; attempt < maxDrainAttempts; attempt++) {
+      if (this.pendingRequests.size === 0) {
+        break;
+      }
+
+      // Wait for current batch
+      await Promise.allSettled(this.pendingRequests);
+
+      // Small delay to catch any stragglers added during allSettled
+      if (this.pendingRequests.size > 0 && attempt < maxDrainAttempts - 1) {
+        await new Promise((resolve) => setTimeout(resolve, drainIntervalMs));
+      }
+    }
+
+    // 3. Warn if we still have pending requests (shouldn't happen, but be defensive)
+    if (this.pendingRequests.size > 0) {
+      console.warn(
+        `[${this.name}] Shutdown completed with ${this.pendingRequests.size} pending requests still in-flight. ` +
+        `This may indicate a bug in the subscriber or extremely slow destination.`
+      );
+    }
+  }
+
+  /**
+   * Internal: Send payload and track request
+   */
+  private async send(payload: EventPayload): Promise<void> {
+    const request = this.sendWithErrorHandling(payload);
+    this.pendingRequests.add(request);
+
+    void request.finally(() => {
+      this.pendingRequests.delete(request);
+    });
+
+    return request;
+  }
+
+  /**
+   * Internal: Send with error handling
+   */
+  private async sendWithErrorHandling(
+    payload: EventPayload,
+  ): Promise<void> {
+    try {
+      await this.sendToDestination(payload);
+    } catch (error) {
+      this.handleError(error as Error, payload);
+    }
+  }
+}
+
+export {type EventAttributes, type FunnelStatus, type OutcomeStatus} from 'autotel/event-subscriber';