import type { BrandApiClientOptions } from "../api/client.js";
/**
 * Base path for the Brand Documents API. Same edge host as the
 * Brand Management / Brand Review APIs.
 */
export declare const DOCUMENTS_BASE_PATH = "/stream/ai-document-api";
export interface DocumentUploadReference {
    /** Reference type — always `"brandkit"` for kit-bound docs. */
    type: "brandkit";
    /** UUID of the target brand kit. */
    id: string;
    /** Canonical brand kit references path. */
    path: string;
}
export type UploadDocumentSource = {
    kind: "url";
    url: string;
} | {
    kind: "bytes";
    bytes: Buffer | Uint8Array;
    mimeType?: string;
};
/**
 * Why local-file (`bytes`) upload is rejected. The documents API
 * offers two routes for a local file and neither works:
 *
 *   - The documented v2 `multipart/form-data` `file` part is
 *     server-broken — the parser drops the sibling `create_request`
 *     part whenever a `file` part is present and returns
 *     `400 create_request: Field required`.
 *   - A `data:<mime>;base64,…` value in the `url` field is accepted
 *     at POST time (201) but the server never fetches it, so the doc
 *     stays at `numberOfPages: 0` and never processes.
 *
 * Both reproduced empirically against the Agents tenant 2026-05-15
 * (`scripts/_smoke-brand-upload-modes.ts`). Until Sitecore exposes a
 * working local-upload path, callers must host the file and use URL
 * mode.
 */
export declare const LOCAL_UPLOAD_UNSUPPORTED_MESSAGE = "Local-file document upload is not supported \u2014 the Sitecore documents API has no working path for it.";
export declare const LOCAL_UPLOAD_UNSUPPORTED_HINT = "Host the PDF at an HTTPS URL that Sitecore's edge can reach (S3, GitHub raw, a CDN), then upload it by URL \u2014 `--url <pdfUrl>` on the CLI, or the `url` field on the MCP tool.";
export interface UploadDocumentOptions {
    client: BrandApiClientOptions;
    /** Brand kit UUID to attach the document to. */
    brandKitId: string;
    /**
     * Source of the document. Only URL mode works:
     *
     *   - `{ kind: "url", url }` — Sitecore fetches the file from the
     *     URL and copies it into MMS. The URL must be an HTTP(S)
     *     address reachable from Sitecore's edge.
     *   - `{ kind: "bytes", … }` — local-file upload. **Not supported**
     *     — `uploadDocument` rejects it with `INPUT_INVALID`. See
     *     {@link LOCAL_UPLOAD_UNSUPPORTED_MESSAGE} for why.
     *
     * The string form `{ url }` is shorthand for `{ kind: "url", url }`.
     */
    source: UploadDocumentSource | {
        url: string;
    };
    /** Document type tag, e.g. "brand guidelines". */
    type?: string;
    /**
     * Document MIME type, e.g. "application/pdf". The working Sync kit
     * docs use the full MIME (not labels like "PDF").
     */
    fileType?: string;
    /** Display title; if `setMetadata: true` the server may overwrite. */
    title?: string;
    /** Brief description. */
    summary?: string;
    /** Tags. The server rejects null — defaults to []. */
    tags?: string[];
    /**
     * Whether the server should auto-fill metadata (page count, etc.)
     * from the fetched file. Defaults to true.
     */
    setMetadata?: boolean;
    signal?: AbortSignal;
}
export interface UploadedDocument {
    id: string;
    organizationId?: string;
    status?: string;
    /** Sitecore MMS URL the file got copied to (when copying happens). */
    url?: string;
    fileId?: string;
    type?: string;
    fileType?: string;
    brandkitId?: string;
    references?: Array<{
        id: string;
        path: string;
        type: string;
    }>;
    [extra: string]: unknown;
}
/**
 * Upload a brand document to the Sitecore Brand Documents API and
 * attach it to a specific brand kit.
 *
 * **URL mode only.** The server fetches the file from `url` and copies
 * it to Sitecore MMS asynchronously, so the `url` must be an HTTP(S)
 * address reachable from Sitecore's edge. Local-file (`bytes`) uploads
 * are rejected up front — see {@link LOCAL_UPLOAD_UNSUPPORTED_MESSAGE}.
 *
 * **Wire shape:** v2 endpoint, `application/x-www-form-urlencoded`, a
 * single `create_request` form parameter whose value is a JSON string
 * carrying `url`, `tags`, `references`, and metadata fields. The
 * documented `multipart/form-data` `file` part is server-broken; the
 * form-urlencoded path is what returns 201 with references populated.
 */
export declare const uploadDocument: (options: UploadDocumentOptions) => Promise<UploadedDocument>;