@nocobase/plugin-ai 2.1.7 → 2.1.9

package/dist/node_modules/openai/src/core/EventEmitter.ts

@@ -0,0 +1,114 @@
+type EventListener<Events, EventType extends keyof Events> = Events[EventType];
+
+type EventListeners<Events, EventType extends keyof Events> = Array<{
+  listener: EventListener<Events, EventType>;
+  once?: boolean;
+}>;
+
+export type EventParameters<Events, EventType extends keyof Events> = {
+  [Event in EventType]: EventListener<Events, EventType> extends (...args: infer P) => any ? P : never;
+}[EventType];
+
+export class EventEmitter<EventTypes extends Record<string, (...args: any) => any>> {
+  #listeners: {
+    [Event in keyof EventTypes]?: EventListeners<EventTypes, Event>;
+  } = {};
+
+  /**
+   * Adds the listener function to the end of the listeners array for the event.
+   * No checks are made to see if the listener has already been added. Multiple calls passing
+   * the same combination of event and listener will result in the listener being added, and
+   * called, multiple times.
+   * @returns this, so that calls can be chained
+   */
+  on<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
+    const listeners: EventListeners<EventTypes, Event> =
+      this.#listeners[event] || (this.#listeners[event] = []);
+    listeners.push({ listener });
+    return this;
+  }
+
+  /**
+   * Removes the specified listener from the listener array for the event.
+   * off() will remove, at most, one instance of a listener from the listener array. If any single
+   * listener has been added multiple times to the listener array for the specified event, then
+   * off() must be called multiple times to remove each instance.
+   * @returns this, so that calls can be chained
+   */
+  off<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
+    const listeners = this.#listeners[event];
+    if (!listeners) return this;
+    const index = listeners.findIndex((l) => l.listener === listener);
+    if (index >= 0) listeners.splice(index, 1);
+    return this;
+  }
+
+  /**
+   * Adds a one-time listener function for the event. The next time the event is triggered,
+   * this listener is removed and then invoked.
+   * @returns this, so that calls can be chained
+   */
+  once<Event extends keyof EventTypes>(event: Event, listener: EventListener<EventTypes, Event>): this {
+    const listeners: EventListeners<EventTypes, Event> =
+      this.#listeners[event] || (this.#listeners[event] = []);
+    listeners.push({ listener, once: true });
+    return this;
+  }
+
+  /**
+   * This is similar to `.once()`, but returns a Promise that resolves the next time
+   * the event is triggered, instead of calling a listener callback.
+   * @returns a Promise that resolves the next time given event is triggered,
+   * or rejects if an error is emitted.  (If you request the 'error' event,
+   * returns a promise that resolves with the error).
+   *
+   * Example:
+   *
+   *   const message = await stream.emitted('message') // rejects if the stream errors
+   */
+  emitted<Event extends keyof EventTypes>(
+    event: Event,
+  ): Promise<
+    EventParameters<EventTypes, Event> extends [infer Param] ? Param
+    : EventParameters<EventTypes, Event> extends [] ? void
+    : EventParameters<EventTypes, Event>
+  > {
+    return new Promise((resolve, reject) => {
+      // TODO: handle errors
+      this.once(event, resolve as any);
+    });
+  }
+
+  protected _emit<Event extends keyof EventTypes>(
+    this: EventEmitter<EventTypes>,
+    event: Event,
+    ...args: EventParameters<EventTypes, Event>
+  ) {
+    const listeners: EventListeners<EventTypes, Event> | undefined = this.#listeners[event];
+    if (listeners) {
+      this.#listeners[event] = listeners.filter((l) => !l.once) as any;
+      listeners.forEach(({ listener }: any) => listener(...(args as any)));
+    }
+  }
+
+  protected _hasListener(event: keyof EventTypes): boolean {
+    const listeners = this.#listeners[event];
+    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/dist/node_modules/openai/src/core/error.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { castToError } from '../internal/errors';
+import type { OAuthErrorCode } from '../resources/shared';
 
 export class OpenAIError extends Error {}
 
@@ -158,3 +159,42 @@ export class InvalidWebhookSignatureError extends Error {
     super(message);
   }
 }
