@oeave/bakery3 0.0.0-stage → 0.2.0

package/dist/testRun-20OARnQr.d.ts

@@ -0,0 +1,1139 @@
+import { R as RenderSpec, e as BakeSpec, f as BakeBundleSummary, V as Vec3, g as CameraSpec, h as CompatibilityIssue, A as AssetHash, i as BakeSettings } from './bake-DZ-CJR6f.js';
+
+/**
+ * A batch: a customer's declared body of work.
+ *
+ * A catalog is products x finishes x cameras, a few thousand stills. The
+ * customer opens a batch, adds items in pages, closes it, and reads one
+ * ledger back. On the control plane every item is a render row with a
+ * `batchId`, staged behind the queue proper and fed into it a page at a
+ * time, so everything that holds for a render (the claim, the reservation,
+ * single billing, webhooks, retention) holds for an item because it is one.
+ */
+
+declare const BATCH_STATES: readonly ["open", "sealed", "paused", "completed", "cancelled"];
+type BatchState = (typeof BATCH_STATES)[number];
+/**
+ * How many items are in each state. `staged` items are admitted: priced,
+ * reserved, waiting behind the queue proper. `queued` are in the queue and
+ * `running` hold a worker. `refused` failed for a reason a retry would not
+ * change (the scene's fault, or ours to explain); `failed` ran out of
+ * attempts on an infrastructure failure. `adopted` were already completed
+ * under the same key when they were added and cost nothing.
+ */
+type BatchCounts = {
+    staged: number;
+    queued: number;
+    running: number;
+    completed: number;
+    failed: number;
+    refused: number;
+    cancelled: number;
+    adopted: number;
+};
+type BatchCost = {
+    /** Sum of estimatedCost over admitted items. */
+    estimated: number;
+    /** Sum of maximumCost over admitted items: what admission reserved. */
+    maximum: number;
+    /** Sum of what completed items actually cost, so far. */
+    actual: number;
+};
+type BatchRecord = {
+    id: string;
+    key: string;
+    name?: string;
+    kind: 'render' | 'bake';
+    state: BatchState;
+    lane: 'batch' | 'normal';
+    maxParallel?: number;
+    /** The customer's ceiling for the whole batch. */
+    maxCost?: number;
+    counts: BatchCounts;
+    /** Every item ever admitted, adopted included. */
+    total: number;
+    /** How many are terminal. `done === total` once sealed is `completed`. */
+    done: number;
+    cost: BatchCost;
+    /** Why it is paused, when it is: the breaker names the top refusal codes. */
+    pausedReason?: string;
+    createdAt: number;
+    sealedAt?: number;
+    finishedAt?: number;
+};
+type BatchOpenRequest = {
+    /**
+     * Stable across re-runs: the same key re-opens the same batch while it is
+     * not terminal, and items already completed under their keys are adopted
+     * rather than rendered again.
+     */
+    key: string;
+    name?: string;
+    kind?: 'render' | 'bake';
+    /**
+     * The ceiling for the whole batch, in dollars. A page that would take the
+     * batch's maximum past it is refused whole.
+     */
+    maxCost?: number;
+    /**
+     * `batch` (the default) never runs ahead of a person in a configurator;
+     * `normal` is the API's ordinary lane.
+     */
+    lane?: 'batch' | 'normal';
+    /** Fewer parallel items than the plan allows, for a gentler budget. */
+    maxParallel?: number;
+};
+type BatchItemRequest = {
+    /**
+     * The item's idempotency key, scoped to the project like every other
+     * render's. `sku/finish/camera@v3` is the shape the docs suggest.
+     */
+    key: string;
+    spec: RenderSpec | BakeSpec;
+    metadata?: Record<string, unknown>;
+    /** A ceiling for this one item, under the batch's. */
+    maxCost?: number;
+};
+type BatchAddRequest = {
+    items: BatchItemRequest[];
+    /**
+     * Price everything, admit nothing: the whole catalog's numbers before a
+     * dollar is reserved.
+     */
+    dryRun?: boolean;
+};
+type BatchItemOutcome = {
+    key: string;
+    /** The render's id, when it was admitted or adopted. */
+    id?: string;
+    estimatedCost: number;
+    maximumCost: number;
+    /** Already completed under this key: attached at no cost. */
+    adopted?: boolean;
+    /**
+     * Why this item, alone, was not admitted (a bad spec, an item over its own
+     * maxCost). The page's other items are unaffected.
+     */
+    error?: RenderError;
+};
+type BatchAddResponse = {
+    batch: BatchRecord;
+    items: BatchItemOutcome[];
+};
+/** One line of `GET /v1/batches/:id/export`: the ledger, item by item. */
+type BatchExportLine = {
+    key: string;
+    id: string;
+    state: string;
+    resultUrl?: string;
+    error?: RenderError;
+    cost?: number;
+    versions?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+
+/**
+ * Render job states and the events that carry them.
+ *
+ * Every transition is timestamped, idempotent and observable. Idempotent is
+ * the load-bearing word: a worker that retries a stage must not bill twice
+ * and must not emit `render.completed` twice, so the control plane treats a
+ * transition to a state it is already in as a no-op rather than an error.
+ */
+declare const RENDER_STATES: readonly ["created", "uploading", "validating", "queued", "starting", "preparing", "rendering_preview", "rendering", "encoding", "uploading_result", "completed", "failed", "cancelled", "expired"];
+type RenderState = (typeof RENDER_STATES)[number];
+type RenderResult = {
+    /**
+     * Signed, private, and only good until `expiresAt` (24 hours). Copy the
+     * bytes into your own storage if you keep them; `getRender(id)` hands out
+     * fresh URLs until the project's retention deletes the files.
+     */
+    url: string;
+    /**
+     * Millisecond epoch at which `url` (and `previewUrl`) stop working. The
+     * URLs are signed when the render is read, so reading it again with
+     * `getRender(id)` returns fresh ones. Absent from an API that predates it.
+     */
+    expiresAt?: number;
+    width: number;
+    height: number;
+    format: string;
+    bytes: number;
+    /** What was actually charged, in USD. Not the estimate. */
+    cost: number;
+    /** Everything needed to reproduce this exact image later. */
+    versions: {
+        protocol: string;
+        sdk: string;
+        translator: string;
+        qualityPreset: string;
+    };
+};
+/**
+ * Which queue a render waits in inside its account.
+ *
+ * `interactive` is a person waiting: every browser-token render, and the
+ * SDK's `render()` by default. `normal` is the API default. `batch` is an
+ * item of a batch. A lane above always dispatches before a lane below, so a
+ * configurator's visitor never waits behind an overnight catalog.
+ */
+declare const RENDER_LANES: readonly ["interactive", "normal", "batch"];
+type RenderLane = (typeof RENDER_LANES)[number];
+type RenderRecord = {
+    id: string;
+    state: RenderState;
+    progress: number;
+    /**
+     * A video's frames traced so far and in all, while it renders. Updated
+     * every ten seconds or so; absent for a still and once the render ends.
+     */
+    frames?: {
+        done: number;
+        total: number;
+    };
+    /** Which of the account's queues it waits in. */
+    lane?: RenderLane;
+    /**
+     * How many times a worker has been handed this render. 1 is the normal
+     * case; more means an infrastructure failure was retried for you.
+     */
+    attempts?: number;
+    /** The batch this render belongs to, and its key within it. */
+    batchId?: string;
+    batchKey?: string;
+    /** A low-sample image, available long before the final one. */
+    previewUrl?: string;
+    result?: RenderResult;
+    error?: RenderError;
+    estimate?: CostEstimate;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * A finished bake, as `GET /v1/bakes/:id` answers it.
+ *
+ * The bundle's uv arrays are behind `bundleUrl`, not here: a dense room's
+ * are megabytes, and the SDK reads them once from storage. `files` is every
+ * name the bundle uses, resolved to a signed URL, so a loader can take
+ * `bundle.objects[i].lightmap.uri` and look it up without knowing where the
+ * files live. All of them expire together, at `expiresAt`.
+ */
+type BakeResult = {
+    /** Signed GET for bundle.json: the BakeBundle, uv arrays and all. */
+    bundleUrl: string;
+    /** Every file the bundle names, by that name, as a signed GET. */
+    files: Record<string, string>;
+    /** Millisecond epoch at which the URLs stop working. */
+    expiresAt: number;
+    /**
+     * The bundle without its uv arrays: what a panel shows before it fetches
+     * anything.
+     */
+    summary: BakeBundleSummary;
+    /** Every file's size together, in bytes. */
+    bytes: number;
+    cost: number;
+    versions: Record<string, string | number>;
+};
+type BakeRecord = {
+    id: string;
+    state: RenderState;
+    progress: number;
+    result?: BakeResult;
+    error?: RenderError;
+    estimate?: CostEstimate;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Cost, before anything expensive happens.
+ *
+ * `maximum` is what `maxCost` is compared against, so a developer who sets
+ * a ceiling gets a refusal rather than a bill somewhere between the two
+ * numbers.
+ */
+type CostEstimate = {
+    estimatedCost: number;
+    maximumCost: number;
+    estimatedSeconds: number;
+    compatibilityScore: number;
+};
+/**
+ * A failure a developer can act on.
+ *
+ * `code` is stable and machine-readable; `message`, `why` and `fix` are for
+ * the developer. A traceback is never any of them.
+ */
+type RenderError = {
+    code: RenderErrorCode;
+    message: string;
+    why?: string;
+    fix?: string;
+    docs?: string;
+    /** Where in the scene, when the failure has a location. */
+    path?: string;
+    /** Whether resubmitting unchanged could plausibly work. */
+    retryable: boolean;
+    /**
+     * The control plane tried this render again and gave up: every attempt
+     * failed the same retryable way. We have been told, and
+     * `POST /v1/renders/:id/retry` tries once more on request.
+     */
+    attemptsExhausted?: boolean;
+};
+declare const RENDER_ERROR_CODES: readonly ["RenderBudgetExceeded", "UnsupportedMaterial", "SceneTooLarge", "TextureTooLarge", "AssetNotFound", "AssetUploadIncomplete", "ProtocolVersionUnsupported", "RoomPresetUnknown", "RoomPresetBuildMismatch", "CompatibilityPreflightFailed", "OutOfVideoMemory", "RenderTimeout", "WorkerFailure", "WorkerLost", "RendererCrashed", "UploadFailed", "ResultLost", "CapacityUnavailable", "QueueFull", "QueueTimeout", "BatchBudgetExceeded", "BatchClosed", "ImportRefused", "ImportFailed", "PlanRequired", "StorageUnavailable", "InsufficientBalance", "QuotaExceeded", "ConcurrencyLimitReached", "RateLimited", "Unauthorized", "TokenExpired", "OriginNotAllowed", "InvalidRequest"];
+type RenderErrorCode = (typeof RENDER_ERROR_CODES)[number];
+/** Webhook event names. */
+declare const WEBHOOK_EVENTS: readonly ["render.created", "render.started", "render.preview", "render.completed", "render.failed", "render.cancelled", "render.retrying", "video.started", "video.frame.completed", "video.completed", "bake.created", "bake.started", "bake.completed", "bake.failed", "bake.cancelled", "bake.retrying", "batch.progress", "batch.completed", "batch.paused"];
+type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
+/**
+ * What a webhook carries. A `render.*` event has `render`; a `bake.*` event
+ * has `bake`. Never both: a receiver switches on `event` and reads the one
+ * record the event is about.
+ */
+type WebhookPayload = {
+    event: WebhookEvent;
+    /** Millisecond epoch. Signed together with the body; see the docs. */
+    sentAt: number;
+    render?: RenderRecord;
+    bake?: BakeRecord;
+    /** A `batch.*` event carries the batch's ledger instead. */
+    batch?: BatchRecord;
+};
+
+type AssetKind = 'scene' | 'texture' | 'hdri' | 'ies' | 'geometry' | 'animation';
+type AssetDescriptor = {
+    hash: string;
+    kind: AssetKind;
+    bytes: number;
+    contentType: string;
+    /** Diagnostics and the devtools' upload list; never used for addressing. */
+    name?: string;
+};
+/** Request body for "which of these do you already have?". */
+type AssetCheckRequest = {
+    assets: AssetDescriptor[];
+};
+/**
+ * The answer, plus a signed PUT for each miss.
+ *
+ * The presigned URL is a capability, not a credential: one object, one
+ * method, one expiry. It lets the browser upload straight to storage without
+ * the control plane ever touching the bytes.
+ */
+type AssetCheckResponse = {
+    /** Hashes already in storage. Do not upload these. */
+    present: string[];
+    /** One signed PUT per hash that is missing. */
+    uploads: Array<{
+        hash: string;
+        url: string;
+        /**
+         * Headers the signature covers. A presigned PUT is signed over an exact
+         * header set, so sending more or fewer than these is a 403. Pass them
+         * through verbatim.
+         */
+        headers?: Record<string, string>;
+        expiresAt: number;
+    }>;
+};
+/**
+ * `DELETE /v1/assets/:hash`. Secret key only. The stored file and its
+ * record are gone; the next render that needs it uploads it again.
+ */
+type AssetDeleteResponse = {
+    hash: string;
+    /** False when the project held no file with this hash: not an error. */
+    deleted: boolean;
+};
+
+/**
+ * What a GLB says about itself, read from its JSON chunk alone.
+ *
+ * A scene the SDK captured arrives with everything the control plane needs
+ * beside it: a triangle count to price with, a camera, a compatibility
+ * report. A model fetched by URL arrives with nothing, and the renderer is
+ * the wrong place to find out it cannot be read: that is a refusal at three
+ * in the morning, a thousand times. So the import reads the file's own
+ * table of contents, which is the first chunk and a few hundred KB at most,
+ * and answers before anything is admitted:
+ *
+ * - how heavy it is (triangles, per node instance, the way it will trace);
+ * - where it is (the world bounds, from accessor min/max through the node
+ *   transforms), which is what lets a camera be FRAMED instead of guessed;
+ * - which cameras it carries, by name;
+ * - what in it the renderer cannot read (a required extension its importer
+ *   does not implement), by name and with the fix.
+ *
+ * Pure, no dependencies, no binary chunk: nothing here decodes geometry.
+ */
+
+type GlbCamera = {
+    /** The node's name, or the camera's. What a caller asks for it by. */
+    name: string;
+    /** As it stands in the file, in world space. `aspect` is the file's own, when it gives one. */
+    camera: CameraSpec;
+};
+type GlbFacts = {
+    bytes: number;
+    /** Counted per node instance: a mesh two nodes show is traced twice. */
+    triangles: number;
+    meshes: number;
+    materials: number;
+    textures: number;
+    /** Punctual lights the file carries. They render as its author set them. */
+    lights: number;
+    animations: number;
+    /** World bounds of everything with geometry, or null for a file with none. */
+    bounds: {
+        min: Vec3;
+        max: Vec3;
+    } | null;
+    cameras: GlbCamera[];
+    /** Named nodes, in file order, bounded. */
+    objects: string[];
+    extensionsUsed: string[];
+    extensionsRequired: string[];
+    generator?: string;
+    /** `error` issues mean the renderer cannot read the file as authored. */
+    issues: CompatibilityIssue[];
+};
+
+/**
+ * Importing an asset by URL: `POST /v1/assets/import`.
+ *
+ * Every other asset is pushed: the browser hashes it and PUTs it on a
+ * presigned URL. A catalog that already sits on a CDN should not be pulled
+ * through somebody's laptop to be pushed again, so this one is pulled: the
+ * control plane fetches the public URL once, stores the bytes content
+ * addressed exactly as an upload would have, and answers with the hash and
+ * what the file says about itself. The result is an ordinary asset, and
+ * everything after it (the manifest, the cache keys, the render) is the
+ * ordinary path.
+ *
+ * Fetching a URL a customer names is the one thing here a stranger could aim
+ * somewhere else, so the route takes a secret key only (never a browser
+ * token), and the fetch is fenced: https, public addresses only, no
+ * credentials in the URL, and a size limit.
+ */
+
+type AssetImportKind = 'scene' | 'hdri';
+type AssetImportRequest = {
+    /** `https://`, public, no credentials in it. */
+    url: string;
+    /** `scene` (a GLB, the default) or `hdri` (a Radiance .hdr or an OpenEXR). */
+    kind?: AssetImportKind;
+};
+type AssetImportResponse = {
+    hash: AssetHash;
+    kind: AssetImportKind;
+    bytes: number;
+    /**
+     * True when nothing was downloaded: the URL answered 304 to the validator
+     * kept from the last import, so the stored bytes are still what it serves.
+     */
+    unchanged: boolean;
+    /** For a `scene`: what the GLB says about itself. */
+    facts?: GlbFacts;
+};
+
+/**
+ * Errors a developer can act on.
+ *
+ * "Render failed" is a bad error. A traceback is a worse one. Every failure
+ * that reaches the developer carries what went wrong, where, why, and what to
+ * do about it, and `code` stays stable so the failure can also be branched on
+ * in code.
+ */
+
+/**
+ * Codes the SDK can raise that the render protocol does not: a fault on the
+ * way (`NetworkError`), a fault before anything left the browser
+ * (`CaptureFailed`), the two refusals a batch page can meet as a whole (over
+ * the batch's own ceiling, or after it was sealed), and the two ends of a job
+ * that are not faults in the scene: it was cancelled (`Cancelled`), or its
+ * files were deleted before it was read (`Expired`).
+ */
+type Bakery3ErrorCode = RenderErrorCode | 'NetworkError' | 'CaptureFailed' | 'BatchBudgetExceeded' | 'BatchClosed' | 'Cancelled' | 'Expired';
+declare class Bakery3Error extends Error {
+    readonly code: Bakery3ErrorCode;
+    readonly why?: string;
+    readonly fix?: string;
+    readonly docs?: string;
+    readonly path?: string;
+    readonly retryable: boolean;
+    constructor(init: {
+        code: Bakery3ErrorCode;
+        message: string;
+        why?: string;
+        fix?: string;
+        docs?: string;
+        path?: string;
+        retryable?: boolean;
+    });
+    static from(error: RenderError): Bakery3Error;
+    /**
+     * The multi-line form, for a console or a devtools panel.
+     *
+     * `Error.message` stays one line so it reads correctly everywhere a message
+     * is expected to be one: a log aggregator, a toast, a test name. `stack`
+     * starts with this form, so an uncaught error prints its fix.
+     */
+    toDisplayString(): string;
+}
+/** What was refused, so the refusal can say which dials bring the price down. */
+type BudgetedKind = 'render' | 'video' | 'bake';
+/**
+ * What a budget refusal can say. Every field is optional, because a refusal
+ * from the API may carry fewer numbers than the SDK's own check knows.
+ */
+type RenderBudgetInit = {
+    message?: string;
+    why?: string;
+    fix?: string;
+    docs?: string;
+    /** The ceiling that was set. */
+    maxCost?: number;
+    estimatedCost?: number;
+    maximumCost?: number;
+    kind?: BudgetedKind;
+};
+/**
+ * The budget refusal.
+ *
+ * Its own class because it is the one failure a developer is expected to
+ * catch by type rather than by code: it is a normal, designed outcome of
+ * setting `maxCost`, not a fault. Nothing was sent to a renderer and nothing
+ * was charged.
+ *
+ * `instanceof RenderBudgetExceeded` catches both ways it is raised: the SDK's
+ * own check before an upload (`new RenderBudgetExceeded(maxCost, quote,
+ * kind)`, every number known), and the API's 402 (`new
+ * RenderBudgetExceeded({ ... })`, with whatever numbers that answer carried,
+ * for example from a browser token that has spent its allowance).
+ */
+declare class RenderBudgetExceeded extends Bakery3Error {
+    /** The ceiling that was set, when known. */
+    readonly maxCost?: number;
+    readonly estimatedCost?: number;
+    /** The ceiling the job would have been accepted under: the number `maxCost` is held against. */
+    readonly maximumCost?: number;
+    readonly kind: BudgetedKind;
+    constructor(maxCost: number, quote: {
+        estimatedCost: number;
+        maximumCost: number;
+    }, kind?: BudgetedKind);
+    constructor(init: RenderBudgetInit);
+}
+/**
+ * A whole page of batch items was refused.
+ *
+ * Admission is per page: the control plane prices the page, checks it against
+ * the account's balance and the batch's own `maxCost`, and either admits
+ * every item or none. A `402 InsufficientBalance`, a `402 BatchBudgetExceeded`
+ * or a `409 BatchClosed` means nothing in the page was admitted. The `Batch`
+ * keeps those items buffered, so after a top-up (or a higher ceiling)
+ * `flush()` sends exactly the same page again.
+ *
+ * `admitted` is what earlier pages of the same flush already got through:
+ * those items are the server's now, and this error carries their outcomes so
+ * a caller does not lose them because a later page was refused.
+ */
+declare class BatchPageRefused extends Bakery3Error {
+    /** The page that was refused whole, still in the batch's buffer. */
+    readonly page: BatchItemRequest[];
+    /** Outcomes of the pages this flush admitted before the refusal. */
+    readonly admitted: BatchItemOutcome[];
+    constructor(cause: Bakery3Error, page: BatchItemRequest[], admitted: BatchItemOutcome[]);
+}
+
+/**
+ * The HTTP client for the control plane.
+ *
+ * Small on purpose: a handful of endpoints, one auth header, one error shape.
+ * The interesting work happens in the browser (capture, hashing) and on the
+ * render workers; this is the thin part in between.
+ *
+ * The one piece of policy it carries is the retry: a 429 or a 503 is the
+ * control plane saying "not now", and it is answered with a bounded, jittered
+ * wait rather than an error the developer has to write a loop around. Only
+ * requests that are safe to repeat are repeated (see `RequestOptions.retry`).
+ *
+ * In production no secret key reaches this file. The browser holds a
+ * short-lived, project-scoped, origin-restricted, spend-capped token minted by
+ * the developer's own server. `token` is a function rather than a string so
+ * it can be fetched again when one expires, which for a five-minute token in
+ * a long configurator session is routine.
+ *
+ * `apiKey` is the other door, and it is open on purpose: a key works from the
+ * browser so the first render is one paste away, and `warnIfKeyIsExposed`
+ * says once, with the replacement code, why it must not stay there.
+ *
+ * Neither is needed to construct a client: `check()` and `inspect()` never
+ * touch the network, and a React tree whose environment variable is unset
+ * must still mount. A missing credential is refused at the first request,
+ * with what to pass instead.
+ */
+
+/** What `/v1/estimate` prices: a still or a clip, or a bake. */
+type EstimateRequest = (Pick<RenderSpec, 'quality' | 'output' | 'advanced'> & {
+    /** Triangle count and texture footprint, so an estimate can be given
+     *  before anything has been uploaded. `room` says the scene stands in a
+     *  preset room, which the renderer builds around it; `enclosure` and
+     *  `objects` say how walled in and how full it is from the camera
+     *  (`SceneComplexity`), which is what makes an interior cost more. */
+    scene?: {
+        triangles?: number;
+        textureBytes?: number;
+        fog?: boolean;
+        room?: boolean;
+        enclosure?: number;
+        objects?: number;
+    };
+    /** Frames in a clip; the control plane prices a video per frame. */
+    frames?: number;
+}) | {
+    /** The settings a bake request would carry. Texels (objects × size²)
+     *  are what the control plane prices. */
+    bake: Pick<BakeSettings, 'quality' | 'textureSize' | 'include' | 'sizes' | 'atlas' | 'deliverGlb' | 'simplify' | 'shadow'> & {
+        /** The scene is a room interior: a ray that misses keeps going,
+         *  which is most of what such a bake costs. */
+        enclosed?: boolean;
+    };
+    /** Triangles in the objects the bake would cover: what the unwrap runs
+     *  over, and priced separately from the scene's own count. */
+    bakedTriangles?: number;
+    scene?: {
+        triangles?: number;
+        textureBytes?: number;
+        fog?: boolean;
+    };
+};
+/** A browser token: the string, or the JSON `tokens.create()` answers with. */
+type MintedToken = string | {
+    token: string;
+    expiresAt?: number;
+};
+type TokenProvider = () => MintedToken | Promise<MintedToken>;
+/**
+ * One of the two, never both. Neither is allowed too, for a client that only
+ * checks scenes; its first request is refused with what to pass.
+ *
+ * The `?: never` arms turn passing both into a type error at the call site
+ * rather than a runtime throw later: the two are different integrations, and
+ * a codebase carrying both is one that has not finished moving off the key.
+ */
+type ClientAuth = {
+    /** Mints a browser token, usually from your own `/api/bakery3-token`. */
+    token: TokenProvider;
+    apiKey?: never;
+} | {
+    /**
+     * A `bk_sk_` key used directly, for local testing, a Node script, or a
+     * server-rendered call.
+     *
+     * From a browser this ships the key to every visitor. The SDK allows it
+     * so the first render is one paste away, warns about it in the console,
+     * and expects `token` by the time you deploy.
+     *
+     * `undefined` (an environment variable that is not set) is accepted
+     * here and refused at the first request, with that said.
+     */
+    apiKey: string | undefined;
+    token?: never;
+} | {
+    token?: undefined;
+    apiKey?: undefined;
+};
+/**
+ * How a 429 or a 503 is waited out. Bounded: after `maxTries` the error is
+ * the developer's. The defaults are the SDK's; a test shortens the delays.
+ */
+type RetryPolicy = {
+    /** Attempts in total, the first included. Default 5. */
+    maxTries?: number;
+    /** The first wait, before jitter and doubling. Default 500 ms. */
+    baseDelayMs?: number;
+    /** No single wait is longer than this, `Retry-After` included. Default 30 s. */
+    maxDelayMs?: number;
+};
+type ClientOptions = ClientAuth & {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    retry?: RetryPolicy;
+};
+/** Per-request knobs, for the client's own methods. */
+type RequestOptions = {
+    /**
+     * Whether a 429/503 may be answered by sending the request again.
+     *
+     * Every GET is. A POST is only when repeating it cannot do a second thing:
+     * a batch page (its items carry keys), a batch action, a render that
+     * carries an `idempotencyKey`. `POST /v1/renders` without one is not: a
+     * second copy would be a second charge, which no amount of backoff is
+     * worth.
+     */
+    retry?: boolean;
+    /** Cuts a long-poll short. */
+    signal?: AbortSignal;
+};
+/** `GET /v1/batches/:id/items`: the render record plus the item's key. */
+type BatchItemRecord = RenderRecord & {
+    key: string;
+};
+type BatchItemsPage = {
+    items: BatchItemRecord[];
+    cursor: string | null;
+};
+type BatchAction = 'close' | 'pause' | 'resume' | 'cancel' | 'retry';
+declare class Bakery3Client {
+    private readonly baseUrl;
+    private readonly auth;
+    /**
+     * The fetch this client sends with: the one passed in `options.fetch`, or
+     * the global. Uploads and bundle reads use it too, so a test, a proxy or a
+     * runtime with its own fetch sees every request the SDK makes.
+     */
+    readonly fetch: typeof fetch;
+    /** Cached until it expires. Re-minting per render would add a round trip to
+     *  the developer's own server on the critical path of every click. */
+    private cached;
+    /** One token fetch at a time. React's StrictMode mounts twice, and two
+     *  renders at once both find the cache empty: they share this one. */
+    private minting;
+    /**
+     * The browser token each render, bake and batch was created with, by id.
+     *
+     * A token can only read the rows it created. Once it has spent its
+     * allowance or expired, the API still lets it read and cancel those rows
+     * (for 24 hours past expiry) but not create more, and a freshly minted
+     * token cannot read them at all. So a job polls with the token that
+     * started it, whatever the local cache thinks of that token's expiry.
+     */
+    private readonly owners;
+    private readonly retry;
+    private readonly sendVersion;
+    constructor(options?: ClientOptions);
+    /**
+     * Why this client cannot make a request, or null when it can. The same
+     * error its first request would throw, for a panel or a status line that
+     * wants to say so before anyone presses Render.
+     */
+    credentialError(): Bakery3Error | null;
+    token(force?: boolean): Promise<string>;
+    private mint;
+    checkAssets(body: AssetCheckRequest): Promise<AssetCheckResponse>;
+    /**
+     * `POST /v1/assets/import`: have the service fetch a public URL into the
+     * project's assets. Secret key only. Safe to repeat: the same bytes are the
+     * same asset, and an unchanged URL is answered without a download.
+     */
+    importAsset(body: AssetImportRequest): Promise<AssetImportResponse>;
+    estimate(body: EstimateRequest): Promise<CostEstimate>;
+    createRender(body: RenderSpec): Promise<RenderRecord>;
+    /**
+     * A render's record, with fresh signed URLs for its result and preview.
+     * Read with the token that created it, when this client created it.
+     */
+    getRender(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RenderRecord>;
+    cancelRender(id: string): Promise<RenderRecord>;
+    /**
+     * `POST /v1/renders/:id/retry`: one more attempt for a dead-lettered render.
+     * Answers 201 with a new render linked to the old one, or 409 when the
+     * render is not dead-lettered. Not repeated on a 429/503: it creates a
+     * render, and a duplicate would be a duplicate charge.
+     */
+    retryRender(id: string): Promise<RenderRecord>;
+    createBake(body: BakeSpec): Promise<BakeRecord>;
+    getBake(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<BakeRecord>;
+    cancelBake(id: string): Promise<BakeRecord>;
+    /** `POST /v1/batches`. The key is the idempotency key: the same key
+     *  re-opens the same batch (200) while it is not terminal. */
+    openBatch(body: BatchOpenRequest): Promise<BatchRecord>;
+    /**
+     * `GET /v1/batches/:id`. With `wait`, long-polls for up to that many
+     * seconds (at most 25) until the counts change: the one poll a batch needs.
+     */
+    getBatch(id: string, options?: {
+        wait?: number;
+        signal?: AbortSignal;
+    }): Promise<BatchRecord>;
+    /**
+     * `POST /v1/batches/:id/items`: one page, at most `BATCH_PAGE_SIZE`.
+     *
+     * Every item carries its own key, so the page is safe to send twice: the
+     * second copy adopts what the first admitted. A refusal of the whole page
+     * (402 InsufficientBalance / BatchBudgetExceeded, 409 BatchClosed) throws;
+     * a problem with one item comes back inside `items[i].error` with a 200.
+     */
+    addBatchItems(id: string, body: BatchAddRequest): Promise<BatchAddResponse>;
+    /** `GET /v1/batches/:id/items?state=&cursor=&limit=`. */
+    listBatchItems(id: string, options?: {
+        state?: RenderState;
+        cursor?: string;
+        limit?: number;
+    }): Promise<BatchItemsPage>;
+    /**
+     * `GET /v1/batches/:id/export`: the ledger as NDJSON, one line per item,
+     * yielded as it streams so a ten-thousand-item batch is never one string.
+     */
+    exportBatch(id: string): AsyncIterable<BatchExportLine>;
+    /** `POST /v1/batches/:id/{close,pause,resume,cancel,retry}`. Every one is a
+     *  state transition the control plane treats idempotently, so all repeat. */
+    batchAction(id: string, action: BatchAction): Promise<BatchRecord>;
+    private post;
+    /** A request about a row this client may have created, with its token. */
+    private read;
+    /** Remember which token created a row, so the row is read with it. */
+    private remember;
+    /**
+     * One authenticated JSON request, with the 401 re-mint and the 429/503
+     * backoff. Public for the server SDK, which shares the transport; the
+     * typed methods above are the API.
+     */
+    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /** A JSON request, and the credential that got the answer. */
+    private call;
+    private send;
+    private fetchOnce;
+    /**
+     * Exponential with full jitter, or the server's own `Retry-After` when it
+     * sent one: a server that says "in 3 s" knows more than a formula does.
+     * Both are capped, so a header naming next Tuesday does not hang a page.
+     */
+    private delayFor;
+}
+
+/**
+ * A batch, from the customer's side.
+ *
+ *     const batch = await bakery3.batches.open({ key: 'fall-2026-v3', maxCost: 600 });
+ *     for await (const item of source) await batch.write(item);   // a full page sends itself
+ *     await batch.close();            // the tail is flushed, then sealed: the total is known
+ *     await batch.wait({ onProgress: (p) => console.log(`${p.completed}/${p.total}`) });
+ *     for await (const item of batch.items({ state: 'failed' })) console.error(item.key);
+ *
+ * Two things this class is careful about, because they are the whole reason
+ * the batch exists rather than a loop over `render()`:
+ *
+ * - Memory. `write` buffers a few KB of manifest per item and sends a page
+ *   the moment one is full, by count or by bytes, so awaiting it is the
+ *   backpressure and nothing here ever holds the catalog. (`add` and
+ *   `flush` are the same two steps taken by hand.) A refused page stays
+ *   buffered: the caller tops up and flushes again, and the same items go,
+ *   under the same keys.
+ * - One poll loop. `wait` long-polls the batch record; it never polls a
+ *   render. Items are read by state with a cursor when they are wanted.
+ */
+
+/** The slice of the client a batch drives: what a mock has to provide. */
+type BatchTransport = {
+    getBatch(id: string, options?: {
+        wait?: number;
+        signal?: AbortSignal;
+    }): Promise<BatchRecord>;
+    addBatchItems(id: string, body: BatchAddRequest): Promise<{
+        batch: BatchRecord;
+        items: BatchItemOutcome[];
+    }>;
+    listBatchItems(id: string, options?: {
+        state?: RenderState;
+        cursor?: string;
+        limit?: number;
+    }): Promise<BatchItemsPage>;
+    exportBatch(id: string): AsyncIterable<BatchExportLine>;
+    batchAction(id: string, action: 'close' | 'pause' | 'resume' | 'cancel' | 'retry'): Promise<BatchRecord>;
+};
+/**
+ * The counts, the cost and where the batch stands: what a status line
+ * prints. Flat on purpose (`p.completed`, not `p.counts.completed`).
+ */
+type BatchProgress = BatchCounts & {
+    id: string;
+    state: BatchState;
+    /** Every item ever admitted, adopted included. Final once sealed. */
+    total: number;
+    /** How many are terminal. */
+    done: number;
+    cost: BatchCost;
+    pausedReason?: string;
+};
+type FlushOptions = {
+    /** Price the pages, admit nothing: the buffer stays for a real flush. */
+    dryRun?: boolean;
+};
+type WaitOptions = {
+    /** Called after every poll that returned, whether or not the counts moved. */
+    onProgress?: (progress: BatchProgress) => void;
+    signal?: AbortSignal;
+};
+declare class Batch {
+    readonly id: string;
+    readonly key: string;
+    private latest;
+    /** The flush in flight, or the last one, settled either way. */
+    private flushing;
+    private readonly buffer;
+    /** `buffer[i]` as JSON is about `sizes[i]` bytes. Kept beside it so a
+     *  page can be closed on bytes without serializing anything twice. */
+    private readonly sizes;
+    private bytes;
+    private readonly client;
+    /** The clock `wait()` measures its patience with. A test turns it. */
+    private clock;
+    /** @internal `bakery3.batches.open()` and `.get()` make these. */
+    constructor(client: BatchTransport, record: BatchRecord);
+    /** Buffer an item. Nothing is sent until `flush()`. */
+    add(item: BatchItemRequest): this;
+    /**
+     * `add`, and send a page when one is full. Awaiting it is the
+     * backpressure: a loop over a file, a cursor or a generator of any length
+     * holds one page at most.
+     *
+     *     for await (const item of source) await batch.write(item);
+     *     await batch.close();
+     */
+    write(item: BatchItemRequest): Promise<void>;
+    /** Items added and not yet sent. */
+    get buffered(): number;
+    /** About how many bytes of JSON those items are. */
+    get bufferedBytes(): number;
+    /**
+     * Price items without buffering or admitting them: the estimate, the
+     * maximum and any refusal, per item, in the order given. Paged like a
+     * flush. An item already completed under its key is quoted as adopted, at
+     * nothing, which makes this the price of a re-run too.
+     */
+    quote(items: BatchItemRequest[]): Promise<BatchItemOutcome[]>;
+    /**
+     * Send the buffer in pages: `BATCH_PAGE_SIZE` items or `BATCH_PAGE_BYTES`
+     * of JSON, whichever a page reaches first.
+     *
+     * Returns one outcome per item sent: admitted, adopted, or refused alone
+     * (`outcome.error`). A page refused whole throws `BatchPageRefused` and
+     * leaves that page and everything behind it in the buffer, so the caller
+     * can top up and call `flush()` again; the error carries the outcomes of
+     * the pages that did get through.
+     */
+    flush(options?: FlushOptions): Promise<BatchItemOutcome[]>;
+    private flushNow;
+    /** Seal: no more items. `completed` fires once the last one is terminal.
+     *  Anything still buffered is flushed first, because closing over unsent
+     *  items would quietly drop the tail of a catalog. */
+    close(): Promise<BatchRecord>;
+    /** Stop feeding the queue; running items finish. */
+    pause(): Promise<BatchRecord>;
+    resume(): Promise<BatchRecord>;
+    /** Cancel every non-terminal item. What completed stays completed: it rendered. */
+    cancel(): Promise<BatchRecord>;
+    /** Re-queue every dead-lettered item, one new attempt each. */
+    retry(): Promise<BatchRecord>;
+    /** The latest record this batch has seen. No request. */
+    record(): BatchRecord;
+    /** Fetch the record now. */
+    refresh(): Promise<BatchRecord>;
+    /** Counts and cost from the latest record. No request. */
+    progress(): BatchProgress;
+    /**
+     * Wait for the batch to finish: one long-poll loop on the batch record
+     * until it is `completed` or `cancelled` (or sealed with every item
+     * terminal). Never a poll per render.
+     *
+     * A paused batch is waited on, not given up on (someone may resume it from
+     * the console), and `onProgress` sees `pausedReason` meanwhile. Pass
+     * `signal` to stop waiting; the batch itself is untouched.
+     *
+     * A fault that clears is ridden out. One that does not (five minutes with
+     * not one poll through) rejects with an error that says so and carries the
+     * last fault's code. The batch renders on regardless, and `wait()` can be
+     * called again.
+     */
+    wait(options?: WaitOptions): Promise<BatchRecord>;
+    /** Every item, or every item in one state, walked with the cursor. */
+    items(options?: {
+        state?: RenderState;
+    }): AsyncIterable<BatchItemRecord>;
+    /** The ledger, line by line, as the server streams it. */
+    export(): AsyncIterable<BatchExportLine>;
+    private apply;
+}
+
+/**
+ * A set of pictures: what every many-pictures call hands back.
+ *
+ * `render({ cameras })` and `renderVariants()` in the browser, and
+ * `renderBatch()` from Node, all record into a batch and return one of
+ * these, so a set of three and a catalog of six thousand are the same object
+ * with the same guarantees: one ceiling for all of it, one poll for all of
+ * it, results walked a page at a time and never held.
+ *
+ * No three.js here: the server entry imports this file.
+ */
+
+/** One finished picture of a set. */
+type RenderSetImage = {
+    /** The item's key: `variant/finish/camera`, as recorded. */
+    key: string;
+    /** The render's id. */
+    id: string;
+    variant?: string;
+    finish?: string;
+    camera?: string;
+    /** The shot this is, for a set recorded with shots. */
+    shot?: string;
+    /** `'video'` when the url is a clip. */
+    kind?: 'image' | 'video';
+    /** Signed and expiring. Copy the bytes; do not serve from it. */
+    url: string;
+    width: number;
+    height: number;
+    /** What this picture cost. Nothing, when it was adopted from an earlier run. */
+    cost: number;
+    metadata?: Record<string, unknown>;
+    result: RenderResult;
+};
+/** One picture that did not render, and why. */
+type RenderSetFailure = {
+    key: string;
+    id: string;
+    variant?: string;
+    finish?: string;
+    camera?: string;
+    shot?: string;
+    error: Bakery3Error;
+    metadata?: Record<string, unknown>;
+};
+/** One picture turned down when it was submitted: it has no render and never will. */
+type RenderSetRefusal = {
+    key: string;
+    variant?: string;
+    finish?: string;
+    camera?: string;
+    shot?: string;
+    error: RenderError;
+};
+/** What a recording did, in numbers small enough to keep. */
+type Recorded = {
+    variants: number;
+    images: number;
+    /** Already rendered under their keys in an earlier run. Cost nothing. */
+    adopted: number;
+    /** Turned down alone at admission (a spec that does not parse, an item over its own ceiling). */
+    refused: number;
+    /** The first of those, with their reasons. Capped, because a broken pipeline refuses every item. */
+    refusals: RenderSetRefusal[];
+};
+/** What a whole run would cost, from `quoteVariants()`. Nothing was admitted. */
+type VariantsQuote = Recorded & {
+    /** Σ estimate over the pictures that would render. */
+    estimated: number;
+    /** Σ maximum: what admission would reserve, and the number to set `maxCost` from. */
+    maximum: number;
+};
+declare class RenderSet {
+    /** The batch underneath: pause, resume, retry, the export. */
+    readonly batch: Batch;
+    readonly id: string;
+    readonly key: string;
+    /** What the call that made this set recorded. Empty for a set fetched by id. */
+    readonly recorded: Recorded;
+    /** Item key → position, for a set small enough to have asked for an order. */
+    private order?;
+    constructor(batch: Batch, recorded?: Recorded);
+    /** Counts and cost from the latest record. No request. */
+    progress(): BatchProgress;
+    /**
+     * Until every picture is terminal. One long-poll on the set, however many
+     * pictures it has. Resolves with the final counts: pictures that failed
+     * are in `failures()`, they do not reject the wait.
+     */
+    wait(options?: WaitOptions): Promise<BatchProgress>;
+    /**
+     * Every finished picture, a page at a time. Safe on a set of any size,
+     * and safe to call before the set is done: it walks what has completed
+     * so far.
+     */
+    images(): AsyncIterable<RenderSetImage>;
+    /**
+     * Every picture that did not render, with the reason and the fix.
+     * `error.retryable` tells the two kinds apart: false is a refusal, the
+     * scene's fault and the same next time; true ran out of attempts on a
+     * fault of ours, and `set.batch.retry()` queues it again.
+     */
+    failures(): AsyncIterable<RenderSetFailure>;
+    /**
+     * Wait, then every picture in one array, in camera order for a
+     * `render({ cameras })`: one picture per camera, or a rejection. Rejects
+     * with `RenderSetRefused` when a picture was turned down at submission
+     * (it has no render, and the array would be one short with every later
+     * picture in the wrong place), and otherwise with the first failure, as
+     * `job.result()` does. The pictures that did render are still there:
+     * walk `images()`, each named by its `camera`.
+     *
+     * It collects, so it is for a handful of pictures. For a catalog, walk
+     * `images()`.
+     */
+    result(options?: WaitOptions): Promise<RenderSetImage[]>;
+    /** Cancel every picture that has not finished. What completed, completed. */
+    cancel(): Promise<void>;
+    /** @internal */
+    ordered(keys: string[]): this;
+}
+/**
+ * Pictures of a set were turned down when they were submitted, so the set
+ * cannot give one picture per camera (or per variant) in order.
+ *
+ * `refusals` says which and why. Its `code` is the first refusal's. The
+ * pictures that were accepted render as usual: `set.images()` walks them.
+ */
+declare class RenderSetRefused extends Bakery3Error {
+    /** Which pictures, and why: the first fifty when a run refused more. */
+    readonly refusals: Array<Omit<RenderSetRefusal, 'error'> & {
+        error: Bakery3Error;
+    }>;
+    /** How many were refused in all. */
+    readonly refused: number;
+    /** How many pictures were asked for. */
+    readonly requested: number;
+    constructor(recorded: Recorded);
+}
+
+/**
+ * The test run: a few products, every camera, small and fast.
+ *
+ * Before six thousand pictures are paid for, three products are worth
+ * looking at: are the cameras where they were meant to be, is the room the
+ * right way round, does the finish list hide what it should. A test run is
+ * the real run's own options with three changes, made here so the browser
+ * and the server make the same ones:
+ *
+ * - A sample of the products. From an array: the first, the middle and the
+ *   last, because a catalog is usually sorted and its ends differ most.
+ *   From anything else (a generator, a cursor): the first three, since a
+ *   list that is never collected has no middle to ask for.
+ * - Preview quality at a small size, the long edge 512 unless told
+ *   otherwise, the aspect kept, so the framing is the real run's framing.
+ * - Its own keys. A test is looked at and thrown away; if it shared the real
+ *   run's keys, the real run would adopt these little previews as finished
+ *   pictures. Every test also differs from the last one, so a test after a
+ *   fix shows the fix and not yesterday's frame.
+ *
+ * No three.js here: the server entry imports this file.
+ */
+
+type TestRunOptions = {
+    /** How many products. Default 3. */
+    products?: number;
+    /** The long edge of each picture, in pixels. Default 512. */
+    size?: number;
+    /** The ceiling for the test, in dollars. Default 5. */
+    maxCost?: number;
+};
+
+export { type AssetImportKind as A, type BatchProgress as B, type CostEstimate as C, type RenderError as D, type BakeRecord as E, type FlushOptions as F, type BakeResult as G, type ClientOptions as H, type Bakery3ErrorCode as I, type BatchAction as J, type BatchCost as K, type BatchCounts as L, type BatchState as M, type BudgetedKind as N, type ClientAuth as O, type MintedToken as P, type RenderBudgetInit as Q, type Recorded as R, type RenderSetRefusal as S, type TestRunOptions as T, RenderSetRefused as U, type VariantsQuote as V, type WebhookPayload as W, type BatchRecord as a, Batch as b, Bakery3Error as c, Bakery3Client as d, type RenderRecord as e, type BatchOpenRequest as f, type AssetImportResponse as g, type AssetDeleteResponse as h, type RetryPolicy as i, RenderSet as j, type BatchAddRequest as k, type BatchAddResponse as l, type BatchExportLine as m, type BatchItemOutcome as n, type BatchItemRecord as o, type BatchItemRequest as p, type BatchItemsPage as q, BatchPageRefused as r, type RenderSetFailure as s, type RenderSetImage as t, type WaitOptions as u, type RenderResult as v, type TokenProvider as w, RenderBudgetExceeded as x, type AssetDescriptor as y, type RenderState as z };