autotel-subscribers 4.0.0

package/src/segment.test.ts

@@ -0,0 +1,228 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { SegmentSubscriber } from './segment';
+
+// Mock the @segment/analytics-node module
+const mockTrack = vi.fn();
+const mockCloseAndFlush = vi.fn(() => Promise.resolve());
+
+// Create a mock Analytics class that returns instances with mocked methods
+const MockAnalytics = vi.fn(function(this: any) {
+  this.track = mockTrack;
+  this.closeAndFlush = mockCloseAndFlush;
+  return this;
+});
+
+vi.mock('@segment/analytics-node', () => ({
+  Analytics: MockAnalytics,
+}));
+
+describe('SegmentSubscriber', () => {
+  beforeEach(() => {
+    mockTrack.mockClear();
+    mockCloseAndFlush.mockClear();
+  });
+
+  describe('initialization', () => {
+    it('should initialize with valid config', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(adapter).toBeDefined();
+    });
+
+    it('should not initialize when disabled', () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_key',
+        enabled: false,
+      });
+
+      expect(adapter).toBeDefined();
+    });
+  });
+
+  describe('trackEvent', () => {
+    it('should track event with attributes', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_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({
+        userId: 'user-123',
+        event: 'order.completed',
+        properties: {
+          userId: 'user-123',
+          amount: 99.99,
+        },
+      });
+    });
+
+    it('should use user_id if userId is not present', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_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({
+        userId: 'user-456',
+        event: 'order.completed',
+        properties: {
+          user_id: 'user-456',
+        },
+      });
+    });
+
+    it('should use anonymous if no userId is present', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      await adapter.trackEvent('page.viewed');
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(mockTrack).toHaveBeenCalledWith({
+        userId: 'anonymous',
+        event: 'page.viewed',
+        properties: undefined,
+      });
+    });
+
+    it('should not track when disabled', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_key',
+        enabled: false,
+      });
+
+      await 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 SegmentSubscriber({
+        writeKey: 'test_write_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(mockTrack).toHaveBeenCalledWith({
+        userId: 'user-123',
+        event: 'checkout.started',
+        properties: {
+          funnel: 'checkout',
+          step: 'started',
+          userId: 'user-123',
+          cartValue: 150,
+        },
+      });
+    });
+  });
+
+  describe('trackOutcome', () => {
+    it('should track outcome', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_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(mockTrack).toHaveBeenCalledWith({
+        userId: 'user-123',
+        event: 'payment.processing.success',
+        properties: {
+          operation: 'payment.processing',
+          outcome: 'success',
+          userId: 'user-123',
+          transactionId: 'txn-789',
+        },
+      });
+    });
+  });
+
+  describe('trackValue', () => {
+    it('should track value', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_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(mockTrack).toHaveBeenCalledWith({
+        userId: 'user-123',
+        event: 'revenue',
+        properties: {
+          value: 99.99,
+          userId: 'user-123',
+          currency: 'USD',
+        },
+      });
+    });
+  });
+
+  describe('shutdown', () => {
+    it('should call closeAndFlush on Events instance', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_key',
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      await adapter.shutdown();
+
+      expect(mockCloseAndFlush).toHaveBeenCalled();
+    });
+
+    it('should not throw when shutting down disabled adapter', async () => {
+      const adapter = new SegmentSubscriber({
+        writeKey: 'test_write_key',
+        enabled: false,
+      });
+
+      await expect(adapter.shutdown()).resolves.not.toThrow();
+    });
+  });
+});

package/src/segment.ts

@@ -0,0 +1,148 @@
+/**
+ * Segment Subscriber for autotel
+ *
+ * Send events to Segment (customer data platform).
+ *
+ * @example
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { SegmentSubscriber } from 'autotel-subscribers/segment';
+ *
+ * const events = new Events('checkout', {
+ *   subscribers: [
+ *     new SegmentSubscriber({
+ *       writeKey: process.env.SEGMENT_WRITE_KEY!
+ *     })
+ *   ]
+ * });
+ *
+ * events.trackEvent('order.completed', { userId: '123', amount: 99.99 });
+ * ```
+ */
+
+import type {
+  EventSubscriber,
+  EventAttributes,
+  FunnelStatus,
+  OutcomeStatus,
+} from 'autotel/event-subscriber';
+
+export interface SegmentConfig {
+  /** Segment write key */
+  writeKey: string;
+  /** Enable/disable the subscriber */
+  enabled?: boolean;
+}
+
+export class SegmentSubscriber implements EventSubscriber {
+  readonly name = 'SegmentSubscriber';
+  readonly version = '1.0.0';
+
+  private events: any;
+  private enabled: boolean;
+  private config: SegmentConfig;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(config: SegmentConfig) {
+    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 @segment/events-node as a hard dependency
+      const { Analytics } = await import('@segment/analytics-node');
+      this.events = new Analytics({ writeKey: this.config.writeKey });
+    } catch (error) {
+      console.error(
+        'Segment subscriber failed to initialize. Install @segment/events-node: pnpm add @segment/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.events?.track({
+      userId: attributes?.userId || attributes?.user_id || 'anonymous',
+      event: name,
+      properties: attributes,
+    });
+  }
+
+  async trackFunnelStep(
+    funnelName: string,
+    step: FunnelStatus,
+    attributes?: EventAttributes,
+  ): Promise<void> {
+    if (!this.enabled) return;
+
+    await this.ensureInitialized();
+    this.events?.track({
+      userId: attributes?.userId || attributes?.user_id || 'anonymous',
+      event: `${funnelName}.${step}`,
+      properties: {
+        funnel: funnelName,
+        step,
+        ...attributes,
+      },
+    });
+  }
+
+  async trackOutcome(
+    operationName: string,
+    outcome: OutcomeStatus,
+    attributes?: EventAttributes,
+  ): Promise<void> {
+    if (!this.enabled) return;
+
+    await this.ensureInitialized();
+    this.events?.track({
+      userId: attributes?.userId || attributes?.user_id || 'anonymous',
+      event: `${operationName}.${outcome}`,
+      properties: {
+        operation: operationName,
+        outcome,
+        ...attributes,
+      },
+    });
+  }
+
+  async trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void> {
+    if (!this.enabled) return;
+
+    await this.ensureInitialized();
+    this.events?.track({
+      userId: attributes?.userId || attributes?.user_id || 'anonymous',
+      event: name,
+      properties: {
+        value,
+        ...attributes,
+      },
+    });
+  }
+
+  /** Flush pending events before shutdown */
+  async shutdown(): Promise<void> {
+    await this.ensureInitialized();
+    if (this.events) {
+      await this.events.closeAndFlush();
+    }
+  }
+}
+