@depup/openai 7.34.0-depup.0 → 7.36.0-depup.0

package/src/internal/ws-connection.ts

@@ -0,0 +1,116 @@
+import { OpenAIError } from '../core/error';
+import { ReadyState } from './ws-adapter';
+import type { WebSocketLike } from './ws-adapter';
+import { flattenRawData } from './ws';
+import type { RawWebSocketData, SendQueue } from './ws';
+
+// Read the public socket on each access; callers may replace it through an accessor.
+interface SocketOwner {
+  socket: WebSocketLike;
+}
+type OnError = (message: string, cause?: unknown) => void;
+
+/** Sends or queues an application event using the existing connection state. */
+export function sendWebSocketEvent<T>(
+  owner: SocketOwner,
+  event: T,
+  queue: SendQueue<T>,
+  isReconnecting: () => boolean,
+  onError: OnError,
+): void {
+  if (!owner.socket) {
+    throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.');
+  }
+
+  if (isReconnecting() || owner.socket.readyState === ReadyState.CONNECTING) {
+    if (!queue.enqueue(event)) {
+      onError('send queue is full, message discarded');
+    }
+    return;
+  }
+  if (owner.socket.readyState !== ReadyState.OPEN) {
+    onError('cannot send on a closed WebSocket');
+    return;
+  }
+  try {
+    owner.socket.send(JSON.stringify(event));
+  } catch (error) {
+    onError('could not send data', error);
+  }
+}
+
+/** Sends or snapshots a raw frame using the same admission rules as application events. */
+export function sendRawWebSocketData<T>(
+  owner: SocketOwner,
+  data: RawWebSocketData,
+  queue: SendQueue<T>,
+  isReconnecting: () => boolean,
+  onError: OnError,
+): void {
+  if (!owner.socket) {
+    throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.');
+  }
+
+  if (isReconnecting() || owner.socket.readyState === ReadyState.CONNECTING) {
+    if (!queue.enqueueRaw(data)) {
+      onError('send queue is full, message discarded');
+    }
+    return;
+  }
+  if (owner.socket.readyState !== ReadyState.OPEN) {
+    onError('cannot send on a closed WebSocket');
+    return;
+  }
+  try {
+    owner.socket.send(flattenRawData(data));
+  } catch (error) {
+    onError('could not send data', error);
+  }
+}
+
+/** Flushes queued frames with the caller's existing failed-send policy. */
+export function flushWebSocketSendQueue<T>(
+  owner: SocketOwner,
+  queue: SendQueue<T>,
+  onError: OnError,
+  options?: { requeueFailed?: boolean },
+): void {
+  if (!owner.socket) {
+    throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.');
+  }
+
+  try {
+    queue.flush((data) => owner.socket.send(flattenRawData(data)), options);
+  } catch (error) {
+    onError('could not send queued data', error);
+  }
+}
+
+/** Resolves when the socket opens, or rejects if it errors or closes first. */
+export function waitForWebSocketOpen(socket: WebSocketLike): Promise<void> {
+  // oxlint-disable-next-line promise/avoid-new -- Convert the existing socket event callbacks into the connection attempt's promise.
+  return new Promise<void>((resolve, reject) => {
+    /* oxlint-disable eslint/no-use-before-define -- All mutually dependent callbacks are initialized before socket listeners are registered. */
+    const cleanup = () => {
+      socket.off('open', onOpen);
+      socket.off('error', onError);
+      socket.off('close', onFail);
+    };
+    /* oxlint-enable eslint/no-use-before-define */
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = (error: Error) => {
+      cleanup();
+      reject(error);
+    };
+    const onFail = () => {
+      cleanup();
+      reject(new Error('socket closed before open'));
+    };
+    socket.once('open', onOpen);
+    socket.once('error', onError);
+    socket.once('close', onFail);
+  });
+}

package/src/internal/ws-credentials.ts

