/**
 * EventBatcher — client-side telemetry batcher
 * @module api/event-batcher
 *
 * SMI-4119: Batch telemetry events to reduce Supabase edge function invocations.
 *
 * Flushes on:
 *  - size   : queue reaches `maxBatchSize` (default 20)
 *  - time   : `maxWaitMs` elapsed since first enqueue in the current batch (default 10s)
 *  - exit   : `beforeExit` / `SIGINT` / `SIGTERM` (drain with `drainTimeoutMs`, default 2s)
 *
 * POSTs to `/events` with `{events: [...]}` and `X-Skillsmith-Batched: true` header.
 * On failure: retry once after `retryDelayMs` (default 2s); on second failure, drop silently
 * (matches the existing "fail silently" contract on telemetry).
 */
import type { TelemetryEvent } from './client.js';
/**
 * Flush function signature. Returns a resolved promise on success, rejects on failure.
 * Must throw / reject on non-2xx responses so the batcher can retry.
 */
export type BatchFlushFn = (events: TelemetryEvent[]) => Promise<void>;
/**
 * Construction options for EventBatcher (all optional; defaults documented inline).
 */
export interface EventBatcherOptions {
    /** Max events per batch before forced flush. Default: 20 (aligns with edge function max). */
    maxBatchSize?: number;
    /** Max ms to wait after first enqueue before flushing. Default: 10_000. */
    maxWaitMs?: number;
    /** Delay before retry on first flush failure. Default: 2_000. */
    retryDelayMs?: number;
    /** Max time to wait during process-exit drain. Default: 2_000. */
    drainTimeoutMs?: number;
    /** Attach process-exit listeners. Default: true. Disable in tests to avoid handler leaks. */
    registerExitHandlers?: boolean;
}
/**
 * In-memory batcher. Single-process, fire-and-forget.
 */
export declare class EventBatcher {
    private queue;
    private timer;
    private activeFlush;
    private readonly maxBatchSize;
    private readonly maxWaitMs;
    private readonly retryDelayMs;
    private readonly drainTimeoutMs;
    private readonly flushFn;
    private exitHandlersAttached;
    private disposed;
    constructor(flushFn: BatchFlushFn, options?: EventBatcherOptions);
    /**
     * Enqueue an event. Flushes immediately if the batch reaches `maxBatchSize`.
     * Fire-and-forget — errors are swallowed.
     */
    enqueue(event: TelemetryEvent): void;
    /**
     * Force a flush of any queued events. Resolves when the in-flight POST completes.
     * Used by shutdown paths and tests.
     */
    flush(): Promise<void>;
    /**
     * Current queue depth (observability / tests).
     */
    size(): number;
    /**
     * Detach exit handlers and clear timers. Call when disposing short-lived clients.
     */
    dispose(): void;
    private clearTimer;
    private flushNow;
    private doFlushWithRetry;
    private attachExitHandlers;
    private detachExitHandlers;
    private drainHandler;
}
/**
 * Factory for an EventBatcher bound to a POST function.
 */
export declare function createEventBatcher(flushFn: BatchFlushFn, options?: EventBatcherOptions): EventBatcher;
//# sourceMappingURL=event-batcher.d.ts.map