feat: add pagination config for list agent files

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 106
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/letta-ai%2Fletta-sdk-c9da12a5f16bb5f9039d2c783261913ea367f0e5d077b6fdb10e899fd8e6d7ca.yml
 openapi_spec_hash: e14297a0306cb58ebfd7594c7d9d994b
-config_hash: fcdeacffedf80fe9b63275b738fbb8c3
+config_hash: 2f5889efe104e3e49d62c0322e07ff4f

api.md

@@ -157,7 +157,7 @@ Types:
 
 Methods:
 
-- <code title="get /v1/agents/{agent_id}/files">client.agents.files.<a href="./src/resources/agents/files.ts">list</a>(agentID, { ...params }) -> FileListResponse</code>
+- <code title="get /v1/agents/{agent_id}/files">client.agents.files.<a href="./src/resources/agents/files.ts">list</a>(agentID, { ...params }) -> FileListResponsesNextFilesPage</code>
 - <code title="patch /v1/agents/{agent_id}/files/{file_id}/close">client.agents.files.<a href="./src/resources/agents/files.ts">close</a>(fileID, { ...params }) -> unknown</code>
 - <code title="patch /v1/agents/{agent_id}/files/close-all">client.agents.files.<a href="./src/resources/agents/files.ts">closeAll</a>(agentID) -> FileCloseAllResponse</code>
 - <code title="patch /v1/agents/{agent_id}/files/{file_id}/open">client.agents.files.<a href="./src/resources/agents/files.ts">open</a>(fileID, { ...params }) -> FileOpenResponse</code>

src/client.ts

@@ -19,6 +19,8 @@ import {
   AbstractPage,
   type ArrayPageParams,
   ArrayPageResponse,
+  type NextFilesPageParams,
+  NextFilesPageResponse,
   type ObjectPageParams,
   ObjectPageResponse,
 } from './core/pagination';
@@ -923,6 +925,12 @@ export declare namespace Letta {
   export import ObjectPage = Pagination.ObjectPage;
   export { type ObjectPageParams as ObjectPageParams, type ObjectPageResponse as ObjectPageResponse };
 
+  export import NextFilesPage = Pagination.NextFilesPage;
+  export {
+    type NextFilesPageParams as NextFilesPageParams,
+    type NextFilesPageResponse as NextFilesPageResponse,
+  };
+
   export { type HealthResponse as HealthResponse };
 
   export {

src/core/pagination.ts

@@ -243,3 +243,92 @@ export class ObjectPage<Item extends { id: string }>
     };
   }
 }
+
+export interface NextFilesPageResponse<Item> {
+  files: Array<Item>;
+
+  next_cursor: string | null;
+
+  has_more: boolean;
+}
+
+export interface NextFilesPageParams {
+  before?: string | null;
+
+  after?: string | null;
+
+  limit?: number | null;
+
+  order?: string | null;
+
+  order_by?: string | null;
+}
+
+export class NextFilesPage<Item extends { next_cursor: string | null }>
+  extends AbstractPage<Item>
+  implements NextFilesPageResponse<Item>
+{
+  files: Array<Item>;
+
+  next_cursor: string | null;
+
+  has_more: boolean;
+
+  constructor(
+    client: Letta,
+    response: Response,
+    body: NextFilesPageResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.files = body.files || [];
+    this.next_cursor = body.next_cursor || null;
+    this.has_more = body.has_more || false;
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.files ?? [];
+  }
+
+  override hasNextPage(): boolean {
+    if (this.has_more === false) {
+      return false;
+    }
+
+    return super.hasNextPage();
+  }
+
+  nextPageRequestOptions(): PageRequestOptions | null {
+    const files = this.getPaginatedItems();
+
+    const isForwards = !(typeof this.options.query === 'object' && 'before' in (this.options.query || {}));
+    if (isForwards) {
+      const nextCursor = files[files.length - 1]?.next_cursor;
+      if (!nextCursor) {
+        return null;
+      }
+
+      return {
+        ...this.options,
+        query: {
+          ...maybeObj(this.options.query),
+          after: nextCursor,
+        },
+      };
+    }
+
+    const nextCursor = files[0]?.next_cursor;
+    if (!nextCursor) {
+      return null;
+    }
+
+    return {
+      ...this.options,
+      query: {
+        ...maybeObj(this.options.query),
+        before: nextCursor,
+      },
+    };
+  }
+}

src/resources/agents/agents.ts

