autotel-subscribers 4.0.0

package/dist/index.d.cts

@@ -0,0 +1,179 @@
+export { PostHogConfig, PostHogSubscriber } from './posthog.cjs';
+export { MixpanelConfig, MixpanelSubscriber } from './mixpanel.cjs';
+export { SegmentConfig, SegmentSubscriber } from './segment.cjs';
+export { AmplitudeConfig, AmplitudeSubscriber } from './amplitude.cjs';
+export { SlackSubscriber, SlackSubscriberConfig } from './slack.cjs';
+export { WebhookConfig, WebhookSubscriber } from './webhook.cjs';
+import { E as EventSubscriber, a as EventPayload } from './event-subscriber-base-CnF3V56W.cjs';
+import 'autotel/event-subscriber';
+import 'posthog-node';
+
+/**
+ * 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)
+ *       }))
+ *     });
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * 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)
+ */
+type BufferOverflowStrategy = 'drop' | 'block' | 'disk';
+/**
+ * Streaming subscriber configuration
+ */
+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
+ */
+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.
+ */
+declare abstract class StreamingEventSubscriber extends EventSubscriber {
+    protected config: Required<StreamingSubscriberConfig>;
+    protected buffer: EventPayload[];
+    protected flushIntervalHandle: NodeJS.Timeout | null;
+    private isShuttingDown;
+    constructor(config?: StreamingSubscriberConfig);
+    /**
+     * 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 sendToDestination(payload: EventPayload): Promise<void>;
+    /**
+     * 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 ensureBufferCapacity;
+    /**
+     * Flush buffer to destination
+     */
+    private flushBuffer;
+    /**
+     * Start periodic flushing
+     */
+    private startFlushInterval;
+    /**
+     * Get current buffer status (for monitoring/observability)
+     */
+    getBufferStatus(): BufferStatus;
+    /**
+     * Shutdown with proper buffer draining
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Optional: Compress payload before sending
+     *
+     * Override this if your streaming platform supports compression.
+     * Only called if compressionEnabled = true.
+     */
+    protected compressPayload(payload: string): Promise<Buffer | string>;
+}
+
+export { EventPayload, EventSubscriber, StreamingEventSubscriber };

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+export { PostHogConfig, PostHogSubscriber } from './posthog.js';
+export { MixpanelConfig, MixpanelSubscriber } from './mixpanel.js';
+export { SegmentConfig, SegmentSubscriber } from './segment.js';
+export { AmplitudeConfig, AmplitudeSubscriber } from './amplitude.js';
+export { SlackSubscriber, SlackSubscriberConfig } from './slack.js';
+export { WebhookConfig, WebhookSubscriber } from './webhook.js';
+import { E as EventSubscriber, a as EventPayload } from './event-subscriber-base-CnF3V56W.js';
+import 'autotel/event-subscriber';
+import 'posthog-node';
+
+/**
+ * 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)
+ *       }))
+ *     });
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * 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)
+ */
+type BufferOverflowStrategy = 'drop' | 'block' | 'disk';
+/**
+ * Streaming subscriber configuration
+ */
+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
+ */
+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.
+ */
+declare abstract class StreamingEventSubscriber extends EventSubscriber {
+    protected config: Required<StreamingSubscriberConfig>;
+    protected buffer: EventPayload[];
+    protected flushIntervalHandle: NodeJS.Timeout | null;
+    private isShuttingDown;
+    constructor(config?: StreamingSubscriberConfig);
+    /**
+     * 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 sendToDestination(payload: EventPayload): Promise<void>;
+    /**
+     * 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 ensureBufferCapacity;
+    /**
+     * Flush buffer to destination
+     */
+    private flushBuffer;
+    /**
+     * Start periodic flushing
+     */
+    private startFlushInterval;
+    /**
+     * Get current buffer status (for monitoring/observability)
+     */
+    getBufferStatus(): BufferStatus;
+    /**
+     * Shutdown with proper buffer draining
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Optional: Compress payload before sending
+     *
+     * Override this if your streaming platform supports compression.
+     * Only called if compressionEnabled = true.
+     */
+    protected compressPayload(payload: string): Promise<Buffer | string>;
+}
+
+export { EventPayload, EventSubscriber, StreamingEventSubscriber };