@retab/node 1.0.87 → 1.0.91

package/dist/api/workflows/runs/client.d.ts

@@ -1,9 +1,14 @@
 import { CompositionClient, RequestOptions } from "../../../client.js";
-import { MIMEDataInput, WorkflowRun } from "../../../types.js";
+import { MIMEDataInput, WorkflowRun, PaginatedList, CancelWorkflowResponse, ResumeWorkflowResponse } from "../../../types.js";
+import APIWorkflowRunSteps from "./steps/client.js";
 /**
  * Workflow Runs API client for managing workflow executions.
+ *
+ * Sub-clients:
+ * - steps: Step output operations (get, getBatch)
  */
 export default class APIWorkflowRuns extends CompositionClient {
+    steps: APIWorkflowRunSteps;
     constructor(client: CompositionClient);
     /**
      * Run a workflow with the provided inputs.
@@ -56,5 +61,170 @@ export default class APIWorkflowRuns extends CompositionClient {
      * ```
      */
     get(runId: string, options?: RequestOptions): Promise<WorkflowRun>;
+    /**
+     * List workflow runs with filtering and pagination.
+     *
+     * @example
+     * ```typescript
+     * const runs = await client.workflows.runs.list({
+     *     workflowId: "wf_abc123",
+     *     status: "completed",
+     *     limit: 10,
+     * });
+     * console.log(`Found ${runs.data.length} runs`);
+     * ```
+     */
+    list({ workflowId, status, statuses, excludeStatus, triggerType, triggerTypes, fromDate, toDate, minCost, maxCost, minDuration, maxDuration, search, sortBy, fields, before, after, limit, order, }?: {
+        workflowId?: string;
+        status?: "pending" | "running" | "completed" | "error" | "waiting_for_human" | "cancelled";
+        statuses?: string;
+        excludeStatus?: "pending" | "running" | "completed" | "error" | "waiting_for_human" | "cancelled";
+        triggerType?: "manual" | "api" | "schedule" | "webhook" | "restart";
+        triggerTypes?: string;
+        fromDate?: string;
+        toDate?: string;
+        minCost?: number;
+        maxCost?: number;
+        minDuration?: number;
+        maxDuration?: number;
+        search?: string;
+        sortBy?: string;
+        fields?: string;
+        before?: string;
+        after?: string;
+        limit?: number;
+        order?: "asc" | "desc";
+    }, options?: RequestOptions): Promise<PaginatedList>;
+    /**
+     * Delete a workflow run and its associated step data.
+     *
+     * @param runId - The ID of the workflow run to delete
+     * @param options - Optional request options
+     *
+     * @example
+     * ```typescript
+     * await client.workflows.runs.delete("run_abc123");
+     * ```
+     */
+    delete(runId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Cancel a running or pending workflow run.
+     *
+     * @param runId - The ID of the workflow run to cancel
+     * @param commandId - Optional idempotency key for deduplicating cancel commands
+     * @param options - Optional request options
+     * @returns The updated run with cancellation status
+     *
+     * @example
+     * ```typescript
+     * const result = await client.workflows.runs.cancel("run_abc123");
+     * console.log(`Cancellation: ${result.cancellation_status}`);
+     * ```
+     */
+    cancel(runId: string, { commandId }?: {
+        commandId?: string;
+    }, options?: RequestOptions): Promise<CancelWorkflowResponse>;
+    /**
+     * Restart a completed or failed workflow run with the same inputs.
+     *
+     * @param runId - The ID of the workflow run to restart
+     * @param commandId - Optional idempotency key for deduplicating restart commands
+     * @param options - Optional request options
+     * @returns The new workflow run
+     *
+     * @example
+     * ```typescript
+     * const newRun = await client.workflows.runs.restart("run_abc123");
+     * console.log(`New run: ${newRun.id}`);
+     * ```
+     */
+    restart(runId: string, { commandId }?: {
+        commandId?: string;
+    }, options?: RequestOptions): Promise<WorkflowRun>;
+    /**
+     * Resume a workflow run after human-in-the-loop (HIL) review.
+     *
+     * @param runId - The ID of the workflow run to resume
+     * @param nodeId - The ID of the HIL node being approved/rejected
+     * @param approved - Whether the human approved the data
+     * @param modifiedData - Optional modified data if the human made changes
+     * @param commandId - Optional idempotency key for deduplicating resume commands
+     * @param options - Optional request options
+     * @returns The resume response with status and queue information
+     *
+     * @example
+     * ```typescript
+     * const result = await client.workflows.runs.resume("run_abc123", {
+     *     nodeId: "hil-node-1",
+     *     approved: true,
+     *     modifiedData: { field: "corrected value" },
+     * });
+     * console.log(`Resume status: ${result.resume_status}`);
+     * ```
+     */
+    resume(runId: string, { nodeId, approved, modifiedData, commandId, }: {
+        nodeId: string;
+        approved: boolean;
+        modifiedData?: Record<string, unknown> | null;
+        commandId?: string;
+    }, options?: RequestOptions): Promise<ResumeWorkflowResponse>;
+    /**
+     * Poll a workflow run until it reaches a terminal state.
+     *
+     * Terminal states: "completed", "error", "cancelled".
+     *
+     * @param runId - The ID of the workflow run to wait for
+     * @param pollIntervalMs - Milliseconds between polls (default: 2000)
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 600000 = 10 minutes)
+     * @returns The workflow run in a terminal state
+     * @throws Error if the run doesn't complete within the timeout
+     *
+     * @example
+     * ```typescript
+     * const run = await client.workflows.runs.waitForCompletion("run_abc123", {
+     *     pollIntervalMs: 1000,
+     *     timeoutMs: 300000,
+     * });
+     * console.log(`Final status: ${run.status}`);
+     * ```
+     */
+    waitForCompletion(runId: string, { pollIntervalMs, timeoutMs, }?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<WorkflowRun>;
+    /**
+     * Create a workflow run and wait for it to complete.
+     *
+     * Convenience method that combines create() and waitForCompletion().
+     *
+     * @param workflowId - The ID of the workflow to run
+     * @param documents - Mapping of start node IDs to their input documents
+     * @param jsonInputs - Mapping of start_json node IDs to their input JSON data
+     * @param textInputs - Mapping of start_text node IDs to their input text
+     * @param pollIntervalMs - Milliseconds between polls (default: 2000)
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 600000)
+     * @param options - Optional request options
+     * @returns The workflow run in a terminal state
+     *
+     * @example
+     * ```typescript
+     * const run = await client.workflows.runs.createAndWait({
+     *     workflowId: "wf_abc123",
+     *     documents: { "start-node-1": "./invoice.pdf" },
+     *     timeoutMs: 120000,
+     * });
+     * if (run.status === "completed") {
+     *     console.log("Outputs:", run.final_outputs);
+     * }
+     * ```
+     */
+    createAndWait({ workflowId, documents, jsonInputs, textInputs, pollIntervalMs, timeoutMs, }: {
+        workflowId: string;
+        documents?: Record<string, MIMEDataInput>;
+        jsonInputs?: Record<string, Record<string, unknown>>;
+        textInputs?: Record<string, string>;
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }, options?: RequestOptions): Promise<WorkflowRun>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/api/workflows/runs/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/api/workflows/runs/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,aAAa,EAAa,WAAW,EAAgB,MAAM,mBAAmB,CAAC;AAExF;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,SAAQ,iBAAiB;gBAC9C,MAAM,EAAE,iBAAiB;IAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,MAAM,CACR,EACI,UAAU,EACV,SAAS,EACT,UAAU,EACV,UAAU,GACb,EAAE;QACC,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;QAC1C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACrD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACvC,EACD,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,WAAW,CAAC;IA2CvB;;;;;;;;;;;;OAYG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;CAQ3E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/api/workflows/runs/client.ts"],"names":[],"mappings":"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"}

package/dist/api/workflows/runs/client.js

@@ -1,11 +1,20 @@
 import { CompositionClient } from "../../../client.js";
-import { ZMIMEData, ZWorkflowRun } from "../../../types.js";
+import { ZMIMEData, ZWorkflowRun, ZPaginatedList, ZCancelWorkflowResponse, ZResumeWorkflowResponse, } from "../../../types.js";
+import APIWorkflowRunSteps from "./steps/client.js";
+const TERMINAL_STATUSES = new Set(["completed", "error", "cancelled"]);
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Workflow Runs API client for managing workflow executions.
+ *
+ * Sub-clients:
+ * - steps: Step output operations (get, getBatch)
  */
 export default class APIWorkflowRuns extends CompositionClient {
     constructor(client) {
         super(client);
+        this.steps = new APIWorkflowRunSteps(this);
     }
     /**
      * Run a workflow with the provided inputs.
@@ -39,15 +48,12 @@ export default class APIWorkflowRuns extends CompositionClient {
      * ```
      */
     async create({ workflowId, documents, jsonInputs, textInputs, }, options) {
-        // Build the request body
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const body = {};
-        // Convert each document to MIMEData format expected by backend
         if (documents) {
             const documentsPayload = {};
             for (const [nodeId, document] of Object.entries(documents)) {
                 const parsedDocument = await ZMIMEData.parseAsync(document);
-                // Extract base64 content from data URL
                 const content = parsedDocument.url.split(",")[1];
                 const mimeType = parsedDocument.url.split(";")[0].split(":")[1];
                 documentsPayload[nodeId] = {
@@ -58,11 +64,9 @@ export default class APIWorkflowRuns extends CompositionClient {
             }
             body.documents = documentsPayload;
         }
-        // Add JSON inputs directly
         if (jsonInputs) {
             body.json_inputs = jsonInputs;
         }
-        // Add text inputs directly
         if (textInputs) {
             body.text_inputs = textInputs;
         }
@@ -95,4 +99,227 @@ export default class APIWorkflowRuns extends CompositionClient {
             headers: options?.headers,
         });
     }
+    /**
+     * List workflow runs with filtering and pagination.
+     *
+     * @example
+     * ```typescript
+     * const runs = await client.workflows.runs.list({
+     *     workflowId: "wf_abc123",
+     *     status: "completed",
+     *     limit: 10,
+     * });
+     * console.log(`Found ${runs.data.length} runs`);
+     * ```
+     */
+    async list({ workflowId, status, statuses, excludeStatus, triggerType, triggerTypes, fromDate, toDate, minCost, maxCost, minDuration, maxDuration, search, sortBy, fields, before, after, limit = 20, order = "desc", } = {}, options) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const params = {
+            workflow_id: workflowId,
+            status,
+            statuses,
+            exclude_status: excludeStatus,
+            trigger_type: triggerType,
+            trigger_types: triggerTypes,
+            from_date: fromDate,
+            to_date: toDate,
+            min_cost: minCost,
+            max_cost: maxCost,
+            min_duration: minDuration,
+            max_duration: maxDuration,
+            search,
+            sort_by: sortBy,
+            fields,
+            before,
+            after,
+            limit,
+            order,
+        };
+        const cleanParams = Object.fromEntries(Object.entries(params).filter(([_, v]) => v !== undefined));
+        return this._fetchJson(ZPaginatedList, {
+            url: "/v1/workflows/runs",
+            method: "GET",
+            params: { ...cleanParams, ...(options?.params || {}) },
+            headers: options?.headers,
+        });
+    }
+    /**
+     * Delete a workflow run and its associated step data.
+     *
+     * @param runId - The ID of the workflow run to delete
+     * @param options - Optional request options
+     *
+     * @example
+     * ```typescript
+     * await client.workflows.runs.delete("run_abc123");
+     * ```
+     */
+    async delete(runId, options) {
+        return this._fetchJson({
+            url: `/v1/workflows/runs/${runId}`,
+            method: "DELETE",
+            params: options?.params,
+            headers: options?.headers,
+        });
+    }
+    /**
+     * Cancel a running or pending workflow run.
+     *
+     * @param runId - The ID of the workflow run to cancel
+     * @param commandId - Optional idempotency key for deduplicating cancel commands
+     * @param options - Optional request options
+     * @returns The updated run with cancellation status
+     *
+     * @example
+     * ```typescript
+     * const result = await client.workflows.runs.cancel("run_abc123");
+     * console.log(`Cancellation: ${result.cancellation_status}`);
+     * ```
+     */
+    async cancel(runId, { commandId } = {}, options) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = {};
+        if (commandId !== undefined)
+            body.command_id = commandId;
+        return this._fetchJson(ZCancelWorkflowResponse, {
+            url: `/v1/workflows/runs/${runId}/cancel`,
+            method: "POST",
+            body: { ...body, ...(options?.body || {}) },
+            params: options?.params,
+            headers: options?.headers,
+        });
+    }
+    /**
+     * Restart a completed or failed workflow run with the same inputs.
+     *
+     * @param runId - The ID of the workflow run to restart
+     * @param commandId - Optional idempotency key for deduplicating restart commands
+     * @param options - Optional request options
+     * @returns The new workflow run
+     *
+     * @example
+     * ```typescript
+     * const newRun = await client.workflows.runs.restart("run_abc123");
+     * console.log(`New run: ${newRun.id}`);
+     * ```
+     */
+    async restart(runId, { commandId } = {}, options) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = {};
+        if (commandId !== undefined)
+            body.command_id = commandId;
+        return this._fetchJson(ZWorkflowRun, {
+            url: `/v1/workflows/runs/${runId}/restart`,
+            method: "POST",
+            body: { ...body, ...(options?.body || {}) },
+            params: options?.params,
+            headers: options?.headers,
+        });
+    }
+    /**
+     * Resume a workflow run after human-in-the-loop (HIL) review.
+     *
+     * @param runId - The ID of the workflow run to resume
+     * @param nodeId - The ID of the HIL node being approved/rejected
+     * @param approved - Whether the human approved the data
+     * @param modifiedData - Optional modified data if the human made changes
+     * @param commandId - Optional idempotency key for deduplicating resume commands
+     * @param options - Optional request options
+     * @returns The resume response with status and queue information
+     *
+     * @example
+     * ```typescript
+     * const result = await client.workflows.runs.resume("run_abc123", {
+     *     nodeId: "hil-node-1",
+     *     approved: true,
+     *     modifiedData: { field: "corrected value" },
+     * });
+     * console.log(`Resume status: ${result.resume_status}`);
+     * ```
+     */
+    async resume(runId, { nodeId, approved, modifiedData, commandId, }, options) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = {
+            node_id: nodeId,
+            approved,
+        };
+        if (modifiedData !== undefined)
+            body.modified_data = modifiedData;
+        if (commandId !== undefined)
+            body.command_id = commandId;
+        return this._fetchJson(ZResumeWorkflowResponse, {
+            url: `/v1/workflows/runs/${runId}/resume`,
+            method: "POST",
+            body: { ...body, ...(options?.body || {}) },
+            params: options?.params,
+            headers: options?.headers,
+        });
+    }
+    /**
+     * Poll a workflow run until it reaches a terminal state.
+     *
+     * Terminal states: "completed", "error", "cancelled".
+     *
+     * @param runId - The ID of the workflow run to wait for
+     * @param pollIntervalMs - Milliseconds between polls (default: 2000)
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 600000 = 10 minutes)
+     * @returns The workflow run in a terminal state
+     * @throws Error if the run doesn't complete within the timeout
+     *
+     * @example
+     * ```typescript
+     * const run = await client.workflows.runs.waitForCompletion("run_abc123", {
+     *     pollIntervalMs: 1000,
+     *     timeoutMs: 300000,
+     * });
+     * console.log(`Final status: ${run.status}`);
+     * ```
+     */
+    async waitForCompletion(runId, { pollIntervalMs = 2000, timeoutMs = 600000, } = {}) {
+        if (pollIntervalMs <= 0)
+            throw new Error("pollIntervalMs must be positive");
+        if (timeoutMs <= 0)
+            throw new Error("timeoutMs must be positive");
+        const deadline = Date.now() + timeoutMs;
+        while (true) {
+            const run = await this.get(runId);
+            if (TERMINAL_STATUSES.has(run.status)) {
+                return run;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Workflow run ${runId} did not complete within ${timeoutMs}ms (last status: ${run.status})`);
+            }
+            await sleep(pollIntervalMs);
+        }
+    }
+    /**
+     * Create a workflow run and wait for it to complete.
+     *
+     * Convenience method that combines create() and waitForCompletion().
+     *
+     * @param workflowId - The ID of the workflow to run
+     * @param documents - Mapping of start node IDs to their input documents
+     * @param jsonInputs - Mapping of start_json node IDs to their input JSON data
+     * @param textInputs - Mapping of start_text node IDs to their input text
+     * @param pollIntervalMs - Milliseconds between polls (default: 2000)
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 600000)
+     * @param options - Optional request options
+     * @returns The workflow run in a terminal state
+     *
+     * @example
+     * ```typescript
+     * const run = await client.workflows.runs.createAndWait({
+     *     workflowId: "wf_abc123",
+     *     documents: { "start-node-1": "./invoice.pdf" },
+     *     timeoutMs: 120000,
+     * });
+     * if (run.status === "completed") {
+     *     console.log("Outputs:", run.final_outputs);
+     * }
+     * ```
+     */
+    async createAndWait({ workflowId, documents, jsonInputs, textInputs, pollIntervalMs = 2000, timeoutMs = 600000, }, options) {
+        const run = await this.create({ workflowId, documents, jsonInputs, textInputs }, options);
+        return this.waitForCompletion(run.id, { pollIntervalMs, timeoutMs });
+    }
 }

package/dist/api/workflows/runs/steps/client.d.ts

@@ -0,0 +1,46 @@
+import { CompositionClient, RequestOptions } from "../../../../client.js";
+import { StepOutputResponse, StepOutputsBatchResponse } from "../../../../types.js";
+/**
+ * Workflow Run Steps API client for accessing step-level outputs.
+ *
+ * Usage: `client.workflows.runs.steps.get(runId, nodeId)`
+ */
+export default class APIWorkflowRunSteps extends CompositionClient {
+    constructor(client: CompositionClient);
+    /**
+     * Get the full output data for a specific step in a workflow run.
+     *
+     * @param runId - The ID of the workflow run
+     * @param nodeId - The ID of the node/step to get output for
+     * @param options - Optional request options
+     * @returns The step output with handle outputs and inputs
+     *
+     * @example
+     * ```typescript
+     * const step = await client.workflows.runs.steps.get("run_abc123", "extract-node-1");
+     * console.log(`Step status: ${step.status}, output:`, step.output);
+     * ```
+     */
+    get(runId: string, nodeId: string, options?: RequestOptions): Promise<StepOutputResponse>;
+    /**
+     * Get outputs for multiple steps in a single request.
+     *
+     * @param runId - The ID of the workflow run
+     * @param nodeIds - List of node IDs to fetch outputs for (max 1000)
+     * @param options - Optional request options
+     * @returns Step outputs keyed by node ID
+     *
+     * @example
+     * ```typescript
+     * const batch = await client.workflows.runs.steps.getBatch(
+     *     "run_abc123",
+     *     ["extract-1", "extract-2", "split-1"]
+     * );
+     * for (const [nodeId, step] of Object.entries(batch.outputs)) {
+     *     console.log(`${nodeId}: ${step.status}`);
+     * }
+     * ```
+     */
+    getBatch(runId: string, nodeIds: string[], options?: RequestOptions): Promise<StepOutputsBatchResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/api/workflows/runs/steps/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../../src/api/workflows/runs/steps/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EACH,kBAAkB,EAElB,wBAAwB,EAE3B,MAAM,sBAAsB,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAoB,SAAQ,iBAAiB;gBAClD,MAAM,EAAE,iBAAiB;IAIrC;;;;;;;;;;;;;OAaG;IACG,GAAG,CACL,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,kBAAkB,CAAC;IAS9B;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,wBAAwB,CAAC;CASvC"}

package/dist/api/workflows/runs/steps/client.js

@@ -0,0 +1,62 @@
+import { CompositionClient } from "../../../../client.js";
+import { ZStepOutputResponse, ZStepOutputsBatchResponse, } from "../../../../types.js";
+/**
+ * Workflow Run Steps API client for accessing step-level outputs.
+ *
+ * Usage: `client.workflows.runs.steps.get(runId, nodeId)`
+ */
+export default class APIWorkflowRunSteps extends CompositionClient {
+    constructor(client) {
+        super(client);
+    }
+    /**
+     * Get the full output data for a specific step in a workflow run.
+     *
+     * @param runId - The ID of the workflow run
+     * @param nodeId - The ID of the node/step to get output for
+     * @param options - Optional request options
+     * @returns The step output with handle outputs and inputs
+     *
+     * @example
+     * ```typescript
+     * const step = await client.workflows.runs.steps.get("run_abc123", "extract-node-1");
+     * console.log(`Step status: ${step.status}, output:`, step.output);
+     * ```
+     */
+    async get(runId, nodeId, options) {
+        return this._fetchJson(ZStepOutputResponse, {
+            url: `/v1/workflows/runs/${runId}/steps/${nodeId}`,
+            method: "GET",
+            params: options?.params,
+            headers: options?.headers,
+        });
+    }
+    /**
+     * Get outputs for multiple steps in a single request.
+     *
+     * @param runId - The ID of the workflow run
+     * @param nodeIds - List of node IDs to fetch outputs for (max 1000)
+     * @param options - Optional request options
+     * @returns Step outputs keyed by node ID
+     *
+     * @example
+     * ```typescript
+     * const batch = await client.workflows.runs.steps.getBatch(
+     *     "run_abc123",
+     *     ["extract-1", "extract-2", "split-1"]
+     * );
+     * for (const [nodeId, step] of Object.entries(batch.outputs)) {
+     *     console.log(`${nodeId}: ${step.status}`);
+     * }
+     * ```
+     */
+    async getBatch(runId, nodeIds, options) {
+        return this._fetchJson(ZStepOutputsBatchResponse, {
+            url: `/v1/workflows/runs/${runId}/steps/batch`,
+            method: "POST",
+            body: { node_ids: nodeIds, ...(options?.body || {}) },
+            params: options?.params,
+            headers: options?.headers,
+        });
+    }
+}