openai 7.3.0 → 7.5.0

package/src/internal/utils/path.ts

@@ -1,7 +1,10 @@
 import { OpenAIError } from '../../core/error';
 
 /**
- * Percent-encode everything that isn't safe to have in a path without encoding safe chars.
+ * Percent-encodes a single URI path parameter while preserving RFC 3986 path characters.
+ *
+ * Slash, question-mark, and hash characters are encoded so an interpolated value
+ * cannot create another path segment, query string, or fragment.
  *
  * Taken from https://datatracker.ietf.org/doc/html/rfc3986#section-3.3:
  * > unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
@@ -14,39 +17,52 @@ export function encodeURIPath(str: string) {
 
 const EMPTY = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null));
 
+/**
+ * Creates a template tag that safely interpolates SDK resource paths.
+ *
+ * Path values use the supplied encoder; values after a literal `?` or `#` use
+ * `encodeURIComponent`. Nullish values, ordinary objects, and literal or
+ * percent-encoded `.`/`..` path segments are rejected with an SDK error.
+ */
 export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
   function path(statics: readonly string[], ...params: readonly unknown[]): string {
     // If there are no params, no processing is needed.
-    if (statics.length === 1) return statics[0]!;
+    if (statics.length === 1) {
+      return statics[0]!;
+    }
 
     let postPath = false;
     const invalidSegments = [];
-    const path = statics.reduce((previousValue, currentValue, index) => {
-      if (/[?#]/.test(currentValue)) {
-        postPath = true;
+    let path = '';
+    for (let index = 0; index < statics.length; index += 1) {
+      if (index in statics) {
+        const currentValue = statics[index]!;
+        if (/[?#]/.test(currentValue)) {
+          postPath = true;
+        }
+        const value = params[index];
+        let encoded = (postPath ? encodeURIComponent : pathEncoder)('' + value);
+        if (
+          index !== params.length &&
+          (value == null ||
+            (typeof value === 'object' &&
+              // handle values from other realms
+              value.toString ===
+                Object.getPrototypeOf(Object.getPrototypeOf((value as any).hasOwnProperty ?? EMPTY) ?? EMPTY)
+                  ?.toString))
+        ) {
+          encoded = value + '';
+          invalidSegments.push({
+            start: path.length + currentValue.length,
+            length: encoded.length,
+            error: `Value of type ${Object.prototype.toString
+              .call(value)
+              .slice(8, -1)} is not a valid path parameter`,
+          });
+        }
+        path += currentValue + (index === params.length ? '' : encoded);
       }
-      const value = params[index];
-      let encoded = (postPath ? encodeURIComponent : pathEncoder)('' + value);
-      if (
-        index !== params.length &&
-        (value == null ||
-          (typeof value === 'object' &&
-            // handle values from other realms
-            value.toString ===
-              Object.getPrototypeOf(Object.getPrototypeOf((value as any).hasOwnProperty ?? EMPTY) ?? EMPTY)
-                ?.toString))
-      ) {
-        encoded = value + '';
-        invalidSegments.push({
-          start: previousValue.length + currentValue.length,
-          length: encoded.length,
-          error: `Value of type ${Object.prototype.toString
-            .call(value)
-            .slice(8, -1)} is not a valid path parameter`,
-        });
-      }
-      return previousValue + currentValue + (index === params.length ? '' : encoded);
-    }, '');
+    }
 
     const pathOnly = path.split(/[?#]/, 1)[0]!;
     const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
@@ -57,7 +73,7 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
       invalidSegments.push({
         start: match.index,
         length: match[0].length,
-        error: `Value "${match[0]}" can\'t be safely passed as a path parameter`,
+        error: `Value "${match[0]}" can't be safely passed as a path parameter`,
       });
     }
 
@@ -65,12 +81,13 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
 
     if (invalidSegments.length > 0) {
       let lastEnd = 0;
-      const underline = invalidSegments.reduce((acc, segment) => {
+      let underline = '';
+      for (const segment of invalidSegments) {
         const spaces = ' '.repeat(segment.start - lastEnd);
         const arrows = '^'.repeat(segment.length);
         lastEnd = segment.start + segment.length;
-        return acc + spaces + arrows;
-      }, '');
+        underline += spaces + arrows;
+      }
 
       throw new OpenAIError(
         `Path parameters result in path with invalid segments:\n${invalidSegments
@@ -83,6 +100,8 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
   };
 
 /**
- * URI-encodes path params and ensures no unsafe /./ or /../ path segments are introduced.
+ * Template tag that encodes resource-path parameters and rejects traversal segments.
+ *
+ * Values inside query strings and fragments are encoded as URI components.
  */
 export const path = /* @__PURE__ */ createPathTagFunction(encodeURIPath);

package/src/internal/utils/query.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import * as qs from '../qs/stringify';
 
 export function stringifyQuery(query: object | Record<string, unknown>) {

package/src/internal/utils/sleep.ts

@@ -1,3 +1 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

package/src/internal/utils/uuid.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 /**
  * https://stackoverflow.com/a/2117523
  */

package/src/internal/utils/values.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 import { OpenAIError } from '../../core/error';
 
 // https://url.spec.whatwg.org/#url-scheme-string

package/src/internal/utils.ts

@@ -1,5 +1,3 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
 export * from './utils/values';
 export * from './utils/base64';
 export * from './utils/env';

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

@@ -6,13 +6,24 @@ type Listener = (...args: any[]) => void;
 /** A DOM-style event handler passed to addEventListener/removeEventListener. */
 type DOMEventHandler = (ev: any) => void;
 
-// Minimal browser API type declarations.
-declare class WebSocket {
+/** Minimal browser WebSocket surface accepted by the platform-neutral adapter. */
+interface WebSocket {
+  /** Numeric connection state reported by the browser WebSocket. */
   readonly readyState: number;
+
+  /** Representation used for received binary message frames. */
   binaryType: string;
+
+  /** Sends a text or binary WebSocket frame. */
   send(data: string | ArrayBufferLike | ArrayBufferView): void;
+
+  /** Initiates a closing handshake with an optional status code and reason. */
   close(code?: number, reason?: string): void;
+
+  /** Subscribes to a browser-native WebSocket event. */
   addEventListener(type: string, listener: DOMEventHandler): void;
+
+  /** Removes a previously registered browser-native event listener. */
   removeEventListener(type: string, listener: DOMEventHandler): void;
 }
 
@@ -25,59 +36,102 @@ interface CloseEvent {
   reason: string;
 }
 
+/**
+ * Adapts a browser-native WebSocket to the SDK's platform-neutral event API.
+ *
+ * Binary messages are received as `ArrayBuffer` values, browser event objects
+ * are converted into positional listener arguments, and browser errors are
+ * normalized to `Error` instances.
+ */
 export class BrowserWebSocket implements WebSocketLike {
   private _ws: WebSocket;
-  private _listenerMap = new Map<string, Map<Listener, DOMEventHandler>>();
+  private _listenerMap = new Map<string, Map<Listener, DOMEventHandler[]>>();
 
+  /** Wraps an existing browser socket and configures binary frames as array buffers. */
   constructor(ws: WebSocket) {
     this._ws = ws;
     this._ws.binaryType = 'arraybuffer';
   }
 
-  /** The underlying platform-specific socket. Code that accesses this will not be isomorphic across server and browser environments. */
+  /** The browser-native socket; accessing it makes calling code platform-specific. */
   get platformSocket(): WebSocket {
     return this._ws;
   }
 
+  /** Current numeric browser connection state, using standard WebSocket values. */
   get readyState(): number {
     return this._ws.readyState;
   }
 
+  /** Sends a text or binary frame without changing its contents. */
   send(data: string | ArrayBufferLike | ArrayBufferView): void {
     this._ws.send(data);
   }
 
+  /** Initiates the browser socket's closing handshake. */
   close(code?: number, reason?: string): void {
     this._ws.close(code, reason);
   }
 
+  /** Registers a listener and converts browser event objects to SDK event arguments. */
   on(event: string, listener: Listener): void {
-    const wrapped = this._wrapListener(event, listener);
-    this._listenersFor(event).set(listener, wrapped);
-    this._ws.addEventListener(event, wrapped);
+    const wrapped = BrowserWebSocket._wrapListener(event, listener);
+    this._addListener(event, listener, wrapped);
   }
 
+  /** Removes the browser event wrapper associated with the original listener. */
   off(event: string, listener: Listener): void {
-    const byListener = this._listenerMap.get(event);
-    if (!byListener) return;
-    const wrapped = byListener.get(listener);
+    const wrappedListeners = this._listenerMap.get(event)?.get(listener);
+    const [wrapped] = wrappedListeners?.slice(-1) ?? [];
     if (wrapped) {
-      byListener.delete(listener);
-      this._ws.removeEventListener(event, wrapped);
+      this._removeListener(event, listener, wrapped);
     }
   }
 
+  /** Registers a listener that is removed before it handles its first event. */
   once(event: string, listener: Listener): void {
-    const onceListener: Listener = (...args) => {
-      this.off(event, listener);
+    let fired = false;
+    const wrapped = BrowserWebSocket._wrapListener(event, (...args) => {
+      if (fired) {
+        return;
+      }
+      fired = true;
+      this._removeListener(event, listener, wrapped);
       listener(...args);
-    };
-    const wrapped = this._wrapListener(event, onceListener);
-    this._listenersFor(event).set(listener, wrapped);
+    });
+    this._addListener(event, listener, wrapped);
+  }
+
+  private _addListener(event: string, listener: Listener, wrapped: DOMEventHandler): void {
     this._ws.addEventListener(event, wrapped);
+    const byListener = this._listenersFor(event);
+    const wrappedListeners = byListener.get(listener);
+    if (!wrappedListeners) {
+      byListener.set(listener, [wrapped]);
+    } else if (!wrappedListeners.includes(wrapped)) {
+      wrappedListeners.push(wrapped);
+    }
+  }
+
+  private _removeListener(event: string, listener: Listener, wrapped: DOMEventHandler): void {
+    const byListener = this._listenerMap.get(event);
+    const wrappedListeners = byListener?.get(listener);
+    const index = wrappedListeners?.lastIndexOf(wrapped) ?? -1;
+    if (!byListener || !wrappedListeners || index === -1) {
+      return;
+    }
+
+    this._ws.removeEventListener(event, wrapped);
+    wrappedListeners.splice(index, 1);
+    if (wrappedListeners.length === 0) {
+      byListener.delete(listener);
+    }
+    if (byListener.size === 0) {
+      this._listenerMap.delete(event);
+    }
   }
 
-  private _listenersFor(event: string): Map<Listener, DOMEventHandler> {
+  private _listenersFor(event: string): Map<Listener, DOMEventHandler[]> {
     let map = this._listenerMap.get(event);
     if (!map) {
       map = new Map();
@@ -90,20 +144,22 @@ export class BrowserWebSocket implements WebSocketLike {
    * Converts browser event objects to positional arguments matching the
    * {@link WebSocketLike} interface.
    */
-  private _wrapListener(event: string, listener: Listener): DOMEventHandler {
+  private static _wrapListener(event: string, listener: Listener): DOMEventHandler {
     switch (event) {
-      case 'message':
+      case 'message': {
         return (ev: MessageEvent) => {
           const isBinary = typeof ev.data !== 'string';
           listener(ev.data, isBinary);
         };
+      }
 
-      case 'close':
+      case 'close': {
         return (ev: CloseEvent) => {
           listener(ev.code, ev.reason);
         };
+      }
 
-      case 'error':
+      case 'error': {
         return (ev: any) => {
           // Some environments provide an ErrorEvent with a `.message`;
           // fall back to a generic message when the event carries nothing.
@@ -114,10 +170,11 @@ export class BrowserWebSocket implements WebSocketLike {
           }
           listener(err);
         };
+      }
 
-      case 'open':
-      default:
+      default: {
         return listener as DOMEventHandler;
+      }
     }
   }
 }

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

@@ -1,63 +1,131 @@
 import type * as WS from 'ws';
 import type { WebSocketLike } from './ws-adapter';
+import { protectWebSocketOptionsFromCredentialRedirects } from './ws';
 
 /** A generic event listener callback. */
 type Listener = (...args: any[]) => void;
 
+/**
+ * Adapts a Node.js `ws` socket to the SDK's platform-neutral WebSocket API.
+ *
+ * Text frames become strings, binary frames become `Buffer` values, fragmented
+ * messages are merged, and close reasons are decoded before reaching listeners.
+ */
 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>>();
+  /** Maps `(event, originalListener)` to every wrapped registration in listener order. */
+  private _listenerMap = new Map<string, Map<Listener, Listener[]>>();
 
+  /** Wraps an existing socket created by the optional `ws` package. */
   constructor(ws: WS.WebSocket) {
     this._ws = ws;
+    this._ws.on('redirect', (_url, request) => {
+      try {
+        const options = protectWebSocketOptionsFromCredentialRedirects({
+          followRedirects: true,
+          headers: request.getHeaders(),
+        });
+
+        if (options.followRedirects) {
+          return;
+        }
+      } catch {
+        // Header inspection failure must never permit a credentialed redirect.
+      }
+
+      this._ws.terminate();
+    });
   }
 
-  /** The underlying platform-specific socket. Code that accesses this will not be isomorphic across server and browser environments. */
+  /** The underlying `ws` socket; accessing it makes calling code Node.js-specific. */
   get platformSocket(): WS.WebSocket {
     return this._ws;
   }
 
+  /** Current numeric socket connection state, using standard WebSocket values. */
   get readyState(): number {
     return this._ws.readyState;
   }
 
+  /** Sends a text or binary frame through the underlying `ws` connection. */
   send(data: string | ArrayBufferLike | ArrayBufferView): void {
     this._ws.send(data);
   }
 
+  /** Initiates the socket's closing handshake with an optional code and reason. */
   close(code?: number, reason?: string): void {
     this._ws.close(code, reason);
   }
 
+  /** Registers a listener with normalized message payloads and close reasons. */
   on(event: string, listener: Listener): void {
-    const wrapped = this._wrapListener(event, listener);
-    this._listenersFor(event).set(listener, wrapped);
-    this._ws.on(event, wrapped);
+    const wrapped = NodeWebSocket._wrapListener(event, listener);
+    this._registerListener(event, listener, wrapped);
   }
 
+  /** Removes the platform listener associated with the original callback. */
   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);
+    const wrappedListeners = this._listenerMap.get(event)?.get(listener);
+    const [wrapped] = wrappedListeners?.slice(-1) ?? [];
+    if (!wrapped) {
+      return;
     }
+
+    this._removeListener(event, listener, wrapped);
   }
 
+  /** Registers a listener that is removed before it handles its first event. */
   once(event: string, listener: Listener): void {
-    const onceListener: Listener = (...args) => {
-      this.off(event, listener);
+    let fired = false;
+    const wrapped = NodeWebSocket._wrapListener(event, (...args) => {
+      if (fired) {
+        return;
+      }
+
+      fired = true;
+      this._removeListener(event, listener, wrapped);
       listener(...args);
-    };
-    const wrapped = this._wrapListener(event, onceListener);
-    this._listenersFor(event).set(listener, wrapped);
+    });
+    this._registerListener(event, listener, wrapped);
+  }
+
+  private _registerListener(event: string, listener: Listener, wrapped: Listener): void {
+    const byListener = this._listenersFor(event);
+    const wrappedListeners = byListener.get(listener);
+    if (wrappedListeners) {
+      wrappedListeners.push(wrapped);
+    } else {
+      byListener.set(listener, [wrapped]);
+    }
+
     this._ws.on(event, wrapped);
   }
 
-  private _listenersFor(event: string): Map<Listener, Listener> {
+  private _removeListener(event: string, listener: Listener, wrapped: Listener): void {
+    const byListener = this._listenerMap.get(event);
+    const wrappedListeners = byListener?.get(listener);
+    if (!byListener || !wrappedListeners) {
+      return;
+    }
+
+    const index = wrappedListeners.lastIndexOf(wrapped);
+    if (index === -1) {
+      return;
+    }
+
+    wrappedListeners.splice(index, 1);
+    if (wrappedListeners.length === 0) {
+      byListener.delete(listener);
+    }
+    if (byListener.size === 0) {
+      this._listenerMap.delete(event);
+    }
+
+    this._ws.removeListener(event, wrapped);
+  }
+
+  private _listenersFor(event: string): Map<Listener, Listener[]> {
     let map = this._listenerMap.get(event);
     if (!map) {
       map = new Map();
@@ -75,31 +143,42 @@ export class NodeWebSocket implements WebSocketLike {
     isBinary: boolean,
   ): string | Buffer {
     if (!isBinary) {
-      if (Array.isArray(data)) return Buffer.concat(data).toString();
-      if (data instanceof ArrayBuffer) return Buffer.from(data).toString();
+      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);
+    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 {
+  private static _wrapListener(event: string, listener: Listener): Listener {
     switch (event) {
-      case 'message':
+      case 'message': {
         return (data: Buffer | ArrayBuffer | Buffer[], isBinary: boolean) => {
           listener(NodeWebSocket._normalizeMessageData(data, isBinary), isBinary);
         };
+      }
 
-      case 'close':
+      case 'close': {
         return (code: number, reason: Buffer) => {
           listener(code, reason.toString());
         };
+      }
 
       // 'open' and 'error' pass through unchanged
-      default:
+      default: {
         return listener;
+      }
     }
   }
 }

package/src/internal/ws-adapter.ts

@@ -3,28 +3,51 @@
  * and the native WebSocket API (browser).
  */
 export interface WebSocketLike {
+  /** Current connection state, using the numeric values in {@link ReadyState}. */
   readonly readyState: number;
 
+  /** Sends a text or binary frame through the underlying platform socket. */
   send(data: string | ArrayBufferLike | ArrayBufferView): void;
+
+  /** Initiates the closing handshake, optionally providing a close code and reason. */
   close(code?: number, reason?: string): void;
 
+  /** Registers a listener that runs when the socket connection opens. */
   on(event: 'open', listener: () => void): void;
+
+  /** Registers a listener for normalized text or binary message payloads. */
   on(
     event: 'message',
     listener: (data: string | ArrayBuffer | ArrayBufferView, isBinary: boolean) => void,
   ): void;
+
+  /** Registers a listener for the numeric close code and decoded close reason. */
   on(event: 'close', listener: (code: number, reason: string) => void): void;
+
+  /** Registers a listener for normalized WebSocket connection errors. */
   on(event: 'error', listener: (err: Error) => void): void;
+
+  /** Registers a listener for any additional platform-supported socket event. */
   on(event: string, listener: (...args: any[]) => void): void;
 
+  /** Removes a listener previously registered for the same event. */
   off(event: string, listener: (...args: any[]) => void): void;
+
+  /** Registers a listener that removes itself before its first invocation. */
   once(event: string, listener: (...args: any[]) => void): void;
 }
 
 /** Standard WebSocket readyState values (RFC 6455). */
 export const ReadyState = {
+  /** The connection has been created but is not ready to send messages. */
   CONNECTING: 0,
+
+  /** The connection is established and ready to send messages. */
   OPEN: 1,
+
+  /** The closing handshake has started but is not complete. */
   CLOSING: 2,
+
+  /** The connection is closed or could not be established. */
   CLOSED: 3,
 } as const;