@meistrari/tela-sdk-js 2.4.3 → 2.5.0

package/dist/index.d.ts

@@ -22,6 +22,7 @@ type RequestOptions<Req = unknown | Record<string, unknown>> = {
     stream?: boolean | undefined;
     timeout?: number;
     signal?: AbortSignal | undefined | null;
+    transformCase?: boolean;
 };
 interface BaseClientOptions {
     baseURL: string;
@@ -145,6 +146,15 @@ declare class ExecutionFailedError extends TelaError {
     readonly rawOutput: Record<string, any>;
     constructor(rawOutput: Record<string, any>);
 }
+/**
+ * Thrown when batch execution fails on the server.
+ *
+ * @category Errors
+ */
+declare class BatchExecutionFailedError extends TelaError {
+    readonly rawResponse: Record<string, any>;
+    constructor(rawResponse: Record<string, any>);
+}
 /**
  * Base class for all API-related errors.
  *
@@ -385,16 +395,6 @@ declare class TelaFile {
     private isValidVaultReference;
 }
 
-/**
- * Canvas execution module for managing canvas execution lifecycle and modes.
- *
- * This module handles the execution of canvas templates with support for
- * synchronous, asynchronous (with polling), and streaming modes. It also
- * manages file uploads and result validation.
- *
- * @module Resources
- */
-
 interface BaseExecutionParams {
     /**
      * The version ID of the canvas to use for this chat completion.
@@ -471,6 +471,29 @@ interface BaseExecutionParams {
      */
     tags?: string[];
 }
+
+/**
+ * Helper type to add request ID to a response type.
+ *
+ * The `requestId` field contains the value from the `x-request-id` HTTP header
+ * returned by the API for that specific request.
+ *
+ * @template T - The base response type.
+ */
+type WithRequestId<T> = T & {
+    requestId?: string;
+};
+
+/**
+ * Canvas execution module for managing canvas execution lifecycle and modes.
+ *
+ * This module handles the execution of canvas templates with support for
+ * synchronous, asynchronous (with polling), and streaming modes. It also
+ * manages file uploads and result validation.
+ *
+ * @module Resources
+ */
+
 /**
  * Configuration for asynchronous canvas execution with polling.
  * The execution starts immediately but results must be retrieved via polling.
@@ -486,15 +509,15 @@ interface AsyncExecutionParams extends BaseExecutionParams {
      */
     webhookUrl?: string;
     /**
-     * Time in milliseconds between polling attempts.
+     * Time (in milliseconds if number) between polling attempts (e.g. "1s", "1m", "1h", "1d").
      * @default 1000
      */
-    pollingInterval?: number;
+    pollingInterval?: string | number;
     /**
-     * Maximum time in milliseconds to wait for completion before timing out.
+     * Maximum time (in milliseconds if number) to wait for completion before timing out (e.g. "1s", "1m", "1h", "1d").
      * @default 60000
      */
-    pollingTimeout?: number;
+    pollingTimeout?: string | number;
     /**
      * Stream mode is not available for async executions.
      */
@@ -649,17 +672,6 @@ type TaskCreationResult = {
  * This type will be refined in future versions with proper typing.
  */
 type RawAPIResult = any;
-/**
- * Helper type to add request ID to a response type.
- *
- * The `requestId` field contains the value from the `x-request-id` HTTP header
- * returned by the API for that specific request.
- *
- * @template T - The base response type.
- */
-type WithRequestId<T> = T & {
-    requestId?: string;
-};
 /**
  * Result returned when polling for asynchronous execution status.
  *
@@ -823,8 +835,8 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * ```
      */
     static fetch<TOutput = unknown>(id: string, outputSchema: _zod__default.ZodType | Record<string, unknown>, client: BaseClient, options?: {
-        pollingInterval?: number;
-        pollingTimeout?: number;
+        pollingInterval?: string | number;
+        pollingTimeout?: string | number;
         isTask?: boolean;
     }): Promise<CanvasExecution<AsyncExecutionParams, unknown, TOutput>>;
     /**
@@ -1124,6 +1136,895 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
     private uploadFiles;
 }
 
+type CompletionRunResult<TOutput> = {
+    id: string;
+    status: string;
+    inputContent: {
+        files: Array<any>;
+        messages: Array<any>;
+        variables: Record<string, unknown>;
+    };
+    outputContent: {
+        role: string;
+        content: TOutput;
+        toolCalls: Array<any>;
+        functionCall: any;
+    };
+    rawInput: {
+        tags: Array<string>;
+        async: boolean;
+        canvasId: string;
+        variables: Record<string, unknown>;
+    };
+    rawOutput: {
+        id: string;
+        usage: {
+            cost: {
+                totalCost: number;
+                promptCost: number;
+                completionCost: number;
+            };
+            totalTokens: number;
+            promptTokens: number;
+            completionTokens: number;
+        };
+        object: string;
+        choices: Array<{
+            message: {
+                role: string;
+                content: TOutput;
+                toolCalls: Array<any>;
+                functionCall: any;
+            };
+        }>;
+        created: number;
+    };
+    compatibilityDate: string;
+    metadata: {
+        promptVersion: {
+            modelConfigurations: {
+                type: string;
+                model: string;
+                temperature: number;
+                structuredOutput: {
+                    schema: {
+                        type: string;
+                        title: string;
+                        required: Array<string>;
+                        properties: Record<string, unknown>;
+                        description: string;
+                    };
+                    enabled: boolean;
+                };
+            };
+            variablesDefinitions: Array<{
+                name: string;
+                type: string;
+                required: boolean;
+                processingOptions: {
+                    allowMultimodal: boolean;
+                };
+            }>;
+        };
+    };
+    tags: Array<string>;
+    creditsUsed: number;
+    promptId: string;
+    promptVersionId: string;
+    promptApplicationId: any;
+    workspaceId: string;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: any;
+};
+
+/**
+ * Helper type for accepting either a single value or an array of values.
+ *
+ * @template T - The base type.
+ */
+type MaybeArray<T> = T | T[];
+/**
+ * Canvas identification methods for batch operations.
+ * Use either canvas ID with optional version, or application ID.
+ */
+type CanvasIdentifier = {
+    id: string;
+    versionId?: string;
+} | {
+    applicationId: string;
+};
+/**
+ * Status of a batch execution.
+ *
+ * Lifecycle progression:
+ * - `created` - Batch queued on server (initial state)
+ * - `validating` - Input file validation in progress
+ * - `running` - Batch actively processing executions
+ * - `completed` - All executions finished successfully
+ * - `failed` - Batch failed (validation error or server failure)
+ * - `canceled` - Batch canceled by user
+ *
+ * @see {@link BatchExecution.status} for accessing current status
+ */
+type BatchExecutionStatus = 'created' | 'validating' | 'running' | 'failed' | 'completed' | 'canceled';
+/**
+ * Raw API response for batch execution operations.
+ * Contains batch metadata, status, and progress information.
+ */
+type BatchResponse = {
+    /**
+     * The type of batch task (always 'async-completion').
+     */
+    task: string;
+    /**
+     * Vault URL of the input JSONL file.
+     */
+    inputFile: string;
+    /**
+     * Webhook URL for completion notifications, if configured.
+     */
+    webhookUrl: string | null;
+    /**
+     * Current status of the batch execution.
+     */
+    status: BatchExecutionStatus;
+    /**
+     * Unique identifier for this batch execution.
+     */
+    id: string;
+    /**
+     * Vault URL of the output JSONL file, available when completed.
+     */
+    outputFile: string | null;
+    /**
+     * Progress statistics, available when running or completed.
+     */
+    state: {
+        /**
+         * Number of failed executions.
+         */
+        failed: number;
+        /**
+         * Number of completed executions.
+         */
+        completed: number;
+        /**
+         * Total number of executions in the batch.
+         */
+        total: number;
+    } | null;
+    /**
+     * ISO timestamp when the batch was created.
+     */
+    createdAt: string;
+    /**
+     * ISO timestamp when the batch was last updated.
+     */
+    updatedAt: string;
+    /**
+     * ISO timestamp when the batch completed, if applicable.
+     */
+    completedAt: string | null;
+    /**
+     * ISO timestamp when the batch was canceled, if applicable.
+     */
+    canceledAt: string | null;
+    /**
+     * ISO timestamp when the batch failed, if applicable.
+     */
+    failedAt: string | null;
+};
+/**
+ * Represents a single item to be executed in a batch.
+ *
+ * @template TInput - The input variables type for the canvas.
+ */
+interface BatchItem<TInput> {
+    /**
+     * Optional unique identifier for this execution.
+     * If not provided, a random UUID will be generated automatically.
+     * Used to retrieve individual results from the batch output.
+     */
+    referenceId?: string;
+    /**
+     * Input variables for this execution, matching the canvas input schema.
+     */
+    variables: TInput;
+}
+/**
+ * Parameters excluded from batch execution (managed internally).
+ */
+type ExcludedParams = 'versionId' | 'canvasId' | 'applicationId' | 'async' | 'stream' | 'webhookUrl' | 'skipResultValidation';
+/**
+ * Configuration options for batch execution.
+ *
+ * Batch executions are always asynchronous and return results via output file.
+ * Unlike single executions, batches do not support streaming or synchronous modes.
+ *
+ * @category Canvas
+ */
+interface BatchParams extends Omit<BaseExecutionParams, ExcludedParams> {
+    /**
+     * Time (in milliseconds if number) between polling attempts (e.g. "1s", "1m", "1h", "1d").
+     * Controls how frequently the SDK checks batch completion status.
+     * @default "1s"
+     */
+    pollingInterval?: string | number;
+    /**
+     * Maximum time (in milliseconds if number) to wait for completion before timing out (e.g. "1s", "1m", "1h", "1d").
+     * After timeout, polling stops but the batch continues processing on the server.
+     * @default "1m"
+     */
+    pollingTimeout?: string | number;
+    /**
+     * Optional webhook URL to receive completion notifications.
+     * The server will POST to this URL when the batch completes, fails, or is canceled.
+     */
+    webhookUrl?: string;
+}
+/**
+ * Promise-like wrapper for batch execution that provides direct result access.
+ *
+ * Enables flexible usage patterns:
+ * - Await for execution object: `const exec = await batch.execute()`
+ * - Direct result access: `const result = await batch.execute().result`
+ *
+ * @template TOutput - The output type for batch results.
+ *
+ * @category Canvas
+ */
+type BatchExecutionPromiseLike<TOutput> = PromiseLike<BatchExecution<TOutput>> & {
+    /**
+     * Direct access to the batch result, automatically starting polling.
+     */
+    result: Promise<BatchExecutionResult<TOutput>>;
+};
+/**
+ * Wraps the completed batch execution response with convenient result access methods.
+ *
+ * Provides multiple ways to access batch results:
+ * - Download entire output file: `downloadOutputFile()`
+ * - Stream results incrementally: `iterateResults()`
+ * - Get all results as array: `getResults()`
+ * - Fetch individual result by reference ID: `getResult(referenceId)`
+ *
+ * @category Canvas
+ *
+ * @template TOutput - The output type for individual results.
+ *
+ * @example
+ * ```typescript
+ * const execution = await batch.execute()
+ * const result = await execution.result
+ *
+ * // Access batch metadata
+ * console.log(`Status: ${result.status}`)
+ * console.log(`Progress: ${result.state.completed}/${result.state.total}`)
+ *
+ * // Iterate through results
+ * for await (const item of result.iterateResults()) {
+ *   console.log(item)
+ * }
+ * ```
+ */
+declare class BatchExecutionResult<TOutput> {
+    private readonly _client;
+    private readonly _response;
+    /**
+     * Creates a new batch execution result wrapper.
+     *
+     * @param client - HTTP client for making API requests.
+     * @param response - Raw batch execution response from the server.
+     * @internal
+     */
+    constructor(client: BaseClient, response: WithRequestId<BatchResponse>);
+    get requestId(): string | undefined;
+    /**
+     * Gets the unique identifier for this batch execution.
+     *
+     * @returns The batch execution ID.
+     */
+    get id(): string;
+    /**
+     * Gets the current status of the batch execution.
+     *
+     * @returns The batch status.
+     */
+    get status(): BatchExecutionStatus;
+    /**
+     * Gets the progress statistics for this batch.
+     *
+     * @returns Object containing completed, failed, and total execution counts, or null if not available.
+     */
+    get state(): {
+        /**
+         * Number of failed executions.
+         */
+        failed: number;
+        /**
+         * Number of completed executions.
+         */
+        completed: number;
+        /**
+         * Total number of executions in the batch.
+         */
+        total: number;
+    } | null;
+    /**
+     * Gets the vault URL of the output JSONL file containing all results.
+     *
+     * @returns The output file URL, or null if batch is not completed.
+     */
+    get outputFile(): string | null;
+    /**
+     * Gets the raw API response without any processing.
+     *
+     * @returns The complete batch response object.
+     */
+    get rawResponse(): WithRequestId<BatchResponse>;
+    /**
+     * Gets the timestamp when this batch was created.
+     *
+     * @returns Creation date.
+     */
+    get createdAt(): Date;
+    /**
+     * Gets the timestamp when this batch was last updated.
+     *
+     * @returns Last update date.
+     */
+    get updatedAt(): Date;
+    /**
+     * Gets the timestamp when this batch completed successfully.
+     *
+     * @returns Completion date, or null if not completed.
+     */
+    get completedAt(): Date | null;
+    /**
+     * Gets the timestamp when this batch was canceled.
+     *
+     * @returns Cancellation date, or null if not canceled.
+     */
+    get canceledAt(): Date | null;
+    /**
+     * Gets the timestamp when this batch failed.
+     *
+     * @returns Failure date, or null if not failed.
+     */
+    get failedAt(): Date | null;
+    /**
+     * Downloads the complete output file as a Blob.
+     *
+     * The output file is a JSONL (JSON Lines) file where each line contains
+     * one execution result with its reference ID, status, and output.
+     *
+     * @throws {Error} If batch is not completed or output file is unavailable.
+     * @returns A promise resolving to the output file as a Blob.
+     *
+     * @example
+     * ```typescript
+     * const file = await result.downloadOutputFile()
+     * const text = await file.text()
+     * console.log(text) // JSONL content
+     * ```
+     */
+    downloadOutputFile(): Promise<Blob>;
+    /**
+     * Streams the output file as a ReadableStream for memory-efficient processing.
+     *
+     * Useful for large batches where loading the entire file into memory is not practical.
+     *
+     * @throws {Error} If batch is not completed or output file is unavailable.
+     * @returns A promise resolving to a ReadableStream of the output file.
+     *
+     * @example
+     * ```typescript
+     * const stream = await result.streamOutputFile()
+     * // Process stream with custom logic
+     * ```
+     */
+    streamOutputFile(): Promise<ReadableStream>;
+    /**
+     * Downloads and parses all results into an array.
+     *
+     * Loads the entire output file into memory, parses each line, and extracts
+     * the output content. For large batches, consider using `iterateResults()` instead.
+     *
+     * @throws {Error} If batch is not completed, output file is unavailable, or parsing fails.
+     * @returns A promise resolving to an array of all execution outputs.
+     *
+     * @example
+     * ```typescript
+     * const results = await result.getResults()
+     * console.log(`Got ${results.length} results`)
+     * results.forEach((output, i) => console.log(`Result ${i}:`, output))
+     * ```
+     */
+    getResults(): Promise<TOutput[]>;
+    /**
+     * Asynchronously iterates over raw result items from the output file.
+     *
+     * Streams and parses the output file line-by-line, yielding raw JSON objects.
+     * Each yielded object contains the full result structure including metadata.
+     *
+     * @param params - Iteration options.
+     * @param params.abortController - Optional AbortController to cancel iteration.
+     * @throws {Error} If batch is not completed or output file is unavailable.
+     * @yields Raw result objects from the JSONL file.
+     *
+     * @example
+     * ```typescript
+     * for await (const rawResult of result.iterateRawResults()) {
+     *   console.log('Reference ID:', rawResult.reference_id)
+     *   console.log('Status:', rawResult.status)
+     *   console.log('Output:', rawResult.result.outputContent.content)
+     * }
+     * ```
+     */
+    iterateRawResults(params?: {
+        abortController?: AbortController;
+    }): AsyncGenerator<unknown, void, unknown>;
+    /**
+     * Asynchronously iterates over parsed output content from the batch results.
+     *
+     * Streams and parses the output file line-by-line, yielding only the output content
+     * (not the full result metadata). Memory-efficient for large batches.
+     *
+     * @param params - Iteration options.
+     * @param params.abortController - Optional AbortController to cancel iteration.
+     * @throws {Error} If batch is not completed, output file is unavailable, or parsing fails.
+     * @yields Parsed output content from each execution.
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController()
+     *
+     * for await (const output of result.iterateResults({ abortController: controller })) {
+     *   console.log(output)
+     *   if (someCondition) {
+     *     controller.abort() // Stop iteration early
+     *   }
+     * }
+     * ```
+     */
+    iterateResults(params?: {
+        abortController?: AbortController;
+    }): AsyncGenerator<Awaited<TOutput>, void, unknown>;
+    /**
+     * Fetches the raw result metadata for a specific execution by its reference ID.
+     *
+     * Queries the API for the execution result using the reference ID tag.
+     * Returns the complete execution metadata including input, output, and usage statistics.
+     *
+     * @param referenceId - The reference ID of the execution to retrieve.
+     * @throws {Error} If no result found with the given reference ID.
+     * @returns A promise resolving to the raw execution result object.
+     *
+     * @example
+     * ```typescript
+     * const rawResult = await result.getRawResult('my-ref-id')
+     * console.log('Credits used:', rawResult.creditsUsed)
+     * console.log('Execution status:', rawResult.status)
+     * ```
+     */
+    getRawResult(referenceId: string): Promise<CompletionRunResult<TOutput>>;
+    /**
+     * Fetches the output content for a specific execution by its reference ID.
+     *
+     * Convenience method that retrieves the raw result and extracts just the output content.
+     *
+     * @param referenceId - The reference ID of the execution to retrieve.
+     * @throws {Error} If no result found with the given reference ID.
+     * @returns A promise resolving to the execution output content.
+     *
+     * @example
+     * ```typescript
+     * const output = await result.getResult('my-ref-id')
+     * console.log('Output:', output)
+     * ```
+     */
+    getResult(referenceId: string): Promise<TOutput>;
+    /**
+     * Validates that the output file is available for access.
+     *
+     * @throws {Error} If batch is not completed or output file is missing.
+     * @private
+     */
+    private validateOutputFile;
+}
+/**
+ * Event types emitted by BatchExecution during its lifecycle.
+ *
+ * @template TOutput - The output type.
+ *
+ * @property poll - Emitted during polling with current status and progress. Includes `requestId` from the polling request.
+ * @property success - Emitted when batch completes successfully with the result object. Includes `requestId` from the final request.
+ * @property error - Emitted when batch fails with the error object.
+ * @property statusChange - Emitted when batch status transitions to a new state, includes new status and response.
+ *
+ * @category Canvas
+ */
+type BatchExecutionEvents<TOutput> = {
+    poll: WithRequestId<BatchResponse>;
+    success: BatchExecutionResult<TOutput>;
+    error: BatchExecutionFailedError;
+    statusChange: [BatchExecutionStatus, WithRequestId<BatchResponse>];
+};
+/**
+ * Manages the execution lifecycle of a batch operation.
+ *
+ * Handles polling for batch completion, progress tracking, and result retrieval.
+ * Provides an event-driven API for monitoring batch progress in real-time.
+ *
+ * ## Status Tracking
+ *
+ * The batch status can be accessed via the `status` property and tracks the lifecycle:
+ *
+ * - **Batch executions**: `created` → `validating` → `running` → `completed` or `failed`
+ * - **Can be canceled**: At any time before completion using `cancel()`
+ *
+ * Status is set to `failed` when:
+ * - Input file validation fails
+ * - Batch processing encounters an error
+ * - Server reports failure status
+ *
+ * Status is set to `completed` when:
+ * - All executions in the batch finish processing
+ * - Output file is generated and available
+ *
+ * ## Event System
+ *
+ * Events are emitted during polling to track progress:
+ * - `statusChange` - Status transitions (created → validating → running → completed)
+ * - `poll` - Each polling attempt with current progress
+ * - `success` - Completion with the BatchExecutionResult
+ * - `error` - Failure notification
+ *
+ * **Important:** Events are only emitted while polling is active. You must either call `poll()` or
+ * await `execution.result` to start polling.
+ *
+ * @category Canvas
+ *
+ * @typeParam TOutput - The output result type for individual executions
+ *
+ * @fires poll - Emitted during polling with current status and progress. Includes `requestId` from the polling request.
+ * @fires success - Emitted when batch completes successfully with the result object. Includes `requestId` from the final request.
+ * @fires error - Emitted when batch fails (only if error listeners are registered, otherwise throws)
+ * @fires statusChange - Emitted when batch status transitions to a new state
+ *
+ * @example
+ * ```typescript
+ * const execution = await batch.execute()
+ *
+ * // Track progress with events
+ * execution.on('statusChange', ([status, response]) => {
+ *   console.log(`Status: ${status}`)
+ *   if (response.state) {
+ *     console.log(`Progress: ${response.state.completed}/${response.state.total}`)
+ *   }
+ * })
+ *
+ * execution.on('success', (result) => {
+ *   console.log('Batch completed!')
+ *   console.log('Request ID:', result.requestId)
+ * })
+ *
+ * // Start polling without waiting
+ * execution.poll()
+ * ```
+ */
+declare class BatchExecution<TOutput> extends Emittery<BatchExecutionEvents<TOutput>> {
+    private readonly _client;
+    private readonly _id;
+    private readonly _params;
+    private readonly _abortController;
+    private readonly _creationResponse;
+    private _status;
+    private _resultPromise;
+    /**
+     * Creates a new batch execution instance.
+     *
+     * @param id - Unique identifier for this batch execution.
+     * @param client - HTTP client for making API requests.
+     * @param params - Batch execution parameters.
+     * @param creationResponse - Initial response from batch creation.
+     * @internal
+     */
+    constructor(id: string, client: BaseClient, params: BatchParams | undefined, creationResponse: WithRequestId<BatchResponse>);
+    /**
+     * Gets the latest known status of the batch execution.
+     *
+     * Status values and transitions:
+     * - `created` → `validating` → `running` → `completed` or `failed`
+     * - Can transition to `canceled` from any non-terminal state
+     *
+     * Use the `statusChange` event to track status transitions in real-time.
+     *
+     * @returns The current status of the batch execution.
+     *
+     * @example
+     * ```typescript
+     * const execution = await batch.execute()
+     * console.log(execution.status) // 'created'
+     *
+     * execution.on('statusChange', ([status]) => {
+     *   console.log('New status:', status)
+     * })
+     *
+     * await execution.result
+     * console.log(execution.status) // 'completed' or 'failed'
+     * ```
+     */
+    get status(): BatchExecutionStatus;
+    /**
+     * Gets the unique identifier for this batch execution.
+     *
+     * @returns The batch execution ID.
+     */
+    get id(): string;
+    /**
+     * Gets the batch execution parameters.
+     *
+     * @returns The batch parameters.
+     */
+    get params(): BatchParams;
+    /**
+     * Cancels the batch execution.
+     *
+     * Sends a cancellation request to the server and aborts any ongoing polling.
+     * The batch will stop processing, but already-completed executions remain available.
+     *
+     * @returns A promise that resolves when the cancellation request completes.
+     *
+     * @example
+     * ```typescript
+     * const execution = await batch.execute()
+     * execution.poll()
+     *
+     * // Cancel after some condition
+     * if (shouldCancel) {
+     *   await execution.cancel()
+     *   console.log(execution.status) // 'canceled'
+     * }
+     * ```
+     */
+    cancel(): Promise<void>;
+    /**
+     * Starts polling for the batch result without waiting for the promise to resolve.
+     * This allows users to track batch progress via events rather than awaiting a promise.
+     *
+     * The following events will be emitted during polling:
+     * - `statusChange`: Emitted when the batch status changes (e.g., 'created' → 'running' → 'completed')
+     * - `poll`: Emitted on each polling attempt with the server response
+     * - `success`: Emitted when the batch completes successfully with the final result
+     * - `error`: Emitted if the batch fails
+     *
+     * **Important:** Events are only emitted while polling is active. You must call `poll()` or
+     * await `execution.result` to start polling. Simply setting up event listeners without starting
+     * polling will not trigger any events.
+     *
+     * @example
+     * ```typescript
+     * const execution = await batch.execute()
+     *
+     * // Set up event listeners
+     * execution.on('statusChange', ([status, response]) => {
+     *   console.log(`Status: ${status}`)
+     *   if (response.state) {
+     *     const { completed, total } = response.state
+     *     console.log(`Progress: ${completed}/${total}`)
+     *   }
+     * })
+     *
+     * execution.on('success', (result) => {
+     *   console.log('Batch completed!')
+     *   console.log('Request ID:', result.requestId)
+     * })
+     *
+     * execution.on('error', (error) => {
+     *   console.error('Batch failed:', error)
+     * })
+     *
+     * // Start polling without waiting
+     * execution.poll()
+     * ```
+     */
+    poll(): void;
+    /**
+     * Sets the batch status and emits statusChange event if changed.
+     *
+     * @param status - The new status.
+     * @param response - The response containing the status.
+     * @private
+     */
+    private setStatus;
+    /**
+     * Starts polling the server for batch completion.
+     * Continues polling until the batch completes, fails, or times out.
+     *
+     * @throws {BatchExecutionFailedError} If the batch fails on the server.
+     * @throws {Error} If the polling operation times out.
+     * @returns A promise resolving to the final batch result.
+     * @private
+     */
+    private startPolling;
+    /**
+     * Gets the batch execution result. Automatically starts polling if not already started.
+     *
+     * @returns A promise resolving to the batch execution result.
+     *
+     * @example
+     * ```typescript
+     * const execution = await batch.execute()
+     * const result = await execution.result
+     *
+     * // Access results
+     * const outputs = await result.getResults()
+     * console.log(`Got ${outputs.length} results`)
+     * ```
+     */
+    get result(): Promise<BatchExecutionResult<TOutput>>;
+}
+/**
+ * Builder class for creating and executing batch operations on a canvas.
+ *
+ * The Batch class provides a fluent API for building up a collection of executions
+ * to be processed in parallel. Items can be added incrementally, and the batch is
+ * executed only when `execute()` is called.
+ *
+ * ## Usage Pattern
+ *
+ * 1. Create batch via `canvas.createBatch()`
+ * 2. Add items via `add()` method (can be called multiple times)
+ * 3. Execute batch via `execute()` method
+ * 4. Monitor progress via events or await result
+ *
+ * ## Reference IDs
+ *
+ * Each batch item can have an optional reference ID for later retrieval.
+ * If not provided, UUIDs are generated automatically. Reference IDs are useful
+ * for correlating results with input data.
+ *
+ * @category Canvas
+ *
+ * @typeParam TInput - The input variables type for the canvas
+ * @typeParam TOutput - The output result type for individual executions
+ *
+ * @example
+ * ```typescript
+ * const batch = canvas.createBatch({
+ *   pollingInterval: '1s',
+ *   pollingTimeout: '5m',
+ * })
+ *
+ * // Add items individually
+ * batch.add({
+ *   referenceId: 'item-1',
+ *   variables: { query: 'First query' }
+ * })
+ *
+ * // Or add multiple items at once
+ * batch.add([
+ *   { variables: { query: 'Second query' } },
+ *   { variables: { query: 'Third query' } }
+ * ])
+ *
+ * // Execute and track progress
+ * const execution = await batch.execute()
+ * execution.on('statusChange', ([status, response]) => {
+ *   if (response.state) {
+ *     console.log(`Progress: ${response.state.completed}/${response.state.total}`)
+ *   }
+ * })
+ *
+ * const result = await execution.result
+ * const outputs = await result.getResults()
+ * ```
+ */
+declare class Batch<TInput, TOutput> {
+    private readonly _client;
+    private readonly _canvasIdentifier;
+    private readonly _items;
+    private readonly _params;
+    /**
+     * Creates a new batch builder.
+     *
+     * @param client - HTTP client for making API requests.
+     * @param canvasIdentifier - Canvas identification (ID + version or application ID).
+     * @param params - Optional batch execution parameters.
+     * @internal
+     */
+    constructor(client: BaseClient, canvasIdentifier: CanvasIdentifier, params?: BatchParams);
+    /**
+     * Gets the current list of items in this batch.
+     *
+     * @returns Array of batch items.
+     */
+    get items(): BatchItem<TInput>[];
+    /**
+     * Gets the batch execution parameters.
+     *
+     * @returns The batch parameters.
+     */
+    get params(): BatchParams;
+    /**
+     * Gets the canvas identifier in the format expected by the API.
+     *
+     * @returns Canvas identifier object.
+     * @private
+     */
+    private get canvasIdentifier();
+    /**
+     * Adds one or more items to the batch.
+     *
+     * Items without a reference ID will have UUIDs generated automatically.
+     * This method can be called multiple times to build up the batch incrementally.
+     *
+     * @param item - Single item or array of items to add to the batch.
+     *
+     * @example
+     * ```typescript
+     * // Add single item
+     * batch.add({
+     *   referenceId: 'my-custom-id',
+     *   variables: { query: 'Hello' }
+     * })
+     *
+     * // Add multiple items
+     * batch.add([
+     *   { variables: { query: 'First' } },
+     *   { variables: { query: 'Second' } },
+     *   { variables: { query: 'Third' } }
+     * ])
+     *
+     * console.log(`Batch has ${batch.items.length} items`)
+     * ```
+     */
+    add(item: MaybeArray<BatchItem<TInput>>): void;
+    /**
+     * Executes the batch by uploading the input file and creating a batch execution on the server.
+     *
+     * Returns a promise-like object that allows flexible usage patterns:
+     * - Await for execution object: `const exec = await batch.execute()`
+     * - Direct result access: `const result = await batch.execute().result`
+     *
+     * The batch items are serialized to JSONL format, uploaded to vault storage,
+     * and submitted to the batch API for processing.
+     *
+     * @returns A promise-like object with a `result` property for direct result access.
+     *
+     * @example
+     * ```typescript
+     * // Direct result access (recommended for simple cases)
+     * const result = await batch.execute().result
+     * const outputs = await result.getResults()
+     *
+     * // Get execution object for event monitoring
+     * const execution = await batch.execute()
+     *
+     * execution.on('statusChange', ([status, response]) => {
+     *   console.log(`Status: ${status}`)
+     *   if (response.state) {
+     *     console.log(`Progress: ${response.state.completed}/${response.state.total}`)
+     *   }
+     * })
+     *
+     * execution.on('success', (result) => {
+     *   console.log('Batch completed!', result.requestId)
+     * })
+     *
+     * const result = await execution.result
+     *
+     * // Iterate through results
+     * for await (const output of result.iterateResults()) {
+     *   console.log(output)
+     * }
+     * ```
+     */
+    execute(): BatchExecutionPromiseLike<TOutput>;
+}
+
 /**
  * Canvas resource for managing prompt templates and their execution.
  *
@@ -1466,16 +2367,12 @@ declare const zod: {
     safeParseAsync: <T extends _zod.core.$ZodType>(schema: T, value: unknown, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => Promise<_zod.ZodSafeParseResult<_zod.core.output<T>>>;
     encode: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.output<T>, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => _zod.core.input<T>;
     decode: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.input<T>, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => _zod.core.output<T>;
-    encodeAsync: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.output<T>, _ctx? /**
-     * Unique identifier for this prompt version.
-     */: _zod.core.ParseContext<_zod.core.$ZodIssue>) => Promise<_zod.core.input<T>>;
+    encodeAsync: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.output<T>, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => Promise<_zod.core.input<T>>;
     decodeAsync: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.input<T>, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => Promise<_zod.core.output<T>>;
     safeEncode: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.output<T>, _ctx? /**
-     * Variables available in this prompt version.
+     * The ID of the parent prompt.
      */: _zod.core.ParseContext<_zod.core.$ZodIssue>) => _zod.ZodSafeParseResult<_zod.core.input<T>>;