@@ -0,0 +1,165 @@
+import { OpenAIError } from '../core/error';
+import type { OpenAI } from '../client';
+import { resolveRealtimeAPIKey } from './realtime-credentials';
+import {
+  buildWebSocketOptions,
+  mergeWebSocketAuthHeaders,
+  snapshotWebSocketCredentials,
+  WEBSOCKET_METADATA_HEADERS,
+} from './ws';
+import type { CredentialedWebSocketOptions } from './ws';
+
+/**
+ * Keep caller credential admission distinct from the hook's final provider-key transform.
+ * The latter reuses captured base headers so no caller getters are reread after the refresh.
+ */
+function buildCredentialedWebSocketOptions<Options extends CredentialedWebSocketOptions>(
+  client: OpenAI,
+  authHeaders: Record<string, string>,
+  options: Options | null | undefined,
+  prepared?: {
+    options: ReturnType<typeof buildWebSocketOptions>;
+    removedHeaders: Set<string>;
+    apiKey?: string | null | undefined;
+  },
+) {
+  if (prepared) {
+    return prepared.apiKey === undefined
+      ? mergeWebSocketAuthHeaders(prepared.options, authHeaders, prepared.removedHeaders)
+      : buildWebSocketOptions(client, authHeaders, prepared.options, prepared.removedHeaders, true);
+  }
+  if (!client._hasApiKeyProvider()) {
+    return buildWebSocketOptions(client, authHeaders, options);
+  }
+  const removedHeaders = new Set<string>();
+  const provided = buildWebSocketOptions(client, {}, options, removedHeaders);
+  return snapshotWebSocketCredentials(provided, WEBSOCKET_METADATA_HEADERS)
+    ? provided
+    : buildWebSocketOptions(client, authHeaders, provided, removedHeaders, true);
+}
+
+/**
+ * Classify reconnect credentials without treating the previous SDK key as a caller override.
+ * Capture routing and caller options before any asynchronous key refresh.
+ */
+function prepareWebSocketReconnect<Options extends CredentialedWebSocketOptions>(
+  client: OpenAI,
+  socketOptions: Options | null | undefined,
+  initialAuthUsedAPIKey: boolean,
+) {
+  const removedHeaders = new Set<string>();
+  const options = buildWebSocketOptions(client, {}, socketOptions, removedHeaders);
+  let authentication: 'provided' | 'cached' | 'refresh';
+  if (snapshotWebSocketCredentials(options, WEBSOCKET_METADATA_HEADERS)) {
+    authentication = 'provided';
+  } else if (
+    removedHeaders.has('authorization') ||
+    options.headers?.['authorization'] !== undefined ||
+    !initialAuthUsedAPIKey
+  ) {
+    authentication = 'cached';
+  } else {
+    authentication = 'refresh';
+  }
+  return { options, removedHeaders, authentication };
+}
+
+/** Per-connection credential snapshots shared by Node WebSocket bindings. */
+export class WebSocketCredentials {
+  private readonly connectionName: string;
+
+  constructor(connectionName: string) {
+    this.connectionName = connectionName;
+  }
+  private initialAuthUsedAPIKey = false;
+  private initialAPIKey: string | undefined;
+  private prepared:
+    | {
+        options: ReturnType<typeof buildWebSocketOptions>;
+        removedHeaders: Set<string>;
+        apiKey?: string | null | undefined;
+      }
+    | undefined;
+
+  get preparedAPIKey(): string | null | undefined {
+    return this.prepared?.apiKey;
+  }
+
+  trackInitialHeaders(client: OpenAI, headers: Record<string, string>, hasSocket: () => boolean): void {
+    if (!hasSocket() && client._hasApiKeyProvider()) {
+      this.initialAPIKey = headers['Authorization']?.slice('Bearer '.length);
+    }
+  }
+
+  usesAPIKey(client: OpenAI, headers: Record<string, string>): boolean {
+    // Hooks can read the SDK key without delegating. Only use an ordinary cached property here:
+    // invoking custom/Bedrock getters could validate credentials a caller-owned socket never sends.
+    const apiKey =
+      this.initialAPIKey ??
+      (client._hasApiKeyProvider() ? Object.getOwnPropertyDescriptor(client, 'apiKey')?.value : undefined);
+    if (!apiKey) {
+      return false;
+    }
+    // Metadata containing a copy of a credential does not make it the socket's authentication.
+    return snapshotWebSocketCredentials(
+      {
+        headers: Object.fromEntries(
+          Object.entries(headers).map(([name, value]) => [name, value?.includes(apiKey) ? value : '']),
+        ),
+      },
+      WEBSOCKET_METADATA_HEADERS,
+    );
+  }
+
+  build<Options extends CredentialedWebSocketOptions>(
+    client: OpenAI,
+    authHeaders: Record<string, string>,
+    options: Options | null | undefined,
+    initialAuthUsedAPIKey?: boolean,
+  ) {
+    if (initialAuthUsedAPIKey !== undefined) {
+      this.initialAuthUsedAPIKey = initialAuthUsedAPIKey;
+      this.initialAPIKey = undefined;
+    }
+    const socketOptions = buildCredentialedWebSocketOptions(client, authHeaders, options, this.prepared);
+    if (
+      client._hasApiKeyProvider() &&
+      !authHeaders['Authorization'] &&
+      !snapshotWebSocketCredentials(socketOptions, WEBSOCKET_METADATA_HEADERS)
+    ) {
+      throw new OpenAIError(
+        `Cannot open a ${this.connectionName} WebSocket with an unresolved function-based apiKey. Resolve it before constructing the WebSocket or provide explicit WebSocket credentials.`,
+      );
+    }
+    return socketOptions;
+  }
+
+  async prepare<Socket, Options extends CredentialedWebSocketOptions>(
+    client: OpenAI,
+    socketOptions: Options | null | undefined,
+    authHeaders: (apiKey?: string | null) => Record<string, string>,
+    createSocket: (url: URL, headers: Record<string, string>) => Socket,
+  ): Promise<(url: URL) => Socket> {
+    const { options, removedHeaders, authentication } = prepareWebSocketReconnect(
+      client,
+      socketOptions,
+      this.initialAuthUsedAPIKey,
+    );
+    const createPreparedSocket = (url: URL, headers: Record<string, string>, apiKey?: string | null) => {
+      const previous = this.prepared;
+      this.prepared = { options, removedHeaders, apiKey };
+      try {
+        // Resolve headers inside the scope so legacy zero-argument overrides see this attempt's key.
+        return createSocket(url, apiKey === undefined ? headers : authHeaders(apiKey));
+      } finally {
+        this.prepared = previous;
+      }
+    };
+    if (authentication !== 'refresh') {
+      const headers = authentication === 'provided' ? {} : authHeaders();
+      return (url) => createPreparedSocket(url, headers);
+    }
+    const { commit } = await resolveRealtimeAPIKey(client, true);
+    return (url) => createPreparedSocket(url, {}, commit());
+  }
+}

