@nodaro/sdk 2.29.0 → 2.32.0

package/dist/entries/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"webhooks.js"}

package/dist/entries/workflows.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+require('../chunk-45CK55BH.cjs');
+var chunkVGWOIWRQ_cjs = require('../chunk-VGWOIWRQ.cjs');
+
+
+
+Object.defineProperty(exports, "WorkflowsResource", {
+  enumerable: true,
+  get: function () { return chunkVGWOIWRQ_cjs.WorkflowsResource; }
+});
+//# sourceMappingURL=workflows.cjs.map
+//# sourceMappingURL=workflows.cjs.map

package/dist/entries/workflows.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"workflows.cjs"}

package/dist/entries/workflows.d.cts

@@ -0,0 +1,393 @@
+import { GenericNode, GenericEdge } from '@nodaro/shared/types';
+export { GenericEdge, GenericNode } from '@nodaro/shared/types';
+import { WorkflowExport, WorkflowImportReport } from '@nodaro/shared/workflow';
+export { WorkflowExport, WorkflowExportCharacter, WorkflowExportLocation, WorkflowExportObject } from '@nodaro/shared/workflow';
+import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.cjs';
+import { CollaboratorRole, WorkflowVisibility } from '@nodaro/shared/organizations';
+import '@nodaro/shared/apps';
+
+/**
+ * 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;
+    /**
+     * Optimistic concurrency: the `updatedAt` your copy of the workflow was
+     * loaded with. When the row has since been written by another tab/device,
+     * the update is rejected with HTTP 409 `workflow_conflict`
+     * (`WorkflowConflictError`) carrying the current record — re-read/merge and
+     * retry instead of last-writer-wins clobbering the other writer's changes.
+     * Omit for the legacy unconditional replace.
+     */
+    expectedUpdatedAt?: string;
+    /**
+     * Optimistic concurrency by monotonic version — preferred over
+     * `expectedUpdatedAt` (integer bumped by the DB on every content change).
+     */
+    expectedVersion?: number;
+}
+interface RunWorkflowParams {
+    /**
+     * Optional subset of node IDs to execute. Omit to run the full workflow.
+     * With `continueMode: "from-failed"`, the nodes to consider (default: the
+     * nodes the run's chain was first started on, plus every node left failed or
+     * held back; see `continueMode`); the run executes only those the failed run
+     * did not complete. Every id sent counts as named: a node of work no run of
+     * the chain ever ran (each only handed on its saved results) runs and is
+     * priced, while a source, trigger, parameter picker or container keeps what
+     * the run handed on and a node set to skip never runs.
+     */
+    nodeIds?: string[];
+    /**
+     * Per-node field overrides for this run only, `{ [nodeId]: { field: value } }`,
+     * shallow-merged over each node's saved data (the node's saved results are
+     * not used). A run through the API has nobody to review a Preview render, so
+     * a workflow whose Apply EDL render is set to Preview is refused
+     * (`preview_review_required`) unless the run sets it to Final:
+     * `{ [renderNodeId]: { quality: "final" } }`. A node with Review before
+     * render on (Tighten Episode, Trailer) is refused the same way (turn its
+     * review off). A failed execution records what held it —
+     * `preview_review_required` / `preview_render_nested` (a render),
+     * `…_review_on` (a review-on node) or `…_mixed` (both); match all six with
+     * `isPreviewRefusalCode` from `@nodaro/shared`. A review-on Tighten Episode
+     * fed by a List is refused with `use_case_review_list_driven`; a Trailer fed
+     * by a List, with `use_case_list_driven`.
+     */
+    inputOverrides?: Record<string, Record<string, unknown>>;
+    /**
+     * Continue from an earlier execution of this workflow — Render final after a
+     * run that stopped at its preview, or (with `continueMode: "from-failed"`) a
+     * failed run from where it stopped. The run executes `nodeIds` only
+     * (required with this field, except with `continueMode`); every other node
+     * hands on what that execution produced, not the workflow's saved results,
+     * and an Edit Plan hands on its plan with the person's review applied. The
+     * execution must be your own `completed` run of this workflow (`failed`,
+     * with `continueMode`), not of a published app version. Refused with
+     * `continuation_subset_required`, `continuation_not_found` (404),
+     * `continuation_workflow_mismatch`, `continuation_version_mismatch` or
+     * `continuation_not_completed` (409). A continuation its payer cannot cover
+     * (with or without `continueMode`, priced on the nodes it runs) throws
+     * `InsufficientCreditsError` before any execution exists, checked as a
+     * {@link WorkflowsResource.renderFinal} is.
+     */
+    continueFromExecutionId?: string;
+    /**
+     * `"from-failed"`: continue a FAILED run (`continueFromExecutionId`) from
+     * where it stopped. It runs every node that run did not complete — of
+     * `nodeIds`, which default to the nodes the run was started on (a run
+     * started on named nodes is continued on those, a run of every node on every
+     * node; a continuation of a continuation keeps those of the first run of its
+     * chain) plus every node the run left failed or held back — and hands on
+     * what it completed,
+     * never run or charged again. That is per node: a node that failed runs
+     * again in full, every list item included. When a later continuation of it
+     * completed only part of what it left (a narrower `nodeIds`), the run builds
+     * on the newest such one: it is seeded from that run and runs only what is
+     * still left ({@link RunWorkflowResult.continuedFrom} names it). A node
+     * `nodeIds` names that no run of the chain ever ran runs too, and is priced
+     * (see `nodeIds`). A Render
+     * final, or a run of named nodes, continuing the newest of those counts as
+     * one of them too. Not combinable with {@link renderFinal}. Refused with
+     * `continuation_not_failed` (409) for a run that did not fail,
+     * `continuation_superseded` (409) when a later continuation supersedes it —
+     * the message names that run: one that failed (continue that one instead),
+     * or one that completed all this run left (the work is done, and its results
+     * are on that run) — `continuation_preview_pending` (409, a
+     * `ContinuationPreviewPendingError`) when the newest later continuation
+     * stopped at a Preview review of a render or of a Tighten Episode (the error
+     * names that run, what holds it, and in `next` the run that finishes it:
+     * `client.workflows.run(workflowId, error.next)` first — for a single render,
+     * its {@link renderFinal}), and
+     * `continuation_subset_required` (409) when nothing is left to run. Send an
+     * {@link RunWorkflowOptions.idempotencyKey} with each continuation.
+     */
+    continueMode?: "from-failed";
+}
+/** Per-call options for {@link WorkflowsResource.run}. */
+interface RunWorkflowOptions {
+    /**
+     * Sent as the `Idempotency-Key` header (at least 8 characters; the server
+     * ignores a shorter one). Reuse the same value when retrying the same
+     * request: the server answers the run it already started (`deduped: true`)
+     * instead of starting a second one — or, once that run is under way or has
+     * superseded the one it continued, refuses with `already_running` (an
+     * `AlreadyRunningError` carrying its `executionId`) or
+     * `continuation_superseded` naming it. Either way nothing runs twice.
+     */
+    idempotencyKey?: string;
+}
+interface RunWorkflowResult {
+    executionId: string;
+    status: "pending" | "running";
+    /** `true` when an `idempotencyKey` retry found the run already started: `executionId` is that run. */
+    deduped?: boolean;
+    /**
+     * With `continueMode: "from-failed"`: the execution the run continued from —
+     * its states seed the run. The run asked for (`continueFromExecutionId`), or
+     * the newest later continuation of it that completed part of what it left.
+     * Absent on any other run, and on a `deduped` answer.
+     */
+    continuedFrom?: string;
+}
+/**
+ * A Render final: the Apply EDL render at Final for this run only, and every
+ * node after it (Camera Switch first, in multicam). The server works out which
+ * nodes run — the same rule as the editor's Render final button.
+ */
+interface RenderFinalParams {
+    /** The Apply EDL render node to finalize. */
+    renderNodeId: string;
+    /**
+     * The execution that stopped at the preview: your own `completed` run of
+     * this workflow. Every node the Render final does not run hands on what it
+     * produced (an Edit Plan hands on its plan with the review applied).
+     */
+    continueFromExecutionId: string;
+}
+/** What a Render final will run and charge. Nothing is created by the quote. */
+interface RenderFinalQuote {
+    renderNodeId: string;
+    /** The nodes the run executes, in canvas order. */
+    nodeIds: string[];
+    /** The one-shot override it runs with: `{ [renderNodeId]: { quality: "final" } }`. */
+    inputOverrides: Record<string, Record<string, unknown>>;
+    /** Estimated credits; `null` in an edition without credits. */
+    estimatedCredits: number | null;
+    /**
+     * Whether the payer can cover `estimatedCredits`; `null` in an edition
+     * without credits. When `false`, {@link WorkflowsResource.renderFinal} is
+     * refused with `InsufficientCreditsError` before any execution exists.
+     */
+    sufficient: boolean | null;
+    /**
+     * The payer's spendable credits; `null` when it is not yours to see (a
+     * deployment's operator pays) or a workspace budget pays.
+     */
+    available: number | null;
+}
+/** A person granted access to a workflow. Email is never returned (privacy). */
+interface Collaborator {
+    userId: string;
+    name?: string | null;
+    avatar?: string | null;
+    role: CollaboratorRole;
+}
+interface AddCollaboratorInput {
+    /** Provide exactly one of `userId` or `email`. */
+    userId?: string;
+    email?: string;
+    role: CollaboratorRole;
+}
+/** A workflow someone else shared with you, plus the role you hold on it. */
+interface SharedWorkflow extends Workflow {
+    grantedRole: CollaboratorRole;
+}
+/** A grant dropped because a move took the workflow out of the workspace the
+ *  access came from. */
+interface DroppedCollaborator {
+    userId: string;
+    name: string | null;
+}
+/**
+ * The people a workflow is shared with — reached as `client.workflows.collaborators`.
+ * All four endpoints are served by the organizations feature and exist only when
+ * it is enabled server-side; against an install without it they 404
+ * (→ `NotFoundError`). The active workspace travels on the request like every
+ * other call, so a workspace admin's grants apply automatically.
+ */
+declare class WorkflowCollaboratorsResource {
+    private client;
+    constructor(client: NodaroClientCore);
+    /** List a workflow's collaborators (id, name, avatar, role — never email). */
+    list(workflowId: string): Promise<{
+        data: Collaborator[];
+    }>;
+    /** Add a collaborator by `userId` OR `email` (exactly one), at the given role. */
+    add(workflowId: string, input: AddCollaboratorInput): Promise<{
+        data: {
+            userId: string;
+            role: CollaboratorRole;
+        };
+    }>;
+    /** Change a collaborator's role. */
+    update(workflowId: string, userId: string, input: {
+        role: CollaboratorRole;
+    }): Promise<{
+        data: {
+            userId: string;
+            role: CollaboratorRole;
+        };
+    }>;
+    /** Remove a collaborator — or yourself. Returns `{ success: true }`. */
+    remove(workflowId: string, userId: string): Promise<{
+        success: true;
+    }>;
+}
+declare class WorkflowsResource {
+    private client;
+    /** The people this workflow is shared with. See {@link WorkflowCollaboratorsResource}. */
+    readonly collaborators: WorkflowCollaboratorsResource;
+    constructor(client: NodaroClientCore);
+    /** 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 }`. Throws `NotFoundError`
+     *  when the id doesn't exist or isn't yours (the delete is not silent). */
+    delete(id: string): Promise<{
+        success: true;
+    }>;
+    /**
+     * Run a workflow. Returns the executionId for polling via
+     * `client.executions.get(executionId)`.
+     */
+    run(id: string, params?: RunWorkflowParams, options?: RunWorkflowOptions): Promise<RunWorkflowResult>;
+    /**
+     * Render final (`renderFinal` on `POST /v1/workflows/:id/run`): run the
+     * render at Final for this run only, and every node after it, continuing the
+     * execution that stopped at its preview. The server derives the nodes and
+     * the override — send nothing else. Quote it first with
+     * {@link estimateRenderFinal}. Refused with `render_final_node_not_found`,
+     * `render_final_not_a_render`, or a continuation code (see `run`); a run
+     * its payer cannot cover throws `InsufficientCreditsError` (with `required`
+     * and, when it is yours to see, `available`) before any execution exists.
+     */
+    renderFinal(id: string, params: RenderFinalParams): Promise<RunWorkflowResult>;
+    /**
+     * Quote a Render final (`POST /v1/workflows/:id/render-final/estimate`): the
+     * nodes it will run, the override it runs with and its estimated credits.
+     * Nothing is created or charged.
+     */
+    estimateRenderFinal(id: string, params: RenderFinalParams): Promise<{
+        data: RenderFinalQuote;
+    }>;
+    /**
+     * 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, creatures, locations)
+     * under your account, and re-points BOTH the entity nodes and every `@`-chip
+     * (`ConnectedReference`) bound in the graph at the rows it created.
+     * Media the bundle references on other hosts is copied onto this instance's
+     * storage where reachable; a bundled entity's images are copied whoever
+     * hosts them, because they are the exporter's bytes and their lifecycle is
+     * not yours. `importReport` says what was copied, what could not be reached
+     * and what was skipped (and why); `assetIdMap` maps each bundled entity id
+     * to the row created for it (for chips you hold outside the graph), and
+     * `assetsSkipped` names the entities your storage quota left uncreated —
+     * the workflow itself still lands.
+     */
+    import(input: WorkflowExport & {
+        projectId: string;
+    }): Promise<{
+        data: Workflow;
+        importReport?: WorkflowImportReport;
+    }>;
+    /**
+     * Set a workflow's visibility — `"private"` (creator + explicit collaborators)
+     * or `"workspace"` (everyone in its workspace). Only the creator or a workspace
+     * admin may change it; anyone else gets HTTP 403. Thin wrapper over `update()`:
+     * the visibility lever lives on `PATCH /v1/workflows/:id`.
+     */
+    setVisibility(id: string, visibility: WorkflowVisibility): Promise<{
+        data: Workflow;
+    }>;
+    /**
+     * Move a workflow to another project (`POST /v1/workflows/:id/move`); its folder
+     * is cleared. When the move takes the workflow out of a workspace, collaborator
+     * grants that came from that workspace are dropped and returned as
+     * `droppedCollaborators`.
+     */
+    move(id: string, params: {
+        projectId: string;
+    }): Promise<{
+        data: Workflow;
+        droppedCollaborators: DroppedCollaborator[];
+    }>;
+    /**
+     * Workflows other people shared with you (`GET /v1/workflows/shared-with-me`) —
+     * grants on work that is NOT in a workspace you belong to (workspace work already
+     * shows in that workspace's own lists). Each carries the `grantedRole` you hold.
+     * Empty when the organizations feature is off server-side.
+     */
+    sharedWithMe(): Promise<{
+        data: SharedWorkflow[];
+    }>;
+}
+
+export { type AddCollaboratorInput, type Collaborator, type CreateWorkflowInput, type DroppedCollaborator, type ListWorkflowsParams, type RenderFinalParams, type RenderFinalQuote, type RunWorkflowOptions, type RunWorkflowParams, type RunWorkflowResult, type SharedWorkflow, type UpdateWorkflowInput, type Workflow, WorkflowsResource };