openai 7.15.0 → 7.17.0

package/src/beta/realtime/websocket.ts

@@ -37,6 +37,7 @@ function isRunningInBrowserOrBrowserWorker(): boolean {
     return true;
   }
 
+  // SAFETY: RuntimeScope describes optional host capabilities; the following predicates verify their presence and value before use.
   const scope = globalThis as RuntimeScope;
   return (
     typeof scope.WorkerGlobalScope === 'function' &&
@@ -55,6 +56,7 @@ function isRunningInBrowserOrBrowserWorker(): boolean {
 
 /** Reports whether the runtime supports request headers in native WebSocket options. */
 function supportsWebSocketRequestHeaders(): boolean {
+  // SAFETY: RuntimeScope describes optional host capabilities; the following predicates verify their presence and value before use.
   const scope = globalThis as RuntimeScope;
   if (
     isRunningInBrowserOrBrowserWorker() ||
@@ -189,7 +191,9 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
   ) {
     super();
     let apiKey = getRealtimeAPIKey(client, props.__apiKey);
+    // SAFETY: The supplied OpenAI client owns _options; these compatibility reads preserve its provider and browser-consent settings.
     const hasProvider = typeof (client as any)?._options?.apiKey === 'function';
+    // SAFETY: The supplied OpenAI client owns _options; these compatibility reads preserve its provider and browser-consent settings.
     const dangerouslyAllowBrowser =
       props.dangerouslyAllowBrowser ??
       (client as any)?._options?.dangerouslyAllowBrowser ??
@@ -265,7 +269,12 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     });
 
     this.socket.addEventListener('error', (event: any) => {
-      this._onError(null, event.message, null);
+      // Native ErrorEvents can carry an empty message while `error` still holds the failure.
+      const cause = event.error ?? null;
+      const message = [event.message, cause?.message].find(
+        (value) => typeof value === 'string' && value !== '',
+      );
+      this._onError(null, message ?? 'unknown error', cause);
     });
   }
 
@@ -329,6 +338,7 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     return new OpenAIRealtimeWebSocket(
       {
         model: deploymentName,
+        // Preserve explicit browser consent as an own data property without invoking an inherited setter.
         ...(dangerouslyAllowBrowser === undefined ? {} : { dangerouslyAllowBrowser }),
         __resolvedApiKey: isApiKeyProvider,
         __apiKey: apiKey,

package/src/beta/realtime/ws.ts

@@ -60,6 +60,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     super();
     client ??= new OpenAI();
     const apiKey = props.__apiKey === undefined ? client.apiKey : props.__apiKey;
+    // SAFETY: The supplied OpenAI client owns _options; this read detects its existing API-key provider without changing its public surface.
     const hasProvider = typeof (client as any)?._options?.apiKey === 'function';
     if (hasProvider && !props.__resolvedApiKey) {
       throw new Error(
@@ -75,6 +76,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     const headers = {
       'User-Agent': `${client.constructor.name}/JS ${VERSION}`,
       ...props.options?.headers,
+      // A credential must be an own data property without invoking an inherited setter.
       ...(isAzure(client) && !props.__resolvedApiKey ? {} : { Authorization: `Bearer ${apiKey}` }),
       'OpenAI-Beta': 'realtime=v1',
     };
@@ -186,6 +188,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
           ...props.options,
           headers: {
             ...props.options?.headers,
+            // A credential must be an own data property without invoking an inherited setter.
             ...(isApiKeyProvider ? {} : { 'api-key': apiKey }),
           },
         },

package/src/client.ts

@@ -5,6 +5,7 @@ import type { HTTPMethod, PromiseOrValue, MergedRequestInit, FinalizedRequestIni
 import { uuid4 } from './internal/utils/uuid';
 import { validatePositiveInteger, isAbsoluteURL, safeJSON, hasOwn } from './internal/utils/values';
 import { sleep } from './internal/utils/sleep';
+import { addRequestAbortListener, retainRequestAbortCallback } from './internal/utils/abort';
 export type { Logger, LogLevel } from './internal/utils/log';
 import { castToError, isAbortError } from './internal/errors';
 import { addRequestID, defaultParseResponse, type APIResponseProps } from './internal/parse';
@@ -47,6 +48,7 @@ import {
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
+import { resolveRealtimeAPIKey } from './internal/realtime-credentials';
 import {
   Batch,
   BatchCreateParams,
@@ -300,8 +302,9 @@ export interface ClientOptions {
    *
    * - Accepts either a static string or an async function that resolves to a string.
    * - Defaults to process.env['OPENAI_API_KEY'].
-   * - When a function is provided, it is invoked before each request so you can rotate
-   *   or refresh credentials at runtime.
+   * - When a function is provided, it is invoked when building bearer authentication
+   *   headers for each attempt, including retries and direct `buildRequest()` calls.
+   *   Each invocation's result is used for its own request.
    * - The function must return a non-empty string; otherwise an OpenAIError is thrown.
    * - If the function throws, the error is wrapped in an OpenAIError with the original
    *   error available as `cause`.
@@ -816,10 +819,11 @@ export class OpenAI {
           : await authentication.getToken();
       return buildHeaders([{ Authorization: `Bearer ${token}` }]);
     }
-    if (this.apiKey == null) {
+    const { apiKey } = await resolveRealtimeAPIKey(this);
+    if (apiKey == null) {
       return undefined;
     }
-    return buildHeaders([{ Authorization: `Bearer ${this.apiKey}` }]);
+    return buildHeaders([{ Authorization: `Bearer ${apiKey}` }]);
   }
 
   protected async adminAPIKeyAuth(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
@@ -852,12 +856,16 @@ export class OpenAI {
     return Errors.APIError.generate(status, normalizedError, message, headers);
   }
 
+  _hasApiKeyProvider(): boolean {
+    return typeof this._options.apiKey === 'function';
+  }
+
   /**
    * Resolves a function-based API key and retains the resolved value on this client.
    * Returns whether a provider was invoked. Internal callers can capture this
    * invocation's key before another request updates the shared `apiKey` property.
    * Overrides should forward `capture` or invoke it with their own resolved key
-   * to preserve connection-local credentials in concurrent Realtime factories.
+   * to preserve invocation-local credentials in concurrent requests and Realtime factories.
    * @internal
    */
   async _callApiKey(capture?: (apiKey: string | null) => void): Promise<boolean> {
@@ -919,15 +927,11 @@ export class OpenAI {
 
   /**
    * Used as a callback for mutating the given `FinalRequestOptions` object.
+   * Function-based credentials are resolved later, when building authentication
+   * headers, including for direct `buildRequest()` calls. Overriding this hook
+   * does not bypass that resolution.
    */
-  protected async prepareOptions(options: FinalRequestOptions): Promise<void> {
-    if (this._provider) return;
-
-    const security = options.__security ?? { bearerAuth: true };
-    if (security.bearerAuth) {
-      await this._callApiKey();
-    }
-  }
+  protected async prepareOptions(options: FinalRequestOptions): Promise<void> {}
 
   /**
    * Used as a callback for mutating the given `RequestInit` object.
@@ -1108,6 +1112,8 @@ export class OpenAI {
           props.options,
           retriesRemaining,
           props.retryOfRequestLogID ?? props.requestLogID,
+          undefined,
+          props.requestSignal,
         );
         Object.assign(props, next);
       } finally {
@@ -1318,7 +1324,13 @@ export class OpenAI {
             message: x509Authentication ? 'X.509 workload identity API connection failed.' : response.message,
           }),
         );
-        return this.retryRequest(options, retriesRemaining, retryOfRequestLogID ?? requestLogID);
+        return this.retryRequest(
+          options,
+          retriesRemaining,
+          retryOfRequestLogID ?? requestLogID,
+          undefined,
+          req.signal,
+        );
       }
       const terminalMessage = hasStreamingBody
         ? 'error; streaming body cannot be retried'
@@ -1442,6 +1454,7 @@ export class OpenAI {
           retriesRemaining,
           retryOfRequestLogID ?? requestLogID,
           response.headers,
+          req.signal,
         );
       }
 
@@ -1497,7 +1510,15 @@ export class OpenAI {
       helperMethod: options.__metadata?.['helperMethod'],
       ...(continueRequest ? { continueRequest } : {}),
     });
-    return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
+    return {
+      response,
+      options,
+      controller,
+      requestSignal: req.signal,
+      requestLogID,
+      retryOfRequestLogID,
+      startTime,
+    };
   }
 
   getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
@@ -1574,7 +1595,8 @@ export class OpenAI {
     const { signal, method, ...options } = init || {};
     const abort = this._makeAbort(controller);
     const composed = !!signal && composedCallerSignals.get(controller) === signal;
-    if (signal && !composed) signal.addEventListener('abort', abort, { once: true });
+    const cleanup =
+      signal && !composed ? addRequestAbortListener(signal, abort, controller.signal) : undefined;
 
     const timeout = setTimeout(abort, ms);
 
@@ -1596,9 +1618,13 @@ export class OpenAI {
 
     try {
       // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
-      return await (this.#x509Fetch ?? this.fetch).call(undefined, url, fetchOptions);
+      const response = await (this.#x509Fetch ?? this.fetch).call(undefined, url, fetchOptions);
+      if (cleanup) {
+        retainRequestAbortCallback(response.body ?? response, abort, controller.signal);
+      }
+      return response;
     } catch (err) {
-      if (signal && !composed) signal.removeEventListener('abort', abort);
+      cleanup?.();
       throw err;
     } finally {
       clearTimeout(timeout);
@@ -1633,6 +1659,7 @@ export class OpenAI {
     retriesRemaining: number,
     requestLogID: string,
     responseHeaders?: Headers | undefined,
+    requestSignal: AbortSignal | null | undefined = options.signal,
   ): Promise<APIResponseProps> {
     let timeoutMillis: number | undefined;
 
@@ -1680,7 +1707,17 @@ export class OpenAI {
     if (x509Authentication) {
       await x509Authentication.waitForRetry(timeoutMillis, x509Authentication.effectiveSignal());
     } else {
-      await sleep(timeoutMillis);
+      const retrySignals =
+        requestSignal === options.signal ? [requestSignal] : [requestSignal, options.signal];
+      try {
+        await sleep(timeoutMillis, ...retrySignals);
+      } catch (error) {
+        const abortedSignal = retrySignals.find((signal) => signal?.aborted);
+        if (abortedSignal) {
+          throw this._makeUserAbortError(abortedSignal);
+        }
+        throw error;
+      }
     }
 
     return this.makeRequest(options, retriesRemaining - 1, requestLogID);
@@ -1701,6 +1738,12 @@ export class OpenAI {
     return sleepSeconds * jitter * 1000;
   }
 
+  /**
+   * Builds a request, resolving callback credentials when constructing authentication
+   * headers, after any subclass request-option rewrites. Calling this method directly
+   * also resolves credentials. Complete replacement builders own authentication and
+   * can call `this.authHeaders()` to resolve headers with request-local credentials.
+   */
   async buildRequest(
     inputOptions: FinalRequestOptions,
     { retryCount = 0 }: { retryCount?: number } = {},
@@ -1745,6 +1788,10 @@ export class OpenAI {
         options.signal = snapshot.signal;
       }
     }
+    const authenticationHeaders =
+      this._provider || x509Authentication
+        ? undefined
+        : await this.authHeaders(inputOptions, inputOptions.__security ?? { bearerAuth: true });
     const { bodyHeaders, body, isStreamingBody } = this.buildBody({ options });
 
     if (isStreamingBody) {
@@ -1759,6 +1806,7 @@ export class OpenAI {
       options: inputOptions,
       method,
       bodyHeaders,
+      authenticationHeaders,
       retryCount,
       x509Headers,
       x509Timeout: explicitTimeout ? options.timeout : undefined,
@@ -1783,6 +1831,7 @@ export class OpenAI {
     options,
     method,
     bodyHeaders,
+    authenticationHeaders,
     retryCount,
     x509Headers,
     x509Timeout,
@@ -1791,6 +1840,7 @@ export class OpenAI {
     options: FinalRequestOptions;
     method: HTTPMethod;
     bodyHeaders: HeadersLike;
+    authenticationHeaders: NullableHeaders | undefined;
     retryCount: number;
     x509Headers?: { defaultHeaders: NullableHeaders; requestHeaders: NullableHeaders } | undefined;
     x509Timeout: number | undefined;
@@ -1816,9 +1866,10 @@ export class OpenAI {
         'OpenAI-Organization': x509Tenant ? x509Tenant.organization : this.organization,
         'OpenAI-Project': x509Tenant ? x509Tenant.project : this.project,
       },
-      this._provider || this.#x509Authentication?.isPlanningRequest()
-        ? undefined
-        : await this.authHeaders(options, options.__security ?? { bearerAuth: true }),
+      // X.509 owns streaming uploads before authentication so it can retire them on failure.
+      this.#x509Authentication && !this.#x509Authentication.isPlanningRequest()
+        ? await this.authHeaders(options, options.__security ?? { bearerAuth: true })
+        : authenticationHeaders,
       x509Headers?.defaultHeaders ?? this._options.defaultHeaders,
       bodyHeaders,
       x509Headers?.requestHeaders ?? options.headers,
@@ -2024,6 +2075,11 @@ OpenAI.Evals = Evals;
 OpenAI.Containers = Containers;
 OpenAI.Skills = Skills;
 OpenAI.Videos = Videos;
+OpenAI.ConversationCursorPage = Pagination.ConversationCursorPage;
+OpenAI.CursorPage = Pagination.CursorPage;
+OpenAI.NextCursorPage = Pagination.NextCursorPage;
+OpenAI.Page = Pagination.Page;
+OpenAI.TokenPage = Pagination.TokenPage;
 
 const composedCallerSignals = new WeakMap<AbortController, AbortSignal>();
 

package/src/core/EventEmitter.ts

@@ -54,12 +54,14 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
       return this;
     }
 
+    // SAFETY: Listener functions are object identities used as WeakMap keys; registration and removal use the same function instance.
     const emittedRegistration = this.#emittedListenerRegistrations.get(listener as object);
     if (
       emittedRegistration?.event === event &&
       !emittedRegistration.registration.removed &&
       !emittedRegistration.registration.detached
     ) {
+      // SAFETY: The stored registration event was compared with this event above, preserving the event/listener type correlation.
       this.#removeEmittedListener(
         event,
         emittedRegistration.registration as EventListeners<EventTypes, Event>[number],
@@ -101,6 +103,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
       registration?.listener === listener &&
       registration.once
     ) {
+      // SAFETY: Listener functions are object identities used as WeakMap keys; registration and removal use the same function instance.
       this.#emittedListenerRegistrations.set(listener as object, { event, registration });
     }
   }
@@ -114,6 +117,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
     }
 
     registration.removed = true;
+    // SAFETY: Listener functions are object identities used as WeakMap keys; registration and removal use the same function instance.
     this.#emittedListenerRegistrations.delete(registration.listener as object);
     this.#pendingListenerCleanup.add(event);
     if (this.#listenerDispatchDepth === 0) {
@@ -123,9 +127,11 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
 
   #cleanupEmittedListeners(): void {
     for (const event of this.#pendingListenerCleanup) {
+      // SAFETY: Pending cleanup keys are added only from registered EventTypes events; the key retains its event-map membership.
       const eventType = event as keyof EventTypes;
       const listeners = this.#listeners[eventType];
       if (listeners) {
+        // SAFETY: Filtering only removes registrations from the same event bucket and preserves the listener signatures for that event.
         this.#listeners[eventType] = listeners.filter((listener) => !listener.removed) as any;
       }
     }
@@ -150,21 +156,27 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
   ): Promise<EmittedEventResult<EventParameters<EventTypes, Event>>> {
     return new Promise((resolve, reject) => {
       const listeners = {
+        // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Failures and rejection reasons can be arbitrary JavaScript values; preserve them until inspection or forwarding.
         onError: (error: unknown) => {
+          // SAFETY: This callback is paired with the same event when registered and removed; its variadic body forwards the event tuple or captured error.
           this.off(event, listeners.onEvent as any);
           reject(error);
         },
         onEvent: (...values: unknown[]) => {
           if (event !== 'error') {
+            // SAFETY: This callback is paired with the same event when registered and removed; its variadic body forwards the event tuple or captured error.
             this.off('error', listeners.onError as any);
           }
+          // SAFETY: The emitted API returns the sole argument or the full tuple according to its existing EventTypes-dependent result contract.
           resolve((values.length > 1 ? values : values[0]) as any);
         },
       };
 
       if (event !== 'error') {
+        // SAFETY: This callback is paired with the same event when registered and removed; its variadic body forwards the event tuple or captured error.
         this.#onceForEmitted('error', listeners.onError as any);
       }
+      // SAFETY: This callback is paired with the same event when registered and removed; its variadic body forwards the event tuple or captured error.
       this.#onceForEmitted(event, listeners.onEvent as any);
     });
   }
@@ -176,6 +188,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
   ) {
     const listeners: EventListeners<EventTypes, Event> | undefined = this.#listeners[event];
     if (listeners) {
+      // SAFETY: Filtering only removes registrations from the same event bucket and preserves the listener signatures for that event.
       this.#listeners[event] = listeners.filter((listener) => {
         if (listener.once) {
           listener.detached = true;
@@ -186,10 +199,12 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
       let firstListenerError: unknown;
       this.#listenerDispatchDepth += 1;
       try {
+        // SAFETY: The listener bucket and argument tuple come from the same EventTypes key; this bridges TypeScript generic indexed-access correlation.
         for (const registration of listeners as any) {
           if (!registration.removed) {
             try {
               const { listener } = registration;
+              // SAFETY: The listener bucket and argument tuple come from the same EventTypes key; this bridges TypeScript generic indexed-access correlation.
               listener(...(args as any));
             } catch (error) {
               if (!listenerThrew) {

package/src/core/streaming.ts

@@ -139,7 +139,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
             let data;
 
             try {
-              data = JSON.parse(sse.data) as any;
+              data = JSON.parse(sse.data);
             } catch {
               logger.error(`Could not parse message into JSON:`);
               logger.error(`From chunk:`);
@@ -164,6 +164,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
               logger.error(`From chunk:`);
               throw new SyntaxError('Error reading response: malformed server-sent event JSON.');
             }
+            // SAFETY: Named SSE events use the public stream's event/data envelope; Item is the caller-selected API event contract.
             yield { event: sse.event, data } as any;
           }
         }
@@ -264,6 +265,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
           if (line) {
             let data: Item;
             try {
+              // SAFETY: Item is the caller's NDJSON response contract; JSON syntax is parsed here without a per-resource runtime schema.
               data = JSON.parse(line) as Item;
             } catch (error) {
               if (error instanceof SyntaxError) {
@@ -352,10 +354,13 @@ export class Stream<Item> implements AsyncIterable<Item> {
    * which can be turned back into a Stream with `Stream.fromReadableStream()`.
    * Canceling a response-backed readable aborts its request. Canceling a tee
    * branch discards its buffered events and leaves sibling consumers running.
+   * Read or serialization failures also release the iterator without replacing the original error.
    */
   toReadableStream(): ReadableStream {
     const { controller } = this;
     let iter: AsyncIterator<Item>;
+    let cancellation: Promise<void> | undefined;
+    const cancel = () => (cancellation ??= this.#cancelIterator(iter, controller));
 
     return makeReadableStream({
       start: async () => {
@@ -373,9 +378,12 @@ export class Stream<Item> implements AsyncIterable<Item> {
           ctrl.enqueue(bytes);
         } catch (err) {
           ctrl.error(err);
+          // An errored readable never invokes its cancel hook. Release the source ourselves,
+          // without letting failed or stalled cleanup replace the read/serialization error.
+          void cancel().catch(() => undefined);
         }
       },
-      cancel: () => this.#cancelIterator(iter, controller),
+      cancel,
     });
   }
 
@@ -385,6 +393,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
       if (!this.#isTeeBranch) {
         controller.abort();
       }
+      // oxlint-disable-next-line anti-slop/no-reflect-apply -- Invoke the captured iterator method with its receiver even if a caller-supplied function shadows call.
       await Reflect.apply(returnMethod, iterator, []);
     }
   }
@@ -524,6 +533,7 @@ export async function* _iterSSEMessages(
 ): AsyncGenerator<ServerSentEvent, void, unknown> {
   if (!response.body) {
     controller.abort();
+    // SAFETY: navigator is optional across SDK runtimes; this compatibility branch checks its presence before identifying React Native.
     if (
       (globalThis as any).navigator !== undefined &&
       (globalThis as any).navigator.product === 'ReactNative'
@@ -569,6 +579,15 @@ export async function* _iterSSEMessages(
         yield sse;
       }
     }
+    // Servers sometimes omit the trailing blank line that normally
+    // terminates the last event. Flush any in-progress event exactly once.
+    if (signal.aborted) {
+      return;
+    }
+    const pending = sseDecoder.flush();
+    if (pending) {
+      yield pending;
+    }
   } catch (error) {
     failed = true;
     if (!signal.aborted || (!isAbortError(error) && error !== signal.reason)) {
@@ -699,6 +718,15 @@ class SSEDecoder {
 
     return null;
   }
+
+  /**
+   * Emits a pending event at EOF when the stream omitted the trailing blank
+   * line. Returns `null` when no event is in progress so a record that already
+   * ended with a blank line is not delivered twice.
+   */
+  flush(): ServerSentEvent | null {
+    return this.decode('');
+  }
 }
 
 function partition(str: string, delimiter: string): [string, string, string] {

package/src/helpers/audio.ts

@@ -47,11 +47,13 @@ async function nodejsPlayAudio(stream: NodeJS.ReadableStream | Response | File):
     try {
       let source: NodeJS.ReadableStream;
       if (isResponse(stream)) {
+        // SAFETY: Fetch implementations may expose a web or Node response body; the following pipe check selects the matching stream adapter.
         const body = stream.body as NodeReadableStream | NodeJS.ReadableStream | null;
         if (!body) {
           throw new Error('Cannot play audio from a response without a body');
         }
 
+        // SAFETY: The preceding branch handled Node pipe streams; the remaining response body follows the web ReadableStream contract consumed by fromWeb.
         source =
           'pipe' in body && typeof body.pipe === 'function'
             ? body