@8ux-co/eelzap 0.0.0-stage → 0.10.0

package/dist/index.d.cts

@@ -0,0 +1,2409 @@
+/**
+ * Pluggable storage interface for last-known-good caching.
+ *
+ * Implement this to persist content to any backend (KV, Redis,
+ * filesystem, IndexedDB, etc.). The SDK ships a built-in
+ * {@link MemoryCacheAdapter} for processes that stay alive.
+ */
+interface CacheAdapter<T = unknown> {
+    get(key: string): Promise<T | undefined> | T | undefined;
+    set(key: string, value: T): Promise<void> | void;
+}
+type CacheStrategy = 'network-first' | 'cache-first';
+interface CachedFetchOptions<T = unknown> {
+    key: string;
+    fetcher: () => Promise<T>;
+    adapter: CacheAdapter<T>;
+    strategy?: CacheStrategy;
+}
+/**
+ * Simple in-memory adapter. Suitable for long-lived server processes
+ * or development. Data is lost when the process restarts.
+ */
+declare class MemoryCacheAdapter implements CacheAdapter {
+    #private;
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    /** Returns the number of cached entries. */
+    get size(): number;
+    /** Removes a specific key from the cache. */
+    delete(key: string): boolean;
+    /** Removes all cached entries. */
+    clear(): void;
+}
+/**
+ * Caches content fetched from the CMS, with one of two strategies:
+ *
+ * - `network-first` (the default, and the only one the positional form
+ *   uses): runs `fetcher`, caches the result on success, and falls back to
+ *   the last cached value on failure.
+ * - `cache-first` (options form): returns the cached value when there is
+ *   one, and fetches and caches only on a miss.
+ *
+ * If no cached value exists and the fetch fails, the original error is
+ * re-thrown — there are no hardcoded fallbacks.
+ *
+ * A preview response (a read with `preview: true`, or any read with a `zpt_`
+ * preview token) is returned but NEVER stored, under either strategy
+ * (zap-cms-v2 §7.5): it carries drafts and stega markers, and a cache entry
+ * would hand them to the next visitor.
+ *
+ * @param key     - Stable cache key (e.g. `"homepage"`, `"blog-posts:page-1"`).
+ * @param fetcher - An async function that fetches fresh content from the CMS.
+ * @param adapter - Storage backend that persists last-known-good values.
+ * @returns The fresh result or the last successfully cached value.
+ *
+ * @example
+ * ```ts
+ * const cache = new MemoryCacheAdapter();
+ *
+ * const homepage = await cachedFetch(
+ *   'homepage',
+ *   () => cms.documents.get('homepage'),
+ *   cache,
+ * );
+ * ```
+ */
+declare function cachedFetch<T>(key: string, fetcher: () => Promise<T>, adapter: CacheAdapter<T>): Promise<T>;
+declare function cachedFetch<T>(options: CachedFetchOptions<T>): Promise<T>;
+
+/**
+ * Supported delivery status filters.
+ */
+type DeliveryStatus = 'published' | 'draft' | 'all';
+/**
+ * A primitive value accepted in query parameters.
+ */
+type QueryPrimitive = string | number | boolean;
+/**
+ * Pagination metadata returned by list endpoints.
+ */
+interface Pagination {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    total: number;
+}
+type JsonObject = {
+    [key: string]: string | number | boolean | null | JsonObject | JsonObject[];
+};
+/**
+ * Site metadata resolved from the authenticated API key.
+ */
+interface SiteInfo {
+    id: string;
+    name: string;
+    key: string;
+    /** The site's address (https; http only on a development host); null until set. */
+    url?: string | null;
+    defaultLocale: string;
+    locales: string[];
+    /**
+     * «Otros dominios»: origins beyond `url`'s own where drafts may be shown
+     * (a staging host, `http://localhost:3000`). Answered by `GET /site`.
+     */
+    previewOrigins?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * `site.update()`: where the site lives. Send at least one. Needs a `secret_`
+ * key, or a suite credential with `zap:schema:write` and an ADMIN seat.
+ */
+interface UpdateSiteInput {
+    /** https, or http on a development host such as `localhost`; `null` clears it. */
+    url?: string | null;
+    /**
+     * Replaces the stored list. Each entry is an origin: https, or
+     * `http://localhost` / `http://127.0.0.1` with any port; never a Zap or
+     * `eel.software` host. Normalised to its origin and deduplicated.
+     */
+    previewOrigins?: string[];
+}
+/**
+ * One of the workspace's sites (`GET /sites`): `GET /site`'s body plus `url`.
+ * Its `key` or its `id` is a valid `X-Eel-Site` for every other route.
+ */
+interface SiteListEntry extends SiteInfo {
+    url: string | null;
+}
+/**
+ * `GET /preview/token`: the preview token is live and was minted for the site
+ * the given site API key belongs to.
+ */
+interface PreviewTokenValidation {
+    site: {
+        key: string;
+    };
+    /** ISO 8601: when the token stops working. */
+    expiresAt?: string;
+}
+/**
+ * SEO metadata resolved for the current locale.
+ */
+interface SeoImage {
+    url: string;
+    alt: string | null;
+    width: number | null;
+    height: number | null;
+    type: string | null;
+}
+/**
+ * SEO metadata resolved for the current locale.
+ */
+interface Seo {
+    metaTitle: string | null;
+    metaDescription: string | null;
+    canonicalUrl: string | null;
+    ogUrl: string | null;
+    ogType: string | null;
+    ogLocale: string;
+    ogImage: SeoImage | null;
+    articlePublishedTime: string | null;
+    articleModifiedTime: string | null;
+    twitterCard: string;
+    noIndex: boolean;
+    noFollow: boolean;
+    keywords: string | null;
+    structuredData: JsonObject | null;
+}
+/**
+ * Collection item timestamps.
+ */
+interface ItemMeta {
+    createdAt: string;
+    updatedAt: string;
+    publishedAt: string | null;
+}
+/**
+ * Document timestamps.
+ */
+interface DocumentMeta {
+    updatedAt: string;
+    publishedAt: string | null;
+}
+/**
+ * Section metadata embedded in sectioned content groups.
+ */
+interface SectionMeta {
+    name: string;
+    key: string;
+}
+/**
+ * Enum values returned by the API.
+ */
+interface EnumValue {
+    value: string;
+    label: string;
+}
+/**
+ * A CURRENCY field's value, read and written in this one shape.
+ *
+ * `amountMinor` is in the currency's minor unit (cents: `4800000` is
+ * COP 48.000,00), an integer. `currency` is the ISO 4217 code.
+ */
+interface CurrencyValue {
+    amountMinor: number;
+    currency: string;
+}
+/**
+ * Access mode for a media value.
+ */
+type MediaAccess = 'public' | 'signed' | 'none';
+/**
+ * Media value returned by the delivery API.
+ */
+interface MediaValue {
+    id: string;
+    filename: string;
+    type: string;
+    mimeType: string;
+    size: number;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    title: string | null;
+    description: string | null;
+    status: string;
+    mediaAccess: MediaAccess;
+    url: string | null;
+    signedUrl: string | null;
+    signedUrlExpiresAt: string | null;
+}
+/**
+ * Gallery entry values returned by the API.
+ */
+interface GalleryItemValue {
+    position: number;
+    caption: string | null;
+    description: string | null;
+    media: MediaValue | null;
+}
+/**
+ * Shared request options supported by most endpoints.
+ */
+interface CommonRequestOptions {
+    locale?: string;
+    status?: DeliveryStatus;
+    fields?: string[];
+}
+/**
+ * JSON error payload returned by the delivery API.
+ */
+interface ApiErrorPayload {
+    error: {
+        code: string;
+        message: string;
+        status: number;
+        /** Per-field problems on a validation refusal. */
+        details?: ApiErrorDetail[];
+    };
+}
+/**
+ * One problem in a validation refusal: where, what, and the rule's code.
+ */
+interface ApiErrorDetail {
+    path: string;
+    message: string;
+    code: string;
+}
+/**
+ * Client-level defaults applied to every request unless overridden.
+ */
+interface ClientDefaults {
+    locale?: string;
+    status?: DeliveryStatus;
+    preview?: boolean;
+}
+/**
+ * Draft preview for the item and document reads.
+ */
+interface PreviewOption {
+    /**
+     * Sends `preview=1`: every entry is returned whatever its status, and an entry
+     * with an unpublished draft comes back with the draft's content. Responses
+     * are `private, no-store`, and `cachedFetch` never stores them. Needs a
+     * secret key that can read drafts, a preview token (`zpt_…`), or a suite
+     * bearer with `zap:content:read` or `zap:preview:read`; a public key is
+     * refused with `DRAFT_ACCESS_DENIED`.
+     */
+    preview?: boolean;
+    /**
+     * Only matters with `preview`: `false` sends `stega=0`, which turns off the
+     * invisible stega markers a preview response carries on prose fields (TEXT,
+     * LONG_TEXT, the last text node of each RICH_TEXT block) for this one
+     * request. Use it for server code that compares or keys on text, `<title>`
+     * and meta tags. Without `preview` a response never carries markers and
+     * nothing is sent.
+     */
+    stega?: boolean;
+}
+/**
+ * SEO input accepted by the public write API.
+ */
+interface SeoInput {
+    metaTitle?: string | null;
+    metaDescription?: string | null;
+    ogType?: string | null;
+    ogImageId?: string | null;
+    ogImageAlt?: string | null;
+    canonicalUrl?: string | null;
+    twitterCard?: 'SUMMARY' | 'SUMMARY_LARGE_IMAGE';
+    noIndex?: boolean;
+    noFollow?: boolean;
+    keywords?: string | null;
+    structuredData?: JsonObject | null;
+    locale?: string;
+}
+/**
+ * Delete operations can optionally remove linked media.
+ */
+interface DeleteOptions {
+    deleteMediaIds?: string[];
+}
+/** Options of a write the API deduplicates by `Idempotency-Key`. */
+interface IdempotencyOptions {
+    /** Defaults to a fresh random key per call; pass your own to make retries safe. */
+    idempotencyKey?: string;
+}
+
+/**
+ * The field types of the Zap API, exactly as its field routes accept and
+ * answer them (`collections.fields` and `documents.fields`: `create`, `list`,
+ * `update`, `restore`, `listDeleted`) and as the delivery schema reads publish
+ * them (`collections.list`, `collections.get`, `documents.list`).
+ */
+type FieldType = 'TEXT' | 'LONG_TEXT' | 'RICH_TEXT' | 'NUMBER' | 'INTEGER' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'CURRENCY' | 'ENUM' | 'GALLERY' | 'IMAGE' | 'VIDEO' | 'FILE' | 'URL' | 'EMAIL';
+/**
+ * Enum option payload for field creation and updates.
+ */
+interface FieldOptionInput {
+    label: string;
+    value: string;
+    color?: string | null;
+}
+/**
+ * Shared field constraints returned by the management API.
+ */
+interface FieldConstraints {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    regex?: string;
+    currencies?: string[];
+    [key: string]: unknown;
+}
+/**
+ * A field as the field routes answer it (`collections.fields`,
+ * `documents.fields`) and as the delivery schema reads describe it.
+ */
+interface FieldInfo {
+    id?: string;
+    key: string;
+    label: string;
+    type: FieldType;
+    required?: boolean;
+    isLocalized: boolean;
+    isSortable?: boolean;
+    isFilterable?: boolean;
+    isUnique?: boolean;
+    description?: string | null;
+    defaultValue?: string | null;
+    sectionId?: string | null;
+    galleryMinItems?: number | null;
+    galleryMaxItems?: number | null;
+    galleryAllowedTypes?: 'IMAGE' | 'VIDEO' | 'IMAGE,VIDEO' | null;
+    constraints?: FieldConstraints | null;
+    options?: EnumValue[];
+}
+/**
+ * Collection section schema information.
+ */
+interface SectionInfo {
+    id?: string;
+    key: string;
+    name: string;
+    description?: string | null;
+    order: number;
+    fields?: string[];
+}
+/**
+ * Collection summary returned in collection lists and item responses.
+ */
+interface CollectionSummary {
+    key: string;
+    name: string;
+    description: string | null;
+    itemCount: number;
+    fields?: FieldInfo[];
+    sections?: SectionInfo[];
+}
+/**
+ * Full collection schema details.
+ */
+interface CollectionDetail extends CollectionSummary {
+    fields: FieldInfo[];
+    sections: SectionInfo[];
+    sortableFields: string[];
+    filterableFields: string[];
+}
+/**
+ * Response shape for the collections list endpoint.
+ */
+interface CollectionListResponse {
+    data: CollectionSummary[];
+}
+/**
+ * Input for creating a collection.
+ */
+interface CreateCollectionInput {
+    name: string;
+    key: string;
+    description?: string;
+}
+/**
+ * Input for updating a collection.
+ */
+interface UpdateCollectionInput {
+    name?: string;
+    description?: string | null;
+    /**
+     * «Ruta en tu sitio»: the page an entry appears on, for the editor's
+     * preview — `/blog/{slug}`, `/{locale}/productos/{slug}`. `''` or `null`
+     * clears it. Starts with `/`; only `{slug}` and `{locale}`.
+     */
+    previewPath?: string | null;
+}
+/**
+ * Input for creating a collection field.
+ */
+interface CreateFieldInput {
+    key: string;
+    label?: string;
+    name?: string;
+    type: FieldType;
+    required?: boolean;
+    isLocalized?: boolean;
+    isUnique?: boolean;
+    isFilterable?: boolean;
+    isSortable?: boolean;
+    galleryMinItems?: number | null;
+    galleryMaxItems?: number | null;
+    galleryAllowedTypes?: 'IMAGE' | 'VIDEO' | 'IMAGE,VIDEO' | null;
+    description?: string | null;
+    constraints?: FieldConstraints | null;
+    defaultValue?: string | null;
+    sectionId?: string | null;
+    options?: FieldOptionInput[] | null;
+}
+/**
+ * Input for updating a collection field.
+ */
+interface UpdateFieldInput {
+    label?: string;
+    name?: string;
+    required?: boolean;
+    isLocalized?: boolean;
+    isUnique?: boolean;
+    isFilterable?: boolean;
+    isSortable?: boolean;
+    galleryMinItems?: number | null;
+    galleryMaxItems?: number | null;
+    galleryAllowedTypes?: 'IMAGE' | 'VIDEO' | 'IMAGE,VIDEO' | null;
+    description?: string | null;
+    constraints?: FieldConstraints | null;
+    defaultValue?: string | null;
+    sectionId?: string | null;
+    options?: FieldOptionInput[] | null;
+}
+/**
+ * Response payload for collection field list operations.
+ */
+interface CollectionFieldListResponse {
+    fields: FieldInfo[];
+}
+/**
+ * Input for creating a collection section.
+ */
+interface CreateSectionInput {
+    name: string;
+    description?: string | null;
+}
+/**
+ * Input for updating a collection section.
+ */
+interface UpdateSectionInput {
+    name?: string;
+    description?: string | null;
+    order?: number;
+}
+/**
+ * Response payload for collection section list operations.
+ */
+interface CollectionSectionListResponse {
+    sections: SectionInfo[];
+}
+
+/**
+ * Retries of a refused request: `429 Too Many Requests` always, and `503
+ * Service Unavailable` when it says when to come back (`Retry-After`).
+ *
+ * Only a request that is safe to repeat is retried: a read (`GET`, `HEAD`), or
+ * a write that carries an `Idempotency-Key`, which the API deduplicates. Any
+ * other write is never repeated, so a create can never land twice.
+ */
+interface RetryOptions {
+    /** Retries after the first attempt. Default `3`; `0` turns retrying off. */
+    retries?: number;
+    /**
+     * The longest single wait, in ms. Default `60000`, the API's rate window. A
+     * `Retry-After` longer than this is not waited out: the refusal is thrown.
+     */
+    maxDelayMs?: number;
+    /** The first backoff step when the answer has no `Retry-After`, in ms. Default `500`. */
+    baseDelayMs?: number;
+    /** Called before each wait, for logging. */
+    onRetry?: (event: RetryEvent) => void;
+}
+/** What {@link RetryOptions.onRetry} is told before a wait. */
+interface RetryEvent {
+    /** The retry about to happen: `1` for the first. */
+    attempt: number;
+    /** How long the client waits first, in ms. */
+    delayMs: number;
+    /** The refused answer's status: `429` or `503`. */
+    status: number;
+    method: string;
+    url: string;
+}
+/** @internal */
+type ResolvedRetry = Required<Omit<RetryOptions, 'onRetry'>> & Pick<RetryOptions, 'onRetry'>;
+
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    pathPrefix: string;
+    fetch: typeof globalThis.fetch;
+    defaultHeaders?: HeadersInit;
+    timeout: number;
+    /** Retries of a `429`/`503`; `null` or absent turns them off. */
+    retry?: ResolvedRetry | null;
+}
+interface HttpRequestOptions {
+    params?: Record<string, QueryPrimitive | undefined>;
+    headers?: HeadersInit;
+    body?: BodyInit | null;
+    contentType?: string;
+}
+/**
+ * Minimal fetch-based HTTP client for the delivery API.
+ *
+ * @internal
+ */
+declare class HttpClient {
+    #private;
+    constructor(config: HttpClientConfig);
+    get<T>(path: string, options?: Omit<HttpRequestOptions, 'body' | 'contentType'>): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: Omit<HttpRequestOptions, 'body'>): Promise<T>;
+    patch<T>(path: string, body?: unknown, options?: Omit<HttpRequestOptions, 'body'>): Promise<T>;
+    put<T>(path: string, body?: unknown, options?: Omit<HttpRequestOptions, 'body'>): Promise<T>;
+    delete<T>(path: string, body?: unknown, options?: Omit<HttpRequestOptions, 'body'>): Promise<T>;
+    upload(url: string, body: BodyInit, headers?: HeadersInit): Promise<void>;
+    request<T>(path: string, options?: HttpRequestOptions): Promise<T>;
+    private toEelZapError;
+}
+
+/**
+ * Collection field management endpoints.
+ */
+declare class CollectionFieldsResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Lists all fields in a collection.
+     */
+    list(collectionKey: string): Promise<FieldInfo[]>;
+    /**
+     * Creates a field in a collection.
+     *
+     * Sends an `Idempotency-Key` (required of suite bearers): a fresh one per
+     * call, or `options.idempotencyKey` to make your own retry safe.
+     */
+    create(collectionKey: string, input: CreateFieldInput, options?: IdempotencyOptions): Promise<FieldInfo>;
+    /**
+     * Updates a field in a collection.
+     */
+    update(collectionKey: string, fieldId: string, input: UpdateFieldInput): Promise<FieldInfo>;
+    /**
+     * Deletes a field from a collection.
+     */
+    delete(collectionKey: string, fieldId: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Lists the collection's archived (soft-deleted) fields, most recently
+     * deleted first. Their values are kept, which is what makes `restore` work.
+     *
+     * `GET /collections/{collectionKey}/fields/deleted`. Secret key, or suite
+     * bearer with `zap:content:read`.
+     */
+    listDeleted(collectionKey: string): Promise<FieldInfo[]>;
+    /**
+     * Brings an archived field back with every value it held, at the end of the
+     * root list (outside any section).
+     *
+     * `POST /collections/{collectionKey}/fields/{fieldId}/restore`. Secret key,
+     * or suite bearer with `zap:schema:write` and the Zap ADMIN role.
+     */
+    restore(collectionKey: string, fieldId: string): Promise<FieldInfo>;
+    /**
+     * Reorders collection fields.
+     */
+    reorder(collectionKey: string, fieldIds: string[]): Promise<{
+        success: true;
+    }>;
+}
+
+/**
+ * Collection section management endpoints.
+ */
+declare class CollectionSectionsResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Lists all sections in a collection.
+     */
+    list(collectionKey: string): Promise<SectionInfo[]>;
+    /**
+     * Gets a single section from a collection.
+     */
+    get(collectionKey: string, sectionId: string): Promise<SectionInfo>;
+    /**
+     * Creates a section in a collection.
+     *
+     * Sends an `Idempotency-Key` (required of suite bearers): a fresh one per
+     * call, or `options.idempotencyKey` to make your own retry safe.
+     */
+    create(collectionKey: string, input: CreateSectionInput, options?: IdempotencyOptions): Promise<SectionInfo>;
+    /**
+     * Updates a section in a collection.
+     */
+    update(collectionKey: string, sectionId: string, input: UpdateSectionInput): Promise<SectionInfo>;
+    /**
+     * Deletes a section from a collection.
+     */
+    delete(collectionKey: string, sectionId: string): Promise<{
+        success: true;
+    }>;
+}
+
+/**
+ * Read-only collection endpoints.
+ */
+declare class CollectionsResource {
+    #private;
+    readonly fields: CollectionFieldsResource;
+    readonly sections: CollectionSectionsResource;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient, defaults: ClientDefaults);
+    /**
+     * Lists all collections available to the current API key.
+     */
+    list(options?: {
+        status?: DeliveryStatus;
+    }): Promise<CollectionListResponse>;
+    /**
+     * Retrieves the schema for a single collection.
+     */
+    get(collectionKey: string, options?: {
+        status?: DeliveryStatus;
+    }): Promise<CollectionDetail>;
+    /**
+     * Creates a collection.
+     *
+     * Sends an `Idempotency-Key` (required of suite bearers): a fresh one per
+     * call, or `options.idempotencyKey` to make your own retry safe.
+     */
+    create(input: CreateCollectionInput, options?: IdempotencyOptions): Promise<CollectionDetail>;
+    /**
+     * Updates a collection.
+     */
+    update(collectionKey: string, input: UpdateCollectionInput): Promise<CollectionDetail>;
+    /**
+     * Deletes a collection.
+     */
+    delete(collectionKey: string, options?: DeleteOptions): Promise<{
+        success: true;
+    }>;
+}
+
+/**
+ * «Comentarios»: comment threads on an entry or a document, as the public
+ * API's `/comments` routes take and answer them. A thread flagged
+ * `isChangeRequest` may carry an assignee, proposed values and, once
+ * resolved, a resolution; a plain comment carries none of them.
+ *
+ * The public API speaks KEYS: a record by `collection` + `slug` or by
+ * `document`, a field by its key. Every date is an ISO string.
+ */
+type CommentStatus = 'OPEN' | 'RESOLVED';
+/** How a change request was resolved; APPLIED also covers "changed by hand". */
+type CommentResolution = 'APPLIED' | 'DISMISSED';
+/** Where the thread was made. The API derives it from the credential. */
+type CommentSource = 'EDITOR' | 'PREVIEW' | 'SITE' | 'API' | 'MCP';
+type CommentAnchorKind = 'field' | 'dom' | 'spot';
+/** A page-normalised rectangle: every value between 0 and 1. */
+interface CommentRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface CommentViewport {
+    w: number;
+    h: number;
+}
+/**
+ * An element on a page: tag, then selector, then the W3C text quote, then the
+ * rectangle. `selector` at most 1 KB, `textQuote.exact` at most 500 characters.
+ */
+interface CommentDomAnchor {
+    tag?: string;
+    selector?: string;
+    textQuote?: {
+        exact: string;
+        prefix?: string;
+        suffix?: string;
+    };
+    rect?: CommentRect;
+    viewport?: CommentViewport;
+}
+/** A pin placed on the page, in page-normalised coordinates. */
+interface CommentSpotAnchor {
+    spot: {
+        x: number;
+        y: number;
+    };
+    viewport?: CommentViewport;
+}
+/** A field anchor as the public API takes it: by key. */
+interface CommentFieldAnchorInput {
+    key: string;
+    locale?: string | null;
+    /** A gallery index or a rich-text block, when the field alone is too coarse. */
+    path?: string | null;
+}
+/**
+ * One anchor of a new thread: a field, an element on the page, or both (at
+ * least one); or a spot. `dom` and `spot` anchors need the thread's `pageUrl`.
+ */
+type CommentAnchorInput = {
+    field?: CommentFieldAnchorInput;
+    dom?: CommentDomAnchor;
+} | CommentSpotAnchor;
+/** An anchor as stored: the field layer carries the field's id and real key. */
+type CommentAnchor = {
+    field?: {
+        id: string;
+        key: string;
+        locale: string | null;
+        path: string | null;
+    };
+    dom?: CommentDomAnchor;
+} | CommentSpotAnchor;
+interface CommentPersonRef {
+    id: string;
+    name: string | null;
+    avatarUrl: string | null;
+}
+interface CommentVersionRef {
+    id: string;
+    /** The version's number, or null when it no longer exists (discarded, pruned). */
+    number: number | null;
+    /** Whether the record still sits on this version (its open draft, else its published one). */
+    current: boolean;
+}
+type CommentTarget = {
+    type: 'item';
+    id: string;
+    collectionId: string;
+    slug: string;
+} | {
+    type: 'document';
+    id: string;
+    key: string;
+};
+interface CommentProposedValue {
+    fieldId: string;
+    fieldKey: string;
+    locale: string | null;
+    value: string | number | null;
+}
+/** A thread, without its comments. */
+interface CommentThread {
+    id: string;
+    siteId: string;
+    target: CommentTarget;
+    isChangeRequest: boolean;
+    status: CommentStatus;
+    /** Set on a RESOLVED change request only. */
+    resolution: CommentResolution | null;
+    source: CommentSource;
+    locale: string | null;
+    /** The page it was made on (origin and path), or null when made in the editor. */
+    pageUrl: string | null;
+    anchors: CommentAnchor[];
+    anchorKinds: CommentAnchorKind[];
+    /** The fields the anchors point at, deduplicated, in anchor order. */
+    fieldIds: string[];
+    fieldKeys: string[];
+    proposedValues: CommentProposedValue[] | null;
+    baseVersion: CommentVersionRef | null;
+    resolvedInVersion: CommentVersionRef | null;
+    assignee: CommentPersonRef | null;
+    createdBy: CommentPersonRef | null;
+    resolvedBy: CommentPersonRef | null;
+    resolvedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** The first comment, shortened. */
+    excerpt: string | null;
+    replyCount: number;
+    permissions: {
+        canEdit: boolean;
+        canDelete: boolean;
+    };
+}
+/** One comment of a thread. */
+interface ThreadComment {
+    id: string;
+    author: CommentPersonRef | null;
+    /** Null on a system line. */
+    body: string | null;
+    system: boolean;
+    systemCode: 'draft_discarded' | null;
+    /** The thread's opening comment. */
+    isFirst: boolean;
+    edited: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `get`, `create` and `update`: the thread and every comment, oldest first. */
+interface CommentThreadAnswer {
+    thread: CommentThread;
+    comments: ThreadComment[];
+}
+/** `apply` and `saveToDraft`: the resolved thread and the draft the values went into. */
+interface CommentDraftAnswer extends CommentThreadAnswer {
+    draftVersionId: string;
+}
+/**
+ * `reply`: the new comment and the thread. Under `zap:suggest:write` alone the
+ * thread is only `{ id, status }`, with no comments.
+ */
+type CommentReplyAnswer = {
+    comment: ThreadComment;
+    thread: CommentThread;
+    comments: ThreadComment[];
+} | {
+    comment: ThreadComment;
+    thread: {
+        id: string;
+        status: CommentStatus;
+    };
+    comments?: undefined;
+};
+interface CommentListResponse {
+    items: CommentThread[];
+    /** Across both statuses, whatever `status` filters. */
+    counts: Record<CommentStatus, number>;
+    page: number;
+    pageSize: number;
+    total: number;
+    hasMore: boolean;
+}
+/** A record: an entry (`collection` + `slug`) or a document (`document`). */
+type CommentRecord = {
+    collection: string;
+    slug: string;
+    document?: never;
+} | {
+    document: string;
+    collection?: never;
+    slug?: never;
+};
+interface CommentListOptions {
+    /** With `slug`: the threads of one entry. */
+    collection?: string;
+    slug?: string;
+    /** The threads of one document. */
+    document?: string;
+    isChangeRequest?: boolean;
+    status?: CommentStatus;
+    resolution?: CommentResolution;
+    /** The page the threads were made on; normalised before it is compared. */
+    pageUrl?: string;
+    /** `me`, `none`, or a user id. */
+    assignee?: 'me' | 'none' | (string & {});
+    page?: number;
+    /** 1 to 100, default 50. */
+    pageSize?: number;
+}
+interface CommentProposedValueInput {
+    fieldKey: string;
+    locale?: string | null;
+    value: string | number | null;
+}
+interface CommentWriteBase {
+    locale?: string | null;
+    /** An http(s) URL; needed by `dom` and `spot` anchors. */
+    pageUrl?: string;
+    /** 0 to 20; none means the whole page (with a `pageUrl`) or the whole record. */
+    anchors?: CommentAnchorInput[];
+    /** The first comment, 1 to 10,000 characters. */
+    body: string;
+}
+/**
+ * `create`. `assigneeId` and `proposedValues` go with a change request only.
+ * Without `assigneeId`, a change request goes to the record's Responsable when
+ * they hold Zap; `null` assigns nobody.
+ */
+type CreateCommentInput = CommentRecord & CommentWriteBase & {
+    isChangeRequest?: boolean;
+    assigneeId?: string | null;
+    /** At most 20; TEXT, LONG_TEXT, NUMBER and URL fields. */
+    proposedValues?: CommentProposedValueInput[];
+};
+/** `saveToDraft`: always a change request, no assignee, at least one proposed value. */
+type SaveCommentToDraftInput = CommentRecord & CommentWriteBase & {
+    proposedValues: CommentProposedValueInput[];
+};
+/** `update`: at least one. */
+interface UpdateCommentInput {
+    status?: CommentStatus;
+    /** A change request's; given with `status: 'OPEN'` it is 409 `INVALID_TRANSITION`. */
+    resolution?: CommentResolution;
+    /**
+     * Turning it off is 409 `HAS_PROPOSAL` on a thread with proposed values, and
+     * 422 `HAS_LINKED_TASKS` while any Swarm task is linked to it.
+     */
+    isChangeRequest?: boolean;
+    assigneeId?: string | null;
+    /** The first comment's text (its author or an ADMIN). */
+    body?: string;
+}
+interface ReplyCommentInput {
+    body: string;
+}
+/** The field types `onPage` describes, per record ref and field key. */
+interface OnPageField {
+    type: string;
+    label: string;
+}
+interface OnPageCommentAnchor {
+    fieldKey: string | null;
+    tag: string | null;
+    selector: string | null;
+    rect: CommentRect | null;
+    spot: {
+        x: number;
+        y: number;
+    } | null;
+}
+interface OnPageComment {
+    id: string;
+    status: 'OPEN';
+    isChangeRequest: boolean;
+    createdAt: string;
+    author: {
+        name: string | null;
+    } | null;
+    excerpt: string | null;
+    anchors: OnPageCommentAnchor[];
+}
+/** `onPage`: what the site's suggestion client needs on one page. */
+interface OnPageComments {
+    viewer: {
+        name: string | null;
+    };
+    /** Whether the site lets people save straight to the draft. */
+    liveEditing: boolean;
+    /** Record ref → field key → field. */
+    fields: Record<string, Record<string, OnPageField>>;
+    /** The page's open threads. */
+    comments: OnPageComment[];
+    truncated: boolean;
+}
+
+/**
+ * «Comentarios» (`/comments`): comment threads on an entry or a document, a
+ * thread flagged `isChangeRequest` carrying an assignee and proposed values.
+ *
+ * Suite bearers only (`eel_sk_…` / `eel_at_…`, with `X-Eel-Site`): a comment
+ * has a person behind it, so site keys are refused. Reads need
+ * `zap:content:read`; writes `zap:content:write`, and `create`, `reply` and
+ * `saveToDraft` also take `zap:suggest:write`.
+ */
+declare class CommentsResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Lists the site's threads, newest first, optionally on one record (an
+     * entry by `collection` + `slug`, or a `document`). `counts` covers both
+     * statuses whatever `status` filters.
+     *
+     * `GET /comments`.
+     */
+    list(options?: CommentListOptions): Promise<CommentListResponse>;
+    /**
+     * Retrieves a thread and its comments, oldest first.
+     *
+     * `GET /comments/{id}`.
+     */
+    get(id: string): Promise<CommentThreadAnswer>;
+    /**
+     * Opens a thread with its first comment. Anchors and proposed values name
+     * fields by key. Sends an `Idempotency-Key`. 404 for an unknown record, 422
+     * `INVALID_ANCHOR` / `INVALID_PROPOSED_VALUE` / `ASSIGNEE_NO_SEAT`, 429
+     * `RATE_LIMITED`.
+     *
+     * `POST /comments`.
+     *
+     * @example
+     * ```ts
+     * await zap.comments.create({
+     *   collection: 'blog',
+     *   slug: 'hello-world',
+     *   isChangeRequest: true,
+     *   body: 'Shorter title?',
+     *   proposedValues: [{ fieldKey: 'title', value: 'Hello' }],
+     * })
+     * ```
+     */
+    create(input: CreateCommentInput, options?: IdempotencyOptions): Promise<CommentThreadAnswer>;
+    /**
+     * Changes a thread: `status` (resolve, reopen), a change request's
+     * `resolution`, the `isChangeRequest` flag, the assignee, or the first
+     * comment's text. 409 `STATUS_CONFLICT`, `INVALID_TRANSITION`,
+     * `HAS_PROPOSAL`; 422 `NOT_A_CHANGE_REQUEST`, `HAS_LINKED_TASKS` (turning
+     * the flag off while a Swarm task is linked).
+     *
+     * `PATCH /comments/{id}`.
+     */
+    update(id: string, input: UpdateCommentInput): Promise<CommentThreadAnswer>;
+    /**
+     * Replies on a thread. Sends an `Idempotency-Key`.
+     *
+     * `POST /comments/{id}/replies`.
+     */
+    reply(id: string, input: ReplyCommentInput, options?: IdempotencyOptions): Promise<CommentReplyAnswer>;
+    /**
+     * «Aplicar al borrador»: writes an open change request's proposed values
+     * into the record's draft and resolves it as APPLIED. 409 `NO_PROPOSAL` /
+     * `NOT_OPEN`.
+     *
+     * `POST /comments/{id}/apply`.
+     */
+    apply(id: string): Promise<CommentDraftAnswer>;
+    /**
+     * Writes proposed values straight into the record's draft, recorded as a
+     * change request already resolved as APPLIED; nobody is notified. 403 when
+     * the site has live editing off. Sends an `Idempotency-Key`.
+     *
+     * `POST /comments/save-to-draft`.
+     */
+    saveToDraft(input: SaveCommentToDraftInput, options?: IdempotencyOptions): Promise<CommentDraftAnswer>;
+    /**
+     * What the site's suggestion client shows on one page: the viewer, whether
+     * live editing is on, the field types of the records tagged there and the
+     * page's open threads. `refs` are `data-zap-ref` values (`collection/slug`
+     * or `doc:key`); at most 20 are read.
+     *
+     * `GET /comments/on-page`. Answers only the site's own suggestion client.
+     */
+    onPage(url: string, refs?: readonly string[]): Promise<OnPageComments>;
+}
+
+/**
+ * Content versioning: the shapes the `…/versions` routes of the public API
+ * answer with. Field names are the API's (camelCase), and every date is an ISO
+ * string.
+ */
+type VersionStatus = 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+/**
+ * One row of an entry's history. What `list`, `createDraft`, `publishDraft`
+ * and `rollback` answer with: no values.
+ */
+interface VersionSummary {
+    id: string;
+    number: number;
+    status: VersionStatus;
+    /** The account that made the version, or null for an API key or a deleted account. */
+    createdById: string | null;
+    /** The author's display name, or null when the account is gone. */
+    authorName: string | null;
+    authorAvatarUrl: string | null;
+    note: string | null;
+    /** Set when the version was produced by a rollback from that version number. */
+    restoredFromVersionNumber: number | null;
+    createdAt: string;
+    publishedAt: string | null;
+}
+interface ItemVersionSummary extends VersionSummary {
+    itemId: string;
+    /** The item's default-locale slug as of this version. */
+    slug: string | null;
+}
+interface DocumentVersionSummary extends VersionSummary {
+    documentId: string;
+}
+interface VersionGalleryItem {
+    id: string;
+    mediaId: string;
+    position: number;
+    caption: string | null;
+    description: string | null;
+}
+/**
+ * A stored value in a version snapshot. It is the raw column form, not the
+ * delivery API's resolved value: one `value*` column is set according to
+ * `fieldType`. `fieldKey` and `fieldType` are copies, so a version still reads
+ * correctly after the field it came from was deleted.
+ */
+interface VersionValue {
+    id: string;
+    fieldKey: string | null;
+    fieldType: string | null;
+    locale: string | null;
+    valueText: string | null;
+    valueNumber: number | null;
+    valueInt: number | null;
+    valueBool: boolean | null;
+    valueDate: string | null;
+    valueDateTime: string | null;
+    valueAmountMinor: number | null;
+    valueCurrency: string | null;
+    valueEnumOptionId: string | null;
+    valueMediaId: string | null;
+    /** Present only on GALLERY values. */
+    galleryItems?: VersionGalleryItem[];
+}
+interface ItemVersionValue extends VersionValue {
+    itemVersionId: string;
+    fieldId: string | null;
+}
+interface DocumentVersionValue extends VersionValue {
+    documentVersionId: string;
+    documentFieldId: string | null;
+}
+/** SEO as stored in a version snapshot, one row per locale. */
+interface VersionSeo {
+    id: string;
+    locale: string | null;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    ogType: string | null;
+    ogImageId: string | null;
+    ogImageAlt: string | null;
+    canonicalUrl: string | null;
+    twitterCard: string;
+    noIndex: boolean;
+    noFollow: boolean;
+    keywords: string | null;
+    structuredData: Record<string, unknown> | null;
+}
+interface ItemVersionSeo extends VersionSeo {
+    itemVersionId: string;
+}
+interface DocumentVersionSeo extends VersionSeo {
+    documentVersionId: string;
+}
+interface ItemVersionSlug {
+    id: string;
+    itemVersionId: string;
+    locale: string;
+    slug: string;
+}
+/**
+ * One version with its snapshot. What `get` and `updateDraft` answer with.
+ */
+interface VersionDetail extends VersionSummary {
+    values: VersionValue[];
+    seo: VersionSeo[];
+}
+interface ItemVersionDetail extends ItemVersionSummary {
+    values: ItemVersionValue[];
+    seo: ItemVersionSeo[];
+    slugs: ItemVersionSlug[];
+}
+interface DocumentVersionDetail extends DocumentVersionSummary {
+    values: DocumentVersionValue[];
+    seo: DocumentVersionSeo[];
+}
+interface VersionListResponse<TVersion extends VersionSummary = VersionSummary> {
+    /** Newest first. */
+    versions: TVersion[];
+}
+interface CreateDraftInput {
+    /** Up to 200 characters. */
+    note?: string;
+}
+interface UpdateItemDraftInput {
+    slug?: string;
+    locale?: string;
+    values?: Record<string, unknown>;
+}
+interface UpdateDocumentDraftInput {
+    locale?: string;
+    values?: Record<string, unknown>;
+}
+
+/**
+ * Version history, drafts and rollbacks for documents
+ * (`/documents/{documentKey}/versions…`).
+ *
+ * A document has at most one open draft. Writing needs a secret key;
+ * publishing and rolling back need one with publish rights.
+ */
+declare class DocumentVersionsResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Lists a document's versions, newest first.
+     */
+    list(documentKey: string): Promise<VersionListResponse<DocumentVersionSummary>>;
+    /**
+     * Gets one version with its snapshot (values and SEO).
+     */
+    get(documentKey: string, versionId: string): Promise<DocumentVersionDetail>;
+    /**
+     * Opens a draft from the document's live state. Fails with `DUPLICATE_KEY`
+     * (409) when the document already has one.
+     */
+    createDraft(documentKey: string, input?: CreateDraftInput): Promise<DocumentVersionSummary>;
+    /**
+     * Stages values on the open draft without touching the live document.
+     * Fails with `VALIDATION_ERROR` (400) when there is no open draft.
+     */
+    updateDraft(documentKey: string, input: UpdateDocumentDraftInput): Promise<DocumentVersionDetail>;
+    /**
+     * Discards the open draft. Fails with `NOT_FOUND` (404) when there is none.
+     */
+    discardDraft(documentKey: string): Promise<void>;
+    /**
+     * Publishes the open draft: its values go live and it becomes the
+     * document's published version. Fails with `NOT_FOUND` (404) when there is
+     * no draft.
+     */
+    publishDraft(documentKey: string): Promise<DocumentVersionSummary>;
+    /**
+     * Restores a past version over the live document and records the restore
+     * as a NEW published version (history is never rewritten). Refused (409)
+     * for a draft version, or while the document has an open draft.
+     */
+    rollback(documentKey: string, versionId: string): Promise<DocumentVersionSummary>;
+}
+
+/**
+ * Document list entry returned by the list endpoint.
+ */
+interface DocumentListEntry {
+    key: string;
+    name: string;
+    description: string | null;
+    status: string;
+    updatedAt: string;
+    publishedAt: string | null;
+    fields: FieldInfo[];
+    sections: SectionInfo[];
+}
+/**
+ * Document detail payload.
+ */
+interface DocumentDetail<TContent = Record<string, unknown>> {
+    key: string;
+    name: string;
+    status: string;
+    locale: string;
+    meta: DocumentMeta;
+    content: TContent;
+    seo: Seo | null;
+}
+/**
+ * Response shape for document lists.
+ */
+interface DocumentListResponse {
+    data: DocumentListEntry[];
+}
+/**
+ * Options for listing documents.
+ */
+type DocumentListOptions = Omit<CommonRequestOptions, 'fields'> & PreviewOption;
+/**
+ * Options for retrieving a single document.
+ */
+type DocumentGetOptions = CommonRequestOptions & PreviewOption;
+/**
+ * Input for creating a document.
+ */
+interface CreateDocumentInput {
+    name: string;
+    key: string;
+    description?: string;
+}
+/**
+ * Input for updating a document.
+ */
+interface UpdateDocumentInput {
+    name?: string;
+    key?: string;
+    description?: string | null;
+    /**
+     * «Ruta en tu sitio»: the page this document is — `/nosotros`,
+     * `/{locale}/nosotros`. `''` or `null` clears it. Starts with `/`; only
+     * `{locale}`.
+     */
+    previewPath?: string | null;
+}
+/**
+ * Response payload for document mutation routes.
+ */
+interface DocumentMutationResponse<TContent = Record<string, unknown>> {
+    document: DocumentDetail<TContent>;
+}
+/**
+ * Response payload for document delete routes.
+ */
+interface DocumentDeleteResponse {
+    success: true;
+}
+/**
+ * Extra options for document deletion.
+ */
+type DeleteDocumentOptions = DeleteOptions;
+/**
+ * Document field inputs mirror collection field inputs.
+ */
+type CreateDocumentFieldInput = CreateFieldInput;
+/**
+ * Document field update inputs mirror collection field inputs.
+ */
+type UpdateDocumentFieldInput = UpdateFieldInput;
+/**
+ * Response payload for document field list operations.
+ */
+type DocumentFieldListResponse = CollectionFieldListResponse;
+/**
+ * Response payload for document section list operations.
+ */
+type DocumentSectionListResponse = CollectionSectionListResponse;
+/**
+ * Response payload for document values routes.
+ */
+interface DocumentValuesResponse {
+    values: Record<string, unknown>;
+}
+/**
+ * SEO payload for document management routes.
+ */
+type DocumentSeo = Seo | SeoInput | Record<string, unknown> | null;
+/**
+ * Response payload for document SEO routes.
+ */
+interface DocumentSeoResponse {
+    seo: DocumentSeo;
+}
+
+/**
+ * Document field management endpoints.
+ */
+declare class DocumentFieldsResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Lists all fields in a document.
+     */
+    list(documentKey: string): Promise<FieldInfo[]>;
+    /**
+     * Gets a single field in a document.
+     */
+    get(documentKey: string, fieldId: string): Promise<FieldInfo>;
+    /**
+     * Creates a field in a document.
+     *
+     * Sends an `Idempotency-Key` (required of suite bearers): a fresh one per
+     * call, or `options.idempotencyKey` to make your own retry safe.
+     */
+    create(documentKey: string, input: CreateDocumentFieldInput, options?: IdempotencyOptions): Promise<FieldInfo>;
+    /**
+     * Updates a field in a document.
+     */
+    update(documentKey: string, fieldId: string, input: UpdateDocumentFieldInput): Promise<FieldInfo>;
+    /**
+     * Deletes a field from a document.
+     */
+    delete(documentKey: string, fieldId: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Lists the document's archived (soft-deleted) fields, most recently
+     * deleted first. Their values are kept, which is what makes `restore` work.
+     *
+     * `GET /documents/{documentKey}/fields/deleted`. Secret key, or suite bearer
+     * with `zap:content:read`.
+     */
+    listDeleted(documentKey: string): Promise<FieldInfo[]>;
+    /**
+     * Brings an archived field back with every value it held, at the end of the
+     * root list (outside any section).
+     *
+     * `POST /documents/{documentKey}/fields/{fieldId}/restore`. Secret key, or
+     * suite bearer with `zap:schema:write` and the Zap ADMIN role.
+     */
+    restore(documentKey: string, fieldId: string): Promise<FieldInfo>;
+    /**
+     * Reorders document fields.
+     */
+    reorder(documentKey: string, fieldIds: string[]): Promise<{
+        success: true;
+    }>;
+}
+
+/**
+ * Document section management endpoints.
+ */
+declare class DocumentSectionsResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Lists all sections in a document.
+     */
+    list(documentKey: string): Promise<SectionInfo[]>;
+    /**
+     * Gets a single section from a document.
+     */
+    get(documentKey: string, sectionId: string): Promise<SectionInfo>;
+    /**
+     * Creates a section in a document.
+     *
+     * Sends an `Idempotency-Key` (required of suite bearers): a fresh one per
+     * call, or `options.idempotencyKey` to make your own retry safe.
+     */
+    create(documentKey: string, input: CreateSectionInput, options?: IdempotencyOptions): Promise<SectionInfo>;
+    /**
+     * Updates a section in a document.
+     */
+    update(documentKey: string, sectionId: string, input: UpdateSectionInput): Promise<SectionInfo>;
+    /**
+     * Deletes a section from a document.
+     */
+    delete(documentKey: string, sectionId: string): Promise<{
+        success: true;
+    }>;
+}
+
+/**
+ * Document SEO management endpoints.
+ */
+declare class DocumentSeoResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Gets SEO metadata for a document.
+     */
+    get(documentKey: string, options?: {
+        locale?: string;
+    }): Promise<DocumentSeo>;
+    /**
+     * Updates SEO metadata for a document.
+     */
+    update(documentKey: string, input: SeoInput): Promise<DocumentSeo>;
+}
+
+/**
+ * Document value management endpoints.
+ */
+declare class DocumentValuesResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Gets all document values.
+     */
+    get(documentKey: string): Promise<Record<string, unknown>>;
+    /**
+     * Updates document values by field key.
+     */
+    update(documentKey: string, values: Record<string, unknown>, options?: {
+        locale?: string;
+    }): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Read-only document endpoints.
+ */
+declare class DocumentsResource {
+    #private;
+    readonly fields: DocumentFieldsResource;
+    readonly sections: DocumentSectionsResource;
+    readonly values: DocumentValuesResource;
+    readonly seo: DocumentSeoResource;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient, defaults: ClientDefaults);
+    /**
+     * Lists all documents available to the current API key.
+     */
+    list(options?: DocumentListOptions): Promise<DocumentListResponse>;
+    /**
+     * Retrieves a single document by key.
+     */
+    get<TContent = Record<string, unknown>>(documentKey: string, options?: DocumentGetOptions): Promise<DocumentDetail<TContent>>;
+    /**
+     * Creates a document.
+     *
+     * Sends an `Idempotency-Key` (required of suite bearers): a fresh one per
+     * call, or `options.idempotencyKey` to make your own retry safe.
+     */
+    create<TContent = Record<string, unknown>>(input: CreateDocumentInput, options?: IdempotencyOptions): Promise<DocumentDetail<TContent>>;
+    /**
+     * Updates a document.
+     */
+    update<TContent = Record<string, unknown>>(documentKey: string, input: UpdateDocumentInput): Promise<DocumentDetail<TContent>>;
+    /**
+     * Deletes a document.
+     */
+    delete(documentKey: string, options?: DeleteDocumentOptions): Promise<{
+        success: true;
+    }>;
+    /**
+     * Publishes a document.
+     */
+    publish<TContent = Record<string, unknown>>(documentKey: string): Promise<DocumentDetail<TContent>>;
+    /**
+     * Unpublishes a document.
+     */
+    unpublish<TContent = Record<string, unknown>>(documentKey: string): Promise<DocumentDetail<TContent>>;
+}
+
+/**
+ * Version history, drafts and rollbacks for collection items
+ * (`/collections/{collectionKey}/items/{slug}/versions…`).
+ *
+ * An item has at most one open draft. Writing needs a secret key; publishing
+ * and rolling back need one with publish rights.
+ */
+declare class ItemVersionsResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Lists an item's versions, newest first.
+     */
+    list(collectionKey: string, slug: string): Promise<VersionListResponse<ItemVersionSummary>>;
+    /**
+     * Gets one version with its snapshot (values, SEO and slugs).
+     */
+    get(collectionKey: string, slug: string, versionId: string): Promise<ItemVersionDetail>;
+    /**
+     * Opens a draft from the item's live state. Fails with `DUPLICATE_KEY` (409)
+     * when the item already has one.
+     */
+    createDraft(collectionKey: string, slug: string, input?: CreateDraftInput): Promise<ItemVersionSummary>;
+    /**
+     * Stages values (and optionally a new slug) on the open draft without
+     * touching the live item. Fails with `VALIDATION_ERROR` (400) when there is
+     * no open draft.
+     */
+    updateDraft(collectionKey: string, slug: string, input: UpdateItemDraftInput): Promise<ItemVersionDetail>;
+    /**
+     * Discards the open draft. Fails with `NOT_FOUND` (404) when there is none.
+     */
+    discardDraft(collectionKey: string, slug: string): Promise<void>;
+    /**
+     * Publishes the open draft: its values go live and it becomes the item's
+     * published version. Fails with `NOT_FOUND` (404) when there is no draft.
+     */
+    publishDraft(collectionKey: string, slug: string): Promise<ItemVersionSummary>;
+    /**
+     * Restores a past version over the live item and records the restore as a
+     * NEW published version (history is never rewritten). Refused (409) for a
+     * draft version, or while the item has an open draft.
+     */
+    rollback(collectionKey: string, slug: string, versionId: string): Promise<ItemVersionSummary>;
+}
+
+/**
+ * Operators supported by item filters.
+ */
+interface FilterOperatorMap {
+    eq?: QueryPrimitive;
+    ne?: QueryPrimitive;
+    gt?: QueryPrimitive;
+    gte?: QueryPrimitive;
+    lt?: QueryPrimitive;
+    lte?: QueryPrimitive;
+    in?: QueryPrimitive[] | string;
+    contains?: string;
+}
+/**
+ * Single filter value accepted by the SDK.
+ */
+type FilterValue = QueryPrimitive | FilterOperatorMap;
+/**
+ * Item list filter object keyed by field name.
+ */
+type ItemFilters = Record<string, FilterValue>;
+/**
+ * Options for the item list endpoint.
+ */
+interface ItemListOptions extends CommonRequestOptions, PreviewOption {
+    page?: number;
+    pageSize?: number;
+    sort?: string;
+    filter?: ItemFilters;
+}
+/**
+ * Options for the item detail endpoint.
+ */
+type ItemGetOptions = CommonRequestOptions & PreviewOption;
+/**
+ * Single item payload.
+ */
+interface ItemDetail<TContent = Record<string, unknown>> {
+    slug: string;
+    status: string;
+    locale: string;
+    localizedSlugs: Record<string, string>;
+    meta: ItemMeta;
+    content: TContent;
+    seo: Seo | null;
+    collection: {
+        key: string;
+        name: string;
+    };
+}
+/**
+ * Item list response payload.
+ */
+interface ItemListResponse<TContent = Record<string, unknown>> {
+    data: ItemDetail<TContent>[];
+    pagination: Pagination;
+    collection: CollectionSummary;
+}
+/**
+ * Input for creating a collection item.
+ */
+interface CreateItemInput {
+    slug: string;
+    locale?: string;
+    values: Record<string, unknown>;
+}
+/**
+ * Input for updating a collection item.
+ */
+interface UpdateItemInput {
+    slug?: string;
+    locale?: string;
+    values?: Record<string, unknown>;
+}
+/**
+ * Response payload for item mutation routes.
+ */
+interface ItemMutationResponse<TContent = Record<string, unknown>> {
+    item: ItemDetail<TContent>;
+}
+/**
+ * Response payload for item delete routes.
+ */
+interface ItemDeleteResponse {
+    success: true;
+}
+/**
+ * Extra options for item deletion.
+ */
+type DeleteItemOptions = DeleteOptions;
+/**
+ * SEO payload for item management routes.
+ */
+type ItemSeo = Seo | SeoInput | Record<string, unknown> | null;
+/**
+ * Response payload for item SEO routes.
+ */
+interface ItemSeoResponse {
+    seo: ItemSeo;
+}
+
+/**
+ * Lazy fluent query builder for item list requests.
+ */
+declare class ItemQueryBuilder {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient, defaults: ClientDefaults, collectionKey: string, options?: ItemListOptions);
+    /**
+     * Overrides the request locale.
+     */
+    locale(locale: string): ItemQueryBuilder;
+    /**
+     * Overrides the delivery status filter.
+     */
+    status(status: NonNullable<ItemListOptions['status']>): ItemQueryBuilder;
+    /**
+     * Adds or replaces a field filter.
+     */
+    filter(field: string, value: FilterValue): ItemQueryBuilder;
+    /**
+     * Sets the sort expression.
+     */
+    sort(sort: string): ItemQueryBuilder;
+    /**
+     * Selects a sparse set of content fields.
+     */
+    fields(fields: string[]): ItemQueryBuilder;
+    /**
+     * Sets the current page.
+     */
+    page(page: number): ItemQueryBuilder;
+    /**
+     * Sets the page size.
+     */
+    pageSize(pageSize: number): ItemQueryBuilder;
+    /**
+     * Executes the built request.
+     */
+    get<TContent = Record<string, unknown>>(): Promise<ItemListResponse<TContent>>;
+    /**
+     * Returns the current request options as a plain object.
+     */
+    toJSON(): ItemListOptions;
+    private clone;
+}
+
+/**
+ * Item SEO management endpoints.
+ */
+declare class ItemSeoResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Gets SEO metadata for an item.
+     */
+    get(collectionKey: string, slug: string, options?: {
+        locale?: string;
+    }): Promise<ItemSeo>;
+    /**
+     * Updates SEO metadata for an item.
+     */
+    update(collectionKey: string, slug: string, input: SeoInput): Promise<ItemSeo>;
+}
+
+/**
+ * Read-only collection item endpoints.
+ */
+declare class ItemsResource {
+    #private;
+    readonly seo: ItemSeoResource;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient, defaults: ClientDefaults);
+    /**
+     * Lists items in a collection.
+     */
+    list<TContent = Record<string, unknown>>(collectionKey: string, options?: ItemListOptions): Promise<ItemListResponse<TContent>>;
+    /**
+     * Retrieves a single item by slug.
+     */
+    get<TContent = Record<string, unknown>>(collectionKey: string, slug: string, options?: ItemGetOptions): Promise<ItemDetail<TContent>>;
+    /**
+     * Starts a lazy fluent query builder for a collection.
+     */
+    collection(collectionKey: string): ItemQueryBuilder;
+    /**
+     * Creates an item in a collection.
+     *
+     * Sends an `Idempotency-Key` (required of suite bearers): a fresh one per
+     * call, or `options.idempotencyKey` to make your own retry safe.
+     */
+    create<TContent = Record<string, unknown>>(collectionKey: string, input: CreateItemInput, options?: IdempotencyOptions): Promise<ItemDetail<TContent>>;
+    /**
+     * Updates an item by slug.
+     */
+    update<TContent = Record<string, unknown>>(collectionKey: string, slug: string, input: UpdateItemInput): Promise<ItemDetail<TContent>>;
+    /**
+     * Deletes an item by slug.
+     */
+    delete(collectionKey: string, slug: string, options?: DeleteItemOptions): Promise<{
+        success: true;
+    }>;
+    /**
+     * Publishes an item by slug.
+     */
+    publish<TContent = Record<string, unknown>>(collectionKey: string, slug: string): Promise<ItemDetail<TContent>>;
+    /**
+     * Unpublishes an item by slug.
+     */
+    unpublish<TContent = Record<string, unknown>>(collectionKey: string, slug: string): Promise<ItemDetail<TContent>>;
+}
+
+/**
+ * Media types supported by the public management API.
+ */
+type MediaType = 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' | 'OTHER' | (string & {});
+/**
+ * Sort expressions supported by the media list route.
+ */
+type MediaSort = 'createdAt:desc' | 'createdAt:asc' | 'filename:asc' | 'filename:desc' | 'size:desc' | 'size:asc';
+/**
+ * Usage filter supported by the media list route.
+ */
+type MediaUsage = 'all' | 'linked' | 'unlinked';
+/**
+ * Media list params accepted by the public API.
+ */
+interface MediaListParams {
+    search?: string;
+    page?: number;
+    pageSize?: number;
+    sort?: MediaSort;
+    type?: MediaType;
+    status?: Uppercase<DeliveryStatus> | DeliveryStatus;
+    usage?: MediaUsage;
+}
+/**
+ * Media payload returned by management routes.
+ */
+interface MediaDetail {
+    id: string;
+    filename?: string;
+    type: MediaType;
+    mimeType?: string;
+    contentType?: string;
+    size?: number;
+    width: number | null;
+    height: number | null;
+    alt?: string | null;
+    title?: string | null;
+    description?: string | null;
+    url: string | null;
+    status: string;
+    mediaAccess?: string;
+    signedUrl?: string | null;
+    signedUrlExpiresAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Response payload for media list routes.
+ */
+interface MediaListResponse {
+    items: MediaDetail[];
+    page: number;
+    pageSize: number;
+    total?: number;
+    pageCount?: number;
+    pagination?: Pagination;
+}
+/**
+ * Response payload for a single media detail route.
+ */
+type MediaDetailResponse = MediaDetail;
+/**
+ * Input for updating media metadata.
+ */
+interface UpdateMediaInput {
+    alt?: string | null;
+    title?: string | null;
+    description?: string | null;
+}
+/**
+ * Input for `POST /media/from-url`: Zap downloads the file server-side.
+ */
+interface MediaFromUrlInput {
+    /** An absolute http(s) URL on port 80 or 443, at most 2048 characters. */
+    url: string;
+    /** Defaults to the URL's last path segment. At most 255 characters. */
+    filename?: string;
+    /** `''` or `null` mean none; at most 2000 characters. */
+    title?: string | null;
+    alt?: string | null;
+}
+/**
+ * Input for requesting a presigned upload URL.
+ */
+interface CreateUploadUrlInput {
+    filename: string;
+    contentType: string;
+    size: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * Response payload for the upload URL route.
+ */
+interface UploadUrlResponse {
+    uploadUrl: string;
+    mediaId: string;
+    key: string;
+}
+/**
+ * Input for confirming an upload.
+ */
+interface ConfirmUploadInput {
+    mediaId: string;
+    key: string;
+    filename: string;
+    contentType: string;
+    size: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * Accepted binary sources for high-level uploads.
+ */
+type UploadFile = ArrayBuffer | ArrayBufferView | Blob;
+/**
+ * High-level media upload input.
+ */
+interface MediaUploadInput {
+    file: UploadFile;
+    filename: string;
+    contentType: string;
+    width?: number;
+    height?: number;
+    alt?: string | null;
+    title?: string | null;
+    description?: string | null;
+}
+
+/**
+ * Media management endpoints.
+ */
+declare class MediaResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Lists media for the current site.
+     */
+    list(params?: MediaListParams): Promise<MediaListResponse>;
+    /**
+     * Gets a single media item.
+     */
+    get(id: string): Promise<MediaDetail>;
+    /**
+     * Updates media metadata.
+     */
+    update(id: string, input: UpdateMediaInput): Promise<MediaDetail>;
+    /**
+     * Deletes media.
+     */
+    delete(id: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Publishes media.
+     */
+    publish(id: string): Promise<MediaDetail>;
+    /**
+     * Unpublishes media.
+     */
+    unpublish(id: string): Promise<MediaDetail>;
+    /**
+     * Requests a presigned upload URL.
+     */
+    createUploadUrl(input: CreateUploadUrlInput): Promise<UploadUrlResponse>;
+    /**
+     * Confirms a completed upload.
+     */
+    confirmUpload(input: ConfirmUploadInput): Promise<MediaDetail>;
+    /**
+     * Fetches a file from a URL into the media library, server-side (SSRF
+     * guarded, type allowlist, size ceiling). The file starts private (`DRAFT`):
+     * the answer carries a 15-minute `signedUrl` and no `url` until `publish`.
+     *
+     * `POST /media/from-url`. Secret key, or suite bearer with
+     * `zap:media:write`. Sends an `Idempotency-Key` (required of suite bearers;
+     * a retry with the same key replays the first answer without downloading
+     * again). Server-side only: the API's general CORS does not allow that
+     * header from a browser.
+     */
+    fromUrl(input: MediaFromUrlInput, options?: IdempotencyOptions): Promise<MediaDetail>;
+    /**
+     * Uploads media using the public presigned URL flow.
+     */
+    upload(input: MediaUploadInput): Promise<MediaDetail>;
+}
+
+/**
+ * Preview tokens (`zpt_…`, zap-cms-v2 §3.5): ten minutes, one site, read-only.
+ */
+declare class PreviewTokensResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Checks that the client's preview token is live AND was minted for the
+     * site `siteApiKey` belongs to, before trusting it (what a draft-mode route
+     * does before turning draft mode on). Rejects with `EelZapError` 401 for an
+     * unknown, revoked or expired token, 403 `WRONG_SITE` for another site's.
+     *
+     * `GET /preview/token`. The client's `apiKey` must be the `zpt_` token
+     * itself (any other bearer is 403); `siteApiKey` is one of the site's own
+     * API keys (public or secret), sent as `X-Zap-Site-Api-Key`.
+     *
+     * @example
+     * ```ts
+     * const zap = createClient({ apiKey: token })
+     * const { site, expiresAt } = await zap.previewTokens.validate(process.env.ZAP_PUBLIC_KEY!)
+     * ```
+     */
+    validate(siteApiKey: string): Promise<PreviewTokenValidation>;
+}
+
+/**
+ * The site the API key belongs to: read it, and set where it lives.
+ */
+declare class SiteResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Resolves the current site from the authenticated API key.
+     */
+    get(): Promise<SiteInfo>;
+    /**
+     * Sets the site's URL and «Otros dominios» (`PATCH /site`), under the same
+     * rules as the site's settings page, and resolves to the updated site.
+     * Server code only: it needs a `secret_` key or an ADMIN suite credential.
+     */
+    update(input: UpdateSiteInput): Promise<SiteInfo>;
+}
+
+/**
+ * The credential's workspace's sites.
+ */
+declare class SitesResource {
+    #private;
+    /**
+     * @internal
+     */
+    constructor(http: HttpClient);
+    /**
+     * Lists the workspace's sites, newest first. Each one's `key` or `id` is a
+     * valid `X-Eel-Site` for every other call; this is how a suite client
+     * learns which sites it can address.
+     *
+     * `GET /sites`. Suite bearer only (`eel_sk_` / `eel_at_`), `zap:sites:read`;
+     * needs no `X-Eel-Site`. Site keys are refused: a site key is one site.
+     */
+    list(): Promise<SiteListEntry[]>;
+}
+
+interface ClientConfig {
+    /**
+     * The bearer: a site API key (`secret_…` / `public_…`), or a preview token
+     * (`zpt_…`) from a draft-mode URL — which turns `preview` on by default.
+     */
+    apiKey: string;
+    baseUrl?: string;
+    pathPrefix?: string;
+    locale?: string;
+    status?: DeliveryStatus;
+    /** Default for the item and document reads' `preview` option. */
+    preview?: boolean;
+    fetch?: typeof globalThis.fetch;
+    defaultHeaders?: HeadersInit;
+    /** Per attempt, in ms. Default `30000`. */
+    timeout?: number;
+    /**
+     * Retries of a `429`, and of a `503` with `Retry-After`, honouring
+     * `Retry-After` with exponential backoff and jitter. On by default for reads
+     * and for writes that carry an `Idempotency-Key`; other writes are never
+     * retried. `false` turns it off.
+     */
+    retry?: boolean | RetryOptions;
+}
+/**
+ * Main SDK client for the EelZap Content Delivery API.
+ */
+declare class EelZapClient {
+    #private;
+    readonly site: SiteResource;
+    readonly sites: SitesResource;
+    readonly collections: CollectionsResource;
+    readonly items: ItemsResource;
+    readonly documents: DocumentsResource;
+    readonly media: MediaResource;
+    readonly itemVersions: ItemVersionsResource;
+    readonly documentVersions: DocumentVersionsResource;
+    readonly previewTokens: PreviewTokensResource;
+    readonly comments: CommentsResource;
+    constructor(config: ClientConfig);
+    /**
+     * Returns a masked string representation safe for logs.
+     */
+    toString(): string;
+}
+/**
+ * Creates a configured EelZap Delivery SDK client.
+ */
+declare function createClient(config: ClientConfig): EelZapClient;
+
+/**
+ * API error codes documented by the delivery API.
+ */
+type EelZapErrorCode = 'UNAUTHORIZED' | 'KEY_EXPIRED' | 'ORIGIN_NOT_ALLOWED' | 'DRAFT_ACCESS_DENIED' | 'NOT_FOUND' | 'INVALID_FILTER' | 'INVALID_SORT' | 'INVALID_LOCALE' | 'INVALID_PARAMS' | 'RATE_LIMITED' | 'INTERNAL_ERROR' | 'NETWORK_ERROR' | (string & {});
+
+/**
+ * Base error thrown by the SDK for API and transport failures.
+ */
+declare class EelZapError extends Error {
+    readonly code: EelZapErrorCode;
+    readonly status: number;
+    /** Per-field problems when the API refused the input; empty otherwise. */
+    readonly details: readonly ApiErrorDetail[];
+    constructor(code: EelZapErrorCode, message: string, status: number, details?: readonly ApiErrorDetail[]);
+}
+/**
+ * Error thrown when a network failure or timeout prevents a response.
+ */
+declare class EelZapNetworkError extends EelZapError {
+    readonly cause: unknown;
+    constructor(cause: unknown, message?: string);
+}
+/**
+ * Type guard for SDK errors.
+ */
+declare function isEelZapError(error: unknown): error is EelZapError;
+
+/**
+ * The URL to render a media value with: the public `url` of a published file,
+ * else the short-lived `signedUrl` a draft carries when the key may read
+ * drafts. `null` when there is neither — an unpublished file read with a key
+ * that cannot see drafts (`mediaAccess: 'none'`), or no media at all.
+ *
+ * A signed URL expires (`signedUrlExpiresAt`), so never cache it in a page
+ * that outlives that time.
+ */
+declare function getMediaUrl(media: Pick<MediaValue, 'url' | 'signedUrl'> | null | undefined): string | null;
+
+/** True when `value` is a string carrying at least one marker. */
+declare function hasStega(value: unknown): boolean;
+/**
+ * `value` with every stega marker removed: a string is cleaned, an array or a
+ * plain object is cleaned deeply (into new objects), anything else is
+ * returned as is. Use it where a preview value is compared, parsed or put in
+ * an attribute, a URL or `<head>`; outside preview it changes nothing.
+ */
+declare function cleanStega<T>(value: T): T;
+
+/**
+ * Outbound webhooks, as the Eel suite sends them (ADR 031): a workspace
+ * endpoint subscribes to `zap.*` events, and every delivery is a JSON envelope
+ * signed with the endpoint's `whsec_…` secret. See `verifyWebhookSignature`.
+ *
+ * Payloads are minimal by design: ids, keys, slugs, links, version numbers and
+ * the NAMES of what changed — never a field value. Read the content itself
+ * with the delivery API.
+ */
+/** Every Zap event an endpoint can receive, plus `ping` (the test button). */
+type WebhookEventName = 'ping' | 'zap.item.created' | 'zap.item.updated' | 'zap.item.draft_updated' | 'zap.item.published' | 'zap.item.unpublished' | 'zap.item.deleted' | 'zap.item.rolled_back' | 'zap.item.assigned' | 'zap.document.created' | 'zap.document.updated' | 'zap.document.draft_updated' | 'zap.document.published' | 'zap.document.unpublished' | 'zap.document.deleted' | 'zap.document.rolled_back' | 'zap.document.assigned' | 'zap.seo.updated' | 'zap.comment.created' | 'zap.comment.replied' | 'zap.comment.resolved' | 'zap.comment.reopened' | 'zap.comment.updated' | 'zap.media.uploaded' | 'zap.media.updated' | 'zap.media.published' | 'zap.media.unpublished' | 'zap.media.deleted' | 'zap.collection.created' | 'zap.collection.updated' | 'zap.collection.deleted' | 'zap.schema.field_changed' | 'zap.site.created' | 'zap.site.updated' | 'zap.site.deleted' | 'zap.site.api_key.created' | 'zap.site.api_key.revoked';
+/** Who made the change. `user_id` is null for an API key or system work. */
+interface WebhookActor {
+    user_id: string | null;
+    display_name: string;
+    kind: 'USER' | 'SYSTEM' | 'API_KEY';
+}
+/** What the event is about, at the id level. Zap events carry `site_id`, and `collection_id` for collection-scoped events. */
+interface WebhookSubject {
+    workspace_id: string;
+    site_id?: string;
+    collection_id?: string;
+}
+/**
+ * The delivery body. `id` is the idempotency key: it is the same across
+ * retries and across endpoints, so dedupe on it (not on `X-Eel-Delivery`).
+ * `type` is a {@link WebhookEventName}; it is typed as a string too because an
+ * endpoint can also subscribe to other suite apps' events.
+ */
+interface WebhookPayload<TData = unknown> {
+    id: string;
+    type: WebhookEventName | (string & {});
+    /** Payload contract version. 2 today. */
+    version: number;
+    app: string;
+    workspace_id: string;
+    /** ISO timestamp of the change. */
+    occurred_at: string;
+    actor: WebhookActor;
+    subject: WebhookSubject;
+    data: TData;
+}
+/** A link into Zap. Null when it cannot be built. */
+type ZapLink = string | null;
+interface WebhookSiteRef {
+    id: string;
+    key: string;
+    url: ZapLink;
+}
+interface WebhookCollectionRef {
+    id: string;
+    key: string;
+}
+/** `data` of the `zap.item.*` content events (not `zap.item.assigned`). */
+interface WebhookItemEventData {
+    site: WebhookSiteRef;
+    collection: WebhookCollectionRef;
+    items: Array<{
+        id: string;
+        slug: string;
+        url: ZapLink;
+        /** The version the event is about; null after a discarded draft. */
+        version?: number | null;
+        /** Names of the fields or properties that changed. */
+        changed?: string[];
+        /** On a rollback: the version number that was restored. */
+        restored_from?: number | null;
+    }>;
+}
+/** `data` of the `zap.document.*` content events (not `zap.document.assigned`). */
+interface WebhookDocumentEventData {
+    site: WebhookSiteRef;
+    documents: Array<{
+        id: string;
+        key: string;
+        url: ZapLink;
+        version?: number | null;
+        changed?: string[];
+        restored_from?: number | null;
+    }>;
+}
+/** `data` of the `zap.media.*` events. */
+interface WebhookMediaEventData {
+    site: WebhookSiteRef;
+    media: Array<{
+        id: string;
+        url: ZapLink;
+        filename?: string;
+    }>;
+}
+/** The kind of content a {@link WebhookChange} is about. */
+type WebhookEventType = 'item' | 'document' | 'media';
+/** What happened to it: the verb of the event name. */
+type WebhookAction = 'created' | 'updated' | 'draft_updated' | 'published' | 'unpublished' | 'deleted' | 'rolled_back' | 'uploaded';
+/**
+ * One changed item, document or file, flattened out of a payload by
+ * `webhookChanges` — the unit a site invalidates its cache by.
+ */
+interface WebhookChange {
+    type: WebhookEventType;
+    action: WebhookAction;
+    id: string;
+    /** The item's slug, the document's key, or the file's id. */
+    resourceKey: string;
+    /** The item's collection. Items only. */
+    collectionKey?: string;
+    siteKey: string;
+}
+/** A comment thread's record: the entry (`slug`) or the document (`key`) it is on. */
+interface WebhookCommentTarget {
+    type: 'item' | 'document';
+    id: string;
+    key: string;
+}
+/** The fields every comment entry carries. Never the comment text. */
+interface WebhookCommentRef {
+    id: string;
+    /** The record page, opened on the thread. */
+    url: string;
+    target: WebhookCommentTarget;
+}
+/** The `data` of every `zap.comment.*` event: one envelope per (event, site, collection). */
+interface WebhookCommentData<TEntry extends WebhookCommentRef = WebhookCommentRef> {
+    site: {
+        id: string;
+        key: string;
+        url: string;
+    };
+    /** Null for events on documents. */
+    collection: {
+        id: string;
+        key: string;
+    } | null;
+    comments: TEntry[];
+}
+type WebhookCommentSource = 'EDITOR' | 'PREVIEW' | 'SITE' | 'API' | 'MCP';
+/** `data` of `zap.comment.created`. */
+type WebhookCommentCreatedData = WebhookCommentData<WebhookCommentRef & {
+    is_change_request: boolean;
+    source: WebhookCommentSource;
+    anchor_kinds: ('field' | 'dom' | 'spot')[];
+    /** Field keys, never values. */
+    field_keys: string[];
+}>;
+/** `data` of `zap.comment.replied`. */
+type WebhookCommentRepliedData = WebhookCommentData<WebhookCommentRef & {
+    comment_id: string;
+}>;
+/** `data` of `zap.comment.resolved`. */
+type WebhookCommentResolvedData = WebhookCommentData<WebhookCommentRef & {
+    is_change_request: boolean;
+    resolution: 'APPLIED' | 'DISMISSED' | null;
+    resolved_in_version_id: string | null;
+}>;
+/** `data` of `zap.comment.reopened`. */
+type WebhookCommentReopenedData = WebhookCommentData<WebhookCommentRef & {
+    cause: 'manual' | 'draft_discarded';
+    resolved_in_version_id: string | null;
+}>;
+/** `data` of `zap.comment.updated`. */
+type WebhookCommentUpdatedData = WebhookCommentData<WebhookCommentRef & {
+    changed: ('assignee' | 'is_change_request' | 'resolution')[];
+    is_change_request: boolean;
+    assignee_id: string | null;
+}>;
+
+/** Header carrying `v1=<hex>`. Header lookups are case-insensitive. */
+declare const WEBHOOK_SIGNATURE_HEADER = "X-Eel-Signature";
+/** Header carrying the unix-second timestamp that is part of the signed content. */
+declare const WEBHOOK_TIMESTAMP_HEADER = "X-Eel-Timestamp";
+/** Deliveries older or newer than this, in seconds, are refused: 5 minutes. */
+declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+/**
+ * The request headers: a Fetch `Headers` (Next.js route handlers, workers), or
+ * a plain object such as Node's `IncomingHttpHeaders` (Express).
+ */
+type WebhookHeaders = Pick<Headers, 'get'> | Record<string, string | readonly string[] | undefined>;
+interface VerifyWebhookOptions {
+    /** Maximum clock difference in seconds. Default {@link WEBHOOK_TOLERANCE_SECONDS}. */
+    toleranceSeconds?: number;
+    /** The current time. Default `new Date()`. */
+    now?: Date;
+}
+/**
+ * Verifies a webhook delivery: the signature over the raw body and the
+ * timestamp, and that the timestamp is within the tolerance window.
+ *
+ * Pass the body exactly as received (`await request.text()`), never a
+ * re-serialised parse: the MAC covers the bytes that were sent.
+ *
+ * @returns `true` only for an authentic, fresh delivery. Any missing or
+ *   malformed header, wrong secret, altered body or stale timestamp is `false`.
+ * @throws When the runtime has no WebCrypto.
+ *
+ * @example
+ * ```ts
+ * const payload = await request.text()
+ * if (!(await verifyWebhookSignature(payload, request.headers, process.env.EELZAP_WEBHOOK_SECRET!))) {
+ *   return new Response('Invalid signature', { status: 401 })
+ * }
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<boolean>;
+/**
+ * Flattens a Zap content event into one {@link WebhookChange} per item,
+ * document or file it names — what a site walks to invalidate its cache.
+ * Every other event (`ping`, schema, site, SEO, assignment, comment
+ * events) yields an empty list.
+ */
+declare function webhookChanges(payload: WebhookPayload): WebhookChange[];
+
+export { type ApiErrorDetail, type ApiErrorPayload, type CacheAdapter, type CacheStrategy, type CachedFetchOptions, type ClientConfig, type ClientDefaults, type CollectionDetail, type CollectionFieldListResponse, CollectionFieldsResource, type CollectionListResponse, type CollectionSectionListResponse, CollectionSectionsResource, type CollectionSummary, CollectionsResource, type CommentAnchor, type CommentAnchorInput, type CommentAnchorKind, type CommentDomAnchor, type CommentDraftAnswer, type CommentFieldAnchorInput, type CommentListOptions, type CommentListResponse, type CommentPersonRef, type CommentProposedValue, type CommentProposedValueInput, type CommentRecord, type CommentRect, type CommentReplyAnswer, type CommentResolution, type CommentSource, type CommentSpotAnchor, type CommentStatus, type CommentTarget, type CommentThread, type CommentThreadAnswer, type CommentVersionRef, type CommentViewport, CommentsResource, type CommonRequestOptions, type ConfirmUploadInput, type CreateCollectionInput, type CreateCommentInput, type CreateDocumentFieldInput, type CreateDocumentInput, type CreateDraftInput, type CreateFieldInput, type CreateItemInput, type CreateSectionInput, type CreateUploadUrlInput, type CurrencyValue, type DeleteDocumentOptions, type DeleteItemOptions, type DeleteOptions, type DeliveryStatus, type DocumentDeleteResponse, type DocumentDetail, type DocumentFieldListResponse, DocumentFieldsResource, type DocumentGetOptions, type DocumentListEntry, type DocumentListOptions, type DocumentListResponse, type DocumentMeta, type DocumentMutationResponse, type DocumentSectionListResponse, DocumentSectionsResource, type DocumentSeo, DocumentSeoResource, type DocumentSeoResponse, DocumentValuesResource, type DocumentValuesResponse, type DocumentVersionDetail, type DocumentVersionSeo, type DocumentVersionSummary, type DocumentVersionValue, DocumentVersionsResource, DocumentsResource, EelZapClient, EelZapError, type EelZapErrorCode, EelZapNetworkError, type EnumValue, type FieldConstraints, type FieldInfo, type FieldOptionInput, type FieldType, type FilterOperatorMap, type FilterValue, type GalleryItemValue, type IdempotencyOptions, type ItemDeleteResponse, type ItemDetail, type ItemFilters, type ItemGetOptions, type ItemListOptions, type ItemListResponse, type ItemMeta, type ItemMutationResponse, ItemQueryBuilder, type ItemSeo, ItemSeoResource, type ItemSeoResponse, type ItemVersionDetail, type ItemVersionSeo, type ItemVersionSlug, type ItemVersionSummary, type ItemVersionValue, ItemVersionsResource, ItemsResource, type JsonObject, type MediaAccess, type MediaDetail, type MediaDetailResponse, type MediaFromUrlInput, type MediaListParams, type MediaListResponse, MediaResource, type MediaSort, type MediaType, type MediaUploadInput, type MediaUsage, type MediaValue, MemoryCacheAdapter, type OnPageComment, type OnPageCommentAnchor, type OnPageComments, type OnPageField, type Pagination, type PreviewOption, type PreviewTokenValidation, PreviewTokensResource, type QueryPrimitive, type ReplyCommentInput, type RetryEvent, type RetryOptions, type SaveCommentToDraftInput, type SectionInfo, type SectionMeta, type Seo, type SeoImage, type SeoInput, type SiteInfo, type SiteListEntry, SiteResource, SitesResource, type ThreadComment, type UpdateCollectionInput, type UpdateCommentInput, type UpdateDocumentDraftInput, type UpdateDocumentFieldInput, type UpdateDocumentInput, type UpdateFieldInput, type UpdateItemDraftInput, type UpdateItemInput, type UpdateMediaInput, type UpdateSectionInput, type UpdateSiteInput, type UploadFile, type UploadUrlResponse, type VerifyWebhookOptions, type VersionDetail, type VersionGalleryItem, type VersionListResponse, type VersionSeo, type VersionStatus, type VersionSummary, type VersionValue, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_TOLERANCE_SECONDS, type WebhookAction, type WebhookActor, type WebhookChange, type WebhookCollectionRef, type WebhookCommentCreatedData, type WebhookCommentData, type WebhookCommentRef, type WebhookCommentReopenedData, type WebhookCommentRepliedData, type WebhookCommentResolvedData, type WebhookCommentSource, type WebhookCommentTarget, type WebhookCommentUpdatedData, type WebhookDocumentEventData, type WebhookEventName, type WebhookEventType, type WebhookHeaders, type WebhookItemEventData, type WebhookMediaEventData, type WebhookPayload, type WebhookSiteRef, type WebhookSubject, cachedFetch, cleanStega, createClient, getMediaUrl, hasStega, isEelZapError, verifyWebhookSignature, webhookChanges };