openai 7.3.0 → 7.5.0

package/src/providers/bedrock/aws.ts

@@ -5,43 +5,62 @@ import { SignatureV4 } from '@smithy/signature-v4';
 import * as Errors from '../../error';
 import type { BodyInit } from '../../internal/builtin-types';
 import {
+  assertBedrockRequestOrigin,
   assertProviderOwnsAuthorization,
   errorWithCause,
   normalizeOptionalString,
+  parseBedrockEndpointHostname,
   resolveBedrockBearerAuth,
   resolveBedrockEndpoint,
-  type BedrockBearerOptions,
-  type BedrockEndpointOptions,
-  type BedrockRequestAuth,
 } from '../../internal/bedrock';
-import { createProvider, type Provider, type ProviderRequestContext } from '../../internal/provider';
+import type {
+  BedrockBearerOptions,
+  BedrockEndpoint,
+  BedrockEndpointOptions,
+  BedrockRequestAuth,
+} from '../../internal/bedrock';
+import { createProvider } from '../../internal/provider';
+import type { Provider, ProviderRequestContext } from '../../internal/provider';
 import type { FinalizedRequestInit } from '../../internal/types';
 
-const BEDROCK_SERVICE = 'bedrock-mantle';
-
+/** AWS credentials used to sign an Amazon Bedrock request with Signature Version 4. */
 export interface AwsCredentialIdentity {
+  /** AWS access-key identifier associated with the signing identity. */
   accessKeyId: string;
+
+  /** Secret access key paired with the AWS access-key identifier. */
   secretAccessKey: string;
+
+  /** Session token required by temporary AWS credentials, when present. */
   sessionToken?: string;
+
+  /** Expiration timestamp supplied by a refreshable temporary-credential provider. */
   expiration?: Date;
 }
 
+/** Resolves current AWS signing credentials before a Bedrock request attempt. */
 export type AwsCredentialsProvider = () => AwsCredentialIdentity | Promise<AwsCredentialIdentity>;
 
+/**
+ * Configures a Bedrock endpoint and exactly one explicit bearer or AWS credential mode.
+ *
+ * When no explicit credential mode is supplied, `AWS_BEARER_TOKEN_BEDROCK` is
+ * preferred, followed by the default AWS credential-provider chain.
+ */
 export interface BedrockProviderOptions extends BedrockEndpointOptions, BedrockBearerOptions {
-  /** Explicit AWS access key ID. Must be paired with secretAccessKey. */
+  /** Explicit AWS access-key identifier; must be paired with `secretAccessKey`. */
   accessKeyId?: string | undefined;
 
-  /** Explicit AWS secret access key. Must be paired with accessKeyId. */
+  /** Explicit AWS secret access key; must be paired with `accessKeyId`. */
   secretAccessKey?: string | undefined;
 
-  /** Optional session token for explicit temporary AWS credentials. */
+  /** Session token for explicit temporary AWS credentials; requires both access-key fields. */
   sessionToken?: string | undefined;
 
-  /** Explicit AWS shared-config profile. */
+  /** AWS shared-config profile; cannot be combined with another explicit credential mode. */
   profile?: string | undefined;
 
-  /** A refreshable provider returning AWS credentials. */
+  /** Refreshable signing-credential provider invoked for each request attempt, including retries. */
   credentialProvider?: AwsCredentialsProvider | undefined;
 }
 
@@ -53,7 +72,9 @@ function validateStaticCredentials(options: BedrockProviderOptions): AwsCredenti
       'The `accessKeyId` and `secretAccessKey` options must be provided together. A `sessionToken` may only be used with both.',
     );
   }