+
+/**
+ * Error thrown by the API server during OAuth token exchange.
+ * Can have status codes 400, 401, or 403.
+ * Other status codes from OAuth endpoints are raised as normal APIError types.
+ */
+export class OAuthError extends APIError<400 | 401 | 403, Headers> {
+  readonly error_code: OAuthErrorCode | undefined;
+
+  constructor(status: 400 | 401 | 403, error: Object | undefined, headers: Headers) {
+    let finalMessage = 'OAuth2 authentication error';
+    let error_code: OAuthErrorCode | undefined = undefined;
+
+    if (error && typeof error === 'object') {
+      const errorData = error as Record<string, any>;
+      error_code = errorData['error'];
+      const description = errorData['error_description'];
+      if (description && typeof description === 'string') {
+        finalMessage = description;
+      } else if (error_code) {
+        finalMessage = error_code;
+      }
+    }
+
+    super(status, error, finalMessage, headers);
+    this.error_code = error_code;
+  }
+}
+
+export class SubjectTokenProviderError extends OpenAIError {
+  readonly provider: string;
+  readonly cause: Error | undefined;
+
+  constructor(message: string, provider: string, cause?: Error) {
+    super(message);
+    this.provider = provider;
+    this.cause = cause;
+  }
+}

package/dist/node_modules/openai/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/dist/node_modules/openai/src/core/streaming.ts

@@ -35,6 +35,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
     response: Response,
     controller: AbortController,
     client?: OpenAI,
+    synthesizeEventData?: boolean,
   ): Stream<Item> {
     let consumed = false;
     const logger = client ? loggerFor(client) : console;
@@ -69,7 +70,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
               throw new APIError(undefined, data.error, undefined, response.headers);
             }
 
-            yield data;
+            yield synthesizeEventData ? { event: sse.event, data } : data;
           } else {
             let data;
             try {

package/dist/node_modules/openai/src/index.ts

@@ -21,6 +21,8 @@ export {
   PermissionDeniedError,
   UnprocessableEntityError,
   InvalidWebhookSignatureError,
+  OAuthError,
+  SubjectTokenProviderError,
 } from './core/error';
 
 export { AzureOpenAI } from './azure';

package/dist/node_modules/openai/src/internal/parse.ts

@@ -28,10 +28,20 @@ export async function defaultParseResponse<T>(
       // that if you set `stream: true` the response type must also be `Stream<T>`
 
       if (props.options.__streamClass) {
-        return props.options.__streamClass.fromSSEResponse(response, props.controller, client) as any;
+        return props.options.__streamClass.fromSSEResponse(
+          response,
+          props.controller,
+          client,
+          props.options.__synthesizeEventData,
+        ) as any;
       }
 
-      return Stream.fromSSEResponse(response, props.controller, client) as any;
+      return Stream.fromSSEResponse(
+        response,
+        props.controller,
+        client,
+        props.options.__synthesizeEventData,
+      ) as any;
     }
 
     // fetch refuses to read the body when the status code is 204.

package/dist/node_modules/openai/src/internal/request-options.ts

@@ -77,8 +77,10 @@ export type RequestOptions = {
   defaultBaseURL?: string | undefined;
 
   __metadata?: Record<string, unknown>;
+  __security?: { bearerAuth?: boolean; adminAPIKeyAuth?: boolean };
   __binaryResponse?: boolean | undefined;
   __streamClass?: typeof Stream;
+  __synthesizeEventData?: boolean;
 };
 
 export type EncodedContent = { bodyHeaders: HeadersLike; body: BodyInit };

package/dist/node_modules/openai/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>
@@ -86,10 +84,18 @@ type RequestInits =
   | NotAny<RequestInit>
   | NotAny<FetchRequestInit>;
 
+type RuntimeFetchOptions = {
+  dispatcher?: unknown;
+  agent?: unknown;
+  client?: unknown;
+  proxy?: unknown;
+};
+
 /**
  * This type contains `RequestInit` options that may be available on the current runtime,
  * including per-platform extensions like `dispatcher`, `agent`, `client`, etc.
  */
 export type MergedRequestInit = RequestInits &
+  RuntimeFetchOptions &
   /** We don't include these in the types as they'll be overridden for every request. */
   Partial<Record<'body' | 'headers' | 'method' | 'signal', never>>;

package/dist/node_modules/openai/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/dist/node_modules/openai/src/internal/utils/log.ts

@@ -107,6 +107,8 @@ export const formatRequestDetails = (details: {
           name,
           (
             name.toLowerCase() === 'authorization' ||
+            name.toLowerCase() === 'api-key' ||
+            name.toLowerCase() === 'x-api-key' ||
             name.toLowerCase() === 'cookie' ||
             name.toLowerCase() === 'set-cookie'
           ) ?

package/dist/node_modules/openai/src/internal/utils/query.ts

@@ -0,0 +1,7 @@
+// 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>) {
+  return qs.stringify(query, { arrayFormat: 'brackets' });
+}

package/dist/node_modules/openai/src/internal/utils.ts

@@ -6,3 +6,4 @@ export * from './utils/env';
 export * from './utils/log';
 export * from './utils/uuid';
 export * from './utils/sleep';
+export * from './utils/query';

package/dist/node_modules/openai/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/dist/node_modules/openai/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/dist/node_modules/openai/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;