@meistrari/tela-sdk-js 1.0.2 → 2.0.0

package/dist/index.d.cts

@@ -1,3 +1,14 @@
+import z, { string, number, boolean, object, array, any, unknown, z as z$1 } from 'zod';
+
+/**
+ * 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 +26,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 +39,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 +62,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 +197,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 +230,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(): z.ZodCustom<TelaFile, TelaFile>;
 /**
  * Represents a file with support for various types including URLs, binary data, streams, and Blobs.
  *
@@ -148,7 +255,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 +279,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 +310,9 @@ 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);
+    private constructor();
+    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 +325,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 +373,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.
+     * Checks if the provided string is a valid Vault reference.
      *
-     * @param iterator - A function that returns an AsyncIterator<Item>.
-     * @param controller - The AbortController for this stream.
+     * @param url - The Vault reference string to validate.
+     * @returns `true` if the Vault reference is valid, otherwise `false`.
      */
-    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()`.
-     *
-     * @returns A ReadableStream containing newline-separated JSON data.
-     */
-    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);
- * ```
- */
-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.
+ * @module Resources
  */
-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.
@@ -408,16 +408,6 @@ interface ChatCompletionCreateParamsBase<Variables = ChatCompletionVariables> {
      * This is required if a canvasId is not provided.
      */
     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.
-     */
-    variables?: Variables;
     /**
      * An array of previous messages in the conversation.
      * Each message should have a 'role' (e.g., 'user', 'assistant') and 'content'.
@@ -459,327 +449,490 @@ 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;
 }
 /**
- * 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 {
     /**
-     * Whether the response should be streamed.
+     * Enable streaming mode.
      */
-    stream?: false | undefined | null;
+    stream: true;
+    /**
+     * Async mode is not available for streaming executions.
+     */
+    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;
+    /**
+     * Webhook URL is not available for synchronous executions.
+     */
+    webhookUrl?: never;
     /**
-     * The webhook URL, if you want to receive a webhook when the completion is completed.
+     * Stream mode is not available for synchronous executions.
      */
-    webhookUrl: string;
+    stream?: never;
 }
 /**
- * Union type for all possible chat completion creation parameters.
+ * Union type of all possible execution parameter configurations.
  */
-type ChatCompletionCreateParams<T> = CompletionCreateParamsStreaming<T> | CompletionCreateParamsNonStreaming<T> | ChatCompletionCreateWebhookParams<T>;
+type ExecutionParams = AsyncExecutionParams | StreamExecutionParams | SyncExecutionParams;
 /**
- * Response structure for a created chat completion.
+ * 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 ChatCompletionCreateResponse<T> = {
+type CanvasExecutionResult<TParams, TOutput = unknown> = TParams extends StreamExecutionParams ? AsyncGenerator<Partial<TOutput>> : Promise<TOutput>;
+/**
+ * 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.
+ *
+ * @category Canvas
+ *
+ * @typeParam TParams - The execution parameters type
+ * @typeParam TInput - The input variables type
+ * @typeParam TOutput - The output result type
+ */
+declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionParams, TInput = unknown, TOutput = unknown> {
+    private _id;
+    private readonly _variables;
+    private readonly _params;
+    private readonly _client;
+    private readonly _outputSchema;
+    private readonly _skipResultValidation;
+    private readonly _abortController;
+    private _startPropmise;
+    private _resultPromise;
+    private _stream;
     /**
-     * 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: z.ZodType | Record<string, unknown>, client: BaseClient);
     /**
-     * The object of the completion.
+     * Gets the unique execution ID assigned by the server.
+     *
+     * @throws {Error} If the execution has not been started yet.
+     * @returns The execution ID.
      */
-    object: string;
+    get id(): string;
     /**
-     * The created time of the completion.
+     * Gets the input variables provided to this execution.
+     *
+     * @returns The variables object.
      */
-    created: number;
+    get variables(): TInput;
     /**
-     * The choices of the completion.
+     * Gets the execution parameters configured for this instance.
+     *
+     * @returns The execution parameters or undefined.
      */
-    choices: Array<{
-        message: {
-            role: string;
-            content: T;
-        };
-    }>;
-};
-/**
- * Response structure for a chat completion streaming response.
- */
-type ChatCompletionCreateStreamingResponse<T> = {
+    get params(): TParams;
     /**
-     * The ID of the completion.
+     * Checks if this execution is configured for asynchronous processing.
+     *
+     * @returns True if async mode is enabled.
      */
-    id: string;
+    get isAsync(): boolean;
     /**
-     * The object of the completion.
+     * Checks if this execution is configured for synchronous processing.
+     *
+     * @returns True if sync mode is enabled (not async).
      */
-    object: string;
+    get isSync(): boolean;
     /**
-     * The created time of the completion.
+     * Checks if this execution is configured for streaming responses.
+     *
+     * @returns True if stream mode is enabled.
      */
-    created: number;
+    get isStream(): boolean;
     /**
-     * The model of the completion.
+     * Type guard to check if params indicate async execution.
+     *
+     * @param params - Execution parameters to check.
+     * @returns True if params indicate async mode.
      */
-    model: string;
+    private _isAsync;
     /**
-     * The choices of the completion.
+     * 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.
      */
-    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;
+    start(): Promise<CanvasExecutionResult<TParams, TOutput>> | AsyncGenerator<Partial<TOutput>, any, any> | Promise<AsyncGenerator<Partial<TOutput>, any, any>> | Promise<{
+        id: string;
     }>;
     /**
-     * The message of the completion.
+     * 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.
      */
-    message: {
-        role: string;
-        content: string | null;
-        functionCall: {
-            name: string | null;
-            arguments: string | null;
-        } | null;
-        toolCalls: Array<{
-            name: string;
-            arguments: string;
-        }>;
-        structuredContent: T;
-    };
-};
+    get result(): CanvasExecutionResult<TParams, TOutput>;
+    /**
+     * Cancels the ongoing execution by aborting all active requests and polling operations.
+     */
+    cancel(): void;
+    /**
+     * Builds the base request body shared across all execution types.
+     * Includes messages, overrides, 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;
+}
+
 /**
- * Response structure for a chat completion webhook.
- * This interface represents the data sent to the webhook URL when a chat completion is finished.
+ * 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
  */
