@scenario-labs/sdk 0.2.0 → 1.0.0

package/src/lib/upload.ts

@@ -0,0 +1,250 @@
+import type { RequestOptions } from '../internal/request-options';
+import {
+  Uploads,
+  type UploadCreateParams,
+  type UploadCreateResponse,
+  type UploadRetrieveResponse,
+} from '../resources/uploads';
+import type { AssetRetrieveResponse } from '../resources/assets/assets';
+import type { ModelRetrieveResponse } from '../resources/models/models';
+
+type UploadKind = NonNullable<UploadCreateParams['kind']>;
+
+/** The resolved entity returned after a successful upload, narrowed by `kind`. */
+export type UploadResult<K extends UploadKind> =
+  K extends 'model' ? ModelRetrieveResponse : AssetRetrieveResponse;
+
+/**
+ * Accepted upload inputs.
+ * - `string` — a local file path, read from disk (Node only; throws in browsers).
+ * - `Uint8Array` — raw bytes. `Buffer` is a `Uint8Array` and works too.
+ * - `Blob` / `File` — browser-native, or Node ≥ 18 via `fs.openAsBlob()` /
+ *   constructors.
+ */
+export type UploadFileInput = string | Uint8Array | Blob;
+
+export interface UploadFileParams<K extends UploadKind> {
+  /**
+   * The file to upload. Accepts a local path (Node), a `Uint8Array` / `Buffer`,
+   * or a `Blob` / `File`.
+   */
+  file: UploadFileInput;
+  /** Original filename (e.g. `"my-model.safetensors"`). */
+  fileName: string;
+  /** MIME type (e.g. `"application/octet-stream"`, `"image/png"`). */
+  contentType: string;
+  /** The kind of upload. Determines the returned entity type. */
+  kind: K;
+  /**
+   * Extra asset options. Ignored when `kind === 'model'` — models don't
+   * produce an asset, so these options are not applicable server-side.
+   */
+  assetOptions?: UploadCreateParams['assetOptions'];
+  /**
+   * Maximum number of parts uploaded to S3 in parallel.
+   * @default 4
+   */
+  partConcurrency?: number;
+  /**
+   * Polling interval for the final "upload imported" check, in ms.
+   * @default 2000
+   */
+  pollIntervalMs?: number;
+  /**
+   * Maximum time to wait for the upload to reach a terminal state, in ms.
+   * Throws if exceeded.
+   * @default 300000
+   */
+  pollTimeoutMs?: number;
+}
+
+// AWS S3 multipart upload limits.
+const MIN_PART_SIZE = 6_000_000; // 6 MB (spec minimum is 5 MiB; a bit over to be safe)
+const MAX_PART_SIZE = 5_368_709_120; // 5 GiB
+const MAX_PARTS = 10_000;
+const MAX_FILE_SIZE = 5_497_558_138_880; // 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<K extends UploadKind>(
+    params: UploadFileParams<K>,
+    options?: RequestOptions,
+  ): Promise<UploadResult<K>> {
+    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: UploadCreateParams = {
+      fileName: params.fileName,
+      fileSize,
+      contentType: params.contentType,
+      kind: params.kind,
+      parts: partsCount,
+      ...(params.kind !== 'model' && params.assetOptions ? { assetOptions: params.assetOptions } : {}),
+    };
+    const createRes: UploadCreateResponse = 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 ?? 2_000,
+      params.pollTimeoutMs ?? 300_000,
+    );
+
+    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 as UploadResult<K>;
+    }
+    const asset = await this._client.assets.retrieve(entityId);
+    return asset as UploadResult<K>;
+  }
+}
+
+// ─────────────────────── helpers ───────────────────────
+
+async function normalizeToBytes(input: UploadFileInput): Promise<Uint8Array> {
+  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: Uint8Array,
+  parts: Array<{ number: number; url: string; expires: string }>,
+  partSize: number,
+  concurrency: number,
+): Promise<void> {
+  // 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: () => Promise<UploadRetrieveResponse>,
+  intervalMs: number,
+  timeoutMs: number,
+): Promise<UploadRetrieveResponse> {
+  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`);
+}

package/src/lib/workflow.ts

@@ -9,23 +9,30 @@ import {
   type WorkflowRunResponse,
 } from '../resources/workflows';
 import { type WithJob, enhanceJob } from './job';
+import { validateWorkflowFlow } from './workflow_validator';
+// Type-only import to break the circular `scenario.ts` ↔ `workflow.ts` graph at runtime.
+import type { Scenario } from './scenario';
 
 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 class WorkflowEntity {
+  /** @internal */ declare readonly _client: Scenario;
+
   /** Find a node in the workflow definition by ID. */
   findNode(
     this: WorkflowEntity & WorkflowRetrieveResponse.Workflow,
@@ -39,9 +46,36 @@ export class WorkflowEntity {
     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(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow): void {
+    validateWorkflowFlow(this.flow);
+  }
+
+  /**
+   * 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>> {
+    return this._client.workflows.run(this.id, params, options);
+  }
+
   /** @internal Create a WorkflowEntity from raw workflow data. */
-  static from(data: WorkflowRetrieveResponse.Workflow): WorkflowRetrieveResponse.Workflow & WorkflowEntity {
-    return Object.assign(Object.create(WorkflowEntity.prototype), data);
+  static from(
+    client: Scenario,
+    data: WorkflowRetrieveResponse.Workflow,
+  ): WorkflowRetrieveResponse.Workflow & WorkflowEntity {
+    const entity = Object.assign(Object.create(WorkflowEntity.prototype), data);
+    Object.defineProperty(entity, '_client', { value: client, enumerable: false });
+    return entity;
   }
 }
 
@@ -58,7 +92,7 @@ export type EnhancedWorkflowRetrieveResponse = Omit<WorkflowRetrieveResponse, 'w
 export class EnhancedWorkflows extends Workflows {
   /**
    * Get workflow by ID. Returns an enhanced response where `workflow` has
-   * `findNode()` and `getNodesByType()`.
+   * `findNode()`, `getNodesByType()`, and `validate()`.
    */
   override retrieve(
     workflowID: string,
@@ -66,7 +100,7 @@ export class EnhancedWorkflows extends Workflows {
   ): APIPromise<EnhancedWorkflowRetrieveResponse> {
     return super.retrieve(workflowID, options)._thenUnwrap((data) => ({
       ...data,
-      workflow: WorkflowEntity.from(data.workflow),
+      workflow: WorkflowEntity.from(this._client as Scenario, data.workflow),
     }));
   }
 

package/src/lib/workflow_import_validator.ts

@@ -0,0 +1,104 @@
+export class WorkflowImportError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkflowImportError';
+  }
+}
+
+export type WorkflowEditorNodeType =
+  | 'text'
+  | 'asset'
+  | 'model'
+  | 'llm'
+  | 'transformText'
+  | 'splitText'
+  | 'ifElse'
+  | 'groupItems'
+  | 'sliceAssets'
+  | 'forEach'
+  | 'forEachEnd'
+  | 'stickyNote';
+
+export const VALID_EDITOR_NODE_TYPES: readonly WorkflowEditorNodeType[] = [
+  'text',
+  'asset',
+  'model',
+  'llm',
+  'transformText',
+  'splitText',
+  'ifElse',
+  'groupItems',
+  'sliceAssets',
+  'forEach',
+  'forEachEnd',
+  'stickyNote',
+];
+
+export interface WorkflowExportData {
+  version: '1.0';
+  name: string;
+  description: string;
+  editorInfo: {
+    nodes: Array<{ type: WorkflowEditorNodeType; [key: string]: unknown }>;
+    edges: Array<{ [key: string]: unknown }>;
+    inputKeys: string[];
+  };
+  inputs: unknown[];
+  tagSet: string[];
+  uiConfig?: object;
+  exportedAt: string;
+  exportedBy: string;
+}
+
+/**
+ * Validates a workflow export payload (e.g. from a JSON file import).
+ *
+ * Throws a `WorkflowImportError` with a human-readable message on the first
+ * violation found. Returns the validated data cast to `WorkflowExportData`.
+ *
+ * Checks performed:
+ *  1. Data is a non-null object
+ *  2. `version` field is present and equals "1.0"
+ *  3. `editorInfo` has non-empty `nodes` and `edges` arrays
+ *  4. Each node's `type` is a recognized editor node type
+ *  5. `inputs` is an array
+ */
+export function validateEditorInfo(data: unknown): WorkflowExportData {
+  if (typeof data !== 'object' || data === null) {
+    throw new WorkflowImportError('Invalid JSON format');
+  }
+
+  const workflow = data as Partial<WorkflowExportData>;
+
+  if (!workflow.version) {
+    throw new WorkflowImportError('Missing version field');
+  }
+
+  if (workflow.version !== '1.0') {
+    throw new WorkflowImportError(`Unsupported version: ${workflow.version}`);
+  }
+
+  if (!workflow.editorInfo || !workflow.editorInfo.nodes || !workflow.editorInfo.edges) {
+    throw new WorkflowImportError('Missing editorInfo structure');
+  }
+
+  if (!Array.isArray(workflow.editorInfo.nodes)) {
+    throw new WorkflowImportError('Invalid nodes array');
+  }
+
+  if (!Array.isArray(workflow.editorInfo.edges)) {
+    throw new WorkflowImportError('Invalid edges array');
+  }
+
+  if (!workflow.inputs || !Array.isArray(workflow.inputs)) {
+    throw new WorkflowImportError('Invalid inputs array');
+  }
+
+  for (const node of workflow.editorInfo.nodes) {
+    if (!(VALID_EDITOR_NODE_TYPES as readonly string[]).includes(node.type)) {
+      throw new WorkflowImportError(`Invalid node type: ${node.type}`);
+    }
+  }
+
+  return workflow as WorkflowExportData;
+}

package/src/lib/workflow_validator.ts

@@ -0,0 +1,167 @@
+const VALID_NODE_TYPES = new Set([
+  'custom-model',
+  'for-each',
+  'generate-prompt',
+  'list',
+  'logic',
+  'model',
+  'remove-background',
+  'transform',
+  'user-approval',
+  'workflow',
+]);
+
+type RawRef = {
+  node?: unknown;
+  conditional?: unknown;
+};
+
+type RawInput = {
+  name?: unknown;
+  ref?: RawRef;
+  items?: unknown[][];
+};
+
+type RawNode = {
+  id?: unknown;
+  type?: unknown;
+  modelId?: unknown;
+  workflowId?: unknown;
+  logicType?: unknown;
+  loopBodyNodeIds?: unknown;
+  count?: unknown;
+  dependsOn?: unknown;
+  inputs?: unknown;
+};
+
+/**
+ * Validates the structural integrity of a workflow flow (array of nodes).
+ *
+ * Throws an `Error` with a human-readable message on the first violation found.
+ *
+ * Checks performed:
+ *  1. Every node has a non-empty string `id`
+ *  2. Node IDs are unique within the flow
+ *  3. Every node `type` is a recognized workflow node type
+ *  4. Per-type required fields:
+ *       - custom-model → modelId
+ *       - workflow     → workflowId
+ *       - logic        → logicType
+ *       - for-each     → loopBodyNodeIds (non-empty) OR count (>0)
+ *  5. Cross-references all point to node IDs that exist in the flow:
+ *       - dependsOn entries
+ *       - input ref.node (excluding "workflow" which is a reserved keyword)
+ *       - input ref.conditional entries
+ *       - loopBodyNodeIds entries
+ */
+export function validateWorkflowFlow(flow: unknown[]): void {
+  const nodeIds = new Set<string>();
+  const firstSeenAt = new Map<string, number>();
+
+  // Pass 1 — per-node checks (ID, type, required fields)
+  for (let i = 0; i < flow.length; i++) {
+    const node = flow[i] as RawNode;
+
+    if (typeof node.id !== 'string' || !node.id) {
+      throw new Error(`Node at index ${i} is missing an "id" field`);
+    }
+    if (nodeIds.has(node.id)) {
+      throw new Error(
+        `Duplicate node id "${node.id}" at index ${i} (first seen at index ${firstSeenAt.get(node.id)})`,
+      );
+    }
+    nodeIds.add(node.id);
+    firstSeenAt.set(node.id, i);
+
+    const label = `"${node.id}"`;
+
+    if (typeof node.type !== 'string' || !VALID_NODE_TYPES.has(node.type)) {
+      throw new Error(
+        `Node ${label} has invalid type "${node.type}". Valid types are: ${[...VALID_NODE_TYPES].join(', ')}`,
+      );
+    }
+
+    const type = node.type;
+
+    if (type === 'custom-model' && !node.modelId) {
+      throw new Error(`Node ${label} (custom-model) is missing required field "modelId"`);
+    }
+    if (type === 'workflow' && !node.workflowId) {
+      throw new Error(`Node ${label} (workflow) is missing required field "workflowId"`);
+    }
+    if (type === 'logic' && !node.logicType) {
+      throw new Error(`Node ${label} (logic) is missing required field "logicType"`);
+    }
+    if (type === 'for-each') {
+      const hasLoopBody = Array.isArray(node.loopBodyNodeIds) && node.loopBodyNodeIds.length > 0;
+      const hasCount = typeof node.count === 'number' && node.count > 0;
+      if (!hasLoopBody && !hasCount) {
+        throw new Error(
+          `Node ${label} (for-each) requires either "loopBodyNodeIds" (non-empty array) or "count" (positive number)`,
+        );
+      }
+    }
+  }
+
+  // Pass 2 — cross-reference checks (all node IDs are now collected)
+  for (const rawNode of flow) {
+    const node = rawNode as RawNode;
+    const nodeId = node.id as string;
+
+    if (Array.isArray(node.dependsOn)) {
+      for (const depId of node.dependsOn) {
+        if (typeof depId === 'string' && !nodeIds.has(depId)) {
+          throw new Error(`Node "${nodeId}" dependsOn unknown node "${depId}"`);
+        }
+      }
+    }
+
+    if (Array.isArray(node.inputs)) {
+      for (const input of node.inputs) {
+        validateInputRefs(nodeId, input as RawInput, nodeIds);
+      }
+    }
+
+    if (Array.isArray(node.loopBodyNodeIds)) {
+      for (const bodyId of node.loopBodyNodeIds as unknown[]) {
+        if (typeof bodyId === 'string' && !nodeIds.has(bodyId)) {
+          throw new Error(`Node "${nodeId}" loopBodyNodeIds references unknown node "${bodyId}"`);
+        }
+      }
+    }
+  }
+}
+
+function validateInputRefs(nodeId: string, input: RawInput, nodeIds: Set<string>): void {
+  const inputName = typeof input.name === 'string' && input.name ? input.name : '(unnamed)';
+
+  if (input.ref) {
+    const { node: refNode, conditional } = input.ref;
+
+    // "workflow" is a reserved keyword meaning "take from the workflow's own inputs"
+    if (typeof refNode === 'string' && refNode !== 'workflow' && !nodeIds.has(refNode)) {
+      throw new Error(`Node "${nodeId}" input "${inputName}" references unknown node "${refNode}"`);
+    }
+
+    if (Array.isArray(conditional)) {
+      for (const condId of conditional) {
+        if (typeof condId === 'string' && !nodeIds.has(condId)) {
+          throw new Error(
+            `Node "${nodeId}" input "${inputName}" has a conditional ref pointing to unknown node "${condId}"`,
+          );
+        }
+      }
+    }
+  }
+
+  // Recurse into INPUTS_ARRAY sub-inputs
+  if (Array.isArray(input.items)) {
+    for (const item of input.items) {
+      if (Array.isArray(item)) {
+        for (const subInput of item) {
+          validateInputRefs(nodeId, subInput as RawInput, nodeIds);
+        }
+      }
+    }
+  }
+}

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';