@llamaindex/llama-cloud 2.3.0 → 2.4.1

package/resources/retrievers/retrievers.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"retrievers.mjs","sourceRoot":"","sources":["../../src/resources/retrievers/retrievers.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,KAAK,YAAY;OAEjB,EAAE,YAAY,EAAE;OAEhB,EAAE,IAAI,EAAE;AAEf,MAAM,OAAO,UAAW,SAAQ,WAAW;IAA3C;;QACE,cAAS,GAA2B,IAAI,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IA2E/E,CAAC;IAzEC;;OAEG;IACH,MAAM,CAAC,MAA6B,EAAE,OAAwB;QAC5D,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE;YAC7C,KAAK,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;YACtC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAmB,EAAE,IAA2B,EAAE,OAAwB;QAC/E,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,sBAAsB,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,CAAC;IAED;;OAEG;IACH,IAAI,CACF,QAAgD,EAAE,EAClD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAmB,EAAE,OAAwB;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,sBAAsB,WAAW,EAAE,EAAE;YAClE,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,GAAG,CACD,WAAmB,EACnB,QAA+C,EAAE,EACjD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,sBAAsB,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC1F,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAA6B,EAAE,OAAwB;QAC5D,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,6BAA6B,EAAE;YACtD,KAAK,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;YACtC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAA6B,EAAE,OAAwB;QAC5D,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE;YAC5C,KAAK,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;YACtC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"retrievers.mjs","sourceRoot":"","sources":["../../src/resources/retrievers/retrievers.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,KAAK,YAAY;OAEjB,EAAE,YAAY,EAAE;OAEhB,EAAE,IAAI,EAAE;AAEf,MAAM,OAAO,UAAW,SAAQ,WAAW;IAA3C;;QACE,cAAS,GAA2B,IAAI,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IA0F/E,CAAC;IAxFC;;OAEG;IACH,MAAM,CAAC,MAA6B,EAAE,OAAwB;QAC5D,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE;YAC7C,KAAK,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;YACtC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CACJ,WAAmB,EACnB,MAA6B,EAC7B,OAAwB;QAExB,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,sBAAsB,WAAW,EAAE,EAAE;YAC/D,KAAK,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;YACtC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,IAAI,CACF,QAAgD,EAAE,EAClD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvE,CAAC;IAED;;OAEG;IACH,MAAM,CACJ,WAAmB,EACnB,SAAmD,EAAE,EACrD,OAAwB;QAExB,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,MAAM,IAAI,EAAE,CAAC;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,sBAAsB,WAAW,EAAE,EAAE;YAClE,KAAK,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;YACtC,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,GAAG,CACD,WAAmB,EACnB,QAA+C,EAAE,EACjD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,sBAAsB,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC1F,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAA6B,EAAE,OAAwB;QAC5D,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,6BAA6B,EAAE;YACtD,KAAK,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;YACtC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAA6B,EAAE,OAAwB;QAC5D,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QACxD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE;YAC5C,KAAK,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE;YACtC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF"}

package/src/client.ts

@@ -201,6 +201,7 @@ import {
   Retriever,
   RetrieverCreate,
   RetrieverCreateParams,
+  RetrieverDeleteParams,
   RetrieverGetParams,
   RetrieverListParams,
   RetrieverListResponse,
@@ -1190,6 +1191,7 @@ export declare namespace LlamaCloud {
     type RetrieverCreateParams as RetrieverCreateParams,
     type RetrieverUpdateParams as RetrieverUpdateParams,
     type RetrieverListParams as RetrieverListParams,
+    type RetrieverDeleteParams as RetrieverDeleteParams,
     type RetrieverGetParams as RetrieverGetParams,
     type RetrieverSearchParams as RetrieverSearchParams,
     type RetrieverUpsertParams as RetrieverUpsertParams,

package/src/internal/utils/env.ts

@@ -9,10 +9,10 @@
  */
 export const readEnv = (env: string): string | undefined => {
   if (typeof (globalThis as any).process !== 'undefined') {
-    return (globalThis as any).process.env?.[env]?.trim() ?? undefined;
+    return (globalThis as any).process.env?.[env]?.trim() || undefined;
   }
   if (typeof (globalThis as any).Deno !== 'undefined') {
-    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+    return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined;
   }
   return undefined;
 };

package/src/resources/beta/agent-data.ts

@@ -7,8 +7,45 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 export class AgentData extends APIResource {
+  /**
+   * Create new agent data.
+   *
+   * @example
+   * ```ts
+   * const agentData = await client.beta.agentData.create({
+   *   data: { foo: 'bar' },
+   *   deployment_name: 'deployment_name',
+   * });
+   * ```
+   */
+  create(params: AgentDataCreateParams, options?: RequestOptions): APIPromise<AgentData> {
+    const { organization_id, project_id, ...body } = params;
+    return this._client.post('/api/v1/beta/agent-data', {
+      query: { organization_id, project_id },
+      body,
+      ...options,
+    });
+  }
+
+  /**
+   * @deprecated Use {@link create} instead. `agentData` is kept as a
+   * backwards-compatible alias for SDK versions that exposed the create
+   * endpoint under this name.
+   */
+  agentData(params: AgentDataCreateParams, options?: RequestOptions): APIPromise<AgentData> {
+    return this.create(params, options);
+  }
+
   /**
    * Update agent data by ID (overwrites).
+   *
+   * @example
+   * ```ts
+   * const agentData = await client.beta.agentData.update(
+   *   'item_id',
+   *   { data: { foo: 'bar' } },
+   * );
+   * ```
    */
   update(itemID: string, params: AgentDataUpdateParams, options?: RequestOptions): APIPromise<AgentData> {
     const { organization_id, project_id, ...body } = params;
@@ -21,6 +58,13 @@ export class AgentData extends APIResource {
 
   /**
    * Delete agent data by ID.
+   *
+   * @example
+   * ```ts
+   * const agentData = await client.beta.agentData.delete(
+   *   'item_id',
+   * );
+   * ```
    */
   delete(
     itemID: string,
@@ -34,20 +78,18 @@ export class AgentData extends APIResource {
     });
   }
 
-  /**
-   * Create new agent data.
-   */
-  agentData(params: AgentDataAgentDataParams, options?: RequestOptions): APIPromise<AgentData> {
-    const { organization_id, project_id, ...body } = params;
-    return this._client.post('/api/v1/beta/agent-data', {
-      query: { organization_id, project_id },
-      body,
-      ...options,
-    });
-  }
-
   /**
    * Aggregate agent data with grouping and optional counting/first item retrieval.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const agentDataAggregateResponse of client.beta.agentData.aggregate(
+   *   { deployment_name: 'deployment_name' },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   aggregate(
     params: AgentDataAggregateParams,
@@ -63,6 +105,13 @@ export class AgentData extends APIResource {
 
   /**
    * Bulk delete agent data by query (deployment_name, collection, optional filters).
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.agentData.deleteByQuery({
+   *   deployment_name: 'deployment_name',
+   * });
+   * ```
    */
   deleteByQuery(
     params: AgentDataDeleteByQueryParams,
@@ -78,6 +127,13 @@ export class AgentData extends APIResource {
 
   /**
    * Get agent data by ID.
+   *
+   * @example
+   * ```ts
+   * const agentData = await client.beta.agentData.get(
+   *   'item_id',
+   * );
+   * ```
    */
   get(
     itemID: string,
@@ -89,6 +145,16 @@ export class AgentData extends APIResource {
 
   /**
    * Search agent data with filtering, sorting, and pagination.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const agentData of client.beta.agentData.search({
+   *   deployment_name: 'deployment_name',
+   * })) {
+   *   // ...
+   * }
+   * ```
    */
   search(
     params: AgentDataSearchParams,
@@ -147,39 +213,38 @@ export interface AgentDataDeleteByQueryResponse {
   deleted_count: number;
 }
 
-export interface AgentDataUpdateParams {
+export interface AgentDataCreateParams {
   /**
    * Body param
    */
   data: { [key: string]: unknown };
 
   /**
-   * Query param
+   * Body param
    */
-  organization_id?: string | null;
+  deployment_name: string;
 
   /**
    * Query param
    */
-  project_id?: string | null;
-}
-
-export interface AgentDataDeleteParams {
   organization_id?: string | null;
 
+  /**
+   * Query param
+   */
   project_id?: string | null;
-}
 
-export interface AgentDataAgentDataParams {
   /**
    * Body param
    */
-  data: { [key: string]: unknown };
+  collection?: string;
+}
 
+export interface AgentDataUpdateParams {
   /**
    * Body param
    */
-  deployment_name: string;
+  data: { [key: string]: unknown };
 
   /**
    * Query param
@@ -190,11 +255,12 @@ export interface AgentDataAgentDataParams {
    * Query param
    */
   project_id?: string | null;
+}
 
-  /**
-   * Body param
-   */
-  collection?: string;
+export interface AgentDataDeleteParams {
+  organization_id?: string | null;
+
+  project_id?: string | null;
 }
 
 export interface AgentDataAggregateParams extends PaginatedCursorPostParams {
@@ -409,9 +475,9 @@ export declare namespace AgentData {
     type AgentDataDeleteByQueryResponse as AgentDataDeleteByQueryResponse,
     type AgentDataAggregateResponsesPaginatedCursorPost as AgentDataAggregateResponsesPaginatedCursorPost,
     type AgentDataPaginatedCursorPost as AgentDataPaginatedCursorPost,
+    type AgentDataCreateParams as AgentDataCreateParams,
     type AgentDataUpdateParams as AgentDataUpdateParams,
     type AgentDataDeleteParams as AgentDataDeleteParams,
-    type AgentDataAgentDataParams as AgentDataAgentDataParams,
     type AgentDataAggregateParams as AgentDataAggregateParams,
     type AgentDataDeleteByQueryParams as AgentDataDeleteByQueryParams,
     type AgentDataGetParams as AgentDataGetParams,

package/src/resources/beta/batch/batch.ts

@@ -30,6 +30,13 @@ export class Batch extends APIResource {
    * Provide either `directory_id` to process all files in a directory, or `item_ids`
    * for specific items. The job runs asynchronously — poll `GET /batch/{job_id}` for
    * progress.
+   *
+   * @example
+   * ```ts
+   * const batch = await client.beta.batch.create({
+   *   job_config: {},
+   * });
+   * ```
    */
   create(params: BatchCreateParams, options?: RequestOptions): APIPromise<BatchCreateResponse> {
     const { organization_id, project_id, 'temporal-namespace': temporalNamespace, ...body } = params;
@@ -49,6 +56,14 @@ export class Batch extends APIResource {
    *
    * Filter by `directory_id`, `job_type`, or `status`. Results are paginated with
    * configurable `limit` and `offset`.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const batchListResponse of client.beta.batch.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: BatchListParams | null | undefined = {},
@@ -65,6 +80,11 @@ export class Batch extends APIResource {
    *
    * Stops processing and marks pending items as cancelled. Items currently being
    * processed may still complete.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.batch.cancel('job_id');
+   * ```
    */
   cancel(
     jobID: string,
@@ -88,6 +108,13 @@ export class Batch extends APIResource {
    *
    * Returns current progress percentage, file counts (total, processed, failed,
    * skipped), and timestamps.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.batch.getStatus(
+   *   'job_id',
+   * );
+   * ```
    */
   getStatus(
     jobID: string,

package/src/resources/beta/batch/job-items.ts

@@ -14,6 +14,16 @@ export class JobItems extends APIResource {
    *
    * Useful for finding failed items, viewing completed items, or debugging
    * processing issues.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const jobItemListResponse of client.beta.batch.jobItems.list(
+   *   'job_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     jobID: string,
@@ -33,6 +43,14 @@ export class JobItems extends APIResource {
    * Returns the complete processing history for an item including what operations
    * were performed, parameters used, and where outputs are stored. Optionally filter
    * by `job_type`.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.beta.batch.jobItems.getProcessingResults(
+   *     'item_id',
+   *   );
+   * ```
    */
   getProcessingResults(
     itemID: string,

package/src/resources/beta/beta.ts

@@ -4,10 +4,10 @@ import { APIResource } from '../../core/resource';
 import * as AgentDataAPI from './agent-data';
 import {
   AgentData,
-  AgentDataAgentDataParams,
   AgentDataAggregateParams,
   AgentDataAggregateResponse,
   AgentDataAggregateResponsesPaginatedCursorPost,
+  AgentDataCreateParams,
   AgentDataDeleteByQueryParams,
   AgentDataDeleteByQueryResponse,
   AgentDataDeleteParams,
@@ -94,9 +94,9 @@ export declare namespace Beta {
     type AgentDataDeleteByQueryResponse as AgentDataDeleteByQueryResponse,
     type AgentDataAggregateResponsesPaginatedCursorPost as AgentDataAggregateResponsesPaginatedCursorPost,
     type AgentDataPaginatedCursorPost as AgentDataPaginatedCursorPost,
+    type AgentDataCreateParams as AgentDataCreateParams,
     type AgentDataUpdateParams as AgentDataUpdateParams,
     type AgentDataDeleteParams as AgentDataDeleteParams,
-    type AgentDataAgentDataParams as AgentDataAgentDataParams,
     type AgentDataAggregateParams as AgentDataAggregateParams,
     type AgentDataDeleteByQueryParams as AgentDataDeleteByQueryParams,
     type AgentDataGetParams as AgentDataGetParams,

package/src/resources/beta/directories/directories.ts

@@ -31,6 +31,13 @@ export class Directories extends APIResource {
    *
    * If data_source_id is provided, validates that the data source exists and belongs
    * to the same project.
+   *
+   * @example
+   * ```ts
+   * const directory = await client.beta.directories.create({
+   *   name: 'x',
+   * });
+   * ```
    */
   create(params: DirectoryCreateParams, options?: RequestOptions): APIPromise<DirectoryCreateResponse> {
     const { organization_id, project_id, ...body } = params;
@@ -43,6 +50,13 @@ export class Directories extends APIResource {
 
   /**
    * Update directory metadata.
+   *
+   * @example
+   * ```ts
+   * const directory = await client.beta.directories.update(
+   *   'directory_id',
+   * );
+   * ```
    */
   update(
     directoryID: string,
@@ -59,6 +73,14 @@ export class Directories extends APIResource {
 
   /**
    * List Directories
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const directoryListResponse of client.beta.directories.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: DirectoryListParams | null | undefined = {},
@@ -72,6 +94,11 @@ export class Directories extends APIResource {
 
   /**
    * Permanently delete a directory.
+   *
+   * @example
+   * ```ts
+   * await client.beta.directories.delete('directory_id');
+   * ```
    */
   delete(
     directoryID: string,
@@ -88,6 +115,13 @@ export class Directories extends APIResource {
 
   /**
    * Retrieve a directory by its identifier.
+   *
+   * @example
+   * ```ts
+   * const directory = await client.beta.directories.get(
+   *   'directory_id',
+   * );
+   * ```
    */
   get(
     directoryID: string,

package/src/resources/beta/directories/files.ts

@@ -18,6 +18,14 @@ export class Files extends APIResource {
    * Note: This endpoint uses directory_file_id (the internal ID). If you're trying
    * to update a file by its unique_id, use the list endpoint with a filter to find
    * the directory_file_id first.
+   *
+   * @example
+   * ```ts
+   * const file = await client.beta.directories.files.update(
+   *   'directory_file_id',
+   *   { path_directory_id: 'directory_id' },
+   * );
+   * ```
    */
   update(
     directoryFileID: string,
@@ -35,6 +43,16 @@ export class Files extends APIResource {
   /**
    * List all files within the specified directory with optional filtering and
    * pagination.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const fileListResponse of client.beta.directories.files.list(
+   *   'directory_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     directoryID: string,
@@ -54,6 +72,14 @@ export class Files extends APIResource {
    * Note: This endpoint uses directory_file_id (the internal ID). If you're trying
    * to delete a file by its unique_id, use the list endpoint with a filter to find
    * the directory_file_id first.
+   *
+   * @example
+   * ```ts
+   * await client.beta.directories.files.delete(
+   *   'directory_file_id',
+   *   { directory_id: 'directory_id' },
+   * );
+   * ```
    */
   delete(directoryFileID: string, params: FileDeleteParams, options?: RequestOptions): APIPromise<void> {
     const { directory_id, organization_id, project_id } = params;
@@ -69,6 +95,14 @@ export class Files extends APIResource {
    *
    * The directory must exist and belong to the project passed in. The file_id must
    * be provided and exist in the project.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.directories.files.add(
+   *   'directory_id',
+   *   { file_id: 'file_id' },
+   * );
+   * ```
    */
   add(directoryID: string, params: FileAddParams, options?: RequestOptions): APIPromise<FileAddResponse> {
     const { organization_id, project_id, ...body } = params;
@@ -83,6 +117,14 @@ export class Files extends APIResource {
    * Get a file by its directory_file_id within the specified directory. If you're
    * trying to get a file by its unique_id, use the list endpoint with a filter
    * instead.
+   *
+   * @example
+   * ```ts
+   * const file = await client.beta.directories.files.get(
+   *   'directory_file_id',
+   *   { directory_id: 'directory_id' },
+   * );
+   * ```
    */
   get(directoryFileID: string, params: FileGetParams, options?: RequestOptions): APIPromise<FileGetResponse> {
     const { directory_id, ...query } = params;
@@ -98,6 +140,14 @@ export class Files extends APIResource {
    * Uploads a file and creates a directory file entry in a single operation. If
    * unique_id or display_name are not provided, they will be derived from the file
    * metadata.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.directories.files.upload(
+   *   'directory_id',
+   *   { upload_file: fs.createReadStream('path/to/file') },
+   * );
+   * ```
    */
   upload(
     directoryID: string,
@@ -163,6 +213,11 @@ export interface FileUpdateResponse {
    */
   file_id?: string | null;
 
+  /**
+   * Merged metadata from all sources. Higher-priority sources override lower.
+   */
+  metadata?: { [key: string]: string | number | boolean | null };
+
   /**
    * Update datetime
    */
@@ -218,6 +273,11 @@ export interface FileListResponse {
    */
   file_id?: string | null;
 
+  /**
+   * Merged metadata from all sources. Higher-priority sources override lower.
+   */
+  metadata?: { [key: string]: string | number | boolean | null };
+
   /**
    * Update datetime
    */
@@ -273,6 +333,11 @@ export interface FileAddResponse {
    */
   file_id?: string | null;
 
+  /**
+   * Merged metadata from all sources. Higher-priority sources override lower.
+   */
+  metadata?: { [key: string]: string | number | boolean | null };
+
   /**
    * Update datetime
    */
@@ -328,6 +393,11 @@ export interface FileGetResponse {
    */
   file_id?: string | null;
 
+  /**
+   * Merged metadata from all sources. Higher-priority sources override lower.
+   */
+  metadata?: { [key: string]: string | number | boolean | null };
+
   /**
    * Update datetime
    */
@@ -383,6 +453,11 @@ export interface FileUploadResponse {
    */
   file_id?: string | null;
 
+  /**
+   * Merged metadata from all sources. Higher-priority sources override lower.
+   */
+  metadata?: { [key: string]: string | number | boolean | null };
+
   /**
    * Update datetime
    */
@@ -415,6 +490,12 @@ export interface FileUpdateParams {
    */
   display_name?: string | null;
 
+  /**
+   * Body param: User-defined metadata key-value pairs. Replaces the user metadata
+   * layer.
+   */
+  metadata?: { [key: string]: string | number | boolean | null } | null;
+
   /**
    * Body param: Updated unique identifier.
    */
@@ -476,6 +557,11 @@ export interface FileAddParams {
    */
   display_name?: string | null;
 
+  /**
+   * Body param: User-defined metadata key-value pairs to associate with the file.
+   */
+  metadata?: { [key: string]: string | number | boolean | null } | null;
+
   /**
    * Body param: Unique identifier for the file in the directory. If not provided,
    * will use the file's external_file_id or name.

package/src/resources/beta/index.ts

@@ -5,9 +5,9 @@ export {
   type AgentDataDeleteResponse,
   type AgentDataAggregateResponse,
   type AgentDataDeleteByQueryResponse,
+  type AgentDataCreateParams,
   type AgentDataUpdateParams,
   type AgentDataDeleteParams,
-  type AgentDataAgentDataParams,
   type AgentDataAggregateParams,
   type AgentDataDeleteByQueryParams,
   type AgentDataGetParams,

package/src/resources/beta/sheets.ts

@@ -13,6 +13,13 @@ export class Sheets extends APIResource {
   /**
    * Create a spreadsheet parsing job. Experimental: This endpoint is not yet ready
    * for production use and is subject to change at any time.
+   *
+   * @example
+   * ```ts
+   * const sheetsJob = await client.beta.sheets.create({
+   *   file_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * });
+   * ```
    */
   create(params: SheetCreateParams, options?: RequestOptions): APIPromise<SheetsJob> {
     const { organization_id, project_id, ...body } = params;
@@ -26,6 +33,14 @@ export class Sheets extends APIResource {
   /**
    * List spreadsheet parsing jobs. Experimental: This endpoint is not yet ready for
    * production use and is subject to change at any time.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const sheetsJob of client.beta.sheets.list()) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     query: SheetListParams | null | undefined = {},
@@ -41,6 +56,13 @@ export class Sheets extends APIResource {
    * Delete a spreadsheet parsing job and its associated data. Experimental: This
    * endpoint is not yet ready for production use and is subject to change at any
    * time.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.sheets.deleteJob(
+   *   'spreadsheet_job_id',
+   * );
+   * ```
    */
   deleteJob(
     spreadsheetJobID: string,
@@ -63,6 +85,13 @@ export class Sheets extends APIResource {
    *
    * Experimental: This endpoint is not yet ready for production use and is subject
    * to change at any time.
+   *
+   * @example
+   * ```ts
+   * const sheetsJob = await client.beta.sheets.get(
+   *   'spreadsheet_job_id',
+   * );
+   * ```
    */
   get(
     spreadsheetJobID: string,
@@ -76,6 +105,15 @@ export class Sheets extends APIResource {
    * Generate a presigned URL to download a specific extracted region. Experimental:
    * This endpoint is not yet ready for production use and is subject to change at
    * any time.
+   *
+   * @example
+   * ```ts
+   * const presignedURL =
+   *   await client.beta.sheets.getResultTable('table', {
+   *     spreadsheet_job_id: 'spreadsheet_job_id',
+   *     region_id: 'region_id',
+   *   });
+   * ```
    */
   getResultTable(
     regionType: 'table' | 'extra' | 'cell_metadata',