openai 7.3.0 → 7.5.0

package/realtime/internal-base.d.ts

@@ -1,8 +1,12 @@
-import { RealtimeClientEvent, RealtimeServerEvent, RealtimeErrorEvent, RealtimeError } from "../resources/realtime/realtime.js";
+import type { RealtimeClientEvent, RealtimeServerEvent, RealtimeErrorEvent, RealtimeError } from "../resources/realtime/realtime.js";
 import { EventEmitter } from "../lib/EventEmitter.js";
 import { OpenAIError } from "../error.js";
-import OpenAI, { AzureOpenAI } from "../index.js";
+import type OpenAI from "../index.js";
+import { AzureOpenAI } from "../index.js";
+/** An API-reported or client-side error encountered by an active Realtime connection. */
 export declare class OpenAIRealtimeError extends OpenAIError {
+    /** Stable error name used to identify Realtime connection failures. */
+    name: string;
     /**
      * The error data that the API sent back in an `error` event.
      */
@@ -11,62 +15,145 @@ export declare class OpenAIRealtimeError extends OpenAIError {
      * The unique ID of the server event.
      */
     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);
 }
+/** Materializes mapped Realtime listener properties without changing their public types. */
 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;
 } & {
     [EventType in Exclude<RealtimeServerEvent['type'], 'error'>]: (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 declare 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?: {
+        /** 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;
 }
+/** Reports whether the client is an Azure OpenAI client with Azure-specific Realtime routing. */
 export declare function isAzure(client: Pick<OpenAI, 'apiKey' | 'baseURL'>): client is AzureOpenAI;
-export type RealtimeConnectionConfig = {
+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;
-};
-export type AzureRealtimeConnectionConfig = {
+});
+/** 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 declare function buildRealtimeURL(client: Pick<OpenAI, 'apiKey' | 'baseURL'>, connection: string | RealtimeConnectionConfig): 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 declare function getAzureRealtimeConnection(client: Pick<AzureOpenAI, 'deploymentName'>, connection: AzureRealtimeConnectionConfig): RealtimeConnectionConfig;
 export {};
 //# sourceMappingURL=internal-base.d.ts.map

package/realtime/internal-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-base.d.ts","sourceRoot":"","sources":["../src/realtime/internal-base.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACd,0CAAuC;AACxC,OAAO,EAAE,YAAY,EAAE,+BAA4B;AACnD,OAAO,EAAE,WAAW,EAAE,oBAAiB;AACvC,OAAO,MAAM,EAAE,EAAE,WAAW,EAAE,oBAAiB;AAE/C,qBAAa,mBAAoB,SAAQ,WAAW;IAClD;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI;CAM9D;AAED,KAAK,QAAQ,CAAC,CAAC,IAAI;KAAG,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;CAAE,GAAG,EAAE,CAAC;AAE7D,KAAK,cAAc,GAAG,QAAQ,CAC5B;IACE,KAAK,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC5C,KAAK,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAC7C,GAAG;KACD,SAAS,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,CAC5D,KAAK,EAAE,OAAO,CAAC,mBAAmB,EAAE;QAAE,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,KACrD,OAAO;CACb,CACF,CAAC;AAEF,8BAAsB,qBAAsB,SAAQ,YAAY,CAAC,cAAc,CAAC;IAC9E;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAE/C;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAE9D,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAClE,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAyBlF;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC,GAAG,MAAM,IAAI,WAAW,CAEzF;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,GACD;IACE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN,MAAM,MAAM,6BAA6B,GACrC;IACE;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB,GACD;IACE,cAAc,CAAC,EAAE,SAAS,CAAC;IAC3B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC,EAC1C,UAAU,EAAE,MAAM,GAAG,wBAAwB,GAC5C,GAAG,CA0CL;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,gBAAgB,CAAC,EAC3C,UAAU,EAAE,6BAA6B,GACxC,wBAAwB,CAa1B"}
+{"version":3,"file":"internal-base.d.ts","sourceRoot":"","sources":["../src/realtime/internal-base.ts"],"names":[],"mappings":"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"}

package/realtime/internal-base.js

@@ -7,20 +7,43 @@ exports.getAzureRealtimeConnection = getAzureRealtimeConnection;
 const EventEmitter_1 = require("../lib/EventEmitter.js");
 const error_1 = require("../error.js");
 const index_1 = require("../index.js");
+function safeErrorValue(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return '[unserializable error value]';
+    }
+}
+/** An API-reported or client-side error encountered by an active Realtime connection. */
 class OpenAIRealtimeError extends error_1.OpenAIError {
+    /**
+     * 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, event) {
         super(message);
+        /** Stable error name used to identify Realtime connection failures. */
+        this.name = 'OpenAIRealtimeError';
         this.error = event?.error;
         this.event_id = event?.event_id;
     }
 }
 exports.OpenAIRealtimeError = OpenAIRealtimeError;
+/**
+ * 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.
+ */
 class OpenAIRealtimeEmitter extends EventEmitter_1.EventEmitter {
     _onError(event, message, cause) {
-        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(message +
                 `\n\nTo resolve these unhandled rejection errors you should bind an \`error\` callback, e.g. \`rt.on('error', (error) => ...)\` `, event);
@@ -36,20 +59,41 @@ class OpenAIRealtimeEmitter extends EventEmitter_1.EventEmitter {
     }
 }
 exports.OpenAIRealtimeEmitter = OpenAIRealtimeEmitter;
+/** Reports whether the client is an Azure OpenAI client with Azure-specific Realtime routing. */
 function isAzure(client) {
     return client instanceof index_1.AzureOpenAI;
 }
+/**
+ * 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:`.
+ */
 function buildRealtimeURL(client, connection) {
     const config = typeof connection === 'string' ? { model: connection } : connection;
     const baseURL = client.baseURL;
     const azure = isAzure(client);
-    const hasModel = !!config.model;
-    const hasCallID = !!config.callID;
-    if (hasModel === hasCallID) {
-        throw new Error('Pass exactly one of `model` or `callID` when opening a Realtime WebSocket.');
+    const hasModel = config.model !== undefined;
+    const hasCallID = config.callID !== undefined;
+    const hasIntent = config.intent !== undefined;
+    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;
-    if (azure && hasCallID) {
+    if (azure) {
         url = new URL(baseURL);
         const basePath = url.pathname.replace(/\/+/g, '/').replace(/\/+$/, '');
         const versionedPath = basePath.endsWith('/v1') ? basePath : `${basePath}/v1`;
@@ -63,36 +107,42 @@ function buildRealtimeURL(client, connection) {
     }
     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.
+ */
 function getAzureRealtimeConnection(client, connection) {
-    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 };
 }
 //# sourceMappingURL=internal-base.js.map

package/realtime/internal-base.js.map

@@ -1 +1 @@
-{"version":3,"file":"internal-base.js","sourceRoot":"","sources":["../src/realtime/internal-base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"internal-base.js","sourceRoot":"","sources":["../src/realtime/internal-base.ts"],"names":[],"mappings":"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"}

package/realtime/internal-base.mjs

@@ -1,19 +1,42 @@
 import { EventEmitter } from "../lib/EventEmitter.mjs";
 import { OpenAIError } from "../error.mjs";
 import { AzureOpenAI } from "../index.mjs";
+function safeErrorValue(value) {
+    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 {
+    /**
+     * 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, event) {
         super(message);
+        /** Stable error name used to identify Realtime connection failures. */
+        this.name = 'OpenAIRealtimeError';
         this.error = event?.error;
         this.event_id = event?.event_id;
     }
 }
+/**
+ * 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 class OpenAIRealtimeEmitter extends EventEmitter {
     _onError(event, message, cause) {
-        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(message +
                 `\n\nTo resolve these unhandled rejection errors you should bind an \`error\` callback, e.g. \`rt.on('error', (error) => ...)\` `, event);
@@ -28,20 +51,41 @@ export class OpenAIRealtimeEmitter extends EventEmitter {
         this._emit('error', error);
     }
 }
+/** Reports whether the client is an Azure OpenAI client with Azure-specific Realtime routing. */
 export function isAzure(client) {
     return client instanceof AzureOpenAI;
 }
+/**
+ * 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, connection) {
     const config = typeof connection === 'string' ? { model: connection } : connection;
     const baseURL = client.baseURL;
     const azure = isAzure(client);
-    const hasModel = !!config.model;
-    const hasCallID = !!config.callID;
-    if (hasModel === hasCallID) {
-        throw new Error('Pass exactly one of `model` or `callID` when opening a Realtime WebSocket.');
+    const hasModel = config.model !== undefined;
+    const hasCallID = config.callID !== undefined;
+    const hasIntent = config.intent !== undefined;
+    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;
-    if (azure && hasCallID) {
+    if (azure) {
         url = new URL(baseURL);
         const basePath = url.pathname.replace(/\/+/g, '/').replace(/\/+$/, '');
         const versionedPath = basePath.endsWith('/v1') ? basePath : `${basePath}/v1`;
@@ -55,36 +99,42 @@ export function buildRealtimeURL(client, connection) {
     }
     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, connection) {
-    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 };
 }
 //# sourceMappingURL=internal-base.mjs.map

package/realtime/internal-base.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"internal-base.mjs","sourceRoot":"","sources":["../src/realtime/internal-base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"internal-base.mjs","sourceRoot":"","sources":["../src/realtime/internal-base.ts"],"names":[],"mappings":"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"}

package/realtime/websocket.d.mts

@@ -1,13 +1,41 @@
-import { AzureOpenAI, OpenAI } from "../index.mjs";
+import type { AzureOpenAI } from "../index.mjs";
+import { OpenAI } from "../index.mjs";
 import type { RealtimeClientEvent } from "../resources/realtime/realtime.mjs";
-import { OpenAIRealtimeEmitter, type AzureRealtimeConnectionConfig, type RealtimeConnectionConfig } from "./internal-base.mjs";
-type _WebSocket = typeof globalThis extends ({
+import { OpenAIRealtimeEmitter } from "./internal-base.mjs";
+import type { AzureRealtimeConnectionConfig, RealtimeConnectionConfig } from "./internal-base.mjs";
+/** 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;
-}) ? InstanceType<ws> : any;
+} ? InstanceType<ws> : any;
+/**
+ * Connects to the Realtime API using the runtime's native `WebSocket` implementation.
+ *
+ * Browser use is blocked by default to prevent secret API-key exposure. Use an
+ * ephemeral Realtime credential in browser clients; set
+ * `dangerouslyAllowBrowser` only after independently securing the credential.
+ * Register an SDK `error` listener and wait for `socket`'s `open` event before
+ * sending Realtime client events.
+ */
 export declare class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
+    /** Secure 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 native WebSocket session or attaches to an existing call.
+     *
+     * Clients with function-based credentials must use
+     * {@link OpenAIRealtimeWebSocket.create}; Azure clients should use
+     * {@link OpenAIRealtimeWebSocket.azure}. An ephemeral credential whose value
+     * starts with `ek_` is permitted in browser runtimes automatically.
+     *
+     * @param props Exactly one model, transcription intent, or call ID, plus 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.
@@ -17,15 +45,45 @@ export declare class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
         /** Indicates the token was resolved by the factory just before connecting. @internal */
         __resolvedApiKey?: boolean;
     }, client?: Pick<OpenAI, 'apiKey' | 'baseURL'>);
+    /**
+     * Resolves a client's current API credential before opening a native 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 model, transcription intent, or call ID, plus browser-safety settings.
+     */
     static create(client: Pick<OpenAI, 'apiKey' | 'baseURL' | '_callApiKey'>, props: RealtimeConnectionConfig & {
+        /** Allows browser execution after the caller has secured the supplied credential. */
         dangerouslyAllowBrowser?: boolean;
     }): Promise<OpenAIRealtimeWebSocket>;
+    /**
+     * Opens a native Azure deployment or transcription session, or an existing sideband call.
+     *
+     * Azure credentials are included only in the initial connection URL and are
+     * redacted from the exposed `url` property immediately after connection setup.
+     *
+     * @param client Azure OpenAI client that supplies the endpoint and credential.
+     * @param options Deployment, transcription intent, or call ID, plus browser-safety settings.
+     * @throws {Error} If the Azure credential or required deployment is unavailable.
+     */
     static azure(client: Pick<AzureOpenAI, '_callApiKey' | 'apiVersion' | 'apiKey' | 'baseURL' | 'deploymentName'>, options?: AzureRealtimeConnectionConfig & {
+        /** Allows browser execution after the caller has secured the supplied Azure credential. */
         dangerouslyAllowBrowser?: boolean;
     }): Promise<OpenAIRealtimeWebSocket>;
+    /**
+     * Serializes and sends a Realtime client event after the native WebSocket has opened.
+     * Serialization and transport failures are delivered to the SDK `error` event.
+     */
     send(event: RealtimeClientEvent): void;
+    /**
+     * 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;
 }