@nodaro/sdk 2.29.0 → 2.31.0

package/dist/nodes-C2zu3uqn.d.ts

@@ -0,0 +1,1264 @@
+import { ConnectedReference, DescribedReference } from '@nodaro/shared/types';
+import { VideoCharacterReference } from '@nodaro/shared/video';
+import { ImageEditTargetResolution, ImageAspectRatio, TaskChainedEditProvider, ImageEditProvider, ModifyImageProvider, ImageResolution, ImageQuality, ImageRenderingSpeed } from '@nodaro/shared/models';
+import '@nodaro/shared/nodes';
+import { SocialSearchParams, SocialPost, SocialPlatform, SocialSearchMode } from '@nodaro/shared/social';
+import { GenerateMaskOutput, GenerateMaskRequest, VideoDepthProvider, VideoDepthModelSize, VideoDepthColormap, VideoDepthResolution } from '@nodaro/shared/media';
+import * as _nodaro_shared_scene3d from '@nodaro/shared/scene3d';
+import { Scene3DPlan, Scene3DEditOperation, Scene3DV2EditOperation, Scene3DReference, Pro3DRenderSource, Pro3DRenderEngine, Pro3DRenderQuality, Pro3DRenderStyle, Scene3DJobOutputAny, Pro3DRenderJobOutput as Pro3DRenderJobOutput$1, Pro3DRenderCapabilities, Scene3DPlanV2, Pro3DRenderQuote as Pro3DRenderQuote$1 } from '@nodaro/shared/scene3d';
+import { TopazUpscaleFactor } from '@nodaro/shared/credits';
+import { ImageToImageAttachColumn } from '@nodaro/shared/entities';
+import { N as NodaroClientCore } from './developer-apps-zSQXWmEG.js';
+import { JobsResource, JobStatusResult } from './entries/jobs.js';
+import { NodaroError } from './entries/errors.js';
+import { ModelInputAdjustment } from '@nodaro/shared/model-catalog';
+import { DirectionFields, SubjectFields } from '@nodaro/prompts/prompt-builder';
+
+/** Reuse newRevisionId for transport retries of the same immutable edit. */
+interface RetainedScene3DEditParams {
+    newRevisionId: string;
+    expectedContentHash: string;
+    operations: readonly Scene3DV2EditOperation[];
+    lockedObjectIds?: readonly string[];
+}
+interface RetainedScene3DEditResult {
+    scenePlan: Scene3DPlanV2;
+    changeSummary: string;
+}
+/**
+ * The kind of bytes a delivery descriptor names, and the usage it is pinned under.
+ *
+ * PAIRED, not two free enums: the platform refuses a pin whose usage is not the one its kind is
+ * defined to have, and a client that checks only one of the two would accept a mis-pinned
+ * artifact the server would then refuse. {@link SCENE3D_DELIVERY_ASSET_USAGE} is the map both
+ * halves are read from.
+ */
+declare const SCENE3D_DELIVERY_ASSET_USAGE: {
+    readonly poster: "poster";
+    readonly "validation-report": "validation";
+    readonly "shot-still": "shot-still";
+    /** The recipe a run that never compiled was refused for. See {@link Scene3DDeliveryAsset}. */
+    readonly "source-json": "checkpoint";
+};
+type Scene3DDeliveryAssetKind = keyof typeof SCENE3D_DELIVERY_ASSET_USAGE;
+/**
+ * One artifact a delivery pins, as a descriptor: opaque ids and digests only.
+ *
+ * Four kinds, and two of them are conditional:
+ *
+ * - `poster` and `validation-report` are on every delivery;
+ * - `shot-still` appears once per shot on a render that produced a contact sheet, and carries
+ *   its own shot identity (`shotIndex`, `frame`, and the frame size);
+ * - `source-json` appears on ONE shape only — a `refused-authoring` delivery, published by a
+ *   3D Render Pro run whose recipe the compiler refused on every pass. It is the planner's last
+ *   admitted recipe, and it is the only thing such a run leaves that names what was attempted.
+ *   Reading it needs `edit` on the job's workflow (the same access the `.blend` export costs);
+ *   a reader with less simply does not see the descriptor.
+ */
+interface Scene3DDeliveryAsset {
+    assetId: string;
+    kind: Scene3DDeliveryAssetKind;
+    usage: (typeof SCENE3D_DELIVERY_ASSET_USAGE)[Scene3DDeliveryAssetKind];
+    byteLength: number;
+    sha256: string;
+    viaRevisionId: string | null;
+    /** Set on a `shot-still` and absent on every other kind — never `null`. */
+    shotIndex?: number;
+    frame?: number;
+    width?: number;
+    height?: number;
+}
+/** Export evidence is retained separately from the immutable scene it rendered. */
+interface Scene3DDelivery {
+    deliveryId: string;
+    /**
+     * Null on a `refused-authoring` delivery and on that alone.
+     *
+     * A Pro run whose recipe the compiler refused on every pass still retains the refusal
+     * report, but nothing was ever compiled, so no scene revision was published. The field is
+     * null rather than absent so the shape stays one shape; read `sourceKind` to tell why.
+     */
+    sceneRevisionId: string | null;
+    /**
+     * What this delivery was made from. Absent when read from a deployment that predates the
+     * refused lane, where every delivery necessarily had a scene behind it.
+     */
+    sourceKind?: "retained-revision" | "job-output" | "refused-authoring";
+    /** Null when there is no plan to hash — see `sceneRevisionId`. */
+    sourcePlanSha256: string | null;
+    sourceContentHash: string | null;
+    sourceJobId: string | null;
+    workflowId: string | null;
+    mode: "authored" | "render-only";
+    createdAt: string;
+    access: "view" | "edit" | "own";
+    assets: Scene3DDeliveryAsset[];
+}
+type Scene3DAuthoringEngine = "basic" | "blender-cloud" | "blender-local";
+interface Scene3DCapabilities {
+    basic: {
+        available: boolean;
+        sceneSchemaVersions: number[];
+    };
+    advanced: null | {
+        version: string;
+        engines: Array<Exclude<Scene3DAuthoringEngine, "basic">>;
+        sceneSchemaVersions: number[];
+        maxRepairPasses: number;
+    };
+    /**
+     * What this deployment can serve for `pro-3d-render`, including which
+     * quality profiles, engines and aspect ratios a client may OFFER. Optional so
+     * a client of this version reads an older backend without throwing; absent
+     * means the node is unavailable.
+     */
+    pro?: Pro3DRenderCapabilities;
+}
+interface Scene3DEngineParams {
+    /** Basic is the default. Discover optional engines through scene3d.capabilities(). */
+    engine?: Scene3DAuthoringEngine;
+    acceptedSceneSchemaVersions?: readonly number[];
+    localConnectionId?: string;
+    quoteId?: string;
+    maxRepairPasses?: number;
+}
+/** Structured authoring inputs; reference roles are interpreted by the platform. */
+interface GenerateScene3DParams extends Record<string, unknown>, Scene3DEngineParams, GenerationSessionParams {
+    /** Existing GLBs selected by immutable revision/artifact IDs. Requires an import-capable advanced engine. */
+    inputAssets?: readonly _nodaro_shared_scene3d.Scene3DInputAsset[];
+    prompt: string;
+    durationSeconds?: number;
+    fps?: number;
+    aspectRatio?: string;
+    references?: readonly Scene3DReference[];
+    llmModel?: string;
+    reasoningEffort?: string;
+    workflowId?: string;
+    nodeId?: string;
+}
+/** Editing creates a new revision and never mutates the supplied scene. */
+interface EditScene3DParams extends Record<string, unknown>, Scene3DEngineParams, GenerationSessionParams {
+    scenePlan: Scene3DPlan;
+    expectedRevisionId: string;
+    /** Replace the complete reference set, including clearing it with an empty list. Default: merge by id. */
+    replaceReferences?: boolean;
+    /** Supply an instruction or deterministic operations, never both. */
+    prompt?: string;
+    operations?: readonly (Scene3DEditOperation | Scene3DV2EditOperation)[];
+    references?: readonly Scene3DReference[];
+    lockedObjectIds?: readonly string[];
+    selectedObjectIds?: readonly string[];
+    llmModel?: string;
+    reasoningEffort?: string;
+    workflowId?: string;
+    nodeId?: string;
+}
+/**
+ * 3D Render Pro — ONE durable operation producing a composition and its MP4.
+ *
+ * `source` is a strict discriminated union, not a bag of optionals:
+ *  - `{kind:'prompt', prompt, references?}` authors a new scene;
+ *  - `{kind:'scene', revisionId, sourceJobId}` with NO `editPrompt` is the
+ *    render-only export — it spends no authoring or build credits, and OMIT
+ *    the field rather than sending `""`, which would buy an authoring pass;
+ *  - `{kind:'local-export', exportId, connectionId}` uses a paired desktop.
+ *
+ * There is no model or effort field: the planner is fixed and server-owned.
+ *
+ * `durationSeconds` / `fps` / `aspectRatio` on a `scene` source are an EXPLICIT
+ * re-time request. Omit them to keep the source's own timing; a conflicting
+ * override is rejected rather than silently applied.
+ */
+interface Pro3DRenderParams extends Record<string, unknown> {
+    source: Pro3DRenderSource;
+    /** Optional. An unknown or unavailable engine is rejected, never downgraded. */
+    engine?: Pro3DRenderEngine;
+    /** Names a paired desktop for a local run. */
+    localConnectionId?: string;
+    durationSeconds?: number;
+    fps?: number;
+    aspectRatio?: string;
+    quality?: Pro3DRenderQuality;
+    style?: Pro3DRenderStyle;
+    /** Correction budget, 0-2. Each pass is paid work. */
+    maxRepairPasses?: number;
+    /**
+     * Which scene-schema versions THIS client can render. A prompt or
+     * local-export source mints v2, so omitting 2 is refused for free; a scene
+     * source inherits its revision's version and is left to the server.
+     */
+    acceptedSceneSchemaVersions?: readonly number[];
+    workflowId?: string;
+    nodeId?: string;
+    /** Keep every artifact of this run out of publicly-readable storage. */
+    forcePrivate?: boolean;
+}
+/** A run additionally carries the quote it was priced under. */
+interface Pro3DRenderRunParams extends Pro3DRenderParams {
+    quoteId: string;
+}
+/** The quote's answer. `maxCredits` is a ceiling; quoting spends nothing. */
+type Pro3DRenderQuote = Readonly<Pro3DRenderQuote$1> & Readonly<Record<string, unknown>>;
+/** Per-call transport controls for the paid run. */
+interface Pro3DRenderRunOptions {
+    /**
+     * The `Idempotency-Key` the run is submitted under. Reuse the same value when
+     * retrying a call that timed out, so the run is not started twice; the SDK
+     * generates a fresh one per call when this is omitted, because two deliberate
+     * calls are two runs.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Render the exact scene revision through the existing render-video node.
+ *
+ * The price follows the plan's OWN `width`/`height`, not any node setting: a
+ * frame up to 1920 px on its longest side settles under `render-video`, a
+ * larger one under `render-video:3d-large` (1.5x) or, above 5.12 megapixels,
+ * `render-video:3d-xlarge` (2.5x). Read the current numbers from the
+ * model-cost API for those three identifiers.
+ */
+interface RenderScene3DParams extends Record<string, unknown>, GenerationSessionParams {
+    planType: "3d-scene";
+    plan: Scene3DPlan;
+    workflowId?: string;
+    nodeId?: string;
+}
+/**
+ * Preserve the shared wire contract while allowing additive job metadata.
+ *
+ * A scene authored by an ADVANCED engine additionally reports what the run knows about its own
+ * answer, every field optional and all of them absent on the deterministic Basic lane:
+ * `validation.warnings[]` entries coded `SCENE_AUTHORING_ASSUMPTION` (the planner's
+ * assumptions), `metadata.summary` (its description of what it authored), `repairPasses`
+ * (repairs actually run — `0` when the scene was accepted first time), `admissionRetries`
+ * (pre-build planner retries, which spend no repair pass), `mechanicalPasses` (repairs the engine
+ * applied from the compiler's own remedy with no planner call, counted APART from `repairPasses`
+ * on their own quoted allowance, each with a `REMEDY_AUTO_APPLIED` warning) and
+ * `restoredAssertions` (mandatory assertions put back after a planner answer re-shaped one the
+ * feedback had not named, each a `ASSERTION_RESTORED` warning).
+ *
+ * A scene that passed every mandatory assertion but did not get the visual reviewer's approval
+ * is delivered anyway, and `metadata.review` carries a verdict saying why. `verdict: "refused"`
+ * is the ADVISORY delivery — the reviewer objected once the repair budget was spent — with one
+ * `SCENE_REVIEW_REFUSED` warning per objection. `verdict: "unavailable"` is the UNREVIEWED
+ * delivery: the review produced no usable verdict after `attempts` asks — `reason: "provider"`
+ * when it never reached its provider, `"unusable"` when the provider answered with nothing usable
+ * (`Scene3DReviewUnavailableReason` in `@nodaro/shared`) — so nobody judged the scene, and
+ * `validation.warnings[]` LEADS with `SCENE_REVIEW_UNAVAILABLE` (any objections under it came from
+ * review batches that answered usably first, and are not the whole verdict).
+ *
+ * `validation.status` stays `"passed"` on both, so `metadata.review` being present is the only
+ * reliable test — use `scene3DReviewVerdictOf` from `@nodaro/shared` rather than reading it by
+ * hand, and `scene3DReviewNote` rather than writing the sentence yourself: a message that says
+ * the reviewer refused a scene nobody reviewed invents an opinion.
+ */
+type Scene3DJobOutput = Readonly<Scene3DJobOutputAny> & Readonly<Record<string, unknown>>;
+/**
+ * The settled 3D Render Pro result, plus any additive job metadata.
+ *
+ * On a run that AUTHORED, the result reports the run's own account of its answer:
+ * `validation.warnings[]` entries coded `SCENE_AUTHORING_ASSUMPTION`, `metadata.summary`,
+ * `repairPasses` (`0` when accepted first time), `admissionRetries` (pre-build planner retries,
+ * which spend no repair pass), `mechanicalPasses` (repairs the engine authored itself from the
+ * compiler's own remedy, counted APART from `repairPasses` because they buy their own quoted
+ * allowance rather than spending one of your repairs) and `restoredAssertions`. A render-only
+ * export authored nothing, so it carries no summary and omits the counts rather than claiming `0`.
+ *
+ * The one case where `mechanicalPasses` IS a subset of `repairPasses` is a run quoted before that
+ * allowance existed — its quote carries no `mechanical` line. The discriminant is the quote, not
+ * the result, so read the quote you were given rather than deriving it from the two counts.
+ *
+ * A completed result may also be published without the visual reviewer's approval, and then
+ * `metadata.review` holds a verdict saying which way. `{ verdict: "refused", objections[],
+ * observed? }` is the ADVISORY delivery: every mandatory assertion passed, the reviewer still
+ * objected, and the scene was published once the repair budget was spent, with one
+ * `SCENE_REVIEW_REFUSED` warning per objection. `{ verdict: "unavailable", reason, attempts,
+ * objections[], observed? }` is the UNREVIEWED delivery: the review produced no usable verdict in
+ * `attempts` asks — `reason: "provider"` when it never reached its provider, `"unusable"` when the
+ * provider answered with nothing usable — so the assertion-passing scene was delivered with no
+ * verdict on it and `validation.warnings[]` LEADS with `SCENE_REVIEW_UNAVAILABLE`. Objections on
+ * that arm are whatever review batches answered usably first — real, but not the whole verdict.
+ *
+ * `validation.status` is `"passed"` on both, so test for `metadata.review` — via
+ * `scene3DReviewVerdictOf` from `@nodaro/shared` — rather than for the status or the warnings,
+ * and render it with `scene3DReviewNote` rather than assuming a refusal.
+ */
+type Pro3DRenderJobOutput = Readonly<Pro3DRenderJobOutput$1> & Readonly<Record<string, unknown>>;
+
+/**
+ * Typed request bodies and results for the image routes beside
+ * `generate-image`: `image-to-image`, `edit-image`, `split-image` and
+ * `generate-mask` — the overloads live on `NodesResource.run` / `runAndWait`.
+ *
+ * Every vocabulary is the platform's own (`@nodaro/shared`), never a copy:
+ * the route Zod enums are built from the same tuples. The field lists are held
+ * to the route bodies by `backend/src/routes/__tests__/sdk-image-params-contract.test.ts`.
+ */
+
+/**
+ * What `nodes.run("image-to-image" | "edit-image" | "generate-mask", …)`
+ * answers: the job it started. Wait for it with `runAndWait` (or poll
+ * `jobs.getStatus(jobId)`).
+ */
+type ImageJobStarted = {
+    jobId: string;
+    /** Parameters the server corrected for the chosen model (an aspect ratio it does not draw, …); the run used the corrected values. */
+    adjustments?: RunNodeAdjustment[];
+    [k: string]: unknown;
+};
+/**
+ * Typed request body for `nodes.run("image-to-image", …)` / `runAndWait` —
+ * restyle or edit one image with a prompt (`POST /v1/image-to-image`). The
+ * completed job writes `imageUrl`. (`modify-image` runs through this route.)
+ *
+ * Levers a model does not take are corrected to one it does, and reported in
+ * the answer's `adjustments` — never rejected. Any other route field passes
+ * through.
+ */
+interface ImageToImageParams extends GenerationSessionParams {
+    /** The source image — a public http(s) URL. */
+    imageUrl: string;
+    prompt: string;
+    /** The prompt as your user typed it, when `prompt` is a version your app expanded. Stored on the job; never sent to the model. */
+    userPrompt?: string;
+    /** Omitted: the platform's default edit model for the requested `aspectRatio`. */
+    provider?: ModifyImageProvider;
+    /** Extra reference images, up to 13. On models priced per reference, `imageUrl` counts as one. */
+    referenceImageUrls?: string[];
+    resolution?: ImageResolution;
+    quality?: ImageQuality;
+    /** 0–1: how far the result may move from the source (taken by the models in `I2I_STRENGTH_SUPPORT`). */
+    strength?: number;
+    /** `"auto"` on a model without a native auto keeps the source image's shape (the model's nearest ratio). */
+    aspectRatio?: ImageAspectRatio;
+    /** Up to 5,000 characters. */
+    negativePrompt?: string;
+    /** A whole number ≥ 0 (taken by the models in `SEED_SUPPORT`). */
+    seed?: number;
+    /** Ideogram's speed tier (the models in `RENDERING_SPEED_SUPPORT`). */
+    renderingSpeed?: ImageRenderingSpeed;
+    /** 0–30: prompt adherence (taken by the models in `GUIDANCE_SCALE_SUPPORT`). */
+    guidanceScale?: number;
+    /**
+     * Inpainting mask — white = the area to change, black = keep. Sent to the
+     * model as its own mask, so only the mask-capable image-to-image models use
+     * it (`I2I_MASK_SUPPORT`: `ideogram-edit`, `flux-fill`); others ignore it.
+     * For a mask on any image model, see `GenerateImageParams.maskUrl`.
+     */
+    maskUrl?: string;
+    /** Character Studio: the asset's one-line description (up to 1,000 characters); drafted for you when omitted on the studio path. */
+    description?: string;
+    /** Character Studio: real-life reference photos, up to 5. Used on the studio path only. */
+    realLifeRefs?: string[];
+    /** Character Studio: with `attachToColumn` and `attachName`, the result is added to this character (one of yours). */
+    attachToCharacterId?: string;
+    attachToColumn?: ImageToImageAttachColumn;
+    /** 1–200 characters. */
+    attachName?: string;
+    /** Append the character's identity description to the prompt (not on the studio path). Default `false`. */
+    injectCharacterContext?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * The fields both forms of an `edit-image` request take. See
+ * {@link EditImageParams}.
+ */
+interface EditImageCommonParams extends GenerationSessionParams {
+    /**
+     * The edit instruction. REQUIRED for `nano-banana-edit` and `grok-2-edit`
+     * (a `400 validation_error` without one); the upscalers and background
+     * removal take none.
+     */
+    prompt?: string;
+    /** The prompt as your user typed it. Stored on the job; never sent to the model. */
+    userPrompt?: string;
+    /** `topaz-image-upscale`: the factor. Wins over `targetResolution`. */
+    upscaleFactor?: TopazUpscaleFactor;
+    /** The upscalers' output tier. On `topaz-image-upscale` it maps to a factor (2K → 2, 4K and 8K → 4) when `upscaleFactor` is absent. */
+    targetResolution?: ImageEditTargetResolution;
+    /** Corrected per model; dropped for the models that take none (the upscalers, background removal, the Grok task ops). */
+    aspectRatio?: ImageAspectRatio;
+    /** Up to 5,000 characters. */
+    negativePrompt?: string;
+    /** Up to 500 characters. */
+    style?: string;
+    /** A whole number ≥ 0. */
+    seed?: number;
+    /** Up to 13. */
+    referenceImageUrls?: string[];
+    /** Inpainting mask, passed to the model as its mask; a model that takes none ignores it. */
+    maskUrl?: string;
+    [k: string]: unknown;
+}
+/** An `edit-image` request on an image URL — every provider but the Grok task ops. */
+interface EditImageFromUrlParams extends EditImageCommonParams {
+    /** The image to edit — a public http(s) URL. */
+    imageUrl: string;
+    /** Default `recraft-upscale`. */
+    provider?: Exclude<ImageEditProvider, TaskChainedEditProvider>;
+    taskId?: never;
+}
+/**
+ * An `edit-image` request on a prior Grok generation — `grok-upscale`,
+ * `grok-2-edit`, `grok-2-segment` take that generation's task id instead of an
+ * image URL (`TASK_CHAINED_EDIT_PROVIDER_IDS`).
+ */
+interface EditImageFromTaskParams extends EditImageCommonParams {
+    /** The prior Grok generation's task id — its job's `output_data.kieTaskId`. 1–200 characters. */
+    taskId: string;
+    provider: TaskChainedEditProvider;
+    imageUrl?: never;
+    /**
+     * `grok-2-edit` only: limit the edit to these segments — the `index` values
+     * a `grok-2-segment` run returned, passed through as they are. 1–64 whole
+     * numbers ≥ 0.
+     */
+    maskIndexes?: number[];
+}
+/**
+ * Typed request body for `nodes.run("edit-image", …)` / `runAndWait` —
+ * upscale, remove the background, or prompt-edit (`POST /v1/edit-image`).
+ * Exactly one source: `imageUrl` for every provider except the Grok task ops,
+ * which take `taskId` (and must name their `provider`). The provider defaults
+ * to `recraft-upscale`. The completed job writes `imageUrl`.
+ *
+ * The union is checked when the body is typed as `EditImageParams`
+ * (`const params: EditImageParams = …` or `{ … } satisfies EditImageParams`). A
+ * body written inline that fails it falls through to the untyped
+ * `run(type: string, …)` overload, compiles, and resolves `RunNodeResult`.
+ */
+type EditImageParams = EditImageFromUrlParams | EditImageFromTaskParams;
+/**
+ * Typed request body for `nodes.run("split-image", …)` — cut one image into a
+ * grid of tiles (`POST /v1/split-image`). Free and SYNCHRONOUS: no job is
+ * created, so `runAndWait` does not apply (it would throw: the answer has no
+ * `jobId`) and there are no session fields; the answer is the tiles
+ * themselves ({@link SplitImageResult}).
+ */
+interface SplitImageParams {
+    /** The image to cut — a public http(s) URL. */
+    imageUrl: string;
+    /** Columns, 1–6. */
+    gridCols: number;
+    /** Rows, 1–6. */
+    gridRows: number;
+    /**
+     * One name per tile, row by row (1–36). Must hold exactly
+     * `gridCols × gridRows` entries (`gridCols` and `gridRows` each 1–6) — a
+     * `400 validation_error` otherwise.
+     */
+    names: string[];
+    [k: string]: unknown;
+}
+/** One tile of a split — see {@link SplitImageResult}. */
+type SplitImageTile = {
+    name: string;
+    url: string;
+};
+/** What `nodes.run("split-image", …)` answers: every tile as a PNG, in `names` order. */
+type SplitImageResult = {
+    images: SplitImageTile[];
+};
+/**
+ * Typed request body for `nodes.run("generate-mask", …)` / `runAndWait` — a
+ * black-and-white mask of the subject a prompt names (`POST /v1/generate-mask`),
+ * ready for `maskUrl` on the inpainting routes. The SDK's one way to start it.
+ * The completed job writes {@link GenerateMaskJobOutput}.
+ *
+ * The fields are `@nodaro/shared`'s {@link GenerateMaskRequest} — the route's
+ * one wire contract, bounds in `GENERATE_MASK_LIMITS` — plus the session
+ * fields every job-creating request takes. Any other route field passes
+ * through.
+ */
+interface GenerateMaskParams extends GenerateMaskRequest, GenerationSessionParams {
+    [k: string]: unknown;
+}
+/**
+ * The completed `generate-mask` job's `output_data`: `@nodaro/shared`'s
+ * {@link GenerateMaskOutput} — `maskUrl`, the mask PNG (white = the subject),
+ * and `imageUrl`, the source passed through unchanged — on top of the common
+ * {@link NodeJobOutput} fields.
+ */
+type GenerateMaskJobOutput = NodeJobOutput & GenerateMaskOutput;
+
+type NodeCategory = "input" | "parameter" | "ai-image" | "ai-video" | "ai-audio" | "ai-text" | "processing" | "composition" | "trigger" | "output" | "control" | "entity" | "utility";
+type OutputType = "text" | "image" | "video" | "audio" | "data" | "none";
+/**
+ * Field shape inside a node's `inputSchema.fields[]`. Mirrors
+ * `backend/src/lib/node-registry.ts`.
+ */
+interface NodeInputField {
+    key: string;
+    type: string;
+    required?: boolean;
+    options?: string[];
+}
+interface NodeInputSchema {
+    fields: NodeInputField[];
+}
+/**
+ * A per-unit price on a node descriptor. A run of N units is charged
+ * `ceil(N × creditsPerUnit)`, rounded up once — so `GET /v1/credits/model-cost`
+ * for `identifier` (one unit, rounded up: the least a run pays) times N can come
+ * to more. `<identifier>:<N>u` is the exact price of N units; for a whole run
+ * use `POST /v1/credits/estimate-workflow`.
+ */
+interface NodeCreditRate {
+    /** The price id the rate is read from. */
+    identifier: string;
+    /** What one unit is, as a token (`"1000-frames"`: one started block of 1,000 sampled frames). */
+    unit: string;
+    /** The credits one unit adds to a run's total — exact, not rounded. */
+    creditsPerUnit: number;
+    /** The fewest units a run is charged for. */
+    minUnits: number;
+    /** `"ceil-run-total"`: the run's total is rounded up to a whole credit once, never per unit. */
+    rounding: "ceil-run-total";
+    /** The rule in words. */
+    note: string;
+}
+/**
+ * Node descriptor returned by `GET /v1/nodes` and `GET /v1/nodes/:type`.
+ * Mirrors `backend/src/lib/node-registry.ts#NodeDescriptor`.
+ */
+interface NodeDescriptor {
+    type: string;
+    label: string;
+    category: NodeCategory;
+    description: string;
+    outputType: OutputType;
+    /** The credits a run is charged, the figure on the node's Run button.
+     *  Number when fixed, string range like "10-80" when model-dependent.
+     *  Undefined when the node is free — or on editions
+     *  without a credit system (community/business omit the field entirely;
+     *  it is meaningful on Cloud only). */
+    creditCost?: number | string;
+    /** A node charged per unit of its own measure (its `creditCost` is a word
+     *  such as `"per-1000-frames"`): the charged price of one unit and how a run
+     *  rounds. Cloud only, like `creditCost`. */
+    creditRate?: NodeCreditRate;
+    /** Input fields the node exposes for user override (subset of full config). */
+    inputSchema?: NodeInputSchema;
+    /** For AI nodes: list of provider IDs supported. */
+    providers?: string[];
+    /** Capability flags such as "supports-reference-image" or "supports-end-frame". */
+    capabilities?: string[];
+    /** Hard duration ceiling in seconds (e.g. Generate Video Pro's env-configured cap). */
+    maxDurationSec?: number;
+    /** Providers whose segment-duration menu is sparse (off-menu values snap to the nearest entry). */
+    sparseProviders?: string[];
+    /** Per-provider resolution tiers, e.g. `{ "minimax-h3": ["2K", "768P"] }`. */
+    providerResolutions?: Record<string, string[]>;
+    /** Per-provider map of display resolution → the literal wire value the API expects. */
+    providerResolutionWire?: Record<string, Record<string, string>>;
+    /** Generate Video Pro: the deployed engine accepts the `soundtrack` input (original-audio replay). */
+    soundtrack?: boolean;
+}
+/**
+ * Result of a direct node execution. Most node types return `{ jobId }` and
+ * are processed asynchronously by a worker — the caller polls
+ * `client.jobs.get(jobId)` until status is `completed`/`failed`.
+ *
+ * Some node types (`meta-ads-scrape`, for one) answer synchronously and
+ * return their full result body. The shape is route-specific; consumers
+ * should branch on the presence of `jobId`.
+ */
+/**
+ * One parameter the server corrected because the chosen model does not accept
+ * the value you sent (e.g. `gpt-image-2` has no 3:2 aspect ratio). The run
+ * proceeds with the corrected value rather than failing — this is how you find
+ * out what it actually used.
+ *
+ * Re-exports `@nodaro/shared`'s `ModelInputAdjustment` — the same shape the
+ * server's `normalizeModelInput` / `resolveNormalizedImageGen` populate — under
+ * the SDK's naming convention, rather than declaring a second copy of the
+ * fields.
+ */
+type RunNodeAdjustment = ModelInputAdjustment;
+/**
+ * WHO is in the shot, as picker-catalog option ids — the `subject` field of
+ * `generate-image` (and `text-to-video`). The platform writes the wording from
+ * the ids you send; you never write prompt text for the subject. It composes
+ * with `prompt`: the subject clauses are folded in right after your prompt and
+ * ahead of any `direction`.
+ *
+ * A flat map of field → id(s):
+ * - **Keys** are the platform's own picker field names — every Person field
+ *   (`type`, `age`, `ethnicity`, `hairBase`, `lipState`, …), every Styling
+ *   field (`makeup`, `jewelry`, `outerwear`, …), and the prop keys `heldProp`,
+ *   `material` and `animal`. They and their ids come from the picker catalogs:
+ *   `pickerCatalogs.get("person")` / `get("styling")` list each dimension's
+ *   `field` with its `options[].id`; `get("held-prop")`, `get("material")` and
+ *   `get("animal")` write their `options[].id` to the catalog's `valueField`.
+ * - **Values** are one id or a list of ids. Ids past a dimension's own cap are
+ *   dropped, not rejected.
+ * - **One number:** `customAge` (years, rounded and clamped to 0–120), read only
+ *   when `age` is `"age-custom"`. A number on any other key does nothing.
+ * - **Bounds** (without `presetId`): at most 128 keys, 64 characters per key,
+ *   8 ids per key and 100 characters per id — a map over any of them is a 400
+ *   `validation_error`. Unknown keys and unknown ids within them are skipped,
+ *   and the job's `input_data.subject` records the ids that were used.
+ * - **With `presetId`** your `subject` replaces the preset's own and is folded
+ *   into the preset's prompt, as `direction` and `structured` are: an over-long
+ *   key, id or list is dropped rather than rejected, and `input_data` does not
+ *   record the subject.
+ *
+ * Same type as `@nodaro/prompts`' `SubjectFields`, under the SDK's name.
+ */
+type Subject = SubjectFields;
+/**
+ * Something you asked for that the run did not send, with why — e.g.
+ * `moodboard_images_not_sent`: some of a `moodboard:<id>` direction's images
+ * did not fit the model's reference limit after your own references. The run
+ * goes ahead; the same warnings are kept on the job's `input_data.warnings`.
+ */
+interface RunNodeWarning {
+    code: string;
+    message: string;
+}
+type RunNodeResult = {
+    jobId: string;
+    usageLogId?: string;
+    adjustments?: RunNodeAdjustment[];
+    warnings?: RunNodeWarning[];
+    [k: string]: unknown;
+} | Record<string, unknown>;
+/**
+ * Structured references — the editor's wired-reference shape — shared by
+ * `generate-image` and `generate-video`. The route assembles them server-side
+ * into per-ref `@image_N` directives and resolves `{image:N}` prompt tokens, so
+ * a direct SDK run binds inline references exactly like the canvas. Pass the
+ * same `ConnectedReference[]` the editor builds; the route dedupes + caps them
+ * to the provider's image-reference limit.
+ */
+interface StructuredReferenceParams {
+    /** Wired references assembled server-side (deduped + capped per provider). */
+    connectedReferences?: ConnectedReference[];
+    /**
+     * References you can NAME and DESCRIBE but have no media for — a cast role no
+     * entity is bound to yet, a character that exists only in the script. They
+     * carry no url, so nothing is attached and no `@image_N` seat is used: each
+     * becomes a `<Name> — <description>.` line, and a name left in the prompt
+     * prose reaches the model as a real, described subject. Up to 10.
+     */
+    describedReferences?: DescribedReference[];
+    /** Reorder the assembled reference list by stable ref ids; renumbers `@image_N`. */
+    referenceOrder?: string[];
+}
+/**
+ * Captions for a node's video / audio rail references — INDEX-ALIGNED with
+ * `referenceVideoUrls` / `referenceAudioUrls`, so `referenceVideoCaptions[0]`
+ * describes `referenceVideoUrls[0]`. Each renders as `@video_N: <caption>.` /
+ * `@audio_N: <caption>.` in the assembled prompt and is bounded by the number of
+ * rail references that actually ship, so a caption can never bind a slot the
+ * payload dropped. A blank entry is a hole in the alignment, not a line.
+ */
+interface ReferenceCaptionParams {
+    referenceVideoCaptions?: string[];
+    referenceAudioCaptions?: string[];
+}
+/**
+ * Typed request body for `nodes.run("text-to-speech", …)` / `runAndWait`.
+ * Common fields are typed; any other route field passes through.
+ */
+interface TextToSpeechParams extends GenerationSessionParams {
+    text: string;
+    /** A premade voice NAME (Rachel, George, …) or a library / custom voice id. */
+    voice?: string;
+    voiceType?: "premade" | "custom" | "library";
+    /** `elevenlabs-v4` (the default), `elevenlabs-v3`, `elevenlabs-v4-turbo`, `elevenlabs-turbo`, `elevenlabs-multilingual`. */
+    provider?: string;
+    stability?: number;
+    similarityBoost?: number;
+    style?: number;
+    speed?: number;
+    languageCode?: string;
+    /**
+     * Continuity across clips: the line spoken just BEFORE this one in the finished piece
+     * (the previous clip's text). Context, not spoken — a model that stitches (v4, Turbo, Multilingual; not v3) carries the
+     * intonation across the cut; others ignore it. Up to 1,000 characters (a 400 above, on a model that stitches).
+     */
+    previousText?: string;
+    /** The line spoken just AFTER this one. Same rule as `previousText`. */
+    nextText?: string;
+    [k: string]: unknown;
+}
+/**
+ * Fields every job-creating request accepts beside its own params, on any
+ * route: the platform stamps them on the job it creates. Typed on every
+ * generation params type.
+ */
+interface GenerationSessionParams {
+    /** A session from `client.sessions.create()` — the job is born in it and
+     *  shows in its feed. Must be one of yours (404 otherwise). */
+    sessionId?: string;
+    /** Your app's slug (`create-image`, …): stored on the job, and what
+     *  `jobs.list({ origin })` filters on. Lowercase letters, digits, dashes. */
+    origin?: string;
+}
+/**
+ * Typed request body for `nodes.run("generate-image", …)` / `runAndWait`.
+ * Common fields are typed; any other route field passes through via the index
+ * signature (the route Zod-validates the full body).
+ *
+ * `count` above 1 or `models` makes several jobs in one call: the answer is a
+ * {@link GenerateImageBatchResult}, and {@link NodesResource.runBatchAndWait}
+ * (not `runAndWait`) waits for it.
+ */
+interface GenerateImageParams extends StructuredReferenceParams, GenerationSessionParams {
+    prompt?: string;
+    /**
+     * Apply a node preset (a factory id like `"generate-image/cinematic-still"`, from
+     * `presets.listFactory("generate-image")`, or one of yours) exactly as the editor does:
+     * its prompt and pre/post text, placeholder defaults, style, negative prompt and
+     * levers. Fields you pass override it; your `prompt` is wrapped in its pre/post text.
+     */
+    presetId?: string;
+    /** Values for the preset's placeholders that have no default, e.g. `{ BRAND: "Acme" }`.
+     *  Without them such a preset answers 400 `preset_variables_required`, naming them. */
+    presetVariables?: Record<string, string>;
+    /** The prompt as your user typed it, when `prompt` is a version your app
+     *  expanded (filled-in fields, resolved references). Stored on the job as
+     *  `input_data.userPrompt` to show what the user wrote; never sent to the
+     *  model. Defaults to `prompt`. */
+    userPrompt?: string;
+    /** Pre & post text wrapped around `prompt` (a preset's words), joined the
+     *  same way every AI prompt node joins them. */
+    promptPrefix?: string;
+    promptSuffix?: string;
+    provider?: string;
+    /** How many images to make, 1–4 — each its own job, one image each, under
+     *  its own Idempotency-Key (`<key>:<i>`). With `models`, per model. */
+    count?: number;
+    /** 2–4 distinct image model ids: the same request runs on each, instead of
+     *  `provider`. models × count is at most 8. With `presetId`, the preset is
+     *  applied once per model. */
+    models?: string[];
+    /** With `count`, image i gets `seed + i` — one seed would draw the same image every time. */
+    seed?: number;
+    /** Flat reference image URLs — appended after `connectedReferences`. */
+    referenceImageUrls?: string[];
+    negativePrompt?: string;
+    /**
+     * Cinematic direction as catalog IDS — the route renders the wording. Two
+     * keys also take one of YOUR saved resources:
+     * - `colorLook: "palette:<id>"` (`paletteDirectionId(id)`) — the palette's
+     *   colours, each by an everyday name and its hex, go into the prompt;
+     * - `style: "moodboard:<id>"` (`moodboardDirectionId(id)`) — the moodboard's
+     *   description goes into the prompt and its images go to the model as style
+     *   references, after your own references and up to the model's reference
+     *   limit (the answer's `warnings` says when some did not fit). Its images
+     *   are references, so on models priced per reference the run costs what is
+     *   sent.
+     * A malformed one answers 400; one that is not yours (or was deleted) 404
+     * `direction_not_found`. The job keeps the id, so a re-run resolves it again.
+     * Not combinable with `presetId` yet (400 `validation_error`).
+     */
+    direction?: DirectionFields;
+    /**
+     * WHO is in the shot — person, styling and props as picker-catalog ids
+     * ({@link Subject}). The platform writes the wording and folds it in after
+     * `prompt`, ahead of `direction`. With `presetId`, it replaces the preset's own
+     * and is folded into the preset's prompt (over-long values dropped, not 400).
+     */
+    subject?: Subject;
+    /**
+     * The image to edit. Alone, the run is image-to-image on it (a text-to-image
+     * model runs as its image-to-image sibling); with `maskUrl`, an inpaint.
+     */
+    baseImageUrl?: string;
+    /**
+     * Inpaint mask — white = the area to change, black = keep (what
+     * `generate-mask` writes). Needs a base: `baseImageUrl`, else the first
+     * `referenceImageUrls` entry. Works on EVERY image model: the result's masked
+     * area is composited back over the base, so everything outside the mask is
+     * the base's own pixels. On the models whose `IMAGE_MASK_MODE` is `"prompt"`
+     * (`@nodaro/shared`) the masked area's position is also described in the
+     * prompt; the rest rely on the composite alone. (A model that takes the mask
+     * itself is on `image-to-image` — `I2I_MASK_SUPPORT`.)
+     */
+    maskUrl?: string;
+    /** 0–1: how far the result may move from the base (taken by the models in `I2I_STRENGTH_SUPPORT`). */
+    strength?: number;
+    /** 0–20: prompt adherence (taken by the models in `GUIDANCE_SCALE_SUPPORT`). */
+    guidanceScale?: number;
+    [k: string]: unknown;
+}
+/** One model's share of a generate-image batch. */
+interface GenerateImageBatchGroup {
+    /** The model id as requested. */
+    model: string;
+    jobIds: string[];
+    /** Credits held for this model's images; absent where nothing is charged. */
+    credits?: number;
+    /** Parameters corrected for this model, as on a single call. */
+    adjustments?: RunNodeAdjustment[];
+    /** Something asked for that was not sent on this model (e.g. a moodboard past its reference limit), as on a single call. */
+    warnings?: RunNodeWarning[];
+}
+/**
+ * What `nodes.run("generate-image", …)` answers when `count` is above 1 or
+ * `models` is set: every job, grouped by model. The whole batch was checked
+ * against the balance and created, charged and queued together — or not at
+ * all (`InsufficientCreditsError`'s `required` is then the batch's total).
+ */
+interface GenerateImageBatchResult {
+    /** The first job — so code reading the single-image answer keeps working. */
+    jobId: string;
+    /** Every job: model by model, then image by image. */
+    jobIds: string[];
+    /** On every job of the batch as `input_data.batchId`; `jobs.list({ batchId })` lists them. */
+    batchId: string;
+    groups: GenerateImageBatchGroup[];
+    /** The groups' credits summed; absent where nothing is charged. */
+    totalCredits?: number;
+    /** Every job already existed and this request charged nothing: a repeat of an earlier request with the same Idempotency-Key. */
+    deduped?: true;
+}
+/**
+ * One job of a batch once {@link NodesResource.runBatchAndWait} stops waiting
+ * for it: its output, or the typed error that ended the wait — a
+ * `JobFailedError` (failed or cancelled), `JobHeldError` (held for review) or
+ * `JobTimeoutError`. One job's error never discards the others' images.
+ */
+type BatchJobOutcome = {
+    readonly jobId: string;
+    readonly model: string;
+    readonly status: "completed";
+    readonly output: NodeJobOutput;
+} | {
+    readonly jobId: string;
+    readonly model: string;
+    readonly status: "error";
+    readonly error: NodaroError;
+};
+/** What {@link NodesResource.runBatchAndWait} resolves. */
+interface GenerateImageBatchOutput {
+    /** The submit's answer: the ids, the groups, the credits. */
+    readonly batch: GenerateImageBatchResult;
+    /** Every job, in `batch.jobIds` order. */
+    readonly results: readonly BatchJobOutcome[];
+}
+/**
+ * Typed request body for `nodes.run("generate-video", …)` / `runAndWait`.
+ * Common fields are typed; any other route field passes through.
+ */
+interface GenerateVideoParams extends StructuredReferenceParams, ReferenceCaptionParams, GenerationSessionParams {
+    prompt?: string;
+    provider?: string;
+    /** Start-frame image (image-to-video). */
+    imageUrl?: string;
+    /** Closing frame, paired with `imageUrl` on models that support one. */
+    endFrameUrl?: string;
+    referenceImageUrls?: string[];
+    referenceVideoUrls?: string[];
+    referenceAudioUrls?: string[];
+    /**
+     * Identity inputs that keep a real person's face — a portrait + description
+     * per person, up to 3. Only models with a dedicated character channel take
+     * them (Gemini Omni: `gemini-omni-video`, `gemini-omni-flash`); any other
+     * model answers `400`. Distinct from `referenceImageUrls`, which a multimodal
+     * model treats as loose context. Cannot be combined with a start frame
+     * (`imageUrl`); each character uses 1 of the model's 7 input units (2 with a
+     * `bodyImageUrl`). Adds no credit charge. Give a character a `voice` to pin one
+     * voice persona (a Gemini preset + optional description / example line) across
+     * clips — up to 3 distinct voices a request.
+     */
+    characterReferences?: VideoCharacterReference[];
+    /** How a start/end frame is reshaped before the model sees it. Default
+     *  `"resolution"`: resize it to the pixel size that model actually renders,
+     *  which is what stops the provider reshaping it mid-clip. `"ratio"` corrects
+     *  only the aspect; `"original"` sends it untouched. */
+    frameFit?: "original" | "ratio" | "resolution";
+    /** Whether the frame travels as a real start frame or as a reference image
+     *  bound in the prompt as the opening frame. Default `"auto"`, which picks per
+     *  model. Ignored by models that take no reference images. */
+    frameDelivery?: "auto" | "frame" | "reference";
+    /** Seedance Draft (`seedance-2-5` only; ignored elsewhere): render a 480p
+     *  DRAFT — it costs the same as a 480p run and any `resolution` is replaced
+     *  by 480p. Finalize the take you like with `nodes.run("video-upscale",
+     *  { provider: "seedance-2-5-hd", sourceJobId })`: the same take, frame for
+     *  frame, at 1080p. Drafts are kept about 7 days. */
+    draft?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * Typed request body for `nodes.run("text-to-video", …)` / `runAndWait` — the
+ * PROMPT-ONLY video lane (`POST /v1/text-to-video`).
+ *
+ * Which lane takes what: `text-to-video` renders from text (plus optional
+ * references) and `prompt` is REQUIRED; frames belong to `generate-video`
+ * alone, which is the image-to-video lane (`imageUrl` start frame, `endFrameUrl`
+ * closing frame) and where a prompt is optional. A model with no text-to-video
+ * mode answers this lane with a `400 image_required` naming itself.
+ *
+ * Common fields are typed; any other route field passes through.
+ */
+interface TextToVideoParams extends StructuredReferenceParams, ReferenceCaptionParams, GenerationSessionParams {
+    prompt: string;
+    provider?: string;
+    duration?: number;
+    /** Native audio toggle, on the models that render sound. */
+    sound?: boolean;
+    negativePrompt?: string;
+    aspectRatio?: string;
+    resolution?: string;
+    seed?: number;
+    referenceImageUrls?: string[];
+    referenceVideoUrls?: string[];
+    referenceAudioUrls?: string[];
+    /** Identity inputs that keep a real person's face — see {@link GenerateVideoParams.characterReferences}. */
+    characterReferences?: VideoCharacterReference[];
+    /** Cinematic direction as catalog IDS — the route renders the wording. */
+    direction?: DirectionFields;
+    /** WHO is in the shot as picker-catalog ids ({@link Subject}), folded ahead of the direction clauses. */
+    subject?: Subject;
+    /** Seedance Draft (`seedance-2-5` only; ignored elsewhere): render a 480p
+     *  DRAFT — it costs the same as a 480p run and any `resolution` is replaced
+     *  by 480p. Finalize the take you like with `nodes.run("video-upscale",
+     *  { provider: "seedance-2-5-hd", sourceJobId })`: the same take, frame for
+     *  frame, at 1080p. Drafts are kept about 7 days. */
+    draft?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * Typed request body for `nodes.run("video-upscale", …)` / `runAndWait`.
+ *
+ * - `topaz` (default): upscale any `videoUrl` by `upscaleFactor`.
+ * - `veo-1080p` / `veo-4k`: re-render a VEO generation by its `taskId`.
+ * - `seedance-2-5-hd`: finalize a Seedance 2.5 DRAFT (a `draft: true` run) —
+ *   the same take re-rendered at 1080p at the draft's own length. Name the
+ *   draft by `sourceJobId` (its job id) or `taskId` (its providerTaskId). The
+ *   price comes from the draft (its length, and whether it used a reference
+ *   video), never from this body. A foreign, unfinished or non-draft source is
+ *   refused with a 4xx before anything is charged.
+ *
+ * Any other route field passes through.
+ */
+interface VideoUpscaleParams extends GenerationSessionParams {
+    provider?: "topaz" | "veo-1080p" | "veo-4k" | "seedance-2-5-hd";
+    videoUrl?: string;
+    upscaleFactor?: "1" | "2" | "4";
+    taskId?: string;
+    sourceJobId?: string;
+    [k: string]: unknown;
+}
+/**
+ * Typed request body for `nodes.run("assemble-narrated-video", …)` / `runAndWait`.
+ * Assembles blocks of video with audio narration into a single composed video.
+ */
+interface AssembleNarratedVideoParams extends GenerationSessionParams {
+    blocks: {
+        videoUrl: string;
+        audioUrl?: string;
+    }[];
+    voiceVolume?: number;
+    clipAudioVolume?: number;
+    maxSlowdown?: number;
+    trimStartFrames?: number;
+    trimEndFrames?: number;
+    [k: string]: unknown;
+}
+/**
+ * Typed request body for `nodes.run("video-depth", …)` / `runAndWait` — turns a
+ * video into a depth video (`POST /v1/video-depth`, near is bright, far is
+ * dark). The completed job writes `videoUrl` (MP4) and `thumbnailUrl`.
+ *
+ * Two providers: `video-depth-anything` (the default, temporally consistent)
+ * honours every lever below; `depth-anything-frames` (Depth Anything per
+ * frame) takes `modelSize` and `colormap` only, and renders only `grayscale` /
+ * `inferno`. A lever the chosen provider does not take is dropped and a
+ * colormap it cannot render becomes `grayscale` — coerced, never rejected (a
+ * value outside the vocabularies below is still a `400 validation_error`).
+ *
+ * The clip is measured before any credits are reserved. Too long answers
+ * `400 video_too_long` (`video-depth-anything`: more than 2,400 frames or
+ * 300 s; `depth-anything-frames`: more than 80 s); a clip that cannot be read
+ * answers `400 video_unreadable`; a provider the deployment has turned off
+ * answers `403 model_not_available`.
+ *
+ * Common fields are typed; any other route field passes through.
+ */
+interface VideoDepthParams extends GenerationSessionParams {
+    /** The source video — a public http(s) URL. */
+    videoUrl: string;
+    /** Default `video-depth-anything`. */
+    provider?: VideoDepthProvider;
+    /** `small` / `base` / `large` (the default) — larger is more detailed and slower. */
+    modelSize?: VideoDepthModelSize;
+    /** Default `grayscale`. `depth-anything-frames` renders only `grayscale` / `inferno`. */
+    colormap?: VideoDepthColormap;
+    /** `video-depth-anything` only. Default `auto`. */
+    resolution?: VideoDepthResolution;
+    /** `video-depth-anything` only: render the original and the depth next to each other. */
+    sideBySide?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * The `output_data` shape a finalized generation job writes. Every async
+ * generation node persists one (or more) of these media URLs to
+ * `jobs.output_data` on completion — `generate-image` → `imageUrl`,
+ * `generate-video` / `combine-videos` / `merge-video-audio` / `video-upscale` /
+ * `video-depth` → `videoUrl` (+ `thumbnailUrl`), `text-to-speech` / `generate-music` →
+ * `audioUrl` (a `text-to-speech` run with `withTimestamps: true` on a model
+ * that returns timings, and every `text-to-dialogue` run on one, also carries
+ * `transcript`). Resolved by {@link NodesResource.runAndWait}. Extra fields may be
+ * present, so the index signature is open.
+ */
+/**
+ * The completed `social-search` job's `output_data`: EVERY post the search
+ * found, in the order it asked for (Social Search, Nodaro Cloud). Picking the
+ * posts a workflow passes on is an editor step; a direct caller gets them all.
+ */
+interface SocialSearchJobOutput extends NodeJobOutput {
+    readonly json: readonly SocialPost[];
+    readonly platform: SocialPlatform;
+    readonly mode: SocialSearchMode;
+    readonly query: string;
+    /** Non-fatal notes ("only part of the results could be loaded"). */
+    readonly warnings?: readonly string[];
+}
+interface NodeJobOutput {
+    /** `text-to-speech` / `generate-music` / audio nodes write here. For
+     *  `audio-separation` this is the primary stem (vocals). */
+    readonly audioUrl?: string;
+    /** `audio-separation` (Demucs) per-stem URLs. `vocalUrl`/`instrumentalUrl`
+     *  in vocal/instrumental mode; the rest in full-stems mode. */
+    readonly vocalUrl?: string;
+    readonly instrumentalUrl?: string;
+    readonly drumsUrl?: string;
+    readonly bassUrl?: string;
+    readonly otherUrl?: string;
+    readonly guitarUrl?: string;
+    readonly pianoUrl?: string;
+    /** `generate-video` / `combine-videos` / `merge-video-audio` / `video-upscale` / `video-depth` write here. */
+    readonly videoUrl?: string;
+    /** `generate-image` / `edit-image` / `extract-frame` write here. */
+    readonly imageUrl?: string;
+    /** Every image, when the job made more than one; `imageUrl` is the first. */
+    readonly imageUrls?: readonly string[];
+    /**
+     * The output's pixel size. On an image job: the size of `imageUrl` as it is
+     * stored — what you download, a free-tier watermark included — with EXIF
+     * orientation applied, so the size a browser shows. Lay a grid tile out
+     * before the image loads, or show and sort by size.
+     *
+     * Present on image jobs completed after this release (and on the jobs that
+     * always recorded it: image overlay, video overlay, video mask, mask
+     * composite). Absent when the size could not be read — never half a size.
+     */
+    readonly width?: number;
+    readonly height?: number;
+    /**
+     * Beside `imageUrls`: each image with its pixel size, index-aligned
+     * (`images[i]` is `imageUrls[i]`). Present on image jobs completed after
+     * this release when at least one size was read; an entry whose size could
+     * not be read has its `url` and no `width` / `height`.
+     */
+    readonly images?: readonly JobOutputImage[];
+    /** Poster frame for video outputs. */
+    readonly thumbnailUrl?: string;
+    readonly [k: string]: unknown;
+}
+/** One image of a job that made several — see {@link NodeJobOutput.images}. */
+interface JobOutputImage {
+    readonly url: string;
+    /** Pixel size as stored, EXIF orientation applied. Absent when it could not be read. */
+    readonly width?: number;
+    readonly height?: number;
+}
+/** Options for {@link NodesResource.runAndWait} and {@link NodesResource.runMany}. */
+interface RunAndWaitOptions {
+    /**
+     * Abort the run/poll loop. Aborting (or passing an already-aborted signal)
+     * stops polling and rejects with {@link JobAbortedError}, whose `jobId`
+     * names the job once it was submitted. Aborting stops the WAITING only: the
+     * job keeps running and is charged, unless {@link cancelOnAbort} is set.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Also cancel the job when `signal` aborts after it was submitted
+     * (`POST /v1/jobs/:id/cancel`, which refunds its credit hold). Best effort:
+     * a failed cancel still rejects with the {@link JobAbortedError}. Default
+     * `false` — aborting only stops waiting.
+     */
+    readonly cancelOnAbort?: boolean;
+    /** Called with each lean status the poll loop observes (running → terminal). */
+    readonly onProgress?: (status: JobStatusResult) => void;
+    /** Poll interval in ms. Default 2000. */
+    readonly pollMs?: number;
+    /** Wall-clock cap before giving up, in ms. Default ~15 min (900_000). */
+    readonly maxMs?: number;
+    /**
+     * `Idempotency-Key` for the submit half. Reuse the same value when retrying a
+     * call that timed out, so the run is not started or charged twice. Omitted →
+     * no key, which is the historical behaviour for every node that does not
+     * require one.
+     */
+    readonly idempotencyKey?: string;
+}
+/** Per-call transport controls for {@link NodesResource.run}. */
+interface RunNodeOptions {
+    /** `Idempotency-Key` header. See {@link RunAndWaitOptions.idempotencyKey}. */
+    readonly idempotencyKey?: string;
+}
+/** One settled result from {@link NodesResource.runMany}. */
+interface RunManyResult {
+    readonly jobId: string;
+    readonly output: NodeJobOutput;
+}
+declare class NodesResource {
+    private client;
+    /** Runs poll through `jobs`, so the client must carry that resource too. */
+    constructor(client: NodaroClientCore & {
+        readonly jobs: JobsResource;
+    });
+    /** List all known node descriptors. Server caches publicly for 5 minutes. */
+    list(): Promise<{
+        data: NodeDescriptor[];
+    }>;
+    /** Get a single node descriptor by type slug (e.g. "generate-image"). */
+    get(type: string): Promise<{
+        data: NodeDescriptor;
+    }>;
+    /**
+     * Run a single node directly without wrapping it in a workflow. Posts
+     * `params` as the request body to the node's API route. Most use
+     * `POST /v1/<type>`; the rest are listed in `NODE_RUN_ROUTES` (exported by
+     * `@nodaro/shared`): scene authoring uses `/v1/3d-scene/generate|edit`,
+     * `llm-chat` uses `/v1/llm-chat/generate`, the Suno nodes `/v1/suno/…`, the
+     * social post nodes `/v1/social/publish` (a per-platform node fills in its
+     * `platform` when you leave it out), and render-video with a planType uses
+     * `/v1/render-video/plan`.
+     *
+     * A node type with no route of its own (`NODE_TYPES_WITHOUT_RUN_ROUTE`, e.g.
+     * `modify-image`, which runs through `image-to-image`) rejects with a
+     * {@link NodaroError} of code `node_not_runnable` naming what to run
+     * instead, without calling the API. A type that runs only inside a workflow
+     * (an input, trigger, utility or parameter node such as `upload-image`)
+     * rejects the same way once the API answers that it has no such route; a
+     * 404 about a missing resource stays a `NotFoundError`.
+     *
+     * This is the SDK equivalent of the MCP server's verb tools — and the
+     * path the Nodaro CLI uses for `nodaro nodes run <type>`.
+     *
+     * Most node types are async: the response includes `{ jobId }` and the
+     * actual generation runs on a worker. Poll `client.jobs.get(jobId)` until
+     * completed. Synchronous node types (`meta-ads-scrape`, etc.) return their
+     * full result without a `jobId` field.
+     *
+     * @param type    Node type slug — must match an entry in the registry
+     *                returned by `list()` (e.g. "generate-image").
+     * @param params  Request body. Field names must match the node's
+     *                `inputSchema` (see `get(type).inputSchema`).
+     */
+    run(type: "generate-3d-scene", params: GenerateScene3DParams): Promise<RunNodeResult>;
+    run(type: "edit-3d-scene", params: EditScene3DParams): Promise<RunNodeResult>;
+    run(type: "render-video", params: RenderScene3DParams): Promise<RunNodeResult>;
+    run(type: "pro-3d-render", params: Pro3DRenderRunParams, options?: RunNodeOptions): Promise<RunNodeResult>;
+    run(type: "generate-image", params: GenerateImageParams & ({
+        count: 2 | 3 | 4;
+    } | {
+        models: string[];
+    }), options?: RunNodeOptions): Promise<GenerateImageBatchResult>;
+    run(type: "generate-image", params?: GenerateImageParams, options?: RunNodeOptions): Promise<RunNodeResult>;
+    run(type: "text-to-speech", params: TextToSpeechParams): Promise<RunNodeResult>;
+    run(type: "generate-video", params?: GenerateVideoParams): Promise<RunNodeResult>;
+    run(type: "text-to-video", params: TextToVideoParams): Promise<RunNodeResult>;
+    run(type: "video-upscale", params: VideoUpscaleParams): Promise<RunNodeResult>;
+    run(type: "assemble-narrated-video", params?: AssembleNarratedVideoParams): Promise<RunNodeResult>;
+    run(type: "social-search", params: SocialSearchParams, options?: RunNodeOptions): Promise<RunNodeResult>;
+    run(type: "video-depth", params: VideoDepthParams, options?: RunNodeOptions): Promise<RunNodeResult>;
+    run(type: "image-to-image", params: ImageToImageParams, options?: RunNodeOptions): Promise<ImageJobStarted>;
+    run(type: "edit-image", params: EditImageParams, options?: RunNodeOptions): Promise<ImageJobStarted>;
+    run(type: "generate-mask", params: GenerateMaskParams, options?: RunNodeOptions): Promise<ImageJobStarted>;
+    /** Synchronous and free: answers the tiles, no job. */
+    run(type: "split-image", params: SplitImageParams, options?: RunNodeOptions): Promise<SplitImageResult>;
+    run(type: string, params?: Record<string, unknown>, options?: RunNodeOptions): Promise<RunNodeResult>;
+    /**
+     * Run a single async node to completion: {@link run} it, extract the
+     * `{ jobId }`, then client-poll `jobs.getStatus(jobId)` every `pollMs`
+     * (default 2000) until a terminal status, up to `maxMs` (default ~15 min).
+     *
+     * Resolves the job's typed `output_data` ({@link NodeJobOutput}) on
+     * `completed`. Throws (all typed, catchable by `instanceof`):
+     * - {@link InsufficientCreditsError} / {@link StorageExceededError} etc. —
+     *   surfaced by the underlying {@link run} on 402/413/… before any poll.
+     * - {@link JobFailedError} — terminal `failed`/`cancelled` (carries the
+     *   job's `error_message` + `jobId`).
+     * - {@link JobTimeoutError} — `maxMs` deadline exceeded before terminal.
+     * - {@link JobAbortedError} — `signal` fired (or was already aborted);
+     *   polling stops immediately.
+     * - {@link JobHeldError} — the job entered `pending_review` on a deployment
+     *   that registers a job policy. Ends the poll on the FIRST held tick (that
+     *   status waits on a human, not on the job) and does NOT cancel it.
+     * - {@link JobBlockedError} — a 422 from {@link run} before any poll: the
+     *   deployment's job policy refused the request outright.
+     *
+     * Polling is fully client-side (no server function blocks) — the same model
+     * thin clients use, lifted out of their hand-rolled run→poll loops.
+     *
+     * @param type    Node type slug (e.g. "generate-video"). See {@link run}.
+     * @param params  Request body — field names match the node's `inputSchema`.
+     * @param opts    `signal` / `onProgress` / `pollMs` / `maxMs`.
+     */
+    runAndWait(type: "generate-3d-scene", params: GenerateScene3DParams, options?: RunAndWaitOptions): Promise<Scene3DJobOutput>;
+    runAndWait(type: "edit-3d-scene", params: EditScene3DParams, options?: RunAndWaitOptions): Promise<Scene3DJobOutput>;
+    runAndWait(type: "render-video", params: RenderScene3DParams, options?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "pro-3d-render", params: Pro3DRenderRunParams, options?: RunAndWaitOptions): Promise<Pro3DRenderJobOutput>;
+    runAndWait(type: "generate-image", params?: GenerateImageParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "text-to-speech", params: TextToSpeechParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "generate-video", params?: GenerateVideoParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "text-to-video", params: TextToVideoParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "video-upscale", params: VideoUpscaleParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "assemble-narrated-video", params?: AssembleNarratedVideoParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "social-search", params: SocialSearchParams, opts?: RunAndWaitOptions): Promise<SocialSearchJobOutput>;
+    runAndWait(type: "video-depth", params: VideoDepthParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "image-to-image", params: ImageToImageParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "edit-image", params: EditImageParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "generate-mask", params: GenerateMaskParams, opts?: RunAndWaitOptions): Promise<GenerateMaskJobOutput>;
+    runAndWait<T extends string>(type: T, params?: Record<string, unknown>, opts?: RunAndWaitOptions): Promise<T extends "pro-3d-render" ? Pro3DRenderJobOutput : T extends "generate-3d-scene" | "edit-3d-scene" ? Scene3DJobOutput : T extends "generate-mask" ? GenerateMaskJobOutput : NodeJobOutput>;
+    /**
+     * Run a generate-image BATCH — `count` above 1 and/or `models` — to the end:
+     * submit it once ({@link run}, with your `idempotencyKey` if any), then wait
+     * for every job at once, each the way {@link runAndWait} waits.
+     *
+     * Resolves `{ batch, results }`: the submit's answer
+     * ({@link GenerateImageBatchResult} — ids, groups by model, credits) and one
+     * {@link BatchJobOutcome} per job, in `batch.jobIds` order — its output, or the
+     * typed error that ended the wait for it. One image failing never discards the
+     * others. Rejects only before any job exists (the submit's own errors, e.g.
+     * `InsufficientCreditsError` with the batch total as `required`), and on
+     * `signal` ({@link JobAbortedError}; `cancelOnAbort` cancels every job).
+     *
+     * A request for one image is refused before anything is sent (code
+     * `not_a_batch`) — wait for it with {@link runAndWait}.
+     */
+    runBatchAndWait(type: "generate-image", params: GenerateImageParams, opts?: RunAndWaitOptions): Promise<GenerateImageBatchOutput>;
+    /**
+     * Fan out N async runs of the same node `type` to completion concurrently —
+     * the candidate-grid path (generate N stills/clips in parallel). Each runs
+     * via {@link runAndWait}; resolves once ALL settle, to an array of
+     * `{ jobId, output }` in input order. Rejects (and the rejection wins) if any
+     * single run rejects — same typed errors as {@link runAndWait}, including
+     * {@link JobHeldError} when one candidate is held for review while the
+     * others complete. A shared `signal` aborts the whole batch.
+     *
+     * @param type        Node type slug, applied to every entry.
+     * @param paramsList  One request body per candidate.
+     * @param opts        Shared `signal` / `cancelOnAbort` / `onProgress` / `pollMs` / `maxMs`.
+     */
+    runMany(type: string, paramsList: Record<string, unknown>[], opts?: RunAndWaitOptions): Promise<RunManyResult[]>;
+    /** {@link pollUntilSettled}, plus what an abort does to the job: it keeps
+     *  running unless `cancelOnAbort` asks to cancel it too, and the rejection
+     *  always names it (an abort landing mid-sleep carries no id of its own). */
+    private pollJob;
+    /** Poll an already-kicked job id until it stops moving; resolve output_data
+     *  or throw. Two non-terminal statuses end the loop: an abort, and
+     *  `pending_review` (a job policy held the output for a human — see
+     *  {@link JobHeldError}). */
+    private pollUntilSettled;
+}
+
+export { type StructuredReferenceParams as $, type AssembleNarratedVideoParams as A, type BatchJobOutcome as B, type RunAndWaitOptions as C, type RunManyResult as D, type EditImageCommonParams as E, type RunNodeAdjustment as F, type GenerateImageBatchGroup as G, type RunNodeOptions as H, type ImageJobStarted as I, type JobOutputImage as J, type RunNodeResult as K, type RunNodeWarning as L, type Scene3DAuthoringEngine as M, type NodeCategory as N, type OutputType as O, type Pro3DRenderJobOutput as P, type Scene3DCapabilities as Q, type ReferenceCaptionParams as R, SCENE3D_DELIVERY_ASSET_USAGE as S, type Scene3DDelivery as T, type Scene3DDeliveryAsset as U, type Scene3DDeliveryAssetKind as V, type Scene3DJobOutput as W, type SocialSearchJobOutput as X, type SplitImageParams as Y, type SplitImageResult as Z, type SplitImageTile as _, type EditImageFromTaskParams as a, type Subject as a0, type TextToSpeechParams as a1, type TextToVideoParams as a2, type VideoDepthParams as a3, type VideoUpscaleParams as a4, type EditImageFromUrlParams as b, type EditImageParams as c, type EditScene3DParams as d, type GenerateImageBatchOutput as e, type GenerateImageBatchResult as f, type GenerateImageParams as g, type GenerateMaskJobOutput as h, type GenerateMaskParams as i, type GenerateScene3DParams as j, type GenerateVideoParams as k, type GenerationSessionParams as l, type ImageToImageParams as m, type NodeCreditRate as n, type NodeDescriptor as o, type NodeInputField as p, type NodeInputSchema as q, type NodeJobOutput as r, NodesResource as s, type Pro3DRenderParams as t, type Pro3DRenderQuote as u, type Pro3DRenderRunOptions as v, type Pro3DRenderRunParams as w, type RenderScene3DParams as x, type RetainedScene3DEditParams as y, type RetainedScene3DEditResult as z };