@meistrari/tela-sdk-js 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-import z, { string, number, boolean, object, array, any, unknown, z as z$1 } from 'zod';
+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.
@@ -245,7 +247,7 @@ type TelaFileOptions = BaseTelaFileOptions | TelaFileOptionsWithMimeType;
  * 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>;
+declare function TelaFileSchema(): _zod__default.ZodCustom<TelaFile, TelaFile>;
 /**
  * Represents a file with support for various types including URLs, binary data, streams, and Blobs.
  *
@@ -310,7 +312,8 @@ declare class TelaFile {
      * @throws {InvalidFileURL} If the provided URL is not valid.
      * @throws {EmptyFileError} If the provided file is empty.
      */
-    private constructor();
+    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;
     /**
@@ -408,6 +411,12 @@ interface BaseExecutionParams {
      * This is required if a canvasId is not provided.
      */
     applicationId?: string;
+    /**
+     * 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.
+     */
+    label?: string;
     /**
      * An array of previous messages in the conversation.
      * Each message should have a 'role' (e.g., 'user', 'assistant') and 'content'.
@@ -456,6 +465,11 @@ interface BaseExecutionParams {
      * @default false
      */
     skipResultValidation?: boolean;
+    /**
+     * Optional array of tags to associate with this execution.
+     * Tags can be used for filtering, categorization, and analytics.
+     */
+    tags?: string[];
 }
 /**
  * Configuration for asynchronous canvas execution with polling.
@@ -523,6 +537,117 @@ interface SyncExecutionParams extends BaseExecutionParams {
      */
     stream?: never;
 }
+/**
+ * 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 RawAPIResult = any;
+/**
+ * Result returned when polling for asynchronous execution status.
+ *
+ * @template T - The type of the output content.
+ */
+type AsyncCompletionPollingResult<T> = {
+    /**
+     * Unique identifier for the execution.
+     */
+    id: string;
+    /**
+     * Current status of the execution.
+     */
+    status: ExecutionStatus;
+    /**
+     * The output content when execution succeeds.
+     */
+    outputContent: {
+        /**
+         * The actual content result.
+         */
+        content: T;
+    };
+    /**
+     * Raw output data from the execution.
+     */
+    rawOutput: Record<string, any>;
+};
 /**
  * Union type of all possible execution parameter configurations.
  */
@@ -537,29 +662,74 @@ type ExecutionParams = AsyncExecutionParams | StreamExecutionParams | SyncExecut
  * @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;
+};
 /**
  * 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'
+ * ```
  */
-declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionParams, TInput = unknown, TOutput = unknown> {
+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 _startPropmise;
     private _resultPromise;
     private _stream;
+    private _rawResultValue;
     /**
      * Creates a new canvas execution instance.
      *
@@ -568,14 +738,81 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * @param outputSchema - Zod schema or object schema for validating/parsing output.
      * @param client - HTTP client instance for making API requests.
      */
-    constructor(variables: TInput, params: TParams | undefined, outputSchema: z.ZodType | Record<string, unknown>, client: BaseClient);
+    constructor(variables: TInput, params: TParams | undefined, outputSchema: _zod__default.ZodType | Record<string, unknown>, client: BaseClient);
+    /**
+     * 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'
+     * ```
+     */
+    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>>;
     /**
      * Gets the unique execution ID assigned by the server.
      *
-     * @throws {Error} If the execution has not been started yet.
+     * 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.
      */
     get id(): string;
+    /**
+     * 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'
+     * ```
+     */
+    get status(): ExecutionStatus;
+    /**
+     * Sets the status of the execution.
+     *
+     * @param status - The new status of the execution.
+     * @private
+     */
+    private set status(value);
     /**
      * Gets the input variables provided to this execution.
      *
@@ -606,6 +843,17 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * @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.
      *
@@ -619,9 +867,7 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      *
      * @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<{
-        id: string;
-    }>;
+    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.
@@ -633,9 +879,59 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * 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, and structured output configuration.
+     * Includes messages, overrides, tags, label, and structured output configuration.
      *
      * @returns The base request body object.
      */
@@ -789,19 +1085,294 @@ type CanvasGetOptions<TInput extends ZodTypeOrRecord, TOutput extends ZodTypeOrR
     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;
+    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$1.ZodType ? z$1.infer<T> : T;
-type ZodTypeOrRecord = z$1.ZodType | Record<string, unknown>;
+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>>;
 };
@@ -916,11 +1487,50 @@ declare class Canvas<TInput extends ZodTypeOrRecord, TOutput extends ZodTypeOrRe
      * ).result) {
      *   console.log(chunk);
      * }
+     *
+     * // Execution with tags
+     * const result = await canvas.execute(
+     *   { query: "Hello" },
+     *   { tags: ["production", "analytics"] }
+     * ).result;
      * ```
      */
-    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>>;
+    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>>;
+    /**
+     * 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()
+     * ```
+     */
+    getExecution(id: string, options?: {
+        pollingInterval?: number;
+        pollingTimeout?: number;
+    }): Promise<CanvasExecution<AsyncExecutionParams, unknown, Output<TOutput>>>;
 }
 
 /**
@@ -990,20 +1600,22 @@ declare class TelaSDK extends BaseClient {
     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.
+     * Validates input and output schemas if provided via schema builder functions.
      *
      * @param options - Options for retrieving the canvas.
      * @returns A promise resolving to a Canvas instance.
      *
      * @example
      * ```typescript
-     * 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() })
+     *   input: schema => schema.object({
+     *     query: schema.string()
+     *   }),
+     *   output: schema => schema.object({
+     *     response: schema.string()
+     *   })
      * });
      *
      * // Get canvas by application ID
@@ -1017,7 +1629,7 @@ declare class TelaSDK extends BaseClient {
      * ```
      */
     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>>;
+        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;