openai 7.3.0 → 7.5.0

package/src/beta/realtime/internal-base.ts

@@ -1,9 +1,26 @@
-import { RealtimeClientEvent, RealtimeServerEvent, ErrorEvent } from '../../resources/beta/realtime/realtime';
+import type {
+  RealtimeClientEvent,
+  RealtimeServerEvent,
+  ErrorEvent,
+} from '../../resources/beta/realtime/realtime';
 import { EventEmitter } from '../../lib/EventEmitter';
 import { OpenAIError } from '../../error';
-import OpenAI, { AzureOpenAI } from '../../index';
+import type OpenAI from '../../index';
+import { AzureOpenAI } from '../../index';
+
+function safeErrorValue(value: unknown): string {
+  try {
+    return String(value);
+  } catch {
+    return '[unserializable error value]';
+  }
+}
 
+/** An API-reported or client-side error encountered by a beta Realtime connection. */
 export class OpenAIRealtimeError extends OpenAIError {
+  /** Stable error name used to identify Realtime connection failures. */
+  override name = 'OpenAIRealtimeError';
+
   /**
    * The error data that the API sent back in an `error` event.
    */
@@ -14,6 +31,12 @@ export class OpenAIRealtimeError extends OpenAIError {
    */
   event_id?: string | undefined;
 
+  /**
+   * Creates a beta Realtime error, preserving server-provided details when available.
+   *
+   * @param message Human-readable API or connection error description.
+   * @param event Server error event, or `null` for a client-side failure.
+   */
   constructor(message: string, event: ErrorEvent | null) {
     super(message);
 
@@ -22,37 +45,69 @@ export class OpenAIRealtimeError extends OpenAIError {
   }
 }
 
+/** Materializes mapped beta Realtime listener properties without changing their public types. */
+// oxlint-disable-next-line typescript/ban-types -- The empty intersection materializes the mapped event shape without changing its public type.
 type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
 
+/**
+ * Maps beta Realtime server event types to their corresponding strongly typed listener callbacks.
+ *
+ * The `event` listener observes every server event, `error` receives normalized
+ * API or transport failures, and other keys match non-error server event types.
+ */
 type RealtimeEvents = Simplify<
   {
+    /** Receives every server event before its event-specific listener is notified. */
     event: (event: RealtimeServerEvent) => void;
+
+    /** Receives API-reported errors and client-side WebSocket failures. */
     error: (error: OpenAIRealtimeError) => void;
   } & {
+    /** Dispatches each non-error server event with the payload matching its event type. */
     [EventType in Exclude<RealtimeServerEvent['type'], 'error'>]: (
-      event: Extract<RealtimeServerEvent, { type: EventType }>,
+      event: Extract<
+        RealtimeServerEvent,
+        {
+          /** Server-event discriminator associated with this specific listener. */
+          type: EventType;
+        }
+      >,
     ) => unknown;
   }
 >;
 
+/**
+ * Typed event emitter shared by the beta Realtime WebSocket implementations.
+ *
+ * Listen for `event` to receive all server events, or subscribe to a specific
+ * server event's `type`. Always register an `error` listener; otherwise API and
+ * transport failures are reported as unhandled promise rejections.
+ */
 export abstract class OpenAIRealtimeEmitter extends EventEmitter<RealtimeEvents> {
   /**
-   * Send an event to the API.
+   * Serializes and sends a client event after the underlying WebSocket is open.
+   * Serialization and transport failures are delivered to the `error` event.
    */
   abstract send(event: RealtimeClientEvent): void;
 
   /**
-   * Close the websocket connection.
+   * Closes the WebSocket with status code `1000` and reason `OK` by default.
+   * Connection-closing failures are delivered to the `error` event.
    */
-  abstract close(props?: { code: number; reason: string }): void;
+  abstract close(props?: {
+    /** WebSocket close status code; defaults to `1000`. */
+    code: number;
+
+    /** WebSocket close reason; defaults to `OK`. */
+    reason: string;
+  }): void;
 
   protected _onError(event: null, message: string, cause: any): void;
   protected _onError(event: ErrorEvent, message?: string | undefined): void;
   protected _onError(event: ErrorEvent | null, message?: string | undefined, cause?: any): void {
-    message =
-      event?.error ?
-        `${event.error.message} code=${event.error.code} param=${event.error.param} type=${event.error.type} event_id=${event.error.event_id}`
-      : message ?? 'unknown error';
+    message = event?.error
+      ? `${safeErrorValue(event.error.message)} code=${safeErrorValue(event.error.code)} param=${safeErrorValue(event.error.param)} type=${safeErrorValue(event.error.type)} event_id=${safeErrorValue(event.error.event_id)}`
+      : (message ?? 'unknown error');
 
     if (!this._hasListener('error')) {
       const error = new OpenAIRealtimeError(
@@ -74,19 +129,24 @@ export abstract class OpenAIRealtimeEmitter extends EventEmitter<RealtimeEvents>
   }
 }
 
+/** Reports whether the client is an Azure OpenAI client with Azure-specific Realtime routing. */
 export function isAzure(client: Pick<OpenAI, 'apiKey' | 'baseURL'>): client is AzureOpenAI {
   return client instanceof AzureOpenAI;
 }
 
+/** Starts a beta Realtime model session or attaches to one existing non-Azure call. */
 export type RealtimeConnectionConfig =
   | {
       /**
        * Start a new Realtime session using the given model.
        */
       model: string;
+
+      /** Existing call identifier; cannot be supplied when starting a model-backed session. */
       callID?: undefined;
     }
   | {
+      /** Model name; cannot be supplied when attaching to an existing call. */
       model?: undefined;
       /**
        * Attach to an in-progress Realtime call over a sideband control connection.
@@ -94,6 +154,12 @@ export type RealtimeConnectionConfig =
       callID: string;
     };
 
+/**
+ * Builds the secure WebSocket URL for a beta Realtime session or non-Azure sideband call.
+ *
+ * @throws {Error} If both `model` and `callID`, or neither, are supplied, or an
+ * Azure sideband call is requested through the beta helpers.
+ */
 export function buildRealtimeURL(
   client: Pick<OpenAI, 'apiKey' | 'baseURL'>,
   connection: string | RealtimeConnectionConfig,
@@ -120,12 +186,10 @@ export function buildRealtimeURL(
     }
     url.searchParams.set('api-version', client.apiVersion);
     url.searchParams.set('deployment', config.model!);
+  } else if (hasCallID) {
+    url.searchParams.set('call_id', config.callID!);
   } else {
-    if (hasCallID) {
-      url.searchParams.set('call_id', config.callID!);
-    } else {
-      url.searchParams.set('model', config.model!);
-    }
+    url.searchParams.set('model', config.model!);
   }
   return url;
 }

package/src/beta/realtime/websocket.ts

@@ -1,35 +1,75 @@
-import { AzureOpenAI, OpenAI } from '../../index';
+import type { AzureOpenAI } from '../../index';
+import { assertBedrockWebSocketOrigin } from '../../internal/bedrock';
+import { OpenAI } from '../../index';
 import { OpenAIError } from '../../error';
 import type { RealtimeClientEvent, RealtimeServerEvent } from '../../resources/beta/realtime/realtime';
-import {
-  OpenAIRealtimeEmitter,
-  buildRealtimeURL,
-  isAzure,
-  type RealtimeConnectionConfig,
-} from './internal-base';
+import { OpenAIRealtimeEmitter, buildRealtimeURL, isAzure } from './internal-base';
+import type { RealtimeConnectionConfig } from './internal-base';
 import { isRunningInBrowser } from '../../internal/detect-platform';
 
 interface MessageEvent {
   data: string;
 }
 
-type _WebSocket =
-  typeof globalThis extends (
-    {
-      WebSocket: infer ws extends abstract new (...args: any) => any;
-    }
-  ) ?
-    // @ts-ignore
+/** Native WebSocket instance supplied by the current JavaScript runtime. */
+type _WebSocket = typeof globalThis extends {
+  /** Runtime-provided WebSocket constructor used for native Realtime connections. */
+  WebSocket: infer ws extends abstract new (...args: any) => any;
+}
+  ? // @ts-ignore
     InstanceType<ws>
   : any;
 
+/** Removes Azure credential query values from the publicly exposed connection URL. */
+function redactAzureCredentials(url: URL): void {
+  const hasAuthorization = url.searchParams.has('Authorization');
+  if (url.searchParams.has('api-key') || !hasAuthorization) {
+    url.searchParams.set('api-key', '<REDACTED>');
+  }
+  if (hasAuthorization) {
+    url.searchParams.set('Authorization', '<REDACTED>');
+  }
+}
+
+/**
+ * Connects to the beta Realtime API using the runtime's native `WebSocket` implementation.
+ *
+ * Browser use is blocked by default to prevent secret API-key exposure. Prefer
+ * an ephemeral Realtime credential in browsers and register an SDK `error`
+ * listener before using the connection. Use the stable Realtime helper for
+ * Azure sideband calls.
+ */
+function resolveRealtimeURL(
+  client: Pick<OpenAI, 'apiKey' | 'baseURL'>,
+  props: RealtimeConnectionConfig & { __url?: URL | undefined },
+): URL {
+  return props.__url ?? buildRealtimeURL(client, props);
+}
+
 export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
+  /** Secure beta Realtime WebSocket URL; Azure authentication query parameters are redacted. */
   url: URL;
+
+  /** Underlying runtime-native WebSocket instance for connection lifecycle events. */
   socket: _WebSocket;
 
+  /**
+   * Immediately opens a beta Realtime session or attaches to an existing non-Azure call.
+   *
+   * Clients with function-based credentials must use
+   * {@link OpenAIRealtimeWebSocket.create}; Azure deployment sessions should use
+   * {@link OpenAIRealtimeWebSocket.azure}. Ephemeral credentials starting with
+   * `ek_` are permitted in browser runtimes automatically.
+   *
+   * @param props Exactly one of `model` or `callID` and optional browser-safety settings.
+   * @param client Existing client whose endpoint and API key should be reused.
+   * @throws {OpenAIError} If browser access would expose an unapproved credential.
+   */
   constructor(
     props: RealtimeConnectionConfig & {
+      /** Allows browser execution; use only when the credential cannot expose a secret API key. */
       dangerouslyAllowBrowser?: boolean;
+
       /**
        * Callback to mutate the URL, needed for Azure.
        * @internal
@@ -37,6 +77,9 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
       onURL?: (url: URL) => void;
       /** Indicates the token was resolved by the factory just before connecting. @internal */
       __resolvedApiKey?: boolean;
+
+      /** Final URL validated before an asynchronous credential provider ran. @internal */
+      __url?: URL;
     },
     client?: Pick<OpenAI, 'apiKey' | 'baseURL'>,
   ) {
@@ -63,8 +106,9 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
       );
     }
 
-    this.url = buildRealtimeURL(client, props);
+    this.url = resolveRealtimeURL(client, props);
     props.onURL?.(this.url);
+    assertBedrockWebSocketOrigin(client, this.url);
 
     // @ts-ignore
     this.socket = new WebSocket(this.url.toString(), [
@@ -100,24 +144,51 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     });
 
     if (isAzure(client)) {
-      if (this.url.searchParams.get('Authorization') !== null) {
-        this.url.searchParams.set('Authorization', '<REDACTED>');
-      } else {
-        this.url.searchParams.set('api-key', '<REDACTED>');
-      }
+      redactAzureCredentials(this.url);
     }
   }
 
+  /**
+   * Resolves a client's current API credential before opening a beta Realtime WebSocket.
+   *
+   * Use this factory instead of the constructor when the client's `apiKey` is a function.
+   *
+   * @param client OpenAI client that owns the endpoint and refreshable or static credential.
+   * @param props Exactly one of `model` or `callID` and optional browser-safety settings.
+   */
   static async create(
     client: Pick<OpenAI, 'apiKey' | 'baseURL' | '_callApiKey'>,
-    props: RealtimeConnectionConfig & { dangerouslyAllowBrowser?: boolean },
+    props: RealtimeConnectionConfig & {
+      /** Allows browser execution after the caller has secured the supplied credential. */
+      dangerouslyAllowBrowser?: boolean;
+    },
   ): Promise<OpenAIRealtimeWebSocket> {
-    return new OpenAIRealtimeWebSocket({ ...props, __resolvedApiKey: await client._callApiKey() }, client);
+    const url = buildRealtimeURL(client, props);
+    assertBedrockWebSocketOrigin(client, url);
+    const resolvedApiKey = await client._callApiKey();
+    return new OpenAIRealtimeWebSocket({ ...props, __resolvedApiKey: resolvedApiKey, __url: url }, client);
   }
 
+  /**
+   * Opens a native beta Azure OpenAI Realtime session for a model deployment.
+   *
+   * Azure credentials are redacted from the exposed `url` property immediately
+   * after connection setup. Use the stable Realtime helper to attach to an
+   * existing Azure call.
+   *
+   * @param client Azure OpenAI client that supplies the endpoint and credential.
+   * @param options Optional deployment override and browser-safety settings.
+   * @throws {Error} If the Azure credential or required deployment is unavailable.
+   */
   static async azure(
     client: Pick<AzureOpenAI, '_callApiKey' | 'apiVersion' | 'apiKey' | 'baseURL' | 'deploymentName'>,
-    options: { deploymentName?: string; dangerouslyAllowBrowser?: boolean } = {},
+    options: {
+      /** Azure model deployment; defaults to the deployment configured on the client. */
+      deploymentName?: string;
+
+      /** Allows browser execution after the caller has secured the supplied Azure credential. */
+      dangerouslyAllowBrowser?: boolean;
+    } = {},
   ): Promise<OpenAIRealtimeWebSocket> {
     const isApiKeyProvider = await client._callApiKey();
     const apiKey = client.apiKey;
@@ -141,14 +212,18 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
       {
         model: deploymentName,
         onURL,
-        ...(dangerouslyAllowBrowser ? { dangerouslyAllowBrowser } : {}),
+        ...(dangerouslyAllowBrowser === undefined ? {} : { dangerouslyAllowBrowser }),
         __resolvedApiKey: isApiKeyProvider,
       },
       client,
     );
   }
 
-  send(event: RealtimeClientEvent) {
+  /**
+   * Serializes and sends a beta Realtime client event after the WebSocket has opened.
+   * Serialization and transport failures are delivered to the SDK `error` event.
+   */
+  send(event: RealtimeClientEvent): void {
     try {
       this.socket.send(JSON.stringify(event));
     } catch (err) {
@@ -156,7 +231,17 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     }
   }
 
-  close(props?: { code: number; reason: string }) {
+  /**
+   * Closes the WebSocket with status code `1000` and reason `OK` by default.
+   * Connection-closing failures are delivered to the SDK `error` event.
+   */
+  close(props?: {
+    /** WebSocket close status code; defaults to `1000`. */
+    code: number;
+
+    /** WebSocket close reason; defaults to `OK`. */
+    reason: string;
+  }): void {
     try {
       this.socket.close(props?.code ?? 1000, props?.reason ?? 'OK');
     } catch (err) {

package/src/beta/realtime/ws.ts

@@ -1,21 +1,53 @@
 import * as WS from 'ws';
-import { AzureOpenAI, OpenAI } from '../../index';
+import { assertBedrockWebSocketOrigin } from '../../internal/bedrock';
+import { protectWebSocketOptionsFromCredentialRedirects } from '../../internal/ws';
+import type { AzureOpenAI } from '../../index';
+import { OpenAI } from '../../index';
 import type { RealtimeClientEvent, RealtimeServerEvent } from '../../resources/beta/realtime/realtime';
-import {
-  OpenAIRealtimeEmitter,
-  buildRealtimeURL,
-  isAzure,
-  type RealtimeConnectionConfig,
-} from './internal-base';
+import { OpenAIRealtimeEmitter, buildRealtimeURL, isAzure } from './internal-base';
+import type { RealtimeConnectionConfig } from './internal-base';
+
+/**
+ * Connects to the beta Realtime API using the Node.js `ws` WebSocket implementation.
+ *
+ * Install the optional `ws` peer dependency before importing this entrypoint.
+ * Register an SDK `error` listener and wait for `socket`'s `open` event before
+ * sending client events. Use the stable Realtime helper for Azure sideband calls.
+ */
+function resolveRealtimeURL(
+  client: Pick<OpenAI, 'apiKey' | 'baseURL'>,
+  props: RealtimeConnectionConfig & { __url?: URL | undefined },
+): URL {
+  return props.__url ?? buildRealtimeURL(client, props);
+}
 
 export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
+  /** Secure beta Realtime WebSocket URL, including the model or non-Azure call ID. */
   url: URL;
+
+  /** Underlying `ws.WebSocket` instance for connection lifecycle and transport events. */
   socket: WS.WebSocket;
 
+  /**
+   * Immediately opens a beta Realtime model session or attaches to an existing non-Azure call.
+   *
+   * Clients with function-based credentials must use
+   * {@link OpenAIRealtimeWS.create}; Azure deployment sessions should use
+   * {@link OpenAIRealtimeWS.azure}.
+   *
+   * @param props Exactly one of `model` or `callID`, plus optional `ws` client settings.
+   * @param client Existing client whose endpoint and API key should be reused.
+   */
   constructor(
     props: RealtimeConnectionConfig & {
+      /** Options passed directly to the underlying `ws.WebSocket` constructor. */
       options?: WS.ClientOptions | undefined;
-      /** @internal */ __resolvedApiKey?: boolean;
+
+      /** Indicates that a function-based credential was resolved by an async factory. @internal */
+      __resolvedApiKey?: boolean;
+
+      /** Final URL validated before an asynchronous credential provider ran. @internal */
+      __url?: URL;
     },
     client?: Pick<OpenAI, 'apiKey' | 'baseURL'>,
   ) {
@@ -30,15 +62,21 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
         ].join('\n'),
       );
     }
-    this.url = buildRealtimeURL(client, props);
-    this.socket = new WS.WebSocket(this.url, {
-      ...props.options,
-      headers: {
-        ...props.options?.headers,
-        ...(isAzure(client) && !props.__resolvedApiKey ? {} : { Authorization: `Bearer ${client.apiKey}` }),
-        'OpenAI-Beta': 'realtime=v1',
-      },
-    });
+    this.url = resolveRealtimeURL(client, props);
+    assertBedrockWebSocketOrigin(client, this.url);
+    const headers = {
+      ...props.options?.headers,
+      ...(isAzure(client) && !props.__resolvedApiKey ? {} : { Authorization: `Bearer ${client.apiKey}` }),
+      'OpenAI-Beta': 'realtime=v1',
+    };
+
+    this.socket = new WS.WebSocket(
+      this.url,
+      protectWebSocketOptionsFromCredentialRedirects({
+        ...props.options,
+        headers,
+      }),
+    );
 
     this.socket.on('message', (wsEvent) => {
       const event = (() => {
@@ -67,16 +105,47 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     });
   }
 
+  /**
+   * Resolves a client's current API credential before opening a beta Realtime connection.
+   *
+   * Use this factory instead of the constructor when the client's `apiKey` is a function.
+   *
+   * @param client OpenAI client that owns the endpoint and refreshable or static credential.
+   * @param props Exactly one of `model` or `callID`, plus optional `ws` client settings.
+   */
   static async create(
     client: Pick<OpenAI, 'apiKey' | 'baseURL' | '_callApiKey'>,
-    props: RealtimeConnectionConfig & { options?: WS.ClientOptions | undefined },
+    props: RealtimeConnectionConfig & {
+      /** Options passed directly to the underlying `ws.WebSocket` constructor. */
+      options?: WS.ClientOptions | undefined;
+    },
   ): Promise<OpenAIRealtimeWS> {
-    return new OpenAIRealtimeWS({ ...props, __resolvedApiKey: await client._callApiKey() }, client);
+    const url = buildRealtimeURL(client, props);
+    assertBedrockWebSocketOrigin(client, url);
+    const resolvedApiKey = await client._callApiKey();
+    return new OpenAIRealtimeWS({ ...props, __resolvedApiKey: resolvedApiKey, __url: url }, client);
   }
 
+  /**
+   * Opens a beta Azure OpenAI Realtime session for the selected model deployment.
+   *
+   * Static Azure API keys are sent in the `api-key` header; function-based
+   * credentials are resolved first and sent as bearer credentials. Use the
+   * stable Realtime helper when attaching to an existing Azure call.
+   *
+   * @param client Azure OpenAI client that supplies the endpoint and credential.
+   * @param props Optional deployment override and `ws` connection settings.
+   * @throws {Error} If the Azure credential or required deployment is unavailable.
+   */
   static async azure(
     client: Pick<AzureOpenAI, '_callApiKey' | 'apiVersion' | 'apiKey' | 'baseURL' | 'deploymentName'>,
-    props: { deploymentName?: string; options?: WS.ClientOptions | undefined } = {},
+    props: {
+      /** Azure model deployment; defaults to the deployment configured on the client. */
+      deploymentName?: string;
+
+      /** Options passed directly to the underlying `ws.WebSocket` constructor. */
+      options?: WS.ClientOptions | undefined;
+    } = {},
   ): Promise<OpenAIRealtimeWS> {
     const isApiKeyProvider = await client._callApiKey();
     const apiKey = client.apiKey;
@@ -103,7 +172,11 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     );
   }
 
-  send(event: RealtimeClientEvent) {
+  /**
+   * Serializes and sends a beta Realtime client event after the WebSocket has opened.
+   * Serialization and transport failures are delivered to the SDK `error` event.
+   */
+  send(event: RealtimeClientEvent): void {
     try {
       this.socket.send(JSON.stringify(event));
     } catch (err) {
@@ -111,7 +184,17 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     }
   }
 
-  close(props?: { code: number; reason: string }) {
+  /**
+   * Closes the WebSocket with status code `1000` and reason `OK` by default.
+   * Connection-closing failures are delivered to the SDK `error` event.
+   */
+  close(props?: {
+    /** WebSocket close status code; defaults to `1000`. */
+    code: number;
+
+    /** WebSocket close reason; defaults to `OK`. */
+    reason: string;
+  }): void {
     try {
       this.socket.close(props?.code ?? 1000, props?.reason ?? 'OK');
     } catch (err) {