@scenario-labs/sdk 0.3.0 → 1.1.0

package/src/lib/models.ts

@@ -1,8 +1,55 @@
 import type { APIPromise } from '../core/api-promise';
 import type { RequestOptions } from '../internal/request-options';
-import { Models } from '../resources/models/models';
+import type { GenerateRunModelParams, GenerateRunModelResponse } from '../resources/generate';
+import { Models, type ModelRetrieveParams, type ModelRetrieveResponse } from '../resources/models/models';
 import { Train, type TrainTriggerParams, type TrainTriggerResponse } from '../resources/models/train';
 import { type WithJob, enhanceJob } from './job';
+// Type-only import to break the circular `scenario.ts` ↔ `models.ts` graph at runtime.
+import type { Scenario } from './scenario';
+
+/**
+ * Enhanced Model entity with helper methods.
+ * Has all original model fields plus `.run()`.
+ *
+ * @example
+ * ```ts
+ * const { model } = await client.models.retrieve(modelId);
+ * const gen = await model.run({ body: { prompt: 'a red car' } });
+ * const completed = await gen.job.wait();
+ * ```
+ */
+export class ModelEntity {
+  /** @internal */ declare readonly _client: Scenario;
+
+  /**
+   * Generate with this model. Shortcut for
+   * `client.generate.runModel(this.id, params)`.
+   *
+   * Returns an enhanced response where `response.job` has `.wait()`.
+   */
+  run(
+    this: ModelEntity & ModelRetrieveResponse.Model,
+    params: GenerateRunModelParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<GenerateRunModelResponse>> {
+    return this._client.generate.runModel(this.id, params, options);
+  }
+
+  /** @internal Create a ModelEntity wrapping raw model data. */
+  static from(
+    client: Scenario,
+    data: ModelRetrieveResponse.Model,
+  ): ModelRetrieveResponse.Model & ModelEntity {
+    const entity = Object.assign(Object.create(ModelEntity.prototype), data);
+    Object.defineProperty(entity, '_client', { value: client, enumerable: false });
+    return entity;
+  }
+}
+
+/** Enhanced retrieve response where `model` has `.run()` on top of its original fields. */
+export type EnhancedModelRetrieveResponse = Omit<ModelRetrieveResponse, 'model'> & {
+  model: ModelRetrieveResponse.Model & ModelEntity;
+};
 
 /**
  * Enhanced Train resource.
@@ -20,8 +67,21 @@ export class EnhancedTrain extends Train {
 
 /**
  * Enhanced Models resource.
- * All original methods inherited. `train` is an {@link EnhancedTrain}.
+ * All original methods inherited.
+ * - `train` is an {@link EnhancedTrain}
+ * - `retrieve()` returns a response where `model` has `.run()`
  */
 export class EnhancedModels extends Models {
   override train: EnhancedTrain = new EnhancedTrain(this._client);
+
+  override retrieve(
+    modelID: string,
+    query: ModelRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EnhancedModelRetrieveResponse> {
+    return super.retrieve(modelID, query, options)._thenUnwrap((data) => ({
+      ...data,
+      model: ModelEntity.from(this._client as Scenario, data.model),
+    }));
+  }
 }

package/src/lib/scenario.ts

@@ -1,6 +1,9 @@
 import { Scenario as BaseScenario } from '../client';
+import { EnhancedAssets } from './asset';
 import { EnhancedGenerate } from './generate';
+import { EnhancedJobs } from './job';
 import { EnhancedModels } from './models';
+import { EnhancedUploads } from './upload';
 import { EnhancedWorkflows } from './workflow';
 
 /**
@@ -30,10 +33,21 @@ import { EnhancedWorkflows } from './workflow';
  * // Enhanced: generate job.wait()
  * const gen = await client.generate.runModel(modelId, { body });
  * const done = await gen.job.wait();
+ *
+ * // Enhanced: upload.wait()
+ * const res = await client.uploads.retrieve(uploadId);
+ * const imported = await res.upload.wait();
+ *
+ * // Enhanced: asset.download()
+ * const a = await client.assets.retrieve(assetId);
+ * const bytes = await a.asset.download();
  * ```
  */
 export class Scenario extends BaseScenario {
   override workflows: EnhancedWorkflows = new EnhancedWorkflows(this);
   override generate: EnhancedGenerate = new EnhancedGenerate(this);
   override models: EnhancedModels = new EnhancedModels(this);
+  override uploads: EnhancedUploads = new EnhancedUploads(this);
+  override assets: EnhancedAssets = new EnhancedAssets(this);
+  override jobs: EnhancedJobs = new EnhancedJobs(this);
 }

package/src/lib/upload.ts

@@ -0,0 +1,344 @@
+import type { Scenario } from '../client';
+import type { APIPromise } from '../core/api-promise';
+import type { RequestOptions } from '../internal/request-options';
+import {
+  Uploads,
+  type UploadCreateParams,
+  type UploadCreateResponse,
+  type UploadRetrieveResponse,
+  type UploadTriggerActionParams,
+  type UploadTriggerActionResponse,
+} 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
+
+type UploadStatus = UploadRetrieveResponse.Upload['status'];
+
+// `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: Set<UploadStatus> = new Set(['complete', 'failed', 'imported']);
+
+export interface UploadWaitOptions {
+  /** Polling interval in milliseconds. Default: 2000 */
+  intervalMs?: number;
+  /** Maximum wait time in milliseconds. Default: 300000 */
+  timeoutMs?: number;
+}
+
+/** Upload methods added on top of the original upload fields. */
+export class UploadMethods {
+  /** @internal */ declare readonly _client: Scenario;
+
+  /**
+   * Poll until the upload has been processed into an entity (asset or model),
+   * or reaches a terminal state (`imported`, `complete`, `failed`). Resolves
+   * with the latest upload data so you can read `entityId`, `status`, or
+   * `errorMessage` without a follow-up retrieve.
+   *
+   * @example
+   * ```ts
+   * const res = await client.uploads.retrieve(uploadId);
+   * const done = await res.upload.wait();
+   * if (done.status === 'failed') throw new Error(done.errorMessage);
+   * console.log(done.entityId);
+   * ```
+   */
+  async wait(this: Upload, options?: UploadWaitOptions): Promise<Upload> {
+    const final = await pollUntilImported(
+      () => this._client.uploads.retrieve(this.id),
+      options?.intervalMs ?? 2_000,
+      options?.timeoutMs ?? 300_000,
+    );
+    return UploadMethods.from(this._client, final.upload);
+  }
+
+  /** @internal Create an Upload from raw upload data. */
+  static from(client: Scenario, data: UploadRetrieveResponse['upload']): Upload {
+    const upload = Object.assign(Object.create(UploadMethods.prototype), data) as Upload;
+    Object.defineProperty(upload, '_client', { value: client, enumerable: false });
+    return upload;
+  }
+}
+
+/** An upload with all original fields plus `.wait()`. */
+export type Upload = UploadRetrieveResponse.Upload & UploadMethods;
+export const Upload = UploadMethods;
+
+/**
+ * @internal Helper type: adds `.wait()` to the `upload` field of a response.
+ * Uses intersection so the original response type is preserved — a `WithUpload<T>` is still assignable to `T`.
+ */
+export type WithUpload<T extends { upload: unknown }> = T & { upload: UploadMethods };
+
+/**
+ * @internal Wrap `_thenUnwrap` to replace `response.upload` with an enhanced Upload.
+ */
+export function enhanceUpload<T extends { upload: { id: string; status: string } }>(
+  client: Scenario,
+  promise: APIPromise<T>,
+): APIPromise<WithUpload<T>> {
+  return promise._thenUnwrap((data) => ({
+    ...data,
+    upload: Upload.from(client, data.upload as UploadRetrieveResponse['upload']),
+  }));
+}
+
+/**
+ * Enhanced Uploads resource.
+ * All original methods (`create`, `retrieve`, `triggerAction`) are inherited,
+ * with each response's `upload` field enriched with a `.wait()` helper.
+ * 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 {
+  override create(
+    body: UploadCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<WithUpload<UploadCreateResponse>> {
+    return enhanceUpload(this._client, super.create(body, options));
+  }
+
+  override retrieve(
+    uploadID: string,
+    options?: RequestOptions,
+  ): APIPromise<WithUpload<UploadRetrieveResponse>> {
+    return enhanceUpload(this._client, super.retrieve(uploadID, options));
+  }
+
+  override triggerAction(
+    uploadID: string,
+    body: UploadTriggerActionParams,
+    options?: RequestOptions,
+  ): APIPromise<WithUpload<UploadTriggerActionResponse>> {
+    return enhanceUpload(this._client, super.triggerAction(uploadID, body, options));
+  }
+
+  /**
+   * 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

@@ -10,23 +10,29 @@ import {
 } 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,
@@ -48,9 +54,28 @@ export class WorkflowEntity {
     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;
   }
 }
 
@@ -75,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/pagination.ts

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