@nodaro/sdk 1.1.1

package/dist/index.d.ts

@@ -0,0 +1,4047 @@
+import { GenericNode, GenericEdge, WorkflowExport, ConnectedReference, TtsProvider, EntityStyle, CharacterAspectRatio, CharacterAttachColumn, LocationAssetType, LocationAttachColumn, SurroundDirection, ObjectAssetType, ObjectAttachColumn, ObjectAspectRatio, CreatureAttachColumn, PipelineInput, PipelineStatus, PipelineMode, PipelineStageName, SubGateName, ChatEnabledStage, ProposedChange, ReduceStrategyId, ReduceMeta, Voice, VoiceLibraryParams, VoiceLibraryResponse, VoiceClone, AudioFxPreset, BrowseCommunityParams, BrowseCommunityResult, CommunityCard, CommunityFullDetail, CommunityEntityType, CloneListingResult, FavoriteListingResult, CommunityReportReason, ReportListingResult, PublishListingParams, PublishListingResult, SharedListing } from '@nodaro/shared';
+export { BrowseCommunityParams, BrowseCommunityResult, CHARACTER_ASPECT_DEFAULTS, CHARACTER_ASPECT_OPTIONS, CHARACTER_STYLES, OBJECT_ASPECT_DEFAULTS as CREATURE_ASPECT_DEFAULTS, OBJECT_ASPECT_OPTIONS as CREATURE_ASPECT_OPTIONS, CREATURE_ATTACH_COLUMNS, CharacterAspectRatio, CloneListingResult, CommunityCard, CommunityEntityType, CommunityReportReason, CommunitySort, ConnectedReference, ObjectAspectRatio as CreatureAspectRatio, CreatureAttachColumn, EntityStyle, FavoriteListingResult, GenericEdge, GenericNode, LOCATION_ASSET_TYPES, LOCATION_ATTACH_COLUMNS, LocationAssetType, LocationAttachColumn, OBJECT_ASPECT_DEFAULTS, OBJECT_ASPECT_OPTIONS, OBJECT_ASSET_TYPES, OBJECT_ATTACH_COLUMNS, ObjectAspectRatio, ObjectAssetType, ObjectAttachColumn, PipelineStageName, PublishListingParams, PublishListingResult, ReduceMeta, ReduceStrategyId, ReportListingResult, SURROUND_DIRECTIONS, SharedListing, SharedVoice, SurroundDirection, Voice, VoiceClone, VoiceLibraryParams, VoiceLibraryResponse, WorkflowExport, WorkflowExportCharacter, WorkflowExportLocation, WorkflowExportObject } from '@nodaro/shared';
+import { PersonValue, WizardNodeContext, WizardQuestion, WizardSelection, RecommendedModel, FactoryPreset } from '@nodaro/prompts';
+export { PEOPLE, PERSON_DIMENSION_LABELS, PERSON_DIMENSION_ORDER, PersonValue, RecommendedModel, WizardNodeContext, WizardOption, WizardQuestion, WizardSelection, buildPersonHints } from '@nodaro/prompts';
+
+/**
+ * Auth provides the token used for `Authorization: Bearer <token>` on each request.
+ * Implementations:
+ *   - StaticTokenAuth — fixed string (server-side, OAuth access token, API token)
+ *   - CallbackAuth    — caller-supplied async function (BYO logic)
+ *   - supabaseAuth    — pulls JWT from a Supabase client live (browser frontends)
+ */
+interface Auth {
+    /** Returns the current Bearer token, or null if not authenticated. */
+    getToken(): Promise<string | null>;
+}
+declare class StaticTokenAuth implements Auth {
+    private token;
+    constructor(token: string);
+    getToken(): Promise<string>;
+}
+declare class CallbackAuth implements Auth {
+    private fn;
+    constructor(fn: () => string | null | Promise<string | null>);
+    getToken(): Promise<string | null>;
+}
+interface SupabaseLikeClient {
+    auth: {
+        getSession(): Promise<{
+            data: {
+                session: {
+                    access_token: string;
+                } | null;
+            };
+        }>;
+    };
+}
+/** Pulls a JWT from a Supabase v2 client. Caller supplies their own supabase. */
+declare function supabaseAuth(supabase: SupabaseLikeClient): Auth;
+
+/**
+ * Workflow metadata + (when fetched as a single record) full nodes/edges/settings.
+ *
+ * The list endpoint returns metadata only; `get`, `create`, and `update` return the
+ * full record. `nodes`, `edges`, `settings`, and `sourcePrompt` are present only on
+ * full records and omitted in list responses.
+ */
+interface Workflow {
+    id: string;
+    projectId: string | null;
+    userId: string;
+    name: string;
+    description?: string | null;
+    folderId?: string | null;
+    isTemplate?: boolean;
+    version?: number;
+    thumbnailUrl?: string | null;
+    nodes?: GenericNode[];
+    edges?: GenericEdge[];
+    settings?: Record<string, unknown>;
+    sourcePrompt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ListWorkflowsParams {
+    /** Required — list endpoint is `/v1/projects/:projectId/workflows`. */
+    projectId: string;
+}
+interface CreateWorkflowInput {
+    /** Required — workflow is created under this project. */
+    projectId: string;
+    name: string;
+    description?: string;
+    folderId?: string | null;
+    nodes?: GenericNode[];
+    edges?: GenericEdge[];
+    settings?: Record<string, unknown>;
+    sourcePrompt?: string;
+}
+interface UpdateWorkflowInput {
+    name?: string;
+    description?: string;
+    folderId?: string | null;
+    nodes?: GenericNode[];
+    edges?: GenericEdge[];
+    settings?: Record<string, unknown>;
+    sourcePrompt?: string;
+    thumbnailUrl?: string | null;
+}
+interface RunWorkflowParams {
+    /** Optional subset of node IDs to execute. Omit to run the full workflow. */
+    nodeIds?: string[];
+}
+interface RunWorkflowResult {
+    executionId: string;
+    status: "pending" | "running";
+}
+declare class WorkflowsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /** List workflows for a project. Returns metadata only — `nodes`/`edges` are not included. */
+    list(params: ListWorkflowsParams): Promise<{
+        data: Workflow[];
+    }>;
+    /** Get a workflow including its full nodes/edges/settings. */
+    get(id: string): Promise<{
+        data: Workflow;
+    }>;
+    /**
+     * Get a PUBLICLY-SHARED workflow by id (`GET /v1/public/workflows/:id`) — the
+     * unauthenticated share-by-link read. Returns the workflow's nodes/edges/
+     * settings ONLY when it's opted into sharing server-side (`settings.studio.shared
+     * === true`); otherwise the route 404s (→ `NotFoundError`). No auth required —
+     * a share viewer has no session; the SDK omits the bearer when no token exists.
+     */
+    getPublic(id: string): Promise<{
+        data: Workflow;
+    }>;
+    /**
+     * Create a workflow under a project. Returns the full record.
+     * NOTE: server route is `POST /v1/projects/:projectId/workflows`.
+     */
+    create(input: CreateWorkflowInput): Promise<{
+        data: Workflow;
+    }>;
+    /** Patch a workflow. Returns the full updated record. */
+    update(id: string, input: UpdateWorkflowInput): Promise<{
+        data: Workflow;
+    }>;
+    /** Delete a workflow. Returns `{ success: true }`. */
+    delete(id: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Run a workflow. Returns the executionId for polling via
+     * `client.executions.get(executionId)`.
+     */
+    run(id: string, params?: RunWorkflowParams): Promise<RunWorkflowResult>;
+    /**
+     * Export a workflow as a portable JSON bundle.
+     * Pass `opts.assets = true` to include character/object/location entity data.
+     */
+    export(workflowId: string, opts?: {
+        assets?: boolean;
+    }): Promise<{
+        data: WorkflowExport;
+    }>;
+    /**
+     * Import a `WorkflowExport` bundle into the specified project.
+     * Re-creates any bundled assets (characters, objects, locations) under your account.
+     */
+    import(input: WorkflowExport & {
+        projectId: string;
+    }): Promise<{
+        data: Workflow;
+    }>;
+}
+
+interface Project {
+    id: string;
+    userId: string;
+    name: string;
+    description?: string | null;
+    settings?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateProjectInput {
+    name: string;
+    description?: string;
+    settings?: Record<string, unknown>;
+}
+interface UpdateProjectInput {
+    name?: string;
+    description?: string;
+    settings?: Record<string, unknown>;
+}
+declare class ProjectsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /** List the authenticated user's projects. */
+    list(): Promise<{
+        data: Project[];
+    }>;
+    /** Get a project by ID. */
+    get(id: string): Promise<{
+        data: Project;
+    }>;
+    /** Create a new project. */
+    create(input: CreateProjectInput): Promise<{
+        data: Project;
+    }>;
+    /** Update a project. At least one field must be provided. */
+    update(id: string, input: UpdateProjectInput): Promise<{
+        data: Project;
+    }>;
+    /** Delete a project. Returns `{ success: true }`. */
+    delete(id: string): Promise<{
+        success: true;
+    }>;
+}
+
+type JobStatus = "pending" | "queued" | "processing" | "completed" | "failed" | "cancelled";
+/**
+ * Job record returned to non-admin SDK consumers. Field names are snake_case
+ * to match the wire format (per the OpenAPI fix in Phase 1).
+ *
+ * Sensitive fields stripped server-side for non-admin callers:
+ * `provider`, `provider_cost`, `display_cost`, `credits_actual`. USD
+ * pricing is admin-only across api/sdk/mcp — non-admin consumers see
+ * only the `credits` abstraction.
+ */
+interface Job {
+    id: string;
+    status: JobStatus;
+    progress: number;
+    user_id: string;
+    input_data: unknown;
+    output_data: unknown;
+    error_message: string | null;
+    credits: number | null;
+    job_type: string | null;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+}
+interface CancelJobResult {
+    success: true;
+    cancelled: number;
+}
+/**
+ * Lean job status returned by `GET /v1/jobs/:id/status`. Skips the
+ * `input_data` JSONB, cost/timestamp columns, and the public sanitize pass —
+ * intended for poll loops that only need progress/output/error.
+ */
+interface JobStatusResult {
+    id: string;
+    status: JobStatus;
+    progress?: number;
+    output_data?: unknown;
+    error_message?: string | null;
+}
+declare class JobsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /** Get a single job by ID. */
+    get(id: string): Promise<{
+        data: Job;
+    }>;
+    /**
+     * Get the lean status of a single job (poll-loop friendly).
+     * Hits `GET /v1/jobs/:id/status` — returns only id/status/progress/
+     * output_data/error_message, with far less wire/CPU cost than `get()`.
+     * Same auth + ownership semantics as {@link get}.
+     */
+    getStatus(id: string): Promise<{
+        data: JobStatusResult;
+    }>;
+    /**
+     * Cancel a job. Server route is `POST /v1/jobs/:jobId/cancel`.
+     * Refunds any reserved credit holds.
+     */
+    cancel(id: string): Promise<CancelJobResult>;
+}
+
+type ExecutionStatus = "pending" | "running" | "completed" | "failed" | "cancelled" | "stopping" | "timed_out" | "discarded";
+type ExecutionTriggerType = "manual" | "webhook" | "schedule" | "app_run" | "single-node";
+/**
+ * Per-node state inside an execution's `nodeStates` map. Keys are node IDs.
+ *
+ * Shape mirrors `services/workflow-engine/types.ts` plus the synthetic
+ * single-node-job shape from `routes/workflow-execution.ts`.
+ */
+interface NodeExecutionState {
+    status: string;
+    nodeType?: string;
+    jobId?: string | null;
+    creditsUsed?: number;
+    error?: string | null;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * Workflow execution record. Returned by `get()` and `cancel()` (the cancel
+ * endpoint returns `{ success: true }`, not the execution itself).
+ */
+interface WorkflowExecution {
+    id: string;
+    workflowId: string | null;
+    userId: string;
+    status: ExecutionStatus;
+    triggerType: ExecutionTriggerType;
+    triggerData?: unknown;
+    nodeStates: Record<string, NodeExecutionState>;
+    totalNodes: number;
+    completedNodes: number;
+    failedNodes: number;
+    totalCreditsUsed: number;
+    errorMessage: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Summary returned by `listForWorkflow()`. Excludes per-row `triggerData`/`updatedAt`. */
+interface WorkflowExecutionSummary {
+    id: string;
+    status: ExecutionStatus;
+    triggerType: ExecutionTriggerType;
+    nodeStates: Record<string, NodeExecutionState>;
+    totalNodes: number;
+    completedNodes: number;
+    failedNodes: number;
+    totalCreditsUsed: number;
+    errorMessage: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+}
+interface ListExecutionsForWorkflowParams {
+    limit?: number;
+    cursor?: string;
+    /** Comma-separated list of statuses, e.g. "pending,running". */
+    status?: string;
+    /** "editor" excludes app_run / component / webhook / schedule executions. */
+    source?: "editor" | "all";
+}
+interface ListExecutionsPage<T> {
+    data: T[];
+    nextCursor?: string;
+}
+interface CancelExecutionParams {
+    /**
+     * "after_current" sets the execution to "stopping" (let in-flight nodes
+     * finish, then stop). Default behavior cancels immediately.
+     */
+    mode?: "after_current" | "discard";
+}
+declare class ExecutionsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /** Get an execution by ID. Falls back to standalone single-node jobs server-side. */
+    get(id: string): Promise<{
+        data: WorkflowExecution;
+    }>;
+    /** List executions for a workflow. Merges workflow_executions + standalone single-node jobs. */
+    listForWorkflow(workflowId: string, params?: ListExecutionsForWorkflowParams): Promise<ListExecutionsPage<WorkflowExecutionSummary>>;
+    /** Cancel an execution. Returns `{ success: true }`. */
+    cancel(id: string, params?: CancelExecutionParams): Promise<{
+        success: true;
+    }>;
+}
+
+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[];
+}
+/**
+ * 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;
+    /** Credit cost. Number when fixed, string range like "1-8" when model-dependent, undefined if free. */
+    creditCost?: number | string;
+    /** 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[];
+}
+/**
+ * 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`.
+ *
+ * A small subset (combine-text, split-text, composite — the "inline"
+ * orchestrator categories) execute synchronously and return their full
+ * result body. The shape is route-specific; consumers should branch on the
+ * presence of `jobId`.
+ */
+type RunNodeResult = {
+    jobId: string;
+    usageLogId?: string;
+    [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[];
+    /** Reorder the assembled reference list by stable ref ids; renumbers `@image_N`. */
+    referenceOrder?: 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).
+ */
+interface GenerateImageParams extends StructuredReferenceParams {
+    prompt?: string;
+    provider?: string;
+    /** Flat reference image URLs — appended after `connectedReferences`. */
+    referenceImageUrls?: string[];
+    negativePrompt?: string;
+    [k: string]: unknown;
+}
+/**
+ * Typed request body for `nodes.run("generate-video", …)` / `runAndWait`.
+ * Common fields are typed; any other route field passes through.
+ */
+interface GenerateVideoParams extends StructuredReferenceParams {
+    prompt?: string;
+    provider?: string;
+    /** Start-frame image (image-to-video). */
+    imageUrl?: string;
+    referenceImageUrls?: string[];
+    referenceVideoUrls?: string[];
+    referenceAudioUrls?: 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 {
+    blocks: {
+        videoUrl: string;
+        audioUrl?: string;
+    }[];
+    voiceVolume?: number;
+    clipAudioVolume?: number;
+    maxSlowdown?: number;
+    trimStartFrames?: number;
+    trimEndFrames?: number;
+    [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`
+ * → `videoUrl` (+ `thumbnailUrl`), `text-to-speech` / `generate-music` →
+ * `audioUrl`. Resolved by {@link NodesResource.runAndWait}. Extra fields may be
+ * present, so the index signature is open.
+ */
+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` write here. */
+    readonly videoUrl?: string;
+    /** `generate-image` / `edit-image` / `extract-frame` write here. */
+    readonly imageUrl?: string;
+    /** Poster frame for video outputs. */
+    readonly thumbnailUrl?: string;
+    readonly [k: string]: unknown;
+}
+/** 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}.
+     */
+    readonly signal?: AbortSignal;
+    /** 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;
+}
+/** One settled result from {@link NodesResource.runMany}. */
+interface RunManyResult {
+    readonly jobId: string;
+    readonly output: NodeJobOutput;
+}
+declare class NodesResource {
+    private client;
+    constructor(client: NodaroClient);
+    /** 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 `POST /v1/<type>` (the route convention
+     * every generation node follows: `generate-image`, `image-to-video`,
+     * `text-to-speech`, etc.).
+     *
+     * 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. Inline node types (combine-text, etc.) return their full
+     * result synchronously 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-image", params?: GenerateImageParams): Promise<RunNodeResult>;
+    run(type: "generate-video", params?: GenerateVideoParams): Promise<RunNodeResult>;
+    run(type: "assemble-narrated-video", params?: AssembleNarratedVideoParams): Promise<RunNodeResult>;
+    run(type: string, params?: Record<string, unknown>): 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.
+     *
+     * 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-image", params?: GenerateImageParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "generate-video", params?: GenerateVideoParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: "assemble-narrated-video", params?: AssembleNarratedVideoParams, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    runAndWait(type: string, params?: Record<string, unknown>, opts?: RunAndWaitOptions): Promise<NodeJobOutput>;
+    /**
+     * 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}. 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` / `onProgress` / `pollMs` / `maxMs`.
+     */
+    runMany(type: string, paramsList: Record<string, unknown>[], opts?: RunAndWaitOptions): Promise<RunManyResult[]>;
+    /** Poll an already-kicked job id until terminal; resolve output_data or throw. */
+    private pollJob;
+}
+
+/**
+ * OAuth scopes that a developer app may request. Mirrors
+ * `backend/src/lib/scopes.ts#ALL_SCOPES`.
+ */
+type DeveloperAppScope = "workflows:read" | "workflows:write" | "workflows:execute" | "jobs:read" | "assets:read" | "assets:write" | "credits:read" | "apps:read" | "pipelines:read" | "pipelines:execute" | "pipelines:approve";
+type DeveloperAppStatus = "active" | "suspended" | "pending_review";
+interface DeveloperApp {
+    id: string;
+    name: string;
+    description: string | null;
+    logoUrl: string | null;
+    homepageUrl: string | null;
+    redirectUris: string[];
+    allowedOrigins: string[];
+    scopesRequested: DeveloperAppScope[];
+    clientId: string;
+    status: DeveloperAppStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * One-shot create response — `clientSecret` is returned exactly ONCE here.
+ * Store it securely; subsequent `get`/`list` calls will not include it.
+ */
+interface CreateDeveloperAppResult extends DeveloperApp {
+    clientSecret: string;
+}
+interface CreateDeveloperAppInput {
+    name: string;
+    description?: string;
+    homepageUrl?: string;
+    logoUrl?: string;
+    /** At least 1, at most 10 redirect URIs. Each must be https or http://localhost. */
+    redirectUris: string[];
+    /** Up to 5 bare origins (no path/query/hash), e.g. "https://example.com". */
+    allowedOrigins?: string[];
+    /** At least 1 scope required. */
+    scopesRequested: DeveloperAppScope[];
+}
+interface UpdateDeveloperAppInput {
+    name?: string;
+    description?: string;
+    homepageUrl?: string;
+    logoUrl?: string;
+    redirectUris?: string[];
+    allowedOrigins?: string[];
+    scopesRequested?: DeveloperAppScope[];
+}
+interface RotateSecretResult {
+    /** New client secret. Returned exactly once — old secret is invalidated. */
+    clientSecret: string;
+}
+declare class DeveloperAppsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /** List the authenticated user's developer apps. */
+    list(): Promise<{
+        data: DeveloperApp[];
+    }>;
+    /** Get a developer app by ID. */
+    get(id: string): Promise<{
+        data: DeveloperApp;
+    }>;
+    /**
+     * Create a new developer app. Returns the app PLUS a one-time `clientSecret`
+     * — store it now, the secret hash is the only copy kept server-side.
+     */
+    create(input: CreateDeveloperAppInput): Promise<{
+        data: CreateDeveloperAppResult;
+    }>;
+    /** Update a developer app's metadata, redirect URIs, origins, or requested scopes. */
+    update(id: string, input: UpdateDeveloperAppInput): Promise<{
+        data: DeveloperApp;
+    }>;
+    /** Delete a developer app. Returns `{ success: true }`. */
+    delete(id: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Generate a new `clientSecret`. The previous secret is invalidated.
+     * Server returns ONLY the new secret, not the full app record.
+     */
+    rotateSecret(id: string): Promise<RotateSecretResult>;
+}
+
+/**
+ * Server-side authorization-code exchange payload. Field names are snake_case
+ * per OAuth 2.0 (RFC 6749).
+ */
+interface ExchangeCodeInput {
+    client_id: string;
+    client_secret: string;
+    /** Authorization code received from the consent redirect. */
+    code: string;
+    /** Must match the redirect_uri used when issuing the code. */
+    redirect_uri: string;
+}
+/**
+ * `POST /v1/oauth/token` response — snake_case per RFC 6749. `expires_in` is
+ * the token's lifetime in seconds.
+ */
+interface AccessTokenResponse {
+    access_token: string;
+    token_type: "Bearer";
+    /** Space-separated list of granted scopes. */
+    scope: string;
+    expires_in: number;
+}
+/**
+ * Public app metadata for consent screens. Only safe-to-display fields —
+ * no secret, no full origin list, no owner_user_id.
+ */
+interface OAuthAppInfo {
+    name: string;
+    description: string | null;
+    logoUrl: string | null;
+    homepageUrl: string | null;
+    scopesRequested: DeveloperAppScope[];
+}
+declare class OAuthResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * Server-side authorization-code exchange. Sends the standard OAuth 2.0
+     * `application/json` body to `POST /v1/oauth/token`.
+     *
+     * NEVER call this from a browser — `client_secret` must stay on the server.
+     */
+    exchangeCode(input: ExchangeCodeInput): Promise<AccessTokenResponse>;
+    /**
+     * Revoke an access token (RFC 7009). Always returns `{ success: true }`,
+     * even for unknown tokens — the spec forbids leaking token validity.
+     */
+    revoke(token: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Get public app metadata for a consent screen.
+     * `GET /v1/oauth/app-info?client_id=<id>`. Public route — no auth needed.
+     */
+    getAppInfo(clientId: string): Promise<OAuthAppInfo>;
+}
+
+/**
+ * A published app — a workflow wrapped in a curated input/output presentation.
+ * Returned by the public `/v1/apps/browse` endpoint.
+ */
+interface PublishedApp {
+    id: string;
+    slug: string;
+    name: string;
+    description?: string | null;
+    creatorId: string;
+    creatorName?: string | null;
+    thumbnailUrl?: string | null;
+    category?: string | null;
+    isFeatured?: boolean;
+    runCount?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ListAppsParams {
+    /** Substring search across app name + description. */
+    search?: string;
+    /** Page size; backend caps at 50. */
+    limit?: number;
+    /** Cursor token returned by the previous page. */
+    cursor?: string;
+    /** Filter to a single category slug. */
+    category?: string;
+}
+interface ListAppsResult {
+    data: PublishedApp[];
+    nextCursor?: string | null;
+}
+/**
+ * App detail — includes the input schema (required + optional fields end users
+ * fill in) and the output mapping (which workflow nodes produce which display
+ * cards).
+ */
+interface PublishedAppDetail extends PublishedApp {
+    inputSchema: Record<string, unknown>;
+    outputs: Array<{
+        nodeId: string;
+        label: string;
+        type: string;
+    }>;
+}
+interface AppRunResult {
+    /** The execution-id that was started — poll via client.executions.get(). */
+    executionId: string;
+    status: "pending" | "running";
+    /** App-run id (distinct from executionId — used by listRuns/getRun). */
+    runId?: string;
+}
+interface AppRun {
+    id: string;
+    appSlug: string;
+    executionId: string;
+    status: "pending" | "running" | "completed" | "failed" | "cancelled";
+    inputs: Record<string, unknown>;
+    outputs?: Array<{
+        nodeId: string;
+        type: string;
+        url?: string;
+        text?: string;
+    }>;
+    startedAt: string;
+    finishedAt?: string | null;
+}
+interface ListAppRunsParams {
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Result of a soft-delete (archive) operation. The run is moved to the user's
+ * archive in the Nodaro UI; restoration and permanent deletion are UI-only by
+ * design — SDK / MCP / API delete callers can't accidentally destroy data.
+ */
+interface DeleteAppRunResult {
+    success: true;
+    archived: true;
+}
+declare class AppsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /** List published apps. Public — no auth required for community apps. */
+    list(params?: ListAppsParams): Promise<ListAppsResult>;
+    /** Get one app's metadata + input schema by slug. */
+    get(slug: string): Promise<{
+        data: PublishedAppDetail;
+    }>;
+    /**
+     * Trigger an app run with the given input values. The keys in `inputs` must
+     * match the app's input-schema field names (see `get(slug).inputSchema`).
+     * Returns the execution-id for status polling via client.executions.get().
+     */
+    run(slug: string, inputs?: Record<string, unknown>): Promise<AppRunResult>;
+    /** List past runs for an app (the caller must own the app or the runs). */
+    listRuns(slug: string, params?: ListAppRunsParams): Promise<{
+        data: AppRun[];
+        nextCursor?: string | null;
+    }>;
+    /** Get one app-run by id. */
+    getRun(slug: string, runId: string): Promise<{
+        data: AppRun;
+    }>;
+    /**
+     * Archive (soft-delete) a published-app run. The run is hidden from the
+     * default run list and can be restored or permanently deleted from the
+     * archive view at https://app.nodaro.ai/archived-runs.
+     *
+     * @param slug   The published app's slug (the last path segment of its URL).
+     * @param runId  The run's UUID.
+     */
+    deleteRun(slug: string, runId: string): Promise<DeleteAppRunResult>;
+}
+
+/**
+ * Re-export the shared `EntityStyle` union (realistic | anime | 3d-pixar |
+ * illustration) and `CHARACTER_STYLES` runtime tuple so SDK consumers don't
+ * have to add `@nodaro/shared` as a second dependency just to typecheck the
+ * `style` field. Single source of truth lives in `@nodaro/shared/entity-prompts`.
+ */
+/**
+ * Re-export the 4-value aspect-ratio union accepted by the generate-character*
+ * routes. Single source of truth lives in `@nodaro/shared`. See
+ * `CHARACTER_ASPECT_DEFAULTS` for the per-asset-type defaults.
+ */
+/**
+ * Structured Person composer, re-exported from `@nodaro/shared` so SDK
+ * consumers can build a detailed person description — Identity, Body, and the
+ * Face facial-geometry layer (cheekbones, canthal tilt, eyelid type, lip
+ * fullness/shape, nose tip, etc.) — and feed it as `seedPrompt` / `description`
+ * to `generate()` / `upsert()` without adding `@nodaro/shared` as a second dep.
+ *
+ * `buildPersonSeedPrompt` collapses a `PersonValue` into the same comma-joined
+ * fragment the editor's Person picker produces (e.g. "almond-shaped eyes,
+ * sharply sculpted high cheekbones, full plump lips"). Returns "" when empty.
+ */
+/**
+ * A character record returned by Nodaro's REST API. Mirrors the camelCase
+ * shape produced by `backend/src/routes/characters.ts::toCamel()`.
+ *
+ * `expressions`, `poses`, `motions`, `angles`, `bodyAngles`,
+ * `lightingVariations` are independent buckets keyed by a human-readable
+ * variant name (e.g. `"smile"`, `"standing"`, `"3/4 left"`). Each entry's
+ * `url` points at an R2-hosted asset.
+ *
+ * Identity-foundation fields:
+ *   - `referencePhotos` — caller-supplied real-life refs (max one per
+ *     non-`other` kind; cap 20 total). Drive the i2v / i2i path when a
+ *     provider supports multi-image conditioning.
+ *   - `realLifeRefsByVariant` — per-variant reference URLs (cap 20 keys,
+ *     5 URLs per key). Keys are lowercased+trimmed.
+ *   - `referenceVideosByVariant` — per-label user-uploaded reference VIDEO
+ *     URLs (cap 20 keys, 5 URLs per key, lowercased+trimmed keys). Mirrors
+ *     `realLifeRefsByVariant` for video clips (e.g. emotion takes). Read the
+ *     chosen URLs off the row to drive generate-video's `referenceVideoUrls`.
+ *   - `seedPrompt` — short prompt fragment that scaffolds portrait gen.
+ *   - `canonicalDescription` — ~80–120-word LLM-authored visual caption,
+ *     populated by `approvePortrait()` / `recaption()`.
+ */
+interface Character {
+    id: string;
+    userId: string;
+    /** Canvas node linkage. `null` only on legacy clone rows that predate the
+     *  clone-side node_id fix (new clones mint one; creates always had one). */
+    nodeId: string | null;
+    projectId: string | null;
+    name: string;
+    description: string | null;
+    gender: string | null;
+    style: string | null;
+    baseOutfit: string | null;
+    sourceImageUrl: string | null;
+    /** MODEL_CATALOG image-model id the main image was generated with (or `null`).
+     *  Set on create (the provider you generated with) + editable via `upsert`. */
+    imageProvider: string | null;
+    expressions: Array<{
+        name: string;
+        url: string;
+    }> | null;
+    poses: Array<{
+        name: string;
+        url: string;
+    }> | null;
+    lightingVariations: Array<{
+        name: string;
+        url: string;
+    }> | null;
+    angles: Array<{
+        name: string;
+        url: string;
+    }> | null;
+    bodyAngles: Array<{
+        name: string;
+        url: string;
+    }> | null;
+    motions: Array<{
+        name: string;
+        url: string;
+    }> | null;
+    /** Named Character Boards — dense reference sheets, one per persona/look
+     *  (the `generate-image/character-board` factory preset rendered from the
+     *  character's images). A first-class bucket: community publish snapshots it
+     *  and clone hands the consumer their own copy to extend. Defaults to `[]`.
+     *  `type` marks an image-collage `"identity"` sheet vs a plain `"looks"`
+     *  board; `sourceImages` are the R2 URLs it was collaged from. Both optional
+     *  + backward-compatible (legacy boards have neither). */
+    boards?: Array<{
+        name: string;
+        url: string;
+        type?: "looks" | "identity";
+        sourceImages?: string[];
+    }> | null;
+    /** Per-label user-uploaded reference VIDEO URLs (R2), keyed by a
+     *  caller-owned label (lowercased+trimmed server-side). Mirrors
+     *  `realLifeRefsByVariant` for video clips; read the chosen URLs off the row
+     *  to feed generate-video's `referenceVideoUrls`. Defaults to `{}`. */
+    referenceVideosByVariant?: Record<string, string[]> | null;
+    /** The user's chosen DEFAULT asset take per variant (Studio version history).
+     *  OPAQUE map: key `"<bucket>:<variant>"` (e.g. `"bodyAngles:front"`,
+     *  `"expressions:smile"`) → the chosen asset URL (one already present in that
+     *  bucket). Stored verbatim — keys are NOT normalized; soft-capped server-side
+     *  at 200 keys / 2048-char values (overflow dropped silently). Defaults to `{}`. */
+    selectedAssetByVariant?: Record<string, string> | null;
+    /** `voiceType` records the selected voice's KIND (premade voices are
+     *  addressed by name; library/custom voices by id at text-to-speech time).
+     *  `previewUrl` is a playable audio sample (the voice's `preview_url` / clone
+     *  sample) the studio plays in an `<audio>` element — persisted so Voice Library
+     *  voices (which have no by-id lookup) stay previewable after reload. Client-
+     *  played only; the server never fetches it. `ttsProvider` is the library
+     *  voice's verified TTS provider (see `SharedVoice.recommendedProvider`) —
+     *  send it as the text-to-speech `provider` so the voice renders on a model
+     *  it's verified for. All optional — a character may have no voice, or a
+     *  legacy voice predating these fields. */
+    voice: {
+        voiceId: string;
+        voiceName: string;
+        traits: string;
+        voiceType?: "premade" | "library" | "custom";
+        previewUrl?: string;
+        ttsProvider?: TtsProvider;
+    } | null;
+    personality: {
+        mood: string;
+        speechStyle: string;
+        movementStyle: string;
+        behavioralNotes: string;
+    } | null;
+    /** ~80–120-word LLM-authored visual caption (approve-portrait / recaption).
+     *  Optional on the read surface so existing literal consumers don't break;
+     *  the route always returns it (string | null). */
+    canonicalDescription?: string | null;
+    /** Identity-lock strength for Character Studio asset generation. */
+    identityLock?: "off" | "soft" | "strict";
+    deletedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * GET /v1/characters/:id appends three live-progress buckets the studio uses
+ * to rehydrate spinners after a reload. Optional in the SDK surface — they
+ * don't appear on `list()` rows.
+ */
+interface CharacterDetail extends Character {
+    pendingJobs?: Array<{
+        jobId: string;
+        assetType: "expressions" | "poses" | "angles" | "bodyAngles" | "lighting" | "motions";
+        name: string;
+    }>;
+    portraitCandidates?: Array<{
+        jobId: string;
+        url: string | undefined;
+        progress: number;
+        status: string;
+    }>;
+    previousCandidates?: Array<{
+        jobId: string;
+        url: string;
+        createdAt: string;
+    }>;
+}
+type ReferencePhotoKind = "frontFace" | "sideLeft" | "sideRight" | "threeQuarterLeft" | "threeQuarterRight" | "frontBody" | "other";
+interface ReferencePhoto {
+    url: string;
+    kind: ReferencePhotoKind;
+}
+/**
+ * Body for `client.characters.upsert()`. Mirrors `upsertCharacterBody` in
+ * `backend/src/routes/characters.ts`. Omitting `id` triggers an INSERT;
+ * supplying it triggers an UPDATE that only writes the fields you pass —
+ * undefined keys are NOT touched on the row.
+ *
+ * `name` is optional at the type level. The route requires `name` on INSERT
+ * (id absent) and rejects with `validation_error` otherwise; on UPDATE the
+ * route just ignores `name` when omitted, which lets partial updates like
+ * `update(id, { gender: "female" })` succeed without re-sending the same
+ * name the caller already has.
+ */
+interface UpsertCharacterInput {
+    /** UUID of the character row; omit to create. */
+    id?: string;
+    /** Canvas node id the character belongs to. REQUIRED on create (the route
+     *  400s without it, like `name`); optional on update — the update branch
+     *  never touches node_id, so partial updates needn't round-trip it. */
+    nodeId?: string;
+    workflowId?: string;
+    projectId?: string;
+    name?: string;
+    description?: string;
+    gender?: string;
+    style?: string;
+    baseOutfit?: string;
+    sourceImageUrl?: string;
+    /** Persistent image-model id (a MODEL_CATALOG image model). Validated
+     *  server-side — unknown / non-image / "" is stored as `null`. */
+    imageProvider?: string | null;
+    expressions?: Array<{
+        name: string;
+        url: string;
+    }>;
+    poses?: Array<{
+        name: string;
+        url: string;
+    }>;
+    lightingVariations?: Array<{
+        name: string;
+        url: string;
+    }>;
+    angles?: Array<{
+        name: string;
+        url: string;
+    }>;
+    bodyAngles?: Array<{
+        name: string;
+        url: string;
+    }>;
+    motions?: Array<{
+        name: string;
+        url: string;
+    }>;
+    /** Named Character Boards (see `Character.boards`) — whole-array replace,
+     *  like the asset buckets. Server caps: 24 boards, 200-char names, 30
+     *  sourceImages per board. */
+    boards?: Array<{
+        name: string;
+        url: string;
+        type?: "looks" | "identity";
+        sourceImages?: string[];
+    }>;
+    /** See `Character.voice` — persisted alongside the voice so TTS can resolve a
+     *  library/custom voice by id, `previewUrl` keeps the sample playable after
+     *  reload, and `ttsProvider` keeps generation on a model the voice is
+     *  verified for. All optional. */
+    voice?: {
+        voiceId: string;
+        voiceName: string;
+        traits: string;
+        voiceType?: "premade" | "library" | "custom";
+        previewUrl?: string;
+        ttsProvider?: TtsProvider;
+    } | null;
+    personality?: {
+        mood: string;
+        speechStyle: string;
+        movementStyle: string;
+        behavioralNotes: string;
+    } | null;
+    seedPrompt?: string;
+    canonicalDescription?: string;
+    /** Identity-lock strength for Character Studio asset generation (off/soft/strict). */
+    identityLock?: "off" | "soft" | "strict";
+    referencePhotos?: ReferencePhoto[];
+    /** Per-variant real-life reference URLs. Keys are lowercased+trimmed server-side. */
+    realLifeRefsByVariant?: Record<string, string[]>;
+    /** Per-label user-uploaded reference VIDEO URLs (e.g. emotion takes). Keys
+     *  are lowercased+trimmed server-side; max 20 keys, 5 URLs each. Stored R2
+     *  URLs are read back off the row to drive generate-video's
+     *  `referenceVideoUrls`. */
+    referenceVideosByVariant?: Record<string, string[]>;
+    /** The user's chosen DEFAULT asset take per variant. OPAQUE
+     *  `"<bucket>:<variant>"` → chosen-URL map; a write REPLACES the whole map
+     *  (the studio sends the full map each save). Omit to leave the row untouched.
+     *  Keys stored verbatim; soft-capped server-side at 200 keys / 2048-char values. */
+    selectedAssetByVariant?: Record<string, string>;
+}
+interface UpsertCharacterResult {
+    id: string;
+    name?: string;
+}
+interface ListCharactersParams {
+    /** Restrict to a single project. */
+    projectId?: string;
+    /** When true, return archived characters instead of active ones. */
+    archived?: boolean;
+    /**
+     * Max rows to return. Server defaults to 100, caps at 500. Omit to take the
+     * server default — passing it just narrows further.
+     */
+    limit?: number;
+}
+interface DuplicateCharacterInput {
+    /** Optional canvas node id to bind the new row to. */
+    nodeId?: string;
+    /** Optional project to drop the new row into. */
+    projectId?: string;
+}
+interface CharacterUsage {
+    workflowCount: number;
+    workflows: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/**
+ * Input for `client.characters.generate()` — fires the
+ * `POST /v1/generate-character` route. Produces 1–10 portrait candidates;
+ * each lands as one `jobs` row in `pending` state and is then enqueued for
+ * the worker.
+ *
+ * Provide at least one of `seedPrompt`, `referencePhotos`, or `description`
+ * (the backend's refinement rejects empty input with `validation_error`).
+ *
+ * When `attachToCharacterId` is set, the worker writes the resulting URL
+ * directly to `characters.source_image_url` on completion — caller doesn't
+ * need a separate `approvePortrait` call for single-candidate runs.
+ */
+interface GenerateCharacterInput {
+    name: string;
+    description?: string;
+    userPrompt?: string;
+    gender?: string;
+    style?: EntityStyle;
+    baseOutfit?: string;
+    sourceImageUrl?: string;
+    provider?: string;
+    /** Auto-attach the result to this character row. */
+    attachToCharacterId?: string;
+    seedPrompt?: string;
+    referencePhotos?: ReferencePhoto[];
+    /** Number of candidate images to generate (1–10; server-validated). */
+    count?: number;
+    /**
+     * Explicit aspect ratio. Highest precedence — overrides both the character
+     * node toggle and the per-asset-type default (portraits default to `3:4`).
+     * Must be one of the 4-value `CharacterAspectRatio` union.
+     */
+    aspectRatio?: CharacterAspectRatio;
+    /**
+     * Character node toggle (per-canvas-node `defaultAssetAspectRatio`). Wins
+     * against the per-asset-type default, loses to `aspectRatio`.
+     */
+    characterNodeAspectRatio?: CharacterAspectRatio;
+    /**
+     * Credit-affecting quality tier (e.g. `"high"` for gpt-image). Priced like
+     * generate-image (composite ids such as `gpt-image:high`); values the chosen
+     * model doesn't support are ignored server-side, never rejected.
+     */
+    quality?: string;
+    /**
+     * Credit-affecting output resolution (e.g. `"2K"` / `"4K"` / `"2 MP"`).
+     * Priced like generate-image (composite ids such as `nano-banana-pro:4K`);
+     * values the chosen model doesn't support are ignored server-side, never
+     * rejected.
+     */
+    resolution?: string;
+}
+interface GenerateCharacterResult {
+    /** First job-id; convenience alias for `jobIds[0]`. */
+    jobId: string;
+    /** All job-ids when `count > 1`. */
+    jobIds: string[];
+}
+interface GenerateAssetInput {
+    assetType: "expressions" | "poses" | "lighting" | "angles" | "headAngles" | "bodyAngles" | "custom";
+    /** The named variant (e.g. `"smile"`, `"standing"`, `"3/4 left"`). */
+    variant: string;
+    /** Display name of the character; appears in the prompt. */
+    name: string;
+    description?: string;
+    userPrompt?: string;
+    gender?: string;
+    style?: EntityStyle;
+    baseOutfit?: string;
+    sourceImageUrl?: string;
+    /** Real-life reference URLs (cap 5). */
+    realLifeRefs?: string[];
+    provider?: string;
+    /** Auto-attach to character row + asset bucket on completion. */
+    attachToCharacterId?: string;
+    /** Shared type — auto-includes new buckets (sheets/detail_closeups/outfit_variations); mirrors objects.ts/locations.ts. */
+    attachToColumn?: CharacterAttachColumn;
+    attachName?: string;
+    /**
+     * Explicit aspect ratio. Highest precedence — overrides both the character
+     * node toggle and the per-asset-type default (expressions=1:1, poses=9:16,
+     * headAngles=3:4, bodyAngles=9:16, lighting=3:4, angles=3:4, custom=3:4).
+     */
+    aspectRatio?: CharacterAspectRatio;
+    /**
+     * Character node toggle (per-canvas-node `defaultAssetAspectRatio`). Wins
+     * against the per-asset-type default, loses to `aspectRatio`.
+     */
+    characterNodeAspectRatio?: CharacterAspectRatio;
+    /**
+     * Credit-affecting quality tier (e.g. `"high"` for gpt-image). Values the
+     * chosen model doesn't support are ignored server-side, never rejected.
+     */
+    quality?: string;
+    /**
+     * Credit-affecting output resolution (e.g. `"2K"` / `"4K"` / `"2 MP"`).
+     * Values the chosen model doesn't support are ignored server-side, never
+     * rejected.
+     */
+    resolution?: string;
+}
+interface GenerateMotionInput {
+    motionPrompt: string;
+    /** Optional when `attachToCharacterId` is set — falls back to the row's portrait. */
+    sourceImageUrl?: string;
+    provider?: string;
+    name: string;
+    description?: string;
+    motionDescription?: string;
+    gender?: string;
+    style?: EntityStyle;
+    baseOutfit?: string;
+    realLifeRefs?: string[];
+    attachToCharacterId?: string;
+    attachName?: string;
+    /**
+     * Explicit aspect ratio. Highest precedence — overrides both the character
+     * node toggle and the motions default (`9:16`).
+     */
+    aspectRatio?: CharacterAspectRatio;
+    /**
+     * Character node toggle (per-canvas-node `defaultAssetAspectRatio`). Wins
+     * against the motions default, loses to `aspectRatio`.
+     */
+    characterNodeAspectRatio?: CharacterAspectRatio;
+}
+interface ApprovePortraitResult {
+    portraitUrl: string;
+    /**
+     * LLM-authored caption. `null` when the LLM call failed during the approval
+     * — the portrait is still set; call `recaption()` to retry.
+     */
+    canonicalDescription: string | null;
+}
+interface RecaptionResult {
+    canonicalDescription: string;
+}
+declare class CharactersResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * List the caller's characters. By default returns active characters only;
+     * pass `archived: true` to fetch soft-deleted rows for an "archive" view.
+     * When `projectId` is set, only characters belonging to that project are
+     * returned.
+     */
+    list(params?: ListCharactersParams): Promise<{
+        characters: Character[];
+    }>;
+    /**
+     * Fetch a single character including in-flight portrait / asset job state.
+     * Soft-deleted (archived) rows are returned by id intentionally so canvas
+     * nodes that hold a stale `characterDbId` keep loading.
+     */
+    get(id: string): Promise<CharacterDetail>;
+    /**
+     * Create or update a character. Omit `id` to create; supply it to update
+     * (only the fields you pass get written — undefined keys are untouched).
+     *
+     * If the caller-supplied `name` collides with an existing active character
+     * for this user, the request returns 409 `name_taken`. To auto-number a
+     * placeholder, pass the placeholder name from `@nodaro/shared` and the
+     * server will derive "Untitled character 2", "Untitled character 3", etc.
+     */
+    upsert(input: UpsertCharacterInput): Promise<UpsertCharacterResult>;
+    /**
+     * Convenience wrapper around `upsert()` for creating new characters.
+     * Equivalent to `upsert({ ...input, id: undefined })`. `name` is REQUIRED
+     * on create — the route 400s on INSERT-without-name; we narrow the type
+     * here so callers fail at compile-time rather than runtime.
+     */
+    create(input: Omit<UpsertCharacterInput, "id"> & {
+        name: string;
+    }): Promise<UpsertCharacterResult>;
+    /**
+     * Convenience wrapper around `upsert()` for updating an existing character.
+     * Equivalent to `upsert({ ...input, id })`.
+     */
+    update(id: string, input: Omit<UpsertCharacterInput, "id">): Promise<UpsertCharacterResult>;
+    /**
+     * Soft-delete (archive) a character. The row is hidden from `list()` by
+     * default but still loadable via `get(id)` so canvas nodes pointing at it
+     * keep working. Restore with `restore(id)`.
+     */
+    delete(id: string): Promise<{
+        success: true;
+        archived: true;
+    }>;
+    /**
+     * Un-archive a character. If the original name now collides with an
+     * active row, the server auto-suffixes "(restored)" and returns the
+     * effective name.
+     */
+    restore(id: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * Duplicate (fork) a character to a new row with a `"(copy)"` suffix.
+     * Asset URLs are shared by reference — the new row can diverge by
+     * regenerating any of them.
+     */
+    duplicate(id: string, input?: DuplicateCharacterInput): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * Count of the caller's workflows that reference this character. Powers the
+     * library "Archive" confirmation modal in the editor.
+     */
+    usage(id: string): Promise<CharacterUsage>;
+    /**
+     * Fire `POST /v1/generate-character` to produce one or more portrait
+     * candidates. With `count > 1`, all jobs are reserved up-front before any
+     * is enqueued — mid-batch failures roll back atomically.
+     *
+     * When `attachToCharacterId` is set, the worker writes the result directly
+     * to the row's `source_image_url`; otherwise you must call
+     * `approvePortrait()` after picking a candidate.
+     */
+    generate(input: GenerateCharacterInput): Promise<GenerateCharacterResult>;
+    /**
+     * Fire `POST /v1/generate-character-asset` to produce a single
+     * expression / pose / angle / lighting variant. When the studio path is
+     * set (`attachToCharacterId` + `attachToColumn` + `attachName`), the
+     * worker appends `{ name: attachName, url: <result> }` to the named
+     * JSONB array column on completion.
+     */
+    generateAsset(input: GenerateAssetInput): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Fire `POST /v1/generate-character-motion` to animate the character's
+     * portrait into a motion clip. The result is appended to the character's
+     * `motions[]` bucket when `attachToCharacterId` is set.
+     */
+    generateMotion(input: GenerateMotionInput): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Approve a completed `generate-character` job as the character's portrait.
+     * Sets `source_image_url` and fires the LLM caption (Claude Sonnet vision)
+     * inline. Returns the new portrait URL plus the caption — `canonicalDescription`
+     * is `null` if the LLM call sub-failed (portrait still set; retry via `recaption()`).
+     */
+    approvePortrait(id: string, candidateJobId: string): Promise<ApprovePortraitResult>;
+    /**
+     * Re-fire the LLM caption against the character's current portrait. 502s on
+     * LLM failure; returns 400 `no_portrait` if no portrait is set yet.
+     */
+    recaption(id: string): Promise<RecaptionResult>;
+}
+
+/**
+ * Collapse a PersonValue into the comma-joined seed-prompt fragment used by
+ * `characters.generate({ seedPrompt })` — same composition the Nodaro editor
+ * performs. Powered by @nodaro/prompts.
+ */
+declare function buildPersonSeedPrompt(value: PersonValue): string;
+
+/**
+ * Re-export the shared `LocationAssetType` / `LocationAttachColumn` unions and
+ * their runtime tuples so SDK consumers don't have to add `@nodaro/shared` as a
+ * second dependency just to typecheck the `assetType` / `attachToColumn`
+ * fields. Single source of truth lives in `@nodaro/shared/entity-prompts`.
+ *
+ * `CharacterAspectRatio` is re-exported alongside them — `generateMotion`'s
+ * `aspectRatio` field reuses the same 4-value enum (1:1 / 3:4 / 16:9 / 9:16)
+ * as characters; the route enforces this with `z.enum(CHARACTER_ASPECT_OPTIONS)`.
+ */
+/**
+ * Reference-photo kind discriminator — the mood-board roles a user can attach
+ * to a location. Mirrors the `reference_photos.kind` Zod enum in
+ * `backend/src/routes/locations.ts`. `other` is the free-form bucket.
+ */
+type LocationReferencePhotoKind = "wide" | "interior" | "exterior" | "detail" | "moodBoard" | "other";
+interface LocationReferencePhoto {
+    url: string;
+    kind: LocationReferencePhotoKind;
+}
+/**
+ * A location record returned by Nodaro's REST API. Mirrors the camelCase
+ * shape produced by `backend/src/routes/locations.ts::toCamel()`.
+ *
+ * Asset buckets (`timeOfDay`, `weather`, `angles`, `lighting`, `seasons`,
+ * `atmosphereMotions`) are independent JSONB arrays keyed by a human-readable
+ * variant name (e.g. `"dawn"`, `"clear"`, `"wide"`). Each entry's `url` points
+ * at an R2-hosted asset.
+ *
+ * Identity-foundation fields:
+ *   - `referencePhotos` — caller-supplied mood-board refs (cap 20).
+ *   - `canonicalDescription` — ~80–120-word LLM-authored visual caption,
+ *     populated by `approveMainImage()` / `recaption()`. The wire still sends
+ *     `""` on caption sub-failure (the breaking wire change is deferred to a
+ *     major bump), but `get()` normalizes `""` → `null` so consumers see the
+ *     same `string | null` semantics as characters.
+ *   - `styleLock` — whether asset gens should anchor to the canonical style
+ *     captured at approval time. Defaults to `true` on new rows.
+ */
+interface Location {
+    id: string;
+    userId: string;
+    nodeId: string;
+    projectId: string | null;
+    name: string;
+    description: string | null;
+    category: string | null;
+    style: string | null;
+    sourceImageUrl: string | null;
+    /** MODEL_CATALOG image-model id the main image was generated with (or `null`).
+     *  Set on create + editable via the update route. */
+    imageProvider: string | null;
+    timeOfDay: Array<{
+        name: string;
+        url: string;
+    }>;
+    weather: Array<{
+        name: string;
+        url: string;
+    }>;
+    angles: Array<{
+        name: string;
+        url: string;
+    }>;
+    lighting: Array<{
+        name: string;
+        url: string;
+    }>;
+    seasons: Array<{
+        name: string;
+        url: string;
+    }>;
+    atmosphereMotions: Array<{
+        name: string;
+        url: string;
+    }>;
+    /** Named Location Boards — dense reference sheets, one per variant/mood
+     *  (the `generate-image/location-board` factory preset rendered from the
+     *  location's images). A first-class bucket: community publish snapshots it
+     *  and clone hands the consumer their own copy to extend. Defaults to `[]`.
+     *  `type` marks an image-collage `"identity"` sheet vs a plain `"looks"`
+     *  board; `sourceImages` are the R2 URLs it was collaged from. Both optional
+     *  + backward-compatible (legacy boards have neither). */
+    boards?: Array<{
+        name: string;
+        url: string;
+        type?: "looks" | "identity";
+        sourceImages?: string[];
+    }> | null;
+    referencePhotos: LocationReferencePhoto[];
+    /** `null` when no caption is set (or the LLM caption sub-failed) — the wire
+     *  sends `""`, normalized to `null` in `get()` to match character semantics. */
+    canonicalDescription: string | null;
+    styleLock: boolean;
+    /** The user's chosen DEFAULT asset take per variant (Studio version history).
+     *  OPAQUE map: key `"<bucket>:<variant>"` (e.g. `"timeOfDay:dawn"`) → the chosen
+     *  asset URL (one already present in that bucket). Stored verbatim — keys are
+     *  NOT normalized; soft-capped server-side at 200 keys / 2048-char values
+     *  (overflow dropped silently). Defaults to `{}`. */
+    selectedAssetByVariant?: Record<string, string> | null;
+    deletedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * GET /v1/locations/:id appends a `pendingJobs` bucket the studio uses to
+ * rehydrate spinners after a reload. Optional on the SDK surface — it doesn't
+ * appear on `list()` rows.
+ */
+interface LocationDetail extends Location {
+    pendingJobs?: Array<{
+        jobId: string;
+        assetType: string;
+        name: string;
+        status: string;
+    }>;
+    /**
+     * Completed candidate main images for this location whose URL differs from
+     * the current `sourceImageUrl`, newest first (max 5). Surfaced so a
+     * "pick from N" UI can offer alternatives the user can promote via
+     * `approveMainImage(id, jobId)`; until they pick, the current main image is
+     * left untouched. Mirrors `CharacterDetail.previousCandidates`. Optional -
+     * absent on `list()` rows, present (possibly empty) on `get()`.
+     */
+    previousCandidates?: Array<{
+        jobId: string;
+        url: string;
+        createdAt: string;
+    }>;
+}
+/**
+ * Body for `client.locations.create()`. Mirrors the INSERT branch of
+ * `upsertLocationBody` in `backend/src/routes/locations.ts`. `name` + `nodeId`
+ * are required on create.
+ */
+interface CreateLocationInput {
+    nodeId: string;
+    name: string;
+    description?: string;
+    category?: string;
+    style?: string;
+    workflowId?: string;
+    projectId?: string;
+    sourceImageUrl?: string;
+    /** Persistent image-model id (a MODEL_CATALOG image model). Validated
+     *  server-side — unknown / non-image / "" is stored as `null`. */
+    imageProvider?: string | null;
+    referencePhotos?: LocationReferencePhoto[];
+    canonicalDescription?: string;
+    styleLock?: boolean;
+    /** The user's chosen DEFAULT asset take per variant. OPAQUE
+     *  `"<bucket>:<variant>"` → chosen-URL map; a write REPLACES the whole map.
+     *  Keys stored verbatim; soft-capped server-side at 200 keys / 2048-char values. */
+    selectedAssetByVariant?: Record<string, string>;
+}
+/**
+ * Body for `client.locations.update()`. Mirrors the UPDATE branch of
+ * `upsertLocationBody` in `backend/src/routes/locations.ts`.
+ *
+ * Worker-owned asset buckets (`timeOfDay`/`weather`/`angles`/`lighting`/
+ * `seasons`/`atmosphereMotions`) are deliberately omitted — the route drops
+ * them on UPDATE so a Studio auto-save with a stale snapshot cannot clobber
+ * the worker's atomic `append_location_asset()` writes.
+ *
+ * `expectedUpdatedAt` is the optimistic-concurrency token: when present, the
+ * UPDATE only succeeds if the row's `updated_at` still matches; on mismatch
+ * the route returns 409 so the studio can re-fetch + merge.
+ */
+interface UpdateLocationInput {
+    name?: string;
+    description?: string;
+    category?: string;
+    style?: string;
+    sourceImageUrl?: string;
+    /** Persistent image-model id (a MODEL_CATALOG image model). Validated
+     *  server-side — unknown / non-image / "" is stored as `null`. */
+    imageProvider?: string | null;
+    referencePhotos?: LocationReferencePhoto[];
+    canonicalDescription?: string;
+    styleLock?: boolean;
+    /** The user's chosen DEFAULT asset take per variant. OPAQUE
+     *  `"<bucket>:<variant>"` → chosen-URL map; a write REPLACES the whole map
+     *  (omit to leave untouched). Keys stored verbatim; soft-capped server-side
+     *  at 200 keys / 2048-char values. */
+    selectedAssetByVariant?: Record<string, string>;
+    /** Named Location Boards (see `Location.boards`) — whole-array replace,
+     *  USER-owned (unlike the worker-owned buckets it flows through UPDATE).
+     *  Server caps: 24 boards, 200-char names, 30 sourceImages per board. */
+    boards?: Array<{
+        name: string;
+        url: string;
+        type?: "looks" | "identity";
+        sourceImages?: string[];
+    }>;
+    /** ISO-8601 timestamp recording when PII consent was captured for this location. */
+    piiConsentAt?: string;
+    expectedUpdatedAt?: string;
+}
+interface UpdateLocationResult {
+    id: string;
+    updatedAt: string;
+}
+interface ListLocationsParams {
+    /** When true, return archived locations instead of active ones. */
+    archived?: boolean;
+}
+/**
+ * Input for `client.locations.generate()` — fires the
+ * `POST /v1/generate-location` route. Produces 1–10 candidate
+ * establishing shots; each lands as one `jobs` row in `pending` state and
+ * is then enqueued for the worker.
+ *
+ * When `attachToLocationId` is set AND `count === 1`, the worker writes the
+ * resulting URL directly to `locations.source_image_url` on completion —
+ * caller doesn't need a separate `approveMainImage` call. Multi-candidate
+ * batches MUST go through explicit approval so the user picks the winner.
+ */
+interface GenerateLocationInput {
+    name: string;
+    description?: string;
+    userPrompt?: string;
+    category?: "indoor" | "outdoor" | "urban" | "nature" | "fantasy" | "sci-fi" | "historical" | "futuristic" | "other";
+    style?: "realistic" | "anime" | "3d-pixar" | "illustration";
+    sourceImageUrl?: string;
+    provider?: string;
+    /** Number of candidate images to generate (1–10; server-validated). */
+    count?: number;
+    /** Auto-attach the result to this location row (single-candidate only). */
+    attachToLocationId?: string;
+    /**
+     * Credit-affecting quality tier (e.g. `"high"` for gpt-image). Priced like
+     * generate-image (composite ids such as `gpt-image:high`); values the chosen
+     * model doesn't support are ignored server-side, never rejected.
+     */
+    quality?: string;
+    /**
+     * Credit-affecting output resolution (e.g. `"2K"` / `"4K"` / `"2 MP"`).
+     * Priced like generate-image (composite ids such as `nano-banana-pro:4K`);
+     * values the chosen model doesn't support are ignored server-side, never
+     * rejected.
+     */
+    resolution?: string;
+}
+/**
+ * `generate()` response — `jobIds` is ALWAYS present (the harmonized contract,
+ * matching characters). `jobId` is a deprecated back-compat alias populated only
+ * on `count === 1`; prefer `jobIds`. (Will be removed on the next major.)
+ */
+interface GenerateLocationResult {
+    jobIds: string[];
+    /** @deprecated count===1 back-compat alias — use `jobIds`. */
+    jobId?: string;
+}
+/**
+ * Input for `client.locations.generateAsset()` — fires the
+ * `POST /v1/generate-location-asset` route. Produces a single
+ * timeOfDay / weather / seasons / angles / lighting / custom variant.
+ *
+ * When all three studio-path fields are set (`attachToLocationId` +
+ * `attachToColumn` + `attachName`), the worker appends
+ * `{ name: attachName, url: <result> }` to the named JSONB array column on
+ * the user's location row on completion. `attachToColumn` is REQUIRED for
+ * `assetType === "custom"` — the worker can't infer the bucket from the
+ * asset type.
+ */
+interface GenerateLocationAssetInput {
+    assetType: LocationAssetType;
+    variant: string;
+    name: string;
+    description?: string;
+    userPrompt?: string;
+    category?: string;
+    style?: "realistic" | "anime" | "3d-pixar" | "illustration";
+    sourceImageUrl?: string;
+    provider?: string;
+    /** Optional framing override (the same 4-value enum as `generateMotion`).
+     *  Absent = the image model's default. The studio's 360° surround path pins
+     *  `"16:9"` so every ring view matches the establishing shot's frame. */
+    aspectRatio?: CharacterAspectRatio;
+    attachToLocationId?: string;
+    attachToColumn?: LocationAttachColumn;
+    attachName?: string;
+    /**
+     * Credit-affecting quality tier (e.g. `"high"` for gpt-image). Values the
+     * chosen model doesn't support are ignored server-side, never rejected.
+     */
+    quality?: string;
+    /**
+     * Credit-affecting output resolution (e.g. `"2K"` / `"4K"` / `"2 MP"`).
+     * Values the chosen model doesn't support are ignored server-side, never
+     * rejected.
+     */
+    resolution?: string;
+}
+/**
+ * Input for `client.locations.generateSurroundContinuation()` — fires the
+ * `POST /v1/generate-surround-continuation` route. Generates one seamless 360°
+ * ring view as an image-to-image continuation of `referenceImageUrl` (the
+ * previous ring view, or the establishing shot for the first ring).
+ *
+ * The platform owns the whole pipeline: it builds the half-carry composite
+ * server-side (carry the reference's trailing half into the new frame's leading
+ * half per `direction`, gray the rest), paints the gray region, then
+ * color-harmonizes the painted half to the carried half so there is no tonal
+ * seam down the frame's center. The carried half stays pixel-exact, so a
+ * panorama viewer stitching adjacent ring views stays geometrically seamless.
+ *
+ * When the studio path is set (`attachToLocationId` + `attachToColumn` +
+ * `attachName`), the worker appends `{ name: attachName, url: <result> }` to the
+ * location's bucket (studio uses `attachToColumn: "angles"`,
+ * `attachName: "Surround 45°"`).
+ */
+interface GenerateSurroundContinuationInput {
+    /** The previous ring view to continue from (i2i anchor). */
+    referenceImageUrl: string;
+    /** Carry/paint axis: turn right, turn left, tilt up, or tilt down. Tilts
+     *  render the sky/ground (a thin horizon strip), not a horizontal continuation. */
+    direction: SurroundDirection;
+    /** Ring angle (45, 90, …) — stored on the result as metadata. */
+    degrees?: number;
+    /** Fraction of the frame carried from the reference. Omitted ⇒ per-direction
+     *  default (0.5 for a pan, 0.12 thin strip for a tilt). */
+    carriedFraction?: number;
+    /** Upscale/denoise the result before it's chained as the next reference, to
+     *  slow cumulative softening down a long ring chain. Default false. */
+    refine?: boolean;
+    /** Refine model when `refine` is set. `recraft-upscale` (1 cr, default) or
+     *  `topaz-image-upscale` (3 cr). */
+    refineProvider?: "recraft-upscale" | "topaz-image-upscale";
+    /** Optional free-form scene hint woven into the fill prompt. */
+    userPrompt?: string;
+    /** Image model. Studio pins `nano-banana-pro`; default `nano-banana`. */
+    provider?: string;
+    /** Studio pins `"16:9"` so every ring view matches the establishing frame. */
+    aspectRatio?: CharacterAspectRatio;
+    attachToLocationId?: string;
+    attachToColumn?: LocationAttachColumn;
+    attachName?: string;
+}
+/**
+ * Input for `client.locations.generateMotion()` — fires the
+ * `POST /v1/generate-location-motion` route. Produces a single atmospheric
+ * motion clip (drifting fog, snowfall, rolling waves, etc.) animated FROM a
+ * static establishing-shot image.
+ *
+ * Mirrors `client.characters.generateMotion()` minus the character-specific
+ * fields (gender / baseOutfit / realLifeRefs). The route hardcodes the attach
+ * column to `atmosphere_motions` — callers supply `attachToLocationId` +
+ * `attachName` only.
+ *
+ * `sourceImageUrl` is REQUIRED — image-to-video needs a source frame and the
+ * route has no fallback (no `source_image_url` column to pull from on the
+ * locations row; the studio path supplies the canonical establishing-shot URL
+ * explicitly).
+ *
+ * When the studio path is set (`attachToLocationId` + `attachName`), the
+ * worker appends `{ name: attachName, url: <result> }` to the location row's
+ * `atmosphere_motions` JSONB column on completion.
+ */
+interface GenerateLocationMotionInput {
+    motionPrompt: string;
+    sourceImageUrl: string;
+    provider?: string;
+    name: string;
+    category?: string;
+    style?: "realistic" | "anime" | "3d-pixar" | "illustration";
+    canonicalDescription?: string;
+    attachToLocationId?: string;
+    attachName?: string;
+    /**
+     * Optional aspect ratio override. Defaults to 16:9 server-side via
+     * `resolveLocationAspectRatio` (locations are cinematic establishing shots).
+     * One of the 4-value `CharacterAspectRatio` union — locations reuse the
+     * character aspect enum since the supported ratios are identical.
+     */
+    aspectRatio?: CharacterAspectRatio;
+}
+interface ApproveMainImageResult {
+    sourceImageUrl: string;
+    /**
+     * LLM-authored caption. `null` when the LLM caption sub-failed — the wire
+     * sends `""`, normalized to `null` here so consumers see the same
+     * `string | null` semantics as characters. The main image is still set; call
+     * `recaption()` to retry.
+     */
+    canonicalDescription: string | null;
+}
+interface RecaptionLocationResult {
+    canonicalDescription: string;
+}
+declare class LocationsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * List the caller's locations. By default returns active locations only;
+     * pass `archived: true` to fetch soft-deleted rows for an "archive" view.
+     */
+    list(params?: ListLocationsParams): Promise<{
+        locations: Location[];
+    }>;
+    /**
+     * Convenience wrapper for `list({ archived: true })`. Returns soft-deleted
+     * rows so callers can drive a UI "Archived" tab without re-encoding the
+     * query param. Mirrors `ObjectsResource.listArchived`.
+     *
+     * `archived` is omitted from the param type — it's always set to `true` here.
+     */
+    listArchived(params?: Omit<ListLocationsParams, "archived">): Promise<{
+        locations: Location[];
+    }>;
+    /**
+     * Fetch a single location including in-flight asset job state. Soft-deleted
+     * (archived) rows are returned by id intentionally so canvas nodes that
+     * hold a stale `locationDbId` keep loading.
+     */
+    get(id: string): Promise<LocationDetail>;
+    /**
+     * Create a new location. `name` + `nodeId` are required — the route 400s
+     * otherwise. Returns the new row's id.
+     *
+     * Note: the underlying route is the same `POST /v1/locations` upsert that
+     * powers `update()`. This convenience wrapper enforces the INSERT-required
+     * fields at the type level and never sends an `id`.
+     */
+    create(data: CreateLocationInput): Promise<{
+        id: string;
+    }>;
+    /**
+     * Update a location. Only the fields you pass are written — undefined keys
+     * are NOT touched on the row. Worker-owned asset buckets are intentionally
+     * not exposed on this surface (see `UpdateLocationInput` for the rationale).
+     *
+     * Optimistic-concurrency: pass `expectedUpdatedAt` to require the row's
+     * `updated_at` still matches; on mismatch the route returns 409
+     * `concurrent_modification`. The SDK surfaces that as a generic
+     * `NodaroError` with the same code.
+     */
+    update(id: string, data: UpdateLocationInput): Promise<UpdateLocationResult>;
+    /**
+     * Soft-delete (archive) a location. The row is hidden from `list()` by
+     * default but still loadable via `get(id)` so canvas nodes pointing at it
+     * keep working. Restore with `restore(id)`.
+     */
+    delete(id: string): Promise<{
+        success: true;
+        archived: true;
+    }>;
+    /**
+     * Un-archive a location. If the original name now collides (case-
+     * insensitive) with an active row, the server auto-suffixes "(restored)"
+     * and returns the effective name.
+     */
+    restore(id: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * Fire `POST /v1/generate-location` to produce one or more candidate main
+     * images. With `count > 1`, all jobs are reserved up-front before any
+     * is enqueued — mid-batch failures roll back atomically.
+     *
+     * When `attachToLocationId` is set AND `count === 1`, the worker writes
+     * the result directly to the row's `source_image_url`; otherwise you must
+     * call `approveMainImage()` after picking a candidate.
+     */
+    generate(data: GenerateLocationInput): Promise<GenerateLocationResult>;
+    /**
+     * Fire `POST /v1/generate-location-asset` to produce a single variant.
+     * When the studio path is set (`attachToLocationId` + `attachToColumn` +
+     * `attachName`), the worker appends `{ name: attachName, url: <result> }`
+     * to the named JSONB array column on completion.
+     */
+    generateAsset(data: GenerateLocationAssetInput): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Fire `POST /v1/generate-surround-continuation` to produce one seamless 360°
+     * ring view as an i2i continuation of `referenceImageUrl`. The platform builds
+     * the half-carry composite, paints the missing half, and color-harmonizes it
+     * to the carried half (no tonal seam; carried half stays pixel-exact). When the
+     * studio path is set, the worker appends the result to the location's bucket.
+     */
+    generateSurroundContinuation(data: GenerateSurroundContinuationInput): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Fire `POST /v1/generate-location-motion` to animate the location's
+     * establishing shot into an atmospheric motion clip. Image-to-video, single
+     * clip per call; the attach column is hardcoded to `atmosphere_motions`
+     * server-side (locations have a single motion bucket so the caller doesn't
+     * supply `attachToColumn`). When the studio path is set
+     * (`attachToLocationId` + `attachName`), the worker appends
+     * `{ name: attachName, url: <result> }` to the row's `atmosphere_motions`
+     * column on completion.
+     */
+    generateMotion(data: GenerateLocationMotionInput): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Atomically remove ONE asset take (every entry matching `url`) from a
+     * worker-owned bucket column — `POST /v1/locations/:id/remove-asset`. The
+     * worker-owned buckets are deliberately not writable through `update()`
+     * (a stale snapshot would race concurrent worker appends), so deleting a
+     * take — e.g. a 360° surround view being regenerated — goes through this
+     * single-statement server-side filter instead. 404s (`NotFoundError`) when
+     * the url isn't in that bucket or the location isn't yours.
+     */
+    removeAsset(id: string, data: {
+        column: LocationAttachColumn;
+        url: string;
+    }): Promise<{
+        removed: true;
+    }>;
+    /**
+     * Approve a completed `generate-location` job as the location's main image.
+     * Sets `source_image_url` and fires the LLM caption (Claude Sonnet vision)
+     * inline. Returns the new main-image URL plus the caption.
+     *
+     * Caption-failure semantics: the route still sends `""` on LLM sub-failure,
+     * but the SDK normalizes `""` → `null` here so `canonicalDescription` carries
+     * the same `string | null` semantics as characters. The main image is still
+     * set; call `recaption()` to retry.
+     */
+    approveMainImage(id: string, candidateJobId: string): Promise<ApproveMainImageResult>;
+    /**
+     * Re-fire the LLM caption against the location's current main image. 502s
+     * on LLM failure (unlike `approveMainImage` which preserves the side-effect
+     * and returns ""); returns 400 `no_source_image` if no main image is set
+     * yet.
+     */
+    recaption(id: string): Promise<RecaptionLocationResult>;
+}
+
+/**
+ * Re-export the shared `ObjectAssetType` / `ObjectAttachColumn` unions and
+ * their runtime tuples so SDK consumers don't have to add `@nodaro/shared` as
+ * a second dependency just to typecheck the `assetType` / `attachToColumn`
+ * fields. Single source of truth lives in `@nodaro/shared/entity-prompts`.
+ *
+ * `ObjectAspectRatio` is re-exported alongside them — `generateMotion`'s
+ * `aspectRatio` field is the 5-value object enum (1:1 / 3:4 / 16:9 / 9:16 /
+ * 4:3) from `@nodaro/shared/object-aspect-defaults`. Distinct from
+ * `CharacterAspectRatio` because objects support an extra 4:3 framing for
+ * product-showcase shots.
+ */
+/**
+ * Reference-photo kind discriminator — the mood-board roles a user can attach
+ * to an object. Mirrors the `reference_photos.kind` field accepted by
+ * `backend/src/routes/objects.ts` (the route accepts open strings; this SDK
+ * type narrows to the 6 canonical roles surfaced by the Studio). `other` is
+ * the free-form bucket.
+ */
+type ObjectReferencePhotoKind = "front" | "side" | "detail" | "context" | "moodBoard" | "other";
+interface ObjectReferencePhoto {
+    url: string;
+    kind: ObjectReferencePhotoKind;
+}
+/**
+ * An object record returned by Nodaro's REST API. Mirrors the camelCase
+ * shape produced by `backend/src/routes/objects.ts::toCamel()`.
+ *
+ * Asset buckets (`angles`, `materials`, `variations`, `motionClips`) are
+ * independent JSONB arrays keyed by a human-readable variant name (e.g.
+ * `"front"`, `"wood"`, `"weathered"`). Each entry's `url` points at an
+ * R2-hosted asset.
+ *
+ * Identity-foundation fields:
+ *   - `referencePhotos` — caller-supplied mood-board refs (cap 20). Objects
+ *     do NOT carry a `piiConsentAt` field (location Phase 2 #7 only).
+ *   - `canonicalDescription` — ~80–120-word LLM-authored visual caption,
+ *     populated by `approveMainImage()` / `recaption()`. The wire still sends
+ *     `""` on caption sub-failure (the breaking wire change is deferred to a
+ *     major bump), but `get()` normalizes `""` → `null` so consumers see the
+ *     same `string | null` semantics as characters.
+ *   - `styleLock` — whether asset gens should anchor to the canonical style
+ *     captured at approval time. Defaults to `true` on new rows.
+ *
+ * `Object` shadows the JS global, which TypeScript handles cleanly via
+ * local-scope resolution. Consumers who need both can alias as
+ * `import type { Object as NodaroObject } from "@nodaro/sdk"`.
+ */
+interface Object$1 {
+    id: string;
+    userId: string;
+    nodeId: string;
+    projectId: string | null;
+    name: string;
+    description: string | null;
+    category: string | null;
+    style: string | null;
+    sourceImageUrl: string | null;
+    /** MODEL_CATALOG image-model id the main image was generated with (or `null`).
+     *  Set on create + editable via the update route. */
+    imageProvider: string | null;
+    angles: Array<{
+        name: string;
+        url: string;
+    }>;
+    materials: Array<{
+        name: string;
+        url: string;
+    }>;
+    variations: Array<{
+        name: string;
+        url: string;
+    }>;
+    motionClips: Array<{
+        name: string;
+        url: string;
+    }>;
+    /** Named Product Boards — dense reference sheets, one per variant/colorway
+     *  (the `generate-image/product-board` factory preset rendered from the
+     *  object's images). A first-class bucket: community publish snapshots it
+     *  and clone hands the consumer their own copy to extend. Defaults to `[]`.
+     *  `type` marks an image-collage `"identity"` sheet vs a plain `"looks"`
+     *  board; `sourceImages` are the R2 URLs it was collaged from. Both optional
+     *  + backward-compatible (legacy boards have neither). */
+    boards?: Array<{
+        name: string;
+        url: string;
+        type?: "looks" | "identity";
+        sourceImages?: string[];
+    }> | null;
+    referencePhotos: ObjectReferencePhoto[];
+    /** `null` when no caption is set (or the LLM caption sub-failed) — the wire
+     *  sends `""`, normalized to `null` in `get()` to match character semantics. */
+    canonicalDescription: string | null;
+    styleLock: boolean;
+    /** The user's chosen DEFAULT asset take per variant (Studio version history).
+     *  OPAQUE map: key `"<bucket>:<variant>"` (e.g. `"angles:front"`) → the chosen
+     *  asset URL (one already present in that bucket). Stored verbatim — keys are
+     *  NOT normalized; soft-capped server-side at 200 keys / 2048-char values
+     *  (overflow dropped silently). Defaults to `{}`. */
+    selectedAssetByVariant?: Record<string, string> | null;
+    deletedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * GET /v1/objects/:id may append a `pendingJobs` bucket the studio uses to
+ * rehydrate spinners after a reload. Optional on the SDK surface — it doesn't
+ * appear on `list()` rows.
+ */
+interface ObjectDetail extends Object$1 {
+    pendingJobs?: Array<{
+        jobId: string;
+        assetType: string;
+        name: string;
+        status: string;
+    }>;
+}
+/**
+ * Body for `client.objects.create()`. Mirrors the INSERT branch of
+ * `upsertObjectBody` in `backend/src/routes/objects.ts`. `name` + `nodeId`
+ * are required on create.
+ */
+interface CreateObjectInput {
+    nodeId: string;
+    name: string;
+    description?: string;
+    category?: ObjectCategory;
+    style?: string;
+    workflowId?: string;
+    projectId?: string;
+    sourceImageUrl?: string;
+    /** Persistent image-model id (a MODEL_CATALOG image model). Validated
+     *  server-side — unknown / non-image / "" is stored as `null`. */
+    imageProvider?: string | null;
+    referencePhotos?: ObjectReferencePhoto[];
+    canonicalDescription?: string;
+    styleLock?: boolean;
+    /** The user's chosen DEFAULT asset take per variant. OPAQUE
+     *  `"<bucket>:<variant>"` → chosen-URL map; a write REPLACES the whole map.
+     *  Keys stored verbatim; soft-capped server-side at 200 keys / 2048-char values. */
+    selectedAssetByVariant?: Record<string, string>;
+}
+/**
+ * The 10-value Object category enum. Mirrors the literal accepted by
+ * `POST /v1/generate-object` and surfaced in the Object Studio category
+ * picker. Distinct from location's geography-based set.
+ */
+type ObjectCategory = "furniture" | "vehicle" | "weapon" | "food" | "clothing" | "electronics" | "nature" | "tool" | "animal" | "other";
+/**
+ * Body for `client.objects.update()`. Mirrors the UPDATE branch of
+ * `upsertObjectBody` in `backend/src/routes/objects.ts`.
+ *
+ * Worker-owned asset buckets (`angles` / `materials` / `variations` /
+ * `motionClips`) are deliberately omitted — the route drops them on UPDATE
+ * so a Studio auto-save with a stale snapshot cannot clobber the worker's
+ * atomic `append_object_asset()` writes.
+ *
+ * `expectedUpdatedAt` is the optimistic-concurrency token: when present, the
+ * UPDATE only succeeds if the row's `updated_at` still matches; on mismatch
+ * the route returns 409 so the studio can re-fetch + merge.
+ */
+interface UpdateObjectInput {
+    name?: string;
+    description?: string;
+    category?: ObjectCategory;
+    style?: string;
+    sourceImageUrl?: string;
+    /** Persistent image-model id (a MODEL_CATALOG image model). Validated
+     *  server-side — unknown / non-image / "" is stored as `null`. */
+    imageProvider?: string | null;
+    referencePhotos?: ObjectReferencePhoto[];
+    canonicalDescription?: string;
+    styleLock?: boolean;
+    /** The user's chosen DEFAULT asset take per variant. OPAQUE
+     *  `"<bucket>:<variant>"` → chosen-URL map; a write REPLACES the whole map
+     *  (omit to leave untouched). Keys stored verbatim; soft-capped server-side
+     *  at 200 keys / 2048-char values. */
+    selectedAssetByVariant?: Record<string, string>;
+    /** Named Product Boards (see `Object.boards`) — whole-array replace,
+     *  USER-owned (unlike the worker-owned buckets it flows through UPDATE).
+     *  Server caps: 24 boards, 200-char names, 30 sourceImages per board. */
+    boards?: Array<{
+        name: string;
+        url: string;
+        type?: "looks" | "identity";
+        sourceImages?: string[];
+    }>;
+    expectedUpdatedAt?: string;
+}
+interface UpdateObjectResult {
+    id: string;
+    updatedAt: string;
+}
+/**
+ * Combined create + update body (parameter for both branches). Exported for
+ * callers that want to drive a single `upsert` flow without picking between
+ * `Create*` and `Update*`. Mirrors the `upsertObjectBody` Zod schema in
+ * `backend/src/routes/objects.ts`. `nodeId` + `name` are required on INSERT;
+ * `id` flips the route into UPDATE mode.
+ */
+interface UpsertObjectInput extends CreateObjectInput {
+    id?: string;
+    expectedUpdatedAt?: string;
+}
+type UpsertObjectResult = {
+    id: string;
+} | UpdateObjectResult;
+interface ListObjectsParams {
+    /** When true, return archived objects instead of active ones. */
+    archived?: boolean;
+    /** Optional project filter — server-scoped to the caller's user. */
+    projectId?: string;
+}
+/**
+ * Input for `client.objects.generate()` — fires the
+ * `POST /v1/generate-object` route. Produces 1–10 candidate
+ * main images; each lands as one `jobs` row in `pending` state and is then
+ * enqueued for the worker.
+ *
+ * When `attachToObjectId` is set AND `count === 1`, the worker writes the
+ * resulting URL directly to `objects.source_image_url` on completion —
+ * caller doesn't need a separate `approveMainImage` call. Multi-candidate
+ * batches MUST go through explicit approval so the user picks the winner.
+ *
+ * `seedPromptHint` (Pass 7 F-77) flows the parameter-picker's prompt fragment
+ * through to the worker so a catalog selection (e.g. "antique brass lantern")
+ * gets appended to the generated prompt context.
+ */
+interface GenerateObjectInput {
+    name: string;
+    description?: string;
+    userPrompt?: string;
+    category?: ObjectCategory;
+    style?: "realistic" | "anime" | "3d-pixar" | "illustration";
+    sourceImageUrl?: string;
+    provider?: string;
+    /** Number of candidate images to generate (1–10; server-validated). */
+    count?: number;
+    /** Auto-attach the result to this object row (single-candidate only). */
+    attachToObjectId?: string;
+    /** Parameter-picker prompt-fragment pass-through. */
+    seedPromptHint?: string;
+    /** Optional name to set on the attached row alongside the main image. */
+    attachName?: string;
+    /** Optimistic-concurrency token for the single-candidate auto-attach path. */
+    expectedUpdatedAt?: string;
+}
+/**
+ * `generate()` response — `jobIds` is ALWAYS present (the harmonized contract,
+ * matching characters). `jobId` is a deprecated back-compat alias populated only
+ * on `count === 1`; prefer `jobIds`. (Will be removed on the next major.)
+ */
+interface GenerateObjectResult {
+    jobIds: string[];
+    /** @deprecated count===1 back-compat alias — use `jobIds`. */
+    jobId?: string;
+}
+/**
+ * Input for `client.objects.generateAsset()` — fires the
+ * `POST /v1/generate-object-asset` route. Produces a single
+ * angles / materials / variations / custom variant.
+ *
+ * When all three studio-path fields are set (`attachToObjectId` +
+ * `attachToColumn` + `attachName`), the worker appends
+ * `{ name: attachName, url: <result> }` to the named JSONB array column on
+ * the user's object row on completion. `attachToColumn` is REQUIRED for
+ * `assetType === "custom"` — the worker can't infer the bucket from the
+ * asset type.
+ */
+interface GenerateObjectAssetInput {
+    assetType: ObjectAssetType;
+    variant: string;
+    name: string;
+    description?: string;
+    userPrompt?: string;
+    category?: string;
+    style?: "realistic" | "anime" | "3d-pixar" | "illustration";
+    sourceImageUrl?: string;
+    provider?: string;
+    attachToObjectId?: string;
+    attachToColumn?: ObjectAttachColumn;
+    attachName?: string;
+    /** Parameter-picker prompt-fragment pass-through (Pass 7 F-77). */
+    seedPromptHint?: string;
+}
+interface GenerateObjectAssetResult {
+    jobId: string;
+}
+/**
+ * Input for `client.objects.generateMotion()` — fires the
+ * `POST /v1/generate-object-motion` route. Produces a single motion clip
+ * (rotation, orbit, hover, drift, etc.) animated FROM a static product-shot
+ * image.
+ *
+ * Mirrors `client.locations.generateMotion()` minus the location-specific
+ * atmospheric fields. The route hardcodes the attach column to `motion_clips`
+ * — callers supply `attachToObjectId` + `attachName` only.
+ *
+ * `sourceImageUrl` is REQUIRED — image-to-video needs a source frame and the
+ * route has no fallback (no `source_image_url` column to pull from on the
+ * objects row at this point in the flow; the studio path supplies the
+ * canonical product-shot URL explicitly).
+ *
+ * Object-specific defaults vs location:
+ *   - `provider` defaults to `"kling-turbo"` (not location's `"kling"`)
+ *   - `aspectRatio` defaults to `"1:1"` server-side via
+ *     `resolveObjectAspectRatio({ assetType: "motion" })` — objects are
+ *     product-showcase framing, not cinematic establishing shots.
+ *
+ * When the studio path is set (`attachToObjectId` + `attachName`), the
+ * worker appends `{ name: attachName, url: <result> }` to the object row's
+ * `motion_clips` JSONB column on completion.
+ */
+interface GenerateObjectMotionInput {
+    motionPrompt: string;
+    sourceImageUrl: string;
+    provider?: string;
+    name: string;
+    /** Source clip URL — when set, worker routes to video-to-video refine. */
+    refineFromVideoUrl?: string;
+    category?: string;
+    style?: "realistic" | "anime" | "3d-pixar" | "illustration";
+    canonicalDescription?: string;
+    /** Parameter-picker prompt-fragment pass-through (Pass 7 F-77). */
+    seedPromptHint?: string;
+    attachToObjectId?: string;
+    attachName?: string;
+    /**
+     * Optional aspect ratio override. Defaults to 1:1 server-side. One of the
+     * 5-value `ObjectAspectRatio` union (1:1 / 3:4 / 16:9 / 9:16 / 4:3) —
+     * objects have their own enum (with 4:3 added) vs the character set.
+     */
+    aspectRatio?: ObjectAspectRatio;
+    /**
+     * Optional clip duration in seconds. Validated server-side against the chosen
+     * provider's allowed durations (e.g. kling 5/10, wan-i2v 5/10/15); omitted →
+     * the model's own default (no behavior change). Mirrors generate-video's
+     * per-model i2v duration lever.
+     */
+    duration?: number;
+}
+interface GenerateObjectMotionResult {
+    jobId: string;
+}
+interface ApproveObjectMainImageResult {
+    sourceImageUrl: string;
+    /**
+     * LLM-authored caption. `null` when the LLM caption sub-failed — the wire
+     * sends `""`, normalized to `null` here so consumers see the same
+     * `string | null` semantics as characters. The main image is still set; call
+     * `recaption()` to retry.
+     */
+    canonicalDescription: string | null;
+}
+interface RecaptionObjectResult {
+    canonicalDescription: string;
+}
+declare class ObjectsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * List the caller's objects. By default returns active objects only;
+     * pass `archived: true` to fetch soft-deleted rows for an "archive" view.
+     * Optional `projectId` scopes the result to a single project.
+     */
+    list(params?: ListObjectsParams): Promise<{
+        objects: Object$1[];
+    }>;
+    /**
+     * Convenience wrapper for `list({ archived: true })`. Returns soft-deleted
+     * rows so callers can drive a UI "Archived" tab without re-encoding the
+     * query param.
+     *
+     * `archived` is omitted from the param type — it's always set to `true` here.
+     */
+    listArchived(params?: Omit<ListObjectsParams, "archived">): Promise<{
+        objects: Object$1[];
+    }>;
+    /**
+     * Fetch a single object including in-flight asset job state. Soft-deleted
+     * (archived) rows are NOT returned by id — the route enforces
+     * `deleted_at IS NULL` so archived objects 404 (uniform Pass 10 F-90b
+     * "not_found" — does not leak the deleted vs non-existent distinction).
+     */
+    get(id: string): Promise<ObjectDetail>;
+    /**
+     * Create a new object. `name` + `nodeId` are required — the route 400s
+     * otherwise. Returns the new row's id.
+     *
+     * Note: the underlying route is the same `POST /v1/objects` upsert that
+     * powers `update()`. This convenience wrapper enforces the INSERT-required
+     * fields at the type level and never sends an `id`.
+     */
+    create(data: CreateObjectInput): Promise<{
+        id: string;
+    }>;
+    /**
+     * Update an object. Only the fields you pass are written — undefined keys
+     * are NOT touched on the row. Worker-owned asset buckets are intentionally
+     * not exposed on this surface (see `UpdateObjectInput` for the rationale).
+     *
+     * Optimistic-concurrency: pass `expectedUpdatedAt` to require the row's
+     * `updated_at` still matches; on mismatch the route returns 409
+     * `concurrent_modification` carrying the fresh `updatedAt`. The SDK
+     * surfaces that as a generic `NodaroError` with the same code (per Phase
+     * E1 calibration finding — error centralization in `throwApiError`).
+     */
+    update(id: string, data: UpdateObjectInput): Promise<UpdateObjectResult>;
+    /**
+     * Soft-delete (archive) an object. The row is hidden from `list()` by
+     * default but recoverable via `restore(id)` or visible under
+     * `listArchived()`. Idempotent — repeating a delete on an already-archived
+     * row is a no-op.
+     */
+    delete(id: string): Promise<{
+        success: true;
+        archived: true;
+    }>;
+    /**
+     * Hard-delete (permanent) an object — the row + every R2 asset it
+     * references. Archived rows ONLY: active objects return 400 `not_archived`.
+     * Call `delete()` first to archive, then `permanentDelete()` to destroy.
+     *
+     * Mirrors the `app_runs` permanent-delete pattern (archive-first) so a
+     * stray SDK / curl caller cannot bypass the studio's archive-first UI
+     * flow.
+     */
+    permanentDelete(id: string): Promise<{
+        success: true;
+        permanent: true;
+    }>;
+    /**
+     * Un-archive an object. If the original name now collides (case-
+     * insensitive) with an active row, the server auto-suffixes "(restored)"
+     * and returns the effective name.
+     */
+    restore(id: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * Fire `POST /v1/generate-object` to produce one or more candidate main
+     * images. With `count > 1`, all jobs are reserved up-front before any
+     * is enqueued — mid-batch failures roll back atomically.
+     *
+     * When `attachToObjectId` is set AND `count === 1`, the worker writes
+     * the result directly to the row's `source_image_url`; otherwise you must
+     * call `approveMainImage()` after picking a candidate.
+     */
+    generate(data: GenerateObjectInput): Promise<GenerateObjectResult>;
+    /**
+     * Fire `POST /v1/generate-object-asset` to produce a single variant.
+     * When the studio path is set (`attachToObjectId` + `attachToColumn` +
+     * `attachName`), the worker appends `{ name: attachName, url: <result> }`
+     * to the named JSONB array column on completion.
+     *
+     * Note: `attachToColumn` is REQUIRED for `assetType === "custom"` — the
+     * worker can't infer the bucket from the asset type. For canonical asset
+     * types (`angles` / `materials` / `variations` / `motion`), the column is
+     * derived automatically by the route.
+     */
+    generateAsset(data: GenerateObjectAssetInput): Promise<GenerateObjectAssetResult>;
+    /**
+     * Fire `POST /v1/generate-object-motion` to animate the object's main
+     * image into a motion clip. Image-to-video, single clip per call; the
+     * attach column is hardcoded to `motion_clips` server-side (objects have a
+     * single motion bucket so the caller doesn't supply `attachToColumn`).
+     * When the studio path is set (`attachToObjectId` + `attachName`), the
+     * worker appends `{ name: attachName, url: <result> }` to the row's
+     * `motion_clips` column on completion.
+     *
+     * Defaults: `provider` → `"kling-turbo"`, `aspectRatio` → `"1:1"` (set
+     * server-side via `resolveObjectAspectRatio({ assetType: "motion" })`).
+     */
+    generateMotion(data: GenerateObjectMotionInput): Promise<GenerateObjectMotionResult>;
+    /**
+     * Approve a completed `generate-object` job as the object's main image.
+     * Sets `source_image_url` and fires the LLM caption (Claude Sonnet vision)
+     * inline. Returns the new main-image URL plus the caption.
+     *
+     * Caption-failure semantics: the route still sends `""` on LLM sub-failure,
+     * but the SDK normalizes `""` → `null` here so `canonicalDescription` carries
+     * the same `string | null` semantics as characters. The main image is still
+     * set; call `recaption()` to retry.
+     *
+     * Optimistic-concurrency: pass `expectedUpdatedAt` to gate the update on
+     * the row's current `updated_at`; on mismatch the route returns 409
+     * `concurrent_modification` carrying the fresh token.
+     */
+    approveMainImage(id: string, candidateJobId: string, expectedUpdatedAt?: string): Promise<ApproveObjectMainImageResult>;
+    /**
+     * Re-fire the LLM caption against the object's current main image. 502s
+     * on LLM failure (unlike `approveMainImage` which preserves the side-effect
+     * and returns ""); returns 400 `main_image_required` if no main image is
+     * set yet.
+     *
+     * The route is a pure idempotent retry — it does NOT accept an
+     * `expectedUpdatedAt` token (per Phase E1 calibration finding: backend
+     * route is idempotent retry, not gated on optimistic-concurrency).
+     */
+    recaption(id: string): Promise<RecaptionObjectResult>;
+}
+
+/**
+ * Creature voice — IDENTICAL shape + semantics to `Character["voice"]` (the
+ * "talking creature" stack reuses the character voice plumbing verbatim).
+ * Render speech via `client.nodes.run("text-to-speech", { text, voice:
+ * voiceId, provider: ttsProvider, voiceType })`, then feed the audio + the
+ * creature's `sourceImageUrl` to `client.nodes.run("lip-sync", …)` (or
+ * speech-to-video) for a talking-creature clip.
+ */
+interface CreatureVoice {
+    voiceId: string;
+    voiceName: string;
+    traits: string;
+    voiceType?: "premade" | "library" | "custom";
+    /** Playable preview sample (client-played only). */
+    previewUrl?: string;
+    /** Recommended TTS provider — send as `provider` on text-to-speech. */
+    ttsProvider?: TtsProvider;
+}
+/**
+ * Re-export the shared `CreatureAttachColumn` union + its runtime tuple so SDK
+ * consumers don't have to add `@nodaro/shared` as a second dependency just to
+ * typecheck the `attachToColumn` field. Single source of truth lives in
+ * `@nodaro/shared/entity-prompts` (`CREATURE_ATTACH_COLUMNS`).
+ *
+ * `CreatureAspectRatio` is re-exported as an alias of the shared
+ * `ObjectAspectRatio` — `generateMotion`'s `aspectRatio` field is the 5-value
+ * object enum (1:1 / 3:4 / 16:9 / 9:16 / 4:3). The creature motion route
+ * deliberately REUSES `OBJECT_ASPECT_OPTIONS` server-side (a creature reference
+ * clip is centered product-showcase framing, not cinematic 16:9), so the SDK
+ * surfaces the same enum under a creature-friendly name. The runtime tuple is
+ * re-exported as `CREATURE_ASPECT_OPTIONS` / `CREATURE_ASPECT_DEFAULTS` aliases.
+ */
+/**
+ * Creature asset-type enum — the kinds of variant a user can generate off a
+ * creature's anchor main image. Mirrors the literal accepted by
+ * `POST /v1/generate-creature-asset` (`backend/src/routes/generate-creature-asset.ts`).
+ *
+ * Delta vs `ObjectAssetType`: object's `materials` becomes `poses` (a creature
+ * has poses, not materials), and there is NO `motion` value — creature motion
+ * variants flow through the dedicated `/v1/generate-creature-motion` endpoint
+ * (worker-side a different BullMQ job type). `custom` is the free-form bucket;
+ * callers must supply `attachToColumn` explicitly since the worker can't infer
+ * the destination from the asset type.
+ *
+ * The shared `@nodaro/shared` package does NOT export a `CREATURE_ASSET_TYPES`
+ * tuple (the route validates an inline Zod enum), so the SDK defines its own
+ * single-source-of-truth tuple here.
+ */
+declare const CREATURE_ASSET_TYPES: readonly ["angles", "poses", "variations", "custom"];
+type CreatureAssetType = (typeof CREATURE_ASSET_TYPES)[number];
+/**
+ * Reference-photo kind discriminator — the mood-board roles a user can attach
+ * to a creature. Mirrors the `reference_photos.kind` field accepted by
+ * `backend/src/routes/creatures.ts` (the route accepts open strings; this SDK
+ * type narrows to the 6 canonical roles surfaced by the Studio). `other` is
+ * the free-form bucket.
+ */
+type CreatureReferencePhotoKind = "front" | "side" | "detail" | "context" | "moodBoard" | "other";
+interface CreatureReferencePhoto {
+    url: string;
+    kind: CreatureReferencePhotoKind;
+}
+/**
+ * A creature record returned by Nodaro's REST API. Mirrors the camelCase
+ * shape produced by `backend/src/routes/creatures.ts::toCamel()`.
+ *
+ * Asset buckets (`angles`, `poses`, `variations`, `motionClips`) are
+ * independent JSONB arrays keyed by a human-readable variant name (e.g.
+ * `"front"`, `"walking"`, `"scarred"`). Each entry's `url` points at an
+ * R2-hosted asset.
+ *
+ * Creature delta vs object:
+ *   - `species` — free-text creature type (e.g. `"dragon"`, `"wolf"`). This is
+ *     the subject of the establishing-shot prompt and the primary creature
+ *     differentiator (object has no equivalent).
+ *   - `poses` (where object has `materials`) — the pose-variant asset bucket.
+ *   - `category` is free-text (NOT object's fixed 10-value enum) — a creature
+ *     can be any animal/type.
+ *
+ * Identity-foundation fields:
+ *   - `referencePhotos` — caller-supplied mood-board refs (cap 20).
+ *   - `canonicalDescription` — ~80–120-word LLM-authored visual caption,
+ *     populated by `approveMainImage()` / `recaption()`. The wire still sends
+ *     `""` on caption sub-failure, but `get()` normalizes `""` → `null` so
+ *     consumers see the same `string | null` semantics as characters.
+ *   - `styleLock` — whether asset gens should anchor to the canonical style
+ *     captured at approval time. Defaults to `true` on new rows.
+ */
+interface Creature {
+    id: string;
+    userId: string;
+    nodeId: string;
+    projectId: string | null;
+    name: string;
+    description: string | null;
+    /** Free-text creature type/species (e.g. "dragon", "wolf") — the creature
+     *  delta vs object. `null` when unset. */
+    species: string | null;
+    category: string | null;
+    style: string | null;
+    sourceImageUrl: string | null;
+    /** MODEL_CATALOG image-model id the main image was generated with (or `null`).
+     *  Set on create + editable via the update route. */
+    imageProvider: string | null;
+    angles: Array<{
+        name: string;
+        url: string;
+    }>;
+    poses: Array<{
+        name: string;
+        url: string;
+    }>;
+    variations: Array<{
+        name: string;
+        url: string;
+    }>;
+    motionClips: Array<{
+        name: string;
+        url: string;
+    }>;
+    /** Named Creature Boards — dense reference sheets, one per variant/mood
+     *  (the `generate-image/creature-board` factory preset rendered from the
+     *  creature's images). A first-class bucket: community publish snapshots it
+     *  and clone hands the consumer their own copy to extend. Defaults to `[]`.
+     *  `type` marks an image-collage `"identity"` sheet vs a plain `"looks"`
+     *  board; `sourceImages` are the R2 URLs it was collaged from. Both optional
+     *  + backward-compatible (legacy boards have neither). */
+    boards?: Array<{
+        name: string;
+        url: string;
+        type?: "looks" | "identity";
+        sourceImages?: string[];
+    }> | null;
+    /** The creature's voice (the "talking creature" stack) — same shape and
+     *  flow as `Character["voice"]`. `null` when no voice is selected. */
+    voice?: CreatureVoice | null;
+    referencePhotos: CreatureReferencePhoto[];
+    /** `null` when no caption is set (or the LLM caption sub-failed) — the wire
+     *  sends `""`, normalized to `null` in `get()` to match character semantics. */
+    canonicalDescription: string | null;
+    styleLock: boolean;
+    /** The user's chosen DEFAULT asset take per variant (Studio version history).
+     *  OPAQUE map: key `"<bucket>:<variant>"` (e.g. `"angles:front"`) → the chosen
+     *  asset URL (one already present in that bucket). Stored verbatim — keys are
+     *  NOT normalized; soft-capped server-side at 200 keys / 2048-char values
+     *  (overflow dropped silently). Defaults to `{}`. */
+    selectedAssetByVariant?: Record<string, string> | null;
+    deletedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * GET /v1/creatures/:id may append a `pendingJobs` bucket the studio uses to
+ * rehydrate spinners after a reload. Optional on the SDK surface — it doesn't
+ * appear on `list()` rows.
+ */
+interface CreatureDetail extends Creature {
+    pendingJobs?: Array<{
+        jobId: string;
+        assetType: string;
+        name: string;
+        status: string;
+    }>;
+}
+/**
+ * Body for `client.creatures.create()`. Mirrors the INSERT branch of
+ * `upsertCreatureBody` in `backend/src/routes/creatures.ts`. `name` + `nodeId`
+ * are required on create.
+ */
+interface CreateCreatureInput {
+    nodeId: string;
+    name: string;
+    description?: string;
+    /** Free-text creature type/species (the creature delta vs object). */
+    species?: string;
+    /** Free-text category (NOT object's fixed enum — a creature can be anything). */
+    category?: string;
+    style?: string;
+    workflowId?: string;
+    projectId?: string;
+    sourceImageUrl?: string;
+    /** Persistent image-model id (a MODEL_CATALOG image model). Validated
+     *  server-side — unknown / non-image / "" is stored as `null`. */
+    imageProvider?: string | null;
+    referencePhotos?: CreatureReferencePhoto[];
+    canonicalDescription?: string;
+    styleLock?: boolean;
+    /** The user's chosen DEFAULT asset take per variant. OPAQUE
+     *  `"<bucket>:<variant>"` → chosen-URL map; a write REPLACES the whole map.
+     *  Keys stored verbatim; soft-capped server-side at 200 keys / 2048-char values. */
+    selectedAssetByVariant?: Record<string, string>;
+    /** Initial voice selection (see `CreatureVoice`). Omit for a voiceless creature. */
+    voice?: CreatureVoice | null;
+}
+/**
+ * Body for `client.creatures.update()`. Mirrors the UPDATE branch of
+ * `upsertCreatureBody` in `backend/src/routes/creatures.ts`.
+ *
+ * Worker-owned asset buckets (`angles` / `poses` / `variations` /
+ * `motionClips`) are deliberately omitted — the route drops them on UPDATE
+ * so a Studio auto-save with a stale snapshot cannot clobber the worker's
+ * atomic `append_creature_asset()` writes.
+ *
+ * `expectedUpdatedAt` is the optimistic-concurrency token: when present, the
+ * UPDATE only succeeds if the row's `updated_at` still matches; on mismatch
+ * the route returns 409 so the studio can re-fetch + merge.
+ */
+interface UpdateCreatureInput {
+    name?: string;
+    description?: string;
+    /** Free-text creature type/species (the creature delta vs object). */
+    species?: string;
+    category?: string;
+    style?: string;
+    sourceImageUrl?: string;
+    /** Persistent image-model id (a MODEL_CATALOG image model). Validated
+     *  server-side — unknown / non-image / "" is stored as `null`. */
+    imageProvider?: string | null;
+    referencePhotos?: CreatureReferencePhoto[];
+    canonicalDescription?: string;
+    styleLock?: boolean;
+    /** The user's chosen DEFAULT asset take per variant. OPAQUE
+     *  `"<bucket>:<variant>"` → chosen-URL map; a write REPLACES the whole map
+     *  (omit to leave untouched). Keys stored verbatim; soft-capped server-side
+     *  at 200 keys / 2048-char values. */
+    selectedAssetByVariant?: Record<string, string>;
+    /** Named Creature Boards (see `Creature.boards`) — whole-array replace,
+     *  USER-owned (unlike the worker-owned buckets it flows through UPDATE).
+     *  Server caps: 24 boards, 200-char names, 30 sourceImages per board. */
+    boards?: Array<{
+        name: string;
+        url: string;
+        type?: "looks" | "identity";
+        sourceImages?: string[];
+    }>;
+    /** Voice selection (see `CreatureVoice`) — whole-object replace; pass
+     *  `null` to clear the voice, omit to leave untouched. */
+    voice?: CreatureVoice | null;
+    expectedUpdatedAt?: string;
+}
+interface UpdateCreatureResult {
+    id: string;
+    updatedAt: string;
+}
+/**
+ * Combined create + update body (parameter for both branches). Exported for
+ * callers that want to drive a single `upsert` flow without picking between
+ * `Create*` and `Update*`. Mirrors the `upsertCreatureBody` Zod schema in
+ * `backend/src/routes/creatures.ts`. `nodeId` + `name` are required on INSERT;
+ * `id` flips the route into UPDATE mode.
+ */
+interface UpsertCreatureInput extends CreateCreatureInput {
+    id?: string;
+    expectedUpdatedAt?: string;
+}
+type UpsertCreatureResult = {
+    id: string;
+} | UpdateCreatureResult;
+interface ListCreaturesParams {
+    /** When true, return archived creatures instead of active ones. */
+    archived?: boolean;
+    /** Optional project filter — server-scoped to the caller's user. */
+    projectId?: string;
+}
+/**
+ * Input for `client.creatures.generate()` — fires the
+ * `POST /v1/generate-creature` route. Produces 1–10 candidate
+ * main images; each lands as one `jobs` row in `pending` state and is then
+ * enqueued for the worker.
+ *
+ * When `attachToCreatureId` is set AND `count === 1`, the worker writes the
+ * resulting URL directly to `creatures.source_image_url` on completion —
+ * caller doesn't need a separate `approveMainImage` call. Multi-candidate
+ * batches MUST go through explicit approval so the user picks the winner.
+ *
+ * `seedPromptHint` flows the parameter-picker's prompt fragment through to the
+ * worker so a catalog selection (e.g. "armored frost dragon") gets appended to
+ * the generated prompt context.
+ */
+interface GenerateCreatureInput {
+    name: string;
+    description?: string;
+    userPrompt?: string;
+    /** Free-text creature type/species (the creature delta vs object). */
+    species?: string;
+    category?: string;
+    style?: "realistic" | "anime" | "3d-pixar" | "illustration";
+    sourceImageUrl?: string;
+    provider?: string;
+    /** Number of candidate images to generate (1–10; server-validated). */
+    count?: number;
+    /** Auto-attach the result to this creature row (single-candidate only). */
+    attachToCreatureId?: string;
+    /** Parameter-picker prompt-fragment pass-through. */
+    seedPromptHint?: string;
+    /** Optional name to set on the attached row alongside the main image. */
+    attachName?: string;
+    /** Optimistic-concurrency token for the single-candidate auto-attach path. */
+    expectedUpdatedAt?: string;
+}
+/**
+ * `generate()` response — `jobIds` is ALWAYS present (the harmonized contract,
+ * matching characters). `jobId` is a deprecated back-compat alias populated only
+ * on `count === 1`; prefer `jobIds`. (Will be removed on the next major.)
+ */
+interface GenerateCreatureResult {
+    jobIds: string[];
+    /** @deprecated count===1 back-compat alias — use `jobIds`. */
+    jobId?: string;
+}
+/**
+ * Input for `client.creatures.generateAsset()` — fires the
+ * `POST /v1/generate-creature-asset` route. Produces a single
+ * angles / poses / variations / custom variant.
+ *
+ * When all three studio-path fields are set (`attachToCreatureId` +
+ * `attachToColumn` + `attachName`), the worker appends
+ * `{ name: attachName, url: <result> }` to the named JSONB array column on
+ * the user's creature row on completion. `attachToColumn` is REQUIRED for
+ * `assetType === "custom"` — the worker can't infer the bucket from the
+ * asset type.
+ */
+interface GenerateCreatureAssetInput {
+    assetType: CreatureAssetType;
+    variant: string;
+    name: string;
+    description?: string;
+    userPrompt?: string;
+    category?: string;
+    style?: string;
+    sourceImageUrl?: string;
+    provider?: string;
+    attachToCreatureId?: string;
+    attachToColumn?: CreatureAttachColumn;
+    attachName?: string;
+    /** Parameter-picker prompt-fragment pass-through. */
+    seedPromptHint?: string;
+}
+interface GenerateCreatureAssetResult {
+    jobId: string;
+}
+/**
+ * Input for `client.creatures.generateMotion()` — fires the
+ * `POST /v1/generate-creature-motion` route. Produces a single motion clip
+ * (idle, prowl, attack, etc.) animated FROM a static creature-shot image.
+ *
+ * Mirrors `client.objects.generateMotion()` — the creature motion route reuses
+ * the entity-agnostic object motion helpers server-side. The route hardcodes
+ * the attach column to `motion_clips` — callers supply `attachToCreatureId` +
+ * `attachName` only.
+ *
+ * `sourceImageUrl` is REQUIRED — image-to-video needs a source frame and the
+ * route has no fallback (the studio path supplies the canonical creature-shot
+ * URL explicitly).
+ *
+ * Defaults vs location:
+ *   - `provider` defaults to `"kling-turbo"` (not location's `"kling"`)
+ *   - `aspectRatio` defaults to `"1:1"` server-side via
+ *     `resolveObjectAspectRatio({ assetType: "motion" })` — creatures use
+ *     centered reference framing, not cinematic establishing shots.
+ *
+ * When the studio path is set (`attachToCreatureId` + `attachName`), the
+ * worker appends `{ name: attachName, url: <result> }` to the creature row's
+ * `motion_clips` JSONB column on completion.
+ */
+interface GenerateCreatureMotionInput {
+    motionPrompt: string;
+    sourceImageUrl: string;
+    provider?: string;
+    name: string;
+    /** Source clip URL — when set, worker routes to video-to-video refine. */
+    refineFromVideoUrl?: string;
+    category?: string;
+    style?: "realistic" | "anime" | "3d-pixar" | "illustration";
+    canonicalDescription?: string;
+    /** Parameter-picker prompt-fragment pass-through. */
+    seedPromptHint?: string;
+    attachToCreatureId?: string;
+    attachName?: string;
+    /**
+     * Optional aspect ratio override. Defaults to 1:1 server-side. One of the
+     * 5-value `CreatureAspectRatio` union (1:1 / 3:4 / 16:9 / 9:16 / 4:3) — the
+     * creature route reuses the object aspect enum.
+     */
+    aspectRatio?: ObjectAspectRatio;
+    /**
+     * Optional clip duration in seconds. Validated server-side against the chosen
+     * provider's allowed durations (e.g. kling 5/10, wan-i2v 5/10/15); omitted →
+     * the model's own default (no behavior change). Mirrors generate-video's
+     * per-model i2v duration lever.
+     */
+    duration?: number;
+}
+interface GenerateCreatureMotionResult {
+    jobId: string;
+}
+interface ApproveCreatureMainImageResult {
+    sourceImageUrl: string;
+    /**
+     * LLM-authored caption. `null` when the LLM caption sub-failed — the wire
+     * sends `""`, normalized to `null` here so consumers see the same
+     * `string | null` semantics as characters. The main image is still set; call
+     * `recaption()` to retry.
+     */
+    canonicalDescription: string | null;
+}
+interface RecaptionCreatureResult {
+    canonicalDescription: string;
+}
+declare class CreaturesResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * List the caller's creatures. By default returns active creatures only;
+     * pass `archived: true` to fetch soft-deleted rows for an "archive" view.
+     * Optional `projectId` scopes the result to a single project.
+     */
+    list(params?: ListCreaturesParams): Promise<{
+        creatures: Creature[];
+    }>;
+    /**
+     * Convenience wrapper for `list({ archived: true })`. Returns soft-deleted
+     * rows so callers can drive a UI "Archived" tab without re-encoding the
+     * query param.
+     *
+     * `archived` is omitted from the param type — it's always set to `true` here.
+     */
+    listArchived(params?: Omit<ListCreaturesParams, "archived">): Promise<{
+        creatures: Creature[];
+    }>;
+    /**
+     * Fetch a single creature including in-flight asset job state. Soft-deleted
+     * (archived) rows are NOT returned by id — the route enforces
+     * `deleted_at IS NULL` so archived creatures 404 (uniform "not_found" — does
+     * not leak the deleted vs non-existent distinction).
+     */
+    get(id: string): Promise<CreatureDetail>;
+    /**
+     * Create a new creature. `name` + `nodeId` are required — the route 400s
+     * otherwise. Returns the new row's id.
+     *
+     * Note: the underlying route is the same `POST /v1/creatures` upsert that
+     * powers `update()`. This convenience wrapper enforces the INSERT-required
+     * fields at the type level and never sends an `id`.
+     */
+    create(data: CreateCreatureInput): Promise<{
+        id: string;
+    }>;
+    /**
+     * Update a creature. Only the fields you pass are written — undefined keys
+     * are NOT touched on the row. Worker-owned asset buckets are intentionally
+     * not exposed on this surface (see `UpdateCreatureInput` for the rationale).
+     *
+     * Optimistic-concurrency: pass `expectedUpdatedAt` to require the row's
+     * `updated_at` still matches; on mismatch the route returns 409
+     * `concurrent_modification` carrying the fresh `updatedAt`. The SDK
+     * surfaces that as a generic `NodaroError` with the same code.
+     */
+    update(id: string, data: UpdateCreatureInput): Promise<UpdateCreatureResult>;
+    /**
+     * Soft-delete (archive) a creature. The row is hidden from `list()` by
+     * default but recoverable via `restore(id)` or visible under
+     * `listArchived()`. Idempotent — repeating a delete on an already-archived
+     * row is a no-op.
+     */
+    delete(id: string): Promise<{
+        success: true;
+        archived: true;
+    }>;
+    /**
+     * Hard-delete (permanent) a creature — the row + every R2 asset it
+     * references. Archived rows ONLY: active creatures return 400 `not_archived`.
+     * Call `delete()` first to archive, then `permanentDelete()` to destroy.
+     *
+     * Mirrors the `app_runs` permanent-delete pattern (archive-first) so a
+     * stray SDK / curl caller cannot bypass the studio's archive-first UI
+     * flow.
+     */
+    permanentDelete(id: string): Promise<{
+        success: true;
+        permanent: true;
+    }>;
+    /**
+     * Un-archive a creature. If the original name now collides (case-
+     * insensitive) with an active row, the server auto-suffixes "(restored)"
+     * and returns the effective name.
+     */
+    restore(id: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * Fire `POST /v1/generate-creature` to produce one or more candidate main
+     * images. With `count > 1`, all jobs are reserved up-front before any
+     * is enqueued — mid-batch failures roll back atomically.
+     *
+     * When `attachToCreatureId` is set AND `count === 1`, the worker writes
+     * the result directly to the row's `source_image_url`; otherwise you must
+     * call `approveMainImage()` after picking a candidate.
+     */
+    generate(data: GenerateCreatureInput): Promise<GenerateCreatureResult>;
+    /**
+     * Fire `POST /v1/generate-creature-asset` to produce a single variant.
+     * When the studio path is set (`attachToCreatureId` + `attachToColumn` +
+     * `attachName`), the worker appends `{ name: attachName, url: <result> }`
+     * to the named JSONB array column on completion.
+     *
+     * Note: `attachToColumn` is REQUIRED for `assetType === "custom"` — the
+     * worker can't infer the bucket from the asset type. For canonical asset
+     * types (`angles` / `poses` / `variations`), the column is derived
+     * automatically by the route.
+     */
+    generateAsset(data: GenerateCreatureAssetInput): Promise<GenerateCreatureAssetResult>;
+    /**
+     * Fire `POST /v1/generate-creature-motion` to animate the creature's main
+     * image into a motion clip. Image-to-video, single clip per call; the
+     * attach column is hardcoded to `motion_clips` server-side (creatures have a
+     * single motion bucket so the caller doesn't supply `attachToColumn`).
+     * When the studio path is set (`attachToCreatureId` + `attachName`), the
+     * worker appends `{ name: attachName, url: <result> }` to the row's
+     * `motion_clips` column on completion.
+     *
+     * Defaults: `provider` → `"kling-turbo"`, `aspectRatio` → `"1:1"` (set
+     * server-side via `resolveObjectAspectRatio({ assetType: "motion" })`).
+     */
+    generateMotion(data: GenerateCreatureMotionInput): Promise<GenerateCreatureMotionResult>;
+    /**
+     * Approve a completed `generate-creature` job as the creature's main image.
+     * Sets `source_image_url` and fires the LLM caption (Claude Sonnet vision)
+     * inline. Returns the new main-image URL plus the caption.
+     *
+     * Caption-failure semantics: the route still sends `""` on LLM sub-failure,
+     * but the SDK normalizes `""` → `null` here so `canonicalDescription` carries
+     * the same `string | null` semantics as characters. The main image is still
+     * set; call `recaption()` to retry.
+     *
+     * Optimistic-concurrency: pass `expectedUpdatedAt` to gate the update on
+     * the row's current `updated_at`; on mismatch the route returns 409
+     * `concurrent_modification` carrying the fresh token.
+     */
+    approveMainImage(id: string, candidateJobId: string, expectedUpdatedAt?: string): Promise<ApproveCreatureMainImageResult>;
+    /**
+     * Re-fire the LLM caption against the creature's current main image. 502s
+     * on LLM failure (unlike `approveMainImage` which preserves the side-effect
+     * and returns ""); returns 400 `main_image_required` if no main image is
+     * set yet.
+     *
+     * The route is a pure idempotent retry — it does NOT accept an
+     * `expectedUpdatedAt` token (backend route is idempotent retry, not gated on
+     * optimistic-concurrency).
+     */
+    recaption(id: string): Promise<RecaptionCreatureResult>;
+}
+
+/**
+ * Owner-scoped pipeline record returned by `get` / `list` (the server strips
+ * `user_id`). Mirrors the public field set of `GET /v1/pipelines/:id`.
+ */
+interface PipelineRecord {
+    id: string;
+    status: PipelineStatus;
+    current_stage: string | null;
+    spent_credits: number;
+    reserved_credits: number;
+    upfront_credit_estimate: number;
+    branched_from_pipeline_id: string | null;
+    branched_from_stage: string | null;
+    mode: PipelineMode | null;
+    failure_reason: string | null;
+    current_progress_message: string | null;
+}
+/** One stage currently awaiting approval (from `pendingApprovals`). */
+interface PendingApproval {
+    stage_name: PipelineStageName;
+    /** Stage output snapshot; shape varies by stage. */
+    output: unknown;
+}
+/**
+ * Assembled timeline (`GET /v1/pipelines/:id/timeline`) — ordered scene
+ * composites + their durations, plus optional music/narration and live
+ * per-shot animate progress. The data the studio turns into a render.
+ */
+interface PipelineTimeline {
+    fps: number;
+    width: number;
+    height: number;
+    scenes: Array<{
+        compositeUrl: string;
+        durationSeconds: number;
+    }>;
+    musicUrl?: string;
+    narrationUrl?: string;
+    animateProgress?: {
+        totalShots: number;
+        shotsDone: number;
+        percent: number;
+    };
+}
+interface BranchPipelineInput {
+    /** The stage to re-run from. Upstream stages are cloned as approved. */
+    fromStage: PipelineStageName;
+}
+interface BranchPipelineResult {
+    /** The id of the newly created pipeline. */
+    pipelineId: string;
+    /** Stage names that were cloned as 'approved' (stages before `fromStage`). */
+    clonedStages: string[];
+    /** Number of entity rows cloned into the new pipeline. */
+    clonedEntities: number;
+}
+/**
+ * A single chat turn returned by `getStageChat`. Mirrors the
+ * `pipeline_chat_turns` row shape selected by the GET handler.
+ *
+ * `@nodaro/shared` does not yet export a Zod schema for the full row; it only
+ * exports `ChatTurnResponseSchema` (the LLM response shape) and the
+ * `ProposedChange` discriminated union. Define the wire-format row locally so
+ * callers get end-to-end typing today without re-shaping the backend payload.
+ */
+interface ChatTurn {
+    id: string;
+    turn_n: number;
+    role: "user" | "assistant";
+    content: string;
+    proposed_change: ProposedChange | null;
+    llm_call_id: string | null;
+    applied_to_attempt_id: string | null;
+    created_at: string;
+}
+/**
+ * Result of `chatStage` — the assistant turn that was just persisted. The
+ * route always echoes the assistant message back so callers can render the
+ * reply without a follow-up GET (SSE is the secondary delivery channel).
+ */
+interface ChatStageResult {
+    turnId: string;
+    role: "assistant";
+    content: string;
+    proposed_change: ProposedChange | null;
+}
+/**
+ * Result of `applyChatProposal`. Discriminated on `applied`:
+ *
+ * - `applied: true` — `applyStageEdit` validated + persisted a new attempt and
+ *   flipped the stage to approved. `newOutput` is the post-patch artifact.
+ * - `applied: false` — recoverable failure (schema_invalid or
+ *   reference_integrity_failed); the backend has already inserted a follow-up
+ *   assistant turn with a human-readable hint so the user can iterate via
+ *   chat. Hard failures throw via the client's error pipeline (409).
+ */
+type ApplyChatProposalResult = {
+    applied: true;
+    attemptId: string;
+    newOutput: unknown;
+} | {
+    applied: false;
+    error: {
+        code: string;
+        detail?: unknown;
+    };
+};
+declare class PipelinesResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * Start a new pipeline (headless film generation) — the programmatic
+     * equivalent of the studio's "Create film". In Auto mode the engine
+     * self-advances to completion; poll {@link get} for status and
+     * {@link getTimeline} for the assembled output. In manual/guided mode, drive
+     * it with {@link pendingApprovals} + {@link approveStage} /
+     * {@link approveSubGate}.
+     *
+     * Requires `pipelines:execute` scope. Returns the new pipeline id.
+     */
+    create(input: PipelineInput): Promise<{
+        id: string;
+    }>;
+    /**
+     * Fetch current pipeline state: `status`, `current_stage`, credit counters,
+     * `mode`, and `failure_reason` (set when `status='failed'`). Poll this to
+     * track a headless Auto run to completion. Requires `pipelines:read`.
+     */
+    get(id: string): Promise<PipelineRecord>;
+    /** List the caller's pipelines (most recent first). Requires `pipelines:read`. */
+    list(): Promise<PipelineRecord[]>;
+    /**
+     * Cancel a running pipeline. Unspent reserved credits refund. Idempotent on
+     * an already-terminal pipeline. Requires `pipelines:execute`.
+     */
+    cancel(id: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Stages currently `awaiting_approval`. Empty in a clean Auto run (the engine
+     * self-approves); populated in manual/guided mode at each gate. Requires
+     * `pipelines:read`.
+     */
+    pendingApprovals(id: string): Promise<PendingApproval[]>;
+    /**
+     * Approve a stage so the engine advances to the next one. An optional `edits`
+     * JSON-Patch is applied to the stage output before approval. Requires
+     * `pipelines:approve`.
+     */
+    approveStage(id: string, stage: PipelineStageName, edits?: unknown): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Reject a stage with feedback; the engine re-runs it incorporating the note.
+     * Requires `pipelines:approve`.
+     */
+    rejectStage(id: string, stage: PipelineStageName, feedback: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Approve a Stage-7 sub-gate (`dialogue_recheck` / `silent_cut`) so the
+     * orchestrator resumes from the next sub-step. Requires `pipelines:approve`.
+     */
+    approveSubGate(id: string, gate: SubGateName): Promise<{
+        ok: true;
+        gate: SubGateName;
+        resumed_at: string;
+    }>;
+    /**
+     * Read a single stage's `status`, `output`, and `critic_feedback`. Useful for
+     * inspecting the script/plan before approving. Requires `pipelines:read`.
+     */
+    getStage(id: string, stage: PipelineStageName): Promise<{
+        status: string;
+        output: unknown;
+        critic_feedback: unknown;
+    }>;
+    /**
+     * Assembled timeline — ordered scene composites + durations + audio URLs +
+     * live animate progress. The output a headless caller renders or hands to a
+     * downstream editor. Requires `pipelines:read`.
+     */
+    getTimeline(id: string): Promise<PipelineTimeline>;
+    /**
+     * Branch a completed pipeline into a new pipeline that re-runs from the
+     * given stage. The original pipeline's upstream stages and entities are
+     * cloned into the new pipeline; downstream stages are created by the
+     * orchestrator as it advances.
+     *
+     * Requires `pipelines:execute` scope.
+     * The source pipeline must have `status='completed'`.
+     *
+     * @returns 201 with `{ pipelineId, clonedStages, clonedEntities }`.
+     */
+    branch(id: string, input: BranchPipelineInput): Promise<BranchPipelineResult>;
+    /**
+     * Send a chat message to the Showrunner Refinement Director (Guided Mode).
+     * Persists user + assistant turns; returns the assistant's reply and an
+     * optional `proposed_change` the user can `applyChatProposal` to commit.
+     *
+     * Requires `pipelines:approve` scope. The pipeline must have
+     * `mode='guided'` and the stage must be `awaiting_approval`.
+     *
+     * Only the Script stage ships a wired specialist in Phase 1D.2b — the other
+     * chat-enabled stages (`shot_list`, `post_merge`) return 501 until 1D.2d.
+     */
+    chatStage(pipelineId: string, stage: ChatEnabledStage, message: string): Promise<ChatStageResult>;
+    /**
+     * Accept a proposed change from a prior assistant turn. Routes through
+     * `applyStageEdit` (validates JSON Patch + per-stage schema +
+     * reference-integrity, inserts a new pipeline_stage_attempts row, CAS-flips
+     * the stage to approved, emits `chat:proposal_applied` SSE).
+     *
+     * Requires `pipelines:approve` scope.
+     *
+     * Returns `{ applied: true, attemptId, newOutput }` on success, or
+     * `{ applied: false, error }` on recoverable failures (the backend already
+     * inserted a follow-up assistant turn with a hint). Hard failures
+     * (`patch_invalid`, `stage_not_awaiting`) throw via the standard error
+     * pipeline (HTTP 409).
+     */
+    applyChatProposal(pipelineId: string, stage: ChatEnabledStage, turnId: string): Promise<ApplyChatProposalResult>;
+    /**
+     * Fetch the chat history for a stage. Returns an empty array when no turns
+     * exist yet (e.g., stage has not been started or the user hasn't sent any
+     * messages). Used by the frontend chat panel on initial mount; subsequent
+     * updates arrive via SSE (`chat:turn` events).
+     *
+     * Requires `pipelines:read` scope.
+     */
+    getStageChat(pipelineId: string, stage: ChatEnabledStage): Promise<{
+        turns: ChatTurn[];
+    }>;
+}
+
+interface ReduceInput {
+    /** Which fan-in strategy to run. */
+    strategyId: ReduceStrategyId;
+    /**
+     * Strategy-specific config. Defaults to `{}` server-side, which uses every
+     * strategy's `defaultConfig`. Schemas (from `@nodaro/shared`):
+     *   - `pick-best-llm`: `{ criteria: string, inputKind?: "text" | "image-url" }`
+     *   - `concat`: `{ separator?: string }`
+     *   - `vote`: `{ caseSensitive?: boolean }`
+     *   - `merge-json`: `{ strategy?: "deep" | "shallow" }`
+     *   - `first-non-empty`, `count`: `{}`
+     */
+    strategyConfig?: Record<string, unknown>;
+    /** Up to 1000 input strings (URLs, text fragments, etc.). */
+    inputs: string[];
+    /**
+     * Optional — associates this reduce run with a workflow execution. The
+     * server reads this from the body before Zod strips it (same path as
+     * other job-creating routes).
+     */
+    workflowId?: string;
+}
+interface ReduceResult {
+    jobId: string;
+    /**
+     * Stringified result — for `count` this is a numeric string, for
+     * `merge-json` this is the JSON-encoded merged object, otherwise the
+     * chosen / joined text.
+     */
+    output: string;
+    meta: ReduceMeta;
+}
+declare class ReduceResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * Run the Reduce (fan-in) node directly — useful for scripted batch
+     * scoring, picking the best of N generations outside a workflow, or
+     * one-shot programmatic merges.
+     *
+     * Throws `NodaroError` on 4xx/5xx responses (e.g. `code: "no_valid_inputs"`
+     * with status 400 when every input is empty / whitespace; the underlying
+     * `EmptyInputError` is mapped to a 400 server-side).
+     */
+    run(input: ReduceInput): Promise<ReduceResult>;
+}
+
+interface CommonInput {
+    nodeType: string;
+    provider?: string;
+    style?: string;
+    aspectRatio?: string;
+    duration?: number;
+    llmModel?: string;
+    nodeContext?: WizardNodeContext;
+    userPreference?: string;
+    /** Associates this call with a workflow execution. Read server-side before Zod. */
+    workflowId?: string;
+}
+interface AnalyzeInput extends CommonInput {
+    /** The user's rough idea. Omit to build questions from scratch. */
+    prompt?: string;
+}
+interface AnalyzeResult {
+    jobId: string;
+    questions: WizardQuestion[];
+}
+interface GenerateInput extends CommonInput {
+    /** The chosen answers from analyze. */
+    selections: WizardSelection[];
+    /** The user's original rough idea, woven into the generated prompt. */
+    originalPrompt?: string;
+}
+interface EnhanceInput extends CommonInput {
+    /** The rough idea to improve one-shot. Omit to build from scratch. */
+    prompt?: string;
+}
+interface PromptResult {
+    jobId: string;
+    prompt: string;
+    recommendedModel?: RecommendedModel;
+}
+/**
+ * AI Prompt Wizard — help write/improve prompts for generation nodes.
+ *
+ * - `analyze` -> guided questions, `generate` -> prompt from selections (the
+ *   2-step human flow), or `enhance` -> one-shot "improve this prompt".
+ *
+ * All three delegate to `POST /v1/prompt-helper/wizard`. Throws `NodaroError`
+ * on 4xx/5xx (e.g. `validation_error`, `malformed_response`).
+ */
+declare class PromptHelperResource {
+    private client;
+    constructor(client: NodaroClient);
+    analyze(input: AnalyzeInput): Promise<AnalyzeResult>;
+    generate(input: GenerateInput): Promise<PromptResult>;
+    enhance(input: EnhanceInput): Promise<PromptResult>;
+}
+
+/**
+ * Re-export the shared voice types so SDK consumers don't have to add
+ * `@nodaro/shared` as a second dependency just to type a `Voice` row, a
+ * `VoiceClone`, or a `searchLibrary` call. Single source of truth lives in
+ * `@nodaro/shared`.
+ */
+/** Audio-FX preset union (reverb spaces / telephone / megaphone / echo / custom) — used by {@link VoiceChangerProInput.voiceFx}. */
+/**
+ * Read access to ElevenLabs voices: the premade catalog plus the shared
+ * community Voice Library (both public GETs, no body), and the signed-in
+ * user's own voice clones (list / create-from-url / delete).
+ */
+declare class VoicesResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * List the premade ElevenLabs voices (`GET /v1/voices`). Falls back to a
+     * curated set server-side when no ElevenLabs API key is configured.
+     */
+    list(): Promise<Voice[]>;
+    /**
+     * Search the shared/community Voice Library (`GET /v1/voices/library`). All
+     * params are optional and forwarded as a querystring; `undefined` / `null` /
+     * empty-string values are omitted so the server defaults apply. `hasMore`
+     * drives "load more" pagination.
+     */
+    searchLibrary(params?: VoiceLibraryParams): Promise<VoiceLibraryResponse>;
+    /**
+     * List the signed-in user's voice clones (`GET /v1/voice-clones`). The route
+     * wraps the rows in `{ voiceClones }`; we unwrap to the bare array.
+     */
+    listClones(): Promise<VoiceClone[]>;
+    /**
+     * Clone a voice from an already-uploaded audio URL
+     * (`POST /v1/voice-clones/from-url`). Costs credits. Returns the create
+     * subset of `VoiceClone` (`elevenlabsVoiceId` is the id to use at
+     * text-to-speech time).
+     */
+    createClone(input: {
+        name: string;
+        audioUrl: string;
+    }): Promise<VoiceClone>;
+    /** Delete one of the user's voice clones (`DELETE /v1/voice-clones/:id`). */
+    deleteClone(id: string): Promise<void>;
+    /**
+     * Replace the voice in a recording — or in a whole talking video — with a
+     * different voice (`POST /v1/voice-changer`). Pass `audioUrl` to revoice
+     * audio→audio, or `videoUrl` to revoice an entire clip (the server demuxes
+     * the audio, runs speech-to-speech, and remuxes onto the original video,
+     * returning the video plus the new audio track). Exactly one of `audioUrl` /
+     * `videoUrl` is required; when both are sent, video wins. `removeBackgroundNoise`
+     * off keeps the music/SFX bed under the new voice; on yields a clean voice-only
+     * result. Costs credits and runs async — poll `jobs.get(jobId)` for the result
+     * (`output_data.videoUrl` + `output_data.audioUrl` in video mode).
+     */
+    change(input: {
+        voiceId: string;
+        audioUrl?: string;
+        videoUrl?: string;
+        stability?: number;
+        similarityBoost?: number;
+        /** Style exaggeration (0–1). Default 0; >0 amplifies delivery at the cost of latency/stability. */
+        style?: number;
+        removeBackgroundNoise?: boolean;
+    }): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Recast each detected speaker in a multi-speaker recording to a different
+     * voice (`POST /v1/voice-changer-pro`). `orderedVoices` maps speaker positions to
+     * voices in detection order — speaker 0 → `orderedVoices[0]`, speaker 1 →
+     * `orderedVoices[1]`, etc. Speakers beyond the end of `orderedVoices` keep
+     * their original voice. Each entry is EITHER a bare voice id (premade name or
+     * ElevenLabs UUID) OR a {@link VoiceChangerProVoice} object carrying per-voice
+     * ElevenLabs speech-to-speech settings (stability / similarityBoost / style /
+     * useSpeakerBoost / `seed`) plus a loudness `volumeMode` (and a manual
+     * `volume`). A per-voice `seed` makes that speaker's recast reproducible.
+     *
+     * Pass `audioUrl` for audio-only recast or `videoUrl` to recast the audio
+     * track of a video clip (the server demuxes, recasts, and remuxes).
+     *
+     * Voice and music are ALWAYS separated first — ElevenLabs only ever sees the
+     * isolated vocal stem, never the music bed. `preserveBackground` (default
+     * `true`) only controls whether that music/instrumental stem is mixed back
+     * under the new voices; set it `false` for a clean voice-only result.
+     * `separationQuality` selects the demucs model used for that split: `"fast"`
+     * (default, htdemucs — preserves more of the voice) or `"best"` (htdemucs_ft —
+     * finer separation). `removeBackgroundNoise` additionally denoises the result.
+     * `musicVolumeMode` sets the level of that preserved background (only relevant
+     * when `preserveBackground` is on): `"match"` (default) keeps the original
+     * level, `"normalize"` loudnorms it, `"manual"` uses `musicVolume`%.
+     * `voiceFx` applies a reverb/echo to the COMBINED recast voices BEFORE the
+     * background is mixed back in (effect sits on the voices, not the music bed).
+     *
+     * Cloud-only — costs credits and runs async; poll `jobs.get(jobId)` for the
+     * result (`output_data.videoUrl` + `output_data.audioUrl` in video mode).
+     */
+    recast(input: VoiceChangerProInput): Promise<{
+        jobId: string;
+    }>;
+}
+/**
+ * One entry in {@link VoiceChangerProInput.orderedVoices}. Either a bare voice id
+ * (premade name like `"Rachel"` or an ElevenLabs UUID for a custom clone), or
+ * an object pinning per-voice speech-to-speech settings and the recast's
+ * loudness behaviour for that speaker.
+ */
+type VoiceChangerProVoice = string | {
+    /** Target voice — premade name (`"Rachel"`, `"Aria"`, …) or an ElevenLabs UUID for a custom clone. */
+    voiceId: string;
+    /** ElevenLabs stability (0–1). Higher = steadier, lower = more expressive. */
+    stability?: number;
+    /** ElevenLabs similarity boost (0–1) — how closely the output hugs the target voice's timbre. */
+    similarityBoost?: number;
+    /** Style exaggeration (0–1). Default 0; >0 amplifies delivery at the cost of latency / stability. */
+    style?: number;
+    /** ElevenLabs speaker boost — sharpens fidelity to the target speaker. */
+    useSpeakerBoost?: boolean;
+    /**
+     * Deterministic speech-to-speech seed (integer 0–4294967295) for
+     * reproducible per-voice output — the same source + settings + seed
+     * recast this speaker identically across runs. Omit for a random seed.
+     */
+    seed?: number;
+    /**
+     * Loudness handling for this recast voice. `"match"` (default) matches the
+     * original speaker's loudness; `"normalize"` applies EBU R128 loudnorm;
+     * `"manual"` uses `volume` as a percentage.
+     */
+    volumeMode?: "match" | "normalize" | "manual";
+    /** Manual output volume as a percentage (0–200). Consulted only when `volumeMode === "manual"`. */
+    volume?: number;
+};
+/** Input for {@link VoicesResource.recast}. */
+interface VoiceChangerProInput {
+    /** URL of an audio file to recast (audio → audio). Exactly one of `audioUrl` / `videoUrl` is required. */
+    audioUrl?: string;
+    /** URL of a video file to recast (the audio track is recast and remuxed). Exactly one of `audioUrl` / `videoUrl` is required. */
+    videoUrl?: string;
+    /**
+     * Voices in speaker-detection order. Speaker N is mapped to `orderedVoices[N]`;
+     * speakers beyond the array keep their original voice. Each entry is a bare
+     * voice id OR a {@link VoiceChangerProVoice} object with per-voice settings.
+     */
+    orderedVoices: Array<VoiceChangerProVoice>;
+    /** Model to use for speech-to-speech. Defaults to the server-configured default when omitted. */
+    model?: string;
+    /**
+     * Mix the separated music / SFX stem back under the recast voices. Default
+     * `true`. The voice is ALWAYS split out before recasting regardless of this
+     * flag — `false` simply drops the music for a clean voice-only result.
+     */
+    preserveBackground?: boolean;
+    /**
+     * Demucs model used to split voice from music. `"fast"` (default, htdemucs —
+     * preserves more of the voice) or `"best"` (htdemucs_ft — finer separation).
+     */
+    separationQuality?: "fast" | "best";
+    /** Strip background noise for a clean voice-only result. */
+    removeBackgroundNoise?: boolean;
+    /**
+     * Level of the preserved background music / SFX stem in the final mix. Only
+     * relevant when `preserveBackground` is on (otherwise there is no background to
+     * level). `"match"` (default) leaves the separated instrumental at its original
+     * level; `"normalize"` applies EBU R128 loudnorm; `"manual"` sets its level to
+     * `musicVolume`%.
+     */
+    musicVolumeMode?: "match" | "normalize" | "manual";
+    /** Background music level as a percentage (0–200). Consulted only when `musicVolumeMode === "manual"`. */
+    musicVolume?: number;
+    /**
+     * Node-level reverb/echo applied to the COMBINED recast voices **before** the
+     * background is mixed back in (so the effect sits on the voices only, not the
+     * music/SFX bed). Reverb presets (`room`, `hall`, `church`, …) use
+     * `wetDryMix`; the `echo` / `custom` presets use `delayMs` + `decay`. Omit for
+     * no effect.
+     */
+    voiceFx?: {
+        /** Effect preset — reverb space, `telephone`, `megaphone`, `echo`, or `custom`. */
+        preset: AudioFxPreset;
+        /** Reverb wet/dry mix as a percentage (0–100). Higher = wetter (more reverb). */
+        wetDryMix?: number;
+        /** Echo delay in milliseconds (20–2000). Used by the `echo` / `custom` presets. */
+        delayMs?: number;
+        /** Echo decay / feedback (0–1). Higher = more repeats. Used by the `echo` / `custom` presets. */
+        decay?: number;
+    };
+}
+
+/**
+ * Authenticated user's credit balance — the shape of `GET /v1/user/credits`'s
+ * `data` field. Mirrors the canonical `UserBalance` from the backend billing
+ * module (`backend/src/ee/billing/credits.ts`), the source of truth: keep this
+ * in sync if that interface changes.
+ */
+interface UserBalance {
+    total: number;
+    subscription: number;
+    topup: number;
+    dailySpent: number;
+    dailyLimit: number | null;
+    monthlyAllocation: number;
+    tier: string;
+    features: Record<string, unknown>;
+    periodEnd: string | null;
+    /** Credits earned for app usage (free tier only — earned by running flows). */
+    appCreditsAllowance: number;
+}
+/**
+ * Result of `POST /v1/credits/model-costs` — a batch cost lookup for editor
+ * cost previews. `data` maps each priced identifier → its credit cost.
+ *
+ * Per-model fault isolation (the route runs the lookups under
+ * `Promise.allSettled`): identifiers with no pricing row are reported in
+ * `missing` (undisplayable until an operator seeds a price) and lookup
+ * failures in `errors`, instead of failing the whole batch. Callers typically
+ * render `'—'` for any identifier that lands in `missing`. The hard-fail
+ * policy still triggers at reservation time when the user actually runs the
+ * node — this preview lookup is intentionally lenient.
+ */
+interface ModelCostsResult {
+    data: Record<string, number>;
+    missing: string[];
+    errors: string[];
+}
+declare class CreditsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * `GET /v1/user/credits` → the authenticated user's credit balance and tier
+     * info. Throws `UnauthorizedError` (401) when signed out, and the SDK's
+     * other typed errors on the usual statuses.
+     */
+    balance(): Promise<UserBalance>;
+    /**
+     * `POST /v1/credits/model-costs` → per-identifier credit cost, for editor
+     * cost previews. Capped at the first {@link MODEL_COSTS_LIMIT} identifiers
+     * (the route's request limit). Preserves the `{ data, missing, errors }`
+     * fault-isolation shape verbatim (see {@link ModelCostsResult}).
+     */
+    modelCosts(ids: string[]): Promise<ModelCostsResult>;
+}
+
+/**
+ * Result of a successful `POST /v1/upload`. Mirrors the route's `data` envelope
+ * (`backend/src/routes/upload.ts`), the source of truth — keep in sync if that
+ * response changes. The route also returns loosely-typed extracted `metadata`;
+ * it is omitted here until a consumer needs a typed shape (add it shaped to
+ * that need rather than inventing `Record<string, unknown>` surface now).
+ */
+interface UploadResult {
+    /** Public R2 URL of the stored asset (always present on success). */
+    readonly url: string;
+    /** Storage row id; `null` when no asset row was written (e.g. unauthenticated). */
+    readonly assetId: string | null;
+    /** Generated thumbnail URL (images/video); `null` for audio or on failure. */
+    readonly thumbnailUrl: string | null;
+    /** Server-classified asset category (e.g. "image" | "video" | "audio"). */
+    readonly category: string;
+    /** Display filename (server override or the original). */
+    readonly filename: string;
+    /** Final MIME type after server normalization. */
+    readonly mimeType: string;
+    /** Stored byte size. */
+    readonly sizeBytes: number;
+    /** R2 object key. */
+    readonly r2Key: string;
+}
+declare class UploadsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * Upload one file (`POST /v1/upload`, multipart — the file rides the `file`
+     * field). The SDK's `request` detects the `FormData` body and lets the
+     * runtime set the multipart boundary. Returns the persisted asset's public
+     * URL + storage metadata (unwraps the `{ data }` envelope). Throws
+     * `StorageExceededError` (413) over the storage cap and the SDK's other typed
+     * errors on the usual statuses.
+     */
+    upload(file: File): Promise<UploadResult>;
+}
+
+/**
+ * A media asset in the caller's library (`GET /v1/library`). Mirrors the route's
+ * camelCase row shape (`backend/src/routes/library.ts`), the source of truth —
+ * keep in sync if that response changes. Covers BOTH uploaded files and saved
+ * generations; `type` discriminates the media kind.
+ */
+interface LibraryAsset {
+    readonly id: string;
+    /** Media kind — filter the list with the same values via `type`. */
+    readonly type: "image" | "video" | "audio";
+    /** Display filename (server override or the original); `null` if unknown. */
+    readonly filename: string | null;
+    readonly mimeType: string | null;
+    readonly sizeBytes: number | null;
+    /** Public R2 URL of the asset. */
+    readonly url: string;
+    /** Generated thumbnail URL (images/video); `null` for audio or when absent. */
+    readonly thumbnailUrl: string | null;
+    readonly metadata: Record<string, unknown>;
+    /** True when promoted to the shared (admin) library. */
+    readonly isLibraryItem: boolean;
+    /** How the asset entered storage (e.g. "manual_upload" | "generated"). */
+    readonly uploadSource: string;
+    readonly createdAt: string;
+}
+interface ListLibraryParams {
+    /** Filter by media kind; `"all"` (default) returns every kind. */
+    readonly type?: "all" | "image" | "video" | "audio";
+    /** Case-insensitive filename substring filter. */
+    readonly search?: string;
+    /** Page size, 1–100 (default 40). */
+    readonly limit?: number;
+    /** Opaque cursor from a prior page's `nextCursor` (fetches the next page). */
+    readonly cursor?: string;
+    /**
+     * `true` → EVERY asset the caller owns (the "Storage" view: uploads +
+     * generations, regardless of the in-library flag). `false` (default) → only
+     * assets explicitly saved to the library plus shared items (the in-editor
+     * Media Library picker).
+     */
+    readonly owned?: boolean;
+}
+interface ListLibraryResult {
+    readonly data: LibraryAsset[];
+    /** Pass back as `cursor` for the next page; `null` when there are no more. */
+    readonly nextCursor: string | null;
+    /** Exact total (first page only — omitted on cursor-paged requests). */
+    readonly totalCount?: number;
+}
+/**
+ * Library — the caller's media assets (uploaded files + saved generations).
+ *
+ * Read surface over `GET /v1/library`: a cursor-paginated, type-filterable,
+ * filename-searchable list. This is the "bring from your media" source for
+ * pickers that also offer upload + in-production stills. Writes (saving a
+ * generation, promoting/removing) stay on their dedicated routes — not exposed
+ * here until a consumer needs them.
+ */
+declare class LibraryResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * `GET /v1/library` → a page of the caller's media assets (newest first) plus
+     * a `nextCursor`. Pass the returned `nextCursor` back as `cursor` for the next
+     * page. Filter by `type` and a filename `search`; `owned: true` returns the
+     * full Storage set (uploads + generations), the default only library-saved +
+     * shared items.
+     */
+    list(params?: ListLibraryParams): Promise<ListLibraryResult>;
+}
+
+/**
+ * A user's saved custom preset (`GET /v1/node-presets`). Mirrors the backend's
+ * camelCase row shape. `data` is captured node config — merge it into a node's
+ * data when building/running a workflow to "apply" the preset.
+ */
+interface NodePreset {
+    id: string;
+    nodeType: string;
+    name: string;
+    description?: string;
+    data: Record<string, unknown>;
+    groupId?: string;
+    tags: string[];
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A user's preset folder/section (`GET /v1/node-preset-groups`). */
+interface NodePresetGroup {
+    id: string;
+    nodeType: string;
+    name: string;
+    kind: "folder" | "section";
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Result of `GET /v1/node-presets/factory` — the built-in (factory) catalog for
+ * a node type.
+ */
+interface FactoryPresetsResult {
+    data: FactoryPreset[];
+}
+/**
+ * Node presets — reusable, named node configurations.
+ *
+ * Read-only over the API today: list your own custom presets and their folders,
+ * and list the built-in factory catalog. To *use* a preset, take its `data` and
+ * merge it into a node's config when you create/update a workflow. (Creating and
+ * editing presets remains in the editor for now.)
+ */
+declare class PresetsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * `GET /v1/node-presets` → your custom presets, newest first. Pass `nodeType`
+     * (e.g. `"generate-image"`) to filter to one node type.
+     */
+    list(nodeType?: string): Promise<NodePreset[]>;
+    /**
+     * `GET /v1/node-preset-groups` → your preset folders/sections, in display
+     * order. Pass `nodeType` to filter to one node type.
+     */
+    listGroups(nodeType?: string): Promise<NodePresetGroup[]>;
+    /**
+     * `GET /v1/node-presets/factory` → the built-in catalog for `nodeType`. These
+     * ship with the app (no account needed to exist), so they're a good starting
+     * point for "what configs are available".
+     */
+    listFactory(nodeType: string): Promise<FactoryPresetsResult>;
+}
+
+/**
+ * Picker-catalog types. Mirrors `@nodaro/shared`'s `ProjectedPickerCatalog` /
+ * `PickerCatalogSummary` so the SDK stays dependency-free (same convention as
+ * `NodeDescriptor` mirroring node-registry).
+ */
+interface PickerOption {
+    id: string;
+    label: string;
+    description?: string;
+    category?: string;
+    /** The prompt fragment this id injects downstream. Present only when detail="full". */
+    promptHint?: string;
+    icon?: string;
+}
+interface PickerDimension {
+    field: string;
+    label: string;
+    options: PickerOption[];
+}
+interface PickerCatalog {
+    nodeType: string;
+    label: string;
+    catalogId: string;
+    kind: "single" | "multi";
+    /** single only — the node-data field the chosen id writes to. */
+    valueField?: string;
+    defaultValue?: string;
+    categoryOrder?: string[];
+    categoryLabels?: Record<string, string>;
+    /** single-dim catalogs. */
+    options?: PickerOption[];
+    /** multi-dim catalogs. */
+    fields?: string[];
+    dimensions?: PickerDimension[];
+    detail?: "compact" | "full";
+}
+interface PickerCatalogSummary {
+    nodeType: string;
+    label: string;
+    catalogId: string;
+    kind: "single" | "multi";
+    valueField?: string;
+    fields?: string[];
+    optionCount: number;
+}
+interface GetPickerCatalogOptions {
+    /** "compact" (default) = id, label, category, icon; "full" additionally includes description + promptHint. */
+    detail?: "compact" | "full";
+    /** single-dim: filter to one category. */
+    category?: string;
+    /** multi-dim: only this dimension field. */
+    field?: string;
+}
+declare class PickerCatalogsResource {
+    private client;
+    constructor(client: NodaroClient);
+    /** List every parameter-picker node type + its option count. Cached publicly 5 min. */
+    list(): Promise<{
+        data: PickerCatalogSummary[];
+    }>;
+    /** Get one picker's catalog of valid values. */
+    get(nodeType: string, opts?: GetPickerCatalogOptions): Promise<{
+        data: PickerCatalog;
+    }>;
+}
+
+/**
+ * The community-listing types are the single source of truth in
+ * `@nodaro/shared` (re-used by the backend, frontend, and CLI). Re-export them
+ * here so SDK consumers don't have to add `@nodaro/shared` as a second
+ * dependency just to typecheck `browse`/`clone`/`favorite`/`report`.
+ */
+/**
+ * Community — browse, favorite, clone, and report shared characters,
+ * locations, and objects.
+ *
+ * Publishing is intentionally NOT exposed here: it is admin-only via the
+ * editor, and the publish route rejects personal access tokens (which is what
+ * the SDK uses).
+ */
+declare class CommunityResource {
+    private client;
+    constructor(client: NodaroClient);
+    /**
+     * `GET /v1/community/browse` → a page of public listings plus a `nextCursor`.
+     * Pass the returned `nextCursor` back as `cursor` to fetch the next page.
+     */
+    browse(params?: BrowseCommunityParams): Promise<BrowseCommunityResult>;
+    /** `GET /v1/community/detail/:slug` → a single listing by its slug. */
+    get(slug: string): Promise<{
+        data: CommunityCard;
+    }>;
+    /**
+     * `GET /v1/community/detail/:slug/full` → the full read-only detail (card
+     * identity + the stored public snapshot). Like {@link get}, but includes the
+     * snapshot asset/voice/text blob needed to render the full cross-user view.
+     */
+    getFull(slug: string): Promise<{
+        data: CommunityFullDetail;
+    }>;
+    /** `GET /v1/community/favorites` → the listings you've favorited. */
+    favorites(): Promise<{
+        data: CommunityCard[];
+    }>;
+    /**
+     * `POST /v1/community/listings/:id/clone` → copy a listing into your library.
+     * Returns the new asset's `entityType` and `id`. Requires the `assets:write`
+     * scope when called with an OAuth app token.
+     */
+    clone(id: string, entityType: CommunityEntityType): Promise<CloneListingResult>;
+    /**
+     * `POST /v1/community/listings/:id/favorite` → toggle a favorite. Returns the
+     * resulting `favorited` state (`true` after adding, `false` after removing).
+     */
+    favorite(id: string): Promise<FavoriteListingResult>;
+    /**
+     * `POST /v1/community/listings/:id/report` → flag a listing for moderation.
+     * `reason` must be one of {@link CommunityReportReason}.
+     */
+    report(id: string, reason: CommunityReportReason): Promise<ReportListingResult>;
+    /**
+     * `POST /v1/admin/community/:entityType/:id/publish` → share one of YOUR
+     * entities to the community, returning the new listing's `slug` + `id`.
+     *
+     * **Requires an admin token** (the route is `requireAdmin`) AND the caller
+     * must own the source entity. Personal/OAuth tokens without admin role get a
+     * 401. For `character` listings, `params.likenessAttestation` must be `true`.
+     */
+    publish(entityType: CommunityEntityType, entityId: string, params: PublishListingParams): Promise<PublishListingResult>;
+    /**
+     * `DELETE /v1/admin/community/listings/:id` → unshare (deactivate) a listing
+     * you published. **Requires an admin token** (the route is `requireAdmin`).
+     */
+    unpublish(listingId: string): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * `GET /v1/admin/community/by-source/:entityType/:sourceId` → look up YOUR
+     * existing listing (if any) for a source entity. Returns `{ data: null }`
+     * when the entity hasn't been shared. **Requires an admin token** (the route
+     * is `requireAdmin`); only returns listings created by the caller.
+     */
+    sharedListing(entityType: CommunityEntityType, sourceId: string): Promise<{
+        data: SharedListing | null;
+    }>;
+}
+
+interface ClientOptions {
+    /** Backend base URL, e.g. "https://nodaro.example.com" or empty string for same-origin. */
+    baseUrl: string;
+    /** Auth provider. Use StaticTokenAuth, supabaseAuth, or CallbackAuth. */
+    auth: Auth;
+    /** Optional fetch override (for tests or custom transports). */
+    fetch?: typeof fetch;
+    /** Default request timeout in ms. Default 60s. */
+    timeoutMs?: number;
+}
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * The authenticated user's canonical identity (`GET /v1/me`). A token-
+ * introspection primitive: any valid bearer token (first-party Supabase JWT or
+ * a developer-app OAuth token) resolves to its owner's identity. Mirrors the
+ * `profiles` identity columns server-side — the route is the source of truth.
+ */
+interface UserIdentity {
+    /** Nodaro user id (= the Supabase auth user id). */
+    readonly id: string;
+    readonly email: string;
+    /** Human-readable display name (from `profiles.full_name`); `null` if unset. */
+    readonly displayName: string | null;
+    /** Avatar URL; `null` if unset. */
+    readonly avatarUrl: string | null;
+    /** Subscription tier (e.g. "free", "pro"). */
+    readonly tier: string;
+}
+declare class NodaroClient {
+    readonly baseUrl: string;
+    readonly auth: Auth;
+    readonly timeoutMs: number;
+    private readonly fetchOverride;
+    /**
+     * Resolved lazily so consumers can swap `globalThis.fetch` after the
+     * client has been constructed (e.g. test mocks). Always rebound to the
+     * global object — native fetch throws "Illegal invocation" when its
+     * `this` is anything else.
+     */
+    get fetch(): typeof fetch;
+    readonly workflows: WorkflowsResource;
+    readonly projects: ProjectsResource;
+    readonly jobs: JobsResource;
+    readonly executions: ExecutionsResource;
+    readonly nodes: NodesResource;
+    readonly developerApps: DeveloperAppsResource;
+    readonly oauth: OAuthResource;
+    readonly apps: AppsResource;
+    readonly characters: CharactersResource;
+    readonly locations: LocationsResource;
+    readonly objects: ObjectsResource;
+    readonly creatures: CreaturesResource;
+    readonly pipelines: PipelinesResource;
+    readonly reduce: ReduceResource;
+    readonly promptHelper: PromptHelperResource;
+    readonly voices: VoicesResource;
+    readonly credits: CreditsResource;
+    readonly uploads: UploadsResource;
+    readonly library: LibraryResource;
+    readonly presets: PresetsResource;
+    readonly pickerCatalogs: PickerCatalogsResource;
+    readonly community: CommunityResource;
+    constructor(opts: ClientOptions);
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * `GET /v1/me` → the authenticated user's identity (see {@link UserIdentity}).
+     * Unwraps the `{ data }` envelope. Throws `UnauthorizedError` (401) when the
+     * token is missing/invalid, and the SDK's other typed errors as usual.
+     */
+    me(): Promise<UserIdentity>;
+    private buildUrl;
+}
+/** Factory function — preferred entry point. */
+declare function createClient(opts: ClientOptions): NodaroClient;
+
+declare class NodaroError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+declare class UnauthorizedError extends NodaroError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends NodaroError {
+    readonly missingScope?: string | undefined;
+    constructor(message?: string, missingScope?: string | undefined);
+}
+declare class NotFoundError extends NodaroError {
+    constructor(message?: string);
+}
+declare class RateLimitedError extends NodaroError {
+    constructor(message?: string);
+}
+declare class InsufficientCreditsError extends NodaroError {
+    readonly required?: number | undefined;
+    readonly available?: number | undefined;
+    constructor(message?: string, required?: number | undefined, available?: number | undefined);
+}
+declare class StorageExceededError extends NodaroError {
+    readonly limitBytes?: number | undefined;
+    constructor(message?: string, limitBytes?: number | undefined);
+}
+/**
+ * A job reached a terminal `failed`/`cancelled` status while being awaited by
+ * `nodes.runAndWait` / `nodes.runMany`. Not an HTTP-level error (the polls
+ * themselves succeeded), so `status` is 0 — distinguish it by type/`code`.
+ * Carries the job's own `error_message` (as the message) and `jobId`.
+ */
+declare class JobFailedError extends NodaroError {
+    readonly jobId: string;
+    /** The terminal status that triggered the failure (`failed` | `cancelled`). */
+    readonly jobStatus: "failed" | "cancelled";
+    constructor(message: string, jobId: string, 
+    /** The terminal status that triggered the failure (`failed` | `cancelled`). */
+    jobStatus?: "failed" | "cancelled");
+}
+/**
+ * `nodes.runAndWait` polled past its `maxMs` deadline without the job reaching
+ * a terminal status. Not an HTTP error — `status` is 0; catch by type/`code`.
+ */
+declare class JobTimeoutError extends NodaroError {
+    readonly jobId: string;
+    /** The wall-clock deadline (ms) that was exceeded. */
+    readonly timeoutMs: number;
+    constructor(message: string, jobId: string, 
+    /** The wall-clock deadline (ms) that was exceeded. */
+    timeoutMs: number);
+}
+/**
+ * The caller's `AbortSignal` fired while `nodes.runAndWait` was polling (or it
+ * was already aborted on entry). Polling stops and this rejects. Not an HTTP
+ * error — `status` is 0; catch by type/`code`.
+ */
+declare class JobAbortedError extends NodaroError {
+    readonly jobId?: string | undefined;
+    constructor(message?: string, jobId?: string | undefined);
+}
+interface ApiErrorBody {
+    error?: {
+        code?: string;
+        message?: string;
+        missingScope?: string;
+        required?: number;
+        available?: number;
+        limitBytes?: number;
+        [key: string]: unknown;
+    };
+}
+declare function throwFromResponse(status: number, body: ApiErrorBody): never;
+
+export { type AccessTokenResponse, type AnalyzeInput, type AnalyzeResult, type AppRun, type AppRunResult, type ApplyChatProposalResult, type ApproveCreatureMainImageResult, type ApproveMainImageResult, type ApproveObjectMainImageResult, type ApprovePortraitResult, AppsResource, type Auth, type BranchPipelineInput, type BranchPipelineResult, CREATURE_ASSET_TYPES, CallbackAuth, type CancelExecutionParams, type CancelJobResult, type Character, type CharacterDetail, type CharacterUsage, CharactersResource, type ChatStageResult, type ChatTurn, type ClientOptions, CommunityResource, type CreateCreatureInput, type CreateDeveloperAppInput, type CreateDeveloperAppResult, type CreateLocationInput, type CreateObjectInput, type CreateProjectInput, type CreateWorkflowInput, type Creature, type CreatureAssetType, type CreatureDetail, type CreatureReferencePhoto, type CreatureReferencePhotoKind, CreaturesResource, CreditsResource, type DeleteAppRunResult, type DeveloperApp, type DeveloperAppScope, type DeveloperAppStatus, DeveloperAppsResource, type DuplicateCharacterInput, type EnhanceInput, type ExchangeCodeInput, type ExecutionStatus, type ExecutionTriggerType, ExecutionsResource, type FactoryPresetsResult, ForbiddenError, type GenerateAssetInput, type GenerateCharacterInput, type GenerateCharacterResult, type GenerateCreatureAssetInput, type GenerateCreatureAssetResult, type GenerateCreatureInput, type GenerateCreatureMotionInput, type GenerateCreatureMotionResult, type GenerateCreatureResult, type GenerateImageParams, type GenerateInput, type GenerateLocationAssetInput, type GenerateLocationInput, type GenerateLocationResult, type GenerateMotionInput, type GenerateObjectAssetInput, type GenerateObjectAssetResult, type GenerateObjectInput, type GenerateObjectMotionInput, type GenerateObjectMotionResult, type GenerateObjectResult, type GenerateSurroundContinuationInput, type GenerateVideoParams, type GetPickerCatalogOptions, InsufficientCreditsError, type Job, JobAbortedError, JobFailedError, type JobStatus, type JobStatusResult, JobTimeoutError, JobsResource, type LibraryAsset, LibraryResource, type ListAppRunsParams, type ListAppsParams, type ListAppsResult, type ListCharactersParams, type ListCreaturesParams, type ListExecutionsForWorkflowParams, type ListExecutionsPage, type ListLibraryParams, type ListLibraryResult, type ListLocationsParams, type ListObjectsParams, type ListWorkflowsParams, type Location, type LocationDetail, type LocationReferencePhoto, type LocationReferencePhotoKind, LocationsResource, type ModelCostsResult, NodaroClient, NodaroError, type NodeCategory, type NodeDescriptor, type NodeExecutionState, type NodeInputField, type NodeInputSchema, type NodeJobOutput, type NodePreset, type NodePresetGroup, NodesResource, NotFoundError, type OAuthAppInfo, OAuthResource, type Object$1 as Object, type ObjectCategory, type ObjectDetail, type ObjectReferencePhoto, type ObjectReferencePhotoKind, ObjectsResource, type OutputType, type PickerCatalog, type PickerCatalogSummary, PickerCatalogsResource, type PickerDimension, type PickerOption, PipelinesResource, PresetsResource, type Project, ProjectsResource, PromptHelperResource, type PromptResult, type PublishedApp, type PublishedAppDetail, RateLimitedError, type RecaptionCreatureResult, type RecaptionLocationResult, type RecaptionObjectResult, type RecaptionResult, type ReduceInput, ReduceResource, type ReduceResult, type ReferencePhoto, type ReferencePhotoKind, type RotateSecretResult, type RunAndWaitOptions, type RunManyResult, type RunNodeResult, type RunWorkflowParams, type RunWorkflowResult, StaticTokenAuth, StorageExceededError, type StructuredReferenceParams, UnauthorizedError, type UpdateCreatureInput, type UpdateCreatureResult, type UpdateDeveloperAppInput, type UpdateLocationInput, type UpdateLocationResult, type UpdateObjectInput, type UpdateObjectResult, type UpdateProjectInput, type UpdateWorkflowInput, type UploadResult, UploadsResource, type UpsertCharacterInput, type UpsertCharacterResult, type UpsertCreatureInput, type UpsertCreatureResult, type UpsertObjectInput, type UpsertObjectResult, type UserBalance, type UserIdentity, type VoiceChangerProInput, type VoiceChangerProVoice, VoicesResource, type Workflow, type WorkflowExecution, type WorkflowExecutionSummary, WorkflowsResource, buildPersonSeedPrompt, createClient, supabaseAuth, throwFromResponse };