@@ -23,6 +23,7 @@ import {
   FileCloseResponse,
   FileListParams,
   FileListResponse,
+  FileListResponsesNextFilesPage,
   FileOpenParams,
   FileOpenResponse,
   Files,
@@ -1718,6 +1719,7 @@ export declare namespace Agents {
     type FileCloseResponse as FileCloseResponse,
     type FileCloseAllResponse as FileCloseAllResponse,
     type FileOpenResponse as FileOpenResponse,
+    type FileListResponsesNextFilesPage as FileListResponsesNextFilesPage,
     type FileListParams as FileListParams,
     type FileCloseParams as FileCloseParams,
     type FileOpenParams as FileOpenParams,

src/resources/agents/files.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
+import { NextFilesPage, type NextFilesPageParams, PagePromise } from '../../core/pagination';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -13,8 +14,11 @@ export class Files extends APIResource {
     agentID: string,
     query: FileListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<FileListResponse> {
-    return this._client.get(path`/v1/agents/${agentID}/files`, { query, ...options });
+  ): PagePromise<FileListResponsesNextFilesPage, FileListResponse> {
+    return this._client.getAPIList(path`/v1/agents/${agentID}/files`, NextFilesPage<FileListResponse>, {
+      query,
+      ...options,
+    });
   }
 
   /**
@@ -51,128 +55,80 @@ export class Files extends APIResource {
   }
 }
 
+export type FileListResponsesNextFilesPage = NextFilesPage<FileListResponse>;
+
 /**
- * Paginated response for agent files
+ * Response model for agent file attachments showing file status in agent context
  */
 export interface FileListResponse {
   /**
-   * List of file attachments for the agent
+   * Unique identifier of the file-agent relationship
    */
-  files: Array<FileListResponse.File>;
+  id: string;
 
   /**
-   * Whether more results exist after this page
+   * Unique identifier of the file
    */
-  has_more: boolean;
+  file_id: string;
 
   /**
-   * Cursor for fetching the next page (file-agent relationship ID)
+   * Name of the file
    */
-  next_cursor?: string | null;
-}
-
-export namespace FileListResponse {
-  /**
-   * Response model for agent file attachments showing file status in agent context
-   */
-  export interface File {
-    /**
-     * Unique identifier of the file-agent relationship
-     */
-    id: string;
-
-    /**
-     * Unique identifier of the file
-     */
-    file_id: string;
-
-    /**
-     * Name of the file
-     */
-    file_name: string;
-
-    /**
-     * Unique identifier of the folder/source
-     */
-    folder_id: string;
-
-    /**
-     * Name of the folder/source
-     */
-    folder_name: string;
-
-    /**
-     * Whether the file is currently open in the agent's context
-     */
-    is_open: boolean;
-
-    /**
-     * Ending line number if file was opened with line range
-     */
-    end_line?: number | null;
-
-    /**
-     * Timestamp of last access by the agent
-     */
-    last_accessed_at?: string | null;
-
-    /**
-     * Starting line number if file was opened with line range
-     */
-    start_line?: number | null;
-
-    /**
-     * Portion of the file visible to the agent if open
-     */
-    visible_content?: string | null;
-  }
-}
-
-export type FileCloseResponse = unknown;
+  file_name: string;
 
-export type FileCloseAllResponse = Array<string>;
+  /**
+   * Unique identifier of the folder/source
+   */
+  folder_id: string;
 
-export type FileOpenResponse = Array<string>;
+  /**
+   * Name of the folder/source
+   */
+  folder_name: string;
 
-export interface FileListParams {
   /**
-   * File ID cursor for pagination. Returns files that come after this file ID in the
-   * specified sort order
+   * Whether the file is currently open in the agent's context
    */
-  after?: string | null;
+  is_open: boolean;
 
   /**
-   * File ID cursor for pagination. Returns files that come before this file ID in
-   * the specified sort order
+   * Ending line number if file was opened with line range
    */
-  before?: string | null;
+  end_line?: number | null;
 
   /**
-   * @deprecated Pagination cursor from previous response (deprecated, use
-   * before/after)
+   * Timestamp of last access by the agent
    */
-  cursor?: string | null;
+  last_accessed_at?: string | null;
 
   /**
-   * Filter by open status (true for open files, false for closed files)
+   * Starting line number if file was opened with line range
    */
-  is_open?: boolean | null;
+  start_line?: number | null;
 
   /**
-   * Maximum number of files to return
+   * Portion of the file visible to the agent if open
    */
-  limit?: number | null;
+  visible_content?: string | null;
+}
+
+export type FileCloseResponse = unknown;
+
+export type FileCloseAllResponse = Array<string>;
 
+export type FileOpenResponse = Array<string>;
+
+export interface FileListParams extends NextFilesPageParams {
   /**
-   * Sort order for files by creation time. 'asc' for oldest first, 'desc' for newest
-   * first
+   * @deprecated Pagination cursor from previous response (deprecated, use
+   * before/after)
    */
-  order?: 'asc' | 'desc';
+  cursor?: string | null;
 
   /**
-   * Field to sort by
+   * Filter by open status (true for open files, false for closed files)
    */
-  order_by?: 'created_at';
+  is_open?: boolean | null;
 }
 
 export interface FileCloseParams {
@@ -195,6 +151,7 @@ export declare namespace Files {
     type FileCloseResponse as FileCloseResponse,
     type FileCloseAllResponse as FileCloseAllResponse,
     type FileOpenResponse as FileOpenResponse,
+    type FileListResponsesNextFilesPage as FileListResponsesNextFilesPage,
     type FileListParams as FileListParams,
     type FileCloseParams as FileCloseParams,
     type FileOpenParams as FileOpenParams,

src/resources/agents/index.ts

@@ -51,6 +51,7 @@ export {
   type FileListParams,
   type FileCloseParams,
   type FileOpenParams,
+  type FileListResponsesNextFilesPage,
 } from './files';
 export {
   Folders,