openai 7.3.0 → 7.5.0

package/src/client.ts

@@ -1,4 +1,4 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
 import type { RequestInit, RequestInfo, BodyInit } from './internal/builtin-types';
 import type { HTTPMethod, PromiseOrValue, MergedRequestInit, FinalizedRequestInit } from './internal/types';
@@ -7,7 +7,7 @@ import { validatePositiveInteger, isAbsoluteURL, safeJSON } from './internal/uti
 import { sleep } from './internal/utils/sleep';
 export type { Logger, LogLevel } from './internal/utils/log';
 import { castToError, isAbortError } from './internal/errors';
-import type { APIResponseProps } from './internal/parse';
+import { addRequestID, defaultParseResponse, type APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
@@ -19,7 +19,6 @@ import type { WorkloadIdentity } from './auth/types';
 import { WorkloadIdentityAuth } from './auth/workload-identity-auth';
 import { OAuthError, SubjectTokenProviderError } from './core/error';
 import {
-  AbstractPage,
   type ConversationCursorPageParams,
   ConversationCursorPageResponse,
   type CursorPageParams,
@@ -250,6 +249,25 @@ import {
 } from './internal/utils/log';
 import { isEmptyObj } from './internal/utils/values';
 
+function isRunningInBrowserOrBrowserWorker(): boolean {
+  if (isRunningInBrowser()) return true;
+
+  const scope = globalThis as any;
+  return (
+    typeof scope.WorkerGlobalScope === 'function' &&
+    scope instanceof scope.WorkerGlobalScope &&
+    typeof scope.WorkerNavigator === 'function' &&
+    scope.navigator instanceof scope.WorkerNavigator &&
+    typeof scope.navigator?.userAgent === 'string' &&
+    scope.navigator.userAgent !== 'Cloudflare-Workers' &&
+    scope.process?.versions?.node === undefined &&
+    scope.Deno === undefined &&
+    scope.Bun === undefined &&
+    scope.EdgeRuntime === undefined &&
+    scope.WebSocketPair === undefined
+  );
+}
+
 const WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER = 'workload-identity-auth';
 
 export type ApiKeySetter = () => Promise<string>;
@@ -303,6 +321,23 @@ export interface ClientOptions {
    * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
    * much longer than this timeout before the promise succeeds or fails.
    *
+   * Node.js fetch enforces independent response-header and body-inactivity timeouts, typically
+   * defaulting to five minutes, even when this timeout is longer. To increase them, install
+   * `undici` and configure an Agent with the matching fetch implementation:
+   *
+   * ```ts
+   * import { Agent, fetch } from 'undici';
+   *
+   * const timeout = 20 * 60 * 1000;
+   * const client = new OpenAI({
+   *   timeout,
+   *   fetch,
+   *   fetchOptions: {
+   *     dispatcher: new Agent({ headersTimeout: timeout, bodyTimeout: timeout }),
+   *   },
+   * });
+   * ```
+   *
    * @unit milliseconds
    */
   timeout?: number | undefined;
@@ -396,6 +431,7 @@ export class OpenAI {
 
   private fetch: Fetch;
   #encoder: Opts.RequestEncoder;
+  #responseAttempts = new WeakMap<AbortController, { timeout: number; retriesRemaining: number }>();
   protected idempotencyHeader?: string;
   protected _options: ClientOptions;
   private _provider: ProviderRuntime | undefined;
@@ -436,10 +472,10 @@ export class OpenAI {
 
     const {
       baseURL = provider ? null : readEnv('OPENAI_BASE_URL'),
-      apiKey = provider ? null : readEnv('OPENAI_API_KEY') ?? null,
-      adminAPIKey = provider ? null : readEnv('OPENAI_ADMIN_KEY') ?? null,
-      organization = provider ? null : readEnv('OPENAI_ORG_ID') ?? null,
-      project = provider ? null : readEnv('OPENAI_PROJECT_ID') ?? null,
+      apiKey = provider ? null : (readEnv('OPENAI_API_KEY') ?? null),
+      adminAPIKey = provider ? null : (readEnv('OPENAI_ADMIN_KEY') ?? null),
+      organization = provider ? null : (readEnv('OPENAI_ORG_ID') ?? null),
+      project = provider ? null : (readEnv('OPENAI_PROJECT_ID') ?? null),
       webhookSecret = readEnv('OPENAI_WEBHOOK_SECRET') ?? null,
       workloadIdentity,
       ...opts
@@ -467,14 +503,14 @@ export class OpenAI {
       );
     }
 
-    if (!options.dangerouslyAllowBrowser && isRunningInBrowser()) {
+    if (!options.dangerouslyAllowBrowser && isRunningInBrowserOrBrowserWorker()) {
       throw new Errors.OpenAIError(
         "It looks like you're running in a browser-like environment.\n\nThis is disabled by default, as it risks exposing your secret API credentials to attackers.\nIf you understand the risks and have appropriate mitigations in place,\nyou can set the `dangerouslyAllowBrowser` option to `true`, e.g.,\n\nnew OpenAI({ apiKey, dangerouslyAllowBrowser: true });\n\nhttps://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety\n",
       );
     }
 
     this.baseURL = options.baseURL!;
-    this.timeout = options.timeout ?? OpenAI.DEFAULT_TIMEOUT /* 10 minutes */;
+    this.timeout = options.timeout ?? OpenAI.DEFAULT_TIMEOUT; /* 10 minutes */
     this.logger = options.logger ?? console;
     const defaultLogLevel = 'warn';
     // Set default logLevel early so that we can log a warning in parseLogLevel.
@@ -638,7 +674,9 @@ export class OpenAI {
     message: string | undefined,
     headers: Headers,
   ): Errors.APIError {
-    return Errors.APIError.generate(status, error, message, headers);
+    const normalizedError =
+      error && typeof error === 'object' && (error as { error?: unknown }).error == null ? { error } : error;
+    return Errors.APIError.generate(status, normalizedError, message, headers);
   }
 
   async _callApiKey(): Promise<boolean> {
@@ -674,9 +712,8 @@ export class OpenAI {
     defaultBaseURL?: string | undefined,
   ): string {
     const baseURL = (!this.#baseURLOverridden() && defaultBaseURL) || this.baseURL;
-    const url =
-      isAbsoluteURL(path) ?
-        new URL(path)
+    const url = isAbsoluteURL(path)
+      ? new URL(path)
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
@@ -751,7 +788,109 @@ export class OpenAI {
     options: PromiseOrValue<FinalRequestOptions>,
     remainingRetries: number | null = null,
   ): APIPromise<Rsp> {
-    return new APIPromise(this, this.makeRequest(options, remainingRetries, undefined));
+    return this.responsePromise<Rsp>(this.makeRequest(options, remainingRetries, undefined));
+  }
+
+  private responsePromise<Rsp>(
+    request: Promise<APIResponseProps>,
+    parse: (client: OpenAI, props: APIResponseProps) => Promise<any> = (client, props) =>
+      this.parseResponseWithTimeout<Rsp>(client, props),
+  ): APIPromise<Rsp> {
+    const promise = new APIPromise<Rsp>(this, request, parse);
+
+    // A body timeout can retry after the original raw response has arrived. Wait for
+    // parsing before selecting the response so withResponse() reports the retry.
+    promise.withResponse = async () => {
+      const data = await promise;
+      const { response } = await request;
+      return { data, response, request_id: response.headers.get('x-request-id') };
+    };
+    promise._thenUnwrap = <Next>(transform: (data: Rsp, props: APIResponseProps) => Next) =>
+      this.responsePromise<Next>(request, async (client, props) =>
+        addRequestID(transform(await parse(client, props), props), props.response),
+      );
+
+    return promise;
+  }
+
+  private async parseResponseWithTimeout<Rsp>(client: OpenAI, props: APIResponseProps): Promise<any> {
+    if (
+      props.options.stream ||
+      props.options.__binaryResponse ||
+      props.response.status === 204 ||
+      props.response.headers.get('content-length') === '0'
+    ) {
+      return defaultParseResponse<Rsp>(client, props);
+    }
+
+    while (true) {
+      const attempt = this.#responseAttempts.get(props.controller);
+      const timeout = attempt?.timeout ?? props.options.timeout ?? this.timeout;
+      const remaining = Math.max(0, props.startTime + timeout - Date.now());
+      const callerSignal = props.options.signal;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let abortListener: (() => void) | undefined;
+      let timedOut = false;
+
+      try {
+        // Tool runners preserve a completed buffered turn before cancellation stops the next request.
+        if (callerSignal?.aborted && props.options.__metadata?.['helperMethod'] !== 'runTools') {
+          throw new Errors.APIUserAbortError();
+        }
+
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            props.controller.abort();
+            reject(new Errors.APIConnectionTimeoutError());
+          }, remaining);
+
+          if (callerSignal) {
+            abortListener = () => reject(new Errors.APIUserAbortError());
+            callerSignal.addEventListener('abort', abortListener, { once: true });
+          }
+        });
+
+        return await Promise.race([defaultParseResponse<Rsp>(client, props), timeoutPromise]);
+      } catch (error) {
+        if (callerSignal?.aborted) {
+          throw new Errors.APIUserAbortError();
+        }
+        if (!timedOut) {
+          throw error;
+        }
+
+        const retriesRemaining = attempt?.retriesRemaining ?? 0;
+        if (
+          !retriesRemaining ||
+          props.options.__metadata?.['hasStreamingBody'] ||
+          ((globalThis as any).ReadableStream &&
+            props.options.body instanceof (globalThis as any).ReadableStream) ||
+          (typeof props.options.body === 'object' &&
+            props.options.body !== null &&
+            (Symbol.asyncIterator in props.options.body ||
+              (Symbol.iterator in props.options.body &&
+                'next' in props.options.body &&
+                typeof props.options.body.next === 'function')))
+        ) {
+          throw new Errors.APIConnectionTimeoutError();
+        }
+
+        if (timer !== undefined) clearTimeout(timer);
+        if (abortListener) callerSignal?.removeEventListener('abort', abortListener);
+        abortListener = undefined;
+
+        const next = await this.retryRequest(
+          props.options,
+          retriesRemaining,
+          props.retryOfRequestLogID ?? props.requestLogID,
+        );
+        Object.assign(props, next);
+      } finally {
+        if (timer !== undefined) clearTimeout(timer);
+        if (abortListener) callerSignal?.removeEventListener('abort', abortListener);
+      }
+    }
   }
 
   private async makeRequest(
@@ -791,19 +930,23 @@ export class OpenAI {
       }),
     );
 
-    if (options.signal?.aborted) {
-      throw new Errors.APIUserAbortError();
+    if (options.signal?.aborted || req.signal?.aborted) {
+      throw this._makeUserAbortError(options.signal?.aborted ? options.signal : req.signal!);
     }
 
     const security = options.__security ?? { bearerAuth: true };
-    const controller = new AbortController();
+    // Request hooks may replace the caller signal before it reaches fetch.
+    const controller =
+      this.fetchWithTimeout === OpenAI.prototype.fetchWithTimeout
+        ? createRequestController(req.signal)
+        : new AbortController();
     const response = await this.fetchWithAuth(url, req, timeout, controller, security).catch(castToError);
     const headersTime = Date.now();
 
     if (response instanceof globalThis.Error) {
       const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
-      if (options.signal?.aborted) {
-        throw new Errors.APIUserAbortError();
+      if (options.signal?.aborted || req.signal?.aborted) {
+        throw this._makeUserAbortError(options.signal?.aborted ? options.signal : req.signal!);
       }
       // detect native connection timeout errors
       // deno throws "TypeError: error sending request for url (https://example/): client error (Connect): tcp connect error: Operation timed out (os error 60): Operation timed out (os error 60)"
@@ -827,8 +970,9 @@ export class OpenAI {
         );
         return this.retryRequest(options, retriesRemaining, retryOfRequestLogID ?? requestLogID);
       }
-      const terminalMessage =
-        hasStreamingBody ? 'error; streaming body cannot be retried' : 'error; no more retries left';
+      const terminalMessage = hasStreamingBody
+        ? 'error; streaming body cannot be retried'
+        : 'error; no more retries left';
       loggerFor(this).info(
         `[${requestLogID}] connection ${isTimeout ? 'timed out' : 'failed'} - ${terminalMessage}`,
       );
@@ -845,7 +989,20 @@ export class OpenAI {
         throw response;
       }
       if (isTimeout) {
-        throw new Errors.APIConnectionTimeoutError();
+        const transportCause = 'cause' in response ? response.cause : undefined;
+        const isHeadersTimeout =
+          typeof transportCause === 'object' &&
+          transportCause !== null &&
+          'code' in transportCause &&
+          transportCause.code === 'UND_ERR_HEADERS_TIMEOUT';
+        const timeoutError = isHeadersTimeout
+          ? new Errors.APIConnectionTimeoutError({
+              message:
+                'Request timed out. Node.js fetch timed out waiting for response headers; ' +
+                'configure a matching undici fetch and fetchOptions.dispatcher with an Agent whose headersTimeout is at least the SDK timeout.',
+            })
+          : new Errors.APIConnectionTimeoutError();
+        throw Object.assign(timeoutError, { cause: response });
       }
       throw new Errors.APIConnectionError({
         message: getConnectionErrorMessage(response),
@@ -910,9 +1067,9 @@ export class OpenAI {
         );
       }
 
-      const retryMessage =
-        shouldRetry ?
-          hasStreamingBody ? `error; streaming body cannot be retried`
+      const retryMessage = shouldRetry
+        ? hasStreamingBody
+          ? `error; streaming body cannot be retried`
           : `error; no more retries left`
         : `error; not retryable`;
 
@@ -950,6 +1107,7 @@ export class OpenAI {
       }),
     );
 
+    this.#responseAttempts.set(controller, { timeout, retriesRemaining });
     return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
   }
 
@@ -960,9 +1118,9 @@ export class OpenAI {
   ): Pagination.PagePromise<PageClass, Item> {
     return this.requestAPIList(
       Page,
-      opts && 'then' in opts ?
-        opts.then((opts) => ({ method: 'get', path, ...opts }))
-      : { method: 'get', path, ...opts },
+      opts && 'then' in opts
+        ? opts.then((opts) => ({ method: 'get', path, ...opts }))
+        : { method: 'get', path, ...opts },
     );
   }
 
@@ -974,7 +1132,17 @@ export class OpenAI {
     options: PromiseOrValue<FinalRequestOptions>,
   ): Pagination.PagePromise<PageClass, Item> {
     const request = this.makeRequest(options, null, undefined);
-    return new Pagination.PagePromise<PageClass, Item>(this as any as OpenAI, request, Page);
+    const page = new Pagination.PagePromise<PageClass, Item>(this as any as OpenAI, request, Page);
+    const guarded = this.responsePromise<PageClass>(request, async (client, props) => {
+      const body = await this.parseResponseWithTimeout(client, props);
+      return new Page(client, props.response, body, props.options);
+    });
+    page.then = guarded.then.bind(guarded);
+    page.catch = guarded.catch.bind(guarded);
+    page.finally = guarded.finally.bind(guarded);
+    page.withResponse = guarded.withResponse.bind(guarded);
+    page._thenUnwrap = guarded._thenUnwrap.bind(guarded);
+    return page;
   }
 
   protected async fetchWithAuth(
@@ -1009,7 +1177,8 @@ export class OpenAI {
   ): Promise<Response> {
     const { signal, method, ...options } = init || {};
     const abort = this._makeAbort(controller);
-    if (signal) signal.addEventListener('abort', abort, { once: true });
+    const composed = !!signal && composedCallerSignals.get(controller) === signal;
+    if (signal && !composed) signal.addEventListener('abort', abort, { once: true });
 
     const timeout = setTimeout(abort, ms);
 
@@ -1032,6 +1201,9 @@ export class OpenAI {
     try {
       // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
       return await this.fetch.call(undefined, url, fetchOptions);
+    } catch (err) {
+      if (signal && !composed) signal.removeEventListener('abort', abort);
+      throw err;
     } finally {
       clearTimeout(timeout);
     }
@@ -1079,7 +1251,7 @@ export class OpenAI {
 
     // About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
     const retryAfterHeader = responseHeaders?.get('retry-after');
-    if (retryAfterHeader && !timeoutMillis) {
+    if (retryAfterHeader && timeoutMillis === undefined) {
       const timeoutSeconds = parseFloat(retryAfterHeader);
       if (!Number.isNaN(timeoutSeconds)) {
         timeoutMillis = timeoutSeconds * 1000;
@@ -1090,7 +1262,12 @@ export class OpenAI {
 
     // If the API asks us to wait a certain amount of time, just do what it
     // says, but otherwise calculate a default
-    if (timeoutMillis === undefined) {
+    if (
+      timeoutMillis === undefined ||
+      !Number.isFinite(timeoutMillis) ||
+      timeoutMillis < 0 ||
+      timeoutMillis > 60 * 1000
+    ) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
@@ -1166,20 +1343,22 @@ export class OpenAI {
       idempotencyHeaders[this.idempotencyHeader] = options.idempotencyKey;
     }
 
+    const helperMethod = options.__metadata?.['helperMethod'];
     const headers = buildHeaders([
       idempotencyHeaders,
       {
         Accept: 'application/json',
-        'User-Agent': this.getUserAgent(),
+        ...(!isRunningInBrowserOrBrowserWorker() ? { 'User-Agent': this.getUserAgent() } : undefined),
         'X-Stainless-Retry-Count': String(retryCount),
         ...(options.timeout ? { 'X-Stainless-Timeout': String(Math.trunc(options.timeout / 1000)) } : {}),
         ...getPlatformHeaders(),
+        ...(typeof helperMethod === 'string' ? { 'X-Stainless-Helper-Method': helperMethod } : {}),
         'OpenAI-Organization': this.organization,
         'OpenAI-Project': this.project,
       },
-      this._provider ? undefined : (
-        await this.authHeaders(options, options.__security ?? { bearerAuth: true })
-      ),
+      this._provider
+        ? undefined
+        : await this.authHeaders(options, options.__security ?? { bearerAuth: true }),
       this._options.defaultHeaders,
       bodyHeaders,
       options.headers,
@@ -1198,6 +1377,12 @@ export class OpenAI {
     return () => controller.abort();
   }
 
+  private _makeUserAbortError(signal: NonNullable<RequestInit['signal']>): Errors.APIUserAbortError {
+    const error = new Errors.APIUserAbortError();
+    Object.defineProperty(error, 'cause', { value: signal.reason, writable: true, configurable: true });
+    return error;
+  }
+
   private buildBody({ options }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
@@ -1345,6 +1530,9 @@ export class OpenAI {
   evals: API.Evals = new API.Evals(this);
   containers: API.Containers = new API.Containers(this);
   skills: API.Skills = new API.Skills(this);
+  /**
+   * @deprecated The Sora API is scheduled to permanently shut down on September 24, 2026.
+   */
   videos: API.Videos = new API.Videos(this);
 }
 
@@ -1373,6 +1561,30 @@ OpenAI.Containers = Containers;
 OpenAI.Skills = Skills;
 OpenAI.Videos = Videos;
 
+const composedCallerSignals = new WeakMap<AbortController, AbortSignal>();
+
+function createRequestController(callerSignal: AbortSignal | null | undefined): AbortController {
+  const controller = new AbortController();
+  if (!callerSignal) return controller;
+
+  const nativeAbortSignal = (globalThis as any).AbortSignal;
+  if (typeof nativeAbortSignal?.any !== 'function' || !(callerSignal instanceof nativeAbortSignal)) {
+    return controller;
+  }
+
+  try {
+    // Native composition keeps cancellation active after response headers without
+    // retaining an abort listener on the caller's signal or changing its reason.
+    const composed = nativeAbortSignal.any([controller.signal, callerSignal]) as AbortSignal;
+    Object.defineProperty(controller, 'signal', { value: composed, configurable: true });
+    composedCallerSignals.set(controller, callerSignal);
+  } catch {
+    // Older or incompatible runtimes retain the existing listener-based fallback.
+  }
+
+  return controller;
+}
+
 function getConnectionErrorMessage(error: Error): string | undefined {
   if (isUndiciDispatcherVersionMismatchError(error)) {
     return `Connection error. This may be caused by passing an undici dispatcher, such as ProxyAgent, that is incompatible with the fetch implementation. If you are using undici's ProxyAgent, pass the fetch implementation from the same undici package: import { fetch, ProxyAgent } from 'undici'; new OpenAI({ fetch, fetchOptions: { dispatcher: new ProxyAgent(...) } });`;

package/src/core/EventEmitter.ts

@@ -1,18 +1,22 @@
+/** Listener callback associated with one event name in a typed event map. */
 type EventListener<Events, EventType extends keyof Events> = Events[EventType];
 
-type EventListeners<Events, EventType extends keyof Events> = Array<{
+type EventListeners<Events, EventType extends keyof Events> = {
   listener: EventListener<Events, EventType>;
   once?: boolean;
-}>;
+}[];
 
-export type EventParameters<Events, EventType extends keyof Events> = {
-  [Event in EventType]: EventListener<Events, EventType> extends (...args: infer P) => any ? P : never;
-}[EventType];
+/** Extracts the ordered listener-argument tuple for one named event. */
+export type EventParameters<Events, EventType extends keyof Events> = Record<
+  EventType,
+  EventListener<Events, EventType> extends (...args: infer P) => any ? P : never
+>[EventType];
 
+/** Registers strongly typed event listeners and awaits individual emitted events. */
 export class EventEmitter<EventTypes extends Record<string, (...args: any) => any>> {
   #listeners: {
     [Event in keyof EventTypes]?: EventListeners<EventTypes, Event>;
-  } = {};
+  } = Object.create(null);
 
   /**
    * Adds the listener function to the end of the listeners array for the event.
@@ -22,8 +26,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
    * @returns this, so that calls can be chained
    */
   on<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
-    const listeners: EventListeners<EventTypes, Event> =
-      this.#listeners[event] || (this.#listeners[event] = []);
+    const listeners: EventListeners<EventTypes, Event> = (this.#listeners[event] ||= []);
     listeners.push({ listener });
     return this;
   }
@@ -37,9 +40,13 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
    */
   off<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
     const listeners = this.#listeners[event];
-    if (!listeners) return this;
+    if (!listeners) {
+      return this;
+    }
     const index = listeners.findIndex((l) => l.listener === listener);
-    if (index >= 0) listeners.splice(index, 1);
+    if (index !== -1) {
+      listeners.splice(index, 1);
+    }
     return this;
   }
 
@@ -49,8 +56,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
    * @returns this, so that calls can be chained
    */
   once<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
-    const listeners: EventListeners<EventTypes, Event> =
-      this.#listeners[event] || (this.#listeners[event] = []);
+    const listeners: EventListeners<EventTypes, Event> = (this.#listeners[event] ||= []);
     listeners.push({ listener, once: true });
     return this;
   }
@@ -58,9 +64,11 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
   /**
    * This is similar to `.once()`, but returns a Promise that resolves the next time
    * the event is triggered, instead of calling a listener callback.
-   * @returns a Promise that resolves the next time given event is triggered,
-   * or rejects if an error is emitted.  (If you request the 'error' event,
-   * returns a promise that resolves with the error).
+   * Events without arguments resolve to `undefined`, single-argument events resolve
+   * to that argument, and events with multiple arguments resolve to an argument tuple.
+   *
+   * @returns A promise for the next event, or a rejection if an error occurs first.
+   * Requesting the `error` event resolves with the emitted error instead.
    *
    * Example:
    *
@@ -69,13 +77,30 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
   emitted<Event extends keyof EventTypes>(
     event: Event,
   ): Promise<
-    EventParameters<EventTypes, Event> extends [infer Param] ? Param
-    : EventParameters<EventTypes, Event> extends [] ? void
-    : EventParameters<EventTypes, Event>
+    EventParameters<EventTypes, Event> extends [infer Param]
+      ? Param
+      : EventParameters<EventTypes, Event> extends []
+        ? void
+        : EventParameters<EventTypes, Event>
   > {
     return new Promise((resolve, reject) => {
-      // TODO: handle errors
-      this.once(event, resolve as any);
+      const listeners = {
+        onError: (error: unknown) => {
+          this.off(event, listeners.onEvent as any);
+          reject(error);
+        },
+        onEvent: (...values: unknown[]) => {
+          if (event !== 'error') {
+            this.off('error', listeners.onError as any);
+          }
+          resolve((values.length > 1 ? values : values[0]) as any);
+        },
+      };
+
+      if (event !== 'error') {
+        this.once('error', listeners.onError as any);
+      }
+      this.once(event, listeners.onEvent as any);
     });
   }
 
@@ -87,7 +112,9 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
     const listeners: EventListeners<EventTypes, Event> | undefined = this.#listeners[event];
     if (listeners) {
       this.#listeners[event] = listeners.filter((l) => !l.once) as any;
-      listeners.forEach(({ listener }: any) => listener(...(args as any)));
+      for (const { listener } of listeners as any) {
+        listener(...(args as any));
+      }
     }
   }
 
@@ -108,6 +135,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
 export class InternalEventEmitter<
   EventTypes extends Record<string, (...args: any) => any>,
 > extends EventEmitter<EventTypes> {
+  /** Dispatches a named event to its currently registered listeners. */
   override _emit<Event extends keyof EventTypes>(event: Event, ...args: EventParameters<EventTypes, Event>) {
     super._emit(event, ...args);
   }

package/src/core/api-promise.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import { type OpenAI } from '../client';
 
 import { type PromiseOrValue } from '../internal/types';

package/src/core/error.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import { castToError } from '../internal/errors';
 import type { OAuthErrorCode } from '../resources/shared';
 
@@ -37,13 +35,13 @@ export class APIError<
   }
 
   private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
-    const msg =
-      error?.message ?
-        typeof error.message === 'string' ?
-          error.message
+    const msg = error?.message
+      ? typeof error.message === 'string'
+        ? error.message
         : JSON.stringify(error.message)
-      : error ? JSON.stringify(error)
-      : message;
+      : error
+        ? JSON.stringify(error)
+        : message;
 
     if (status && msg) {
       return `${status} ${msg}`;

package/src/core/pagination.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import { OpenAIError } from './error';
 import { FinalRequestOptions } from '../internal/request-options';
 import { defaultParseResponse, WithRequestID } from '../internal/parse';
@@ -73,9 +71,9 @@ export abstract class AbstractPage<Item> implements AsyncIterable<Item> {
  *    }
  */
 export class PagePromise<
-    PageClass extends AbstractPage<Item>,
-    Item = ReturnType<PageClass['getPaginatedItems']>[number],
-  >
+  PageClass extends AbstractPage<Item>,
+  Item = ReturnType<PageClass['getPaginatedItems']>[number],
+>
   extends APIPromise<PageClass>
   implements AsyncIterable<Item>
 {

package/src/core/resource.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import type { OpenAI } from '../client';
 
 export abstract class APIResource {