openai 7.4.0 → 7.6.0

package/src/auth/x509-transport.ts

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { setTimeout as delay } from 'node:timers/promises';
+import {
+  createX509Transport as createCapability,
+  registerX509Transport,
+  sendX509Request,
+} from '../internal/auth/x509-transport-capability';
+import type { X509Transport, X509TransportOptions } from '../internal/auth/x509-transport-capability';
+import { exchangeX509Token } from '../internal/auth/x509-token-exchange';
+import { isRetryableX509TransportFailure } from '../internal/auth/x509-transport-registry';
+import type { X509RequestScope } from '../internal/auth/x509-transport-registry';
+import { markTransientX509ConnectionError } from '#x509-transport-state';
+
+/** Creates one frozen, caller-attested Node.js transport for X.509 workload authentication. */
+export function createX509Transport(options: X509TransportOptions): X509Transport {
+  const capability = createCapability(options);
+  const scopes = new AsyncLocalStorage<X509RequestScope>();
+  registerX509Transport(capability, {
+    dispatch: async (target, requestOptions) => {
+      try {
+        return await sendX509Request(capability, target, requestOptions);
+      } catch (error) {
+        if (error instanceof Error && isRetryableX509TransportFailure(error)) {
+          markTransientX509ConnectionError(error);
+        }
+        throw error;
+      }
+    },
+    exchange: async (identityProviderId, serviceAccountId, signal) =>
+      await exchangeX509Token({
+        transport: capability,
+        identityProviderId,
+        serviceAccountId,
+        ...(signal ? { signal } : {}),
+      }),
+    run: (operation) =>
+      scopes.run({ wallStartedAt: Date.now(), monotonicStartedAt: performance.now() }, operation),
+    current: () => scopes.getStore(),
+    resume: (scope, operation) => scopes.run(scope, operation),
+    sleep: async (duration, signal) => await delay(duration, undefined, { signal: signal ?? undefined }),
+  });
+  return capability;
+}
+
+export type {
+  X509ProxyMode,
+  X509Transport,
+  X509TransportOptions,
+} from '../internal/auth/x509-transport-capability';

package/src/azure.ts

@@ -1,17 +1,32 @@
-import type { RequestInit } from './internal/builtin-types';
+import type { RequestInit, RequestInfo, Response } from './internal/builtin-types';
 import type { NullableHeaders } from './internal/headers';
 import { buildHeaders } from './internal/headers';
 import * as Errors from './error';
-import { FinalRequestOptions } from './internal/request-options';
+import type { FinalRequestOptions } from './internal/request-options';
 import { isObj, readEnv } from './internal/utils';
+import { path } from './internal/utils/path';
 import { OpenAI } from './client';
 import type { ClientOptions } from './client';
+import type { WorkloadIdentity } from './auth/types';
+import { assertNoDataResidency } from './internal/data-residency';
 
 /** API Client for interfacing with the Azure OpenAI API. */
