import type { FastifyRequest } from "fastify";
type Awaitable<T> = T | Promise<T>;
export interface IdempotencyAcquireInput {
    storageKey: string;
    fingerprint: string;
    leaseToken: string;
    now: number;
    leaseExpiresAt: number;
    recordExpiresAt: number;
}
export type IdempotencyAcquireResult<TResponse> = {
    kind: "acquired";
} | {
    kind: "replay";
    response: TResponse;
} | {
    kind: "conflict";
} | {
    kind: "in_progress";
    retryAt: number;
};
export interface IdempotencyCompleteInput<TResponse> {
    storageKey: string;
    leaseToken: string;
    response: TResponse;
    now: number;
    recordExpiresAt: number;
}
/**
 * Durable adapters must linearize operations per storageKey. The lease token is a
 * fencing token: complete and release may mutate only the record owned by that
 * token. Responses must be serializable by the selected adapter.
 */
export interface IdempotencyStore<TResponse> {
    acquire(input: IdempotencyAcquireInput): Promise<IdempotencyAcquireResult<TResponse>>;
    complete(input: IdempotencyCompleteInput<TResponse>): Promise<boolean>;
    release(storageKey: string, leaseToken: string): Promise<boolean>;
    purgeExpired(now: number, limit?: number): Promise<number>;
    close?(): Awaitable<void>;
}
export interface LocalIdempotencyStoreOptions<TResponse> {
    maxEntries?: number;
    cleanupIntervalMs?: number;
    cloneResponse?: (response: TResponse) => TResponse;
}
export declare class IdempotencyStoreCapacityError extends Error {
    readonly retryAt?: number;
    constructor(retryAt?: number);
}
/**
 * A bounded single-process adapter. It is useful for local deployments and tests;
 * multi-instance deployments should provide a database or Redis implementation of
 * IdempotencyStore so acquisition and fencing remain shared and atomic.
 */
export declare class LocalIdempotencyStore<TResponse> implements IdempotencyStore<TResponse> {
    private readonly entries;
    private readonly maxEntries;
    private readonly cleanupIntervalMs;
    private readonly cloneResponse;
    private lastCleanupAt;
    constructor(options?: LocalIdempotencyStoreOptions<TResponse>);
    get size(): number;
    acquire(input: IdempotencyAcquireInput): Promise<IdempotencyAcquireResult<TResponse>>;
    complete(input: IdempotencyCompleteInput<TResponse>): Promise<boolean>;
    release(storageKey: string, leaseToken: string): Promise<boolean>;
    purgeExpired(now: number, limit?: number): Promise<number>;
    close(): void;
    private earliestExpiry;
}
export interface IdempotencyCoordinatorOptions {
    leaseMs?: number;
    retentionMs?: number;
    maxKeyLength?: number;
    now?: () => number;
    leaseToken?: () => string;
}
export interface BeginIdempotencyInput {
    actorId: string;
    scope: string;
    key: string;
    fingerprint: string;
}
export interface IdempotencyLease {
    storageKey: string;
    leaseToken: string;
}
export type BeginIdempotencyResult<TResponse> = {
    kind: "acquired";
    lease: IdempotencyLease;
} | {
    kind: "replay";
    response: TResponse;
} | {
    kind: "conflict";
} | {
    kind: "in_progress";
    retryAfterMs: number;
};
export type ExecuteIdempotencyResult<TResponse> = {
    kind: "executed";
    response: TResponse;
} | {
    kind: "replay";
    response: TResponse;
} | {
    kind: "conflict";
} | {
    kind: "in_progress";
    retryAfterMs: number;
};
export declare class IdempotencyLeaseLostError extends Error {
    constructor();
}
export declare class IdempotencyCoordinator<TResponse> {
    private readonly store;
    private readonly leaseMs;
    private readonly retentionMs;
    private readonly maxKeyLength;
    private readonly now;
    private readonly leaseToken;
    constructor(store: IdempotencyStore<TResponse>, options?: IdempotencyCoordinatorOptions);
    begin(input: BeginIdempotencyInput): Promise<BeginIdempotencyResult<TResponse>>;
    complete(lease: IdempotencyLease, response: TResponse): Promise<boolean>;
    release(lease: IdempotencyLease): Promise<boolean>;
    execute(input: BeginIdempotencyInput, operation: () => Promise<TResponse>): Promise<ExecuteIdempotencyResult<TResponse>>;
    close(): Promise<void>;
}
export interface RequestFingerprintInput {
    action: string;
    method?: string;
    contentType?: string;
    query?: unknown;
    payload?: unknown;
}
/** Hashes canonical JSON, so object key order does not create false conflicts. */
export declare function createRequestFingerprint(input: RequestFingerprintInput): string;
/**
 * Uses Fastify's route template rather than the raw URL. Callers may override the
 * payload when the body is not JSON (for example, with a precomputed file digest).
 */
export declare function fingerprintFastifyRequest(request: Pick<FastifyRequest, "body" | "headers" | "method" | "query" | "routeOptions" | "url">, payload?: unknown): string;
export declare function idempotencyRequestAction(request: Pick<FastifyRequest, "method" | "url">): string;
export declare function idempotencyKeyFromRequest(request: Pick<FastifyRequest, "headers">): string | undefined;
export declare function createIdempotencyStorageKey(input: Pick<BeginIdempotencyInput, "actorId" | "scope" | "key">): string;
export {};
//# sourceMappingURL=idempotency.d.ts.map