openai 6.34.0 → 6.35.0

package/src/internal/ws-adapter-node.ts

@@ -0,0 +1,105 @@
+import type * as WS from 'ws';
+import type { WebSocketLike } from './ws-adapter';
+
+/** A generic event listener callback. */
+type Listener = (...args: any[]) => void;
+
+export class NodeWebSocket implements WebSocketLike {
+  private _ws: WS.WebSocket;
+
+  /** Maps `(event, originalListener)` -> wrapped listener for correct `off()` removal. */
+  private _listenerMap = new Map<string, Map<Listener, Listener>>();
+
+  constructor(ws: WS.WebSocket) {
+    this._ws = ws;
+  }
+
+  /** The underlying platform-specific socket. Code that accesses this will not be isomorphic across server and browser environments. */
+  get platformSocket(): WS.WebSocket {
+    return this._ws;
+  }
+
+  get readyState(): number {
+    return this._ws.readyState;
+  }
+
+  send(data: string | ArrayBufferLike | ArrayBufferView): void {
+    this._ws.send(data);
+  }
+
+  close(code?: number, reason?: string): void {
+    this._ws.close(code, reason);
+  }
+
+  on(event: string, listener: Listener): void {
+    const wrapped = this._wrapListener(event, listener);
+    this._listenersFor(event).set(listener, wrapped);
+    this._ws.on(event, wrapped);
+  }
+
+  off(event: string, listener: Listener): void {
+    const byListener = this._listenerMap.get(event);
+    if (!byListener) return;
+    const wrapped = byListener.get(listener);
+    if (wrapped) {
+      byListener.delete(listener);
+      this._ws.removeListener(event, wrapped);
+    }
+  }
+
+  once(event: string, listener: Listener): void {
+    const onceListener: Listener = (...args) => {
+      this.off(event, listener);
+      listener(...args);
+    };
+    const wrapped = this._wrapListener(event, onceListener);
+    this._listenersFor(event).set(listener, wrapped);
+    this._ws.on(event, wrapped);
+  }
+
+  private _listenersFor(event: string): Map<Listener, Listener> {
+    let map = this._listenerMap.get(event);
+    if (!map) {
+      map = new Map();
+      this._listenerMap.set(event, map);
+    }
+    return map;
+  }
+
+  /**
+   * Normalizes `ws` message payloads: text frames become strings,
+   * binary frames stay as `Buffer`, and fragmented frames are merged.
+   */
+  private static _normalizeMessageData(
+    data: Buffer | ArrayBuffer | Buffer[],
+    isBinary: boolean,
+  ): string | Buffer {
+    if (!isBinary) {
+      if (Array.isArray(data)) return Buffer.concat(data).toString();
+      if (data instanceof ArrayBuffer) return Buffer.from(data).toString();
+      return data.toString();
+    }
+
+    if (Array.isArray(data)) return Buffer.concat(data);
+    if (data instanceof ArrayBuffer) return Buffer.from(data);
+    return data;
+  }
+
+  private _wrapListener(event: string, listener: Listener): Listener {
+    switch (event) {
+      case 'message':
+        return (data: Buffer | ArrayBuffer | Buffer[], isBinary: boolean) => {
+          listener(NodeWebSocket._normalizeMessageData(data, isBinary), isBinary);
+        };
+
+      case 'close':
+        return (code: number, reason: Buffer) => {
+          listener(code, reason.toString());
+        };
+
+      // 'open' and 'error' pass through unchanged
+      default:
+        return listener;
+    }
+  }
+}

package/src/internal/ws-adapter.ts

