@meistrari/tela-sdk-js 1.0.2 → 2.1.0

package/dist/index.d.cts

@@ -1,3 +1,16 @@
+import * as _zod from 'zod';
+import _zod__default, { ZodError, z } from 'zod';
+import Emittery from 'emittery';
+
+/**
+ * Base HTTP client with retry logic, request/response transformation, and streaming support.
+ *
+ * This module provides the abstract BaseClient class that handles all HTTP communication
+ * with the Tela API, including automatic field transformation, retry logic, timeout handling,
+ * and Server-Sent Events streaming.
+ *
+ * @module Core
+ */
 type HTTPMethods = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 type RequestOptions<Req = unknown | Record<string, unknown>> = {
     method?: HTTPMethods;
@@ -15,6 +28,11 @@ interface BaseClientOptions {
     maxRetries?: number;
     timeout?: number;
 }
+/**
+ * Abstract base HTTP client with retry logic and request/response transformation.
+ *
+ * @category Client
+ */
 declare abstract class BaseClient {
     baseURL: string;
     maxRetries: number;
@@ -23,7 +41,8 @@ declare abstract class BaseClient {
     constructor({ baseURL, maxRetries, timeout }: BaseClientOptions);
     protected createHeaders(opts?: Record<string, string>): Headers;
     protected getUserAgent(): string;
-    protected getAuthHeaders(): Record<string, string>;
+    protected abstract getAuthHeaders(): Record<string, string>;
+    abstract get authToken(): string;
     get<Req, Res>(path: string, opts?: RequestOptions<Req>): Promise<Res>;
     post<Req, Res>(path: string, opts?: RequestOptions<Req>): Promise<Res>;
     put<Req, Res>(path: string, opts?: RequestOptions<Req>): Promise<Res>;
@@ -45,23 +64,92 @@ declare abstract class BaseClient {
     protected stringifyQuery(query: Record<string, unknown>): string;
 }
 
+/**
+ * Error classes and exception handling for the Tela SDK.
+ *
+ * This module provides all custom error classes used throughout the SDK,
+ * including API errors, authentication errors, file errors, and execution errors.
+ *
+ * @module Core
+ */
+/**
+ * Base error class for all Tela SDK errors.
+ *
+ * @category Errors
+ */
 declare class TelaError extends Error {
 }
+/**
+ * Thrown when both API key and JWT are provided.
+ *
+ * @category Errors
+ */
 declare class ConflictApiKeyAndJWTError extends TelaError {
     constructor();
 }
+/**
+ * Thrown when neither API key nor JWT is provided.
+ *
+ * @category Errors
+ */
 declare class MissingApiKeyOrJWTError extends TelaError {
     constructor();
 }
+/**
+ * Thrown when attempting to upload an empty file.
+ *
+ * @category Errors
+ */
 declare class EmptyFileError extends TelaError {
     constructor();
 }
+/**
+ * Thrown when an invalid file URL is provided.
+ *
+ * @category Errors
+ */
 declare class InvalidFileURL extends TelaError {
     constructor(url: string);
 }
+/**
+ * Thrown when file upload to vault storage fails.
+ *
+ * @category Errors
+ */
 declare class FileUploadError extends TelaError {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+/**
+ * Thrown when accessing execution result before execution has started.
+ *
+ * @category Errors
+ */
+declare class ExecutionNotStartedError extends TelaError {
+    constructor();
+}
+/**
+ * Thrown when invalid execution mode parameters are provided.
+ *
+ * @category Errors
+ */
+declare class InvalidExecutionModeError extends TelaError {
     constructor(message: string);
 }
+/**
+ * Thrown when canvas execution fails on the server.
+ *
+ * @category Errors
+ */
+declare class ExecutionFailedError extends TelaError {
+    readonly rawOutput: Record<string, any>;
+    constructor(rawOutput: Record<string, any>);
+}
+/**
+ * Base class for all API-related errors.
+ *
+ * @category Errors
+ */
 declare class APIError extends TelaError {
     readonly statusCode: number | undefined;
     readonly error: any;
@@ -111,11 +199,22 @@ declare class RateLimitError extends APIError {
 declare class InternalServerError extends APIError {
     readonly statusCode = 500;
 }
+declare function toError(err: any): Error;
+
+/**
+ * File handling module for TelaFile wrapper and file upload operations.
+ *
+ * This module provides the TelaFile class for handling various file input types
+ * (URLs, Blobs, Streams, Buffers, vault references) with support for MIME types,
+ * page ranges, and file uploads to vault storage.
+ *
+ * @module Resources
+ */
 
 /**
  * Configuration options for `TelaFile`.
  */
-type TelaFileOptions = {
+type BaseTelaFileOptions = {
     /**
      * Defines the page range of the document to be processed.
      *
@@ -133,12 +232,22 @@ type TelaFileOptions = {
      * Defines the parser provider to be used for the file.
      */
     parserType?: string;
+    /**
+     * Defines the name of the file.
+     * If content is an instance of File or Blob, this will override the `name` property of the content.
+     */
+    name?: string;
 };
+type TelaFileOptionsWithMimeType = BaseTelaFileOptions & {
+    mimeType: string;
+};
+type TelaFileOptions = BaseTelaFileOptions | TelaFileOptionsWithMimeType;
 /**
  * Represents the possible types for a file input,
  * which can be a URL string, Uint8Array, ReadableStream, ReadStream, Blob, or File.
  */
 type TelaFileInput = string | Uint8Array | ReadableStream | Blob | File;
+declare function TelaFileSchema(): _zod__default.ZodCustom<TelaFile, TelaFile>;
 /**
  * Represents a file with support for various types including URLs, binary data, streams, and Blobs.
  *
@@ -148,7 +257,7 @@ type TelaFileInput = string | Uint8Array | ReadableStream | Blob | File;
  * const urlFile = new TelaFile("https://example.com/file.png", { range: { start: 0, end: 1024 } })
  *
  * // Using a Uint8Array (buffer)
- * const buffer = new Uint8Array([/* binary data * /])
+ * const buffer = new Uint8Array(['binary data...'])
  * const bufferFile = new TelaFile(buffer)
  *
  * // Using a ReadStream
@@ -172,12 +281,29 @@ type TelaFileInput = string | Uint8Array | ReadableStream | Blob | File;
  * // Using a File (in browser environments)
  * const file = new File(['file content'], 'filename.txt', { type: 'text/plain' })
  * const fileInstance = new TelaFile(file)
+ *
+ * // Using multiple files in a collection
+ * const files = [
+ *   new TelaFile("https://example.com/file1.pdf", { range: [0, 1] }),
+ *   new TelaFile("https://example.com/file2.pdf", { range: [1, 2] })
+ * ]
+ * // Pass the array of files to a variable
+ * const result = await tela.completions.create({
+ *   canvasId: "your-canvas-id",
+ *   variables: {
+ *     documents: files
+ *   }
+ * })
  * ```
+ *
+ * @category File
  */
 declare class TelaFile {
     private _file;
     private _options;
     private _size;
+    private _mimeType;
+    private _name;
     /**
      * Creates an instance of `TelaFile`.
      *
@@ -186,7 +312,10 @@ declare class TelaFile {
      * @throws {InvalidFileURL} If the provided URL is not valid.
      * @throws {EmptyFileError} If the provided file is empty.
      */
-    constructor(file: string | Uint8Array | ReadableStream | Blob | File, options?: TelaFileOptions);
+    constructor(file: Blob | File | string, options?: BaseTelaFileOptions);
+    constructor(file: Uint8Array | ReadableStream, options: TelaFileOptionsWithMimeType);
+    static create(file: Blob | File | string, options?: BaseTelaFileOptions): TelaFile;
+    static create(file: Uint8Array | ReadableStream, options: TelaFileOptionsWithMimeType): TelaFile;
     /**
      * Retrieves the options provided during instantiation.
      *
@@ -199,12 +328,30 @@ declare class TelaFile {
      * @returns `true` if the file source is a valid URL string, otherwise `false`.
      */
     get isURL(): boolean;
+    /**
+     * Determines whether the file source is a valid Vault reference.
+     *
+     * @returns `true` if the file source is a valid Vault reference, otherwise `false`.
+     */
+    get isVaultReference(): boolean;
     /**
      * Gets the size of the file in bytes.
      *
      * @returns The size of the file if available, otherwise `null`.
      */
     get size(): number | null;
+    /**
+     * Gets the name of the file.
+     *
+     * @returns The name of the file if available, otherwise `null`.
+     */
+    get name(): string | null;
+    /**
+     * Gets the type of the file.
+     *
+     * @returns The type of the file if available, otherwise `null`.
+     */
+    get type(): string | null;
     /**
      * Retrieves the content of the file in a format suitable for uploading.
      *
@@ -229,170 +376,26 @@ declare class TelaFile {
      * @returns `true` if the URL is valid, otherwise `false`.
      */
     private isValidURL;
-}
-/**
- * Creates a new `TelaFile` instance from the provided file input.
- *
- * @param file - The file input to create a `TelaFile` instance from.
- * @returns A new `TelaFile` instance.
- */
-declare function createTelaFile(file: TelaFileInput, options?: TelaFileOptions): TelaFile;
-
-/**
- * Base class for all resources.
- */
-declare class Resource {
-    protected _client: BaseClient;
-    constructor(client: BaseClient);
-}
-
-/**
- * Represents a stream of items that can be asynchronously iterated over.
- */
-declare class Stream<Item> implements AsyncIterable<Item> {
-    private iterator;
-    /**
-     * The AbortController associated with this stream.
-     */
-    controller: AbortController;
-    /**
-     * Creates a new Stream instance.
-     *
-     * @param iterator - A function that returns an AsyncIterator<Item>.
-     * @param controller - The AbortController for this stream.
-     */
-    constructor(iterator: () => AsyncIterator<Item>, controller: AbortController);
-    /**
-     * Creates a Stream from a server-sent events (SSE) Response.
-     *
-     * @param response - The Response object containing the SSE data.
-     * @param controller - The AbortController for this stream.
-     * @returns A new Stream instance.
-     * @throws {Error} If the stream is consumed more than once.
-     * @throws {APIError} If the SSE data contains an error.
-     */
-    static fromSSEResponse<Item>(response: Response, controller: AbortController): Stream<Item>;
-    /**
-     * Creates a Stream from a newline-separated ReadableStream where each item is a JSON value.
-     *
-     * @param readableStream - The ReadableStream containing newline-separated JSON data.
-     * @param controller - The AbortController for this stream.
-     * @returns A new Stream instance.
-     * @throws {Error} If the stream is consumed more than once.
-     */
-    static fromReadableStream<Item>(readableStream: ReadableStream, controller: AbortController): Stream<Item>;
-    /**
-     * Implements the AsyncIterable interface, allowing the Stream to be used in a for-await-of loop.
-     *
-     * @returns An AsyncIterator for the stream items.
-     */
-    [Symbol.asyncIterator](): AsyncIterator<Item>;
-    /**
-     * Splits the stream into two streams which can be independently read from at different speeds.
-     *
-     * @returns A tuple containing two new Stream instances.
-     */
-    tee(): [Stream<Item>, Stream<Item>];
     /**
-     * Converts this stream to a newline-separated ReadableStream of JSON stringified values.
-     * The resulting stream can be converted back to a Stream using `Stream.fromReadableStream()`.
+     * Checks if the provided string is a valid Vault reference.
      *
-     * @returns A ReadableStream containing newline-separated JSON data.
+     * @param url - The Vault reference string to validate.
+     * @returns `true` if the Vault reference is valid, otherwise `false`.
      */
-    toReadableStream(): ReadableStream;
+    private isValidVaultReference;
 }
 
 /**
- * Manages chat completion operations.
+ * Canvas execution module for managing canvas execution lifecycle and modes.
  *
- * Provides methods to create chat completions, handle streaming responses,
- * and manage file uploads associated with chat completions.
+ * 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.
  *
- * @example
- * ```typescript
- * const tela = new TelaSDK({
- *   apiKey: 'your-api-key',
- * });
- * const response = await tela.completions.create({
- *   canvasId: "your-canvas-id",
- *   messages: [{ role: "user", content: "Hello!" }],
- * });
- * console.log(response.choices[0].message.content);
- * ```
+ * @module Resources
  */
-declare class ChatCompletions extends Resource {
-    /**
-     * Creates a chat completion with various input options and response formats.
-     *
-     * This method supports synchronous responses, streaming responses, and webhook-based asynchronous processing.
-     *
-     * @param body - The parameters for creating a chat completion.
-     * @param opts - Additional request options.
-     * @returns A Promise that resolves to either a stream of chat completion responses,
-     *          a single chat completion response, or a webhook response, depending on the input parameters.
-     *
-     * @example
-     * ```typescript
-     * // Synchronous response
-     * const response = await tela.completions.create({
-     *   canvasId: "your-canvas-id",
-     *   messages: [{ role: "user", content: "Tell me a joke." }],
-     * });
-     *
-     * // Streaming response
-     * const stream = await tela.completions.create({
-     *   canvasId: "your-canvas-id",
-     *   messages: [{ role: "user", content: "Tell me a story." }],
-     *   stream: true,
-     * });
-     *
-     * // Webhook response
-     * const webhookResponse = await tela.completions.create({
-     *   canvasId: "your-canvas-id",
-     *   messages: [{ role: "user", content: "Generate a report." }],
-     *   webhookUrl: "https://example.com/webhook",
-     * });
-     * ```
-     */
-    create<Variables = ChatCompletionVariables, CompletionContent = string>(body: ChatCompletionCreateWebhookParams<Variables>, opts?: RequestOptions<ChatCompletionCreateParams<Variables>>): Promise<ChatCompletionWebhookResponse<CompletionContent>>;
-    create<Variables = ChatCompletionVariables, CompletionContent = string>(body: CompletionCreateParamsNonStreaming<Variables>, opts?: RequestOptions<ChatCompletionCreateParams<Variables>>): Promise<ChatCompletionCreateResponse<CompletionContent>>;
-    create<Variables = ChatCompletionVariables, CompletionContent = string>(body: CompletionCreateParamsStreaming<Variables>, opts?: RequestOptions<ChatCompletionCreateParams<Variables>>): Promise<Stream<ChatCompletionCreateStreamingResponse<CompletionContent>>>;
-    create<Variables = ChatCompletionVariables, CompletionContent = string>(body: ChatCompletionCreateParamsBase<Variables>, opts?: RequestOptions<ChatCompletionCreateParams<Variables>>): Promise<Stream<ChatCompletionCreateStreamingResponse<CompletionContent>> | ChatCompletionCreateResponse<CompletionContent> | ChatCompletionWebhookResponse<CompletionContent>>;
-    /**
-     * Uploads a file and returns its URL and options.
-     *
-     * This is used internally to handle file uploads associated with chat completions.
-     *
-     * @param file - The TelaFile to be uploaded.
-     * @returns A Promise that resolves to an object containing the file URL and options.
-     * @throws {FileUploadError} If the file upload fails.
-     *
-     * @example
-     * ```typescript
-     * const file = new TelaFile({ /* file options *\/ });
-     * const uploadedFile = await this.uploadFile(file);
-     * console.log(uploadedFile.file_url);
-     * ```
-     */
-    private uploadFile;
-}
-type ChatCompletionVariablesValue = string | number | boolean | TelaFile;
-/**
- * Represents the variables available in the canvas.
- * Keys are strings, and values can be strings, numbers, booleans, or TelaFile instances.
- */
-type ChatCompletionVariables = Record<string, ChatCompletionVariablesValue>;
-/**
- * Represents the processed variables with file URLs.
- * Similar to ChatCompletionVariables, but TelaFile instances are replaced with their URLs.
- */
-type ChatCompletionVariablesWithFileURL = Record<string, string | number | boolean | {
-    fileUrl: string;
-}>;
-/**
- * Base parameters for creating a chat completion.
- */
-interface ChatCompletionCreateParamsBase<Variables = ChatCompletionVariables> {
+
+interface BaseExecutionParams {
     /**
      * The version ID of the canvas to use for this chat completion.
      * If not provided, the latest version of the specified canvas will be used.
@@ -409,15 +412,11 @@ interface ChatCompletionCreateParamsBase<Variables = ChatCompletionVariables> {
      */
     applicationId?: string;
     /**
-     * The URL to receive a webhook notification when the chat completion is finished.
-     * If provided, the completion will be processed asynchronously.
-     */
-    webhookUrl?: string | null | undefined;
-    /**
-     * Variables to be passed to the canvas for this chat completion.
-     * These can be used to customize the behavior of the canvas for this specific request.
+     * Optional label for this execution when using applicationId.
+     * This label can be used to identify or categorize the execution.
+     * Note: This field is only applicable when applicationId is provided.
      */
-    variables?: Variables;
+    label?: string;
     /**
      * An array of previous messages in the conversation.
      * Each message should have a 'role' (e.g., 'user', 'assistant') and 'content'.
@@ -459,327 +458,1091 @@ interface ChatCompletionCreateParamsBase<Variables = ChatCompletionVariables> {
                 required?: string[];
             };
         }>;
-        /**
-         * Configuration for generating structured output.
-         */
-        structuredOutput?: {
-            /**
-             * Whether to enable structured output for this completion.
-             */
-            enabled: boolean;
-            /**
-             * The schema defining the structure of the output.
-             * This is used when structured output is enabled.
-             */
-            schema?: {
-                properties: Record<string, unknown>;
-                type: 'object';
-                title: string;
-                description: string;
-                required: string[];
-            };
-        };
     };
+    /**
+     * Whether to skip Zod schema validation on execution results.
+     * When true, results are typecast to the expected output type without validation.
+     * @default false
+     */
+    skipResultValidation?: boolean;
+    /**
+     * Optional array of tags to associate with this execution.
+     * Tags can be used for filtering, categorization, and analytics.
+     */
+    tags?: string[];
 }
 /**
- * Parameters for creating a streaming chat completion.
+ * Configuration for asynchronous canvas execution with polling.
+ * The execution starts immediately but results must be retrieved via polling.
  */
-interface CompletionCreateParamsStreaming<T> extends ChatCompletionCreateParamsBase<T> {
+interface AsyncExecutionParams extends BaseExecutionParams {
     /**
-     * Whether the response should be streamed.
+     * Enable asynchronous execution mode.
+     * @default false
      */
-    stream: true;
+    async?: true;
+    /**
+     * Optional webhook URL to receive completion notifications.
+     */
+    webhookUrl?: string;
     /**
-     * The webhook URL, if you want to receive a webhook when the completion is completed.
+     * Time in milliseconds between polling attempts.
+     * @default 1000
      */
-    webhookUrl?: undefined | null;
+    pollingInterval?: number;
+    /**
+     * Maximum time in milliseconds to wait for completion before timing out.
+     * @default 60000
+     */
+    pollingTimeout?: number;
+    /**
+     * Stream mode is not available for async executions.
+     */
+    stream?: never;
 }
 /**
- * Parameters for creating a non-streaming chat completion.
+ * Configuration for streaming canvas execution.
+ * Results are returned incrementally as they're generated.
  */
-interface CompletionCreateParamsNonStreaming<T> extends ChatCompletionCreateParamsBase<T> {
+interface StreamExecutionParams extends BaseExecutionParams {
+    /**
+     * Enable streaming mode.
+     */
+    stream: true;
     /**
-     * Whether the response should be streamed.
+     * Async mode is not available for streaming executions.
      */
-    stream?: false | undefined | null;
+    async?: false;
+    /**
+     * Webhook URL is not available for streaming executions.
+     */
+    webhookUrl?: never;
 }
 /**
- * Parameters for creating a chat completion with a webhook.
+ * Configuration for synchronous canvas execution.
+ * The execution waits for the complete result before returning.
  */
-interface ChatCompletionCreateWebhookParams<T> extends CompletionCreateParamsNonStreaming<T> {
+interface SyncExecutionParams extends BaseExecutionParams {
+    /**
+     * Disable asynchronous execution mode.
+     * @default false
+     */
+    async?: false;
     /**
-     * The webhook URL, if you want to receive a webhook when the completion is completed.
+     * Webhook URL is not available for synchronous executions.
      */
-    webhookUrl: string;
+    webhookUrl?: never;
+    /**
+     * Stream mode is not available for synchronous executions.
+     */
+    stream?: never;
 }
 /**
- * Union type for all possible chat completion creation parameters.
+ * Status of a canvas execution.
+ *
+ * Possible values:
+ * - `created` - Async execution queued on server (initial state)
+ * - `running` - Async execution actively processing
+ * - `succeeded` - Execution completed successfully (after validation)
+ * - `failed` - Execution failed (API error, validation error, or server failure)
+ * - `streaming` - Stream execution in progress
+ *
+ * @see {@link CanvasExecution.status} for status transitions and timing
+ */
+type ExecutionStatus = 'succeeded' | 'failed' | 'running' | 'created' | 'streaming';
+type AsyncCompletionCreateResult = {
+    id: string;
+    status: ExecutionStatus;
+    input_content: {
+        files: Array<any>;
+        messages: Array<any>;
+        variables: {
+            body: string;
+            title: string;
+        };
+    };
+    output_content: null;
+    raw_input: {
+        async: boolean;
+        canvas_id: string;
+        variables: {
+            body: string;
+            title: string;
+        };
+    };
+    raw_output: any;
+    compatibility_date: string;
+    metadata: Array<{
+        promptVersion: {
+            modelConfigurations: {
+                type: string;
+                model: string;
+                temperature: number;
+                structuredOutput: {
+                    schema: {
+                        type: string;
+                        title: string;
+                        required: Array<string>;
+                        properties: {
+                            clickbaitMessages: {
+                                id: string;
+                                type: string;
+                                items: {
+                                    id: string;
+                                    type: string;
+                                };
+                                description: string;
+                            };
+                        };
+                        description: string;
+                    };
+                    enabled: boolean;
+                };
+            };
+            variablesDefinitions: Array<{
+                name: string;
+                type: string;
+                required: boolean;
+            }>;
+        };
+    }>;
+    credits_used: number;
+    prompt_id: string;
+    prompt_version_id: string;
+    prompt_application_id: any;
+    workspace_id: string;
+    created_at: string;
+    updated_at: string;
+    deleted_at: any;
+};
+/**
+ * Raw API response type. Represents the unprocessed response from the Tela API.
+ * This type will be refined in future versions with proper typing.
  */
-type ChatCompletionCreateParams<T> = CompletionCreateParamsStreaming<T> | CompletionCreateParamsNonStreaming<T> | ChatCompletionCreateWebhookParams<T>;
+type RawAPIResult = any;
 /**
- * Response structure for a created chat completion.
+ * Result returned when polling for asynchronous execution status.
+ *
+ * @template T - The type of the output content.
  */
-type ChatCompletionCreateResponse<T> = {
+type AsyncCompletionPollingResult<T> = {
     /**
-     * The ID of the completion.
+     * Unique identifier for the execution.
      */
     id: string;
     /**
-     * The object of the completion.
+     * Current status of the execution.
      */
-    object: string;
+    status: ExecutionStatus;
     /**
-     * The created time of the completion.
+     * The output content when execution succeeds.
      */
-    created: number;
+    outputContent: {
+        /**
+         * The actual content result.
+         */
+        content: T;
+    };
     /**
-     * The choices of the completion.
+     * Raw output data from the execution.
      */
-    choices: Array<{
-        message: {
-            role: string;
-            content: T;
-        };
-    }>;
+    rawOutput: Record<string, any>;
+};
+/**
+ * Union type of all possible execution parameter configurations.
+ */
+type ExecutionParams = AsyncExecutionParams | StreamExecutionParams | SyncExecutionParams;
+/**
+ * Conditional type that determines the return type based on execution parameters.
+ *
+ * @category Canvas
+ *
+ * @template TParams - The execution parameters type.
+ * @template TOutput - The output type.
+ * @returns AsyncGenerator for streaming executions, Promise otherwise.
+ */
+type CanvasExecutionResult<TParams, TOutput = unknown> = TParams extends StreamExecutionParams ? AsyncGenerator<Partial<TOutput>> : Promise<TOutput>;
+type CanvasExecutionEvents<TOutput> = {
+    poll: AsyncCompletionPollingResult<TOutput>;
+    success: TOutput;
+    error: ExecutionFailedError;
+    statusChange: ExecutionStatus;
 };
 /**
- * Response structure for a chat completion streaming response.
+ * Manages the execution lifecycle of a canvas.
+ *
+ * Handles synchronous, asynchronous (with polling), and streaming execution modes.
+ * Automatically uploads TelaFile instances and validates results based on output schema.
+ *
+ * ## Status Tracking
+ *
+ * The execution status can be accessed via the `status` property and tracks the lifecycle:
+ *
+ * - **Sync executions**: `succeeded` or `failed` (set after validation completes)
+ * - **Async executions**: `created` → `running` → `succeeded` or `failed` (updated during polling)
+ * - **Stream executions**: `streaming` (set when stream starts)
+ *
+ * Status is set to `failed` when:
+ * - API request fails
+ * - Validation fails (for both sync and async)
+ * - Polling reports failure status
+ *
+ * Status is set to `succeeded` only after:
+ * - API request succeeds AND
+ * - Output validation passes (if schema provided)
+ *
+ * @category Canvas
+ *
+ * @typeParam TParams - The execution parameters type
+ * @typeParam TInput - The input variables type
+ * @typeParam TOutput - The output result type
+ *
+ * @fires poll - Emitted during async polling with current status and output (async executions only)
+ * @fires success - Emitted when execution completes successfully with the final result
+ * @fires error - Emitted when execution fails (only if error listeners are registered, otherwise throws)
+ * @fires statusChange - Emitted when execution status transitions to a new state
+ *
+ * @example
+ * ```typescript
+ * const execution = await canvas.execute({ query: 'test' }, { async: true })
+ *
+ * // Track status changes
+ * execution.on('statusChange', (status) => {
+ *   console.log(`Status: ${status}`) // created → running → succeeded
+ * })
+ *
+ * // Access current status at any time
+ * console.log(execution.status) // 'running'
+ *
+ * const result = await execution.result
+ * console.log(execution.status) // 'succeeded'
+ * ```
  */
-type ChatCompletionCreateStreamingResponse<T> = {
+declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionParams, TInput = unknown, TOutput = unknown> extends Emittery<CanvasExecutionEvents<TOutput>> {
+    private _id;
+    private _status;
+    private readonly _variables;
+    private readonly _params;
+    private readonly _client;
+    private readonly _outputSchema;
+    private readonly _skipResultValidation;
+    private readonly _abortController;
+    private _resultPromise;
+    private _stream;
+    private _rawResultValue;
     /**
-     * The ID of the completion.
+     * Creates a new canvas execution instance.
+     *
+     * @param variables - Input variables to be passed to the canvas template.
+     * @param params - Execution parameters controlling sync/async/stream behavior.
+     * @param outputSchema - Zod schema or object schema for validating/parsing output.
+     * @param client - HTTP client instance for making API requests.
      */
-    id: string;
+    constructor(variables: TInput, params: TParams | undefined, outputSchema: _zod__default.ZodType | Record<string, unknown>, client: BaseClient);
     /**
-     * The object of the completion.
+     * Fetches an existing asynchronous execution by its ID.
+     *
+     * This method retrieves the current state of an async execution and creates a new
+     * CanvasExecution instance with the fetched data. Only async executions can be
+     * fetched, as they are the only ones with persistent UUIDs on the server.
+     *
+     * @param id - The UUID of the async execution to fetch.
+     * @param outputSchema - Zod schema or object schema for validating/parsing output.
+     * @param client - HTTP client instance for making API requests.
+     * @param options - Optional configuration for polling behavior.
+     * @param options.pollingInterval - Time in milliseconds between polling attempts (default: 1000).
+     * @param options.pollingTimeout - Maximum time in milliseconds to wait for completion (default: 60000).
+     * @throws {InvalidExecutionModeError} If the provided ID is not a valid UUID.
+     * @returns A promise resolving to a CanvasExecution instance with the fetched state.
+     *
+     * @example
+     * ```typescript
+     * const execution = await CanvasExecution.fetch(
+     *   'execution-uuid',
+     *   z.object({ result: z.string() }),
+     *   client,
+     *   { pollingInterval: 2000, pollingTimeout: 120000 }
+     * )
+     * console.log(execution.status) // 'running' or 'succeeded' or 'failed'
+     * ```
      */
-    object: string;
+    static fetch<TOutput = unknown>(id: string, outputSchema: _zod__default.ZodType | Record<string, unknown>, client: BaseClient, options?: {
+        pollingInterval?: number;
+        pollingTimeout?: number;
+    }): Promise<CanvasExecution<AsyncExecutionParams, unknown, TOutput>>;
     /**
-     * The created time of the completion.
+     * Gets the unique execution ID assigned by the server.
+     *
+     * Note: Streaming executions do not have an ID as they don't create a tracked execution on the server.
+     *
+     * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+     * @throws {InvalidExecutionModeError} If called on a streaming execution (streams don't have IDs).
+     * @returns The execution ID.
      */
-    created: number;
+    get id(): string;
     /**
-     * The model of the completion.
+     * Gets the latest known status of the execution.
+     *
+     * Status values and transitions:
+     * - **Sync**: `succeeded` (after validation) or `failed` (on any error)
+     * - **Async**: `created` → `running` → `succeeded` or `failed`
+     * - **Stream**: `streaming` (once started)
+     *
+     * **Important:** Status is set to `succeeded` only after successful validation.
+     * If validation fails, status will be `failed` even if the API request succeeded.
+     *
+     * Use the `statusChange` event to track status transitions in real-time.
+     *
+     * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+     * @returns The current status of the execution.
+     *
+     * @example
+     * ```typescript
+     * const execution = await canvas.execute({ query: 'test' }, { async: true })
+     * console.log(execution.status) // 'created'
+     *
+     * await execution.result
+     * console.log(execution.status) // 'succeeded' or 'failed'
+     * ```
      */
-    model: string;
+    get status(): ExecutionStatus;
     /**
-     * The choices of the completion.
+     * Sets the status of the execution.
+     *
+     * @param status - The new status of the execution.
+     * @private
      */
-    choices: Array<{
-        delta: {
-            role: string | null;
-            content: string | null;
-            functionCall: {
-                name: string | null;
-                arguments: string | null;
-            } | null;
-        };
-        finishReason: string | null;
-        index: number;
-        logprobs: number | null;
-    }>;
+    private set status(value);
+    /**
+     * Gets the input variables provided to this execution.
+     *
+     * @returns The variables object.
+     */
+    get variables(): TInput;
     /**
-     * The message of the completion.
+     * Gets the execution parameters configured for this instance.
+     *
+     * @returns The execution parameters or undefined.
      */
-    message: {
-        role: string;
-        content: string | null;
-        functionCall: {
-            name: string | null;
-            arguments: string | null;
-        } | null;
-        toolCalls: Array<{
-            name: string;
-            arguments: string;
-        }>;
-        structuredContent: T;
-    };
-};
+    get params(): TParams;
+    /**
+     * Checks if this execution is configured for asynchronous processing.
+     *
+     * @returns True if async mode is enabled.
+     */
+    get isAsync(): boolean;
+    /**
+     * Checks if this execution is configured for synchronous processing.
+     *
+     * @returns True if sync mode is enabled (not async).
+     */
+    get isSync(): boolean;
+    /**
+     * Checks if this execution is configured for streaming responses.
+     *
+     * @returns True if stream mode is enabled.
+     */
+    get isStream(): boolean;
+    /**
+     * Gets the raw API response without any processing or validation.
+     * Automatically starts execution and waits for completion (including polling for async executions).
+     *
+     * For sync executions, returns the complete API response.
+     * For async executions, returns the polling response with status and output.
+     *
+     * @throws {InvalidExecutionModeError} If called on a streaming execution.
+     * @returns A promise resolving to the raw API result.
+     */
+    get rawResult(): Promise<RawAPIResult>;
+    /**
+     * Type guard to check if params indicate async execution.
+     *
+     * @param params - Execution parameters to check.
+     * @returns True if params indicate async mode.
+     */
+    private _isAsync;
+    /**
+     * Starts the execution based on configured parameters.
+     * Routes to the appropriate execution method (sync, async, or stream).
+     *
+     * @returns A promise or async generator depending on execution mode.
+     */
+    start(): Promise<CanvasExecutionResult<TParams, TOutput>> | AsyncGenerator<Partial<TOutput>, any, any> | Promise<AsyncGenerator<Partial<TOutput>, any, any>> | Promise<AsyncCompletionCreateResult>;
+    /**
+     * Gets the execution result. For async executions, automatically starts polling.
+     * For sync executions, returns the result promise. For streams, returns the generator.
+     *
+     * @returns The execution result as a promise or async generator.
+     */
+    get result(): CanvasExecutionResult<TParams, TOutput>;
+    /**
+     * Cancels the ongoing execution by aborting all active requests and polling operations.
+     */
+    cancel(): void;
+    /**
+     * Starts polling for the execution result without waiting for the promise to resolve.
+     * This allows users to track execution progress via events rather than awaiting a promise.
+     *
+     * The following events will be emitted during polling:
+     * - `statusChange`: Emitted when the execution status changes (e.g., 'created' → 'running' → 'succeeded')
+     * - `poll`: Emitted on each polling attempt with the server response
+     * - `success`: Emitted when the execution completes successfully with the final result
+     * - `error`: Emitted if the execution fails
+     *
+     * **Important:** Events are only emitted while polling is active. You must either call `poll()` or
+     * await `execution.result` to start polling. Simply setting up event listeners without starting
+     * polling will not trigger any events.
+     *
+     * **Note:** If the execution has already completed (succeeded or failed) when fetched, the `success`
+     * and `error` events will not fire since no polling is needed. Check the `status` property and
+     * access the `result` directly for already-completed executions.
+     *
+     * @throws {InvalidExecutionModeError} If called on a non-async execution (sync or stream).
+     * @throws {ExecutionNotStartedError} If the execution has not been started yet (no ID assigned).
+     *
+     * @example
+     * ```typescript
+     * const execution = await canvas.getExecution('execution-id')
+     *
+     * // Check if already completed
+     * if (execution.status === 'succeeded' || execution.status === 'failed') {
+     *   // Access result directly - events won't fire
+     *   const result = await execution.result
+     *   console.log('Already completed:', result)
+     * } else {
+     *   // Still running - set up events and start polling
+     *   execution.on('statusChange', (status) => {
+     *     console.log('Status:', status)
+     *   })
+     *
+     *   execution.on('success', (result) => {
+     *     console.log('Completed:', result)
+     *   })
+     *
+     *   execution.on('error', (error) => {
+     *     console.error('Failed:', error)
+     *   })
+     *
+     *   // Start polling without waiting
+     *   execution.poll()
+     * }
+     * ```
+     */
+    poll(): void;
+    /**
+     * Builds the base request body shared across all execution types.
+     * Includes messages, overrides, tags, label, and structured output configuration.
+     *
+     * @returns The base request body object.
+     */
+    private get baseBody();
+    /**
+     * Processes variables and uploads any TelaFile instances to the server.
+     * Replaces TelaFile objects with their uploaded URLs while preserving other values.
+     *
+     * @returns A promise resolving to the processed variables object.
+     */
+    private resolveVariables;
+    /**
+     * Initiates a synchronous execution that waits for the complete result.
+     * The result is validated against the output schema if provided.
+     *
+     * @returns A promise resolving to the parsed execution result.
+     */
+    private startSync;
+    /**
+     * Initiates an asynchronous execution that returns immediately with an execution ID.
+     * Results must be retrieved separately via polling using the `result` getter.
+     *
+     * @returns A promise that resolves when the execution is queued.
+     */
+    private startAsync;
+    /**
+     * Initiates a streaming execution that returns results incrementally as they're generated.
+     *
+     * @returns A promise resolving to an async generator yielding result chunks.
+     */
+    private startStream;
+    /**
+     * Polls the server for async execution results at regular intervals.
+     * Continues polling until the execution completes or the timeout is reached.
+     *
+     * @throws {Error} If called on a non-async execution.
+     * @throws {Error} If the execution fails on the server.
+     * @throws {Error} If the polling operation times out.
+     * @returns A promise resolving to the final execution result.
+     */
+    private startPolling;
+    /**
+     * Uploads a file and returns its URL and options.
+     *
+     * This is used internally to handle file uploads associated with chat completions.
+     *
+     * @param file - The TelaFile to be uploaded.
+     * @returns A Promise that resolves to an object containing the file URL and options.
+     * @throws {FileUploadError} If the file upload fails.
+     *
+     * @example
+     * ```typescript
+     * const file = new TelaFile({ /* file options *\/ });
+     * const uploadedFile = await this.uploadFile(file);
+     * console.log(uploadedFile.fileUrl);
+     * ```
+     */
+    private uploadFile;
+    /**
+     * Uploads multiple files and returns their URLs and options.
+     *
+     * This is used internally to handle multiple file uploads associated with chat completions.
+     *
+     * @param files - An array of TelaFile instances to be uploaded.
+     * @returns A Promise that resolves to an array of objects containing file URLs and options.
+     * @throws {FileUploadError} If any file upload fails.
+     */
+    private uploadFiles;
+}
+
+/**
+ * Canvas resource for managing prompt templates and their execution.
+ *
+ * This module provides the core Canvas class for retrieving and executing
+ * prompt templates from the Tela API, with support for schema validation,
+ * type safety, and multiple execution modes.
+ *
+ * @module Resources
+ */
+
 /**
- * Response structure for a chat completion webhook.
- * This interface represents the data sent to the webhook URL when a chat completion is finished.
+ * Represents a variable that can be used in a canvas template.
  */
-interface ChatCompletionWebhookResponse<T> {
+type CanvasVariable = {
     /**
-     * Unique identifier for this chat completion response.
+     * The name of the variable.
      */
-    id: string;
+    name: string;
     /**
-     * The current status of the chat completion.
-     * - 'created': The request has been received but processing hasn't started.
-     * - 'running': The chat completion is currently being processed.
-     * - 'succeeded': The chat completion has finished successfully.
-     * - 'failed': The chat completion encountered an error and couldn't complete.
+     * The type of the variable (e.g., 'string', 'number', 'file').
      */
-    status: 'created' | 'failed' | 'running' | 'succeeded';
+    type: string;
     /**
-     * Contains information about the input provided for this chat completion.
+     * Whether this variable is required for canvas execution.
      */
-    inputContent: {
-        /**
-         * Variables passed to the chat completion, including any file URLs.
-         */
-        variables: ChatCompletionVariablesWithFileURL;
-        /**
-         * Array of messages that were part of the input.
-         */
-        messages: Array<{
-            /**
-             * The role of the message sender (e.g., 'user', 'assistant', 'system').
-             */
-            role: string;
-            /**
-             * The content of the message. Can be a string for text messages,
-             * or an object for more complex content types like images.
-             */
-            content: string | {
-                type: 'text';
-                text: string;
-            } | {
-                type: 'image_url';
-                imageUrl: {
-                    url: string;
-                    detail?: 'auto' | 'high' | 'low';
-                };
-            };
-            /**
-             * Optional. Information about a function call, if applicable.
-             */
-            functionCall?: {
-                name: string;
-                arguments: string;
-            };
-        }>;
+    required: boolean;
+    /**
+     * Description of the variable's purpose.
+     */
+    description: string;
+    /**
+     * Processing options for the variable.
+     */
+    processingOptions: {
         /**
-         * Information about files used in the chat completion.
+         * Whether multimodal content (images, files) is allowed.
          */
-        files: Array<{
-            name: string;
-            usedAt: 'variables' | 'messages';
-            parsedContent: string;
-            url: string;
-            type: 'image' | 'file';
-        }>;
+        allowMultimodal: boolean;
     };
+};
+interface CanvasOptions<TInput, TOutput> {
     /**
-     * Contains the output generated by the chat completion.
+     * Id of the canvas that will be used to create the completion.
      */
-    outputContent: {
-        /**
-         * The role of the entity providing the output.
-         */
-        role: 'system' | 'user' | 'assistant' | 'function';
-        /**
-         * Optional. Information about tool calls made during the completion.
-         */
-        toolCalls?: Array<{
-            name: string;
-            arguments: string;
-        }>;
-        /**
-         * Optional. Additional information about the completion process.
-         */
-        information?: {
-            duration: number;
-            cost?: number;
-            inputTokens?: number;
-            outputTokens?: number;
-        };
-        /**
-         * Indicates whether the output has a structured format.
-         */
-        hasStructuredOutput?: boolean;
-        /**
-         * The main content of the chat completion output.
-         */
-        content: T;
-        /**
-         * Optional. The input messages in a string format.
-         */
-        inputMessages?: string | undefined;
+    id?: string;
+    /**
+     * Id of the version of the canvas. If not provided, the latest promoted version will be used.
+     */
+    versionId?: string;
+    /**
+     * Id of the application that the canvas belongs to.
+     */
+    applicationId?: string;
+    /**
+     * Name of the canvas. Useful for debugging.
+     */
+    name?: string;
+    /**
+     * Input schema of the canvas.
+     */
+    input?: SchemaFunction<TInput>;
+    /**
+     * Output schema of the canvas.
+     */
+    output?: SchemaFunction<TOutput>;
+    /**
+     * Base client for making requests to the Tela API.
+     */
+    client: BaseClient;
+    /**
+     * Variables of the canvas.
+     */
+    variables: Array<CanvasVariable>;
+}
+type CanvasGetOptions<TInput extends ZodTypeOrRecord, TOutput extends ZodTypeOrRecord> = Omit<CanvasOptions<TInput, TOutput>, 'client' | 'variables'> & {
+    /**
+     * Whether to skip schema validation warnings during canvas retrieval.
+     * When true, no warnings will be logged for schema mismatches.
+     * @default false
+     */
+    skipSchemaValidation?: boolean;
+};
+declare const zod: {
+    file: typeof TelaFileSchema;
+    z: typeof _zod.z;
+    default: typeof _zod.z;
+    core: typeof _zod.core;
+    globalRegistry: _zod.core.$ZodRegistry<_zod.core.GlobalMeta, _zod.core.$ZodType<unknown, unknown, _zod.core.$ZodTypeInternals<unknown, unknown>>>;
+    registry: typeof _zod.core.registry;
+    config: typeof _zod.core.config;
+    $output: typeof _zod.core.$output;
+    $input: typeof _zod.core.$input;
+    $brand: typeof _zod.core.$brand;
+    clone: typeof _zod.core.util.clone;
+    regexes: typeof _zod.core.regexes;
+    treeifyError: typeof _zod.core.treeifyError;
+    prettifyError: typeof _zod.core.prettifyError;
+    formatError: typeof _zod.core.formatError;
+    flattenError: typeof _zod.core.flattenError;
+    toJSONSchema: typeof _zod.core.toJSONSchema;
+    TimePrecision: {
+        readonly Any: null;
+        readonly Minute: -1;
+        readonly Second: 0;
+        readonly Millisecond: 3;
+        readonly Microsecond: 6;
+    };
+    util: typeof _zod.core.util;
+    NEVER: never;
+    locales: typeof _zod.core.locales;
+    ZodISODateTime: _zod.core.$constructor<_zod.ZodISODateTime, _zod.core.$ZodISODateTimeDef>;
+    ZodISODate: _zod.core.$constructor<_zod.ZodISODate, _zod.core.$ZodStringFormatDef<"date">>;
+    ZodISOTime: _zod.core.$constructor<_zod.ZodISOTime, _zod.core.$ZodISOTimeDef>;
+    ZodISODuration: _zod.core.$constructor<_zod.ZodISODuration, _zod.core.$ZodStringFormatDef<"duration">>;
+    iso: typeof _zod.iso;
+    coerce: typeof _zod.coerce;
+    string(params?: string | _zod.core.$ZodStringParams): _zod.ZodString;
+    string<T extends string>(params?: string | _zod.core.$ZodStringParams): _zod.core.$ZodType<T, T>;
+    email(params?: string | _zod.core.$ZodEmailParams): _zod.ZodEmail;
+    guid(params?: string | _zod.core.$ZodGUIDParams): _zod.ZodGUID;
+    uuid(params?: string | _zod.core.$ZodUUIDParams): _zod.ZodUUID;
+    uuidv4(params?: string | _zod.core.$ZodUUIDv4Params): _zod.ZodUUID;
+    uuidv6(params?: string | _zod.core.$ZodUUIDv6Params): _zod.ZodUUID;
+    uuidv7(params?: string | _zod.core.$ZodUUIDv7Params): _zod.ZodUUID;
+    url(params?: string | _zod.core.$ZodURLParams): _zod.ZodURL;
+    httpUrl(params?: string | Omit<_zod.core.$ZodURLParams, "protocol" | "hostname">): _zod.ZodURL;
+    emoji(params?: string | _zod.core.$ZodEmojiParams): _zod.ZodEmoji;
+    nanoid(params?: string | _zod.core.$ZodNanoIDParams): _zod.ZodNanoID;
+    cuid(params?: string | _zod.core.$ZodCUIDParams): _zod.ZodCUID;
+    cuid2(params?: string | _zod.core.$ZodCUID2Params): _zod.ZodCUID2;
+    ulid(params?: string | _zod.core.$ZodULIDParams): _zod.ZodULID;
+    xid(params?: string | _zod.core.$ZodXIDParams): _zod.ZodXID;
+    ksuid(params?: string | _zod.core.$ZodKSUIDParams): _zod.ZodKSUID;
+    ipv4(params?: string | _zod.core.$ZodIPv4Params): _zod.ZodIPv4;
+    ipv6(params?: string | _zod.core.$ZodIPv6Params): _zod.ZodIPv6;
+    cidrv4(params?: string | _zod.core.$ZodCIDRv4Params): _zod.ZodCIDRv4;
+    cidrv6(params?: string | _zod.core.$ZodCIDRv6Params): _zod.ZodCIDRv6;
+    base64(params?: string | _zod.core.$ZodBase64Params): _zod.ZodBase64;
+    base64url(params?: string | _zod.core.$ZodBase64URLParams): _zod.ZodBase64URL;
+    e164(params?: string | _zod.core.$ZodE164Params): _zod.ZodE164;
+    jwt(params?: string | _zod.core.$ZodJWTParams): _zod.ZodJWT;
+    stringFormat<Format extends string>(format: Format, fnOrRegex: ((arg: string) => _zod.core.util.MaybeAsync<unknown>) | RegExp, _params?: string | _zod.core.$ZodStringFormatParams): _zod.ZodCustomStringFormat<Format>;
+    hostname(_params?: string | _zod.core.$ZodStringFormatParams): _zod.ZodCustomStringFormat<"hostname">;
+    hex(_params?: string | _zod.core.$ZodStringFormatParams): _zod.ZodCustomStringFormat<"hex">;
+    hash<Alg extends _zod.core.util.HashAlgorithm, Enc extends _zod.core.util.HashEncoding = "hex">(alg: Alg, params?: {
+        enc?: Enc;
+    } & _zod.core.$ZodStringFormatParams): _zod.ZodCustomStringFormat<`${Alg}_${Enc}`>;
+    number(params?: string | _zod.core.$ZodNumberParams): _zod.ZodNumber;
+    int(params?: string | _zod.core.$ZodCheckNumberFormatParams): _zod.ZodInt;
+    float32(params?: string | _zod.core.$ZodCheckNumberFormatParams): _zod.ZodFloat32;
+    float64(params?: string | _zod.core.$ZodCheckNumberFormatParams): _zod.ZodFloat64;
+    int32(params?: string | _zod.core.$ZodCheckNumberFormatParams): _zod.ZodInt32;
+    uint32(params?: string | _zod.core.$ZodCheckNumberFormatParams): _zod.ZodUInt32;
+    boolean(params?: string | _zod.core.$ZodBooleanParams): _zod.ZodBoolean;
+    bigint(params?: string | _zod.core.$ZodBigIntParams): _zod.ZodBigInt;
+    int64(params?: string | _zod.core.$ZodBigIntFormatParams): _zod.ZodBigIntFormat;
+    uint64(params?: string | _zod.core.$ZodBigIntFormatParams): _zod.ZodBigIntFormat;
+    symbol(params?: string | _zod.core.$ZodSymbolParams): _zod.ZodSymbol;
+    any(): _zod.ZodAny;
+    unknown(): _zod.ZodUnknown;
+    never(params?: string | _zod.core.$ZodNeverParams): _zod.ZodNever;
+    date(params?: string | _zod.core.$ZodDateParams): _zod.ZodDate;
+    array<T extends _zod.core.SomeType>(element: T, params?: string | _zod.core.$ZodArrayParams): _zod.ZodArray<T>;
+    keyof<T extends _zod.ZodObject>(schema: T): _zod.ZodEnum<_zod.core.util.KeysEnum<T["_zod"]["output"]>>;
+    object<T extends _zod.core.$ZodLooseShape = Partial<Record<never, _zod.core.SomeType>>>(shape?: T, params?: string | _zod.core.$ZodObjectParams): _zod.ZodObject<_zod.core.util.Writeable<T>, _zod.core.$strip>;
+    strictObject<T extends _zod.core.$ZodLooseShape>(shape: T, params?: string | _zod.core.$ZodObjectParams): _zod.ZodObject<T, _zod.core.$strict>;
+    looseObject<T extends _zod.core.$ZodLooseShape>(shape: T, params?: string | _zod.core.$ZodObjectParams): _zod.ZodObject<T, _zod.core.$loose>;
+    union<const T extends readonly _zod.core.SomeType[]>(options: T, params?: string | _zod.core.$ZodUnionParams): _zod.ZodUnion<T>;
+    discriminatedUnion<Types extends readonly [_zod.core.$ZodTypeDiscriminable, ..._zod.core.$ZodTypeDiscriminable[]], Disc extends string>(discriminator: Disc, options: Types, params?: string | _zod.core.$ZodDiscriminatedUnionParams): _zod.ZodDiscriminatedUnion<Types, Disc>;
+    intersection<T extends _zod.core.SomeType, U extends _zod.core.SomeType>(left: T, right: U): _zod.ZodIntersection<T, U>;
+    tuple<T extends readonly [_zod.core.SomeType, ..._zod.core.SomeType[]]>(items: T, params?: string | _zod.core.$ZodTupleParams): _zod.ZodTuple<T, null>;
+    tuple<T extends readonly [_zod.core.SomeType, ..._zod.core.SomeType[]], Rest extends _zod.core.SomeType>(items: T, rest: Rest, params?: string | _zod.core.$ZodTupleParams): _zod.ZodTuple<T, Rest>;
+    tuple(items: [], params?: string | _zod.core.$ZodTupleParams): _zod.ZodTuple<[], null>;
+    record<Key extends _zod.core.$ZodRecordKey, Value extends _zod.core.SomeType>(keyType: Key, valueType: Value, params?: string | _zod.core.$ZodRecordParams): _zod.ZodRecord<Key, Value>;
+    partialRecord<Key extends _zod.core.$ZodRecordKey, Value extends _zod.core.SomeType>(keyType: Key, valueType: Value, params?: string | _zod.core.$ZodRecordParams): _zod.ZodRecord<Key & _zod.core.$partial, Value>;
+    map<Key extends _zod.core.SomeType, Value extends _zod.core.SomeType>(keyType: Key, valueType: Value, params?: string | _zod.core.$ZodMapParams): _zod.ZodMap<Key, Value>;
+    set<Value extends _zod.core.SomeType>(valueType: Value, params?: string | _zod.core.$ZodSetParams): _zod.ZodSet<Value>;
+    nativeEnum<T extends _zod.core.util.EnumLike>(entries: T, params?: string | _zod.core.$ZodEnumParams): _zod.ZodEnum<T>;
+    literal<const T extends ReadonlyArray<_zod.core.util.Literal>>(value: T, params?: string | _zod.core.$ZodLiteralParams): _zod.ZodLiteral<T[number]>;
+    literal<const T extends _zod.core.util.Literal>(value: T, params?: string | _zod.core.$ZodLiteralParams): _zod.ZodLiteral<T>;
+    transform<I = unknown, O = I>(fn: (input: I, ctx: _zod.core.ParsePayload) => O): _zod.ZodTransform<Awaited<O>, I>;
+    optional<T extends _zod.core.SomeType>(innerType: T): _zod.ZodOptional<T>;
+    nullable<T extends _zod.core.SomeType>(innerType: T): _zod.ZodNullable<T>;
+    nullish<T extends _zod.core.SomeType>(innerType: T): _zod.ZodOptional<_zod.ZodNullable<T>>;
+    _default<T extends _zod.core.SomeType>(innerType: T, defaultValue: _zod.core.util.NoUndefined<_zod.core.output<T>> | (() => _zod.core.util.NoUndefined<_zod.core.output<T>>)): _zod.ZodDefault<T>;
+    prefault<T extends _zod.core.SomeType>(innerType: T, defaultValue: _zod.core.input<T> | (() => _zod.core.input<T>)): _zod.ZodPrefault<T>;
+    nonoptional<T extends _zod.core.SomeType>(innerType: T, params?: string | _zod.core.$ZodNonOptionalParams): _zod.ZodNonOptional<T>;
+    success<T extends _zod.core.SomeType>(innerType: T): _zod.ZodSuccess<T>;
+    nan(params?: string | _zod.core.$ZodNaNParams): _zod.ZodNaN;
+    pipe<const A extends _zod.core.SomeType, B extends _zod.core.$ZodType<unknown, _zod.core.output<A>> = _zod.core.$ZodType<unknown, _zod.core.output<A>, _zod.core.$ZodTypeInternals<unknown, _zod.core.output<A>>>>(in_: A, out: B | _zod.core.$ZodType<unknown, _zod.core.output<A>>): _zod.ZodPipe<A, B>;
+    codec<const A extends _zod.core.SomeType, B extends _zod.core.SomeType = _zod.core.$ZodType<unknown, unknown, _zod.core.$ZodTypeInternals<unknown, unknown>>>(in_: A, out: B, params: {
+        decode: (value: _zod.core.output<A>, payload: _zod.core.ParsePayload<_zod.core.output<A>>) => _zod.core.util.MaybeAsync<_zod.core.input<B>>;
+        encode: (value: _zod.core.input<B>, payload: _zod.core.ParsePayload<_zod.core.input<B>>) => _zod.core.util.MaybeAsync<_zod.core.output<A>>;
+    }): _zod.ZodCodec<A, B>;
+    readonly<T extends _zod.core.SomeType>(innerType: T): _zod.ZodReadonly<T>;
+    templateLiteral<const Parts extends _zod.core.$ZodTemplateLiteralPart[]>(parts: Parts, params?: string | _zod.core.$ZodTemplateLiteralParams): _zod.ZodTemplateLiteral<_zod.core.$PartsToTemplateLiteral<Parts>>;
+    lazy<T extends _zod.core.SomeType>(getter: () => T): _zod.ZodLazy<T>;
+    promise<T extends _zod.core.SomeType>(innerType: T): _zod.ZodPromise<T>;
+    _function(): _zod.ZodFunction;
+    _function<const In extends ReadonlyArray<_zod.core.$ZodType>>(params: {
+        input: In;
+    }): _zod.ZodFunction<_zod.ZodTuple<In, null>, _zod.core.$ZodFunctionOut>;
+    _function<const In extends ReadonlyArray<_zod.core.$ZodType>, const Out extends _zod.core.$ZodFunctionOut = _zod.core.$ZodFunctionOut>(params: {
+        input: In;
+        output: Out;
+    }): _zod.ZodFunction<_zod.ZodTuple<In, null>, Out>;
+    _function<const In extends _zod.core.$ZodFunctionIn = _zod.core.$ZodFunctionArgs>(params: {
+        input: In;
+    }): _zod.ZodFunction<In, _zod.core.$ZodFunctionOut>;
+    _function<const Out extends _zod.core.$ZodFunctionOut = _zod.core.$ZodFunctionOut>(params: {
+        output: Out;
+    }): _zod.ZodFunction<_zod.core.$ZodFunctionIn, Out>;
+    _function<In extends _zod.core.$ZodFunctionIn = _zod.core.$ZodFunctionArgs, Out extends _zod.core.$ZodType = _zod.core.$ZodType<unknown, unknown, _zod.core.$ZodTypeInternals<unknown, unknown>>>(params?: {
+        input: In;
+        output: Out;
+    }): _zod.ZodFunction<In, Out>;
+    check<O = unknown>(fn: _zod.core.CheckFn<O>): _zod.core.$ZodCheck<O>;
+    custom<O>(fn?: (data: unknown) => unknown, _params?: string | _zod.core.$ZodCustomParams | undefined): _zod.ZodCustom<O, O>;
+    refine<T>(fn: (arg: NoInfer<T>) => _zod.core.util.MaybeAsync<unknown>, _params?: string | _zod.core.$ZodCustomParams): _zod.core.$ZodCheck<T>;
+    superRefine<T>(fn: (arg: T, payload: _zod.core.$RefinementCtx<T>) => void | Promise<void>): _zod.core.$ZodCheck<T>;
+    json(params?: string | _zod.core.$ZodCustomParams): _zod.ZodJSONSchema;
+    preprocess<A, U extends _zod.core.SomeType, B = unknown>(fn: (arg: B, ctx: _zod.core.$RefinementCtx) => A, schema: U): _zod.ZodPipe<_zod.ZodTransform<A, B>, U>;
+    ZodType: _zod.core.$constructor<_zod.ZodType>;
+    _ZodString: _zod.core.$constructor<_zod._ZodString>;
+    ZodString: _zod.core.$constructor<_zod.ZodString>;
+    ZodStringFormat: _zod.core.$constructor<_zod.ZodStringFormat>;
+    ZodEmail: _zod.core.$constructor<_zod.ZodEmail>;
+    ZodGUID: _zod.core.$constructor<_zod.ZodGUID>;
+    ZodUUID: _zod.core.$constructor<_zod.ZodUUID>;
+    ZodURL: _zod.core.$constructor<_zod.ZodURL>;
+    ZodEmoji: _zod.core.$constructor<_zod.ZodEmoji>;
+    ZodNanoID: _zod.core.$constructor<_zod.ZodNanoID>;
+    ZodCUID: _zod.core.$constructor<_zod.ZodCUID>;
+    ZodCUID2: _zod.core.$constructor<_zod.ZodCUID2>;
+    ZodULID: _zod.core.$constructor<_zod.ZodULID>;
+    ZodXID: _zod.core.$constructor<_zod.ZodXID>;
+    ZodKSUID: _zod.core.$constructor<_zod.ZodKSUID>;
+    ZodIPv4: _zod.core.$constructor<_zod.ZodIPv4>;
+    ZodIPv6: _zod.core.$constructor<_zod.ZodIPv6>;
+    ZodCIDRv4: _zod.core.$constructor<_zod.ZodCIDRv4>;
+    ZodCIDRv6: _zod.core.$constructor<_zod.ZodCIDRv6>;
+    ZodBase64: _zod.core.$constructor<_zod.ZodBase64>;
+    ZodBase64URL: _zod.core.$constructor<_zod.ZodBase64URL>;
+    ZodE164: _zod.core.$constructor<_zod.ZodE164>;
+    ZodJWT: _zod.core.$constructor<_zod.ZodJWT>;
+    ZodCustomStringFormat: _zod.core.$constructor<_zod.ZodCustomStringFormat>;
+    ZodNumber: _zod.core.$constructor<_zod.ZodNumber>;
+    ZodNumberFormat: _zod.core.$constructor<_zod.ZodNumberFormat>;
+    ZodBoolean: _zod.core.$constructor<_zod.ZodBoolean>;
+    ZodBigInt: _zod.core.$constructor<_zod.ZodBigInt>;
+    ZodBigIntFormat: _zod.core.$constructor<_zod.ZodBigIntFormat>;
+    ZodSymbol: _zod.core.$constructor<_zod.ZodSymbol>;
+    ZodUndefined: _zod.core.$constructor<_zod.ZodUndefined>;
+    undefined: typeof _zod.undefined;
+    ZodNull: _zod.core.$constructor<_zod.ZodNull>;
+    null: typeof _zod.null;
+    ZodAny: _zod.core.$constructor<_zod.ZodAny>;
+    ZodUnknown: _zod.core.$constructor<_zod.ZodUnknown>;
+    ZodNever: _zod.core.$constructor<_zod.ZodNever>;
+    ZodVoid: _zod.core.$constructor<_zod.ZodVoid>;
+    void: typeof _zod.void;
+    ZodDate: _zod.core.$constructor<_zod.ZodDate>;
+    ZodArray: _zod.core.$constructor<_zod.ZodArray>;
+    ZodObject: _zod.core.$constructor<_zod.ZodObject>;
+    ZodUnion: _zod.core.$constructor<_zod.ZodUnion>;
+    ZodDiscriminatedUnion: _zod.core.$constructor<_zod.ZodDiscriminatedUnion>;
+    ZodIntersection: _zod.core.$constructor<_zod.ZodIntersection>;
+    ZodTuple: _zod.core.$constructor<_zod.ZodTuple>;
+    ZodRecord: _zod.core.$constructor<_zod.ZodRecord>;
+    ZodMap: _zod.core.$constructor<_zod.ZodMap>;
+    ZodSet: _zod.core.$constructor<_zod.ZodSet>;
+    ZodEnum: _zod.core.$constructor<_zod.ZodEnum>;
+    enum: typeof _zod.enum;
+    ZodLiteral: _zod.core.$constructor<_zod.ZodLiteral>;
+    ZodFile: _zod.core.$constructor<_zod.ZodFile>;
+    ZodTransform: _zod.core.$constructor<_zod.ZodTransform>;
+    ZodOptional: _zod.core.$constructor<_zod.ZodOptional>;
+    ZodNullable: _zod.core.$constructor<_zod.ZodNullable>;
+    ZodDefault: _zod.core.$constructor<_zod.ZodDefault>;
+    ZodPrefault: _zod.core.$constructor<_zod.ZodPrefault>;
+    ZodNonOptional: _zod.core.$constructor<_zod.ZodNonOptional>;
+    ZodSuccess: _zod.core.$constructor<_zod.ZodSuccess>;
+    ZodCatch: _zod.core.$constructor<_zod.ZodCatch>;
+    catch: typeof _zod.catch;
+    ZodNaN: _zod.core.$constructor<_zod.ZodNaN>;
+    ZodPipe: _zod.core.$constructor<_zod.ZodPipe>;
+    ZodCodec: _zod.core.$constructor<_zod.ZodCodec>;
+    ZodReadonly: _zod.core.$constructor<_zod.ZodReadonly>;
+    ZodTemplateLiteral: _zod.core.$constructor<_zod.ZodTemplateLiteral>;
+    ZodLazy: _zod.core.$constructor<_zod.ZodLazy>;
+    ZodPromise: _zod.core.$constructor<_zod.ZodPromise>;
+    ZodFunction: _zod.core.$constructor<_zod.ZodFunction>;
+    function: typeof _zod._function;
+    ZodCustom: _zod.core.$constructor<_zod.ZodCustom>;
+    instanceof: typeof _zod.instanceof;
+    stringbool: (_params?: string | _zod.core.$ZodStringBoolParams) => _zod.ZodCodec<_zod.ZodString, _zod.ZodBoolean>;
+    lt: typeof _zod.core._lt;
+    lte: typeof _zod.core._lte;
+    gt: typeof _zod.core._gt;
+    gte: typeof _zod.core._gte;
+    positive: typeof _zod.core._positive;
+    negative: typeof _zod.core._negative;
+    nonpositive: typeof _zod.core._nonpositive;
+    nonnegative: typeof _zod.core._nonnegative;
+    multipleOf: typeof _zod.core._multipleOf;
+    maxSize: typeof _zod.core._maxSize;
+    minSize: typeof _zod.core._minSize;
+    size: typeof _zod.core._size;
+    maxLength: typeof _zod.core._maxLength;
+    minLength: typeof _zod.core._minLength;
+    length: typeof _zod.core._length;
+    regex: typeof _zod.core._regex;
+    lowercase: typeof _zod.core._lowercase;
+    uppercase: typeof _zod.core._uppercase;
+    includes: typeof _zod.core._includes;
+    startsWith: typeof _zod.core._startsWith;
+    endsWith: typeof _zod.core._endsWith;
+    property: typeof _zod.core._property;
+    mime: typeof _zod.core._mime;
+    overwrite: typeof _zod.core._overwrite;
+    normalize: typeof _zod.core._normalize;
+    trim: typeof _zod.core._trim;
+    toLowerCase: typeof _zod.core._toLowerCase;
+    toUpperCase: typeof _zod.core._toUpperCase;
+    ZodError: _zod.core.$constructor<ZodError>;
+    ZodRealError: _zod.core.$constructor<ZodError>;
+    parse: <T extends _zod.core.$ZodType>(schema: T, value: unknown, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>, _params?: {
+        callee?: _zod.core.util.AnyFunc;
+        Err?: _zod.core.$ZodErrorClass;
+    }) => _zod.core.output<T>;
+    parseAsync: <T extends _zod.core.$ZodType>(schema: T, value: unknown, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>, _params?: {
+        callee?: _zod.core.util.AnyFunc;
+        Err?: _zod.core.$ZodErrorClass;
+    }) => Promise<_zod.core.output<T>>;
+    safeParse: <T extends _zod.core.$ZodType>(schema: T, value: unknown, _ctx?: _zod.core.ParseContext<_zod.core.$ZodIssue>) => _zod.ZodSafeParseResult<_zod.core.output<T>>;
+    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>>;
+    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.
+     */: _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>>;
+    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;
+    getErrorMap(): _zod.core.$ZodErrorMap<_zod.core.$ZodIssue> | undefined;
+    ZodIssueCode: {
+        readonly invalid_type: "invalid_type";
+        readonly too_big: "too_big";
+        readonly too_small: "too_small";
+        readonly invalid_format: "invalid_format";
+        readonly not_multiple_of: "not_multiple_of";
+        readonly unrecognized_keys: "unrecognized_keys";
+        readonly invalid_union: "invalid_union";
+        readonly invalid_key: "invalid_key";
+        readonly invalid_element: "invalid_element";
+        readonly invalid_value: "invalid_value";
+        readonly custom: "custom";
     };
+    ZodFirstPartyTypeKind: typeof _zod.ZodFirstPartyTypeKind;
+};
+type SchemaBuilder = typeof zod;
+type SchemaFunction<T> = (schema: SchemaBuilder) => T;
+type Output<T> = T extends z.ZodType ? z.infer<T> : T;
+type ZodTypeOrRecord = z.ZodType | Record<string, unknown>;
+type CanvasExecutionPromiseLike<TParams extends ExecutionParams = SyncExecutionParams, TInput = unknown, TOutput = unknown> = PromiseLike<CanvasExecution<TParams, TInput, TOutput>> & {
+    result: Promise<CanvasExecutionResult<TParams, TOutput>>;
+};
+/**
+ * Represents a canvas (prompt template) from the Tela API.
+ *
+ * Canvas instances are retrieved using `tela.canvas.get()` and provide methods
+ * for executing prompts with various modes (sync, async, streaming).
+ *
+ * @category Canvas
+ *
+ * @typeParam TInput - The input schema type (Zod schema or plain object type)
+ * @typeParam TOutput - The output schema type (Zod schema or plain object type)
+ */
+declare class Canvas<TInput extends ZodTypeOrRecord, TOutput extends ZodTypeOrRecord> {
+    private readonly _id;
+    private readonly _versionId;
+    private readonly _applicationId;
+    private readonly _name;
+    private readonly _input;
+    private readonly _output;
+    private readonly _client;
+    private readonly _variables;
     /**
-     * The original input parameters provided for this chat completion.
-     */
-    rawInput: {
-        versionId?: string;
-        canvasId?: string;
-        applicationId?: string;
-        webhookUrl?: string;
-        variables?: ChatCompletionVariablesWithFileURL;
-        messages?: Array<{
-            role: string;
-            content: string | {
-                type: 'text';
-                text: string;
-            } | {
-                type: 'image_url';
-                imageUrl: {
-                    url: string;
-                    detail?: 'auto' | 'high' | 'low';
-                };
-            };
-        }>;
-        override?: {
-            model?: string;
-            temperature?: number;
-            type: 'chat' | 'completion';
-            functions?: Array<{
-                id: string;
-                name: string;
-                description?: string;
-                parameters?: {
-                    type: 'object';
-                    properties: Record<string, unknown>;
-                    required?: string[];
-                };
-            }>;
-            structuredOutput?: {
-                enabled: boolean;
-                schema?: {
-                    properties: Record<string, unknown>;
-                    type: 'object';
-                    title: string;
-                    description: string;
-                    required: string[];
-                };
-            };
-        };
-    } | null;
+     * Creates a new instance of the Canvas class. Usage of this constructor is not recommended.
+     * Use the `tela.getCanvas` method instead.
+     *
+     * @private
+     */
+    private constructor();
     /**
-     * The raw output from the chat completion process.
+     * Gets a canvas by its ID.
+     *
+     * @param options - The options to use to get the canvas.
+     * @param options.id - The ID of the canvas to get.
+     * @param options.versionId - The version ID of the canvas to get.
+     * @param options.applicationId - The application ID of the canvas to get.
+     * @param options.client - The client to use to make the request.
+     * @param options.input - The input schema of the canvas to get.
+     * @param options.output - The output schema of the canvas to get.
+     * @returns The canvas.
      */
-    rawOutput: Record<string, unknown>;
+    static get<TInput extends ZodTypeOrRecord, TOutput extends ZodTypeOrRecord>(options: CanvasGetOptions<TInput, TOutput> & {
+        client: BaseClient;
+    }): Promise<Canvas<TInput, TOutput>>;
     /**
-     * The date used for compatibility checks.
+     * Gets the unique identifier of this canvas.
+     *
+     * @returns The canvas ID.
      */
-    compatibilityDate: Date;
+    get id(): string;
     /**
-     * The ID of the prompt version used for this chat completion.
+     * Gets the name of this canvas, if provided.
+     *
+     * @returns The canvas name or undefined.
      */
-    promptVersionId: string;
+    get name(): string;
     /**
-     * The ID of the prompt application, if applicable.
+     * Gets the version identifier of this canvas, if specified.
+     * When undefined, the latest promoted version is used.
+     *
+     * @returns The version ID or undefined.
      */
-    promptApplicationId: string | null;
+    get versionId(): string;
+    get applicationId(): string;
     /**
-     * The ID of the workspace where this chat completion was executed.
+     * Gets the variables of this canvas.
+     *
+     * @returns The variables of the canvas.
      */
-    workspaceId: string;
+    get variables(): Array<CanvasVariable>;
     /**
-     * The timestamp when this chat completion was created.
+     * Validates and parses input variables using the canvas input schema.
+     *
+     * @param variables - Raw input variables to validate.
+     * @returns Parsed and validated variables.
+     * @throws {ZodError} If validation fails when a Zod schema is configured.
      */
-    createdAt: string;
+    private parseVariables;
     /**
-     * The timestamp when this chat completion was last updated.
+     * Executes this canvas with the provided input variables.
+     * Creates and starts a canvas execution, handling variable validation and schema parsing.
+     *
+     * Returns a promise-like object that allows flexible usage patterns:
+     * - Await for the execution object: `const exec = await canvas.execute(vars)`
+     * - Direct result access: `const result = await canvas.execute(vars).result`
+     * - Stream iteration: `for await (const chunk of canvas.execute(vars, { stream: true }).result)`
+     *
+     * @param variables - Input variables to pass to the canvas template.
+     * @param params - Optional execution parameters (sync/async/stream configuration).
+     * @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 canvas.execute({ query: "Hello" }).result;
+     *
+     * // Get execution object for control (e.g., to abort)
+     * const execution = await canvas.execute({ query: "Hello" });
+     * const result = await execution.result;
+     *
+     * // Asynchronous execution with polling
+     * const result = await canvas.execute(
+     *   { query: "Hello" },
+     *   { async: true, pollingInterval: 500 }
+     * ).result;
+     *
+     * // Streaming execution
+     * for await (const chunk of canvas.execute(
+     *   { query: "Hello" },
+     *   { stream: true }
+     * ).result) {
+     *   console.log(chunk);
+     * }
+     *
+     * // Execution with tags
+     * const result = await canvas.execute(
+     *   { query: "Hello" },
+     *   { tags: ["production", "analytics"] }
+     * ).result;
+     * ```
      */
-    updatedAt: string;
+    execute(variables: z.input<TInput>, params?: SyncExecutionParams): CanvasExecutionPromiseLike<SyncExecutionParams, Output<TInput>, Output<TOutput>>;
+    execute(variables: z.input<TInput>, params?: AsyncExecutionParams): CanvasExecutionPromiseLike<AsyncExecutionParams, Output<TInput>, Output<TOutput>>;
+    execute(variables: z.input<TInput>, params?: StreamExecutionParams): CanvasExecutionPromiseLike<StreamExecutionParams, Output<TInput>, Output<TOutput>>;
     /**
-     * The timestamp when this chat completion was deleted, if applicable.
+     * Fetches an existing async execution by its ID.
+     *
+     * This method retrieves the current state of an async execution that was previously
+     * started on this canvas. Only async executions can be fetched, as they are the only
+     * ones with persistent UUIDs on the server.
+     *
+     * @param id - The UUID of the async execution to fetch.
+     * @param options - Optional configuration for polling behavior.
+     * @param options.pollingInterval - Time in milliseconds between polling attempts (default: 1000).
+     * @param options.pollingTimeout - Maximum time in milliseconds to wait for completion (default: 60000).
+     * @throws {InvalidExecutionModeError} If the provided ID is not a valid UUID.
+     * @returns A promise resolving to a CanvasExecution instance with the fetched state.
+     *
+     * @example
+     * ```typescript
+     * // Start an async execution
+     * const execution = await canvas.execute({ query: 'test' }, { async: true })
+     * const executionId = execution.id
+     *
+     * // Later, fetch the execution by ID
+     * const fetched = await canvas.getExecution(executionId)
+     * console.log(fetched.status) // 'running', 'succeeded', or 'failed'
+     *
+     * // Use poll() for event-driven progress tracking
+     * fetched.on('statusChange', (status) => console.log('Status:', status))
+     * fetched.poll()
+     * ```
      */
-    deletedAt: string | null;
+    getExecution(id: string, options?: {
+        pollingInterval?: number;
+        pollingTimeout?: number;
+    }): Promise<CanvasExecution<AsyncExecutionParams, unknown, Output<TOutput>>>;
 }
 
+/**
+ * Tela SDK main entry point and client initialization.
+ *
+ * This module provides the main TelaSDK class for initializing the client
+ * and accessing all Tela API resources including canvas management, file
+ * handling, and error classes.
+ *
+ * @module Core
+ */
+
 /**
  * Configuration options for the TelaSDK.
  *
@@ -806,6 +1569,8 @@ interface TelaSDKOptions extends Omit<BaseClientOptions, 'baseURL'> {
  *
  * Provides methods to access various Tela API resources.
  *
+ * @category SDK
+ *
  * @example
  * ```typescript
  * const tela = new TelaSDK({ apiKey: 'your-api-key' });
@@ -823,29 +1588,49 @@ declare class TelaSDK extends BaseClient {
      * Creates a new instance of the TelaSDK.
      */
     constructor({ baseURL, apiKey, jwt, ...rest }: TelaSDKOptions);
+    get authToken(): string;
     private validateAuth;
     protected getAuthHeaders(): Record<string, string>;
     /**
-     * The ChatCompletions resource for interacting with Tela's chat completion API.
+     * Creates a new `TelaFile` instance from the provided file input.
+     *
+     * @param file - The file input to create a `TelaFile` instance from.
+     * @returns A new `TelaFile` instance.
+     */
+    createFile: typeof TelaFile.create;
+    /**
+     * Retrieves a canvas by its ID, version ID, or application ID.
+     * Validates input and output schemas if provided via schema builder functions.
      *
-     * Use this to generate chat completions based on provided messages.
+     * @param options - Options for retrieving the canvas.
+     * @returns A promise resolving to a Canvas instance.
      *
      * @example
      * ```typescript
-     * const completion = await tela.completions.create({
-     *   canvasId: "your-canvas-id",
-     *   messages: [{ role: "user", content: "Hello!" }],
+     * // Get canvas by ID with schemas
+     * const canvas = await tela.canvas.get({
+     *   id: 'canvas-id',
+     *   input: schema => schema.object({
+     *     query: schema.string()
+     *   }),
+     *   output: schema => schema.object({
+     *     response: schema.string()
+     *   })
      * });
-     * ```
-     */
-    completions: ChatCompletions;
-    /**
-     * Creates a new `TelaFile` instance from the provided file input.
      *
-     * @param file - The file input to create a `TelaFile` instance from.
-     * @returns A new `TelaFile` instance.
+     * // Get canvas by application ID
+     * const canvas = await tela.canvas.get({
+     *   applicationId: 'app-id'
+     * });
+     *
+     * // Execute the canvas
+     * const execution = await canvas.execute({ query: 'Hello' });
+     * const result = await execution.result;
+     * ```
      */
-    createFile: typeof createTelaFile;
+    canvas: {
+        get: <TInput extends z.ZodType | Record<string, unknown> = Record<string, unknown>, TOutput extends z.ZodType | Record<string, unknown> = Record<string, unknown>>(options: CanvasGetOptions<TInput, TOutput>) => Promise<Canvas<TInput, TOutput>>;
+    };
     static TelaSDK: typeof TelaSDK;
     static DEFAULT_TIMEOUT: number;
     /** Thrown when an API request fails. */
@@ -891,4 +1676,4 @@ declare class TelaSDK extends BaseClient {
  */
 declare function createTelaClient(opts: TelaSDKOptions): TelaSDK;
 
-export { TelaFile, TelaSDK, type TelaSDKOptions, createTelaClient };
+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 };