import type { Files } from "../index.js";
/** A bucket-notification format `files-sdk/events` can read. */
export type EventFormat = "s3" | "r2" | "gcs" | "azure" | "b2" | "tigris" | "supabase" | "cloudinary" | "appwrite" | "box" | "memory";
/**
 * The notification format an adapter's provider sends for this bucket, as
 * `files.capabilities.events` reports it. `files-sdk/events` reads it
 * to parse deliveries.
 */
export interface EventCapability {
    format: EventFormat;
}
/** What happened to a key. Providers rarely tell an overwrite from a create, so these two are the honest common subset; a copy or move arrives as `created` (and `deleted`). */
export type FileEventType = "created" | "deleted";
/**
 * Where an event came from: the provider's own notification (`parse()`,
 * `webhook()`, `dispatch()`, the memory adapter), a gateway upload completion,
 * or a write made through this `Files` instance (`events({ sdk: true })`).
 */
export type FileEventSource = "provider" | "gateway" | "sdk";
export interface FileEvent {
    type: FileEventType;
    /** Caller-facing: URL-decoded, the instance `prefix` stripped. */
    key: string;
    size?: number;
    etag?: string;
    versionId?: string;
    /** Only when the delivery carries it (GCS, Azure, the gateway, the SDK). */
    contentType?: string;
    /** When it happened, ms since the epoch (like `lastModified`). */
    time: number;
    source: FileEventSource;
    /** The adapter's `name` (`"s3"`, `"r2-binding"`, `"memory"`, …). */
    provider: string;
    /**
     * The idempotency key. Delivery is at-least-once on every provider, so a
     * handler sees the same event again on a redelivery; this id stays the same.
     * The provider's event id where it has one, else derived from the key and the
     * provider's per-write sequencer, or its version, event time and ETag, else a
     * stable hash of the raw record. Never derived from the local clock.
     */
    id: string;
    /** The provider's original record, untouched. */
    raw: unknown;
}
/**
 * The `Files` method `files-sdk/events` calls to map a provider event onto an
 * instance: drop it when it falls outside the instance `prefix`, strip the
 * prefix, then fold it through each plugin's `event` hook. A registry symbol so
 * it survives a consumer loading the core and the plugin from different
 * bundles, and stays off the instance's public surface.
 */
export declare const FOLD_PROVIDER_EVENT: unique symbol;
/** The part of `files.events` the gateway feeds upload completions into. */
export interface EventSink {
    emit: (events: FileEvent | readonly FileEvent[]) => Promise<void>;
}
/** `files.events` when the `files-sdk/events` plugin is installed on `files`. */
export declare const eventSinkOf: (files: Files) => EventSink | undefined;
/**
 * A gateway upload completion as a `FileEvent` (`source: "gateway"`). `key` is
 * the key in the `Files` instance (authorize's `keyPrefix` applied), the same
 * namespace provider events land in; `id` derives from the gateway's
 * `uploadId`, so a replayed `complete` carries the same one.
 */
export declare const gatewayUploadEvent: (provider: string, upload: {
    key: string;
    size: number;
    contentType: string;
    etag?: string;
    lastModified?: number;
    uploadId: string;
}) => FileEvent;
//# sourceMappingURL=events.d.ts.map