@@ -0,0 +1,30 @@
+/**
+ * Normalized WebSocket interface that abstracts over the `ws` package (Node.js)
+ * and the native WebSocket API (browser).
+ */
+export interface WebSocketLike {
+  readonly readyState: number;
+
+  send(data: string | ArrayBufferLike | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+
+  on(event: 'open', listener: () => void): void;
+  on(
+    event: 'message',
+    listener: (data: string | ArrayBuffer | ArrayBufferView, isBinary: boolean) => void,
+  ): void;
+  on(event: 'close', listener: (code: number, reason: string) => void): void;
+  on(event: 'error', listener: (err: Error) => void): void;
+  on(event: string, listener: (...args: any[]) => void): void;
+
+  off(event: string, listener: (...args: any[]) => void): void;
+  once(event: string, listener: (...args: any[]) => void): void;
+}
+
+/** Standard WebSocket readyState values (RFC 6455). */
+export const ReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const;

package/src/internal/ws.ts

@@ -0,0 +1,193 @@
+import { concatBytes, encodeUTF8 } from './utils/bytes';
+
+/** Reconnection event passed to the `onReconnecting` handler and event listeners. */
+export interface ReconnectingEvent<Parameters = Record<string, unknown>> {
+  /** Which retry attempt this is (1-based). */
+  readonly attempt: number;
+  /** Total attempts that will be made. */
+  readonly maxAttempts: number;
+  /** Delay in ms before this attempt connects. */
+  readonly delay: number;
+  /** The WebSocket close code that triggered reconnection. */
+  readonly closeCode: number;
+  /** The current query parameters. */
+  readonly parameters: (Parameters & Record<string, unknown>) | undefined;
+}
+
+/**
+ * Optional overrides returned from the `onReconnecting` handler
+ * to customize the next reconnection attempt.
+ */
+export type ReconnectingOverrides<Parameters = Record<string, unknown>> =
+  | {
+      /**
+       * If provided, assigns the query parameters for the next connection.
+       * Set to `undefined` to clear all query parameters.
+       */
+      parameters?: (Parameters & Record<string, unknown>) | undefined;
+    }
+  | {
+      /**
+       * If set, will stop attempting to reconnect.
+       */
+      abort: true;
+    };
+
+/**
+ * Raw data types that can be sent over a WebSocket without serialization.
+ */
+export type RawWebSocketData = string | ArrayBufferLike | ArrayBufferView | ArrayBufferView[];
+
+export type UnsentMessage<T> = { type: 'message'; message: T } | { type: 'raw'; data: RawWebSocketData };
+
+type QueueEntry =
+  | { kind: 'json'; data: string; byteLength: number }
+  | { kind: 'raw'; data: RawWebSocketData; byteLength: number };
+
+function toUint8Array(view: ArrayBufferView): Uint8Array {
+  if (view instanceof Uint8Array) return view;
+  return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+}
+
+/**
+ * Flatten `ArrayBufferView[]` fragments into a single `Uint8Array` so that
+ * `ws.send()` transmits the correct bytes.
+ */
+export function flattenRawData(data: RawWebSocketData): Exclude<RawWebSocketData, ArrayBufferView[]> {
+  if (Array.isArray(data)) return concatBytes(data.map(toUint8Array));
+  return data;
+}
+
+function snapshotRawData(data: RawWebSocketData): Exclude<RawWebSocketData, ArrayBufferView[]> {
+  if (typeof data === 'string') return data;
+  if (Array.isArray(data)) return concatBytes(data.map(toUint8Array));
+  if (ArrayBuffer.isView(data)) {
+    const copy = new Uint8Array(data.byteLength);
+    copy.set(toUint8Array(data));
+    return copy;
+  }
+  return data.slice(0);
+}
+
+function rawByteLength(data: RawWebSocketData): number {
+  if (typeof data === 'string') return encodeUTF8(data).byteLength;
+  if (Array.isArray(data)) return data.reduce((sum, buf) => sum + buf.byteLength, 0);
+  if ('byteLength' in data) return data.byteLength;
+  return 0;
+}
+
+/**
+ * A bounded queue for outgoing WebSocket messages. JSON messages are
+ * serialized on enqueue; raw messages are stored as-is. The queue enforces
+ * a configurable byte-size limit and can return the original messages via
+ * {@link drain} when the connection permanently closes.
+ */
+export class SendQueue<T = unknown> {
+  private _queue: QueueEntry[] = [];
+  private _bytes: number = 0;
+  private _maxBytes: number;
+
+  constructor(maxBytes: number = 1_048_576) {
+    this._maxBytes = maxBytes;
+  }
+
+  /**
+   * Serialize and enqueue a JSON message. Returns `true` if the message was
+   * accepted, `false` if it would exceed the byte-size limit.
+   */
+  enqueue(event: T): boolean {
+    const data = JSON.stringify(event);
+    const byteLength = encodeUTF8(data).byteLength;
+    if (this._bytes + byteLength > this._maxBytes && this._queue.length > 0) {
+      return false;
+    }
+    this._queue.push({ kind: 'json', data, byteLength });
+    this._bytes += byteLength;
+    return true;
+  }
+
+  /**
+   * Enqueue raw data without serialization. Returns `true` if the data was
+   * accepted, `false` if it would exceed the byte-size limit.
+   */
+  enqueueRaw(data: RawWebSocketData): boolean {
+    const snapshot = snapshotRawData(data);
+    const byteLength = rawByteLength(snapshot);
+    if (this._bytes + byteLength > this._maxBytes && this._queue.length > 0) {
+      return false;
+    }
+    this._queue.push({ kind: 'raw', data: snapshot, byteLength });
+    this._bytes += byteLength;
+    return true;
+  }
+
+  /**
+   * Send every queued message via `send`. If `send` throws, the failing
+   * message and all subsequent messages are re-queued and the error is
+   * re-thrown so the caller can report it.
+   */
+  flush(send: (data: RawWebSocketData) => void): void {
+    const pending = this._queue.splice(0);
+    this._bytes = 0;
+    for (let i = 0; i < pending.length; i++) {
+      try {
+        send(pending[i]!.data);
+      } catch (err) {
+        const remaining = pending.slice(i);
+        this._queue = remaining.concat(this._queue);
+        this._bytes = this._queue.reduce((sum, item) => sum + item.byteLength, 0);
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Drain the queue and return the unsent messages. JSON messages are
+   * deserialized back to their original form. Resets byte tracking to zero.
+   */
+  drain(): UnsentMessage<T>[] {
+    const unsent = this._queue.map((entry): UnsentMessage<T> => {
+      if (entry.kind === 'raw') return { type: 'raw', data: entry.data };
+      return { type: 'message', message: JSON.parse(entry.data) as T };
+    });
+    this._queue = [];
+    this._bytes = 0;
+    return unsent;
+  }
+}
+
+// RFC 6455 §7.4.1
+export function isRecoverableClose(code: number): boolean {
+  switch (code) {
+    case 1000:
+      return false; // Normal closure
+    case 1001:
+      return true; // Going away (server shutting down)
+    case 1002:
+      return false; // Protocol error
+    case 1003:
+      return false; // Unsupported data
+    case 1005:
+      return true; // No status code (abnormal)
+    case 1006:
+      return true; // Abnormal closure (network drop)
+    case 1007:
+      return false; // Invalid payload
+    case 1008:
+      return false; // Policy violation
+    case 1009:
+      return false; // Message too big
+    case 1010:
+      return false; // Missing extension
+    case 1011:
+      return true; // Internal server error
+    case 1012:
+      return true; // Service restart
+    case 1013:
+      return true; // Try again later
+    case 1015:
+      return true; // TLS handshake failure
+    default:
+      return false;
+  }
+}

package/src/resources/audio/speech.ts

@@ -18,8 +18,8 @@ export class Speech extends APIResource {
    * ```ts
    * const speech = await client.audio.speech.create({
    *   input: 'input',
-   *   model: 'string',
-   *   voice: 'string',
+   *   model: 'tts-1',
+   *   voice: 'alloy',
    * });
    *
    * const content = await speech.blob();

package/src/resources/chat/completions/completions.ts

@@ -1665,7 +1665,7 @@ export interface ChatCompletionCreateParamsBase {
    * of 24 hours.
    * [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).
    */
-  prompt_cache_retention?: 'in-memory' | '24h' | null;
+  prompt_cache_retention?: 'in_memory' | '24h' | null;
 
   /**
    * Constrains effort on reasoning for

package/src/resources/completions.ts

@@ -20,7 +20,7 @@ export class Completions extends APIResource {
    * @example
    * ```ts
    * const completion = await client.completions.create({
-   *   model: 'string',
+   *   model: 'gpt-3.5-turbo-instruct',
    *   prompt: 'This is a test.',
    * });
    * ```

package/src/resources/responses/index.ts

@@ -3,3 +3,5 @@
 export { InputItems, type ResponseItemList, type InputItemListParams } from './input-items';
 export { InputTokens, type InputTokenCountResponse, type InputTokenCountParams } from './input-tokens';
 export { Responses } from './responses';
+export { type ResponsesWSClientOptions } from './ws';
+export { type ResponsesWSReconnectOptions } from './ws-base';

package/src/resources/responses/internal-base.ts

@@ -4,11 +4,21 @@ import * as ResponsesAPI from './responses';
 import { OpenAI } from '../../client';
 import { EventEmitter } from '../../core/EventEmitter';
 import { OpenAIError } from '../../core/error';
-import { stringifyQuery } from '../../internal/utils';
+
+import type { RawWebSocketData, ReconnectingEvent, UnsentMessage } from '../../internal/ws';
 
 export type ResponsesStreamMessage =
-  | { type: 'connecting' | 'open' | 'closing' | 'close' }
+  | { type: 'connecting' | 'open' | 'closing' }
+  | {
+      type: 'close';
+      code: number;
+      reason: string;
+      unsent: UnsentMessage<ResponsesAPI.ResponsesClientEvent>[];
+    }
+  | { type: 'reconnecting'; reconnect: ReconnectingEvent }
+  | { type: 'reconnected' }
   | { type: 'message'; message: ResponsesAPI.ResponsesServerEvent }
+  | { type: 'raw'; data: RawWebSocketData }
   | { type: 'error'; error: WebSocketError };
 
 export class WebSocketError extends OpenAIError {
@@ -29,7 +39,11 @@ type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
 type WebSocketEvents = Simplify<
   {
     event: (event: ResponsesAPI.ResponsesServerEvent) => void;
+    raw: (data: RawWebSocketData) => void;
     error: (error: WebSocketError) => void;
+    close: (code: number, reason: string, unsent: UnsentMessage<ResponsesAPI.ResponsesClientEvent>[]) => void;
+    reconnecting: (event: ReconnectingEvent) => void;
+    reconnected: () => void;
   } & {
     [EventType in Exclude<NonNullable<ResponsesAPI.ResponsesServerEvent['type']>, 'error'>]: (
       event: Extract<ResponsesAPI.ResponsesServerEvent, { type?: EventType }>,
@@ -43,6 +57,11 @@ export abstract class ResponsesEmitter extends EventEmitter<WebSocketEvents> {
    */
   abstract send(event: ResponsesAPI.ResponsesClientEvent): void;
 
+  /**
+   * Send raw data over the WebSocket without JSON serialization.
+   */
+  abstract sendRaw(data: RawWebSocketData): void;
+
   /**
    * Close the WebSocket connection.
    */
@@ -77,14 +96,11 @@ export abstract class ResponsesEmitter extends EventEmitter<WebSocketEvents> {
   }
 }
 
-export function buildURL(client: OpenAI, query?: object | null): URL {
-  const path = '/responses';
-  const baseURL = client.baseURL;
-  const url = new URL(baseURL + (baseURL.endsWith('/') ? path.slice(1) : path));
-  if (query) {
-    url.search = stringifyQuery(query);
-  }
-  url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:';
+export function buildURL(client: OpenAI, parameters: Record<string, unknown>): URL {
+  const { ...query } = parameters;
+  const endpoint = '/responses';
+  const url = new URL(client.buildURL(endpoint, query, undefined));
+  url.protocol = url.protocol === 'http:' || url.protocol === 'ws:' ? 'ws:' : 'wss:';
   return url;
 }
 

package/src/resources/responses/responses.ts

@@ -1120,7 +1120,7 @@ export interface Response {
    * of 24 hours.
    * [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).
    */
-  prompt_cache_retention?: 'in-memory' | '24h' | null;
+  prompt_cache_retention?: 'in_memory' | '24h' | null;
 
   /**
    * **gpt-5 and o-series models only**
@@ -3423,6 +3423,13 @@ export interface ResponseInputFile {
    */
   type: 'input_file';
 
+  /**
+   * The detail level of the file to be sent to the model. Use `low` for the default
+   * rendering behavior, or `high` to render the file at higher quality. Defaults to
+   * `low`.
+   */
+  detail?: 'low' | 'high';
+
   /**
    * The content of the file to be sent to the model.
    */
@@ -3453,6 +3460,13 @@ export interface ResponseInputFileContent {
    */
   type: 'input_file';
 
+  /**
+   * The detail level of the file to be sent to the model. Use `low` for the default
+   * rendering behavior, or `high` to render the file at higher quality. Defaults to
+   * `low`.
+   */
+  detail?: 'low' | 'high';
+
   /**
    * The base64-encoded data of the file to be sent to the model.
    */
@@ -6551,7 +6565,7 @@ export interface ResponsesClientEvent {
    * of 24 hours.
    * [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).
    */
-  prompt_cache_retention?: 'in-memory' | '24h' | null;
+  prompt_cache_retention?: 'in_memory' | '24h' | null;
 
   /**
    * **gpt-5 and o-series models only**
@@ -7571,7 +7585,7 @@ export interface ResponseCreateParamsBase {
    * of 24 hours.
    * [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).
    */
-  prompt_cache_retention?: 'in-memory' | '24h' | null;
+  prompt_cache_retention?: 'in_memory' | '24h' | null;
 
   /**
    * **gpt-5 and o-series models only**
@@ -7965,6 +7979,11 @@ export interface ResponseCompactParams {
    * A key to use when reading from or writing to the prompt cache.
    */
   prompt_cache_key?: string | null;
+
+  /**
+   * How long to retain a prompt cache entry created by this request.
+   */
+  prompt_cache_retention?: 'in_memory' | '24h' | null;
 }
 
 Responses.InputItems = InputItems;