-export interface AzureClientOptions extends Omit<ClientOptions, 'provider'> {
+export interface AzureClientOptions extends Omit<
+  ClientOptions,
+  'provider' | 'dataResidency' | 'workloadIdentity' | 'x509Transport'
+> {
   /** AzureOpenAI does not support third-party provider configuration. */
   provider?: never;
 
+  /** OpenAI data residency cannot be combined with Azure routing. */
+  dataResidency?: never;
+
+  /** Azure cannot receive OpenAI X.509 workload-identity certificate transports. */
+  x509Transport?: never;
+
+  /** Existing subject-token workload-identity configuration remains unchanged. */
+  workloadIdentity?: WorkloadIdentity | undefined;
+
   /**
    * Defaults to process.env['OPENAI_API_VERSION'].
    */
@@ -23,8 +38,9 @@ export interface AzureClientOptions extends Omit<ClientOptions, 'provider'> {
   endpoint?: string | undefined;
 
   /**
-   * A model deployment, if given, sets the base client URL to include `/deployments/{deployment}`.
-   * Note: this means you won't be able to use non-deployment endpoints. Not supported with Assistants APIs.
+   * Azure model deployment inserted into supported deployment-scoped request
+   * paths. The client's base URL remains unchanged, so non-deployment endpoints
+   * remain available.
    */
   deployment?: string | undefined;
 
@@ -42,25 +58,27 @@ export interface AzureClientOptions extends Omit<ClientOptions, 'provider'> {
 
 /** API Client for interfacing with the Azure OpenAI API. */
 export class AzureOpenAI extends OpenAI {
+  /** Azure deployment configured for deployment-scoped model requests. */
   deploymentName: string | undefined;
-  apiVersion: string = '';
+  /** Azure OpenAI API version included in requests made by this client. */
+  apiVersion = '';
 
   /**
    * API Client for interfacing with the Azure OpenAI API.
    *
-   * @param {string | undefined} [opts.apiVersion=process.env['OPENAI_API_VERSION'] ?? undefined]
-   * @param {string | undefined} [opts.endpoint=process.env['AZURE_OPENAI_ENDPOINT'] ?? undefined] - Your Azure endpoint, including the resource, e.g. `https://example-resource.azure.openai.com/`
-   * @param {string | undefined} [opts.apiKey=process.env['AZURE_OPENAI_API_KEY'] ?? undefined]
-   * @param {string | undefined} opts.deployment - A model deployment, if given, sets the base client URL to include `/deployments/{deployment}`.
-   * @param {string | null | undefined} [opts.organization=process.env['OPENAI_ORG_ID'] ?? null]
-   * @param {string} [opts.baseURL=process.env['OPENAI_BASE_URL']] - Sets the base URL for the API, e.g. `https://example-resource.azure.openai.com/openai/`.
-   * @param {number} [opts.timeout=10 minutes] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
-   * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
+   * @param {string | undefined} [opts.apiVersion] - Defaults to `process.env['OPENAI_API_VERSION'] ?? undefined`.
+   * @param {string | undefined} [opts.endpoint] - Your Azure endpoint, including the resource, e.g. `https://example-resource.azure.openai.com/`. Defaults to `process.env['AZURE_OPENAI_ENDPOINT'] ?? undefined`.
+   * @param {string | undefined} [opts.apiKey] - Defaults to `process.env['AZURE_OPENAI_API_KEY'] ?? undefined`.
+   * @param {string | undefined} opts.deployment - Azure model deployment inserted into supported deployment-scoped request paths.
+   * @param {string | null | undefined} [opts.organization] - Defaults to `process.env['OPENAI_ORG_ID'] ?? null`.
+   * @param {string} [opts.baseURL] - Sets the base URL for the API, e.g. `https://example-resource.azure.openai.com/openai/`. Defaults to `process.env['OPENAI_BASE_URL']`.
+   * @param {number} [opts.timeout] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out. Defaults to 10 minutes.
+   * @param {() => Promise<string>} [opts.azureADTokenProvider] - Returns a fresh Microsoft Entra access token for each request; cannot be combined with `apiKey`.
    * @param {Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
-   * @param {number} [opts.maxRetries=2] - The maximum number of times the client will retry a request.
+   * @param {number} [opts.maxRetries] - The maximum number of times the client will retry a request. Defaults to `2`.
    * @param {Headers} opts.defaultHeaders - Default headers to include with every request to the API.
    * @param {DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
-   * @param {boolean} [opts.dangerouslyAllowBrowser=false] - By default, client-side use of this library is not allowed, as it risks exposing your secret API credentials to attackers.
+   * @param {boolean} [opts.dangerouslyAllowBrowser] - By default, client-side use of this library is not allowed, as it risks exposing your secret API credentials to attackers. Defaults to `false`.
    */
   constructor({
     baseURL = readEnv('OPENAI_BASE_URL'),
@@ -70,8 +88,10 @@ export class AzureOpenAI extends OpenAI {
     deployment,
     azureADTokenProvider,
     dangerouslyAllowBrowser,
+    dataResidency,
     ...opts
   }: AzureClientOptions = {}) {
+    assertNoDataResidency(dataResidency, 'AzureOpenAI');
     if (!apiVersion) {
       throw new Errors.OpenAIError(
         "The OPENAI_API_VERSION environment variable is missing or empty; either provide it, or instantiate the AzureOpenAI client with an apiVersion option, like new AzureOpenAI({ apiVersion: 'My API Version' }).",
@@ -79,7 +99,7 @@ export class AzureOpenAI extends OpenAI {
     }
 
     if (typeof azureADTokenProvider === 'function') {
-      dangerouslyAllowBrowser = true;
+      dangerouslyAllowBrowser ??= true;
     }
 
     if (!azureADTokenProvider && !apiKey) {
@@ -112,37 +132,72 @@ export class AzureOpenAI extends OpenAI {
         endpointEnd--;
       }
       baseURL = `${endpoint.slice(0, endpointEnd)}/openai`;
-    } else {
-      if (endpoint) {
-        throw new Errors.OpenAIError('baseURL and endpoint are mutually exclusive');
-      }
+    } else if (endpoint) {
+      throw new Errors.OpenAIError('baseURL and endpoint are mutually exclusive');
     }
 
     super({
       apiKey: azureADTokenProvider ?? apiKey,
       baseURL,
       ...opts,
-      ...(dangerouslyAllowBrowser !== undefined ? { dangerouslyAllowBrowser } : {}),
+      ...(dangerouslyAllowBrowser === undefined ? {} : { dangerouslyAllowBrowser }),
     });
 
     this.apiVersion = apiVersion;
     this.deploymentName = deployment;
   }
 
+  /** Clones this client with Azure options; OpenAI data residency remains unsupported. */
+  override withOptions(options: Partial<AzureClientOptions>): this {
+    return super.withOptions(options);
+  }
+
+  /** Builds an Azure request and inserts its deployment into model-scoped endpoint paths. */
   override async buildRequest(
     options: FinalRequestOptions,
-    props: { retryCount?: number } = {},
-  ): Promise<{ req: RequestInit & { headers: Headers }; url: string; timeout: number }> {
+    props: {
+      /** Number of retries already attempted for the current request. */
+      retryCount?: number;
+    } = {},
+  ): Promise<{
+    /** Fetch request options after authentication, headers, and the body are prepared. */
+    req: RequestInit & {
+      /** Fully resolved request headers sent to Azure OpenAI. */
+      headers: Headers;
+    };
+    /** Absolute deployment-aware request URL. */
+    url: string;
+    /** Request timeout in milliseconds. */
+    timeout: number;
+  }> {
     if (_deployments_endpoints.has(options.path) && options.method === 'post' && options.body !== undefined) {
       if (!isObj(options.body)) {
         throw new Error('Expected request body to be an object');
       }
       const model = this.deploymentName || options.body['model'] || options.__metadata?.['model'];
       if (model !== undefined && !this.baseURL.includes('/deployments')) {
-        options.path = `/deployments/${model}${options.path}`;
+        options.path = path`/deployments/${model}` + options.path;
       }
     }
-    return super.buildRequest(options, props);
+    const built = await super.buildRequest(options, props);
+    if (built.req.headers.has('api-key')) {
+      built.req.redirect = 'manual';
+    }
+    return built;
+  }
+
+  protected override async fetchWithAuth(
+    url: RequestInfo,
+    init: RequestInit,
+    timeout: number,
+    controller: AbortController,
+    schemes?: { bearerAuth?: boolean; adminAPIKeyAuth?: boolean },
+  ): Promise<Response> {
+    if (new Headers(init.headers).has('api-key')) {
+      init.redirect = 'manual';
+    }
+
+    return super.fetchWithAuth(url, init, timeout, controller, schemes);
   }
 
   protected override async authHeaders(

package/src/bedrock.ts

@@ -1,6 +1,13 @@
 import * as Errors from './error';
 import { OpenAI } from './client';
 import type { ApiKeySetter, ClientOptions } from './client';
+import { assertNoDataResidency } from './internal/data-residency';
+import {
+  assertBedrockRequestOrigin,
+  assertValidBedrockBearerCredential,
+  brand_privateBedrockClient,
+} from './internal/bedrock';
+import type { RequestInit } from './internal/builtin-types';
 import type { NullableHeaders } from './internal/headers';
 import { buildHeaders } from './internal/headers';
 import type { FinalRequestOptions, RequestOptions } from './internal/request-options';
@@ -10,8 +17,11 @@ import type { ResponseStreamParams } from './lib/responses/ResponseStream';
 import * as API from './resources/index';
 import type * as ResponsesAPI from './resources/responses/responses';
 
-export interface BedrockClientOptions
-  extends Omit<ClientOptions, 'apiKey' | 'adminAPIKey' | 'baseURL' | 'workloadIdentity'> {
+/** Configures Amazon Bedrock's OpenAI-compatible endpoint and bearer-token authentication. */
+export interface BedrockClientOptions extends Omit<
+  ClientOptions,
+  'apiKey' | 'adminAPIKey' | 'baseURL' | 'workloadIdentity' | 'x509Transport' | 'dataResidency'
+> {
   /**
    * Bedrock bearer token used for authentication.
    *
@@ -33,11 +43,17 @@ export interface BedrockClientOptions
    */
   adminAPIKey?: never;
 
+  /** OpenAI data residency cannot be combined with Bedrock routing. */
+  dataResidency?: never;
+
   /**
    * BedrockOpenAI only supports Bedrock bearer token authentication.
    */
   workloadIdentity?: never;
 
+  /** Bedrock cannot receive OpenAI X.509 workload-identity certificate transports. */
+  x509Transport?: never;
+
   /**
    * AWS region used to derive the default Bedrock Mantle endpoint.
    *
@@ -59,6 +75,11 @@ function deriveBedrockBaseURL(awsRegion: string | undefined): string {
       'Must provide one of the `baseURL` or `awsRegion` arguments, or set the `AWS_BEDROCK_BASE_URL`, `AWS_REGION`, or `AWS_DEFAULT_REGION` environment variable.',
     );
   }
+  if (!/^[a-z]{2,8}(?:-[a-z0-9]+)+-\d+$/u.test(region)) {
+    throw new Errors.OpenAIError(
+      'The Bedrock AWS `region` is invalid. Use a standard AWS region such as `us-east-1`.',
+    );
+  }
 
   return `https://bedrock-mantle.${region}.api.aws/openai/v1`;
 }
@@ -100,14 +121,21 @@ function restoreBedrockStreamOutputText(responses: API.Responses): API.Responses
 
 /** API Client for interfacing with Amazon Bedrock's OpenAI-compatible endpoint. */
 export class BedrockOpenAI extends OpenAI {
+  /**
+   * Identifies this client to credential-bearing WebSocket helpers.
+   *
+   * @internal
+   */
+  readonly [brand_privateBedrockClient] = true;
+
   private readonly bedrockTokenProvider: ApiKeySetter | undefined;
 
   /**
    * API Client for interfacing with Amazon Bedrock's OpenAI-compatible endpoint.
    *
-   * @param {string | null | undefined} [opts.apiKey=process.env['AWS_BEARER_TOKEN_BEDROCK'] ?? null]
-   * @param {string | null | undefined} [opts.baseURL=process.env['AWS_BEDROCK_BASE_URL'] ?? derived from opts.awsRegion or AWS_REGION/AWS_DEFAULT_REGION]
-   * @param {string | undefined} [opts.awsRegion=process.env['AWS_REGION'] ?? process.env['AWS_DEFAULT_REGION'] ?? undefined]
+   * @param {string | null | undefined} [opts.apiKey] - Defaults to `process.env['AWS_BEARER_TOKEN_BEDROCK'] ?? null`.
+   * @param {string | null | undefined} [opts.baseURL] - Defaults to `process.env['AWS_BEDROCK_BASE_URL']`, or is derived from `opts.awsRegion`, `AWS_REGION`, or `AWS_DEFAULT_REGION`.
+   * @param {string | undefined} [opts.awsRegion] - Defaults to `process.env['AWS_REGION'] ?? process.env['AWS_DEFAULT_REGION'] ?? undefined`.
    * @param {ApiKeySetter | undefined} opts.bedrockTokenProvider - A function that returns a Bedrock bearer token and is invoked before each request.
    */
   constructor({
@@ -117,9 +145,12 @@ export class BedrockOpenAI extends OpenAI {
     bedrockTokenProvider,
     adminAPIKey,
     workloadIdentity,
+    x509Transport,
+    dataResidency,
     ...opts
   }: BedrockClientOptions = {}) {
-    if (adminAPIKey || workloadIdentity) {
+    assertNoDataResidency(dataResidency, 'BedrockOpenAI');
+    if (adminAPIKey || workloadIdentity || x509Transport) {
       throw new Errors.OpenAIError('BedrockOpenAI only supports Bedrock bearer token authentication.');
     }
 
@@ -154,17 +185,59 @@ export class BedrockOpenAI extends OpenAI {
       ...opts,
     });
 
+    let currentApiKey = this.apiKey;
+    Object.defineProperty(this, 'apiKey', {
+      enumerable: true,
+      configurable: true,
+      get() {
+        if (currentApiKey !== null) {
+          assertValidBedrockBearerCredential(currentApiKey);
+        }
+        return currentApiKey;
+      },
+      set(nextApiKey: string | null) {
+        currentApiKey = nextApiKey;
+      },
+    });
+
+    const trustedBaseURL = this.baseURL;
+    let currentBaseURL = trustedBaseURL;
+    Object.defineProperty(this, 'baseURL', {
+      enumerable: true,
+      configurable: false,
+      get() {
+        return currentBaseURL;
+      },
+      set(nextBaseURL: string) {
+        assertBedrockRequestOrigin(trustedBaseURL, nextBaseURL);
+        currentBaseURL = nextBaseURL;
+      },
+    });
+
     this.bedrockTokenProvider = bedrockTokenProvider;
     this.responses = restoreBedrockStreamOutputText(new API.Responses(this));
   }
 
   protected override async prepareOptions(options: FinalRequestOptions): Promise<void> {
+    const configuredBaseURL = this._options.baseURL ?? this.baseURL;
+    assertBedrockRequestOrigin(configuredBaseURL, this.buildURL(options.path, null, options.defaultBaseURL));
+
     const security = options.__security ?? { bearerAuth: true };
     if (security.adminAPIKeyAuth && !security.bearerAuth) {
       await this._callApiKey();
     }
 
     await super.prepareOptions(options);
+    assertBedrockRequestOrigin(configuredBaseURL, this.buildURL(options.path, null, options.defaultBaseURL));
+  }
+
+  protected override async prepareRequest(
+    request: RequestInit,
+    context: { url: string; options: FinalRequestOptions },
+  ): Promise<void> {
+    assertBedrockRequestOrigin(this._options.baseURL ?? this.baseURL, context.url);
+    await super.prepareRequest(request, context);
+    request.redirect = 'manual';
   }
 
   protected override async authHeaders(
@@ -172,16 +245,27 @@ export class BedrockOpenAI extends OpenAI {
     schemes?: { bearerAuth?: boolean; adminAPIKeyAuth?: boolean },
   ): Promise<NullableHeaders | undefined> {
     const security = schemes ?? { bearerAuth: true, adminAPIKeyAuth: true };
-    if ((security.bearerAuth || security.adminAPIKeyAuth) && this.apiKey !== null) {
-      return buildHeaders([{ Authorization: `Bearer ${this.apiKey}` }]);
+    const credential = this.apiKey;
+    if ((security.bearerAuth || security.adminAPIKeyAuth) && credential !== null) {
+      assertValidBedrockBearerCredential(credential);
+      try {
+        return buildHeaders([{ Authorization: `Bearer ${credential}` }]);
+      } catch (error) {
+        if (error instanceof TypeError) {
+          // oxlint-disable-next-line eslint/preserve-caught-error -- The original error contains the bearer credential.
+          throw new TypeError('Bedrock bearer credential contains an invalid HTTP header value.');
+        }
+        throw error;
+      }
     }
 
     return super.authHeaders(opts, security);
   }
 
+  /** Clones this client while preserving its refreshable Bedrock token provider when appropriate. */
   override withOptions(options: Partial<BedrockClientOptions>): this {
     const bedrockTokenProvider =
-      options.apiKey !== undefined ? undefined : options.bedrockTokenProvider ?? this.bedrockTokenProvider;
+      options.apiKey === undefined ? (options.bedrockTokenProvider ?? this.bedrockTokenProvider) : undefined;
 
     return super.withOptions({
       ...options,

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

@@ -1,9 +1,40 @@
-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';
+import { assertX509WebSocketSupported } from '../../internal/auth/x509-workload-identity-auth';
+
+/** Parses frame data without exposing malformed payloads through JSON syntax errors. */
+export function parseRealtimeEvent(data: string): RealtimeServerEvent {
+  try {
+    return JSON.parse(data) as RealtimeServerEvent;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new SyntaxError('Could not parse Realtime WebSocket event data as JSON.');
+    }
+
+    throw error;
+  }
+}
 
+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 +45,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 +59,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 +143,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,10 +168,17 @@ 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,
 ): URL {
+  assertX509WebSocketSupported(client);
   const config: RealtimeConnectionConfig =
     typeof connection === 'string' ? { model: connection } : connection;
   const baseURL = client.baseURL;
@@ -120,12 +201,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;
 }