@scenario-labs/sdk 0.2.0 → 1.0.0

package/lib/upload.js

@@ -0,0 +1,193 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnhancedUploads = void 0;
+const uploads_1 = require("../resources/uploads.js");
+// AWS S3 multipart upload limits.
+const MIN_PART_SIZE = 6000000; // 6 MB (spec minimum is 5 MiB; a bit over to be safe)
+const MAX_PART_SIZE = 5368709120; // 5 GiB
+const MAX_PARTS = 10000;
+const MAX_FILE_SIZE = 5497558138880; // 5 TiB
+// `validated` is intermediate — the server has validated the upload but
+// hasn't created the asset/model yet, so `entityId` isn't populated.
+// Real terminals are `imported` (asset/model created), `complete`, and
+// `failed`. Everything else means "keep polling".
+const TERMINAL_STATUSES = new Set(['complete', 'failed', 'imported']);
+/**
+ * Enhanced Uploads resource.
+ * All original methods (`create`, `retrieve`, `triggerAction`) are inherited.
+ * Adds `uploadFile()` — a one-call wrapper around the 4-step upload flow:
+ * init → PUT parts to S3 → trigger complete → poll until imported.
+ */
+class EnhancedUploads extends uploads_1.Uploads {
+    /**
+     * Upload a file end-to-end. Computes an optimal part size (within AWS's
+     * 5 MiB / 5 GiB / 10,000-part bounds), uploads all parts in parallel,
+     * triggers completion, polls until the server has validated and imported
+     * the file, and returns the resolved entity.
+     *
+     * The returned type narrows on `kind`: `'model'` returns a Model,
+     * everything else returns an Asset.
+     *
+     * @example
+     * ```ts
+     * // From a file path (Node)
+     * const { asset } = await client.uploads.uploadFile({
+     *   file: './photo.jpg',
+     *   fileName: 'photo.jpg',
+     *   contentType: 'image/jpeg',
+     *   kind: 'image',
+     * });
+     * console.log(asset.id, asset.url);
+     *
+     * // Or from bytes / Blob — anything you already have in memory
+     * await client.uploads.uploadFile({
+     *   file: new Blob([pngBytes], { type: 'image/png' }),
+     *   fileName: 'generated.png',
+     *   contentType: 'image/png',
+     *   kind: 'image',
+     * });
+     * ```
+     */
+    async uploadFile(params, options) {
+        const bytes = await normalizeToBytes(params.file);
+        const fileSize = bytes.byteLength;
+        if (fileSize === 0) {
+            throw new Error('Cannot upload an empty file');
+        }
+        if (fileSize > MAX_FILE_SIZE) {
+            throw new Error(`File size (${fileSize} bytes) exceeds the maximum allowed size of ${MAX_FILE_SIZE} bytes (5 TiB)`);
+        }
+        // Pick the smallest legal part size that fits within MAX_PARTS.
+        const requiredPartSize = Math.ceil(fileSize / MAX_PARTS);
+        const partSize = Math.max(MIN_PART_SIZE, requiredPartSize);
+        if (partSize > MAX_PART_SIZE) {
+            throw new Error(`File size (${fileSize} bytes) requires a part size of ${partSize} bytes, ` +
+                `which exceeds the maximum part size of ${MAX_PART_SIZE} bytes (5 GiB)`);
+        }
+        const partsCount = Math.max(1, Math.ceil(fileSize / partSize));
+        // Step 1 — init upload session and receive presigned S3 URLs.
+        const createBody = {
+            fileName: params.fileName,
+            fileSize,
+            contentType: params.contentType,
+            kind: params.kind,
+            parts: partsCount,
+            ...(params.kind !== 'model' && params.assetOptions ? { assetOptions: params.assetOptions } : {}),
+        };
+        const createRes = await this.create(createBody, options);
+        const session = createRes.upload;
+        const uploadId = session.id;
+        const parts = session.parts;
+        if (parts?.length !== partsCount) {
+            throw new Error(`Expected ${partsCount} presigned part URL(s), got ${parts?.length ?? 0}`);
+        }
+        // Step 2 — PUT each chunk to its presigned S3 URL, with a concurrency cap.
+        const concurrency = Math.max(1, params.partConcurrency ?? 4);
+        await uploadPartsWithConcurrency(bytes, parts, partSize, concurrency);
+        // Step 3 — tell the server all parts are uploaded.
+        await this.triggerAction(uploadId, { action: 'complete' }, options);
+        // Step 4 — poll until the upload has been processed into an entity.
+        const final = await pollUntilImported(() => this.retrieve(uploadId, options), params.pollIntervalMs ?? 2000, params.pollTimeoutMs ?? 300000);
+        if (final.upload.status === 'failed') {
+            throw new Error(`Upload ${uploadId} failed: ${final.upload.errorMessage ?? '<no error message>'}`);
+        }
+        const entityId = final.upload.entityId;
+        if (!entityId) {
+            throw new Error(`Upload ${uploadId} reached status "${final.upload.status}" but has no entityId`);
+        }
+        // Fetch and return the resolved entity (narrowed by kind).
+        if (params.kind === 'model') {
+            const model = await this._client.models.retrieve(entityId);
+            return model;
+        }
+        const asset = await this._client.assets.retrieve(entityId);
+        return asset;
+    }
+}
+exports.EnhancedUploads = EnhancedUploads;
+// ─────────────────────── helpers ───────────────────────
+async function normalizeToBytes(input) {
+    if (typeof input === 'string') {
+        // Dynamic import so browser bundlers don't pull in node:fs.
+        const { readFile } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        return new Uint8Array(await readFile(input));
+    }
+    if (input instanceof Uint8Array) {
+        return input;
+    }
+    if (typeof Blob !== 'undefined' && input instanceof Blob) {
+        return new Uint8Array(await input.arrayBuffer());
+    }
+    throw new Error('uploadFile: unsupported input type — expected a path string, Uint8Array, or Blob');
+}
+async function uploadPartsWithConcurrency(bytes, parts, partSize, concurrency) {
+    // Sort by part number so slicing lines up with the presigned URL order.
+    const sorted = [...parts].sort((a, b) => a.number - b.number);
+    let nextIndex = 0;
+    const workers = Array.from({ length: concurrency }, () => worker());
+    await Promise.all(workers);
+    async function worker() {
+        while (true) {
+            const i = nextIndex++;
+            if (i >= sorted.length)
+                return;
+            const part = sorted[i];
+            if (!part)
+                continue;
+            const start = i * partSize;
+            const end = Math.min(bytes.byteLength, start + partSize);
+            const chunk = bytes.subarray(start, end);
+            const res = await fetch(part.url, { method: 'PUT', body: chunk });
+            if (!res.ok) {
+                throw new Error(`Failed to upload part ${part.number}/${sorted.length}: ${res.status} ${res.statusText}`);
+            }
+        }
+    }
+}
+async function pollUntilImported(retrieve, intervalMs, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const res = await retrieve();
+        const { status } = res.upload;
+        // Return as soon as we have an entityId OR the upload reached a terminal state.
+        if (res.upload.entityId || TERMINAL_STATUSES.has(status)) {
+            return res;
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    throw new Error(`Upload did not reach a terminal status within ${timeoutMs / 1000}s`);
+}
+//# sourceMappingURL=upload.js.map

package/lib/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../src/lib/upload.ts"],"names":[],"mappings":"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"}

package/lib/upload.mjs

@@ -0,0 +1,156 @@
+import { Uploads, } from "../resources/uploads.mjs";
+// AWS S3 multipart upload limits.
+const MIN_PART_SIZE = 6000000; // 6 MB (spec minimum is 5 MiB; a bit over to be safe)
+const MAX_PART_SIZE = 5368709120; // 5 GiB
+const MAX_PARTS = 10000;
+const MAX_FILE_SIZE = 5497558138880; // 5 TiB
+// `validated` is intermediate — the server has validated the upload but
+// hasn't created the asset/model yet, so `entityId` isn't populated.
+// Real terminals are `imported` (asset/model created), `complete`, and
+// `failed`. Everything else means "keep polling".
+const TERMINAL_STATUSES = new Set(['complete', 'failed', 'imported']);
+/**
+ * Enhanced Uploads resource.
+ * All original methods (`create`, `retrieve`, `triggerAction`) are inherited.
+ * Adds `uploadFile()` — a one-call wrapper around the 4-step upload flow:
+ * init → PUT parts to S3 → trigger complete → poll until imported.
+ */
+export class EnhancedUploads extends Uploads {
+    /**
+     * Upload a file end-to-end. Computes an optimal part size (within AWS's
+     * 5 MiB / 5 GiB / 10,000-part bounds), uploads all parts in parallel,
+     * triggers completion, polls until the server has validated and imported
+     * the file, and returns the resolved entity.
+     *
+     * The returned type narrows on `kind`: `'model'` returns a Model,
+     * everything else returns an Asset.
+     *
+     * @example
+     * ```ts
+     * // From a file path (Node)
+     * const { asset } = await client.uploads.uploadFile({
+     *   file: './photo.jpg',
+     *   fileName: 'photo.jpg',
+     *   contentType: 'image/jpeg',
+     *   kind: 'image',
+     * });
+     * console.log(asset.id, asset.url);
+     *
+     * // Or from bytes / Blob — anything you already have in memory
+     * await client.uploads.uploadFile({
+     *   file: new Blob([pngBytes], { type: 'image/png' }),
+     *   fileName: 'generated.png',
+     *   contentType: 'image/png',
+     *   kind: 'image',
+     * });
+     * ```
+     */
+    async uploadFile(params, options) {
+        const bytes = await normalizeToBytes(params.file);
+        const fileSize = bytes.byteLength;
+        if (fileSize === 0) {
+            throw new Error('Cannot upload an empty file');
+        }
+        if (fileSize > MAX_FILE_SIZE) {
+            throw new Error(`File size (${fileSize} bytes) exceeds the maximum allowed size of ${MAX_FILE_SIZE} bytes (5 TiB)`);
+        }
+        // Pick the smallest legal part size that fits within MAX_PARTS.
+        const requiredPartSize = Math.ceil(fileSize / MAX_PARTS);
+        const partSize = Math.max(MIN_PART_SIZE, requiredPartSize);
+        if (partSize > MAX_PART_SIZE) {
+            throw new Error(`File size (${fileSize} bytes) requires a part size of ${partSize} bytes, ` +
+                `which exceeds the maximum part size of ${MAX_PART_SIZE} bytes (5 GiB)`);
+        }
+        const partsCount = Math.max(1, Math.ceil(fileSize / partSize));
+        // Step 1 — init upload session and receive presigned S3 URLs.
+        const createBody = {
+            fileName: params.fileName,
+            fileSize,
+            contentType: params.contentType,
+            kind: params.kind,
+            parts: partsCount,
+            ...(params.kind !== 'model' && params.assetOptions ? { assetOptions: params.assetOptions } : {}),
+        };
+        const createRes = await this.create(createBody, options);
+        const session = createRes.upload;
+        const uploadId = session.id;
+        const parts = session.parts;
+        if (parts?.length !== partsCount) {
+            throw new Error(`Expected ${partsCount} presigned part URL(s), got ${parts?.length ?? 0}`);
+        }
+        // Step 2 — PUT each chunk to its presigned S3 URL, with a concurrency cap.
+        const concurrency = Math.max(1, params.partConcurrency ?? 4);
+        await uploadPartsWithConcurrency(bytes, parts, partSize, concurrency);
+        // Step 3 — tell the server all parts are uploaded.
+        await this.triggerAction(uploadId, { action: 'complete' }, options);
+        // Step 4 — poll until the upload has been processed into an entity.
+        const final = await pollUntilImported(() => this.retrieve(uploadId, options), params.pollIntervalMs ?? 2000, params.pollTimeoutMs ?? 300000);
+        if (final.upload.status === 'failed') {
+            throw new Error(`Upload ${uploadId} failed: ${final.upload.errorMessage ?? '<no error message>'}`);
+        }
+        const entityId = final.upload.entityId;
+        if (!entityId) {
+            throw new Error(`Upload ${uploadId} reached status "${final.upload.status}" but has no entityId`);
+        }
+        // Fetch and return the resolved entity (narrowed by kind).
+        if (params.kind === 'model') {
+            const model = await this._client.models.retrieve(entityId);
+            return model;
+        }
+        const asset = await this._client.assets.retrieve(entityId);
+        return asset;
+    }
+}
+// ─────────────────────── helpers ───────────────────────
+async function normalizeToBytes(input) {
+    if (typeof input === 'string') {
+        // Dynamic import so browser bundlers don't pull in node:fs.
+        const { readFile } = await import('node:fs/promises');
+        return new Uint8Array(await readFile(input));
+    }
+    if (input instanceof Uint8Array) {
+        return input;
+    }
+    if (typeof Blob !== 'undefined' && input instanceof Blob) {
+        return new Uint8Array(await input.arrayBuffer());
+    }
+    throw new Error('uploadFile: unsupported input type — expected a path string, Uint8Array, or Blob');
+}
+async function uploadPartsWithConcurrency(bytes, parts, partSize, concurrency) {
+    // Sort by part number so slicing lines up with the presigned URL order.
+    const sorted = [...parts].sort((a, b) => a.number - b.number);
+    let nextIndex = 0;
+    const workers = Array.from({ length: concurrency }, () => worker());
+    await Promise.all(workers);
+    async function worker() {
+        while (true) {
+            const i = nextIndex++;
+            if (i >= sorted.length)
+                return;
+            const part = sorted[i];
+            if (!part)
+                continue;
+            const start = i * partSize;
+            const end = Math.min(bytes.byteLength, start + partSize);
+            const chunk = bytes.subarray(start, end);
+            const res = await fetch(part.url, { method: 'PUT', body: chunk });
+            if (!res.ok) {
+                throw new Error(`Failed to upload part ${part.number}/${sorted.length}: ${res.status} ${res.statusText}`);
+            }
+        }
+    }
+}
+async function pollUntilImported(retrieve, intervalMs, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const res = await retrieve();
+        const { status } = res.upload;
+        // Return as soon as we have an entityId OR the upload reached a terminal state.
+        if (res.upload.entityId || TERMINAL_STATUSES.has(status)) {
+            return res;
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    throw new Error(`Upload did not reach a terminal status within ${timeoutMs / 1000}s`);
+}
+//# sourceMappingURL=upload.mjs.map

package/lib/upload.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.mjs","sourceRoot":"","sources":["../src/lib/upload.ts"],"names":[],"mappings":"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"}

package/lib/workflow.d.mts

@@ -2,27 +2,43 @@ import type { APIPromise } from "../core/api-promise.mjs";
 import type { RequestOptions } from "../internal/request-options.mjs";
 import { Workflows, type WorkflowApproveUserParams, type WorkflowApproveUserResponse, type WorkflowRetrieveResponse, type WorkflowRunParams, type WorkflowRunResponse } from "../resources/workflows.mjs";
 import { type WithJob } from "./job.mjs";
+import type { Scenario } from "./scenario.mjs";
 type DefinitionFlow = WorkflowRetrieveResponse.Workflow.Flow;
 type NodeType = DefinitionFlow['type'];
 /**
  * Enhanced workflow object with helper methods.
- * Has all original workflow fields plus `findNode()`, `getNodesByType()`.
+ * Has all original workflow fields plus `findNode()`, `getNodesByType()`,
+ * `validate()`, and `run()`.
  *
  * @example
  * ```ts
  * const response = await client.workflows.retrieve(workflowId);
  * response.workflow.findNode('final_image');
  * response.workflow.getNodesByType('custom-model');
+ * const gen = await response.workflow.run({ body: { prompt: '...' } });
  * response.workflow.name; // original fields still work
  * ```
  */
 export declare class WorkflowEntity {
+    /** @internal */ readonly _client: Scenario;
     /** Find a node in the workflow definition by ID. */
     findNode(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow, nodeId: string): DefinitionFlow | undefined;
     /** Get all nodes of a specific type from the workflow definition. */
     getNodesByType(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow, type: NodeType): DefinitionFlow[];
+    /**
+     * Validate the structural integrity of a workflow flow.
+     * Throws an `Error` with a human-readable message on the first violation found.
+     */
+    validate(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow): void;
+    /**
+     * Run this workflow. Shortcut for
+     * `client.workflows.run(this.id, params)`.
+     *
+     * Returns an enhanced response where `response.job` has `.wait()`.
+     */
+    run(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow, params: WorkflowRunParams, options?: RequestOptions): APIPromise<WithJob<WorkflowRunResponse>>;
     /** @internal Create a WorkflowEntity from raw workflow data. */
-    static from(data: WorkflowRetrieveResponse.Workflow): WorkflowRetrieveResponse.Workflow & WorkflowEntity;
+    static from(client: Scenario, data: WorkflowRetrieveResponse.Workflow): WorkflowRetrieveResponse.Workflow & WorkflowEntity;
 }
 /** Enhanced retrieve response with workflow entity methods. */
 export type EnhancedWorkflowRetrieveResponse = Omit<WorkflowRetrieveResponse, 'workflow'> & {
@@ -36,7 +52,7 @@ export type EnhancedWorkflowRetrieveResponse = Omit<WorkflowRetrieveResponse, 'w
 export declare class EnhancedWorkflows extends Workflows {
     /**
      * Get workflow by ID. Returns an enhanced response where `workflow` has
-     * `findNode()` and `getNodesByType()`.
+     * `findNode()`, `getNodesByType()`, and `validate()`.
      */
     retrieve(workflowID: string, options?: RequestOptions): APIPromise<EnhancedWorkflowRetrieveResponse>;
     /** Run a workflow. Returns an enhanced response where `job` has `.wait()`. */

package/lib/workflow.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.d.mts","sourceRoot":"","sources":["../src/lib/workflow.ts"],"names":[],"mappings":"OAAO,KAAK,EAAE,UAAU,EAAE;OACnB,KAAK,EAAE,cAAc,EAAE;OACvB,EACL,SAAS,EACT,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB;OACM,EAAE,KAAK,OAAO,EAAc;AAEnC,KAAK,cAAc,GAAG,wBAAwB,CAAC,QAAQ,CAAC,IAAI,CAAC;AAC7D,KAAK,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACzB,oDAAoD;IACpD,QAAQ,CACN,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EACxD,MAAM,EAAE,MAAM,GACb,cAAc,GAAG,SAAS;IAI7B,qEAAqE;IACrE,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,GAAG,cAAc,EAAE;IAI1G,gEAAgE;IAChE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,wBAAwB,CAAC,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,GAAG,cAAc;CAGzG;AAED,+DAA+D;AAC/D,MAAM,MAAM,gCAAgC,GAAG,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,GAAG;IAC1F,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,GAAG,cAAc,CAAC;CAC9D,CAAC;AAEF;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C;;;OAGG;IACM,QAAQ,CACf,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,gCAAgC,CAAC;IAO/C,8EAA8E;IACrE,GAAG,CACV,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAI3C,4FAA4F;IACnF,WAAW,CAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,yBAAyB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC;CAGpD"}
+{"version":3,"file":"workflow.d.mts","sourceRoot":"","sources":["../src/lib/workflow.ts"],"names":[],"mappings":"OAAO,KAAK,EAAE,UAAU,EAAE;OACnB,KAAK,EAAE,cAAc,EAAE;OACvB,EACL,SAAS,EACT,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB;OACM,EAAE,KAAK,OAAO,EAAc;OAG5B,KAAK,EAAE,QAAQ,EAAE;AAExB,KAAK,cAAc,GAAG,wBAAwB,CAAC,QAAQ,CAAC,IAAI,CAAC;AAC7D,KAAK,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB,gBAAgB,CAAC,SAAiB,OAAO,EAAE,QAAQ,CAAC;IAEpD,oDAAoD;IACpD,QAAQ,CACN,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EACxD,MAAM,EAAE,MAAM,GACb,cAAc,GAAG,SAAS;IAI7B,qEAAqE;IACrE,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,GAAG,cAAc,EAAE;IAI1G;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,GAAG,IAAI;IAIxE;;;;;OAKG;IACH,GAAG,CACD,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EACxD,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAI3C,gEAAgE;IAChE,MAAM,CAAC,IAAI,CACT,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,wBAAwB,CAAC,QAAQ,GACtC,wBAAwB,CAAC,QAAQ,GAAG,cAAc;CAKtD;AAED,+DAA+D;AAC/D,MAAM,MAAM,gCAAgC,GAAG,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,GAAG;IAC1F,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,GAAG,cAAc,CAAC;CAC9D,CAAC;AAEF;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C;;;OAGG;IACM,QAAQ,CACf,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,gCAAgC,CAAC;IAO/C,8EAA8E;IACrE,GAAG,CACV,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAI3C,4FAA4F;IACnF,WAAW,CAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,yBAAyB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC;CAGpD"}

package/lib/workflow.d.ts

@@ -2,27 +2,43 @@ import type { APIPromise } from "../core/api-promise.js";
 import type { RequestOptions } from "../internal/request-options.js";
 import { Workflows, type WorkflowApproveUserParams, type WorkflowApproveUserResponse, type WorkflowRetrieveResponse, type WorkflowRunParams, type WorkflowRunResponse } from "../resources/workflows.js";
 import { type WithJob } from "./job.js";
+import type { Scenario } from "./scenario.js";
 type DefinitionFlow = WorkflowRetrieveResponse.Workflow.Flow;
 type NodeType = DefinitionFlow['type'];
 /**
  * Enhanced workflow object with helper methods.
- * Has all original workflow fields plus `findNode()`, `getNodesByType()`.
+ * Has all original workflow fields plus `findNode()`, `getNodesByType()`,
+ * `validate()`, and `run()`.
  *
  * @example
  * ```ts
  * const response = await client.workflows.retrieve(workflowId);
  * response.workflow.findNode('final_image');
  * response.workflow.getNodesByType('custom-model');
+ * const gen = await response.workflow.run({ body: { prompt: '...' } });
  * response.workflow.name; // original fields still work
  * ```
  */
 export declare class WorkflowEntity {
+    /** @internal */ readonly _client: Scenario;
     /** Find a node in the workflow definition by ID. */
     findNode(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow, nodeId: string): DefinitionFlow | undefined;
     /** Get all nodes of a specific type from the workflow definition. */
     getNodesByType(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow, type: NodeType): DefinitionFlow[];
+    /**
+     * Validate the structural integrity of a workflow flow.
+     * Throws an `Error` with a human-readable message on the first violation found.
+     */
+    validate(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow): void;
+    /**
+     * Run this workflow. Shortcut for
+     * `client.workflows.run(this.id, params)`.
+     *
+     * Returns an enhanced response where `response.job` has `.wait()`.
+     */
+    run(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow, params: WorkflowRunParams, options?: RequestOptions): APIPromise<WithJob<WorkflowRunResponse>>;
     /** @internal Create a WorkflowEntity from raw workflow data. */
-    static from(data: WorkflowRetrieveResponse.Workflow): WorkflowRetrieveResponse.Workflow & WorkflowEntity;
+    static from(client: Scenario, data: WorkflowRetrieveResponse.Workflow): WorkflowRetrieveResponse.Workflow & WorkflowEntity;
 }
 /** Enhanced retrieve response with workflow entity methods. */
 export type EnhancedWorkflowRetrieveResponse = Omit<WorkflowRetrieveResponse, 'workflow'> & {
@@ -36,7 +52,7 @@ export type EnhancedWorkflowRetrieveResponse = Omit<WorkflowRetrieveResponse, 'w
 export declare class EnhancedWorkflows extends Workflows {
     /**
      * Get workflow by ID. Returns an enhanced response where `workflow` has
-     * `findNode()` and `getNodesByType()`.
+     * `findNode()`, `getNodesByType()`, and `validate()`.
      */
     retrieve(workflowID: string, options?: RequestOptions): APIPromise<EnhancedWorkflowRetrieveResponse>;
     /** Run a workflow. Returns an enhanced response where `job` has `.wait()`. */

package/lib/workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/lib/workflow.ts"],"names":[],"mappings":"OAAO,KAAK,EAAE,UAAU,EAAE;OACnB,KAAK,EAAE,cAAc,EAAE;OACvB,EACL,SAAS,EACT,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB;OACM,EAAE,KAAK,OAAO,EAAc;AAEnC,KAAK,cAAc,GAAG,wBAAwB,CAAC,QAAQ,CAAC,IAAI,CAAC;AAC7D,KAAK,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACzB,oDAAoD;IACpD,QAAQ,CACN,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EACxD,MAAM,EAAE,MAAM,GACb,cAAc,GAAG,SAAS;IAI7B,qEAAqE;IACrE,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,GAAG,cAAc,EAAE;IAI1G,gEAAgE;IAChE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,wBAAwB,CAAC,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,GAAG,cAAc;CAGzG;AAED,+DAA+D;AAC/D,MAAM,MAAM,gCAAgC,GAAG,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,GAAG;IAC1F,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,GAAG,cAAc,CAAC;CAC9D,CAAC;AAEF;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C;;;OAGG;IACM,QAAQ,CACf,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,gCAAgC,CAAC;IAO/C,8EAA8E;IACrE,GAAG,CACV,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAI3C,4FAA4F;IACnF,WAAW,CAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,yBAAyB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC;CAGpD"}
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/lib/workflow.ts"],"names":[],"mappings":"OAAO,KAAK,EAAE,UAAU,EAAE;OACnB,KAAK,EAAE,cAAc,EAAE;OACvB,EACL,SAAS,EACT,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB;OACM,EAAE,KAAK,OAAO,EAAc;OAG5B,KAAK,EAAE,QAAQ,EAAE;AAExB,KAAK,cAAc,GAAG,wBAAwB,CAAC,QAAQ,CAAC,IAAI,CAAC;AAC7D,KAAK,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB,gBAAgB,CAAC,SAAiB,OAAO,EAAE,QAAQ,CAAC;IAEpD,oDAAoD;IACpD,QAAQ,CACN,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EACxD,MAAM,EAAE,MAAM,GACb,cAAc,GAAG,SAAS;IAI7B,qEAAqE;IACrE,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,GAAG,cAAc,EAAE;IAI1G;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,GAAG,IAAI;IAIxE;;;;;OAKG;IACH,GAAG,CACD,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAAC,QAAQ,EACxD,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAI3C,gEAAgE;IAChE,MAAM,CAAC,IAAI,CACT,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,wBAAwB,CAAC,QAAQ,GACtC,wBAAwB,CAAC,QAAQ,GAAG,cAAc;CAKtD;AAED,+DAA+D;AAC/D,MAAM,MAAM,gCAAgC,GAAG,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,GAAG;IAC1F,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,GAAG,cAAc,CAAC;CAC9D,CAAC;AAEF;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC9C;;;OAGG;IACM,QAAQ,CACf,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,gCAAgC,CAAC;IAO/C,8EAA8E;IACrE,GAAG,CACV,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAI3C,4FAA4F;IACnF,WAAW,CAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,yBAAyB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAAC,OAAO,CAAC,2BAA2B,CAAC,CAAC;CAGpD"}

package/lib/workflow.js

@@ -3,15 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnhancedWorkflows = exports.WorkflowEntity = void 0;
 const workflows_1 = require("../resources/workflows.js");
 const job_1 = require("./job.js");
+const workflow_validator_1 = require("./workflow_validator.js");
 /**
  * Enhanced workflow object with helper methods.
- * Has all original workflow fields plus `findNode()`, `getNodesByType()`.
+ * Has all original workflow fields plus `findNode()`, `getNodesByType()`,
+ * `validate()`, and `run()`.
  *
  * @example
  * ```ts
  * const response = await client.workflows.retrieve(workflowId);
  * response.workflow.findNode('final_image');
  * response.workflow.getNodesByType('custom-model');
+ * const gen = await response.workflow.run({ body: { prompt: '...' } });
  * response.workflow.name; // original fields still work
  * ```
  */
@@ -24,9 +27,27 @@ class WorkflowEntity {
     getNodesByType(type) {
         return this.flow.filter((node) => node.type === type);
     }
+    /**
+     * Validate the structural integrity of a workflow flow.
+     * Throws an `Error` with a human-readable message on the first violation found.
+     */
+    validate() {
+        (0, workflow_validator_1.validateWorkflowFlow)(this.flow);
+    }
+    /**
+     * Run this workflow. Shortcut for
+     * `client.workflows.run(this.id, params)`.
+     *
+     * Returns an enhanced response where `response.job` has `.wait()`.
+     */
+    run(params, options) {
+        return this._client.workflows.run(this.id, params, options);
+    }
     /** @internal Create a WorkflowEntity from raw workflow data. */
-    static from(data) {
-        return Object.assign(Object.create(WorkflowEntity.prototype), data);
+    static from(client, data) {
+        const entity = Object.assign(Object.create(WorkflowEntity.prototype), data);
+        Object.defineProperty(entity, '_client', { value: client, enumerable: false });
+        return entity;
     }
 }
 exports.WorkflowEntity = WorkflowEntity;
@@ -38,12 +59,12 @@ exports.WorkflowEntity = WorkflowEntity;
 class EnhancedWorkflows extends workflows_1.Workflows {
     /**
      * Get workflow by ID. Returns an enhanced response where `workflow` has
-     * `findNode()` and `getNodesByType()`.
+     * `findNode()`, `getNodesByType()`, and `validate()`.
      */
     retrieve(workflowID, options) {
         return super.retrieve(workflowID, options)._thenUnwrap((data) => ({
             ...data,
-            workflow: WorkflowEntity.from(data.workflow),
+            workflow: WorkflowEntity.from(this._client, data.workflow),
         }));
     }
     /** Run a workflow. Returns an enhanced response where `job` has `.wait()`. */

package/lib/workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../src/lib/workflow.ts"],"names":[],"mappings":";;;AAEA,yDAOgC;AAChC,kCAAiD;AAKjD;;;;;;;;;;;GAWG;AACH,MAAa,cAAc;IACzB,oDAAoD;IACpD,QAAQ,CAEN,MAAc;QAEd,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;IACtD,CAAC;IAED,qEAAqE;IACrE,cAAc,CAA2D,IAAc;QACrF,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACxD,CAAC;IAED,gEAAgE;IAChE,MAAM,CAAC,IAAI,CAAC,IAAuC;QACjD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;CACF;AAlBD,wCAkBC;AAOD;;;;GAIG;AACH,MAAa,iBAAkB,SAAQ,qBAAS;IAC9C;;;OAGG;IACM,QAAQ,CACf,UAAkB,EAClB,OAAwB;QAExB,OAAO,KAAK,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAChE,GAAG,IAAI;YACP,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC7C,CAAC,CAAC,CAAC;IACN,CAAC;IAED,8EAA8E;IACrE,GAAG,CACV,UAAkB,EAClB,MAAyB,EACzB,OAAwB;QAExB,OAAO,IAAA,gBAAU,EAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,4FAA4F;IACnF,WAAW,CAClB,UAAkB,EAClB,IAA+B,EAC/B,OAAwB;QAExB,OAAO,IAAA,gBAAU,EAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,CAAC;CACF;AAhCD,8CAgCC"}
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../src/lib/workflow.ts"],"names":[],"mappings":";;;AAEA,yDAOgC;AAChC,kCAAiD;AACjD,gEAA4D;AAO5D;;;;;;;;;;;;;GAaG;AACH,MAAa,cAAc;IAGzB,oDAAoD;IACpD,QAAQ,CAEN,MAAc;QAEd,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;IACtD,CAAC;IAED,qEAAqE;IACrE,cAAc,CAA2D,IAAc;QACrF,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACxD,CAAC;IAED;;;OAGG;IACH,QAAQ;QACN,IAAA,yCAAoB,EAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAED,MAAyB,EACzB,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED,gEAAgE;IAChE,MAAM,CAAC,IAAI,CACT,MAAgB,EAChB,IAAuC;QAEvC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;QAC5E,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/E,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AA/CD,wCA+CC;AAOD;;;;GAIG;AACH,MAAa,iBAAkB,SAAQ,qBAAS;IAC9C;;;OAGG;IACM,QAAQ,CACf,UAAkB,EAClB,OAAwB;QAExB,OAAO,KAAK,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAChE,GAAG,IAAI;YACP,QAAQ,EAAE,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,OAAmB,EAAE,IAAI,CAAC,QAAQ,CAAC;SACvE,CAAC,CAAC,CAAC;IACN,CAAC;IAED,8EAA8E;IACrE,GAAG,CACV,UAAkB,EAClB,MAAyB,EACzB,OAAwB;QAExB,OAAO,IAAA,gBAAU,EAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,4FAA4F;IACnF,WAAW,CAClB,UAAkB,EAClB,IAA+B,EAC/B,OAAwB;QAExB,OAAO,IAAA,gBAAU,EAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,CAAC;CACF;AAhCD,8CAgCC"}

package/lib/workflow.mjs

@@ -1,14 +1,17 @@
 import { Workflows, } from "../resources/workflows.mjs";
 import { enhanceJob } from "./job.mjs";
+import { validateWorkflowFlow } from "./workflow_validator.mjs";
 /**
  * Enhanced workflow object with helper methods.
- * Has all original workflow fields plus `findNode()`, `getNodesByType()`.
+ * Has all original workflow fields plus `findNode()`, `getNodesByType()`,
+ * `validate()`, and `run()`.
  *
  * @example
  * ```ts
  * const response = await client.workflows.retrieve(workflowId);
  * response.workflow.findNode('final_image');
  * response.workflow.getNodesByType('custom-model');
+ * const gen = await response.workflow.run({ body: { prompt: '...' } });
  * response.workflow.name; // original fields still work
  * ```
  */
@@ -21,9 +24,27 @@ export class WorkflowEntity {
     getNodesByType(type) {
         return this.flow.filter((node) => node.type === type);
     }
+    /**
+     * Validate the structural integrity of a workflow flow.
+     * Throws an `Error` with a human-readable message on the first violation found.
+     */
+    validate() {
+        validateWorkflowFlow(this.flow);
+    }
+    /**
+     * Run this workflow. Shortcut for
+     * `client.workflows.run(this.id, params)`.
+     *
+     * Returns an enhanced response where `response.job` has `.wait()`.
+     */
+    run(params, options) {
+        return this._client.workflows.run(this.id, params, options);
+    }
     /** @internal Create a WorkflowEntity from raw workflow data. */
-    static from(data) {
-        return Object.assign(Object.create(WorkflowEntity.prototype), data);
+    static from(client, data) {
+        const entity = Object.assign(Object.create(WorkflowEntity.prototype), data);
+        Object.defineProperty(entity, '_client', { value: client, enumerable: false });
+        return entity;
     }
 }
 /**
@@ -34,12 +55,12 @@ export class WorkflowEntity {
 export class EnhancedWorkflows extends Workflows {
     /**
      * Get workflow by ID. Returns an enhanced response where `workflow` has
-     * `findNode()` and `getNodesByType()`.
+     * `findNode()`, `getNodesByType()`, and `validate()`.
      */
     retrieve(workflowID, options) {
         return super.retrieve(workflowID, options)._thenUnwrap((data) => ({
             ...data,
-            workflow: WorkflowEntity.from(data.workflow),
+            workflow: WorkflowEntity.from(this._client, data.workflow),
         }));
     }
     /** Run a workflow. Returns an enhanced response where `job` has `.wait()`. */