package/src/lib/live/webrtc.ts

@@ -1,6 +1,6 @@
 /* oxlint-disable max-classes-per-file -- Both thin facades belong to the same public Live WebRTC entrypoint. */
 import type {
-  ConnectClientEvent as ClientEvent,
+  ConnectClientEvent,
   ConnectServerEvent as ServerEvent,
 } from '../../resources/live/sideband/sideband';
 import { WebRTCConnection } from '../webrtc/connection';
@@ -16,6 +16,9 @@ export type {
   WebRTCState,
 } from '../webrtc/types';
 
+/** Fixture playback requires a primary WebSocket or server sideband. */
+type ClientEvent = Exclude<ConnectClientEvent, { type: 'session.output_audio.fixture.play' }>;
+
 /** Browser Live connection with application-owned SDP exchange and typed server-event subscriptions. */
 export class OpenAILiveWebRTC extends WebRTCConnection<ClientEvent, ServerEvent> {}
 

package/src/resources/admin/organization/projects/api-keys.ts

@@ -153,8 +153,20 @@ export class APIKeys extends APIResource {
   }
 
   /**
-   * Updates the expiration of an existing API key in the project, including a
-   * service-account-owned key. Requires permission to write project API keys.
+   * Updates the scopes and/or expiration of an existing API key in the project,
+   * including a service-account-owned key. Requires permission to write project API
+   * keys.
+   *
+   * Provide at least one of `scopes` or `expires_in_seconds`. Omitted fields stay
+   * unchanged; neither field accepts `null`. Both changes are saved together.
+   *
+   * `scopes` replaces the key's scope restrictions using the same scope identifiers
+   * as the dashboard. An empty array means All permissions, subject to the owner's
+   * effective access; it does not mean no access. Use `["api.all.read"]` for
+   * read-only access or specific scopes such as `["api.files.read"]` for restricted
+   * access. This does not change user or service-account roles or grant admin
+   * permissions. Scope changes follow the same authentication-cache propagation as
+   * dashboard edits.
    *
    * Provide `expires_in_seconds` to set the expiration relative to this request. The
    * value must satisfy the organization's and project's expiry policies. Expired
@@ -166,7 +178,10 @@ export class APIKeys extends APIResource {
    * const projectAPIKey =
    *   await client.admin.organization.projects.apiKeys.update(
    *     'api_key_id',
-   *     { project_id: 'project_id', expires_in_seconds: 1 },
+   *     {
+   *       project_id: 'project_id',
+   *       scopes: ['api.all.read'],
+   *     },
    *   );
    * ```
    */
