autotel-subscribers 4.0.0

package/src/slack.ts

@@ -0,0 +1,383 @@
+/**
+ * Slack Subscriber for autotel
+ *
+ * Send events events as notifications to Slack channels via webhooks.
+ *
+ * Perfect for:
+ * - Critical business events (orders, payments, signups)
+ * - Real-time alerts for failures
+ * - Team notifications for important milestones
+ * - Monitoring funnel completions
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Events } from 'autotel/events';
+ * import { SlackSubscriber } from 'autotel-subscribers/slack';
+ *
+ * const events = new Events('app', {
+ *   subscribers: [
+ *     new SlackSubscriber({
+ *       webhookUrl: process.env.SLACK_WEBHOOK_URL!,
+ *       channel: '#order-events'
+ *     })
+ *   ]
+ * });
+ *
+ * // Sends to Slack
+ * events.trackEvent('order.completed', {
+ *   orderId: 'ord_123',
+ *   userId: 'user_456',
+ *   amount: 99.99
+ * });
+ * ```
+ *
+ * @example Filter critical events only
+ * ```typescript
+ * const events = new Events('app', {
+ *   subscribers: [
+ *     new SlackSubscriber({
+ *       webhookUrl: process.env.SLACK_WEBHOOK_URL!,
+ *       channel: '#alerts',
+ *       filter: (payload) => {
+ *         // Only send failures and high-value orders
+ *         if (payload.type === 'outcome' && payload.outcome === 'failure') {
+ *           return true;
+ *         }
+ *         if (payload.name === 'order.completed' && payload.attributes?.amount > 1000) {
+ *           return true;
+ *         }
+ *         return false;
+ *       }
+ *     })
+ *   ]
+ * });
+ * ```
+ *
+ * Setup:
+ * 1. Create Slack App: https://api.slack.com/apps
+ * 2. Enable Incoming Webhooks
+ * 3. Add webhook to workspace
+ * 4. Copy webhook URL (https://hooks.slack.com/services/...)
+ */
+
+import {
+  EventSubscriber,
+  type EventPayload,
+} from './event-subscriber-base';
+
+export interface SlackSubscriberConfig {
+  /** Slack webhook URL (https://hooks.slack.com/services/...) */
+  webhookUrl: string;
+
+  /** Default channel to post to (optional, overrides webhook default) */
+  channel?: string;
+
+  /** Custom username for bot (default: 'Events Bot') */
+  username?: string;
+
+  /** Custom emoji icon (default: ':chart_with_upwards_trend:') */
+  iconEmoji?: string;
+
+  /** Include timestamp in messages (default: true) */
+  includeTimestamp?: boolean;
+
+  /** Include event attributes as fields (default: true) */
+  includeAttributes?: boolean;
+
+  /** Maximum attributes to show (default: 10) */
+  maxAttributeFields?: number;
+
+  /** Filter function - return true to send, false to skip */
+  filter?: (payload: EventPayload) => boolean;
+
+  /** Enable/disable subscriber */
+  enabled?: boolean;
+}
+
+interface SlackMessage {
+  channel?: string;
+  username?: string;
+  icon_emoji?: string;
+  text?: string;
+  attachments: SlackAttachment[];
+}
+
+interface SlackAttachment {
+  color?: string;
+  title?: string;
+  text?: string;
+  fields?: SlackField[];
+  footer?: string;
+  footer_icon?: string;
+  ts?: number;
+}
+
+interface SlackField {
+  title: string;
+  value: string;
+  short: boolean;
+}
+
+export class SlackSubscriber extends EventSubscriber {
+  readonly name = 'SlackSubscriber';
+  readonly version = '1.0.0';
+
+  private config: Required<Omit<SlackSubscriberConfig, 'channel' | 'filter'>> & {
+    channel?: string;
+    filter?: (payload: EventPayload) => boolean;
+  };
+
+  constructor(config: SlackSubscriberConfig) {
+    super();
+
+    this.config = {
+      webhookUrl: config.webhookUrl,
+      channel: config.channel,
+      username: config.username ?? 'Events Bot',
+      iconEmoji: config.iconEmoji ?? ':chart_with_upwards_trend:',
+      includeTimestamp: config.includeTimestamp ?? true,
+      includeAttributes: config.includeAttributes ?? true,
+      maxAttributeFields: config.maxAttributeFields ?? 10,
+      filter: config.filter,
+      enabled: config.enabled ?? true,
+    };
+
+    this.enabled = this.config.enabled;
+
+    if (!this.config.webhookUrl) {
+      console.error(
+        '[SlackSubscriber] No webhook URL provided - subscriber disabled'
+      );
+      this.enabled = false;
+    }
+  }
+
+  protected async sendToDestination(payload: EventPayload): Promise<void> {
+    // Apply filter if provided
+    if (this.config.filter) {
+      const filterFn = this.config.filter;
+      const shouldInclude = filterFn(payload);
+      if (!shouldInclude) {
+        return; // Skip this event
+      }
+    }
+
+    const message = this.formatSlackMessage(payload);
+
+    const response = await fetch(this.config.webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(message),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(
+        `Slack webhook failed (${response.status}): ${errorText}`
+      );
+    }
+  }
+
+  /**
+   * Format events payload as Slack message
+   */
+  private formatSlackMessage(payload: EventPayload): SlackMessage {
+    const emoji = this.getEventEmoji(payload);
+    const color = this.getEventColor(payload);
+    const title = `${emoji} ${payload.name}`;
+
+    // Add event type
+    const fields: SlackField[] = [
+      {
+        title: 'Event Type',
+        value: this.formatEventType(payload),
+        short: true,
+      },
+    ];
+
+    // Add timestamp if enabled
+    if (this.config.includeTimestamp) {
+      fields.push({
+        title: 'Timestamp',
+        value: new Date(payload.timestamp).toLocaleString('en-US', {
+          month: 'short',
+          day: 'numeric',
+          hour: '2-digit',
+          minute: '2-digit',
+          second: '2-digit',
+        }),
+        short: true,
+      });
+    }
+
+    // Add attributes as fields
+    if (this.config.includeAttributes && payload.attributes) {
+      const attributeFields = this.formatAttributes(payload.attributes);
+      fields.push(...attributeFields);
+    }
+
+    const attachment: SlackAttachment = {
+      color,
+      title,
+      fields,
+      footer: 'Events Events',
+      footer_icon: 'https://i.imgur.com/QpCKbNL.png',
+    };
+
+    // Add Unix timestamp for Slack
+    if (this.config.includeTimestamp) {
+      attachment.ts = Math.floor(
+        new Date(payload.timestamp).getTime() / 1000
+      );
+    }
+
+    return {
+      channel: this.config.channel,
+      username: this.config.username,
+      icon_emoji: this.config.iconEmoji,
+      attachments: [attachment],
+    };
+  }
+
+  /**
+   * Get emoji for event type
+   */
+  private getEventEmoji(payload: EventPayload): string {
+    switch (payload.type) {
+      case 'outcome': {
+        return payload.outcome === 'success' ? '✅' : '❌';
+      }
+      case 'funnel': {
+        return '🔄';
+      }
+      case 'value': {
+        return '📊';
+      }
+      default: {
+        // Use custom emoji for common event patterns
+        if (payload.name.includes('order') || payload.name.includes('payment'))
+          return '💰';
+        if (payload.name.includes('signup') || payload.name.includes('user'))
+          return '👤';
+        if (payload.name.includes('error') || payload.name.includes('fail'))
+          return '⚠️';
+        return '📌';
+      }
+    }
+  }
+
+  /**
+   * Get Slack attachment color for event type
+   */
+  private getEventColor(payload: EventPayload): string {
+    switch (payload.type) {
+      case 'outcome': {
+        return payload.outcome === 'success' ? 'good' : 'danger';
+      } // Green or red
+      case 'funnel': {
+        return '#3AA3E3';
+      } // Blue
+      case 'value': {
+        return '#764FA5';
+      } // Purple
+      default: {
+        // Custom colors for patterns
+        if (payload.name.includes('error') || payload.name.includes('fail'))
+          return 'danger';
+        if (payload.name.includes('warning')) return 'warning';
+        return 'good';
+      } // Default green
+    }
+  }
+
+  /**
+   * Format event type for display
+   */
+  private formatEventType(payload: EventPayload): string {
+    switch (payload.type) {
+      case 'event': {
+        return 'Event';
+      }
+      case 'funnel': {
+        return `Funnel: ${payload.step || 'unknown'}`;
+      }
+      case 'outcome': {
+        return `Outcome: ${payload.outcome || 'unknown'}`;
+      }
+      case 'value': {
+        return `Value: ${payload.value ?? 'N/A'}`;
+      }
+      default: {
+        return payload.type;
+      }
+    }
+  }
+
+  /**
+   * Format attributes as Slack fields
+   */
+  private formatAttributes(attributes: Record<string, any>): SlackField[] {
+    const fields: SlackField[] = [];
+    const entries = Object.entries(attributes);
+
+    // Limit number of fields
+    const limit = Math.min(entries.length, this.config.maxAttributeFields);
+
+    for (let i = 0; i < limit; i++) {
+      const [key, value] = entries[i];
+
+      // Skip internal/system fields
+      if (key.startsWith('_') || key === 'timestamp') continue;
+
+      fields.push({
+        title: this.formatFieldName(key),
+        value: this.formatFieldValue(value),
+        short: true,
+      });
+    }
+
+    // Add truncation notice if needed
+    if (entries.length > this.config.maxAttributeFields) {
+      fields.push({
+        title: 'Note',
+        value: `... and ${entries.length - this.config.maxAttributeFields} more fields`,
+        short: false,
+      });
+    }
+
+    return fields;
+  }
+
+  /**
+   * Format field name (convert camelCase to Title Case)
+   */
+  private formatFieldName(name: string): string {
+    return name
+      .replaceAll(/([A-Z])/g, ' $1') // Add space before capitals
+      .replace(/^./, (str) => str.toUpperCase()) // Capitalize first letter
+      .trim();
+  }
+
+  /**
+   * Format field value
+   */
+  private formatFieldValue(value: any): string {
+    if (value === null || value === undefined) return 'N/A';
+    if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+    if (typeof value === 'object') return JSON.stringify(value);
+    if (typeof value === 'number' && !Number.isInteger(value)) {
+      return value.toFixed(2);
+    }
+    return String(value);
+  }
+
+  /**
+   * Handle errors (override from EventSubscriber)
+   */
+  protected handleError(error: Error, payload: EventPayload): void {
+    console.error(
+      `[SlackSubscriber] Failed to send ${payload.type} event "${payload.name}":`,
+      error
+    );
+  }
+}

