openai 7.15.0 → 7.16.0

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> {
@@ -857,7 +861,7 @@ export class OpenAI {
    * 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 +923,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.
@@ -1574,7 +1574,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 +1597,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);
@@ -1701,6 +1706,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 +1756,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 +1774,7 @@ export class OpenAI {
       options: inputOptions,
       method,
       bodyHeaders,
+      authenticationHeaders,
       retryCount,
       x509Headers,
       x509Timeout: explicitTimeout ? options.timeout : undefined,
@@ -1783,6 +1799,7 @@ export class OpenAI {
     options,
     method,
     bodyHeaders,
+    authenticationHeaders,
     retryCount,
     x509Headers,
     x509Timeout,
@@ -1791,6 +1808,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 +1834,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 +2043,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/internal/realtime-credentials.ts

@@ -9,7 +9,7 @@ export function getRealtimeAPIKey(
 }
 
 /**
- * Captures the key belonging to this factory invocation while retaining the
+ * Captures the key belonging to this request or factory invocation while retaining the
  * existing boolean credential-hook contract. Legacy overrides that do not
  * capture a key keep their shared-property behavior and remain responsible for
  * synchronizing concurrent credential updates.

package/src/internal/utils/abort.ts

@@ -0,0 +1,111 @@
+type AbortCallback = () => void;
+interface WeakReference<T> {
+  deref: () => T | undefined;
+}
+type WeakAbortCallback = WeakReference<AbortCallback>;
+interface AbortFinalizer {
+  register: (target: AbortCallback, cleanup: AbortCallback, token: object) => void;
+  unregister: (token: object) => boolean;
+}
+
+// Keep these optional runtime features out of the SDK's ES2020 type requirements.
+const weakGlobals = globalThis as typeof globalThis & {
+  WeakRef?: new <T extends object>(target: T) => WeakReference<T>;
+  FinalizationRegistry?: new (cleanup: (value: AbortCallback) => void) => AbortFinalizer;
+};
+const finalizer =
+  typeof weakGlobals.FinalizationRegistry === 'function'
+    ? new weakGlobals.FinalizationRegistry((cleanup) => {
+        try {
+          cleanup();
+        } catch {
+          // Caller-provided signal methods must not throw out of a GC callback.
+        }
+      })
+    : undefined;
+const callbackOwners = new WeakMap<object, Set<AbortCallback>>();
+const subscriptions = new WeakMap<AbortSignal, { callbacks: Set<WeakAbortCallback>; abort: AbortCallback }>();
+
+// This scope receives only a weak reference, so its closures cannot retain the callback.
+function subscribeWeakly(signal: AbortSignal, reference: WeakAbortCallback, registry: AbortFinalizer) {
+  let subscription = subscriptions.get(signal);
+  if (!subscription) {
+    const callbacks = new Set<WeakAbortCallback>();
+    const abort = () => {
+      subscriptions.delete(signal);
+      for (const callback of callbacks) {
+        registry.unregister(callback);
+        callback.deref()?.();
+      }
+      callbacks.clear();
+    };
+    subscription = { callbacks, abort };
+    signal.addEventListener('abort', abort, { once: true });
+    subscriptions.set(signal, subscription);
+  }
+  const owner = subscription;
+  owner.callbacks.add(reference);
+  return () => {
+    owner.callbacks.delete(reference);
+    registry.unregister(reference);
+    if (owner.callbacks.size === 0) {
+      if (subscriptions.get(signal) === owner) {
+        subscriptions.delete(signal);
+      }
+      signal.removeEventListener('abort', owner.abort);
+    }
+  };
+}
+
+// The listener must not retain the shared owner or its other request callbacks.
+function releaseOnAbort(
+  signal: AbortSignal,
+  callbacks: WeakReference<Set<AbortCallback>>,
+  abort: AbortCallback,
+) {
+  signal.addEventListener('abort', () => callbacks.deref()?.delete(abort), { once: true });
+}
+
+/** Keep cancellation alive until abort or collection of the response body or bodyless custom response. */
+export function retainRequestAbortCallback(
+  owner: object,
+  abort: AbortCallback,
+  requestSignal: AbortSignal,
+): void {
+  if (typeof weakGlobals.WeakRef === 'function' && finalizer && !requestSignal.aborted) {
+    let callbacks = callbackOwners.get(owner);
+    if (!callbacks) {
+      callbacks = new Set();
+      callbackOwners.set(owner, callbacks);
+    }
+    callbacks.add(abort);
+    releaseOnAbort(requestSignal, new weakGlobals.WeakRef(callbacks), abort);
+  }
+}
+
+/**
+ * Share one caller listener without it retaining completed requests. Collection removes
+ * weak subscriptions eventually; a live response body or custom response retains its callback.
+ * Runtimes without weak references keep the existing listener-based behavior.
+ */
+export function addRequestAbortListener(
+  signal: AbortSignal,
+  abort: AbortCallback,
+  requestSignal: AbortSignal,
+): AbortCallback {
+  if (signal.aborted) {
+    abort();
+    return () => {
+      // No listener was installed for an already aborted signal.
+    };
+  }
+  if (typeof weakGlobals.WeakRef !== 'function' || !finalizer) {
+    signal.addEventListener('abort', abort, { once: true });
+    return () => signal.removeEventListener('abort', abort);
+  }
+  const reference = new weakGlobals.WeakRef(abort);
+  const cleanup = subscribeWeakly(signal, reference, finalizer);
+  finalizer.register(abort, cleanup, reference);
+  retainRequestAbortCallback(requestSignal, abort, requestSignal);
+  return cleanup;
+}

package/src/internal/ws.ts

@@ -1,4 +1,26 @@
 import { concatBytes, encodeUTF8 } from './utils/bytes';
+import { OpenAIError } from '../core/error';
+
+/** Options for an independently buffered WebSocket stream iterator. */
+export interface WebSocketStreamOptions {
+  /**
+   * Maximum queued records, including raw data, errors and lifecycle events.
+   * Must be a positive safe integer. Omitted means unlimited. Overflow discards
+   * this iterator's backlog and rejects its next() calls with a WebSocketError,
+   * without closing the shared socket or affecting other iterators.
+   * This bounds event count, not payload bytes or total memory.
+   */
+  maxBufferedEvents?: number | undefined;
+}
+
+/** Snapshots and validates the iterator's limit before listeners are attached. */
+export function getMaxBufferedEvents(options?: WebSocketStreamOptions): number | undefined {
+  const limit = options?.maxBufferedEvents;
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit <= 0)) {
+    throw new OpenAIError('maxBufferedEvents must be a positive safe integer');
+  }
+  return limit;
+}
 
 /** Reconnection event passed to the `onReconnecting` handler and event listeners. */
 export interface ReconnectingEvent<Parameters = Record<string, unknown>> {

package/src/lib/live/transcript-grouping.ts

@@ -15,11 +15,17 @@ export type GroupingUpdate =
   | { type: 'updated'; segment: TranscriptSegment }
   | { type: 'closed'; segment: TranscriptSegment; reason: TranscriptSegmentCloseReason };
 
+interface Acknowledgment {
+  characters: number;
+  text: string | undefined;
+}
+
 type Turn = TranscriptFragment & {
   id: string;
   previousId: string | null;
   emitted: boolean;
   canDropAsBackchannel: boolean;
+  acknowledgment?: Acknowledgment | undefined;
 };
 
 const ACKNOWLEDGMENTS = [
@@ -42,14 +48,16 @@ const ACKNOWLEDGMENTS = [
 ];
 
 function normalizeAcknowledgment(text: string): string {
-  return text
+  const normalized = text
     .toLowerCase()
     .split('-')
     .join(' ')
-    .replace(/^[\s.,!?;:"'()[\]{}]+/u, '')
-    .replace(/[\s.,!?;:"'()[\]{}]+$/u, '')
-    .split(/\s+/u)
-    .join(' ');
+    .replace(/^[\s.,!?;:"'()[\]{}]+/u, '');
+  let end = normalized.length;
+  while (end > 0 && /[\s.,!?;:"'()[\]{}]/u.test(normalized.charAt(end - 1))) {
+    end -= 1;
+  }
+  return normalized.slice(0, end).split(/\s+/u).join(' ');
 }
 
 /** The v2 grouping policy, driven by timed public text rather than engine frames. */
@@ -63,6 +71,7 @@ export class TranscriptGrouping {
   private readonly options: Required<TranscriptGrouperOptions>;
   private readonly idPrefix: string;
   private readonly acknowledgments: readonly string[];
+  private readonly maxAcknowledgmentLength: number;
 
   constructor(options: Required<TranscriptGrouperOptions>, idPrefix: string) {
     this.options = options;
@@ -71,6 +80,11 @@ export class TranscriptGrouping {
       ...ACKNOWLEDGMENTS,
       ...options.additionalAcknowledgments.map(normalizeAcknowledgment).filter(Boolean),
     ];
+    let maxLength = 0;
+    for (const acknowledgment of this.acknowledgments) {
+      maxLength = Math.max(maxLength, acknowledgment.length);
+    }
+    this.maxAcknowledgmentLength = maxLength;
   }
 
   get speaker(): TranscriptFragment['speaker'] | undefined {
@@ -183,16 +197,22 @@ export class TranscriptGrouping {
       this.buffer(fragment);
       return this.promote();
     }
+    const withinDuration =
+      fragment.endMs - (this.buffered?.startMs ?? fragment.startMs) < this.options.backchannelMaxDurationMs;
+    const acknowledgment = this.acknowledgment(fragment, withinDuration);
+    const normalized = withinDuration ? acknowledgment.text : undefined;
     if (separation < this.options.minTurnSeparationMs) {
-      this.buffer(fragment, this.possibleAcknowledgment(fragment));
-      return [];
-    }
-    if (this.buffered && this.standaloneAcknowledgment(fragment, this.buffered)) {
-      this.buffer(fragment, true);
+      this.buffer(
+        fragment,
+        normalized !== undefined &&
+          normalized.length > 0 &&
+          this.acknowledgments.some((phrase) => phrase.startsWith(normalized)),
+        acknowledgment,
+      );
       return [];
     }
-    if (!this.buffered && this.standaloneAcknowledgment(fragment)) {
-      this.buffer(fragment, false);
+    if (normalized !== undefined && this.acknowledgments.includes(normalized)) {
+      this.buffer(fragment, this.buffered !== undefined, acknowledgment);
       return [];
     }
     this.buffered = this.maybeDropBackchannel(undefined, fragment);
@@ -227,7 +247,7 @@ export class TranscriptGrouping {
     turn.endMs = Math.max(turn.endMs, fragment.endMs);
   }
 
-  private buffer(fragment: TranscriptFragment, canDrop?: boolean): void {
+  private buffer(fragment: TranscriptFragment, canDrop?: boolean, acknowledgment?: Acknowledgment): void {
     if (this.buffered) {
       TranscriptGrouping.append(this.buffered, fragment);
     } else {
@@ -236,6 +256,7 @@ export class TranscriptGrouping {
     if (canDrop !== undefined) {
       this.buffered.canDropAsBackchannel = canDrop;
     }
+    this.buffered.acknowledgment = acknowledgment;
   }
 
   private promote(): GroupingUpdate[] {
@@ -344,19 +365,30 @@ export class TranscriptGrouping {
     return this.buffered.canDropAsBackchannel ? undefined : this.buffered;
   }
 
-  private standaloneAcknowledgment(fragment: TranscriptFragment, previous?: Turn): boolean {
-    return (
-      fragment.endMs - (previous?.startMs ?? fragment.startMs) < this.options.backchannelMaxDurationMs &&
-      this.acknowledgments.includes(normalizeAcknowledgment((previous?.text ?? '') + fragment.text))
-    );
-  }
-
-  private possibleAcknowledgment(fragment: TranscriptFragment): boolean {
-    const text = normalizeAcknowledgment((this.buffered?.text ?? '') + fragment.text);
-    return (
-      fragment.endMs - (this.buffered?.startMs ?? fragment.startMs) < this.options.backchannelMaxDurationMs &&
-      text.length > 0 &&
-      this.acknowledgments.some((acknowledgment) => acknowledgment.startsWith(text))
-    );
+  private acknowledgment(fragment: TranscriptFragment, withinDuration: boolean): Acknowledgment {
+    const previous = this.buffered?.acknowledgment;
+    const previousCharacters = previous?.characters ?? 0;
+    let characters = previousCharacters;
+    const separator = /[\s.,!?;:"'()[\]{}-]/u;
+    for (
+      let index = 0;
+      index < fragment.text.length && characters <= this.maxAcknowledgmentLength;
+      index += 1
+    ) {
+      if (!separator.test(fragment.text.charAt(index))) {
+        characters += 1;
+      }
+    }
+    // Significant characters cannot disappear during normalization. Once they
+    // outgrow the configured phrases, stop counting without allocating tokens.
+    let text: string | undefined;
+    if (characters === previousCharacters && previous?.text !== undefined) {
+      // Keep the raw suffix in the turn: later text can make punctuation internal.
+      ({ text } = previous);
+    } else if (withinDuration && characters <= this.maxAcknowledgmentLength) {
+      // Retain whole-string Unicode casing (including context-sensitive sigma).
+      text = normalizeAcknowledgment((this.buffered?.text ?? '') + fragment.text);
+    }
+    return { characters, text };
   }
 }

package/src/resources/beta/responses/internal-base.ts

@@ -79,6 +79,11 @@ export abstract class ResponsesEmitter extends EventEmitter<WebSocketEvents> {
   protected _onError(event: WebSocketErrorEvent | null, message?: string | undefined, cause?: any): void {
     const eventMessage = event && ('error' in event ? event.error?.message : event.message);
     message = message ?? eventMessage ?? safeJSONStringify(event) ?? 'unknown error';
+    try {
+      message = String(message);
+    } catch {
+      message = '[unserializable error value]';
+    }
 
     if (!this._hasListener('error')) {
       const error = new WebSocketError(