/**
 * sqlfu/outbox — a small transactional-outbox / job-queue built on any sqlfu
 * `Client` (sync or async). Sync clients get plain return values from
 * `setup()`, `emit()`, and `claim()`; async clients get Promises. `tick()`
 * is always async because consumer handlers are.
 *
 * SQLite serialises writers for us, so claim-and-lease works as a plain
 * `BEGIN; select pending; update to running; commit` — no row-locking dance
 * needed.
 *
 * Zero Node-only dependencies: causation propagation is explicit (the handler
 * receives an `emit` helper already bound to its own job context) rather than
 * via `AsyncLocalStorage`, which keeps this module runnable in browsers, edge
 * workers, and anywhere else sqlfu already runs.
 *
 * The body of each method is written once as a generator. `client.sync` picks
 * the right driver (`driveSync` / `driveAsync`) so the runtime shape matches
 * the input client without two parallel implementations to keep in step.
 */
import type { Client, SyncClient } from '../types.js';
export type TimeUnit = 's' | 'm' | 'h' | 'd';
export type TimePeriod = `${number}${TimeUnit}`;
export type JobContext = {
    jobId: number;
    eventId: number;
    attempt: number;
    consumerName: string;
};
export type Causation = {
    eventId: number;
    consumerName: string;
    jobId: number;
};
export type WhenFn<TPayload> = (input: {
    payload: TPayload;
}) => boolean | null | undefined | '';
export type DelayFn<TPayload> = (input: {
    payload: TPayload;
}) => TimePeriod;
export type RetryOutcome = {
    retry: false;
    reason: string;
    delay?: never;
} | {
    retry: true;
    reason: string;
    delay: TimePeriod;
};
export type RetryFn = (job: JobContext, error: unknown) => RetryOutcome;
export type EmitInput<TEvents extends EventMap, K extends keyof TEvents> = {
    name: K;
    payload: TEvents[K];
};
export type EmitOptions<TClient extends Client = Client> = {
    /** Pass a transaction client to make emit atomic with the surrounding domain write. */
    client?: TClient;
};
export type EmitResult = {
    eventId: number;
};
/**
 * Pick `TSync` for `SyncClient`s, `TAsync` for `AsyncClient`s. When `TClient`
 * is the open `Client` union, `TSync | TAsync` falls out — that's what
 * external callers typing `Outbox<Events>` (without parameterising over the
 * client) get.
 */
type MaybeAsync<TClient extends Client, TSync, TAsync> = TClient extends SyncClient ? TSync : TAsync;
export type EmitFn<TEvents extends EventMap, TClient extends Client = Client> = <K extends keyof TEvents>(event: EmitInput<TEvents, K>, options?: EmitOptions<TClient>) => MaybeAsync<TClient, EmitResult, Promise<EmitResult>>;
export type ConsumerHandlerInput<TPayload, TEvents extends EventMap> = {
    payload: TPayload;
    eventId: number;
    eventName: string;
    job: {
        id: number;
        attempt: number;
    };
    /**
     * Emit a follow-up event from inside this handler. This `emit` is pre-bound
     * to the running job's causation, so the downstream event's
     * `context.causedBy` points back to this job/consumer/event automatically.
     *
     * Always async-shaped, regardless of the underlying client: handlers are
     * always async, so awaiting the bound emit costs nothing and keeps consumer
     * code uniform.
     */
    emit: EmitFn<TEvents>;
};
export type ConsumerDefinition<TPayload, TEvents extends EventMap = EventMap> = {
    name: string;
    when?: WhenFn<TPayload>;
    delay?: DelayFn<TPayload>;
    retry?: RetryFn;
    visibilityTimeout?: TimePeriod;
    handler: (input: ConsumerHandlerInput<TPayload, TEvents>) => Promise<void>;
};
export type OutboxDefaults = {
    visibilityTimeout?: TimePeriod;
    retry?: RetryFn;
    /** Hard cap on attempts: once reached after a failed run, the job transitions to `failed` regardless of `retry`. */
    maxAttempts?: number;
    /** Application environment tag written onto every event — useful when the same DB sees events from dev + CI. */
    environment?: string;
    /** How many jobs to claim per tick(). */
    batchSize?: number;
    /**
     * Hook for bookkeeping errors — updates that fail after a handler has
     * already run its side effects. Default is `console.warn`; pass a custom
     * logger or Sentry hook to surface these in production. Distinct from
     * handler errors, which are routed through the retry policy.
     */
    onBookkeepingError?: (error: unknown, job: JobContext) => void;
};
export type EventMap = Record<string, unknown>;
export type OutboxConsumers<TEvents extends EventMap> = {
    [K in keyof TEvents]?: ConsumerDefinition<TEvents[K], TEvents>[];
};
export type OutboxConfig<TEvents extends EventMap, TClient extends Client = Client> = {
    client: TClient;
    consumers: OutboxConsumers<TEvents>;
    now?: () => Date;
    defaults?: OutboxDefaults;
};
export type ClaimedJob = {
    id: number;
    event_id: number;
    consumer_name: string;
    event_name: string;
    event_payload: string;
    event_context: string;
    attempt: number;
    vt_until: number;
};
export type TickResult = {
    claimed: number;
    succeeded: number;
    failed: number;
    retried: number;
};
export interface Outbox<TEvents extends EventMap, TClient extends Client = Client> {
    setup(): MaybeAsync<TClient, void, Promise<void>>;
    emit: EmitFn<TEvents, TClient>;
    tick(): Promise<TickResult>;
    claim(input?: {
        limit?: number;
    }): MaybeAsync<TClient, ClaimedJob[], Promise<ClaimedJob[]>>;
}
export declare function defineConsumer<TPayload, TEvents extends EventMap = EventMap>(definition: ConsumerDefinition<TPayload, TEvents>): ConsumerDefinition<TPayload, TEvents>;
export declare function createOutbox<TEvents extends EventMap, TClient extends Client = Client>(config: OutboxConfig<TEvents, TClient>): Outbox<TEvents, TClient>;
export {};