autotel-subscribers 40.0.0 → 41.0.0

package/src/event-subscriber-base.ts

@@ -1,433 +0,0 @@
-/**
- * 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,
-  EventAttributesInput,
-  FunnelStatus,
-  OutcomeStatus,
-  AutotelEventContext,
-  EventTrackingOptions,
-} from 'autotel/event-subscriber';
-
-// Re-export types for convenience
-export type { AutotelEventContext, EventTrackingOptions } from 'autotel/event-subscriber';
-
-/**
- * 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 (from FunnelStatus enum) */
-  step?: FunnelStatus | string;
-
-  /** For funnel events: custom step name (from trackFunnelProgression) */
-  stepName?: string;
-
-  /** For funnel events: numeric position in funnel */
-  stepNumber?: number;
-
-  /** 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;
-
-  /**
-   * Autotel trace context (present when events.includeTraceContext is enabled)
-   *
-   * Subscribers should map these to platform-specific field names:
-   * - PostHog: autotel.trace_id → $trace_id
-   * - Mixpanel: autotel.trace_id → trace_id
-   */
-  autotel?: AutotelEventContext;
-  /** Optional schema metadata for contract-aware subscribers. */
-  schema?: EventTrackingOptions['schema'];
-}
-
-/**
- * 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,
-    );
-  }
-
-  /**
-   * Filter out undefined and null values from attributes
-   *
-   * This improves DX by allowing callers to pass objects with optional properties
-   * without having to manually filter them first.
-   *
-   * @param attributes - Input attributes (may contain undefined/null)
-   * @returns Filtered attributes with only defined values, or undefined if empty
-   *
-   * @example
-   * ```typescript
-   * const filtered = this.filterAttributes({
-   *   userId: user.id,
-   *   email: user.email,      // might be undefined
-   *   plan: null,             // will be filtered out
-   * });
-   * // Result: { userId: 'abc', email: 'test@example.com' } or { userId: 'abc' }
-   * ```
-   */
-  protected filterAttributes(
-    attributes?: EventAttributesInput,
-  ): EventAttributes | undefined {
-    if (!attributes) return undefined;
-
-    const filtered: EventAttributes = {};
-    for (const [key, value] of Object.entries(attributes)) {
-      if (value !== undefined && value !== null) {
-        filtered[key] = value;
-      }
-    }
-
-    // Return undefined if no attributes remain after filtering
-    return Object.keys(filtered).length > 0 ? filtered : undefined;
-  }
-
-  /**
-   * Track an event
-   */
-  async trackEvent(
-    name: string,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void> {
-    if (!this.enabled) return;
-
-    const payload: EventPayload = {
-      type: 'event',
-      name,
-      attributes,
-      timestamp: new Date().toISOString(),
-      autotel: options?.autotel,
-      schema: options?.schema,
-    };
-
-    await this.send(payload);
-  }
-
-  /**
-   * Track a funnel step
-   */
-  async trackFunnelStep(
-    funnelName: string,
-    step: FunnelStatus,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void> {
-    if (!this.enabled) return;
-
-    const payload: EventPayload = {
-      type: 'funnel',
-      name: `${funnelName}.${step}`,
-      funnel: funnelName,
-      step,
-      attributes,
-      timestamp: new Date().toISOString(),
-      autotel: options?.autotel,
-    };
-
-    await this.send(payload);
-  }
-
-  /**
-   * Track an outcome
-   */
-  async trackOutcome(
-    operationName: string,
-    outcome: OutcomeStatus,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void> {
-    if (!this.enabled) return;
-
-    const payload: EventPayload = {
-      type: 'outcome',
-      name: `${operationName}.${outcome}`,
-      operation: operationName,
-      outcome,
-      attributes,
-      timestamp: new Date().toISOString(),
-      autotel: options?.autotel,
-    };
-
-    await this.send(payload);
-  }
-
-  /**
-   * Track a value/metric
-   */
-  async trackValue(
-    name: string,
-    value: number,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void> {
-    if (!this.enabled) return;
-
-    const payload: EventPayload = {
-      type: 'value',
-      name,
-      value,
-      attributes,
-      timestamp: new Date().toISOString(),
-      autotel: options?.autotel,
-    };
-
-    await this.send(payload);
-  }
-
-  /**
-   * 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
-   */
-  async trackFunnelProgression(
-    funnelName: string,
-    stepName: string,
-    stepNumber?: number,
-    attributes?: EventAttributes,
-    options?: EventTrackingOptions,
-  ): Promise<void> {
-    if (!this.enabled) return;
-
-    const payload: EventPayload = {
-      type: 'funnel',
-      name: `${funnelName}.${stepName}`,
-      funnel: funnelName,
-      step: stepName,
-      stepName,
-      stepNumber,
-      attributes,
-      timestamp: new Date().toISOString(),
-      autotel: options?.autotel,
-    };
-
-    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 EventAttributesInput,
-  type FunnelStatus,
-  type OutcomeStatus,
-} from 'autotel/event-subscriber';

package/src/factories.compose.test.ts

@@ -1,107 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { composeSubscribers } from './factories';
-import type {
-  EventSubscriber,
-  EventAttributes,
-  FunnelStatus,
-  OutcomeStatus,
-  EventTrackingOptions,
-} from 'autotel/event-subscriber';
-
-class StubSubscriber implements EventSubscriber {
-  readonly name: string;
-  private readonly failUntil: number;
-  public calls = 0;
-
-  constructor(name: string, failUntil = 0) {
-    this.name = name;
-    this.failUntil = failUntil;
-  }
-
-  private async run(): Promise<void> {
-    this.calls += 1;
-    if (this.calls <= this.failUntil) {
-      throw new Error(`${this.name} failed`);
-    }
-  }
-
-  async trackEvent(_name: string, _attributes?: EventAttributes, _options?: EventTrackingOptions): Promise<void> {
-    await this.run();
-  }
-  async trackFunnelStep(_funnel: string, _step: FunnelStatus, _attributes?: EventAttributes, _options?: EventTrackingOptions): Promise<void> {
-    await this.run();
-  }
-  async trackOutcome(_operation: string, _outcome: OutcomeStatus, _attributes?: EventAttributes, _options?: EventTrackingOptions): Promise<void> {
-    await this.run();
-  }
-  async trackValue(_name: string, _value: number, _attributes?: EventAttributes, _options?: EventTrackingOptions): Promise<void> {
-    await this.run();
-  }
-}
-
-describe('composeSubscribers strategies', () => {
-  it('parallel requires all subscribers to succeed', async () => {
-    const a = new StubSubscriber('a');
-    const b = new StubSubscriber('b', 1);
-
-    const composed = composeSubscribers([a, b], { strategy: 'parallel' });
-    await expect(composed.trackEvent('x')).rejects.toThrow();
-  });
-
-  it('failover succeeds on next healthy subscriber', async () => {
-    const a = new StubSubscriber('a', 1);
-    const b = new StubSubscriber('b');
-
-    const composed = composeSubscribers([a, b], { strategy: 'failover' });
-    await composed.trackEvent('x');
-
-    expect(a.calls).toBe(1);
-    expect(b.calls).toBe(1);
-  });
-
-  it('race succeeds if any subscriber succeeds', async () => {
-    const a = new StubSubscriber('a', 1);
-    const b = new StubSubscriber('b');
-
-    const composed = composeSubscribers([a, b], { strategy: 'race' });
-    await expect(composed.trackEvent('x')).resolves.toBeUndefined();
-  });
-
-  it('mirrored returns based on primary subscriber only', async () => {
-    const a = new StubSubscriber('a');
-    const b = new StubSubscriber('b', 10);
-
-    const composed = composeSubscribers([a, b], { strategy: 'mirrored' });
-    await expect(composed.trackEvent('x')).resolves.toBeUndefined();
-    expect(a.calls).toBe(1);
-  });
-
-  it('round-robin rotates starting subscriber', async () => {
-    const a = new StubSubscriber('a');
-    const b = new StubSubscriber('b');
-
-    const composed = composeSubscribers([a, b], {
-      strategy: 'round-robin',
-      maxAttemptsPerSubscriber: 1,
-    });
-
-    await composed.trackEvent('x');
-    await composed.trackEvent('x');
-
-    expect(a.calls).toBe(1);
-    expect(b.calls).toBe(1);
-  });
-
-  it('retries subscriber when retriable', async () => {
-    const a = new StubSubscriber('a', 1);
-    const composed = composeSubscribers([a], {
-      strategy: 'failover',
-      maxAttemptsPerSubscriber: 2,
-      initialRetryDelayMs: 1,
-      maxRetryDelayMs: 1,
-    });
-
-    await composed.trackEvent('x');
-    expect(a.calls).toBe(2);
-  });
-});