-interface ChatCompletionWebhookResponse<T> {
+
+/**
+ * Represents a variable that can be used in a canvas template.
+ */
+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;
-            };
-        }>;
-        /**
-         * Information about files used in the chat completion.
-         */
-        files: Array<{
-            name: string;
-            usedAt: 'variables' | 'messages';
-            parsedContent: string;
-            url: string;
-            type: 'image' | 'file';
-        }>;
-    };
+    required: boolean;
     /**
-     * Contains the output generated by the chat completion.
+     * Description of the variable's purpose.
      */
-    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;
+    description: string;
+    /**
+     * Processing options for the variable.
+     */
+    processingOptions: {
         /**
-         * Optional. The input messages in a string format.
+         * Whether multimodal content (images, files) is allowed.
          */
-        inputMessages?: string | undefined;
+        allowMultimodal: boolean;
     };
+};
+interface CanvasOptions<TInput, TOutput> {
     /**
-     * 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;
+     * Id of the canvas that will be used to create the completion.
+     */
+    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: {
+    string: typeof string;
+    number: typeof number;
+    boolean: typeof boolean;
+    object: typeof object;
+    array: typeof array;
+    file: typeof TelaFileSchema;
+    any: typeof any;
+    unknown: typeof unknown;
+};
+type SchemaBuilder = typeof zod;
+type SchemaFunction<T> = (schema: SchemaBuilder) => T;
+type Output<T> = T extends z$1.ZodType ? z$1.infer<T> : T;
+type ZodTypeOrRecord = z$1.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 raw output from the chat completion process.
+     * Creates a new instance of the Canvas class. Usage of this constructor is not recommended.
+     * Use the `tela.getCanvas` method instead.
+     *
+     * @private
      */
-    rawOutput: Record<string, unknown>;
+    private constructor();
     /**
-     * The date used for compatibility checks.
+     * 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.
      */
-    compatibilityDate: Date;
+    static get<TInput extends ZodTypeOrRecord, TOutput extends ZodTypeOrRecord>(options: CanvasGetOptions<TInput, TOutput> & {
+        client: BaseClient;
+    }): Promise<Canvas<TInput, TOutput>>;
     /**
-     * The ID of the prompt version used for this chat completion.
+     * Gets the unique identifier of this canvas.
+     *
+     * @returns The canvas ID.
      */
-    promptVersionId: string;
+    get id(): string;
     /**
-     * The ID of the prompt application, if applicable.
+     * Gets the name of this canvas, if provided.
+     *
+     * @returns The canvas name or undefined.
      */
-    promptApplicationId: string | null;
+    get name(): string;
     /**
-     * The ID of the workspace where this chat completion was executed.
+     * Gets the version identifier of this canvas, if specified.
+     * When undefined, the latest promoted version is used.
+     *
+     * @returns The version ID or undefined.
      */
-    workspaceId: string;
+    get versionId(): string;
+    get applicationId(): string;
     /**
-     * The timestamp when this chat completion was created.
+     * Gets the variables of this canvas.
+     *
+     * @returns The variables of the canvas.
      */
-    createdAt: string;
+    get variables(): Array<CanvasVariable>;
     /**
-     * The timestamp when this chat completion was last updated.
+     * 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.
      */
-    updatedAt: string;
+    private parseVariables;
     /**
-     * The timestamp when this chat completion was deleted, if applicable.
+     * 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);
+     * }
+     * ```
      */
-    deletedAt: string | null;
+    execute(variables: z$1.input<TInput>, params?: SyncExecutionParams): CanvasExecutionPromiseLike<SyncExecutionParams, Output<TInput>, Output<TOutput>>;
+    execute(variables: z$1.input<TInput>, params?: AsyncExecutionParams): CanvasExecutionPromiseLike<AsyncExecutionParams, Output<TInput>, Output<TOutput>>;
+    execute(variables: z$1.input<TInput>, params?: StreamExecutionParams): CanvasExecutionPromiseLike<StreamExecutionParams, Output<TInput>, 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 +959,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 +978,47 @@ 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.
      *
-     * Use this to generate chat completions based on provided messages.
+     * @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 Zod schemas are provided.
+     *
+     * @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!" }],
+     * import { z } from 'zod';
+     *
+     * // Get canvas by ID with schemas
+     * const canvas = await tela.canvas.get({
+     *   id: 'canvas-id',
+     *   input: z.object({ query: z.string() }),
+     *   output: z.object({ response: z.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$1.ZodType | Record<string, unknown> = Record<string, unknown>, TOutput extends z$1.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 +1064,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 };