feat(client): add files.waitForProcessing() method (#292)

api.md

@@ -62,6 +62,7 @@ Methods:
 - <code title="get /files">client.files.<a href="./src/resources/files.ts">list</a>() -> FileObjectsPage</code>
 - <code title="delete /files/{file_id}">client.files.<a href="./src/resources/files.ts">del</a>(fileId) -> FileDeleted</code>
 - <code title="get /files/{file_id}/content">client.files.<a href="./src/resources/files.ts">retrieveContent</a>(fileId) -> string</code>
+- <code>client.files.<a href="./src/resources/files.ts">waitForProcessing</a>(id, { pollInterval = 5000, maxWait = 30 _ 60 _ 1000 }) -> Promise&lt;FileObject&gt;</code>
 
 # Images
 

src/core.ts

@@ -901,7 +901,7 @@ const isAbsoluteURL = (url: string): boolean => {
   return startsWithSchemeRegexp.test(url);
 };
 
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
 const validatePositiveInteger = (name: string, n: unknown): number => {
   if (typeof n !== 'number' || !Number.isInteger(n)) {

src/error.ts

@@ -106,8 +106,8 @@ export class APIConnectionError extends APIError {
 }
 
 export class APIConnectionTimeoutError extends APIConnectionError {
-  constructor() {
-    super({ message: 'Request timed out.' });
+  constructor({ message }: { message?: string } = {}) {
+    super({ message: message ?? 'Request timed out.' });
   }
 }
 

src/resources/files.ts

@@ -2,6 +2,8 @@
 
 import * as Core from 'openai/core';
 import { APIResource } from 'openai/resource';
+import { sleep } from 'openai/core';
+import { APIConnectionTimeoutError } from 'openai/error';
 import * as API from './index';
 import { type Uploadable, multipartFormRequestOptions } from 'openai/core';
 import { Page } from 'openai/pagination';
@@ -47,6 +49,32 @@ export class Files extends APIResource {
       headers: { Accept: 'application/json', ...options?.headers },
     });
   }
+
+  /**
+   * Waits for the given file to be processed, default timeout is 30 mins.
+   */
+  async waitForProcessing(
+    id: string,
+    { pollInterval = 5000, maxWait = 30 * 60 * 1000 }: { pollInterval?: number; maxWait?: number } = {},
+  ): Promise<FileObject> {
+    const TERMINAL_STATES = new Set(['processed', 'error', 'deleted']);
+
+    const start = Date.now();
+    let file = await this.retrieve(id);
+
+    while (!file.status || !TERMINAL_STATES.has(file.status)) {
+      await sleep(pollInterval);
+
+      file = await this.retrieve(id);
+      if (Date.now() - start > maxWait) {
+        throw new APIConnectionTimeoutError({
+          message: `Giving up on waiting for file ${id} to finish processing after ${maxWait} milliseconds.`,
+        });
+      }
+    }
+
+    return file;
+  }
 }
 
 /**