openai 6.34.0 → 6.36.0

package/src/client.ts

@@ -24,6 +24,8 @@ import {
   ConversationCursorPageResponse,
   type CursorPageParams,
   CursorPageResponse,
+  type NextCursorPageParams,
+  NextCursorPageResponse,
   PageResponse,
 } from './core/pagination';
 import * as Uploads from './core/uploads';
@@ -115,6 +117,7 @@ import {
   Videos,
   VideosPage,
 } from './resources/videos';
+import { Admin } from './resources/admin/admin';
 import { Audio, AudioModel, AudioResponseFormat } from './resources/audio/audio';
 import { Beta } from './resources/beta/beta';
 import { Chat } from './resources/chat/chat';
@@ -258,7 +261,12 @@ export interface ClientOptions {
    *   error available as `cause`.
    * - Mutually exclusive with `workloadIdentity`.
    */
-  apiKey?: string | ApiKeySetter | undefined;
+  apiKey?: string | ApiKeySetter | null | undefined;
+
+  /**
+   * Defaults to process.env['OPENAI_ADMIN_KEY'].
+   */
+  adminAPIKey?: string | null | undefined;
 
   /**
    * Defaults to process.env['OPENAI_ORG_ID'].
@@ -361,7 +369,8 @@ export interface ClientOptions {
  * API Client for interfacing with the OpenAI API.
  */
 export class OpenAI {
-  apiKey: string;
+  apiKey: string | null;
+  adminAPIKey: string | null;
   organization: string | null;
   project: string | null;
   webhookSecret: string | null;
@@ -382,7 +391,8 @@ export class OpenAI {
   /**
    * API Client for interfacing with the OpenAI API.
    *
-   * @param {string | undefined} [opts.apiKey=process.env['OPENAI_API_KEY'] ?? undefined]
+   * @param {string | null | undefined} [opts.apiKey=process.env['OPENAI_API_KEY'] ?? null]
+   * @param {string | null | undefined} [opts.adminAPIKey=process.env['OPENAI_ADMIN_KEY'] ?? null]
    * @param {string | null | undefined} [opts.organization=process.env['OPENAI_ORG_ID'] ?? null]
    * @param {string | null | undefined} [opts.project=process.env['OPENAI_PROJECT_ID'] ?? null]
    * @param {string | null | undefined} [opts.webhookSecret=process.env['OPENAI_WEBHOOK_SECRET'] ?? null]
@@ -397,28 +407,17 @@ export class OpenAI {
    */
   constructor({
     baseURL = readEnv('OPENAI_BASE_URL'),
-    apiKey = readEnv('OPENAI_API_KEY'),
+    apiKey = readEnv('OPENAI_API_KEY') ?? null,
+    adminAPIKey = readEnv('OPENAI_ADMIN_KEY') ?? null,
     organization = readEnv('OPENAI_ORG_ID') ?? null,
     project = readEnv('OPENAI_PROJECT_ID') ?? null,
     webhookSecret = readEnv('OPENAI_WEBHOOK_SECRET') ?? null,
     workloadIdentity,
     ...opts
   }: ClientOptions = {}) {
-    if (workloadIdentity) {
-      if (apiKey && apiKey !== WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER) {
-        throw new Errors.OpenAIError(
-          'The `apiKey` and `workloadIdentity` arguments are mutually exclusive; only one can be passed at a time.',
-        );
-      }
-      apiKey = WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER;
-    } else if (apiKey === undefined) {
-      throw new Errors.OpenAIError(
-        'Missing credentials. Please pass an `apiKey`, `workloadIdentity`, or set the `OPENAI_API_KEY` environment variable.',
-      );
-    }
-
     const options: ClientOptions = {
       apiKey,
+      adminAPIKey,
       organization,
       project,
       webhookSecret,
@@ -427,6 +426,16 @@ export class OpenAI {
       baseURL: baseURL || `https://api.openai.com/v1`,
     };
 
+    if (apiKey && workloadIdentity) {
+      throw new Errors.OpenAIError('The `apiKey` and `workloadIdentity` options are mutually exclusive');
+    }
+
+    if (!apiKey && !adminAPIKey && !workloadIdentity) {
+      throw new Errors.OpenAIError(
+        'Missing credentials. Please pass an `apiKey`, `workloadIdentity`, `adminAPIKey`, or set the `OPENAI_API_KEY` or `OPENAI_ADMIN_KEY` environment variable.',
+      );
+    }
+
     if (!options.dangerouslyAllowBrowser && isRunningInBrowser()) {
       throw new Errors.OpenAIError(
         "It looks like you're running in a browser-like environment.\n\nThis is disabled by default, as it risks exposing your secret API credentials to attackers.\nIf you understand the risks and have appropriate mitigations in place,\nyou can set the `dangerouslyAllowBrowser` option to `true`, e.g.,\n\nnew OpenAI({ apiKey, dangerouslyAllowBrowser: true });\n\nhttps://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety\n",
@@ -448,13 +457,26 @@ export class OpenAI {
     this.fetch = options.fetch ?? Shims.getDefaultFetch();
     this.#encoder = Opts.FallbackEncoder;
 
+    const customHeadersEnv = readEnv('OPENAI_CUSTOM_HEADERS');
+    if (customHeadersEnv) {
+      const parsed: Record<string, string> = {};
+      for (const line of customHeadersEnv.split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon >= 0) {
+          parsed[line.substring(0, colon).trim()] = line.substring(colon + 1).trim();
+        }
+      }
+      options.defaultHeaders = buildHeaders([parsed, options.defaultHeaders]);
+    }
+
     this._options = options;
 
     if (workloadIdentity) {
       this._workloadIdentityAuth = new WorkloadIdentityAuth(workloadIdentity, this.fetch);
     }
 
-    this.apiKey = typeof apiKey === 'string' ? apiKey : 'Missing Key';
+    this.apiKey = typeof apiKey === 'string' ? apiKey : null;
+    this.adminAPIKey = adminAPIKey;
     this.organization = organization;
     this.project = project;
     this.webhookSecret = webhookSecret;
@@ -473,7 +495,8 @@ export class OpenAI {
       logLevel: this.logLevel,
       fetch: this.fetch,
       fetchOptions: this.fetchOptions,
-      apiKey: this.apiKey,
+      apiKey: this._options.apiKey,
+      adminAPIKey: this.adminAPIKey,
       workloadIdentity: this._options.workloadIdentity,
       organization: this.organization,
       project: this.project,
@@ -494,14 +517,59 @@ export class OpenAI {
     return this._options.defaultQuery;
   }
 
-  protected validateHeaders({ values, nulls }: NullableHeaders) {
-    return;
+  protected validateHeaders(
+    { values, nulls }: NullableHeaders,
+    schemes: { bearerAuth?: boolean; adminAPIKeyAuth?: boolean } = {
+      bearerAuth: true,
+      adminAPIKeyAuth: true,
+    },
+  ) {
+    if (values.get('authorization') || values.get('api-key')) {
+      return;
+    }
+    if (nulls.has('authorization') || nulls.has('api-key')) {
+      return;
+    }
+
+    if (this._workloadIdentityAuth && schemes.bearerAuth) {
+      return;
+    }
+
+    throw new Error(
+      'Could not resolve authentication method. Expected either apiKey or adminAPIKey to be set. Or for one of the "Authorization" or "api-key" headers to be explicitly omitted',
+    );
+  }
+
+  protected async authHeaders(
+    opts: FinalRequestOptions,
+    schemes: { bearerAuth?: boolean; adminAPIKeyAuth?: boolean } = {
+      bearerAuth: true,
+      adminAPIKeyAuth: true,
+    },
+  ): Promise<NullableHeaders | undefined> {
+    return buildHeaders([
+      schemes.bearerAuth ? await this.bearerAuth(opts) : null,
+      schemes.adminAPIKeyAuth ? await this.adminAPIKeyAuth(opts) : null,
+    ]);
   }
 
-  protected async authHeaders(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
+  protected async bearerAuth(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
+    if (this._workloadIdentityAuth) {
+      return buildHeaders([{ Authorization: `Bearer ${await this._workloadIdentityAuth.getToken()}` }]);
+    }
+    if (this.apiKey == null) {
+      return undefined;
+    }
     return buildHeaders([{ Authorization: `Bearer ${this.apiKey}` }]);
   }
 
+  protected async adminAPIKeyAuth(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
+    if (this.adminAPIKey == null) {
+      return undefined;
+    }
+    return buildHeaders([{ Authorization: `Bearer ${this.adminAPIKey}` }]);
+  }
+
   protected stringifyQuery(query: object | Record<string, unknown>): string {
     return stringifyQuery(query);
   }
@@ -576,7 +644,10 @@ export class OpenAI {
    * Used as a callback for mutating the given `FinalRequestOptions` object.
    */
   protected async prepareOptions(options: FinalRequestOptions): Promise<void> {
-    await this._callApiKey();
+    const security = options.__security ?? { bearerAuth: true };
+    if (security.bearerAuth) {
+      await this._callApiKey();
+    }
   }
 
   /**
@@ -668,8 +739,9 @@ export class OpenAI {
       throw new Errors.APIUserAbortError();
     }
 
+    const security = options.__security ?? { bearerAuth: true };
     const controller = new AbortController();
-    const response = await this.fetchWithAuth(url, req, timeout, controller).catch(castToError);
+    const response = await this.fetchWithAuth(url, req, timeout, controller, security).catch(castToError);
     const headersTime = Date.now();
 
     if (response instanceof globalThis.Error) {
@@ -732,6 +804,7 @@ export class OpenAI {
       if (
         response.status === 401 &&
         this._workloadIdentityAuth &&
+        security.bearerAuth &&
         !options.__metadata?.['hasStreamingBody'] &&
         !options.__metadata?.['workloadIdentityTokenRefreshed']
       ) {
@@ -844,8 +917,12 @@ export class OpenAI {
     init: RequestInit,
     timeout: number,
     controller: AbortController,
+    schemes: { bearerAuth?: boolean; adminAPIKeyAuth?: boolean } = {
+      bearerAuth: true,
+      adminAPIKeyAuth: true,
+    },
   ): Promise<Response> {
-    if (this._workloadIdentityAuth) {
+    if (this._workloadIdentityAuth && schemes.bearerAuth) {
       const headers = init.headers as Headers;
       const authHeader = headers.get('Authorization');
       if (!authHeader || authHeader === `Bearer ${WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER}`) {
@@ -1035,13 +1112,13 @@ export class OpenAI {
         'OpenAI-Organization': this.organization,
         'OpenAI-Project': this.project,
       },
-      await this.authHeaders(options),
+      await this.authHeaders(options, options.__security ?? { bearerAuth: true }),
       this._options.defaultHeaders,
       bodyHeaders,
       options.headers,
     ]);
 
-    this.validateHeaders(headers);
+    this.validateHeaders(headers, options.__security ?? { bearerAuth: true });
 
     return headers.values;
   }
@@ -1176,6 +1253,7 @@ export class OpenAI {
    * Use Uploads to upload large files in multiple parts.
    */
   uploads: API.Uploads = new API.Uploads(this);
+  admin: API.Admin = new API.Admin(this);
   responses: API.Responses = new API.Responses(this);
   realtime: API.Realtime = new API.Realtime(this);
   /**
@@ -1206,6 +1284,7 @@ OpenAI.Webhooks = Webhooks;
 OpenAI.Beta = Beta;
 OpenAI.Batches = Batches;
 OpenAI.Uploads = UploadsAPIUploads;
+OpenAI.Admin = Admin;
 OpenAI.Responses = Responses;
 OpenAI.Realtime = Realtime;
 OpenAI.Conversations = Conversations;
@@ -1229,6 +1308,12 @@ export declare namespace OpenAI {
     type ConversationCursorPageResponse as ConversationCursorPageResponse,
   };
 
+  export import NextCursorPage = Pagination.NextCursorPage;
+  export {
+    type NextCursorPageParams as NextCursorPageParams,
+    type NextCursorPageResponse as NextCursorPageResponse,
+  };
+
   export {
     Completions as Completions,
     type Completion as Completion,
@@ -1391,6 +1476,8 @@ export declare namespace OpenAI {
     type UploadCompleteParams as UploadCompleteParams,
   };
 
+  export { Admin as Admin };
+
   export { Responses as Responses };
 
   export { Realtime as Realtime };

package/src/core/EventEmitter.ts

@@ -96,3 +96,19 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
     return listeners && listeners.length > 0;
   }
 }
+
+/**
+ * An EventEmitter variant that exposes `_emit()` publicly.
+ *
+ * The base {@link EventEmitter} keeps `_emit` protected so that consumers
+ * can only listen, not dispatch. When you need a separate emitter instance
+ * that your own code can emit on, without exposing emit on the
+ * consumer-facing emitter, use this class.
+ */
+export class InternalEventEmitter<
+  EventTypes extends Record<string, (...args: any) => any>,
+> extends EventEmitter<EventTypes> {
+  override _emit<Event extends keyof EventTypes>(event: Event, ...args: EventParameters<EventTypes, Event>) {
+    super._emit(event, ...args);
+  }
+}

package/src/core/pagination.ts

@@ -267,3 +267,65 @@ export class ConversationCursorPage<Item>
     };
   }
 }
+
+export interface NextCursorPageResponse<Item> {
+  data: Array<Item>;
+
+  has_more: boolean;
+
+  next: string | null;
+}
+
+export interface NextCursorPageParams {
+  after?: string;
+
+  limit?: number;
+}
+
+export class NextCursorPage<Item> extends AbstractPage<Item> implements NextCursorPageResponse<Item> {
+  data: Array<Item>;
+
+  has_more: boolean;
+
+  next: string | null;
+
+  constructor(
+    client: OpenAI,
+    response: Response,
+    body: NextCursorPageResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.data = body.data || [];
+    this.has_more = body.has_more || false;
+    this.next = body.next || null;
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.data ?? [];
+  }
+
+  override hasNextPage(): boolean {
+    if (this.has_more === false) {
+      return false;
+    }
+
+    return super.hasNextPage();
+  }
+
+  nextPageRequestOptions(): PageRequestOptions | null {
+    const cursor = this.next;
+    if (!cursor) {
+      return null;
+    }
+
+    return {
+      ...this.options,
+      query: {
+        ...maybeObj(this.options.query),
+        after: cursor,
+      },
+    };
+  }
+}

package/src/internal/request-options.ts

@@ -77,6 +77,7 @@ export type RequestOptions = {
   defaultBaseURL?: string | undefined;
 
   __metadata?: Record<string, unknown>;
+  __security?: { bearerAuth?: boolean; adminAPIKeyAuth?: boolean };
   __binaryResponse?: boolean | undefined;
   __streamClass?: typeof Stream;
   __synthesizeEventData?: boolean;

package/src/internal/types.ts

@@ -40,7 +40,6 @@ type OverloadedParameters<T> =
   : T extends (...args: infer A) => unknown ? A
   : never;
 
-/* eslint-disable */
 /**
  * These imports attempt to get types from a parent package's dependencies.
  * Unresolved bare specifiers can trigger [automatic type acquisition][1] in some projects, which
@@ -63,19 +62,18 @@ type OverloadedParameters<T> =
  *
  * [1]: https://www.typescriptlang.org/tsconfig/#typeAcquisition
  */
-/** @ts-ignore For users with \@types/node */
+/** @ts-ignore For users with \@types/node */ /* prettier-ignore */
 type UndiciTypesRequestInit = NotAny<import('../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici-types/index.d.ts').RequestInit>;
-/** @ts-ignore For users with undici */
+/** @ts-ignore For users with undici */ /* prettier-ignore */
 type UndiciRequestInit = NotAny<import('../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/undici/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/undici/index.d.ts').RequestInit>;
-/** @ts-ignore For users with \@types/bun */
+/** @ts-ignore For users with \@types/bun */ /* prettier-ignore */
 type BunRequestInit = globalThis.FetchRequestInit;
-/** @ts-ignore For users with node-fetch@2 */
+/** @ts-ignore For users with node-fetch@2 */ /* prettier-ignore */
 type NodeFetch2RequestInit = NotAny<import('../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/@types/node-fetch/index.d.ts').RequestInit>;
-/** @ts-ignore For users with node-fetch@3, doesn't need file extension because types are at ./@types/index.d.ts */
+/** @ts-ignore For users with node-fetch@3, doesn't need file extension because types are at ./@types/index.d.ts */ /* prettier-ignore */
 type NodeFetch3RequestInit =  NotAny<import('../node_modules/node-fetch').RequestInit> | NotAny<import('../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../node_modules/node-fetch').RequestInit> | NotAny<import('../../../../../../../../../../node_modules/node-fetch').RequestInit>;
-/** @ts-ignore For users who use Deno */
+/** @ts-ignore For users who use Deno */ /* prettier-ignore */
 type FetchRequestInit = NonNullable<OverloadedParameters<typeof fetch>[1]>;
-/* eslint-enable */
 
 type RequestInits =
   | NotAny<UndiciTypesRequestInit>

package/src/internal/utils/env.ts

@@ -9,10 +9,10 @@
  */
 export const readEnv = (env: string): string | undefined => {
   if (typeof (globalThis as any).process !== 'undefined') {
-    return (globalThis as any).process.env?.[env]?.trim() ?? undefined;
+    return (globalThis as any).process.env?.[env]?.trim() || undefined;
   }
   if (typeof (globalThis as any).Deno !== 'undefined') {
-    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+    return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined;
   }
   return undefined;
 };

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

@@ -0,0 +1,123 @@
+import type { WebSocketLike } from './ws-adapter';
+
+/** A generic event listener callback. */
+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 {
+  readonly readyState: number;
+  binaryType: string;
+  send(data: string | ArrayBufferLike | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: string, listener: DOMEventHandler): void;
+  removeEventListener(type: string, listener: DOMEventHandler): void;
+}
+
+interface MessageEvent {
+  data: any;
+}
+
+interface CloseEvent {
+  code: number;
+  reason: string;
+}
+
+export class BrowserWebSocket implements WebSocketLike {
+  private _ws: WebSocket;
+  private _listenerMap = new Map<string, Map<Listener, DOMEventHandler>>();
+
+  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. */
+  get platformSocket(): 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.addEventListener(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.removeEventListener(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.addEventListener(event, wrapped);
+  }
+
+  private _listenersFor(event: string): Map<Listener, DOMEventHandler> {
+    let map = this._listenerMap.get(event);
+    if (!map) {
+      map = new Map();
+      this._listenerMap.set(event, map);
+    }
+    return map;
+  }
+
+  /**
+   * Converts browser event objects to positional arguments matching the
+   * {@link WebSocketLike} interface.
+   */
+  private _wrapListener(event: string, listener: Listener): DOMEventHandler {
+    switch (event) {
+      case 'message':
+        return (ev: MessageEvent) => {
+          const isBinary = typeof ev.data !== 'string';
+          listener(ev.data, isBinary);
+        };
+
+      case 'close':
+        return (ev: CloseEvent) => {
+          listener(ev.code, ev.reason);
+        };
+
+      case 'error':
+        return (ev: any) => {
+          // Some environments provide an ErrorEvent with a `.message`;
+          // fall back to a generic message when the event carries nothing.
+          const message = ev?.message || ev?.error?.message || 'WebSocket error';
+          const err = new Error(message);
+          if (ev?.error) {
+            (err as any).cause = ev.error;
+          }
+          listener(err);
+        };
+
+      case 'open':
+      default:
+        return listener as DOMEventHandler;
+    }
+  }
+}

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;
+    }
+  }
+}