-    safeDecode: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.input<T>, _ctx? /**
-     * Configuration settings for this prompt version.
-     */: _zod.core.ParseContext<_zod.core.$ZodIssue>) => _zod.ZodSafeParseResult<_zod.core.output<T>>;
+    safeDecode: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.input<T>, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => _zod.ZodSafeParseResult<_zod.core.output<T>>;
     safeEncodeAsync: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.output<T>, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => Promise<_zod.ZodSafeParseResult<_zod.core.input<T>>>;
     safeDecodeAsync: <T extends _zod.core.$ZodType>(schema: T, value: _zod.core.input<T>, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => Promise<_zod.ZodSafeParseResult<_zod.core.output<T>>>;
     setErrorMap(map: _zod.core.$ZodErrorMap): void;
@@ -1668,9 +2565,38 @@ declare class Canvas<TInput extends ZodTypeOrRecord, TOutput extends ZodTypeOrRe
      * ```
      */
     getExecution(id: string, options?: {
-        pollingInterval?: number;
-        pollingTimeout?: number;
+        pollingInterval?: string | number;
+        pollingTimeout?: string | number;
     }): Promise<CanvasExecution<AsyncExecutionParams, unknown, Output<TOutput>>>;
+    /**
+     * Prepares to execute this canvas in batch.
+     *
+     * @param params - The parameters for the batch.
+     * @param params.pollingInterval - The interval between polling attempts.
+     * @param params.pollingTimeout - The timeout for the batch.
+     * @param params.webhookUrl - The webhook URL for the batch.
+     *
+     * @example
+     * ```typescript
+     * const batch = canvas.createBatch({
+     *   pollingInterval: '1s',
+     *   pollingTimeout: '1m',
+     *   webhookUrl: 'https://example.com/webhook',
+     * })
+     *
+     * batch.add({
+     *   referenceId: crypto.randomUUID(), // Optional
+     *   variables: { query: 'Hello' },
+     * })
+     *
+     * const execution = await batch.execute()
+     * const result = await execution.result
+     * const resultFile = await execution.downloadOutputFile()
+     * ```
+     *
+     * @returns The batch instance that can be used to manage the batch.
+     */
+    createBatch(params?: BatchParams): Batch<Output<TInput>, Output<TOutput>>;
 }
 
 /**
@@ -1816,4 +2742,4 @@ declare class TelaSDK extends BaseClient {
  */
 declare function createTelaClient(opts: TelaSDKOptions): TelaSDK;
 
-export { APIError, AuthenticationError, AuthorizationError, BadRequestError, BaseClient, type BaseClientOptions, type BaseTelaFileOptions, ConflictApiKeyAndJWTError, ConflictError, ConnectionError, ConnectionTimeout, EmptyFileError, ExecutionFailedError, ExecutionNotStartedError, FileUploadError, type HTTPMethods, InternalServerError, InvalidExecutionModeError, InvalidFileURL, MissingApiKeyOrJWTError, NotFoundError, RateLimitError, type RequestOptions, type SchemaBuilder, TelaError, TelaFile, type TelaFileInput, type TelaFileOptions, type TelaFileOptionsWithMimeType, TelaFileSchema, TelaSDK, type TelaSDKOptions, UnprocessableEntityError, UserAbortError, createTelaClient, toError };
+export { APIError, AuthenticationError, AuthorizationError, BadRequestError, BaseClient, type BaseClientOptions, type BaseTelaFileOptions, BatchExecutionFailedError, ConflictApiKeyAndJWTError, ConflictError, ConnectionError, ConnectionTimeout, EmptyFileError, ExecutionFailedError, ExecutionNotStartedError, FileUploadError, type HTTPMethods, InternalServerError, InvalidExecutionModeError, InvalidFileURL, MissingApiKeyOrJWTError, NotFoundError, RateLimitError, type RequestOptions, type SchemaBuilder, TelaError, TelaFile, type TelaFileInput, type TelaFileOptions, type TelaFileOptionsWithMimeType, TelaFileSchema, TelaSDK, type TelaSDKOptions, UnprocessableEntityError, UserAbortError, createTelaClient, toError };