-  if (!hasAccessKey) return undefined;
+  if (!hasAccessKey) {
+    return undefined;
+  }
 
   if (
     typeof options.accessKeyId !== 'string' ||
@@ -80,20 +101,33 @@ function validateStaticCredentials(options: BedrockProviderOptions): AwsCredenti
 }
 
 function requestTarget(parsedURL: URL): { path: string; query: Record<string, string | string[]> } {
-  const query: Record<string, string | string[]> = {};
+  const query: Record<string, string | string[]> = Object.create(null);
   for (const [name, value] of parsedURL.searchParams) {
+    if (name === '__proto__') {
+      throw new Errors.OpenAIError(
+        'The Bedrock SigV4 signer cannot safely sign a `__proto__` query parameter.',
+      );
+    }
+
     const existing = query[name];
-    query[name] =
-      existing === undefined ? value
-      : typeof existing === 'string' ? [existing, value]
-      : [...existing, value];
+    if (existing === undefined) {
+      query[name] = value;
+    } else if (typeof existing === 'string') {
+      query[name] = [existing, value];
+    } else {
+      query[name] = [...existing, value];
+    }
   }
   return { path: parsedURL.pathname, query };
 }
 
 function signableBody(body: BodyInit | null | undefined): string | ArrayBuffer | ArrayBufferView | undefined {
-  if (body === undefined || body === null) return undefined;
-  if (typeof body === 'string' || body instanceof ArrayBuffer || ArrayBuffer.isView(body)) return body;
+  if (body === undefined || body === null) {
+    return undefined;
+  }
+  if (typeof body === 'string' || body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+    return body;
+  }
   throw new Errors.OpenAIError(
     "The SDK's Bedrock SigV4 mode requires a replayable request body. Buffer the body before sending or use bearer authentication.",
   );
@@ -115,22 +149,28 @@ function validateCredentialIdentity(identity: AwsCredentialIdentity): AwsCredent
   return identity;
 }
 
