@flowcore/data-pump 0.21.4 → 0.23.0

package/dist/mod.d.ts

@@ -0,0 +1,648 @@
+import { FlowcoreEvent, FlowcoreClient, EventListOutput } from '@flowcore/sdk';
+import { Registry, Gauge, Counter, Histogram } from 'prom-client';
+import * as Nats from 'nats';
+
+type FlowcoreDataPumpAuth = {
+    apiKey: string;
+    /**
+     * The ID of the API key.
+     * @deprecated Use apiKey only instead (apiKeyId is only used for old api keys).
+     */
+    apiKeyId?: string;
+} | {
+    getBearerToken: () => Promise<string>;
+};
+interface FlowcoreDataPumpState {
+    timeBucket: string;
+    eventId?: string;
+}
+interface FlowcoreDataPumpDataSource {
+    tenant: string;
+    dataCore: string;
+    flowType: string;
+    eventTypes: string[];
+}
+interface FlowcoreDataPumpStateManager {
+    getState: () => Promise<FlowcoreDataPumpState | null> | FlowcoreDataPumpState | null;
+    setState?: (state: FlowcoreDataPumpState) => Promise<void> | void;
+}
+interface FlowcoreLogger {
+    debug: (message: string, metadata?: Record<string, unknown>) => void;
+    info: (message: string, metadata?: Record<string, unknown>) => void;
+    warn: (message: string, metadata?: Record<string, unknown>) => void;
+    error: (message: string | Error, metadata?: Record<string, unknown>) => void;
+}
+interface FlowcoreDataPumpProcessor {
+    concurrency?: number;
+    handler: (events: FlowcoreEvent[]) => Promise<void>;
+    failedHandler?: (events: FlowcoreEvent[]) => void | Promise<void>;
+}
+interface FlowcoreDataPumpCoordinator {
+    acquireLease(instanceId: string, key: string, ttlMs: number): Promise<boolean>;
+    renewLease(instanceId: string, key: string, ttlMs: number): Promise<boolean>;
+    releaseLease(instanceId: string, key: string): Promise<void>;
+    register(instanceId: string, address: string): Promise<void>;
+    heartbeat(instanceId: string): Promise<void>;
+    unregister(instanceId: string): Promise<void>;
+    getInstances(staleThresholdMs: number): Promise<Array<{
+        instanceId: string;
+        address: string;
+    }>>;
+}
+
+/**
+ * @module data-source
+ * @description Provides functionality to interact with Flowcore data sources
+ */
+
+/**
+ * Options for configuring a Flowcore data source
+ * @interface FlowcoreDataSourceOptions
+ */
+interface FlowcoreDataSourceOptions {
+    /** Authentication information for Flowcore */
+    auth: FlowcoreDataPumpAuth;
+    /** Data source configuration */
+    dataSource: FlowcoreDataPumpDataSource;
+    /** Optional base URL override for the Flowcore API */
+    baseUrlOverride?: string;
+    /** When true, disables name-to-ID translation for tenant, dataCore, flowType, and eventTypes */
+    noTranslation?: boolean;
+    /** When true, executes commands in direct mode */
+    directMode?: boolean;
+}
+/**
+ * Provides methods to interact with a Flowcore data source
+ * @class FlowcoreDataSource
+ */
+declare class FlowcoreDataSource {
+    protected readonly options: FlowcoreDataSourceOptions;
+    /** Flowcore client instance */
+    protected flowcoreClient: FlowcoreClient;
+    /** Cached tenant ID */
+    protected tenantId?: string;
+    /** Cached data core ID */
+    protected dataCoreId?: string;
+    /** Cached flow type ID */
+    protected flowTypeId?: string;
+    /** Cached event type IDs */
+    protected eventTypeIds?: string[];
+    /** Cached time buckets */
+    protected timeBuckets?: string[];
+    /** Index for each cached bucket. */
+    private timeBucketIndexes;
+    /**
+     * Creates a new FlowcoreDataSource instance
+     * @param options - Configuration options for the data source
+     */
+    constructor(options: FlowcoreDataSourceOptions);
+    /**
+     * Gets the tenant name from the data source configuration
+     * @returns Tenant name
+     */
+    get tenant(): string;
+    /**
+     * Gets the data core name from the data source configuration
+     * @returns Data core name
+     */
+    get dataCore(): string;
+    /**
+     * Gets the flow type name from the data source configuration
+     * @returns Flow type name
+     */
+    get flowType(): string;
+    /**
+     * Gets the event type names from the data source configuration
+     * @returns Array of event type names
+     */
+    get eventTypes(): string[];
+    /**
+     * Gets the tenant ID, translating from name if necessary
+     * @returns Promise that resolves to the tenant ID
+     */
+    getTenantId(): Promise<string>;
+    /**
+     * Gets the data core ID, translating from name if necessary
+     * @returns Promise that resolves to the data core ID
+     */
+    getDataCoreId(): Promise<string>;
+    /**
+     * Gets the flow type ID, translating from name if necessary
+     * @returns Promise that resolves to the flow type ID
+     */
+    getFlowTypeId(): Promise<string>;
+    /**
+     * Gets the event type IDs, translating from names if necessary
+     * @returns Promise that resolves to an array of event type IDs
+     * @throws Error if an event type is not found
+     */
+    getEventTypeIds(): Promise<string[]>;
+    /**
+     * Gets all time buckets for the configured event types
+     * @param force - When true, forces a refresh of cached time buckets
+     * @returns Promise that resolves to an array of time bucket strings
+     */
+    getTimeBuckets(force?: boolean): Promise<string[]>;
+    private lowerBoundTimeBucket;
+    private upperBoundTimeBucket;
+    /**
+     * Gets the next time bucket after the specified time bucket
+     * @param timeBucket - The reference time bucket
+     * @returns Promise that resolves to the next time bucket, or null if none exists
+     */
+    getNextTimeBucket(timeBucket: string): Promise<string | null>;
+    /**
+     * Gets the closest time bucket to the specified time bucket
+     * @param timeBucket - The reference time bucket
+     * @param getBefore - When true, gets the closest time bucket before the reference
+     * @returns Promise that resolves to the closest time bucket, or null if none exists
+     * @throws Error if the time bucket format is invalid
+     */
+    getClosestTimeBucket(timeBucket: string, getBefore?: boolean): Promise<string | null>;
+    /**
+     * Gets events from the data source starting from a specific state
+     * @param from - The state to start from (includes timeBucket and eventId)
+     * @param amount - Maximum number of events to retrieve
+     * @param toEventId - Optional ID to stop at when retrieving events
+     * @returns Promise that resolves to an array of Flowcore events
+     */
+    getEvents(from: FlowcoreDataPumpState, amount: number, toEventId?: string, cursor?: string, includeSensitiveData?: boolean): Promise<EventListOutput>;
+}
+
+/**
+ * Log level for pulse emitter events. Corresponds to FlowcoreLogger methods.
+ */
+type PulseLogLevel = "debug" | "info" | "warn" | "error";
+interface PulseEmitterOptions {
+    url: string;
+    intervalMs?: number;
+    auth: FlowcoreDataPumpAuth;
+    logger?: FlowcoreLogger;
+    /** Log level for successful pulses. Defaults to 'debug'. */
+    successLogLevel?: PulseLogLevel;
+    /** Log level for pulse failures. Defaults to 'warn'. */
+    failureLogLevel?: PulseLogLevel;
+}
+interface PulseSnapshot {
+    pathwayId: string;
+    sourceId?: string;
+    flowType: string;
+    timeBucket: string;
+    eventId: string | undefined;
+    isLive: boolean;
+    /** Delivery to the processor is paused. The pump is still fetching and alive. */
+    paused: boolean;
+    bufferDepth: number;
+    bufferReserved: number;
+    bufferSizeBytes: number;
+    acknowledgedTotal: number;
+    failedTotal: number;
+    pulledTotal: number;
+    uptimeMs: number;
+}
+declare class PulseEmitter {
+    private readonly options;
+    private readonly getSnapshot;
+    private interval;
+    private startTimeout;
+    private readonly intervalMs;
+    private readonly logger?;
+    private readonly successLogLevel;
+    private readonly failureLogLevel;
+    constructor(options: PulseEmitterOptions, getSnapshot: () => PulseSnapshot | null);
+    start(): void;
+    stop(): void;
+    private emitSafe;
+    private emit;
+}
+
+interface FlowcoreDataPumpNotifierNatsOptions {
+    type: "nats";
+    servers: string[];
+}
+interface FlowcoreDataPumpNotifierWebsocketOptions {
+    type: "websocket";
+}
+interface FlowcoreDataPumpNotifierPollerOptions {
+    type: "poller";
+    /**
+     * The interval in milliseconds to poll the data pump state (min 1000 ms)
+     */
+    intervalMs: number;
+}
+type FlowcoreDataPumpNotifierOptions = FlowcoreDataPumpNotifierNatsOptions | FlowcoreDataPumpNotifierWebsocketOptions | FlowcoreDataPumpNotifierPollerOptions;
+interface FlowcoreDataPumpOptions {
+    auth: FlowcoreDataPumpAuth;
+    dataSource: FlowcoreDataPumpDataSource;
+    stateManager: FlowcoreDataPumpStateManager;
+    bufferSize?: number;
+    maxRedeliveryCount?: number;
+    achknowledgeTimeoutMs?: number;
+    includeSensitiveData?: boolean;
+    processor?: FlowcoreDataPumpProcessor;
+    notifier?: FlowcoreDataPumpNotifierOptions;
+    logger?: FlowcoreLogger;
+    stopAt?: Date;
+    /**
+     * Start the pump with delivery already paused.
+     *
+     * Use this to restore a pause that is stored somewhere durable. Calling `pause()`
+     * after `start()` would let the pump deliver events in the gap between the two.
+     * Ignored when no `processor` is configured, for the same reason as {@link FlowcoreDataPump.pause}.
+     */
+    paused?: boolean;
+    baseUrlOverride?: string;
+    noTranslation?: boolean;
+    directMode?: boolean;
+    pulse?: {
+        url: string;
+        intervalMs?: number;
+        pathwayId: string;
+        sourceId?: string;
+        /** Log level for successful pulses. Defaults to 'debug'. */
+        successLogLevel?: "debug" | "info" | "warn" | "error";
+        /** Log level for pulse failures. Defaults to 'warn'. */
+        failureLogLevel?: "debug" | "info" | "warn" | "error";
+    };
+}
+declare class FlowcoreDataPump {
+    readonly dataSource: FlowcoreDataSource;
+    private readonly notifier;
+    private stateManager;
+    private readonly options;
+    private readonly logger?;
+    private nextCursor?;
+    private running;
+    private paused;
+    private restartTo?;
+    private processLoopGeneration;
+    private activeProcessLoopGeneration?;
+    private processLoopBackoffGeneration?;
+    private processLoopRestartTimer?;
+    private abortController?;
+    private buffer;
+    private bufferState;
+    private stopAtState?;
+    private isLive;
+    private finallyFailedHandler?;
+    private pulseEmitter?;
+    private startedAt;
+    private acknowledgedCount;
+    private failedCount;
+    private pulledCount;
+    private processLoopRestartAttempts;
+    private mainLoopRestartAttempts;
+    private readonly replayObserver;
+    private readonly bufferStats;
+    private bufferReservedCount;
+    private bufferSizeBytes;
+    private gaugePublicationScheduled;
+    private constructor();
+    /**
+     * Whether delivery to the processor is currently paused.
+     * A paused pump is still running: it fetches, buffers and pulses.
+     */
+    get isPaused(): boolean;
+    get isRunning(): boolean;
+    getSnapshot(): PulseSnapshot | null;
+    static create(options: FlowcoreDataPumpOptions, dataSourceOverride?: FlowcoreDataSource): FlowcoreDataPump;
+    start(callback?: (error?: Error) => void): Promise<void>;
+    private startMainLoop;
+    restart(state: FlowcoreDataPumpState, stopAt?: Date | null): void;
+    /**
+     * Pause delivery to the processor.
+     *
+     * The fetch loop keeps running and tops the buffer up to `bufferSize`, then blocks on
+     * normal backpressure. The buffer, the cursor and the pulse emitter are untouched, so
+     * the control plane still sees a live pump. An in-flight batch finishes its handler
+     * and acknowledges, so the checkpoint stays accurate and nothing is redelivered
+     * needlessly.
+     *
+     * Idempotent. A paused pump holds up to `bufferSize` events in memory.
+     */
+    pause(): void;
+    /**
+     * Resume delivery to the processor from the exact position where {@link pause} stopped it.
+     * Idempotent.
+     */
+    resume(): void;
+    stop(isRestart?: boolean): void;
+    private updateState;
+    private loop;
+    reserve(amount: number): Promise<FlowcoreEvent[]>;
+    private reserveInternal;
+    onFinalyFailed(handler: (events: FlowcoreEvent[]) => Promise<void> | void): void;
+    acknowledge(eventIds: string[]): Promise<void>;
+    fail(eventIds: string[]): Promise<void>;
+    private reOpen;
+    /**
+     * Guarantee a live process loop whenever the pump is running with a
+     * processor. Called from the fetch loop, so a delivery loop that exited for
+     * any reason — most importantly a restart, which clears `running` while the
+     * loop is mid-batch — comes back within one fetch iteration instead of
+     * leaving a pump that pulls but never delivers.
+     */
+    private ensureProcessLoop;
+    private startProcessLoop;
+    private isCurrentProcessLoop;
+    private processLoop;
+    private addEventsToBuffer;
+    private updateReservedStats;
+    private removeFromBufferStats;
+    private resetBufferStats;
+    private updateMetricsGauges;
+    private publishMetricsGauges;
+    private incMetricsCounter;
+    private publicEventWaiter?;
+    private readonly processEventWaiters;
+    private notifyEventWaiters;
+    private waitForEvents;
+    private waiterBufferThreshold?;
+    private waitForBufferThreshold;
+    private waiterBufferEmpty?;
+    private notifyBufferEmpty;
+    private waitForBufferEmpty;
+}
+
+interface FlowcoreDataPumpClusterOptions extends FlowcoreDataPumpOptions {
+    coordinator: FlowcoreDataPumpCoordinator;
+    advertisedAddress?: string;
+    dataSourceOverride?: FlowcoreDataSource;
+    leaseTtlMs?: number;
+    leaseRenewIntervalMs?: number;
+    heartbeatIntervalMs?: number;
+    workerConcurrency?: number;
+    clusterKey?: string;
+}
+declare class FlowcoreDataPumpCluster {
+    private readonly options;
+    private readonly instanceId;
+    private readonly coordinator;
+    private readonly leaseTtlMs;
+    private readonly leaseRenewIntervalMs;
+    private readonly heartbeatIntervalMs;
+    private readonly workerConcurrency;
+    private readonly logger?;
+    private running;
+    private isLeader;
+    private paused;
+    private pump?;
+    private leaderConnection?;
+    private workers;
+    private workerRoundRobinIndex;
+    private leaseRenewInterval?;
+    private discoveryInterval?;
+    private heartbeatInterval?;
+    private electionInterval?;
+    private workerHandler?;
+    private workerFailedHandler?;
+    private pumpRestartAttempts;
+    private natsConnectionManager?;
+    private natsDistLeader?;
+    private natsDistWorker?;
+    constructor(options: FlowcoreDataPumpClusterOptions);
+    private get useNatsDistribution();
+    private get natsDistributionSubject();
+    get isRunning(): boolean;
+    get isLeaderInstance(): boolean;
+    get activeWorkerCount(): number;
+    get id(): string;
+    /**
+     * Handle an incoming WebSocket connection from a peer.
+     * Call this from your HTTP server's WebSocket upgrade handler.
+     *
+     * Example (Bun):
+     * ```typescript
+     * Bun.serve({
+     *   port: 8080,
+     *   fetch(req, server) {
+     *     if (server.upgrade(req)) return undefined
+     *     return new Response("Not found", { status: 404 })
+     *   },
+     *   websocket: {
+     *     open(socket) {
+     *       cluster.handleConnection(socket as unknown as WebSocket)
+     *     },
+     *     message() {},
+     *   },
+     * })
+     * ```
+     *
+     * Example (Node.js with ws):
+     * ```typescript
+     * import { WebSocketServer } from "ws"
+     * const wss = new WebSocketServer({ port: 8080 })
+     * wss.on("connection", (ws) => cluster.handleConnection(ws))
+     * ```
+     */
+    handleConnection(ws: WebSocket): void;
+    start(): Promise<void>;
+    /**
+     * Whether delivery is paused across the cluster.
+     * The flag lives on the cluster, so it survives a leader change.
+     */
+    get isPaused(): boolean;
+    /**
+     * Pause delivery. A leader applies it to its pump immediately. A follower records it,
+     * so the pause is re-applied if this instance later becomes leader.
+     *
+     * The flag is in-memory. It does NOT survive a process restart or a full rolling
+     * deploy — persist it in the coordinator or the control plane if you need that.
+     */
+    pause(): void;
+    /** Resume delivery from the position where {@link pause} stopped it. */
+    resume(): void;
+    stop(): Promise<void>;
+    private startHeartbeat;
+    private startElectionLoop;
+    private attemptElection;
+    private becomeLeader;
+    private stepDownAsLeader;
+    private startPumpAsLeader;
+    private distributeEvents;
+    private distributeEventsNats;
+    private distributeEventsWs;
+    private selectWorker;
+    private startWorkerDiscovery;
+    private discoverWorkers;
+    private connectToWorker;
+    private handleWorkerDisconnect;
+    private scheduleReconnect;
+    private handleLeaderMessage;
+    private handleWorkerMessage;
+}
+
+declare const dataPumpPromRegistry: Registry<"text/plain; version=0.0.4; charset=utf-8">;
+declare const REPLAY_DURATION_BUCKETS_SECONDS: readonly [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 20, 30, 60, 120];
+declare const REPLAY_EVENT_COUNT_BUCKETS: readonly [1, 10, 50, 100, 250, 500, 1000, 2000, 5000, 10000];
+declare const REPLAY_BATCH_SIZE_BUCKETS: readonly ["empty", "1", "2-10", "11-100", "101-1000", "1001+"];
+declare const REPLAY_FETCH_RESULTS: readonly ["success", "no_events", "error"];
+declare const REPLAY_STAGE_RESULTS: readonly ["success", "error"];
+declare const REPLAY_IDLE_REASONS: readonly ["no_events", "buffer_full", "waiting_for_events"];
+type ReplayBatchSizeBucket = (typeof REPLAY_BATCH_SIZE_BUCKETS)[number];
+type ReplayIdleReason = (typeof REPLAY_IDLE_REASONS)[number];
+type ReplaySourceLabels = {
+    tenant: string;
+    data_core: string;
+    flow_type: string;
+};
+declare function replayBatchSizeBucket(size: number): ReplayBatchSizeBucket;
+declare function createDataPumpMetrics(registry: Registry, includeDefaultRegistry?: boolean): {
+    bufferEventCountGauge: Gauge<"tenant" | "data_core" | "flow_type" | "event_type">;
+    bufferReservedEventCountGauge: Gauge<"tenant" | "data_core" | "flow_type" | "event_type">;
+    bufferSizeBytesGauge: Gauge<"tenant" | "data_core" | "flow_type" | "event_type">;
+    eventsAcknowledgedCounter: Counter<"tenant" | "data_core" | "flow_type" | "event_type">;
+    eventsFailedCounter: Counter<"tenant" | "data_core" | "flow_type" | "event_type">;
+    eventsPulledSizeBytesCounter: Counter<"tenant" | "data_core" | "flow_type" | "event_type">;
+    sdkCommandsCounter: Counter<"command">;
+    replayFetchDuration: Histogram<"tenant" | "data_core" | "flow_type" | "result">;
+    replayFetchEvents: Histogram<"tenant" | "data_core" | "flow_type">;
+    replayHandlerDuration: Histogram<"tenant" | "data_core" | "flow_type" | "result" | "batch_size_bucket">;
+    replayAcknowledgementDuration: Histogram<"tenant" | "data_core" | "flow_type" | "result">;
+    replayCheckpointDuration: Histogram<"tenant" | "data_core" | "flow_type" | "result">;
+    replayIdleDuration: Histogram<"tenant" | "data_core" | "flow_type" | "reason">;
+};
+type DataPumpMetrics = ReturnType<typeof createDataPumpMetrics>;
+declare const metrics: {
+    bufferEventCountGauge: Gauge<"tenant" | "data_core" | "flow_type" | "event_type">;
+    bufferReservedEventCountGauge: Gauge<"tenant" | "data_core" | "flow_type" | "event_type">;
+    bufferSizeBytesGauge: Gauge<"tenant" | "data_core" | "flow_type" | "event_type">;
+    eventsAcknowledgedCounter: Counter<"tenant" | "data_core" | "flow_type" | "event_type">;
+    eventsFailedCounter: Counter<"tenant" | "data_core" | "flow_type" | "event_type">;
+    eventsPulledSizeBytesCounter: Counter<"tenant" | "data_core" | "flow_type" | "event_type">;
+    sdkCommandsCounter: Counter<"command">;
+    replayFetchDuration: Histogram<"tenant" | "data_core" | "flow_type" | "result">;
+    replayFetchEvents: Histogram<"tenant" | "data_core" | "flow_type">;
+    replayHandlerDuration: Histogram<"tenant" | "data_core" | "flow_type" | "result" | "batch_size_bucket">;
+    replayAcknowledgementDuration: Histogram<"tenant" | "data_core" | "flow_type" | "result">;
+    replayCheckpointDuration: Histogram<"tenant" | "data_core" | "flow_type" | "result">;
+    replayIdleDuration: Histogram<"tenant" | "data_core" | "flow_type" | "reason">;
+};
+declare class ReplayStageObserver {
+    private readonly stageMetrics;
+    private readonly source;
+    private readonly now;
+    constructor(stageMetrics: DataPumpMetrics, source: ReplaySourceLabels, now?: () => number);
+    observeFetch<T extends {
+        events: unknown[];
+    }>(operation: () => Promise<T>): Promise<T>;
+    observeHandler<T>(events: unknown[], operation: () => Promise<T>): Promise<T>;
+    observeAcknowledgement<T>(operation: () => T): T;
+    observeCheckpoint<T>(operation: () => Promise<T> | T): Promise<T>;
+    observeIdle<T>(reason: ReplayIdleReason, operation: () => Promise<T>): Promise<T>;
+    private observeResult;
+    private elapsedSeconds;
+}
+declare const clusterMetrics: {
+    activeWorkersGauge: Gauge<string>;
+    leaderStatusGauge: Gauge<string>;
+    eventsDistributedCounter: Counter<string>;
+    workerAcksCounter: Counter<string>;
+    workerFailsCounter: Counter<string>;
+};
+
+declare class NatsConnectionManager {
+    private readonly servers;
+    private readonly logger?;
+    private connection?;
+    private connecting?;
+    constructor(servers: string[], logger?: FlowcoreLogger | undefined);
+    connect(): Promise<Nats.NatsConnection>;
+    close(): Promise<void>;
+    get isConnected(): boolean;
+}
+
+interface NatsDistributionRequest {
+    deliveryId: string;
+    events: FlowcoreEvent[];
+}
+interface NatsDistributionReply {
+    status: "ack" | "fail";
+    error?: string;
+}
+declare class NatsDistributionLeader {
+    private readonly connection;
+    private readonly subject;
+    private readonly logger?;
+    private readonly timeoutMs;
+    private readonly codec;
+    constructor(connection: Nats.NatsConnection, subject: string, logger?: FlowcoreLogger | undefined, timeoutMs?: number);
+    distribute(events: FlowcoreEvent[]): Promise<void>;
+}
+declare class NatsDistributionWorker {
+    private readonly connection;
+    private readonly subject;
+    private readonly handler;
+    private readonly logger?;
+    private subscription?;
+    private readonly codec;
+    private readonly queueGroup;
+    constructor(connection: Nats.NatsConnection, subject: string, handler: (events: FlowcoreEvent[]) => Promise<void>, logger?: FlowcoreLogger | undefined);
+    start(): void;
+    stop(): void;
+    private handleMessage;
+}
+
+interface WsEventsMessage {
+    type: "events";
+    deliveryId: string;
+    events: FlowcoreEvent[];
+}
+interface WsAckMessage {
+    type: "ack";
+    deliveryId: string;
+    eventIds: string[];
+}
+interface WsFailMessage {
+    type: "fail";
+    deliveryId: string;
+    eventIds: string[];
+}
+interface WsPingMessage {
+    type: "ping";
+}
+interface WsPongMessage {
+    type: "pong";
+}
+type WsMessage = WsEventsMessage | WsAckMessage | WsFailMessage | WsPingMessage | WsPongMessage;
+declare function serializeMessage(msg: WsMessage): string;
+declare function deserializeMessage(data: string): WsMessage | null;
+interface WsConnectionOptions {
+    logger?: FlowcoreLogger;
+    onMessage: (msg: WsMessage) => void;
+    onClose: () => void;
+}
+declare class WsConnection {
+    private readonly ws;
+    private readonly options;
+    private pingInterval?;
+    private pongTimeout?;
+    private closed;
+    constructor(ws: WebSocket, options: WsConnectionOptions);
+    send(msg: WsMessage): void;
+    close(): void;
+    get isClosed(): boolean;
+    private startPingLoop;
+    private clearPongTimeout;
+    private cleanup;
+}
+interface PendingDelivery {
+    deliveryId: string;
+    eventIds: string[];
+    resolve: () => void;
+    reject: (error: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+}
+declare class DeliveryTracker {
+    private pending;
+    add(deliveryId: string, eventIds: string[], timeoutMs: number): Promise<void>;
+    ack(deliveryId: string): void;
+    fail(deliveryId: string): void;
+    rejectAll(error: Error): void;
+    get size(): number;
+    getPendingEventIds(): string[];
+}
+
+declare const noOpLogger: FlowcoreLogger;
+
+export { type DataPumpMetrics, DeliveryTracker, FlowcoreDataPump, type FlowcoreDataPumpAuth, FlowcoreDataPumpCluster, type FlowcoreDataPumpClusterOptions, type FlowcoreDataPumpCoordinator, type FlowcoreDataPumpDataSource, type FlowcoreDataPumpOptions, type FlowcoreDataPumpProcessor, type FlowcoreDataPumpState, type FlowcoreDataPumpStateManager, FlowcoreDataSource, type FlowcoreDataSourceOptions, type FlowcoreLogger, NatsConnectionManager, NatsDistributionLeader, type NatsDistributionReply, type NatsDistributionRequest, NatsDistributionWorker, type PendingDelivery, PulseEmitter, type PulseEmitterOptions, type PulseLogLevel, type PulseSnapshot, REPLAY_BATCH_SIZE_BUCKETS, REPLAY_DURATION_BUCKETS_SECONDS, REPLAY_EVENT_COUNT_BUCKETS, REPLAY_FETCH_RESULTS, REPLAY_IDLE_REASONS, REPLAY_STAGE_RESULTS, type ReplayBatchSizeBucket, type ReplayIdleReason, type ReplaySourceLabels, ReplayStageObserver, type WsAckMessage, WsConnection, type WsConnectionOptions, type WsEventsMessage, type WsFailMessage, type WsMessage, type WsPingMessage, type WsPongMessage, clusterMetrics, createDataPumpMetrics, dataPumpPromRegistry, deserializeMessage, metrics, noOpLogger, replayBatchSizeBucket, serializeMessage };