@scenario-labs/sdk 0.1.3 → 0.2.0

package/src/core/error.ts

@@ -2,13 +2,13 @@
 
 import { castToError } from '../internal/errors';
 
-export class ScenarioSDKError extends Error {}
+export class ScenarioError extends Error {}
 
 export class APIError<
   TStatus extends number | undefined = number | undefined,
   THeaders extends Headers | undefined = Headers | undefined,
   TError extends Object | undefined = Object | undefined,
-> extends ScenarioSDKError {
+> extends ScenarioError {
   /** HTTP status for the response that caused the error */
   readonly status: TStatus;
   /** HTTP headers for the response that caused the error */

package/src/core/resource.ts

@@ -1,11 +1,11 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import type { ScenarioSDK } from '../client';
+import type { Scenario } from '../client';
 
 export abstract class APIResource {
-  protected _client: ScenarioSDK;
+  protected _client: Scenario;
 
-  constructor(client: ScenarioSDK) {
+  constructor(client: Scenario) {
     this._client = client;
   }
 }

package/src/index.ts

@@ -1,12 +1,13 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-export { ScenarioSDK as default } from './client';
+export { Scenario as default } from './lib/scenario';
 
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
-export { ScenarioSDK, type ClientOptions } from './client';
+export { Scenario } from './lib/scenario';
+export { type ClientOptions } from './client';
 export {
-  ScenarioSDKError,
+  ScenarioError,
   APIError,
   APIConnectionError,
   APIConnectionTimeoutError,
@@ -20,3 +21,7 @@ export {
   PermissionDeniedError,
   UnprocessableEntityError,
 } from './core/error';
+export { Job, type WaitOptions, type WithJob } from './lib/job';
+export { EnhancedWorkflows, WorkflowEntity } from './lib/workflow';
+export { EnhancedGenerate } from './lib/generate';
+export { EnhancedModels, EnhancedTrain } from './lib/models';

package/src/internal/parse.ts

@@ -1,7 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import type { FinalRequestOptions } from './request-options';
-import { type ScenarioSDK } from '../client';
+import { type Scenario } from '../client';
 import { formatRequestDetails, loggerFor } from './utils/log';
 
 export type APIResponseProps = {
@@ -13,7 +13,7 @@ export type APIResponseProps = {
   startTime: number;
 };
 
-export async function defaultParseResponse<T>(client: ScenarioSDK, props: APIResponseProps): Promise<T> {
+export async function defaultParseResponse<T>(client: Scenario, props: APIResponseProps): Promise<T> {
   const { response, requestLogID, retryOfRequestLogID, startTime } = props;
   const body = await (async () => {
     // fetch refuses to read the body when the status code is 204.

package/src/internal/request-options.ts

@@ -75,6 +75,8 @@ export type RequestOptions = {
    */
   defaultBaseURL?: string | undefined;
 
+  __security?: { scBearerAuth?: boolean; scBasicAuth?: boolean };
+
   __binaryResponse?: boolean | undefined;
 };
 

package/src/internal/shims.ts

@@ -16,7 +16,7 @@ export function getDefaultFetch(): Fetch {
   }
 
   throw new Error(
-    '`fetch` is not defined as a global; Either pass `fetch` to the client, `new ScenarioSDK({ fetch })` or polyfill the global, `globalThis.fetch = fetch`',
+    '`fetch` is not defined as a global; Either pass `fetch` to the client, `new Scenario({ fetch })` or polyfill the global, `globalThis.fetch = fetch`',
   );
 }
 

package/src/internal/uploads.ts

@@ -1,6 +1,6 @@
 import { type RequestOptions } from './request-options';
 import type { FilePropertyBag, Fetch } from './builtin-types';
-import type { ScenarioSDK } from '../client';
+import type { Scenario } from '../client';
 import { ReadableStreamFrom } from './shims';
 
 export type BlobPart = string | ArrayBuffer | ArrayBufferView | Blob | DataView;
@@ -74,7 +74,7 @@ export const isAsyncIterable = (value: any): value is AsyncIterable<any> =>
  */
 export const maybeMultipartFormRequestOptions = async (
   opts: RequestOptions,
-  fetch: ScenarioSDK | Fetch,
+  fetch: Scenario | Fetch,
 ): Promise<RequestOptions> => {
   if (!hasUploadableValue(opts.body)) return opts;
 
@@ -85,7 +85,7 @@ type MultipartFormRequestOptions = Omit<RequestOptions, 'body'> & { body: unknow
 
 export const multipartFormRequestOptions = async (
   opts: MultipartFormRequestOptions,
-  fetch: ScenarioSDK | Fetch,
+  fetch: Scenario | Fetch,
 ): Promise<RequestOptions> => {
   return { ...opts, body: await createForm(opts.body, fetch) };
 };
@@ -98,7 +98,7 @@ const supportsFormDataMap = /* @__PURE__ */ new WeakMap<Fetch, Promise<boolean>>
  * This function detects if the fetch function provided supports the global FormData object to avoid
  * confusing error messages later on.
  */
-function supportsFormData(fetchObject: ScenarioSDK | Fetch): Promise<boolean> {
+function supportsFormData(fetchObject: Scenario | Fetch): Promise<boolean> {
   const fetch: Fetch = typeof fetchObject === 'function' ? fetchObject : (fetchObject as any).fetch;
   const cached = supportsFormDataMap.get(fetch);
   if (cached) return cached;
@@ -124,7 +124,7 @@ function supportsFormData(fetchObject: ScenarioSDK | Fetch): Promise<boolean> {
 
 export const createForm = async <T = Record<string, unknown>>(
   body: T | undefined,
-  fetch: ScenarioSDK | Fetch,
+  fetch: Scenario | Fetch,
 ): Promise<FormData> => {
   if (!(await supportsFormData(fetch))) {
     throw new TypeError(

package/src/internal/utils/base64.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { ScenarioSDKError } from '../../core/error';
+import { ScenarioError } from '../../core/error';
 import { encodeUTF8 } from './bytes';
 
 export const toBase64 = (data: string | Uint8Array | null | undefined): string => {
@@ -18,7 +18,7 @@ export const toBase64 = (data: string | Uint8Array | null | undefined): string =
     return btoa(String.fromCharCode.apply(null, data as any));
   }
 
-  throw new ScenarioSDKError('Cannot generate base64 string; Expected `Buffer` or `btoa` to be defined');
+  throw new ScenarioError('Cannot generate base64 string; Expected `Buffer` or `btoa` to be defined');
 };
 
 export const fromBase64 = (str: string): Uint8Array => {
@@ -36,5 +36,5 @@ export const fromBase64 = (str: string): Uint8Array => {
     return buf;
   }
 
-  throw new ScenarioSDKError('Cannot decode base64 string; Expected `Buffer` or `atob` to be defined');
+  throw new ScenarioError('Cannot decode base64 string; Expected `Buffer` or `atob` to be defined');
 };

package/src/internal/utils/log.ts

@@ -1,7 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { hasOwn } from './values';
-import { type ScenarioSDK } from '../../client';
+import { type Scenario } from '../../client';
 import { RequestOptions } from '../request-options';
 
 type LogFn = (message: string, ...rest: unknown[]) => void;
@@ -24,7 +24,7 @@ const levelNumbers = {
 export const parseLogLevel = (
   maybeLevel: string | undefined,
   sourceName: string,
-  client: ScenarioSDK,
+  client: Scenario,
 ): LogLevel | undefined => {
   if (!maybeLevel) {
     return undefined;
@@ -60,7 +60,7 @@ const noopLogger = {
 
 let cachedLoggers = /* @__PURE__ */ new WeakMap<Logger, [LogLevel, Logger]>();
 
-export function loggerFor(client: ScenarioSDK): Logger {
+export function loggerFor(client: Scenario): Logger {
   const logger = client.logger;
   const logLevel = client.logLevel ?? 'off';
   if (!logger) {

package/src/internal/utils/path.ts

@@ -1,4 +1,4 @@
-import { ScenarioSDKError } from '../../core/error';
+import { ScenarioError } from '../../core/error';
 
 /**
  * Percent-encode everything that isn't safe to have in a path without encoding safe chars.
@@ -72,7 +72,7 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
         return acc + spaces + arrows;
       }, '');
 
-      throw new ScenarioSDKError(
+      throw new ScenarioError(
         `Path parameters result in path with invalid segments:\n${invalidSegments
           .map((e) => e.error)
           .join('\n')}\n${path}\n${underline}`,

package/src/internal/utils/values.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { ScenarioSDKError } from '../../core/error';
+import { ScenarioError } from '../../core/error';
 
 // https://url.spec.whatwg.org/#url-scheme-string
 const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
@@ -39,7 +39,7 @@ export function isObj(obj: unknown): obj is Record<string, unknown> {
 
 export const ensurePresent = <T>(value: T | null | undefined): T => {
   if (value == null) {
-    throw new ScenarioSDKError(`Expected a value to be given but received ${value} instead.`);
+    throw new ScenarioError(`Expected a value to be given but received ${value} instead.`);
   }
 
   return value;
@@ -47,10 +47,10 @@ export const ensurePresent = <T>(value: T | null | undefined): T => {
 
 export const validatePositiveInteger = (name: string, n: unknown): number => {
   if (typeof n !== 'number' || !Number.isInteger(n)) {
-    throw new ScenarioSDKError(`${name} must be an integer`);
+    throw new ScenarioError(`${name} must be an integer`);
   }
   if (n < 0) {
-    throw new ScenarioSDKError(`${name} must be a positive integer`);
+    throw new ScenarioError(`${name} must be a positive integer`);
   }
   return n;
 };
@@ -59,14 +59,14 @@ export const coerceInteger = (value: unknown): number => {
   if (typeof value === 'number') return Math.round(value);
   if (typeof value === 'string') return parseInt(value, 10);
 
-  throw new ScenarioSDKError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+  throw new ScenarioError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
 };
 
 export const coerceFloat = (value: unknown): number => {
   if (typeof value === 'number') return value;
   if (typeof value === 'string') return parseFloat(value);
 
-  throw new ScenarioSDKError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+  throw new ScenarioError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
 };
 
 export const coerceBoolean = (value: unknown): boolean => {

package/src/lib/generate.ts

@@ -0,0 +1,77 @@
+import type { APIPromise } from '../core/api-promise';
+import type { RequestOptions } from '../internal/request-options';
+import {
+  Generate,
+  type GenerateCaptionParams,
+  type GenerateCaptionResponse,
+  type GenerateDescribeStyleParams,
+  type GenerateDescribeStyleResponse,
+  type GenerateDetectParams,
+  type GenerateDetectResponse,
+  type GenerateEmbedParams,
+  type GenerateEmbedResponse,
+  type GeneratePatchParams,
+  type GeneratePatchResponse,
+  type GenerateRunModelParams,
+  type GenerateRunModelResponse,
+  type GenerateTranslateParams,
+  type GenerateTranslateResponse,
+} from '../resources/generate';
+import { type WithJob, enhanceJob } from './job';
+
+/**
+ * Enhanced Generate resource.
+ * All original methods are inherited. Job-producing methods return
+ * responses where `job` has `.wait()`.
+ */
+export class EnhancedGenerate extends Generate {
+  override caption(
+    params: GenerateCaptionParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<GenerateCaptionResponse>> {
+    return enhanceJob(this._client, super.caption(params, options));
+  }
+
+  override describeStyle(
+    params: GenerateDescribeStyleParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<GenerateDescribeStyleResponse>> {
+    return enhanceJob(this._client, super.describeStyle(params, options));
+  }
+
+  override detect(
+    params: GenerateDetectParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<GenerateDetectResponse>> {
+    return enhanceJob(this._client, super.detect(params, options));
+  }
+
+  override embed(
+    params: GenerateEmbedParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<GenerateEmbedResponse>> {
+    return enhanceJob(this._client, super.embed(params, options));
+  }
+
+  override patch(
+    params: GeneratePatchParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<GeneratePatchResponse>> {
+    return enhanceJob(this._client, super.patch(params, options));
+  }
+
+  override runModel(
+    modelID: string,
+    params: GenerateRunModelParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<GenerateRunModelResponse>> {
+    return enhanceJob(this._client, super.runModel(modelID, params, options));
+  }
+
+  override translate(
+    params: GenerateTranslateParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<GenerateTranslateResponse>> {
+    return enhanceJob(this._client, super.translate(params, options));
+  }
+}

package/src/lib/job.ts

@@ -0,0 +1,78 @@
+import type { Scenario } from '../client';
+import type { APIPromise } from '../core/api-promise';
+import type { JobRetrieveResponse } from '../resources/jobs';
+
+export interface WaitOptions {
+  /** Polling interval in milliseconds. Default: 3000 */
+  intervalMs?: number;
+  /** Maximum wait time in milliseconds. Default: 120000 */
+  timeoutMs?: number;
+}
+
+type JobStatus = JobRetrieveResponse.Job['status'];
+
+const TERMINAL_STATUSES: Set<JobStatus> = new Set(['success', 'failure', 'canceled']);
+
+/** Job methods added on top of the original job fields. */
+export class JobMethods {
+  /** @internal */ declare readonly _client: Scenario;
+
+  /**
+   * Poll until the job reaches a terminal status (success, failure, or canceled).
+   *
+   * @example
+   * ```ts
+   * const response = await client.workflows.run(workflowId, { body });
+   * const completed = await response.job.wait();
+   * console.log(completed.status);
+   * ```
+   */
+  async wait(this: Job, options?: WaitOptions): Promise<Job> {
+    const intervalMs = options?.intervalMs ?? 3_000;
+    const timeoutMs = options?.timeoutMs ?? 120_000;
+    let elapsed = 0;
+
+    while (elapsed < timeoutMs) {
+      const response = await this._client.jobs.retrieve(this.jobId);
+
+      if (TERMINAL_STATUSES.has(response.job.status)) {
+        return Job.from(this._client, response.job);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      elapsed += intervalMs;
+    }
+
+    throw new Error(`Job ${this.jobId} did not complete within ${timeoutMs / 1_000}s`);
+  }
+
+  /** @internal Create a Job from raw job data. */
+  static from(client: Scenario, data: JobRetrieveResponse['job']): Job {
+    const job = Object.assign(Object.create(JobMethods.prototype), data) as Job;
+    Object.defineProperty(job, '_client', { value: client, enumerable: false });
+    return job;
+  }
+}
+
+/** A job with all original fields plus `.wait()`. */
+export type Job = JobRetrieveResponse.Job & JobMethods;
+export const Job = JobMethods;
+
+/**
+ * @internal Helper type: adds `.wait()` to the `job` field of a response.
+ * Uses intersection so the original response type is preserved — a `WithJob<T>` is still assignable to `T`.
+ */
+export type WithJob<T extends { job: unknown }> = T & { job: JobMethods };
+
+/**
+ * @internal Wrap `_thenUnwrap` to replace `response.job` with an enhanced Job.
+ */
+export function enhanceJob<T extends { job: { jobId: string; status: string } }>(
+  client: Scenario,
+  promise: APIPromise<T>,
+): APIPromise<WithJob<T>> {
+  return promise._thenUnwrap((data) => ({
+    ...data,
+    job: Job.from(client, data.job as JobRetrieveResponse['job']),
+  }));
+}

package/src/lib/models.ts

@@ -0,0 +1,27 @@
+import type { APIPromise } from '../core/api-promise';
+import type { RequestOptions } from '../internal/request-options';
+import { Models } from '../resources/models/models';
+import { Train, type TrainTriggerParams, type TrainTriggerResponse } from '../resources/models/train';
+import { type WithJob, enhanceJob } from './job';
+
+/**
+ * Enhanced Train resource.
+ * `trigger()` returns a response where `job` has `.wait()`.
+ */
+export class EnhancedTrain extends Train {
+  override trigger(
+    modelID: string,
+    params: TrainTriggerParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<TrainTriggerResponse>> {
+    return enhanceJob(this._client, super.trigger(modelID, params, options));
+  }
+}
+
+/**
+ * Enhanced Models resource.
+ * All original methods inherited. `train` is an {@link EnhancedTrain}.
+ */
+export class EnhancedModels extends Models {
+  override train: EnhancedTrain = new EnhancedTrain(this._client);
+}

package/src/lib/scenario.ts

@@ -0,0 +1,39 @@
+import { Scenario as BaseScenario } from '../client';
+import { EnhancedGenerate } from './generate';
+import { EnhancedModels } from './models';
+import { EnhancedWorkflows } from './workflow';
+
+/**
+ * Enhanced Scenario client.
+ *
+ * Extends the generated client — all original methods are inherited.
+ * Job-producing methods return responses where `job` has `.wait()`.
+ * Workflow retrieve returns a response where `workflow` has `.findNode()`.
+ *
+ * @example
+ * ```ts
+ * import Scenario from '@scenario-labs/sdk';
+ *
+ * const client = new Scenario({ apiKey: '...' });
+ *
+ * // All generated methods work as-is
+ * const list = await client.assets.list({});
+ *
+ * // Enhanced: response.job.wait()
+ * const run = await client.workflows.run(workflowId, { body });
+ * const completed = await run.job.wait();
+ *
+ * // Enhanced: response.workflow.findNode()
+ * const wf = await client.workflows.retrieve(workflowId);
+ * wf.workflow.findNode('final_image');
+ *
+ * // Enhanced: generate job.wait()
+ * const gen = await client.generate.runModel(modelId, { body });
+ * const done = await gen.job.wait();
+ * ```
+ */
+export class Scenario extends BaseScenario {
+  override workflows: EnhancedWorkflows = new EnhancedWorkflows(this);
+  override generate: EnhancedGenerate = new EnhancedGenerate(this);
+  override models: EnhancedModels = new EnhancedModels(this);
+}

package/src/lib/workflow.ts

@@ -0,0 +1,90 @@
+import type { APIPromise } from '../core/api-promise';
+import type { RequestOptions } from '../internal/request-options';
+import {
+  Workflows,
+  type WorkflowApproveUserParams,
+  type WorkflowApproveUserResponse,
+  type WorkflowRetrieveResponse,
+  type WorkflowRunParams,
+  type WorkflowRunResponse,
+} from '../resources/workflows';
+import { type WithJob, enhanceJob } from './job';
+
+type DefinitionFlow = WorkflowRetrieveResponse.Workflow.Flow;
+type NodeType = DefinitionFlow['type'];
+
+/**
+ * Enhanced workflow object with helper methods.
+ * Has all original workflow fields plus `findNode()`, `getNodesByType()`.
+ *
+ * @example
+ * ```ts
+ * const response = await client.workflows.retrieve(workflowId);
+ * response.workflow.findNode('final_image');
+ * response.workflow.getNodesByType('custom-model');
+ * response.workflow.name; // original fields still work
+ * ```
+ */
+export class WorkflowEntity {
+  /** Find a node in the workflow definition by ID. */
+  findNode(
+    this: WorkflowEntity & WorkflowRetrieveResponse.Workflow,
+    nodeId: string,
+  ): DefinitionFlow | undefined {
+    return this.flow.find((node) => node.id === nodeId);
+  }
+
+  /** Get all nodes of a specific type from the workflow definition. */
+  getNodesByType(this: WorkflowEntity & WorkflowRetrieveResponse.Workflow, type: NodeType): DefinitionFlow[] {
+    return this.flow.filter((node) => node.type === type);
+  }
+
+  /** @internal Create a WorkflowEntity from raw workflow data. */
+  static from(data: WorkflowRetrieveResponse.Workflow): WorkflowRetrieveResponse.Workflow & WorkflowEntity {
+    return Object.assign(Object.create(WorkflowEntity.prototype), data);
+  }
+}
+
+/** Enhanced retrieve response with workflow entity methods. */
+export type EnhancedWorkflowRetrieveResponse = Omit<WorkflowRetrieveResponse, 'workflow'> & {
+  workflow: WorkflowRetrieveResponse.Workflow & WorkflowEntity;
+};
+
+/**
+ * Enhanced Workflows resource.
+ * Extends the generated {@link Workflows} — all original methods are inherited.
+ * Overrides `retrieve()`, `run()`, and `approveUser()` to return enriched response objects.
+ */
+export class EnhancedWorkflows extends Workflows {
+  /**
+   * Get workflow by ID. Returns an enhanced response where `workflow` has
+   * `findNode()` and `getNodesByType()`.
+   */
+  override retrieve(
+    workflowID: string,
+    options?: RequestOptions,
+  ): APIPromise<EnhancedWorkflowRetrieveResponse> {
+    return super.retrieve(workflowID, options)._thenUnwrap((data) => ({
+      ...data,
+      workflow: WorkflowEntity.from(data.workflow),
+    }));
+  }
+
+  /** Run a workflow. Returns an enhanced response where `job` has `.wait()`. */
+  override run(
+    workflowID: string,
+    params: WorkflowRunParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<WorkflowRunResponse>> {
+    return enhanceJob(this._client, super.run(workflowID, params, options));
+  }
+
+  /** Approve a user approval node. Returns an enhanced response where `job` has `.wait()`. */
+  override approveUser(
+    workflowID: string,
+    body: WorkflowApproveUserParams,
+    options?: RequestOptions,
+  ): APIPromise<WithJob<WorkflowApproveUserResponse>> {
+    return enhanceJob(this._client, super.approveUser(workflowID, body, options));
+  }
+}