@meistrari/tela-sdk-js 2.3.1 → 2.3.2

package/README.md

@@ -171,12 +171,13 @@ execution.on('statusChange', (status) => {
 
 // Listen for polling updates
 execution.on('poll', (pollResult) => {
-    console.log(`Poll - Status: ${pollResult.status}`)
+    console.log(`Poll - Status: ${pollResult.status}, Request ID: ${pollResult.requestId}`)
 })
 
 // Listen for successful completion
 execution.on('success', (result) => {
     console.log('Success!', result)
+    console.log('Request ID:', result.requestId)
 })
 
 // Listen for errors (prevents throwing)
@@ -218,6 +219,53 @@ Status is set to `succeeded` only after successful validation. If validation fai
 
 See [Event Examples](./examples/events/) for detailed usage patterns.
 
+#### Accessing Request IDs
+
+Every API request to Tela returns a unique `requestId` (from the `x-request-id` header) that can be used for debugging, tracking, and correlating with server logs. The SDK exposes request IDs in three ways:
+
+```typescript
+const canvas = await tela.canvas.get({ id: 'canvas-id' })
+
+// Start an async execution
+const execution = await canvas.execute(
+    { query: 'test' },
+    { async: true }
+)
+
+// Method 1: Access directly from execution object
+// This is the request ID from the initial request that created the execution
+const requestId = await execution.requestId
+console.log('Request ID:', requestId)
+
+// Method 2: Access from poll events
+// Each poll event includes the request ID from that specific polling request
+execution.on('poll', (pollResult) => {
+    console.log('Request ID from this poll:', pollResult.requestId)
+})
+
+// Method 3: Access from success event
+// The success event includes the request ID from the final successful polling request
+execution.on('success', (result) => {
+    console.log('Request ID from final request:', result.requestId)
+})
+
+// Start polling
+execution.poll()
+```
+
+**Important Notes:**
+- `execution.requestId` - Request ID from the execution creation request (POST /v2/chat/completions)
+- `pollResult.requestId` - Request ID from each individual polling request (GET /v2/chat/completions/:id)
+- `result.requestId` - Request ID from the final successful polling request
+
+**Use Cases:**
+- **Debugging**: Identify specific API requests when troubleshooting issues
+- **Logging**: Track individual requests across distributed systems
+- **Support**: Reference specific requests in support tickets
+- **Monitoring**: Correlate client requests with server logs and traces
+
+See [Request ID Example](./examples/events/request-id.ts) for a complete demonstration.
+
 #### Schema Validation
 
 The Canvas API validates your inputs and outputs against the server schema:

package/dist/index.cjs

@@ -24,7 +24,7 @@ const z__default = /*#__PURE__*/_interopDefaultCompat(z);
 const z__namespace = /*#__PURE__*/_interopNamespaceCompat(z);
 const Emittery__default = /*#__PURE__*/_interopDefaultCompat(Emittery);
 
-const version = "2.3.1";
+const version = "2.3.2";
 
 var __defProp$7 = Object.defineProperty;
 var __defNormalProp$7 = (obj, key, value) => key in obj ? __defProp$7(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -319,13 +319,10 @@ class Stream {
    * @param iterator - A function that returns an AsyncIterator<Item>.
    * @param controller - The AbortController for this stream.
    */
-  constructor(iterator, controller) {
+  constructor(iterator, controller, requestId) {
     this.iterator = iterator;
-    /**
-     * The AbortController associated with this stream.
-     */
-    __publicField$6(this, "controller");
     this.controller = controller;
+    this.requestId = requestId;
   }
   /**
    * Creates a Stream from a server-sent events (SSE) Response.
@@ -399,7 +396,8 @@ class Stream {
           controller.abort();
       }
     }
-    return new Stream(iterator, controller);
+    const requestId = response.headers.get("x-request-id") || response.headers.get("request-id") || "";
+    return new Stream(iterator, controller, requestId);
   }
   /**
    * Creates a Stream from a newline-separated ReadableStream where each item is a JSON value.
@@ -739,31 +737,41 @@ var __publicField$5 = (obj, key, value) => {
   __defNormalProp$5(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-function tryGetResponseHeaders(response) {
+function getRequestIdFromResponse(response) {
   try {
+    if (typeof response.headers.get === "function") {
+      return response.headers.get("x-request-id") || void 0;
+    }
     if (typeof response.headers.toJSON === "function") {
-      return response.headers.toJSON();
+      const headers = response.headers.toJSON();
+      return headers["x-request-id"] || void 0;
     }
     if ("entries" in response.headers && typeof response.headers.entries === "function") {
-      return Object.fromEntries(response.headers.entries());
+      for (const [key, value] of response.headers.entries()) {
+        if (key.toLowerCase() === "x-request-id") {
+          return value;
+        }
+      }
     }
     if (typeof response.headers.forEach === "function") {
-      const headers = {};
+      let requestId;
       response.headers.forEach((value, key) => {
-        headers[key] = value;
+        if (key.toLowerCase() === "x-request-id") {
+          requestId = value;
+        }
       });
-      return headers;
+      return requestId;
     }
     if (response.headers && typeof response.headers[Symbol.iterator] === "function") {
-      const headers = {};
       for (const [key, value] of response.headers) {
-        headers[key] = value;
+        if (key.toLowerCase() === "x-request-id") {
+          return value;
+        }
       }
-      return headers;
     }
-    return {};
+    return void 0;
   } catch {
-    return {};
+    return void 0;
   }
 }
 async function defaultParseResponse(props) {
@@ -780,7 +788,12 @@ async function defaultParseResponse(props) {
   if (isJSON) {
     const json = await response.json();
     debug("response", response.status, response.url, response.headers, json);
-    return transformObjectFromSnakeCaseToCamelCase({ ...json, headers: tryGetResponseHeaders(response) }, DEFAULT_FIELDS_TRANSFORMATION_EXCLUSIONS);
+    const requestId = getRequestIdFromResponse(response);
+    const finalJson = { ...json };
+    if (requestId) {
+      finalJson.requestId = requestId;
+    }
+    return transformObjectFromSnakeCaseToCamelCase(finalJson, DEFAULT_FIELDS_TRANSFORMATION_EXCLUSIONS);
   }
   const text = await response.text();
   debug("response", response.status, response.url, response.headers, text);
@@ -1567,6 +1580,7 @@ class CanvasExecution extends Emittery__default {
     __publicField$2(this, "_resultPromise");
     __publicField$2(this, "_stream");
     __publicField$2(this, "_rawResultValue");
+    __publicField$2(this, "_requestId");
     this._variables = variables;
     this._params = params;
     this._outputSchema = outputSchema;
@@ -1662,6 +1676,53 @@ class CanvasExecution extends Emittery__default {
     }
     return this._id;
   }
+  /**
+   * Gets the request ID from the `x-request-id` header of the execution creation request.
+   *
+   * This is the request ID from the initial POST /v2/chat/completions request that created
+   * the execution. Each API request has its own unique request ID.
+   *
+   * For async executions, different request IDs are available:
+   * - `execution.requestId` - ID from the execution creation request
+   * - `pollResult.requestId` - ID from each polling request (in poll events)
+   * - `result.requestId` - ID from the final successful polling request (in success events)
+   *
+   * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+   * @returns A promise that resolves to the request ID from the execution creation request.
+   *
+   * @example
+   * ```typescript
+   * const execution = await canvas.execute({ query: 'test' })
+   * const requestId = await execution.requestId
+   * console.log('Request ID:', requestId)
+   * ```
+   *
+   * @example Accessing different request IDs in async executions
+   * ```typescript
+   * const execution = await canvas.execute({ query: 'test' }, { async: true })
+   *
+   * // Request ID from execution creation
+   * const creationRequestId = await execution.requestId
+   *
+   * // Request IDs from polling
+   * execution.on('poll', (pollResult) => {
+   *   console.log('Poll request ID:', pollResult.requestId)
+   * })
+   *
+   * // Request ID from final result
+   * execution.on('success', (result) => {
+   *   console.log('Final request ID:', result.requestId)
+   * })
+   *
+   * execution.poll()
+   * ```
+   */
+  get requestId() {
+    if (!this._requestId) {
+      throw new ExecutionNotStartedError();
+    }
+    return this._requestId;
+  }
   /**
    * Gets the latest known status of the execution.
    *
@@ -1946,31 +2007,48 @@ class CanvasExecution extends Emittery__default {
     return variables;
   }
   /**
-   * 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.
+   * Creates an execution on the server by making a POST request to /v2/chat/completions.
+   * This method is shared between sync, async, and streaming execution modes.
+   * Automatically sets the _requestId property from response headers.
+   *
+   * @template TResponse - The expected response type (sync, async, or stream).
+   * @param resolvedVariables - The processed variables with uploaded files.
+   * @param options - Execution options.
+   * @param options.async - Whether to create an async execution.
+   * @param options.stream - Whether to create a streaming execution.
+   * @returns A promise resolving to the execution creation response or stream.
    */
-  async startSync() {
-    const resolvedVariables = await this.resolveVariables();
+  async create(resolvedVariables, options = {}) {
     const body = {
-      async: this._params.async ?? false,
-      stream: false,
+      async: options.async ?? false,
+      stream: options.stream ?? false,
       ...this.baseBody,
       variables: resolvedVariables
     };
-    this._resultPromise = this._client.post("/v2/chat/completions", {
+    const responsePromise = this._client.post("/v2/chat/completions", {
       body,
-      stream: false,
+      stream: options.stream ?? false,
       signal: this._abortController.signal
-    }).then((response) => {
+    });
+    this._requestId = responsePromise.then((response) => response?.requestId || "").catch(() => "");
+    return await responsePromise;
+  }
+  /**
+   * 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.
+   */
+  async startSync() {
+    const resolvedVariables = await this.resolveVariables();
+    this._resultPromise = this.create(resolvedVariables, { async: false }).then((response) => {
       this._id = response.id;
       this._rawResultValue = response;
       return { content: getResultFromPollingResponse(response), response };
     }).then(({ content, response }) => {
       const validatedContent = this._skipResultValidation || !(this._outputSchema instanceof z__default.ZodType) ? content : this._outputSchema.parse(content);
       this.status = "succeeded";
-      this.emit("success", { ...validatedContent, headers: response?.headers ?? {} });
+      this.emit("success", { ...validatedContent, requestId: response?.requestId });
       return validatedContent;
     }).catch((error) => {
       this.status = "failed";
@@ -1990,17 +2068,7 @@ class CanvasExecution extends Emittery__default {
    */
   async startAsync() {
     const resolvedVariables = await this.resolveVariables();
-    const body = {
-      async: true,
-      stream: false,
-      ...this.baseBody,
-      variables: resolvedVariables
-    };
-    return await this._client.post("/v2/chat/completions", {
-      body,
-      stream: false,
-      signal: this._abortController.signal
-    }).then((response) => {
+    return await this.create(resolvedVariables, { async: true }).then((response) => {
       this._id = response.id;
       this.status = response.status;
       this.emit("poll", {
@@ -2008,7 +2076,7 @@ class CanvasExecution extends Emittery__default {
         status: response.status,
         outputContent: response.output_content,
         rawOutput: response.raw_output,
-        headers: response.headers
+        requestId: response.requestId
       });
       return response;
     });
@@ -2020,16 +2088,7 @@ class CanvasExecution extends Emittery__default {
    */
   async startStream() {
     const resolvedVariables = await this.resolveVariables();
-    const body = {
-      ...this.baseBody,
-      stream: true,
-      variables: resolvedVariables
-    };
-    this._stream = await this._client.post("/v2/chat/completions", {
-      body,
-      stream: true,
-      signal: this._abortController.signal
-    });
+    this._stream = await this.create(resolvedVariables, { stream: true });
     this.status = "streaming";
     return this._stream;
   }
@@ -2073,7 +2132,7 @@ class CanvasExecution extends Emittery__default {
         };
       }
       this._rawResultValue = response;
-      this.emit("success", { ...getResultFromPollingResponse(response), headers: response?.headers ?? {} });
+      this.emit("success", { ...getResultFromPollingResponse(response), requestId: response?.requestId });
       return {
         done: response.status === "succeeded",
         value: getResultFromPollingResponse(response)

package/dist/index.d.cts

@@ -620,6 +620,17 @@ type AsyncCompletionCreateResult = {
  * This type will be refined in future versions with proper typing.
  */
 type RawAPIResult = any;
+/**
+ * Helper type to add request ID to a response type.
+ *
+ * The `requestId` field contains the value from the `x-request-id` HTTP header
+ * returned by the API for that specific request.
+ *
+ * @template T - The base response type.
+ */
+type WithRequestId<T> = T & {
+    requestId?: string;
+};
 /**
  * Result returned when polling for asynchronous execution status.
  *
@@ -662,13 +673,21 @@ 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>;
+/**
+ * Event types emitted by CanvasExecution during its lifecycle.
+ *
+ * @template TOutput - The output type.
+ *
+ * @property poll - Emitted during async polling with current status and output. Includes `requestId` from the polling request.
+ * @property success - Emitted when execution completes successfully with the final result. Includes `requestId` from the final request.
+ * @property error - Emitted when execution fails with the error object.
+ * @property statusChange - Emitted when execution status transitions to a new state.
+ *
+ * @category Canvas
+ */
 type CanvasExecutionEvents<TOutput> = {
-    poll: AsyncCompletionPollingResult<TOutput> & {
-        headers: Record<string, string>;
-    };
-    success: TOutput & {
-        headers: Record<string, string>;
-    };
+    poll: WithRequestId<AsyncCompletionPollingResult<TOutput>>;
+    success: WithRequestId<TOutput>;
     error: ExecutionFailedError;
     statusChange: ExecutionStatus;
 };
@@ -701,8 +720,8 @@ type CanvasExecutionEvents<TOutput> = {
  * @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 poll - Emitted during async polling with current status and output. Includes `requestId` from the polling request. (async executions only)
+ * @fires success - Emitted when execution completes successfully with the final result. Includes `requestId` from the final request.
  * @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
  *
@@ -734,6 +753,7 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
     private _resultPromise;
     private _stream;
     private _rawResultValue;
+    private _requestId;
     /**
      * Creates a new canvas execution instance.
      *
@@ -784,6 +804,48 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * @returns The execution ID.
      */
     get id(): string;
+    /**
+     * Gets the request ID from the `x-request-id` header of the execution creation request.
+     *
+     * This is the request ID from the initial POST /v2/chat/completions request that created
+     * the execution. Each API request has its own unique request ID.
+     *
+     * For async executions, different request IDs are available:
+     * - `execution.requestId` - ID from the execution creation request
+     * - `pollResult.requestId` - ID from each polling request (in poll events)
+     * - `result.requestId` - ID from the final successful polling request (in success events)
+     *
+     * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+     * @returns A promise that resolves to the request ID from the execution creation request.
+     *
+     * @example
+     * ```typescript
+     * const execution = await canvas.execute({ query: 'test' })
+     * const requestId = await execution.requestId
+     * console.log('Request ID:', requestId)
+     * ```
+     *
+     * @example Accessing different request IDs in async executions
+     * ```typescript
+     * const execution = await canvas.execute({ query: 'test' }, { async: true })
+     *
+     * // Request ID from execution creation
+     * const creationRequestId = await execution.requestId
+     *
+     * // Request IDs from polling
+     * execution.on('poll', (pollResult) => {
+     *   console.log('Poll request ID:', pollResult.requestId)
+     * })
+     *
+     * // Request ID from final result
+     * execution.on('success', (result) => {
+     *   console.log('Final request ID:', result.requestId)
+     * })
+     *
+     * execution.poll()
+     * ```
+     */
+    get requestId(): Promise<string>;
     /**
      * Gets the latest known status of the execution.
      *
@@ -871,9 +933,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<AsyncCompletionCreateResult & {
-        headers: Record<string, string>;
-    }>;
+    start(): Promise<CanvasExecutionResult<TParams, TOutput>> | AsyncGenerator<Partial<TOutput>, any, any> | Promise<AsyncGenerator<Partial<TOutput>, any, any>> | Promise<WithRequestId<AsyncCompletionCreateResult>>;
     /**
      * Gets the execution result. For async executions, automatically starts polling.
      * For sync executions, returns the result promise. For streams, returns the generator.
@@ -949,6 +1009,19 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * @returns A promise resolving to the processed variables object.
      */
     private resolveVariables;
+    /**
+     * Creates an execution on the server by making a POST request to /v2/chat/completions.
+     * This method is shared between sync, async, and streaming execution modes.
+     * Automatically sets the _requestId property from response headers.
+     *
+     * @template TResponse - The expected response type (sync, async, or stream).
+     * @param resolvedVariables - The processed variables with uploaded files.
+     * @param options - Execution options.
+     * @param options.async - Whether to create an async execution.
+     * @param options.stream - Whether to create a streaming execution.
+     * @returns A promise resolving to the execution creation response or stream.
+     */
+    private create;
     /**
      * Initiates a synchronous execution that waits for the complete result.
      * The result is validated against the output schema if provided.

package/dist/index.d.mts

@@ -620,6 +620,17 @@ type AsyncCompletionCreateResult = {
  * This type will be refined in future versions with proper typing.
  */
 type RawAPIResult = any;
+/**
+ * Helper type to add request ID to a response type.
+ *
+ * The `requestId` field contains the value from the `x-request-id` HTTP header
+ * returned by the API for that specific request.
+ *
+ * @template T - The base response type.
+ */
+type WithRequestId<T> = T & {
+    requestId?: string;
+};
 /**
  * Result returned when polling for asynchronous execution status.
  *
@@ -662,13 +673,21 @@ 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>;
+/**
+ * Event types emitted by CanvasExecution during its lifecycle.
+ *
+ * @template TOutput - The output type.
+ *
+ * @property poll - Emitted during async polling with current status and output. Includes `requestId` from the polling request.
+ * @property success - Emitted when execution completes successfully with the final result. Includes `requestId` from the final request.
+ * @property error - Emitted when execution fails with the error object.
+ * @property statusChange - Emitted when execution status transitions to a new state.
+ *
+ * @category Canvas
+ */
 type CanvasExecutionEvents<TOutput> = {
-    poll: AsyncCompletionPollingResult<TOutput> & {
-        headers: Record<string, string>;
-    };
-    success: TOutput & {
-        headers: Record<string, string>;
-    };
+    poll: WithRequestId<AsyncCompletionPollingResult<TOutput>>;
+    success: WithRequestId<TOutput>;
     error: ExecutionFailedError;
     statusChange: ExecutionStatus;
 };
@@ -701,8 +720,8 @@ type CanvasExecutionEvents<TOutput> = {
  * @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 poll - Emitted during async polling with current status and output. Includes `requestId` from the polling request. (async executions only)
+ * @fires success - Emitted when execution completes successfully with the final result. Includes `requestId` from the final request.
  * @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
  *
@@ -734,6 +753,7 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
     private _resultPromise;
     private _stream;
     private _rawResultValue;
+    private _requestId;
     /**
      * Creates a new canvas execution instance.
      *
@@ -784,6 +804,48 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * @returns The execution ID.
      */
     get id(): string;
+    /**
+     * Gets the request ID from the `x-request-id` header of the execution creation request.
+     *
+     * This is the request ID from the initial POST /v2/chat/completions request that created
+     * the execution. Each API request has its own unique request ID.
+     *
+     * For async executions, different request IDs are available:
+     * - `execution.requestId` - ID from the execution creation request
+     * - `pollResult.requestId` - ID from each polling request (in poll events)
+     * - `result.requestId` - ID from the final successful polling request (in success events)
+     *
+     * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+     * @returns A promise that resolves to the request ID from the execution creation request.
+     *
+     * @example
+     * ```typescript
+     * const execution = await canvas.execute({ query: 'test' })
+     * const requestId = await execution.requestId
+     * console.log('Request ID:', requestId)
+     * ```
+     *
+     * @example Accessing different request IDs in async executions
+     * ```typescript
+     * const execution = await canvas.execute({ query: 'test' }, { async: true })
+     *
+     * // Request ID from execution creation
+     * const creationRequestId = await execution.requestId
+     *
+     * // Request IDs from polling
+     * execution.on('poll', (pollResult) => {
+     *   console.log('Poll request ID:', pollResult.requestId)
+     * })
+     *
+     * // Request ID from final result
+     * execution.on('success', (result) => {
+     *   console.log('Final request ID:', result.requestId)
+     * })
+     *
+     * execution.poll()
+     * ```
+     */
+    get requestId(): Promise<string>;
     /**
      * Gets the latest known status of the execution.
      *
@@ -871,9 +933,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<AsyncCompletionCreateResult & {
-        headers: Record<string, string>;
-    }>;
+    start(): Promise<CanvasExecutionResult<TParams, TOutput>> | AsyncGenerator<Partial<TOutput>, any, any> | Promise<AsyncGenerator<Partial<TOutput>, any, any>> | Promise<WithRequestId<AsyncCompletionCreateResult>>;
     /**
      * Gets the execution result. For async executions, automatically starts polling.
      * For sync executions, returns the result promise. For streams, returns the generator.
@@ -949,6 +1009,19 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * @returns A promise resolving to the processed variables object.
      */
     private resolveVariables;
+    /**
+     * Creates an execution on the server by making a POST request to /v2/chat/completions.
+     * This method is shared between sync, async, and streaming execution modes.
+     * Automatically sets the _requestId property from response headers.
+     *
+     * @template TResponse - The expected response type (sync, async, or stream).
+     * @param resolvedVariables - The processed variables with uploaded files.
+     * @param options - Execution options.
+     * @param options.async - Whether to create an async execution.
+     * @param options.stream - Whether to create a streaming execution.
+     * @returns A promise resolving to the execution creation response or stream.
+     */
+    private create;
     /**
      * Initiates a synchronous execution that waits for the complete result.
      * The result is validated against the output schema if provided.

package/dist/index.d.ts

@@ -620,6 +620,17 @@ type AsyncCompletionCreateResult = {
  * This type will be refined in future versions with proper typing.
  */
 type RawAPIResult = any;
+/**
+ * Helper type to add request ID to a response type.
+ *
+ * The `requestId` field contains the value from the `x-request-id` HTTP header
+ * returned by the API for that specific request.
+ *
+ * @template T - The base response type.
+ */
+type WithRequestId<T> = T & {
+    requestId?: string;
+};
 /**
  * Result returned when polling for asynchronous execution status.
  *
@@ -662,13 +673,21 @@ 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>;
+/**
+ * Event types emitted by CanvasExecution during its lifecycle.
+ *
+ * @template TOutput - The output type.
+ *
+ * @property poll - Emitted during async polling with current status and output. Includes `requestId` from the polling request.
+ * @property success - Emitted when execution completes successfully with the final result. Includes `requestId` from the final request.
+ * @property error - Emitted when execution fails with the error object.
+ * @property statusChange - Emitted when execution status transitions to a new state.
+ *
+ * @category Canvas
+ */
 type CanvasExecutionEvents<TOutput> = {
-    poll: AsyncCompletionPollingResult<TOutput> & {
-        headers: Record<string, string>;
-    };
-    success: TOutput & {
-        headers: Record<string, string>;
-    };
+    poll: WithRequestId<AsyncCompletionPollingResult<TOutput>>;
+    success: WithRequestId<TOutput>;
     error: ExecutionFailedError;
     statusChange: ExecutionStatus;
 };
@@ -701,8 +720,8 @@ type CanvasExecutionEvents<TOutput> = {
  * @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 poll - Emitted during async polling with current status and output. Includes `requestId` from the polling request. (async executions only)
+ * @fires success - Emitted when execution completes successfully with the final result. Includes `requestId` from the final request.
  * @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
  *
@@ -734,6 +753,7 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
     private _resultPromise;
     private _stream;
     private _rawResultValue;
+    private _requestId;
     /**
      * Creates a new canvas execution instance.
      *
@@ -784,6 +804,48 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * @returns The execution ID.
      */
     get id(): string;
+    /**
+     * Gets the request ID from the `x-request-id` header of the execution creation request.
+     *
+     * This is the request ID from the initial POST /v2/chat/completions request that created
+     * the execution. Each API request has its own unique request ID.
+     *
+     * For async executions, different request IDs are available:
+     * - `execution.requestId` - ID from the execution creation request
+     * - `pollResult.requestId` - ID from each polling request (in poll events)
+     * - `result.requestId` - ID from the final successful polling request (in success events)
+     *
+     * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+     * @returns A promise that resolves to the request ID from the execution creation request.
+     *
+     * @example
+     * ```typescript
+     * const execution = await canvas.execute({ query: 'test' })
+     * const requestId = await execution.requestId
+     * console.log('Request ID:', requestId)
+     * ```
+     *
+     * @example Accessing different request IDs in async executions
+     * ```typescript
+     * const execution = await canvas.execute({ query: 'test' }, { async: true })
+     *
+     * // Request ID from execution creation
+     * const creationRequestId = await execution.requestId
+     *
+     * // Request IDs from polling
+     * execution.on('poll', (pollResult) => {
+     *   console.log('Poll request ID:', pollResult.requestId)
+     * })
+     *
+     * // Request ID from final result
+     * execution.on('success', (result) => {
+     *   console.log('Final request ID:', result.requestId)
+     * })
+     *
+     * execution.poll()
+     * ```
+     */
+    get requestId(): Promise<string>;
     /**
      * Gets the latest known status of the execution.
      *
@@ -871,9 +933,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<AsyncCompletionCreateResult & {
-        headers: Record<string, string>;
-    }>;
+    start(): Promise<CanvasExecutionResult<TParams, TOutput>> | AsyncGenerator<Partial<TOutput>, any, any> | Promise<AsyncGenerator<Partial<TOutput>, any, any>> | Promise<WithRequestId<AsyncCompletionCreateResult>>;
     /**
      * Gets the execution result. For async executions, automatically starts polling.
      * For sync executions, returns the result promise. For streams, returns the generator.
@@ -949,6 +1009,19 @@ declare class CanvasExecution<TParams extends ExecutionParams = SyncExecutionPar
      * @returns A promise resolving to the processed variables object.
      */
     private resolveVariables;
+    /**
+     * Creates an execution on the server by making a POST request to /v2/chat/completions.
+     * This method is shared between sync, async, and streaming execution modes.
+     * Automatically sets the _requestId property from response headers.
+     *
+     * @template TResponse - The expected response type (sync, async, or stream).
+     * @param resolvedVariables - The processed variables with uploaded files.
+     * @param options - Execution options.
+     * @param options.async - Whether to create an async execution.
+     * @param options.stream - Whether to create a streaming execution.
+     * @returns A promise resolving to the execution creation response or stream.
+     */
+    private create;
     /**
      * Initiates a synchronous execution that waits for the complete result.
      * The result is validated against the output schema if provided.

package/dist/index.mjs

@@ -4,7 +4,7 @@ import * as z from 'zod';
 import z__default, { z as z$1, ZodError } from 'zod';
 import Emittery from 'emittery';
 
-const version = "2.3.1";
+const version = "2.3.2";
 
 var __defProp$7 = Object.defineProperty;
 var __defNormalProp$7 = (obj, key, value) => key in obj ? __defProp$7(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -299,13 +299,10 @@ class Stream {
    * @param iterator - A function that returns an AsyncIterator<Item>.
    * @param controller - The AbortController for this stream.
    */
-  constructor(iterator, controller) {
+  constructor(iterator, controller, requestId) {
     this.iterator = iterator;
-    /**
-     * The AbortController associated with this stream.
-     */
-    __publicField$6(this, "controller");
     this.controller = controller;
+    this.requestId = requestId;
   }
   /**
    * Creates a Stream from a server-sent events (SSE) Response.
@@ -379,7 +376,8 @@ class Stream {
           controller.abort();
       }
     }
-    return new Stream(iterator, controller);
+    const requestId = response.headers.get("x-request-id") || response.headers.get("request-id") || "";
+    return new Stream(iterator, controller, requestId);
   }
   /**
    * Creates a Stream from a newline-separated ReadableStream where each item is a JSON value.
@@ -719,31 +717,41 @@ var __publicField$5 = (obj, key, value) => {
   __defNormalProp$5(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-function tryGetResponseHeaders(response) {
+function getRequestIdFromResponse(response) {
   try {
+    if (typeof response.headers.get === "function") {
+      return response.headers.get("x-request-id") || void 0;
+    }
     if (typeof response.headers.toJSON === "function") {
-      return response.headers.toJSON();
+      const headers = response.headers.toJSON();
+      return headers["x-request-id"] || void 0;
     }
     if ("entries" in response.headers && typeof response.headers.entries === "function") {
-      return Object.fromEntries(response.headers.entries());
+      for (const [key, value] of response.headers.entries()) {
+        if (key.toLowerCase() === "x-request-id") {
+          return value;
+        }
+      }
     }
     if (typeof response.headers.forEach === "function") {
-      const headers = {};
+      let requestId;
       response.headers.forEach((value, key) => {
-        headers[key] = value;
+        if (key.toLowerCase() === "x-request-id") {
+          requestId = value;
+        }
       });
-      return headers;
+      return requestId;
     }
     if (response.headers && typeof response.headers[Symbol.iterator] === "function") {
-      const headers = {};
       for (const [key, value] of response.headers) {
-        headers[key] = value;
+        if (key.toLowerCase() === "x-request-id") {
+          return value;
+        }
       }
-      return headers;
     }
-    return {};
+    return void 0;
   } catch {
-    return {};
+    return void 0;
   }
 }
 async function defaultParseResponse(props) {
@@ -760,7 +768,12 @@ async function defaultParseResponse(props) {
   if (isJSON) {
     const json = await response.json();
     debug("response", response.status, response.url, response.headers, json);
-    return transformObjectFromSnakeCaseToCamelCase({ ...json, headers: tryGetResponseHeaders(response) }, DEFAULT_FIELDS_TRANSFORMATION_EXCLUSIONS);
+    const requestId = getRequestIdFromResponse(response);
+    const finalJson = { ...json };
+    if (requestId) {
+      finalJson.requestId = requestId;
+    }
+    return transformObjectFromSnakeCaseToCamelCase(finalJson, DEFAULT_FIELDS_TRANSFORMATION_EXCLUSIONS);
   }
   const text = await response.text();
   debug("response", response.status, response.url, response.headers, text);
@@ -1547,6 +1560,7 @@ class CanvasExecution extends Emittery {
     __publicField$2(this, "_resultPromise");
     __publicField$2(this, "_stream");
     __publicField$2(this, "_rawResultValue");
+    __publicField$2(this, "_requestId");
     this._variables = variables;
     this._params = params;
     this._outputSchema = outputSchema;
@@ -1642,6 +1656,53 @@ class CanvasExecution extends Emittery {
     }
     return this._id;
   }
+  /**
+   * Gets the request ID from the `x-request-id` header of the execution creation request.
+   *
+   * This is the request ID from the initial POST /v2/chat/completions request that created
+   * the execution. Each API request has its own unique request ID.
+   *
+   * For async executions, different request IDs are available:
+   * - `execution.requestId` - ID from the execution creation request
+   * - `pollResult.requestId` - ID from each polling request (in poll events)
+   * - `result.requestId` - ID from the final successful polling request (in success events)
+   *
+   * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+   * @returns A promise that resolves to the request ID from the execution creation request.
+   *
+   * @example
+   * ```typescript
+   * const execution = await canvas.execute({ query: 'test' })
+   * const requestId = await execution.requestId
+   * console.log('Request ID:', requestId)
+   * ```
+   *
+   * @example Accessing different request IDs in async executions
+   * ```typescript
+   * const execution = await canvas.execute({ query: 'test' }, { async: true })
+   *
+   * // Request ID from execution creation
+   * const creationRequestId = await execution.requestId
+   *
+   * // Request IDs from polling
+   * execution.on('poll', (pollResult) => {
+   *   console.log('Poll request ID:', pollResult.requestId)
+   * })
+   *
+   * // Request ID from final result
+   * execution.on('success', (result) => {
+   *   console.log('Final request ID:', result.requestId)
+   * })
+   *
+   * execution.poll()
+   * ```
+   */
+  get requestId() {
+    if (!this._requestId) {
+      throw new ExecutionNotStartedError();
+    }
+    return this._requestId;
+  }
   /**
    * Gets the latest known status of the execution.
    *
@@ -1926,31 +1987,48 @@ class CanvasExecution extends Emittery {
     return variables;
   }
   /**
-   * 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.
+   * Creates an execution on the server by making a POST request to /v2/chat/completions.
+   * This method is shared between sync, async, and streaming execution modes.
+   * Automatically sets the _requestId property from response headers.
+   *
+   * @template TResponse - The expected response type (sync, async, or stream).
+   * @param resolvedVariables - The processed variables with uploaded files.
+   * @param options - Execution options.
+   * @param options.async - Whether to create an async execution.
+   * @param options.stream - Whether to create a streaming execution.
+   * @returns A promise resolving to the execution creation response or stream.
    */
-  async startSync() {
-    const resolvedVariables = await this.resolveVariables();
+  async create(resolvedVariables, options = {}) {
     const body = {
-      async: this._params.async ?? false,
-      stream: false,
+      async: options.async ?? false,
+      stream: options.stream ?? false,
       ...this.baseBody,
       variables: resolvedVariables
     };
-    this._resultPromise = this._client.post("/v2/chat/completions", {
+    const responsePromise = this._client.post("/v2/chat/completions", {
       body,
-      stream: false,
+      stream: options.stream ?? false,
       signal: this._abortController.signal
-    }).then((response) => {
+    });
+    this._requestId = responsePromise.then((response) => response?.requestId || "").catch(() => "");
+    return await responsePromise;
+  }
+  /**
+   * 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.
+   */
+  async startSync() {
+    const resolvedVariables = await this.resolveVariables();
+    this._resultPromise = this.create(resolvedVariables, { async: false }).then((response) => {
       this._id = response.id;
       this._rawResultValue = response;
       return { content: getResultFromPollingResponse(response), response };
     }).then(({ content, response }) => {
       const validatedContent = this._skipResultValidation || !(this._outputSchema instanceof z__default.ZodType) ? content : this._outputSchema.parse(content);
       this.status = "succeeded";
-      this.emit("success", { ...validatedContent, headers: response?.headers ?? {} });
+      this.emit("success", { ...validatedContent, requestId: response?.requestId });
       return validatedContent;
     }).catch((error) => {
       this.status = "failed";
@@ -1970,17 +2048,7 @@ class CanvasExecution extends Emittery {
    */
   async startAsync() {
     const resolvedVariables = await this.resolveVariables();
-    const body = {
-      async: true,
-      stream: false,
-      ...this.baseBody,
-      variables: resolvedVariables
-    };
-    return await this._client.post("/v2/chat/completions", {
-      body,
-      stream: false,
-      signal: this._abortController.signal
-    }).then((response) => {
+    return await this.create(resolvedVariables, { async: true }).then((response) => {
       this._id = response.id;
       this.status = response.status;
       this.emit("poll", {
@@ -1988,7 +2056,7 @@ class CanvasExecution extends Emittery {
         status: response.status,
         outputContent: response.output_content,
         rawOutput: response.raw_output,
-        headers: response.headers
+        requestId: response.requestId
       });
       return response;
     });
@@ -2000,16 +2068,7 @@ class CanvasExecution extends Emittery {
    */
   async startStream() {
     const resolvedVariables = await this.resolveVariables();
-    const body = {
-      ...this.baseBody,
-      stream: true,
-      variables: resolvedVariables
-    };
-    this._stream = await this._client.post("/v2/chat/completions", {
-      body,
-      stream: true,
-      signal: this._abortController.signal
-    });
+    this._stream = await this.create(resolvedVariables, { stream: true });
     this.status = "streaming";
     return this._stream;
   }
@@ -2053,7 +2112,7 @@ class CanvasExecution extends Emittery {
         };
       }
       this._rawResultValue = response;
-      this.emit("success", { ...getResultFromPollingResponse(response), headers: response?.headers ?? {} });
+      this.emit("success", { ...getResultFromPollingResponse(response), requestId: response?.requestId });
       return {
         done: response.status === "succeeded",
         value: getResultFromPollingResponse(response)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-sdk-js",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/meistrari/tela-sdk-js.git"