autotel-subscribers 4.0.0

package/dist/event-subscriber-base-CnF3V56W.d.cts

@@ -0,0 +1,182 @@
+import { EventSubscriber as EventSubscriber$1, EventAttributes, FunnelStatus, OutcomeStatus } from 'autotel/event-subscriber';
+
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Payload sent to destination
+ */
+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 */
+    step?: FunnelStatus;
+    /** 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;
+}
+/**
+ * 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.
+ */
+declare abstract class EventSubscriber implements EventSubscriber$1 {
+    /**
+     * Subscriber name (required for debugging)
+     */
+    abstract readonly name: string;
+    /**
+     * Subscriber version (optional)
+     */
+    readonly version?: string;
+    /**
+     * Enable/disable the subscriber (default: true)
+     */
+    protected enabled: boolean;
+    /**
+     * Track pending requests for graceful shutdown
+     */
+    private pendingRequests;
+    /**
+     * 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;
+    /**
+     * Track an event
+     */
+    trackEvent(name: string, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track a funnel step
+     */
+    trackFunnelStep(funnelName: string, step: FunnelStatus, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track an outcome
+     */
+    trackOutcome(operationName: string, outcome: OutcomeStatus, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track a value/metric
+     */
+    trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void>;
+    /**
+     * 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.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Internal: Send payload and track request
+     */
+    private send;
+    /**
+     * Internal: Send with error handling
+     */
+    private sendWithErrorHandling;
+}
+
+export { EventSubscriber as E, type EventPayload as a };

package/dist/event-subscriber-base-CnF3V56W.d.ts

@@ -0,0 +1,182 @@
+import { EventSubscriber as EventSubscriber$1, EventAttributes, FunnelStatus, OutcomeStatus } from 'autotel/event-subscriber';
+
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Payload sent to destination
+ */
+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 */
+    step?: FunnelStatus;
+    /** 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;
+}
+/**
+ * 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.
+ */
+declare abstract class EventSubscriber implements EventSubscriber$1 {
+    /**
+     * Subscriber name (required for debugging)
+     */
+    abstract readonly name: string;
+    /**
+     * Subscriber version (optional)
+     */
+    readonly version?: string;
+    /**
+     * Enable/disable the subscriber (default: true)
+     */
+    protected enabled: boolean;
+    /**
+     * Track pending requests for graceful shutdown
+     */
+    private pendingRequests;
+    /**
+     * 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;
+    /**
+     * Track an event
+     */
+    trackEvent(name: string, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track a funnel step
+     */
+    trackFunnelStep(funnelName: string, step: FunnelStatus, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track an outcome
+     */
+    trackOutcome(operationName: string, outcome: OutcomeStatus, attributes?: EventAttributes): Promise<void>;
+    /**
+     * Track a value/metric
+     */
+    trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void>;
+    /**
+     * 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.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Internal: Send payload and track request
+     */
+    private send;
+    /**
+     * Internal: Send with error handling
+     */
+    private sendWithErrorHandling;
+}
+
+export { EventSubscriber as E, type EventPayload as a };