+type BedrockSigV4AuthOptions = {
+  endpoint: BedrockEndpoint;
+  region: string;
+  staticCredentials?: AwsCredentialIdentity | undefined;
+  profile?: string | undefined;
+  credentialProvider?: AwsCredentialsProvider | undefined;
+  usesDefaultChain: boolean;
+};
+
 class BedrockSigV4Auth implements BedrockRequestAuth {
   private signer: SignatureV4 | undefined;
   private resolvedCredentialsProvider: (() => Promise<AwsCredentialIdentity>) | undefined;
+  private readonly options: BedrockSigV4AuthOptions;
 
-  constructor(
-    private readonly options: {
-      region: string;
-      staticCredentials?: AwsCredentialIdentity | undefined;
-      profile?: string | undefined;
-      credentialProvider?: AwsCredentialsProvider | undefined;
-      usesDefaultChain: boolean;
-    },
-  ) {}
+  constructor(options: BedrockSigV4AuthOptions) {
+    this.options = options;
+  }
 
   private credentialsProvider(): () => Promise<AwsCredentialIdentity> {
-    if (this.resolvedCredentialsProvider) return this.resolvedCredentialsProvider;
+    if (this.resolvedCredentialsProvider) {
+      return this.resolvedCredentialsProvider;
+    }
 
     if (this.options.staticCredentials) {
       const credentials = this.options.staticCredentials;
@@ -149,7 +189,7 @@ class BedrockSigV4Auth implements BedrockRequestAuth {
     return (this.signer ??= new SignatureV4({
       credentials: this.credentialsProvider(),
       region: this.options.region,
-      service: BEDROCK_SERVICE,
+      service: this.options.endpoint === 'runtime' ? 'bedrock' : 'bedrock-mantle',
       sha256: Hash.bind(null, 'sha256'),
     }));
   }
@@ -162,10 +202,15 @@ class BedrockSigV4Auth implements BedrockRequestAuth {
     }
 
     const parsedURL = new URL(url);
-    const canonicalRegion = /^bedrock-mantle\.([a-z0-9-]+)\.api\.aws$/i.exec(parsedURL.hostname)?.[1];
-    if (canonicalRegion && canonicalRegion !== this.options.region) {
+    const canonicalEndpoint = parseBedrockEndpointHostname(parsedURL.hostname);
+    if (canonicalEndpoint && canonicalEndpoint.endpoint !== this.options.endpoint) {
       throw new Errors.OpenAIError(
-        `The Bedrock endpoint region \`${canonicalRegion}\` does not match the SigV4 region \`${this.options.region}\`.`,
+        `The Bedrock ${canonicalEndpoint.endpoint} hostname does not match the selected \`${this.options.endpoint}\` endpoint.`,
+      );
+    }
+    if (canonicalEndpoint && canonicalEndpoint.region !== this.options.region) {
+      throw new Errors.OpenAIError(
+        `The Bedrock endpoint region \`${canonicalEndpoint.region}\` does not match the SigV4 region \`${this.options.region}\`.`,
       );
     }
 
@@ -178,6 +223,7 @@ class BedrockSigV4Auth implements BedrockRequestAuth {
 
     const method = (request.method ?? 'GET').toUpperCase();
     const body = signableBody(request.body);
+    const target = requestTarget(parsedURL);
 
     let signed: { headers: Record<string, string> };
     try {
@@ -186,14 +232,13 @@ class BedrockSigV4Auth implements BedrockRequestAuth {
         hostname: parsedURL.hostname,
         ...(parsedURL.port ? { port: Number(parsedURL.port) } : {}),
         method,
-        ...requestTarget(parsedURL),
+        ...target,
         headers: Object.fromEntries(headers.entries()),
-        ...(body !== undefined ? { body } : {}),
+        ...(body === undefined ? {} : { body }),
       });
     } catch (cause) {
-      const message =
-        this.options.usesDefaultChain ?
-          'Could not find credentials for Bedrock. Pass AWS credentials to `bedrock(...)` or configure the default AWS credential chain.'
+      const message = this.options.usesDefaultChain
+        ? 'Could not find credentials for Bedrock. Pass AWS credentials to `bedrock(...)` or configure the default AWS credential chain.'
         : 'Failed to resolve AWS credentials for Bedrock. Verify your AWS profile, environment variables, or runtime identity configuration and try again.';
       throw errorWithCause(message, cause);
     }
@@ -204,7 +249,22 @@ class BedrockSigV4Auth implements BedrockRequestAuth {
   }
 }
 
-/** Configure the standard OpenAI client for Amazon Bedrock using bearer or AWS authentication. */
+/**
+ * Configures the standard OpenAI client for Amazon Bedrock bearer or AWS SigV4 authentication.
+ *
+ * Explicit bearer credentials, static AWS credentials, a shared-config profile,
+ * and a credential provider are mutually exclusive. Without explicit
+ * credentials, `AWS_BEARER_TOKEN_BEDROCK` takes precedence over the default AWS
+ * credential chain. The region defaults to `AWS_REGION` or `AWS_DEFAULT_REGION`.
+ *
+ * This entrypoint requires `@aws-sdk/credential-provider-node`,
+ * `@smithy/hash-node`, and `@smithy/signature-v4`. AWS signing is available in
+ * Node.js-compatible server runtimes and requires replayable request bodies.
+ *
+ * @param options Bedrock endpoint and optional explicit authentication settings.
+ * @returns A provider accepted by `new OpenAI({ provider })`.
+ * @throws {OpenAIError} If endpoint settings or credential modes are invalid or ambiguous.
+ */
 export function bedrock(options: BedrockProviderOptions = {}): Provider {
   const staticCredentials = validateStaticCredentials(options);
   const profile = normalizeOptionalString(options.profile);
@@ -226,12 +286,21 @@ export function bedrock(options: BedrockProviderOptions = {}): Provider {
     );
   }
 
-  const { region, baseURL } = resolveBedrockEndpoint(options);
+  const { endpoint, region, baseURL } = resolveBedrockEndpoint(options);
   if (!bearerAuth.factory && !region) {
     throw new Errors.OpenAIError(
       'Bedrock requires an AWS region. Pass `region` to `bedrock(...)`, or set `AWS_REGION` or `AWS_DEFAULT_REGION`.',
     );
   }
+  if (
+    !bearerAuth.factory &&
+    options.endpoint === undefined &&
+    !parseBedrockEndpointHostname(new URL(baseURL).hostname)
+  ) {
+    throw new Errors.OpenAIError(
+      'A custom Bedrock endpoint requires an explicit `endpoint` option when using AWS credential authentication.',
+    );
+  }
   const credentialProvider = options.credentialProvider;
 
   return createProvider({
@@ -239,6 +308,7 @@ export function bedrock(options: BedrockProviderOptions = {}): Provider {
       const auth =
         bearerAuth.factory?.() ??
         new BedrockSigV4Auth({
+          endpoint,
           region: region!,
           staticCredentials,
           profile,
@@ -248,7 +318,10 @@ export function bedrock(options: BedrockProviderOptions = {}): Provider {
       return {
         name: 'bedrock',
         baseURL,
-        prepareRequest: auth.prepareRequest.bind(auth),
+        async prepareRequest(request, context) {
+          assertBedrockRequestOrigin(baseURL, context.url);
+          await auth.prepareRequest(request, context);
+        },
       };
     },
   });

package/src/providers/bedrock.ts

@@ -2,15 +2,30 @@ import * as Errors from '../error';
 import type { Provider } from '../internal/provider';
 import { createProvider } from '../internal/provider';
 import {
+  assertBedrockRequestOrigin,
   resolveBedrockBearerAuth,
   resolveBedrockEndpoint,
-  type BedrockBearerOptions,
-  type BedrockEndpointOptions,
 } from '../internal/bedrock';
+import type { BedrockBearerOptions, BedrockEndpointOptions } from '../internal/bedrock';
 
+/** Endpoint and bearer-credential settings for the dependency-free Amazon Bedrock provider. */
 export interface BedrockProviderOptions extends BedrockEndpointOptions, BedrockBearerOptions {}
 
-/** Configure the standard OpenAI client for Amazon Bedrock using bearer authentication. */
+/**
+ * Configures the standard OpenAI client for Amazon Bedrock bearer authentication.
+ *
+ * Supply `apiKey` or `tokenProvider`, or set `AWS_BEARER_TOKEN_BEDROCK`.
+ * The endpoint defaults to Mantle; pass `endpoint: 'runtime'` to use Bedrock
+ * Runtime. The region defaults to `AWS_REGION` or `AWS_DEFAULT_REGION`, and a
+ * custom endpoint can be supplied with `baseURL` or `AWS_BEDROCK_BASE_URL`.
+ *
+ * This entrypoint has no AWS SDK dependencies. To use AWS credentials or
+ * Signature Version 4, import `bedrock` from `openai/providers/bedrock/aws`.
+ *
+ * @param options Bedrock endpoint and mutually exclusive bearer-credential settings.
+ * @returns A provider accepted by `new OpenAI({ provider })`.
+ * @throws {OpenAIError} If no usable endpoint or bearer credential is configured.
+ */
 export function bedrock(options: BedrockProviderOptions = {}): Provider {
   const { baseURL } = resolveBedrockEndpoint(options);
   const { factory } = resolveBedrockBearerAuth(options);
@@ -26,7 +41,10 @@ export function bedrock(options: BedrockProviderOptions = {}): Provider {
       return {
         name: 'bedrock',
         baseURL,
-        prepareRequest: auth.prepareRequest.bind(auth),
+        async prepareRequest(request, context) {
+          assertBedrockRequestOrigin(baseURL, context.url);
+          await auth.prepareRequest(request, context);
+        },
       };
     },
   });

package/src/realtime/internal-base.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   RealtimeClientEvent,
   RealtimeServerEvent,
   RealtimeErrorEvent,
@@ -6,9 +6,22 @@ import {
 } from '../resources/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 an active 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.
    */
@@ -19,6 +32,12 @@ export class OpenAIRealtimeError extends OpenAIError {
    */
   event_id?: string | undefined;
 
+  /**
+   * Creates a 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: RealtimeErrorEvent | null) {
     super(message);
 
@@ -27,37 +46,72 @@ export class OpenAIRealtimeError extends OpenAIError {
   }
 }
 
+/** Materializes mapped 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 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 Realtime WebSocket client 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 over the active WebSocket connection.
+   *
+   * Wait until the underlying socket is open before calling this method.
+   * 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: RealtimeErrorEvent, message?: string | undefined): void;
   protected _onError(event: RealtimeErrorEvent | 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(
@@ -79,42 +133,108 @@ 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;
 }
 
+interface RealtimeURLBuilderOptions {
+  /**
+   * Builds the exact WebSocket URL after the connection target has been validated.
+   *
+   * Return only a trusted `wss:` URL because the client's credentials are sent to
+   * that endpoint. Model, call ID, transcription intent, and deployment query
+   * parameters are not added to the returned URL.
+   */
+  buildRealtimeURL?: (
+    client: Pick<OpenAI, 'apiKey' | 'baseURL'>,
+    connection: RealtimeConnectionConfig,
+  ) => URL;
+}
+
+/** Starts a model or transcription session, or attaches to exactly one existing call. */
 export type RealtimeConnectionConfig =
-  | {
+  | (RealtimeURLBuilderOptions & {
       /**
        * Start a new Realtime session using the given model.
        */
       model: string;
+
+      /** Transcription intent; cannot be supplied when starting a model-backed session. */
+      intent?: undefined;
+
+      /** Existing call identifier; cannot be supplied when starting a model-backed session. */
       callID?: undefined;
-    }
-  | {
+    })
+  | (RealtimeURLBuilderOptions & {
+      /** Starts a transcription-only Realtime session without selecting a model. */
+      intent: 'transcription';
+
+      /** Model name; cannot be supplied when starting a transcription-only session. */
       model?: undefined;
+
+      /** Existing call identifier; cannot be supplied with transcription intent. */
+      callID?: undefined;
+    })
+  | (RealtimeURLBuilderOptions & {
+      /** Model name; cannot be supplied when attaching to an existing call. */
+      model?: undefined;
+
+      /** Transcription intent; cannot be supplied when attaching to an existing call. */
+      intent?: undefined;
+
       /**
        * Attach to an in-progress Realtime call over a sideband control connection.
        */
       callID: string;
-    };
+    });
 
+/** Starts an Azure deployment or transcription session, or attaches to an existing call. */
 export type AzureRealtimeConnectionConfig =
-  | {
+  | (RealtimeURLBuilderOptions & {
       /**
        * Override the deployment configured on the Azure client.
        */
       deploymentName?: string;
+
+      /** Transcription intent; cannot be combined with a model deployment. */
+      intent?: undefined;
+
+      /** Existing call identifier; cannot be combined with `deploymentName`. */
       callID?: undefined;
-    }
-  | {
+    })
+  | (RealtimeURLBuilderOptions & {
+      /** Starts an Azure transcription session; set its deployment later in `session.update`. */
+      intent: 'transcription';
+
+      /** Deployment override; cannot be supplied with transcription intent. */
+      deploymentName?: undefined;
+
+      /** Existing call identifier; cannot be supplied with transcription intent. */
+      callID?: undefined;
+    })
+  | (RealtimeURLBuilderOptions & {
+      /** Deployment override; cannot be supplied when attaching to an existing call. */
       deploymentName?: undefined;
+
+      /** Transcription intent; cannot be supplied when attaching to an existing call. */
+      intent?: undefined;
+
       /**
        * Attach to an in-progress Azure Realtime call over a sideband control connection.
        */
       callID: string;
-    };
+    });
 
+/**
+ * Builds the secure WebSocket URL for a model or transcription session, or a sideband call.
+ *
+ * All Azure sessions use the versioned GA Realtime endpoint. Model-backed
+ * sessions select their deployment with `model`, transcription sessions use
+ * `intent`, and sideband connections use `call_id`.
+ *
+ * @throws {Error} If the connection target is invalid or a custom URL does not use `wss:`.
+ */
 export function buildRealtimeURL(
   client: Pick<OpenAI, 'apiKey' | 'baseURL'>,
   connection: string | RealtimeConnectionConfig,
@@ -123,15 +243,31 @@ export function buildRealtimeURL(
     typeof connection === 'string' ? { model: connection } : connection;
   const baseURL = client.baseURL;
   const azure = isAzure(client);
-  const hasModel = !!config.model;
-  const hasCallID = !!config.callID;
+  const hasModel = config.model !== undefined;
+  const hasCallID = config.callID !== undefined;
+  const hasIntent = config.intent !== undefined;
 
-  if (hasModel === hasCallID) {
-    throw new Error('Pass exactly one of `model` or `callID` when opening a Realtime WebSocket.');
+  if (
+    Number(hasModel) + Number(hasCallID) + Number(hasIntent) !== 1 ||
+    (hasModel && !config.model) ||
+    (hasCallID && !config.callID) ||
+    (hasIntent && config.intent !== 'transcription')
+  ) {
+    throw new Error(
+      'Pass exactly one of `model`, `callID`, or transcription `intent` when opening a Realtime WebSocket.',
+    );
+  }
+
+  if (config.buildRealtimeURL) {
+    const url = new URL(config.buildRealtimeURL(client, config));
+    if (url.protocol !== 'wss:') {
+      throw new Error('Custom Realtime WebSocket URLs must use the wss: protocol.');
+    }
+    return url;
   }
 
   let url: URL;
-  if (azure && hasCallID) {
+  if (azure) {
     url = new URL(baseURL);
     const basePath = url.pathname.replace(/\/+/g, '/').replace(/\/+$/, '');
     const versionedPath = basePath.endsWith('/v1') ? basePath : `${basePath}/v1`;
@@ -145,37 +281,51 @@ export function buildRealtimeURL(
 
   url.protocol = 'wss';
   // Sideband control connections attach to an existing call via `call_id`.
-  if (azure) {
-    if (hasCallID) {
-      url.searchParams.set('call_id', config.callID!);
-    } else {
-      url.searchParams.set('api-version', client.apiVersion);
-      url.searchParams.set('deployment', config.model!);
-    }
+  if (hasCallID) {
+    url.searchParams.set('call_id', config.callID!);
+  } else if (hasIntent) {
+    url.searchParams.set('intent', 'transcription');
   } 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;
 }
 
+/**
+ * Resolves an Azure deployment, transcription intent, or an existing Realtime call.
+ *
+ * @throws {Error} If connection targets conflict, intent is invalid, or no deployment is available.
+ */
 export function getAzureRealtimeConnection(
   client: Pick<AzureOpenAI, 'deploymentName'>,
   connection: AzureRealtimeConnectionConfig,
 ): RealtimeConnectionConfig {
-  if (connection.callID !== undefined) {
-    if (connection.deploymentName !== undefined) {
-      throw new Error('Pass either `deploymentName` or `callID`, but not both.');
-    }
-    return { callID: connection.callID };
+  const hasDeploymentName = connection.deploymentName !== undefined;
+  const hasCallID = connection.callID !== undefined;
+  const hasIntent = connection.intent !== undefined;
+  const customURLBuilder = connection.buildRealtimeURL;
+  const normalizedOptions = customURLBuilder ? { buildRealtimeURL: customURLBuilder } : {};
+
+  if (
+    Number(hasDeploymentName) + Number(hasCallID) + Number(hasIntent) > 1 ||
+    (hasIntent && connection.intent !== 'transcription')
+  ) {
+    throw new Error(
+      'Pass exactly one of `deploymentName`, `callID`, or transcription `intent` when opening an Azure Realtime WebSocket.',
+    );
+  }
+
+  if (hasCallID) {
+    return { ...normalizedOptions, callID: connection.callID! };
+  }
+
+  if (hasIntent) {
+    return { ...normalizedOptions, intent: 'transcription' };
   }
 
   const model = connection.deploymentName ?? client.deploymentName;
   if (!model) {
     throw new Error('No deployment name provided');
   }
-  return { model };
+  return { ...normalizedOptions, model };
 }