@oeave/bakery3 0.0.0-stage → 0.1.0

package/dist/node/index.d.ts

@@ -0,0 +1,576 @@
+import { Q as QualityPreset, O as OutputSpec, R as RenderSpec, C as ColorSpec } from '../bake-DaOlenyx.js';
+export { F as FrameSequenceIndex } from '../bake-DaOlenyx.js';
+import { B as BatchProgress, R as Recorded, c as Bakery3Error, W as WebhookPayload, d as Bakery3Client, e as RenderRecord, C as CostEstimate, f as BatchOpenRequest, b as Batch, A as AssetImportKind, g as AssetImportResponse, h as RetryPolicy, i as RenderSet, T as TestRunOptions } from '../testRun-BIPXaVPb.js';
+export { j as BatchAddRequest, k as BatchAddResponse, l as BatchExportLine, m as BatchItemOutcome, n as BatchItemRecord, o as BatchItemRequest, p as BatchItemsPage, q as BatchPageRefused, a as BatchRecord, F as FlushOptions, r as RenderSetFailure, s as RenderSetImage, t as WaitOptions } from '../testRun-BIPXaVPb.js';
+import { H as HdriPresetName } from '../catalog.gen-BM-aNf7n.js';
+import { R as RoomPresetName, a as RoomPresetLighting } from '../rooms.gen-vhj6sFW5.js';
+import '../animation-B1h0Ryvj.js';
+
+/**
+ * Cameras without a scene graph: where to stand to photograph a box.
+ *
+ * In the browser a camera is an object the developer placed. From a server
+ * there is a model's bounds (`GlbFacts.bounds`, read at import) and nothing
+ * else, so a view is described the way a photographer would: from which
+ * side, how high, how tight. `framedCamera` turns that into the same
+ * `CameraSpec` a captured camera becomes.
+ *
+ * No three.js here: the server entry imports this file.
+ */
+
+/** Where to look from: degrees around the model from its front (+Z, where glTF says a model faces) toward its right (+X), and degrees above the horizon. */
+type Angle = {
+    azimuthDeg: number;
+    elevationDeg?: number;
+};
+/** The framings with names. */
+declare const VIEW_WORDS: {
+    readonly front: {
+        readonly azimuthDeg: 0;
+        readonly elevationDeg: 6;
+    };
+    readonly 'three-quarter': {
+        readonly azimuthDeg: 35;
+        readonly elevationDeg: 14;
+    };
+    readonly side: {
+        readonly azimuthDeg: 90;
+        readonly elevationDeg: 6;
+    };
+    readonly back: {
+        readonly azimuthDeg: 180;
+        readonly elevationDeg: 6;
+    };
+    readonly 'three-quarter-back': {
+        readonly azimuthDeg: 145;
+        readonly elevationDeg: 14;
+    };
+    readonly top: {
+        readonly azimuthDeg: 0;
+        readonly elevationDeg: 88;
+    };
+};
+type ViewWord = keyof typeof VIEW_WORDS;
+
+/**
+ * A catalog from a server: models by URL, shots per product, no browser.
+ *
+ *     import { Bakery3Server } from '@oeave/bakery3/node';
+ *     const api = new Bakery3Server(process.env.BAKERY3_SECRET_KEY!);
+ *
+ *     const run = await api.renderBatch({
+ *       key: 'fall-2026',
+ *       products: [{ id: 'chair-aria', url: 'https://cdn.shop.com/models/chair-aria.glb' }],
+ *       shots: [
+ *         'three-quarter',
+ *         { kind: 'video', from: 'three-quarter', to: 'three-quarter-back', seconds: 4 },
+ *         { id: 'low', azimuthDeg: -30, elevationDeg: 4 },
+ *       ],
+ *       room: { preset: 'loft_golden' },
+ *       maxCost: 600,
+ *     });
+ *
+ * A shot is a picture or a clip of a product from an angle: degrees around
+ * the model from its front and degrees above the horizon, or a word for one.
+ * The camera is framed from the model's own bounds, read when the model is
+ * imported, so a vase and a sofa both fill the frame from the same word and
+ * nothing is asked of the file itself. A clip is the camera carried from one
+ * angle to another over `seconds`, one framed camera per frame.
+ *
+ * Settings come in three layers: the run's, then a product's, then a shot's,
+ * the nearer winning. So one `room` at the top is every shot's room, a
+ * product that wants the studio instead says `room: null, environment: {…}`,
+ * and one shot in it can still be a close-up at 2048² in a jpeg.
+ *
+ * The model's bytes never pass through this process. Each URL is handed to
+ * `POST /v1/assets/import`; the service fetches it once, stores it content
+ * addressed like any upload, and answers with the hash and what the GLB says
+ * about itself. A model that did not change since the last run is not
+ * downloaded again. What this process sends is a few KB of manifest per shot.
+ *
+ * A manifest built here describes a model, cameras and light. A scene whose
+ * look lives in code exists only where that code runs, so it is recorded
+ * there, with `renderVariants()` in the page. Both kinds of item can share a
+ * batch.
+ *
+ * No three.js here.
+ */
+
+/**
+ * Where to look from: a word, or degrees. `'room'` is the framing a preset
+ * room was published with, from level or above: never looking up at the
+ * product.
+ */
+type View = ViewWord | 'room' | Angle;
+type BatchEnvironment = {
+    /** A studio or a sky from the preset library. */
+    preset?: HdriPresetName;
+    /**
+     * Or an HDRI of your own: a public https URL of a .hdr or .exr, imported
+     * like the models.
+     */
+    url?: string;
+    /** How strongly it lights the product. Default 1 (0.6 for the default studio). */
+    intensity?: number;
+    /** Turn the environment about the vertical, in degrees. */
+    rotationDeg?: number;
+};
+type BatchRoom = {
+    /** A room from the preset library. */
+    preset: RoomPresetName;
+    /** Default: the mode the room was designed under. */
+    mode?: RoomPresetLighting;
+    /**
+     * What the product stands on. `'auto'` (the default) goes by its size: the
+     * room's own pedestal for a small thing, the low plinth for a mid-sized
+     * one, the floor for furniture and anything that would overhang. `'own'`
+     * and `'floor'` say so yourself.
+     */
+    stand?: 'auto' | 'own' | 'floor';
+    /**
+     * Where the room's own camera sees the product from, in degrees from the
+     * product's front. The room is turned about the product to make it so.
+     * Default 30: a three-quarter view from the side the room is open to.
+     */
+    viewFromDeg?: number;
+};
+/**
+ * What every shot can say about how it is taken. Set on the run for all of
+ * them, on a product for its own, on a shot for that one; the nearest wins.
+ */
+type ShotSettings = {
+    /**
+     * A preset room to stand in. `null` says no room, where a wider layer had
+     * one.
+     */
+    room?: BatchRoom | null;
+    /**
+     * The light and backdrop when there is no room. Default: the
+     * `studio_small_03` preset at 0.6.
+     */
+    environment?: BatchEnvironment;
+    /**
+     * `'transparent'` (the default, with a traced shadow), a `#rrggbb`, or
+     * `'environment'`. A video has no alpha: `'transparent'` is `#f4f4f5` there
+     * (a `png-sequence` keeps it).
+     */
+    background?: 'transparent' | 'environment' | `#${string}`;
+    /** Default `'studio'`. */
+    quality?: QualityPreset;
+    /** Pixels. Default: the quality preset's long edge, square. */
+    width?: number;
+    height?: number;
+    /**
+     * `png` (the default), `jpeg` or `webp` for an image; `mp4` (the default),
+     * `webm` or `png-sequence` (every frame a PNG with alpha, in one tar) for a
+     * video.
+     */
+    format?: OutputSpec['format'];
+    /** JPEG/WebP only, 1 to 100. */
+    imageQuality?: number;
+    /**
+     * Vertical field of view in degrees. Default 30, or the room's own lens in
+     * a room.
+     */
+    fov?: number;
+    /**
+     * Room around the model, as a share of its size. Default 0.12, or 0.9 in
+     * a room.
+     */
+    margin?: number;
+    /** Frames a second, for a video. Default 30, at most 60. */
+    fps?: number;
+    /** Renderer settings beyond the quality preset. */
+    advanced?: RenderSpec['advanced'];
+    /**
+     * How the pictures are developed. Default: sRGB, ACES filmic, exposure 1
+     * (a room's own exposure in a room).
+     */
+    color?: Partial<ColorSpec>;
+};
+type ImageShot = ShotSettings & {
+    kind?: 'image';
+    /** Default: the view's word, or `az35-el14` for degrees. Ends the item's key. */
+    id?: string;
+    /** Where from. Default `'three-quarter'`, or `'room'` in a room. */
+    view?: View;
+    /**
+     * Instead of a view: a camera inside the model, by its node name, as the
+     * file has it.
+     */
+    camera?: string;
+};
+type VideoShot = ShotSettings & {
+    kind: 'video';
+    /** Default `orbit-<from>-<to>`. */
+    id?: string;
+    /** The camera is carried from here. */
+    from: View;
+    /**
+     * To here, azimuth as written: `{ azimuthDeg: 395 }` from 35 is a full
+     * turn.
+     */
+    to: View;
+    /** Default 4. At most 30. */
+    seconds?: number;
+};
+/** A word or an angle is an image from that view. */
+type Shot = ViewWord | 'room' | Angle | ImageShot | VideoShot;
+type BatchProduct = ShotSettings & {
+    /** Starts every shot's key. Stable across re-runs. */
+    id: string;
+    /** A public https URL of a binary glTF (.glb). */
+    url: string;
+    /** This product's shots, instead of the run's. */
+    shots?: Shot[];
+    /** Echoed on every shot of this product, its webhooks and the ledger. */
+    metadata?: Record<string, unknown>;
+};
+type RenderBatchProgress = BatchProgress & {
+    /** The product just recorded, or skipped. */
+    product: string;
+    /** Products recorded so far. */
+    products: number;
+    /** Shots recorded so far, clips included. */
+    images: number;
+    /** Products skipped so far. */
+    skipped: number;
+};
+/** A product left out of a run, with the reason. */
+type ProductSkip = {
+    id: string;
+    url: string;
+    error: Bakery3Error;
+};
+type RenderBatchRecorded = Recorded & {
+    /**
+     * Products whose model could not be imported or read. The run went on
+     * without them.
+     */
+    skipped: number;
+    /** The first of those, with their reasons. */
+    skips: ProductSkip[];
+};
+type RenderBatchOptions = ShotSettings & {
+    /** Names the run. The same key re-opens it while it is unfinished. */
+    key: string;
+    /** A label for the console. Default: the key. */
+    name?: string;
+    /**
+     * An array, a generator, a database cursor. Pulled as it is needed, never
+     * collected.
+     */
+    products: Iterable<BatchProduct> | AsyncIterable<BatchProduct>;
+    /**
+     * Every product's shots, unless it has its own. Default: one image,
+     * `'three-quarter'` (`'room'` in a room).
+     */
+    shots?: Shot[];
+    /**
+     * Appended to every key as `@version`. Bump it to trace again what already
+     * rendered.
+     */
+    version?: string;
+    /** The ceiling for the whole run, in USD. */
+    maxCost: number;
+    /** A ceiling per shot, in USD. A shot quoted above it is refused. */
+    maxCostPerImage?: 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 shots than the plan allows, for a gentler budget. */
+    maxParallel?: number;
+    /** Imports in flight at once. Default 4, at most 16. */
+    concurrency?: number;
+    /** Called after each product is recorded or skipped. */
+    onProgress?: (progress: RenderBatchProgress) => void;
+    /**
+     * Stops between products. What was recorded stays admitted; call again to
+     * go on.
+     */
+    signal?: AbortSignal;
+};
+type RenderBatchRecording = RenderBatchRecorded & {
+    estimated: number;
+    maximum: number;
+};
+
+/**
+ * Webhook signature verification.
+ *
+ * A webhook endpoint is a public URL that causes writes in the developer's
+ * database. Verifying is not optional, so it is one function with no options
+ * and no way to get it subtly wrong.
+ *
+ *     const event = await verifyWebhook({
+ *       body: await request.text(),
+ *       signature: request.headers.get('bakery3-signature'),
+ *       secret: process.env.BAKERY3_WEBHOOK_SECRET!,
+ *     });
+ *
+ * Pass the raw body, not a parsed and re-stringified object. Re-serializing
+ * JSON changes key order and whitespace and therefore the signature, and it
+ * is the single most common reason a correct implementation fails.
+ */
+
+/**
+ * Verify a webhook request and return its payload. Throws a `Bakery3Error`
+ * (`Unauthorized`) when the header is missing, malformed, older than five
+ * minutes, or signed with another secret.
+ */
+declare function verifyWebhook(input: {
+    /** The request body exactly as received, as text. */
+    body: string;
+    /**
+     * The `bakery3-signature` header. `headers.get()` gives `null` when the
+     * request has none, and that is refused like a bad signature.
+     */
+    signature: string | null | undefined;
+    /** The signing secret from your webhook settings. */
+    secret: string;
+    /** Test seam. Never pass this in production. */
+    now?: number;
+}): Promise<WebhookPayload>;
+
+/**
+ * @oeave/bakery3/node: the server half.
+ *
+ * The secret key lives here and only here. It never reaches a browser and is
+ * never an argument to anything in `@oeave/bakery3`. This module mints the
+ * short-lived, narrow token that goes in its place, verifies webhooks, and
+ * calls the API with the secret key for the things a browser may not do.
+ *
+ *     import { Bakery3Server } from '@oeave/bakery3/node';
+ *
+ *     const bakery3 = new Bakery3Server(process.env.BAKERY3_SECRET_KEY!);
+ *
+ *     export async function POST() {
+ *       return Response.json(
+ *         await bakery3.tokens.create({
+ *           expiresInSeconds: 300,
+ *           maxRenders: 1,
+ *           maxCost: 1,
+ *           allowedOrigins: ['https://shop.example.com'],
+ *         })
+ *       );
+ *     }
+ *
+ * That endpoint is the entire server-side integration.
+ */
+
+type BrowserTokenOptions = {
+    /**
+     * How long the token lives, in seconds. Default 300. Keep it short: a
+     * browser token is a capability handed to a page, and the shorter its life
+     * the less a leaked one is worth. Five minutes is plenty, because the
+     * browser SDK re-mints on a 401 without the developer writing anything.
+     */
+    expiresInSeconds?: number;
+    /** Hard ceiling on renders this token can start. Default 5. */
+    maxRenders?: number;
+    /** Hard ceiling on spend across all of them, in USD. Default 2. */
+    maxCost?: number;
+    /**
+     * Origins allowed to spend it. Set this in production: it is what stops a
+     * token lifted out of one page's network tab from working anywhere else.
+     */
+    allowedOrigins?: string[];
+    /** Your own user/session id. Shows up in the usage ledger for attribution. */
+    subject?: string;
+};
+type BrowserToken = {
+    /** The token itself, a `bk_pt_` string. Hand it to the browser SDK. */
+    token: string;
+    /** When it stops working, as a Unix timestamp in milliseconds. */
+    expiresAt: number;
+    /** The project the token renders into. */
+    projectId: string;
+};
+type Bakery3ServerOptions = {
+    /** The API's base URL. Only for a self-hosted or test deployment. */
+    baseUrl?: string;
+    /** A `fetch` to use instead of the global one. */
+    fetch?: typeof fetch;
+    /** How a 429/503 is waited out. The browser SDK's defaults otherwise. */
+    retry?: RetryPolicy;
+};
+/** A run's pictures, plus which products were left out and why. */
+type RenderBatchRun = RenderSet & {
+    readonly recorded: RenderBatchRecorded;
+};
+declare class Bakery3Server {
+    readonly tokens: TokensApi;
+    readonly renders: RendersApi;
+    readonly batches: BatchesApi;
+    readonly assets: AssetsApi;
+    private readonly secretKey;
+    private readonly options;
+    private transport;
+    /**
+     * @param secretKey Your `bk_sk_` key, as a string, from a server-only
+     *   environment variable. Not the browser SDK's `{ apiKey }` object.
+     *
+     * The key is checked on the first request, not here. A route module that
+     * builds its client at the top level is evaluated by `next build`, often
+     * where the server's secrets are not set, and a constructor that threw
+     * there would fail the build over a key the build never uses.
+     */
+    constructor(secretKey: string, options?: Bakery3ServerOptions);
+    /**
+     * The same transport the browser SDK uses (one error shape, the same
+     * 429/503 backoff) with the secret key as the bearer. It has nothing to
+     * re-mint, so a 401 here is a 401. Made on first use, after the key is
+     * checked.
+     */
+    private client;
+    /**
+     * Render a catalog of models that already sit on a CDN: one call, no
+     * browser, and none of the models' bytes through this process. Needs a
+     * plan that includes imports (see https://bakery3.com/docs/catalog#plans).
+     *
+     *     const run = await api.renderBatch({
+     *       key: 'fall-2026',
+     *       products: [{ id: 'chair-aria', url: 'https://cdn.shop.com/models/chair-aria.glb' }],
+     *       shots: ['three-quarter', 'front', { kind: 'video', from: 'front', to: 'back', seconds: 4 }],
+     *       room: { preset: 'loft_golden' },
+     *       maxCost: 600,
+     *     });
+     *     await run.wait();          // or let a webhook tell you, and exit now
+     *
+     * Resolves once every product is recorded and the run is sealed. The
+     * shots render on from there; this process does not have to stay up.
+     * A product whose model cannot be imported is skipped and listed in
+     * `run.recorded.skips`, and the run goes on. Calling it again with the
+     * same `key` resumes a recording that stopped, re-downloads no model that
+     * did not change, and adopts every shot that already rendered.
+     *
+     * What a model by URL cannot carry (node materials, a shader-lit set) is
+     * recorded where that code runs; see `renderVariants()` in `@oeave/bakery3`.
+     */
+    renderBatch(options: RenderBatchOptions): Promise<RenderBatchRun>;
+    /**
+     * What `renderBatch()` would cost. The models are imported (that is how
+     * they are priced); nothing is rendered or charged.
+     */
+    quoteBatch(options: Omit<RenderBatchOptions, 'maxCost'> & {
+        maxCost?: number;
+    }): Promise<RenderBatchRecording>;
+    /**
+     * Look before paying: three products (the first, the middle and the last
+     * of an array; the first three of anything else), every shot, at preview
+     * quality and a small size, in the ordinary lane so they come back in
+     * about a minute. A clip is cut to two seconds at twelve frames. Same
+     * options as `renderBatch()`. The test run has keys of its own, so the
+     * real run never adopts these previews as finished shots.
+     *
+     *     const test = await api.testBatch(options);
+     *     for (const shot of await test.result()) console.log(shot.variant, shot.shot, shot.url);
+     */
+    testBatch(options: Omit<RenderBatchOptions, 'maxCost'> & {
+        maxCost?: number;
+    }, test?: TestRunOptions): Promise<RenderBatchRun>;
+    /**
+     * A run by id, from another process, a webhook handler, or tomorrow
+     * morning.
+     */
+    getRenderSet(id: string): Promise<RenderSet>;
+    private openRun;
+}
+declare class AssetsApi {
+    private readonly client;
+    constructor(client: () => Bakery3Client);
+    /**
+     * Have the service fetch a public https URL into the project's assets,
+     * and say what it found: the hash to put in a manifest, and for a model
+     * its triangles, bounds, cameras and anything the renderer cannot read.
+     *
+     * Secret key only, which is why it is here and not in the browser SDK.
+     * What is fetched is fenced on the service's side: https, public
+     * addresses only, no credentials, a size limit, and the file must be a
+     * model or an HDRI. An unchanged URL is answered without a download
+     * (`unchanged: true`).
+     */
+    import(url: string, options?: {
+        kind?: AssetImportKind;
+    }): Promise<AssetImportResponse>;
+}
+type Request = <T>(method: string, path: string, body?: unknown) => Promise<T>;
+declare class TokensApi {
+    private readonly request;
+    constructor(request: Request);
+    /**
+     * Mint a browser token.
+     *
+     * Everything about it is a ceiling rather than a grant: it cannot outlive
+     * its expiry, cannot start more renders than `maxRenders`, cannot spend past
+     * `maxCost`, cannot be used from an origin outside `allowedOrigins`, and
+     * cannot perform a single billing or admin operation. That last one is not
+     * a policy: those routes require a `bk_sk_` key and this is not one.
+     */
+    create(options?: BrowserTokenOptions): Promise<BrowserToken>;
+    /** Revoke a token before its expiry. */
+    revoke(token: string): Promise<void>;
+}
+declare class RendersApi {
+    private readonly request;
+    private readonly client;
+    constructor(request: Request, client: () => Bakery3Client);
+    /**
+     * Render from a manifest you already have: a batch job, a re-render, a
+     * queued webhook. The browser flow is `@oeave/bakery3`; this is the API.
+     * Repeated on a 429/503 only when `spec.idempotencyKey` makes that safe.
+     */
+    create(spec: RenderSpec): Promise<RenderRecord>;
+    /** A render's record, with its state, cost and result URLs. */
+    get(id: string): Promise<RenderRecord>;
+    /** Cancel a render that has not finished. Already terminal is a no-op. */
+    cancel(id: string): Promise<RenderRecord>;
+    /**
+     * One more attempt for a render that failed with `attemptsExhausted`.
+     * Returns the new render, linked to the old one; a render that is not in
+     * that state answers 409.
+     */
+    retry(id: string): Promise<RenderRecord>;
+    /**
+     * Delete a render now rather than when retention would: the result, the
+     * preview, and every signed URL that pointed at them. The record survives
+     * as `expired`, so the receipt is still readable. A live render is
+     * cancelled first.
+     */
+    delete(id: string): Promise<RenderRecord>;
+    /** The project's renders, newest first, a page at a time. */
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        renders: RenderRecord[];
+        cursor: string | null;
+    }>;
+    /** The quote for a spec: a likely cost and a maximum, in USD. */
+    estimate(spec: Pick<RenderSpec, 'quality' | 'output' | 'advanced'>): Promise<CostEstimate>;
+}
+/**
+ * Batches from a server: manifests you already have, added by the hundred
+ * and rendered behind one cost ceiling. `renderBatch()` builds on this.
+ *
+ *     const batch = await api.batches.open({ key: 'fall-2026-v3', lane: 'batch', maxCost: 600 });
+ *     for await (const line of readLines('manifests.jsonl')) {
+ *       const item = JSON.parse(line);
+ *       batch.add({ key: item.key, spec: item.spec, metadata: item.metadata });
+ *       if (batch.buffered >= 100) await batch.flush();
+ *     }
+ *     await batch.close();
+ *     await batch.wait({ onProgress: (p) => console.log(`${p.completed}/${p.total}`) });
+ */
+declare class BatchesApi {
+    private readonly client;
+    constructor(client: () => Bakery3Client);
+    /** Open, or re-open by key. */
+    open(request: BatchOpenRequest): Promise<Batch>;
+    /** A batch by id, with its latest counts. */
+    get(id: string): Promise<Batch>;
+}
+
+export { type Angle, Bakery3Error, Bakery3Server, type Bakery3ServerOptions, Batch, type BatchEnvironment, BatchOpenRequest, type BatchProduct, BatchProgress, type BatchRoom, type BrowserToken, type BrowserTokenOptions, CostEstimate, type ImageShot, type ProductSkip, Recorded, type RenderBatchOptions, type RenderBatchProgress, type RenderBatchRecorded, type RenderBatchRun, RenderRecord, RenderSet, RenderSpec, RetryPolicy, type Shot, type ShotSettings, TestRunOptions, type VideoShot, type View, type ViewWord, verifyWebhook };