autotel-subscribers 4.0.0

package/dist/factories.d.cts

@@ -0,0 +1,304 @@
+import { EventSubscriber, EventAttributes, FunnelStatus, OutcomeStatus } from 'autotel/event-subscriber';
+export { PostHogConfig } from './posthog.cjs';
+export { MixpanelConfig } from './mixpanel.cjs';
+export { AmplitudeConfig } from './amplitude.cjs';
+export { SegmentConfig } from './segment.cjs';
+export { WebhookConfig } from './webhook.cjs';
+export { SlackSubscriberConfig } from './slack.cjs';
+import './event-subscriber-base-CnF3V56W.cjs';
+import 'posthog-node';
+
+/**
+ * Mock Events Subscriber for Testing
+ *
+ * In-memory subscriber that captures all events events for testing assertions.
+ * Useful for unit testing code that uses Events without making real API calls.
+ *
+ * @example Basic testing
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { MockEventSubscriber } from 'autotel-subscribers/mock-event-subscriber';
+ * import { describe, it, expect, beforeEach } from 'vitest';
+ *
+ * describe('CheckoutService', () => {
+ *   let mockSubscriber: MockEventSubscriber;
+ *   let events: Events;
+ *
+ *   beforeEach(() => {
+ *     mockSubscriber = new MockEventSubscriber();
+ *     events = new Events('checkout', { subscribers: [mockSubscriber] });
+ *   });
+ *
+ *   it('should track order completion', async () => {
+ *     const service = new CheckoutService(events);
+ *     await service.completeOrder('ord_123', 99.99);
+ *
+ *     expect(mockSubscriber.events).toHaveLength(1);
+ *     expect(mockSubscriber.events[0]).toMatchObject({
+ *       type: 'event',
+ *       name: 'order.completed',
+ *       attributes: { orderId: 'ord_123', amount: 99.99 }
+ *     });
+ *   });
+ *
+ *   it('should track checkout funnel', () => {
+ *     events.trackFunnelStep('checkout', 'started', { cartValue: 99.99 });
+ *     events.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 });
+ *
+ *     const funnelEvents = mockSubscriber.getFunnelEvents('checkout');
+ *     expect(funnelEvents).toHaveLength(2);
+ *     expect(funnelEvents[0].step).toBe('started');
+ *     expect(funnelEvents[1].step).toBe('completed');
+ *   });
+ * });
+ * ```
+ *
+ * @example With Outbox Pattern
+ * ```typescript
+ * import { createPublisher } from 'autotel-outbox';
+ * import { MockOutboxStorage } from 'autotel-outbox/testing';
+ *
+ * it('should broadcast events to all subscribers', async () => {
+ *   const mockOutbox = new MockOutboxStorage();
+ *   const mockSubscriber = new MockEventSubscriber();
+ *
+ *   // Add events to outbox
+ *   await mockOutbox.writeEvent({
+ *     id: '1',
+ *     type: 'order.completed',
+ *     aggregateId: 'ord_123',
+ *     aggregateType: 'Order',
+ *     payload: { amount: 99.99 },
+ *     createdAt: new Date().toISOString(),
+ *     publishedAt: null
+ *   });
+ *
+ *   // Run publisher
+ *   const publisher = createPublisher(mockOutbox, [mockSubscriber]);
+ *   await publisher();
+ *
+ *   // Assert event was broadcast
+ *   expect(mockSubscriber.events).toHaveLength(1);
+ *   expect(mockSubscriber.events[0].name).toBe('order.completed');
+ * });
+ * ```
+ */
+
+/**
+ * Captured event data
+ */
+interface CapturedEvent {
+    type: 'event' | 'funnel' | 'outcome' | 'value';
+    name: string;
+    attributes?: EventAttributes;
+    funnel?: string;
+    step?: FunnelStatus;
+    operation?: string;
+    outcome?: OutcomeStatus;
+    value?: number;
+    timestamp: string;
+}
+/**
+ * Mock subscriber for testing
+ *
+ * Captures all events calls in memory for test assertions.
+ * Does not make any real API calls.
+ */
+declare class MockEventSubscriber implements EventSubscriber {
+    readonly name = "MockEventSubscriber";
+    readonly version = "1.0.0";
+    /**
+     * All captured events
+     */
+    events: CapturedEvent[];
+    /**
+     * Track if shutdown was called
+     */
+    shutdownCalled: boolean;
+    trackEvent(name: string, attributes?: EventAttributes): Promise<void>;
+    trackFunnelStep(funnelName: string, step: FunnelStatus, attributes?: EventAttributes): Promise<void>;
+    trackOutcome(operationName: string, outcome: OutcomeStatus, attributes?: EventAttributes): Promise<void>;
+    trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * Reset captured events (useful between tests)
+     */
+    reset(): void;
+    /**
+     * Get events by type
+     */
+    getEventsByType(type: 'event' | 'funnel' | 'outcome' | 'value'): CapturedEvent[];
+    /**
+     * Get events by name
+     */
+    getEventsByName(name: string): CapturedEvent[];
+    /**
+     * Get funnel events for a specific funnel
+     */
+    getFunnelEvents(funnelName: string): CapturedEvent[];
+    /**
+     * Get outcome events for a specific operation
+     */
+    getOutcomeEvents(operationName: string): CapturedEvent[];
+    /**
+     * Get value events by metric name
+     */
+    getValueEvents(metricName: string): CapturedEvent[];
+    /**
+     * Assert that an event was tracked
+     */
+    assertEventTracked(name: string, attributes?: Partial<EventAttributes>): void;
+    /**
+     * Assert that a funnel step was tracked
+     */
+    assertFunnelStepTracked(funnelName: string, step: FunnelStatus, attributes?: Partial<EventAttributes>): void;
+    /**
+     * Assert that an outcome was tracked
+     */
+    assertOutcomeTracked(operationName: string, outcome: OutcomeStatus, attributes?: Partial<EventAttributes>): void;
+    /**
+     * Pretty print all captured events (useful for debugging)
+     */
+    printEvents(): void;
+}
+
+/**
+ * Factory functions for creating events subscribers
+ *
+ * Function-based alternatives to `new SubscriberClass()` pattern.
+ * Provides a consistent API and better tree-shaking.
+ *
+ * @example
+ * ```typescript
+ * import { createPostHogSubscriber, createWebhookSubscriber } from 'autotel-subscribers/factories'
+ *
+ * const events = new Events('my-service', {
+ *   subscribers: [
+ *     createPostHogSubscriber({ apiKey: 'phc_...' }),
+ *     createWebhookSubscriber({ url: 'https://...' })
+ *   ]
+ * })
+ * ```
+ */
+
+/**
+ * Create a PostHog events subscriber
+ *
+ * @example
+ * ```typescript
+ * const posthog = createPostHogSubscriber({
+ *   apiKey: 'phc_...',
+ *   host: 'https://app.posthog.com' // optional
+ * })
+ * ```
+ */
+declare function createPostHogSubscriber(config: {
+    apiKey: string;
+    host?: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a Mixpanel events subscriber
+ *
+ * @example
+ * ```typescript
+ * const mixpanel = createMixpanelSubscriber({
+ *   token: 'YOUR_TOKEN'
+ * })
+ * ```
+ */
+declare function createMixpanelSubscriber(config: {
+    token: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create an Amplitude events subscriber
+ *
+ * @example
+ * ```typescript
+ * const amplitude = createAmplitudeSubscriber({
+ *   apiKey: 'YOUR_API_KEY'
+ * })
+ * ```
+ */
+declare function createAmplitudeSubscriber(config: {
+    apiKey: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a Segment events subscriber
+ *
+ * @example
+ * ```typescript
+ * const segment = createSegmentSubscriber({
+ *   writeKey: 'YOUR_WRITE_KEY'
+ * })
+ * ```
+ */
+declare function createSegmentSubscriber(config: {
+    writeKey: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a Webhook events subscriber
+ *
+ * @example
+ * ```typescript
+ * const webhook = createWebhookSubscriber({
+ *   url: 'https://your-webhook-endpoint.com/events',
+ *   headers: { 'Authorization': 'Bearer token' }
+ * })
+ * ```
+ */
+declare function createWebhookSubscriber(config: {
+    url: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a Slack events subscriber
+ *
+ * @example
+ * ```typescript
+ * const slack = createSlackSubscriber({
+ *   webhookUrl: 'https://hooks.slack.com/services/...',
+ *   channel: '#events'
+ * })
+ * ```
+ */
+declare function createSlackSubscriber(config: {
+    webhookUrl: string;
+    channel?: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a mock events subscriber (for testing)
+ *
+ * @example
+ * ```typescript
+ * const mock = createMockSubscriber()
+ *
+ * // Capture events
+ * events.trackEvent('test.event', { foo: 'bar' })
+ *
+ * // Assert
+ * expect(mock.events).toHaveLength(1)
+ * expect(mock.events[0].name).toBe('test.event')
+ * ```
+ */
+declare function createMockSubscriber(): MockEventSubscriber;
+/**
+ * Compose multiple subscribers into one
+ *
+ * @example
+ * ```typescript
+ * const multiSubscriber = composeSubscribers([
+ *   createPostHogSubscriber({ apiKey: '...' }),
+ *   createWebhookSubscriber({ url: '...' })
+ * ])
+ * ```
+ */
+declare function composeSubscribers(adapters: EventSubscriber[]): EventSubscriber;
+
+export { composeSubscribers, createAmplitudeSubscriber, createMixpanelSubscriber, createMockSubscriber, createPostHogSubscriber, createSegmentSubscriber, createSlackSubscriber, createWebhookSubscriber };

package/dist/factories.d.ts

@@ -0,0 +1,304 @@
+import { EventSubscriber, EventAttributes, FunnelStatus, OutcomeStatus } from 'autotel/event-subscriber';
+export { PostHogConfig } from './posthog.js';
+export { MixpanelConfig } from './mixpanel.js';
+export { AmplitudeConfig } from './amplitude.js';
+export { SegmentConfig } from './segment.js';
+export { WebhookConfig } from './webhook.js';
+export { SlackSubscriberConfig } from './slack.js';
+import './event-subscriber-base-CnF3V56W.js';
+import 'posthog-node';
+
+/**
+ * Mock Events Subscriber for Testing
+ *
+ * In-memory subscriber that captures all events events for testing assertions.
+ * Useful for unit testing code that uses Events without making real API calls.
+ *
+ * @example Basic testing
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { MockEventSubscriber } from 'autotel-subscribers/mock-event-subscriber';
+ * import { describe, it, expect, beforeEach } from 'vitest';
+ *
+ * describe('CheckoutService', () => {
+ *   let mockSubscriber: MockEventSubscriber;
+ *   let events: Events;
+ *
+ *   beforeEach(() => {
+ *     mockSubscriber = new MockEventSubscriber();
+ *     events = new Events('checkout', { subscribers: [mockSubscriber] });
+ *   });
+ *
+ *   it('should track order completion', async () => {
+ *     const service = new CheckoutService(events);
+ *     await service.completeOrder('ord_123', 99.99);
+ *
+ *     expect(mockSubscriber.events).toHaveLength(1);
+ *     expect(mockSubscriber.events[0]).toMatchObject({
+ *       type: 'event',
+ *       name: 'order.completed',
+ *       attributes: { orderId: 'ord_123', amount: 99.99 }
+ *     });
+ *   });
+ *
+ *   it('should track checkout funnel', () => {
+ *     events.trackFunnelStep('checkout', 'started', { cartValue: 99.99 });
+ *     events.trackFunnelStep('checkout', 'completed', { cartValue: 99.99 });
+ *
+ *     const funnelEvents = mockSubscriber.getFunnelEvents('checkout');
+ *     expect(funnelEvents).toHaveLength(2);
+ *     expect(funnelEvents[0].step).toBe('started');
+ *     expect(funnelEvents[1].step).toBe('completed');
+ *   });
+ * });
+ * ```
+ *
+ * @example With Outbox Pattern
+ * ```typescript
+ * import { createPublisher } from 'autotel-outbox';
+ * import { MockOutboxStorage } from 'autotel-outbox/testing';
+ *
+ * it('should broadcast events to all subscribers', async () => {
+ *   const mockOutbox = new MockOutboxStorage();
+ *   const mockSubscriber = new MockEventSubscriber();
+ *
+ *   // Add events to outbox
+ *   await mockOutbox.writeEvent({
+ *     id: '1',
+ *     type: 'order.completed',
+ *     aggregateId: 'ord_123',
+ *     aggregateType: 'Order',
+ *     payload: { amount: 99.99 },
+ *     createdAt: new Date().toISOString(),
+ *     publishedAt: null
+ *   });
+ *
+ *   // Run publisher
+ *   const publisher = createPublisher(mockOutbox, [mockSubscriber]);
+ *   await publisher();
+ *
+ *   // Assert event was broadcast
+ *   expect(mockSubscriber.events).toHaveLength(1);
+ *   expect(mockSubscriber.events[0].name).toBe('order.completed');
+ * });
+ * ```
+ */
+
+/**
+ * Captured event data
+ */
+interface CapturedEvent {
+    type: 'event' | 'funnel' | 'outcome' | 'value';
+    name: string;
+    attributes?: EventAttributes;
+    funnel?: string;
+    step?: FunnelStatus;
+    operation?: string;
+    outcome?: OutcomeStatus;
+    value?: number;
+    timestamp: string;
+}
+/**
+ * Mock subscriber for testing
+ *
+ * Captures all events calls in memory for test assertions.
+ * Does not make any real API calls.
+ */
+declare class MockEventSubscriber implements EventSubscriber {
+    readonly name = "MockEventSubscriber";
+    readonly version = "1.0.0";
+    /**
+     * All captured events
+     */
+    events: CapturedEvent[];
+    /**
+     * Track if shutdown was called
+     */
+    shutdownCalled: boolean;
+    trackEvent(name: string, attributes?: EventAttributes): Promise<void>;
+    trackFunnelStep(funnelName: string, step: FunnelStatus, attributes?: EventAttributes): Promise<void>;
+    trackOutcome(operationName: string, outcome: OutcomeStatus, attributes?: EventAttributes): Promise<void>;
+    trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * Reset captured events (useful between tests)
+     */
+    reset(): void;
+    /**
+     * Get events by type
+     */
+    getEventsByType(type: 'event' | 'funnel' | 'outcome' | 'value'): CapturedEvent[];
+    /**
+     * Get events by name
+     */
+    getEventsByName(name: string): CapturedEvent[];
+    /**
+     * Get funnel events for a specific funnel
+     */
+    getFunnelEvents(funnelName: string): CapturedEvent[];
+    /**
+     * Get outcome events for a specific operation
+     */
+    getOutcomeEvents(operationName: string): CapturedEvent[];
+    /**
+     * Get value events by metric name
+     */
+    getValueEvents(metricName: string): CapturedEvent[];
+    /**
+     * Assert that an event was tracked
+     */
+    assertEventTracked(name: string, attributes?: Partial<EventAttributes>): void;
+    /**
+     * Assert that a funnel step was tracked
+     */
+    assertFunnelStepTracked(funnelName: string, step: FunnelStatus, attributes?: Partial<EventAttributes>): void;
+    /**
+     * Assert that an outcome was tracked
+     */
+    assertOutcomeTracked(operationName: string, outcome: OutcomeStatus, attributes?: Partial<EventAttributes>): void;
+    /**
+     * Pretty print all captured events (useful for debugging)
+     */
+    printEvents(): void;
+}
+
+/**
+ * Factory functions for creating events subscribers
+ *
+ * Function-based alternatives to `new SubscriberClass()` pattern.
+ * Provides a consistent API and better tree-shaking.
+ *
+ * @example
+ * ```typescript
+ * import { createPostHogSubscriber, createWebhookSubscriber } from 'autotel-subscribers/factories'
+ *
+ * const events = new Events('my-service', {
+ *   subscribers: [
+ *     createPostHogSubscriber({ apiKey: 'phc_...' }),
+ *     createWebhookSubscriber({ url: 'https://...' })
+ *   ]
+ * })
+ * ```
+ */
+
+/**
+ * Create a PostHog events subscriber
+ *
+ * @example
+ * ```typescript
+ * const posthog = createPostHogSubscriber({
+ *   apiKey: 'phc_...',
+ *   host: 'https://app.posthog.com' // optional
+ * })
+ * ```
+ */
+declare function createPostHogSubscriber(config: {
+    apiKey: string;
+    host?: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a Mixpanel events subscriber
+ *
+ * @example
+ * ```typescript
+ * const mixpanel = createMixpanelSubscriber({
+ *   token: 'YOUR_TOKEN'
+ * })
+ * ```
+ */
+declare function createMixpanelSubscriber(config: {
+    token: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create an Amplitude events subscriber
+ *
+ * @example
+ * ```typescript
+ * const amplitude = createAmplitudeSubscriber({
+ *   apiKey: 'YOUR_API_KEY'
+ * })
+ * ```
+ */
+declare function createAmplitudeSubscriber(config: {
+    apiKey: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a Segment events subscriber
+ *
+ * @example
+ * ```typescript
+ * const segment = createSegmentSubscriber({
+ *   writeKey: 'YOUR_WRITE_KEY'
+ * })
+ * ```
+ */
+declare function createSegmentSubscriber(config: {
+    writeKey: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a Webhook events subscriber
+ *
+ * @example
+ * ```typescript
+ * const webhook = createWebhookSubscriber({
+ *   url: 'https://your-webhook-endpoint.com/events',
+ *   headers: { 'Authorization': 'Bearer token' }
+ * })
+ * ```
+ */
+declare function createWebhookSubscriber(config: {
+    url: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a Slack events subscriber
+ *
+ * @example
+ * ```typescript
+ * const slack = createSlackSubscriber({
+ *   webhookUrl: 'https://hooks.slack.com/services/...',
+ *   channel: '#events'
+ * })
+ * ```
+ */
+declare function createSlackSubscriber(config: {
+    webhookUrl: string;
+    channel?: string;
+    enabled?: boolean;
+}): EventSubscriber;
+/**
+ * Create a mock events subscriber (for testing)
+ *
+ * @example
+ * ```typescript
+ * const mock = createMockSubscriber()
+ *
+ * // Capture events
+ * events.trackEvent('test.event', { foo: 'bar' })
+ *
+ * // Assert
+ * expect(mock.events).toHaveLength(1)
+ * expect(mock.events[0].name).toBe('test.event')
+ * ```
+ */
+declare function createMockSubscriber(): MockEventSubscriber;
+/**
+ * Compose multiple subscribers into one
+ *
+ * @example
+ * ```typescript
+ * const multiSubscriber = composeSubscribers([
+ *   createPostHogSubscriber({ apiKey: '...' }),
+ *   createWebhookSubscriber({ url: '...' })
+ * ])
+ * ```
+ */
+declare function composeSubscribers(adapters: EventSubscriber[]): EventSubscriber;
+
+export { composeSubscribers, createAmplitudeSubscriber, createMixpanelSubscriber, createMockSubscriber, createPostHogSubscriber, createSegmentSubscriber, createSlackSubscriber, createWebhookSubscriber };