@@ -486,9 +501,18 @@ export interface APIKeyUpdateParams {
   /**
    * Body param: Number of seconds from this request until the API key expires. Must
    * comply with the organization and project expiry policies. Expired keys cannot be
-   * updated. Retrying resets the expiry relative to the new request.
+   * updated. Retrying resets the expiry relative to the new request. Omit to keep
+   * the current expiration.
+   */
+  expires_in_seconds?: number;
+
+  /**
+   * Body param: Replace the API key scope restrictions. Omit to leave scopes
+   * unchanged. An empty array removes key restrictions (All permissions), subject to
+   * the owner's effective permissions. Use ["api.all.read"] for read-only access.
+   * Scopes do not change the owner's roles or grant administrative permissions.
    */
-  expires_in_seconds: number;
+  scopes?: Array<string>;
 }
 
 export interface APIKeyListParams extends ConversationCursorPageParams {

package/src/resources/audio/speech.ts

@@ -69,7 +69,8 @@ export interface SpeechCreateParams {
    * object with an `id`, for example `{ "id": "voice_1234" }`. Previews of the
    * voices are available in the
    * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-   * Custom voices must be created from audio samples.
+   * Custom voices must be created from audio samples. Voices created from text
+   * prompts are supported only in Live.
    */
   voice:
     | string

package/src/resources/audio/voices.ts

@@ -18,17 +18,17 @@ function resolveResourceRequestOptions(
  */
 export class Voices extends APIResource {
   /**
-   * Create a custom voice you can use for audio output (for example, in
-   * Text-to-Speech and the Realtime API). This requires an audio sample and a
-   * previously uploaded consent recording.
+   * Creates a voice from a text prompt or from a consent recording and an audio
+   * sample.
    *
-   * Send `name`, `audio_sample`, and the `consent` recording ID as multipart form
-   * data. The optional `type` defaults to `audio_sample`.
+   * For prompt-based creation, send `type: "prompt"` with a `name` and `prompt` as
+   * JSON or multipart form data. For creation from an audio sample, send
+   * `type: "audio_sample"` with a `name`, `audio_sample`, and `consent` recording ID
+   * as multipart form data. The type defaults to `audio_sample` when omitted.
    *
-   * Returns the saved voice's metadata. See the
-   * [custom voices guide](https://developers.openai.com/api/docs/guides/text-to-speech#custom-voices)
-   * for requirements and best practices. Custom voices are limited to eligible
-   * customers.
+   * Returns the saved voice's metadata. Voices created from text prompts are
+   * supported only in Live, not in Realtime or the speech endpoint. The response
+   * does not include preview audio.
    *
    * @example
    * ```ts
@@ -50,7 +50,8 @@ export class Voices extends APIResource {
 }
 
 /**
- * A custom voice that can be used for audio output.
+ * A custom voice that can be used for audio output. Voices created from text
+ * prompts are supported only in Live.
  */
 export interface Voice {
   /**
@@ -76,10 +77,17 @@ export interface Voice {
   /**
    * How the voice was created.
    */
-  type: 'audio_sample';
+  type: 'audio_sample' | 'prompt';
+
+  /**
+   * The original text prompt used to create the voice. Present for prompt-generated
+   * voices with a stored prompt; omitted for audio-sample voices and older voices
+   * without a stored prompt.
+   */
+  prompt?: string;
 }
 
-export type VoiceCreateParams = VoiceCreateParams.Consent;
+export type VoiceCreateParams = VoiceCreateParams.Consent | VoiceCreateParams.Prompt;
 
 export declare namespace VoiceCreateParams {
   /**
@@ -110,6 +118,39 @@ export declare namespace VoiceCreateParams {
      */
     type?: 'audio_sample';
   }
+
+  /**
+   * Creates a synthetic voice from a text description. Supports application/json or
+   * multipart/form-data.
+   */
+  export interface Prompt {
+    /**
+     * The name of the new voice.
+     */
+    name: string;
+
+    /**
+     * A description of the desired voice. Must not contain only whitespace.
+     */
+    prompt: string;
+
+    /**
+     * Set to `prompt` to create a voice from a text description.
+     */
+    type: 'prompt';
+
+    /**
+     * The voice creation model to use. Defaults to `auto`.
+     */
+    model?: string | 'auto' | '2026-10-08';
+
+    /**
+     * Optional text for the voice to speak during creation. If omitted, a script is
+     * generated from the prompt. Must not be blank after trimming whitespace; scripts
+     * that are too short are rejected.
+     */
+    script_hint?: string;
+  }
 }
 
 export declare namespace Voices {

package/src/resources/beta/realtime/realtime.ts

@@ -1173,6 +1173,11 @@ export namespace RealtimeResponseStatus {
      */
     code?: string;
 
+    /**
+     * A human-readable error message.
+     */
+    message?: string;
+
     /**
      * The type of error.
      */

package/src/resources/beta/responses/responses.ts

@@ -3706,6 +3706,16 @@ export interface BetaResponseError {
   message: string;
 
   misalignment?: BetaResponseError.Misalignment;
+
+  /**
+   * The request parameter associated with the error, or null if none was recorded.
+   */
+  param?: string | null;
+
+  /**
+   * The original error type, or null if it was not recorded.
+   */
+  type?: string | null;
 }
 
 export namespace BetaResponseError {