openai 6.34.0 → 6.36.0

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/realtime/websocket.ts

@@ -116,11 +116,16 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     options: { deploymentName?: string; dangerouslyAllowBrowser?: boolean } = {},
   ): Promise<OpenAIRealtimeWebSocket> {
     const isApiKeyProvider = await client._callApiKey();
+    const apiKey = client.apiKey;
+    if (!apiKey) {
+      throw new Error('Azure OpenAI Realtime requires an API key');
+    }
+    const azureApiKey = apiKey;
     function onURL(url: URL) {
       if (isApiKeyProvider) {
-        url.searchParams.set('Authorization', `Bearer ${client.apiKey}`);
+        url.searchParams.set('Authorization', `Bearer ${azureApiKey}`);
       } else {
-        url.searchParams.set('api-key', client.apiKey);
+        url.searchParams.set('api-key', azureApiKey);
       }
     }
     const deploymentName = options.deploymentName ?? client.deploymentName;

package/src/realtime/ws.ts

@@ -75,6 +75,10 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     props: { deploymentName?: string; options?: WS.ClientOptions | undefined } = {},
   ): Promise<OpenAIRealtimeWS> {
     const isApiKeyProvider = await client._callApiKey();
+    const apiKey = client.apiKey;
+    if (!apiKey) {
+      throw new Error('Azure OpenAI Realtime requires an API key');
+    }
     const deploymentName = props.deploymentName ?? client.deploymentName;
     if (!deploymentName) {
       throw new Error('No deployment name provided');
@@ -86,7 +90,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
           ...props.options,
           headers: {
             ...props.options?.headers,
-            ...(isApiKeyProvider ? {} : { 'api-key': client.apiKey }),
+            ...(isApiKeyProvider ? {} : { 'api-key': apiKey }),
           },
         },
         __resolvedApiKey: isApiKeyProvider,

package/src/resources/admin/admin.ts

@@ -0,0 +1,15 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as OrganizationAPI from './organization/organization';
+import { Organization } from './organization/organization';
+
+export class Admin extends APIResource {
+  organization: OrganizationAPI.Organization = new OrganizationAPI.Organization(this._client);
+}
+
+Admin.Organization = Organization;
+
+export declare namespace Admin {
+  export { Organization as Organization };
+}

package/src/resources/admin/index.ts

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Admin } from './admin';
+export { Organization } from './organization/index';

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

@@ -0,0 +1,199 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../../core/pagination';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class AdminAPIKeys extends APIResource {
+  /**
+   * Create an organization admin API key
+   *
+   * @example
+   * ```ts
+   * const adminAPIKey =
+   *   await client.admin.organization.adminAPIKeys.create({
+   *     name: 'New Admin Key',
+   *   });
+   * ```
+   */
+  create(body: AdminAPIKeyCreateParams, options?: RequestOptions): APIPromise<AdminAPIKeyCreateResponse> {
+    return this._client.post('/organization/admin_api_keys', {
+      body,
+      ...options,
+      __security: { adminAPIKeyAuth: true },
+    });
+  }
+
+  /**
+   * Retrieve a single organization API key
+   *
+   * @example
+   * ```ts
+   * const adminAPIKey =
+   *   await client.admin.organization.adminAPIKeys.retrieve(
+   *     'key_id',
+   *   );
+   * ```
+   */
+  retrieve(keyID: string, options?: RequestOptions): APIPromise<AdminAPIKey> {
+    return this._client.get(path`/organization/admin_api_keys/${keyID}`, {
+      ...options,
+      __security: { adminAPIKeyAuth: true },
+    });
+  }
+
+  /**
+   * List organization API keys
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const adminAPIKey of client.admin.organization.adminAPIKeys.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: AdminAPIKeyListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AdminAPIKeysPage, AdminAPIKey> {
+    return this._client.getAPIList('/organization/admin_api_keys', CursorPage<AdminAPIKey>, {
+      query,
+      ...options,
+      __security: { adminAPIKeyAuth: true },
+    });
+  }
+
+  /**
+   * Delete an organization admin API key
+   *
+   * @example
+   * ```ts
+   * const adminAPIKey =
+   *   await client.admin.organization.adminAPIKeys.delete(
+   *     'key_id',
+   *   );
+   * ```
+   */
+  delete(keyID: string, options?: RequestOptions): APIPromise<AdminAPIKeyDeleteResponse> {
+    return this._client.delete(path`/organization/admin_api_keys/${keyID}`, {
+      ...options,
+      __security: { adminAPIKeyAuth: true },
+    });
+  }
+}
+
+export type AdminAPIKeysPage = CursorPage<AdminAPIKey>;
+
+/**
+ * Represents an individual Admin API key in an org.
+ */
+export interface AdminAPIKey {
+  /**
+   * The identifier, which can be referenced in API endpoints
+   */
+  id: string;
+
+  /**
+   * The Unix timestamp (in seconds) of when the API key was created
+   */
+  created_at: number;
+
+  /**
+   * The object type, which is always `organization.admin_api_key`
+   */
+  object: 'organization.admin_api_key';
+
+  owner: AdminAPIKey.Owner;
+
+  /**
+   * The redacted value of the API key
+   */
+  redacted_value: string;
+
+  /**
+   * The Unix timestamp (in seconds) of when the API key was last used
+   */
+  last_used_at?: number | null;
+
+  /**
+   * The name of the API key
+   */
+  name?: string | null;
+}
+
+export namespace AdminAPIKey {
+  export interface Owner {
+    /**
+     * The identifier, which can be referenced in API endpoints
+     */
+    id?: string;
+
+    /**
+     * The Unix timestamp (in seconds) of when the user was created
+     */
+    created_at?: number;
+
+    /**
+     * The name of the user
+     */
+    name?: string;
+
+    /**
+     * The object type, which is always organization.user
+     */
+    object?: string;
+
+    /**
+     * Always `owner`
+     */
+    role?: string;
+
+    /**
+     * Always `user`
+     */
+    type?: string;
+  }
+}
+
+/**
+ * Represents an individual Admin API key in an org.
+ */
+export interface AdminAPIKeyCreateResponse extends AdminAPIKey {
+  /**
+   * The value of the API key. Only shown on create.
+   */
+  value: string;
+}
+
+export interface AdminAPIKeyDeleteResponse {
+  id: string;
+
+  deleted: boolean;
+
+  object: 'organization.admin_api_key.deleted';
+}
+
+export interface AdminAPIKeyCreateParams {
+  name: string;
+}
+
+export interface AdminAPIKeyListParams extends CursorPageParams {
+  /**
+   * Order results by creation time, ascending or descending.
+   */
+  order?: 'asc' | 'desc';
+}
+
+export declare namespace AdminAPIKeys {
+  export {
+    type AdminAPIKey as AdminAPIKey,
+    type AdminAPIKeyCreateResponse as AdminAPIKeyCreateResponse,
+    type AdminAPIKeyDeleteResponse as AdminAPIKeyDeleteResponse,
+    type AdminAPIKeysPage as AdminAPIKeysPage,
+    type AdminAPIKeyCreateParams as AdminAPIKeyCreateParams,
+    type AdminAPIKeyListParams as AdminAPIKeyListParams,
+  };
+}