interface EventAdapter

Defines an event adapter for real-time event processing and integration.

EventAdapter provides a hot-subscription pattern for processing live events as they occur, without replaying historical data. Unlike EventView which processes both historical and live events, adapters focus on real-time integration scenarios like external system synchronization, notifications, and live data feeds.

Key Characteristics: - *\*Hot Subscription Only\**: Processes new events, never replays history - \**External Integration\**: Designed for pushing data to external systems - \**Transactional\**: Each event is processed within a database transaction - \**Error Handling\**: Built-in error recovery and monitoring - \**Consumer Groups\*\*: Supports load balancing across multiple instances

Properties

consumerGroup

Consumer group identifier for load balancing and failure recovery.

Multiple adapter instances with the same consumer group will share event processing, enabling horizontal scaling and fault tolerance.

Signature

consumerGroup: string;

deleteConsumerGroupOnClose

When true, deletes the Kafka consumer group when the adapter is closed.

Useful for ephemeral adapters with dynamic consumer groups (e.g., UUID-based) to prevent accumulation of stale consumer groups in Kafka.

Signature

deleteConsumerGroupOnClose?: boolean;

errorHandler

Optional custom error handler for event processing failures.

If not provided, a default handler logs the error and continues processing. Use this for custom error reporting, retry logic, or dead letter queues.

Signature

errorHandler?: (adapter: EventAdapter, event: EventicleEvent, error: Error) => Promise<void>;

handleEvent

Event processing function called for each live event.

Should be idempotent as events may be redelivered during failures. Typically integrates with external systems or triggers side effects.

Signature

handleEvent: (event: EventicleEvent) => Promise<void>;

name

Unique adapter identifier for monitoring and debugging.

Should be descriptive of the adapter’s purpose (e.g., 'crm-sync', 'email-notifications').

Signature

name: string;

streamsToSubscribe

List of event streams to monitor for live events.

Adapter will receive all new events from these streams. Use specific stream names to reduce noise and improve performance.

Signature

streamsToSubscribe: string[];