package/src/streaming-event-subscriber.ts

@@ -0,0 +1,323 @@
+/**
+ * Streaming Events Subscriber Base Class
+ *
+ * Specialized base class for high-throughput streaming platforms like
+ * Kafka, Kinesis, Pub/Sub, etc.
+ *
+ * Extends EventSubscriber with streaming-specific features:
+ * - Partitioning strategy for ordered delivery
+ * - Buffer overflow handling (drop/block/disk)
+ * - High-throughput optimizations
+ * - Backpressure signaling
+ *
+ * @example Kafka Streaming Subscriber
+ * ```typescript
+ * import { StreamingEventSubscriber } from 'autotel-subscribers/streaming-event-subscriber';
+ *
+ * class KafkaSubscriber extends StreamingEventSubscriber {
+ *   name = 'KafkaSubscriber';
+ *   version = '1.0.0';
+ *
+ *   constructor(config: KafkaConfig) {
+ *     super({
+ *       maxBufferSize: 10000,
+ *       bufferOverflowStrategy: 'block',
+ *       maxBatchSize: 500
+ *     });
+ *   }
+ *
+ *   protected getPartitionKey(payload: EventPayload): string {
+ *     // Partition by userId for ordered events per user
+ *     return payload.attributes?.userId || 'default';
+ *   }
+ *
+ *   protected async sendBatch(events: EventPayload[]): Promise<void> {
+ *     await this.producer.send({
+ *       topic: this.topic,
+ *       messages: events.map(e => ({
+ *         key: this.getPartitionKey(e),
+ *         value: JSON.stringify(e)
+ *       }))
+ *     });
+ *   }
+ * }
+ * ```
+ */
+
+import {
+  EventSubscriber,
+  type EventPayload,
+} from './event-subscriber-base';
+
+/**
+ * Buffer overflow strategy
+ *
+ * - 'drop': Drop new events when buffer is full (prevents blocking, but loses data)
+ * - 'block': Wait for space in buffer (backpressure, may slow application)
+ * - 'disk': Spill to disk when memory buffer full (reliable, but complex - not implemented yet)
+ */
+export type BufferOverflowStrategy = 'drop' | 'block' | 'disk';
+
+/**
+ * Streaming subscriber configuration
+ */
+export interface StreamingSubscriberConfig {
+  /** Maximum buffer size before triggering overflow strategy (default: 10000) */
+  maxBufferSize?: number;
+
+  /** Strategy when buffer is full (default: 'block') */
+  bufferOverflowStrategy?: BufferOverflowStrategy;
+
+  /** Maximum batch size for sending (default: 500) */
+  maxBatchSize?: number;
+
+  /** Flush interval in milliseconds (default: 1000) */
+  flushIntervalMs?: number;
+
+  /** Enable compression (default: false) */
+  compressionEnabled?: boolean;
+}
+
+/**
+ * Buffer status for monitoring
+ */
+export interface BufferStatus {
+  /** Current number of events in buffer */
+  size: number;
+
+  /** Maximum capacity */
+  capacity: number;
+
+  /** Utilization percentage (0-100) */
+  utilization: number;
+
+  /** Is buffer near full (>80%) */
+  isNearFull: boolean;
+
+  /** Is buffer full (100%) */
+  isFull: boolean;
+}
+
+/**
+ * Streaming Events Subscriber Base Class
+ *
+ * Provides streaming-specific patterns on top of EventSubscriber.
+ */
+export abstract class StreamingEventSubscriber extends EventSubscriber {
+  protected config: Required<StreamingSubscriberConfig>;
+  protected buffer: EventPayload[] = [];
+  protected flushIntervalHandle: NodeJS.Timeout | null = null;
+  private isShuttingDown = false;
+
+  constructor(config: StreamingSubscriberConfig = {}) {
+    super();
+
+    // Set defaults
+    this.config = {
+      maxBufferSize: config.maxBufferSize ?? 10_000,
+      bufferOverflowStrategy: config.bufferOverflowStrategy ?? 'block',
+      maxBatchSize: config.maxBatchSize ?? 500,
+      flushIntervalMs: config.flushIntervalMs ?? 1000,
+      compressionEnabled: config.compressionEnabled ?? false,
+    };
+
+    // Start periodic flushing
+    this.startFlushInterval();
+  }
+
+  /**
+   * Get partition key for event
+   *
+   * Override this to implement your partitioning strategy.
+   * Events with the same partition key go to the same partition/shard.
+   *
+   * Common strategies:
+   * - By userId: Ordered events per user
+   * - By tenantId: Isolate tenants
+   * - By eventType: Group similar events
+   * - Round-robin: Load balancing
+   *
+   * @param payload - Event payload
+   * @returns Partition key (string)
+   *
+   * @example Partition by userId
+   * ```typescript
+   * protected getPartitionKey(payload: EventPayload): string {
+   *   return payload.attributes?.userId || 'default';
+   * }
+   * ```
+   */
+  protected abstract getPartitionKey(payload: EventPayload): string;
+
+  /**
+   * Send batch of events to streaming platform
+   *
+   * Override this to implement platform-specific batch sending.
+   * Called when buffer reaches maxBatchSize or flush interval triggers.
+   *
+   * @param events - Batch of events to send
+   */
+  protected abstract sendBatch(events: EventPayload[]): Promise<void>;
+
+  /**
+   * Send single event to destination (from EventSubscriber)
+   *
+   * This buffers events and sends in batches for performance.
+   * Override sendBatch() instead of this method.
+   */
+  protected async sendToDestination(payload: EventPayload): Promise<void> {
+    // Check buffer capacity before adding
+    await this.ensureBufferCapacity();
+
+    // Add to buffer
+    this.buffer.push(payload);
+
+    // Auto-flush if batch size reached
+    if (this.buffer.length >= this.config.maxBatchSize) {
+      await this.flushBuffer();
+    }
+  }
+
+  /**
+   * Ensure buffer has capacity for new event
+   *
+   * Implements buffer overflow strategy:
+   * - 'drop': Returns immediately (event will be added, oldest may be dropped)
+   * - 'block': Waits until space available (backpressure)
+   * - 'disk': Not implemented yet (would spill to disk)
+   */
+  private async ensureBufferCapacity(): Promise<void> {
+    if (this.buffer.length < this.config.maxBufferSize) {
+      return; // Has space
+    }
+
+    // Buffer is full - apply overflow strategy
+    switch (this.config.bufferOverflowStrategy) {
+      case 'drop': {
+        // Drop oldest event to make space
+        this.buffer.shift();
+        console.warn(
+          `[${this.name}] Buffer full (${this.config.maxBufferSize}), dropped oldest event`
+        );
+        break;
+      }
+
+      case 'block': {
+        // Wait for flush to complete (backpressure)
+        console.warn(
+          `[${this.name}] Buffer full (${this.config.maxBufferSize}), blocking until space available`
+        );
+        await this.flushBuffer();
+
+        // If still full after flush, wait a bit and retry
+        if (this.buffer.length >= this.config.maxBufferSize) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          await this.ensureBufferCapacity(); // Recursive retry
+        }
+        break;
+      }
+
+      case 'disk': {
+        throw new Error(
+          `[${this.name}] Disk overflow strategy not implemented yet`
+        );
+      }
+    }
+  }
+
+  /**
+   * Flush buffer to destination
+   */
+  private async flushBuffer(): Promise<void> {
+    if (this.buffer.length === 0) return;
+
+    const batch = [...this.buffer];
+    this.buffer = [];
+
+    try {
+      await this.sendBatch(batch);
+    } catch (error) {
+      console.error(
+        `[${this.name}] Failed to send batch of ${batch.length} events:`,
+        error
+      );
+
+      // On failure, put events back in buffer (at front)
+      this.buffer.unshift(...batch);
+
+      // If we're near capacity, we need to make a decision
+      if (this.buffer.length >= this.config.maxBufferSize * 0.9 && this.config.bufferOverflowStrategy === 'drop') {
+          // Drop oldest to prevent runaway growth
+          const toDrop = Math.floor(this.config.maxBufferSize * 0.1);
+          this.buffer.splice(0, toDrop);
+          console.warn(
+            `[${this.name}] After failed flush, dropped ${toDrop} oldest events to prevent overflow`
+          );
+        }
+    }
+  }
+
+  /**
+   * Start periodic flushing
+   */
+  private startFlushInterval(): void {
+    this.flushIntervalHandle = setInterval(() => {
+      if (!this.isShuttingDown) {
+        void this.flushBuffer();
+      }
+    }, this.config.flushIntervalMs);
+  }
+
+  /**
+   * Get current buffer status (for monitoring/observability)
+   */
+  public getBufferStatus(): BufferStatus {
+    const size = this.buffer.length;
+    const capacity = this.config.maxBufferSize;
+    const utilization = Math.round((size / capacity) * 100);
+
+    return {
+      size,
+      capacity,
+      utilization,
+      isNearFull: utilization > 80,
+      isFull: utilization >= 100,
+    };
+  }
+
+  /**
+   * Shutdown with proper buffer draining
+   */
+  async shutdown(): Promise<void> {
+    this.isShuttingDown = true;
+
+    // Stop flush interval (no more automatic flushes)
+    if (this.flushIntervalHandle) {
+      clearInterval(this.flushIntervalHandle);
+      this.flushIntervalHandle = null;
+    }
+
+    // Call parent shutdown FIRST to:
+    // 1. Set enabled = false (stop accepting new events)
+    // 2. Drain any pending sendToDestination() calls
+    await super.shutdown();
+
+    // THEN flush remaining buffer
+    // (no new events can arrive after super.shutdown() disabled the subscriber)
+    await this.flushBuffer();
+  }
+
+  /**
+   * Optional: Compress payload before sending
+   *
+   * Override this if your streaming platform supports compression.
+   * Only called if compressionEnabled = true.
+   */
+  protected async compressPayload(
+    payload: string
+  ): Promise<Buffer | string> {
+    // Default: no compression
+    // Override with gzip, snappy, lz4, etc.
+    return payload;
+  }
+}