feat(client): add auto-pagination to fine tuning list endpoints (#254)

README.md

@@ -215,6 +215,37 @@ On timeout, an `APIConnectionTimeoutError` is thrown.
 
 Note that requests which time out will be [retried twice by default](#retries).
 
+## Auto-pagination
+
+List methods in the OpenAI API are paginated.
+You can use `for await … of` syntax to iterate through items across all pages:
+
+```ts
+async function fetchAllFineTuningJobs(params) {
+  const allFineTuningJobs = [];
+  // Automatically fetches more pages as needed.
+  for await (const job of openai.fineTuning.jobs.list({ limit: 20 })) {
+    allFineTuningJobs.push(job);
+  }
+  return allFineTuningJobs;
+}
+```
+
+Alternatively, you can make request a single page at a time:
+
+```ts
+let page = await openai.fineTuning.jobs.list({ limit: 20 });
+for (const job of page.data) {
+  console.log(job);
+}
+
+// Convenience methods are provided for manually paginating:
+while (page.hasNextPage()) {
+  page = page.getNextPage();
+  // ...
+}
+```
+
 ## Advanced Usage
 
 ### Accessing raw Response data (e.g., headers)

src/index.ts

@@ -206,6 +206,10 @@ export namespace OpenAI {
   export import Page = Pagination.Page;
   export import PageResponse = Pagination.PageResponse;
 
+  export import CursorPage = Pagination.CursorPage;
+  export import CursorPageParams = Pagination.CursorPageParams;
+  export import CursorPageResponse = Pagination.CursorPageResponse;
+
   export import Completions = API.Completions;
   export import Completion = API.Completion;
   export import CompletionChoice = API.CompletionChoice;

src/pagination.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless.
 
-import { AbstractPage, Response, APIClient, FinalRequestOptions } from './core';
+import { AbstractPage, Response, APIClient, FinalRequestOptions, PageInfo } from './core';
 
 export interface PageResponse<Item> {
   data: Array<Item>;
@@ -40,3 +40,61 @@ export class Page<Item> extends AbstractPage<Item> implements PageResponse<Item>
     return null;
   }
 }
+
+export interface CursorPageResponse<Item> {
+  data: Array<Item>;
+}
+
+export interface CursorPageParams {
+  /**
+   * Identifier for the last job from the previous pagination request.
+   */
+  after?: string;
+
+  /**
+   * Number of fine-tuning jobs to retrieve.
+   */
+  limit?: number;
+}
+
+export class CursorPage<Item extends { id: string }>
+  extends AbstractPage<Item>
+  implements CursorPageResponse<Item>
+{
+  data: Array<Item>;
+
+  constructor(
+    client: APIClient,
+    response: Response,
+    body: CursorPageResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.data = body.data;
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data;
+  }
+
+  // @deprecated Please use `nextPageInfo()` instead
+  nextPageParams(): Partial<CursorPageParams> | null {
+    const info = this.nextPageInfo();
+    if (!info) return null;
+    if ('params' in info) return info.params;
+    const params = Object.fromEntries(info.url.searchParams);
+    if (!Object.keys(params).length) return null;
+    return params;
+  }
+
+  nextPageInfo(): PageInfo | null {
+    if (!this.data?.length) {
+      return null;
+    }
+
+    const next = this.data[this.data.length - 1]?.id;
+    if (!next) return null;
+    return { params: { after: next } };
+  }
+}

src/resources/fine-tuning/jobs.ts

@@ -5,7 +5,7 @@ import { APIResource } from 'openai/resource';
 import { isRequestOptions } from 'openai/core';
 import * as Files from 'openai/resources/files';
 import * as API from './index';
-import { Page } from 'openai/pagination';
+import { CursorPage, CursorPageParams } from 'openai/pagination';
 
 export class Jobs extends APIResource {
   /**
@@ -81,17 +81,11 @@ export class Jobs extends APIResource {
   }
 }
 
-/**
- * Note: no pagination actually occurs yet, this is for forwards-compatibility.
- */
-export class FineTuningJobsPage extends Page<FineTuningJob> {}
+export class FineTuningJobsPage extends CursorPage<FineTuningJob> {}
 // alias so we can export it in the namespace
 type _FineTuningJobsPage = FineTuningJobsPage;
 
-/**
- * Note: no pagination actually occurs yet, this is for forwards-compatibility.
- */
-export class FineTuningJobEventsPage extends Page<FineTuningJobEvent> {}
+export class FineTuningJobEventsPage extends CursorPage<FineTuningJobEvent> {}
 // alias so we can export it in the namespace
 type _FineTuningJobEventsPage = FineTuningJobEventsPage;
 
@@ -258,29 +252,9 @@ export namespace JobCreateParams {
   }
 }
 
-export interface JobListParams {
-  /**
-   * Identifier for the last job from the previous pagination request.
-   */
-  after?: string;
-
-  /**
-   * Number of fine-tuning jobs to retrieve.
-   */
-  limit?: number;
-}
-
-export interface JobListEventsParams {
-  /**
-   * Identifier for the last event from the previous pagination request.
-   */
-  after?: string;
+export interface JobListParams extends CursorPageParams {}
 
-  /**
-   * Number of events to retrieve.
-   */
-  limit?: number;
-}
+export interface JobListEventsParams extends CursorPageParams {}
 
 export namespace Jobs {
   export import FineTuningJob = API.FineTuningJob;