openai 7.13.0 → 7.15.0

package/src/lib/webrtc/connection.ts

@@ -0,0 +1,309 @@
+import { DataChannel } from './data-channel';
+import { WebRTCError } from './errors';
+import type { WebRTCErrorPhase } from './errors';
+import { Subscriptions } from './subscriptions';
+import type {
+  BrowserDataChannel,
+  BrowserPeerConnection,
+  WebRTCConfiguration,
+  WebRTCConnectOptions,
+  WebRTCConnectionEvent,
+  WebRTCCloseReason,
+  WebRTCPeerConnection,
+  WebRTCState,
+} from './types';
+
+interface Attempt {
+  controller: AbortController;
+  phase: WebRTCErrorPhase;
+  answered: boolean;
+  resolve: () => void;
+  reject: (error: WebRTCError) => void;
+  cleanup: () => void;
+}
+
+/** Browser-native WebRTC negotiation with application-owned SDP signaling. */
+export class WebRTCConnection<ClientEvent, ServerEvent extends { type: string }> {
+  /** Native peer connection; configure application-owned media before connect(). */
+  readonly peerConnection: BrowserPeerConnection;
+  /** Native ordered, reliable channel carrying protocol events. */
+  readonly dataChannel: BrowserDataChannel;
+  private readonly peer: WebRTCPeerConnection;
+  private readonly adapter: DataChannel<ClientEvent, ServerEvent>;
+  private readonly connectionEvents = new Subscriptions<WebRTCConnectionEvent>();
+  private currentState: WebRTCState = 'new';
+  private attempt: Attempt | undefined;
+
+  /** Creates native resources, but does not request media, contact a server, or begin negotiation. */
+  constructor(configuration?: WebRTCConfiguration) {
+    const host = globalThis as typeof globalThis & {
+      RTCPeerConnection?: new (configuration?: WebRTCConfiguration) => WebRTCPeerConnection;
+    };
+    if (!host.RTCPeerConnection) {
+      throw new WebRTCError(
+        'unsupported_environment',
+        'transport',
+        'WebRTC requires a browser with RTCPeerConnection.',
+      );
+    }
+    const peer = new host.RTCPeerConnection(configuration);
+    try {
+      this.adapter = new DataChannel(peer.createDataChannel('oai-events'));
+    } catch (error) {
+      peer.close();
+      throw new WebRTCError(
+        'negotiation_failed',
+        'transport',
+        'Could not create the WebRTC data channel.',
+        error,
+      );
+    }
+    this.peer = peer;
+    this.peerConnection = peer as BrowserPeerConnection;
+    this.dataChannel = this.adapter.dataChannel;
+    peer.addEventListener('connectionstatechange', this.onPeerState);
+    this.adapter.onConnectionEvent(this.onChannelEvent);
+  }
+
+  /** Current state, including before subscriptions are registered; notifications are not replayed. */
+  get state(): WebRTCState {
+    return this.currentState;
+  }
+
+  /** Subscribes to one server event type with its generated payload; returns an independent unsubscribe function. */
+  on<Type extends ServerEvent['type']>(
+    type: Type,
+    handler: (event: Extract<ServerEvent, { type: Type }>) => unknown,
+  ): () => void {
+    return this.adapter.on(type, handler);
+  }
+
+  /** Subscribes before connecting so initial server events are observable. API errors remain protocol data. */
+  onEvent(handler: (event: ServerEvent) => unknown): () => void {
+    return this.adapter.onEvent(handler);
+  }
+
+  /** Subscribes to local diagnostics and lifecycle. Setup failures reject connect() instead of emitting errors here. */
+  onConnectionEvent(handler: (event: WebRTCConnectionEvent) => unknown): () => void {
+    if (this.currentState === 'closed') {
+      throw new WebRTCError('invalid_state', 'transport', 'The WebRTC connection is closed.');
+    }
+    return this.connectionEvents.add(handler);
+  }
+
+  /** Sends without buffering; returning means local submission, not server acceptance. */
+  send(event: ClientEvent): void {
+    this.adapter.send(event);
+  }
+
+  /** Negotiates once and waits for both native connection and data-channel readiness. Defaults to a 30-second deadline. */
+  connect(options: WebRTCConnectOptions): Promise<void> {
+    if (this.currentState !== 'new') {
+      return Promise.reject(
+        new WebRTCError('invalid_state', 'transport', 'connect() may only be called once per connection.'),
+      );
+    }
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+      return Promise.reject(
+        new WebRTCError('invalid_state', 'transport', 'timeoutMs must be a positive finite timer duration.'),
+      );
+    }
+    const controller = new AbortController();
+    // oxlint-disable-next-line promise/avoid-new -- Native readiness, timeout, and abort events settle one connection attempt.
+    const result = new Promise<void>((resolve, reject) => {
+      const onAbort = () =>
+        this.failSetup(
+          new WebRTCError(
+            'aborted',
+            this.attempt?.phase ?? 'offer',
+            'WebRTC setup was cancelled.',
+            options.signal?.reason,
+          ),
+          'aborted',
+        );
+      const timer = setTimeout(
+        () =>
+          this.failSetup(
+            new WebRTCError('timeout', this.attempt?.phase ?? 'offer', 'WebRTC setup timed out.'),
+            'timeout',
+          ),
+        timeoutMs,
+      );
+      this.attempt = {
+        controller,
+        phase: 'offer',
+        answered: false,
+        resolve,
+        reject,
+        cleanup: () => {
+          clearTimeout(timer);
+          options.signal?.removeEventListener('abort', onAbort);
+        },
+      };
+      this.currentState = 'connecting';
+      options.signal?.addEventListener('abort', onAbort, { once: true });
+      if (options.signal?.aborted) {
+        onAbort();
+        return;
+      }
+      this.connectionEvents.emit({ type: 'state.changed', state: 'connecting' });
+    });
+    const { attempt } = this;
+    if (attempt) {
+      void this.negotiate(options, attempt);
+    }
+    return result;
+  }
+
+  /** Idempotently closes owned native resources. It never stops application-supplied media tracks. */
+  close(): void {
+    if (this.attempt) {
+      this.failSetup(
+        new WebRTCError('aborted', this.attempt.phase, 'WebRTC setup was closed by the application.'),
+        'local',
+      );
+    } else {
+      this.finish('local');
+    }
+  }
+
+  private async negotiate(options: WebRTCConnectOptions, attempt: Attempt): Promise<void> {
+    try {
+      const offer = await this.peer.createOffer();
+      if (this.attempt !== attempt) {
+        return;
+      }
+      await this.peer.setLocalDescription(offer);
+      if (this.attempt !== attempt) {
+        return;
+      }
+      const sdp = this.peer.localDescription?.sdp;
+      if (!sdp) {
+        throw new Error('The local description has no SDP.');
+      }
+      attempt.phase = 'signaling';
+      const answer = await options.exchangeSdp(sdp, { signal: attempt.controller.signal });
+      if (this.attempt !== attempt) {
+        return;
+      }
+      if (typeof answer !== 'string' || answer.length === 0) {
+        throw new TypeError('The SDP callback must return a nonempty string.');
+      }
+      attempt.phase = 'answer';
+      await this.peer.setRemoteDescription({ type: 'answer', sdp: answer });
+      if (this.attempt !== attempt) {
+        return;
+      }
+      attempt.answered = true;
+      attempt.phase = 'transport';
+      this.checkReady();
+    } catch (error) {
+      if (this.attempt !== attempt) {
+        return;
+      }
+      this.failSetup(
+        new WebRTCError(
+          attempt.phase === 'signaling' ? 'signaling_failed' : 'negotiation_failed',
+          attempt.phase,
+          'Could not establish the WebRTC connection.',
+          error,
+        ),
+        'failed',
+      );
+    }
+  }
+
+  private checkReady(): void {
+    const { attempt } = this;
+    if (
+      !attempt?.answered ||
+      this.peer.connectionState !== 'connected' ||
+      this.dataChannel.readyState !== 'open'
+    ) {
+      return;
+    }
+    this.attempt = undefined;
+    attempt.cleanup();
+    this.currentState = 'connected';
+    attempt.resolve();
+    this.connectionEvents.emit({ type: 'state.changed', state: 'connected' });
+  }
+
+  private failSetup(error: WebRTCError, reason: WebRTCCloseReason): void {
+    const { attempt } = this;
+    if (!attempt) {
+      return;
+    }
+    this.attempt = undefined;
+    attempt.cleanup();
+    attempt.reject(error);
+    // Change state and detach first: abort callbacks cannot resurrect setup.
+    this.finish(reason);
+    attempt.controller.abort(error);
+  }
+
+  private finish(reason: WebRTCCloseReason, error?: WebRTCError): void {
+    if (this.currentState === 'closed') {
+      return;
+    }
+    this.currentState = 'closed';
+    this.peer.removeEventListener('connectionstatechange', this.onPeerState);
+    this.adapter.dispose();
+    this.peer.close();
+    if (error) {
+      this.connectionEvents.emit({ type: 'error', error, fatal: true });
+    }
+    this.connectionEvents.emit({ type: 'closed', reason });
+    this.connectionEvents.clear();
+  }
+
+  private readonly onPeerState = (): void => {
+    if (this.currentState === 'closed') {
+      return;
+    }
+    if (this.peer.connectionState === 'failed' || this.peer.connectionState === 'closed') {
+      const failed = this.peer.connectionState === 'failed';
+      const error = new WebRTCError(
+        failed ? 'transport_failed' : 'connection_closed',
+        'transport',
+        'The WebRTC peer connection ended.',
+      );
+      if (this.attempt) {
+        this.failSetup(error, failed ? 'failed' : 'remote');
+      } else {
+        this.finish(failed ? 'failed' : 'remote', failed ? error : undefined);
+      }
+    } else {
+      this.checkReady();
+    }
+  };
+
+  private readonly onChannelEvent = (event: WebRTCConnectionEvent): void => {
+    if (this.currentState === 'closed') {
+      return;
+    }
+    if (event.type === 'closed') {
+      if (this.attempt) {
+        this.failSetup(
+          new WebRTCError('connection_closed', 'transport', 'The data channel closed during setup.'),
+          'remote',
+        );
+      } else {
+        this.finish('remote');
+      }
+    } else if (event.type === 'error') {
+      if (event.error.phase === 'transport') {
+        if (this.attempt) {
+          this.failSetup(event.error, 'failed');
+        } else {
+          this.finish('failed', event.error);
+        }
+      } else {
+        this.connectionEvents.emit(event);
+      }
+    } else {
+      this.checkReady();
+    }
+  };
+}

package/src/lib/webrtc/data-channel.ts

@@ -0,0 +1,144 @@
+import { WebRTCError } from './errors';
+import { Subscriptions } from './subscriptions';
+import type { BrowserDataChannel, WebRTCConnectionEvent, WebRTCDataChannel } from './types';
+
+/** Typed protocol messages on an application-owned native RTCDataChannel. */
+export class DataChannel<ClientEvent, ServerEvent extends { type: string }> {
+  /** The borrowed native channel. dispose() never closes it. */
+  readonly dataChannel: BrowserDataChannel;
+  private readonly channel: WebRTCDataChannel;
+  private readonly events = new Subscriptions<ServerEvent>();
+  private readonly connectionEvents = new Subscriptions<WebRTCConnectionEvent>();
+  private disposed = false;
+
+  /** Attaches listeners without negotiating, opening, or taking ownership of the channel. */
+  constructor(channel: WebRTCDataChannel) {
+    this.channel = channel;
+    this.dataChannel = channel as BrowserDataChannel;
+    channel.addEventListener('message', this.onMessage);
+    channel.addEventListener('error', this.onError);
+    channel.addEventListener('open', this.onOpen);
+    channel.addEventListener('close', this.onClose);
+  }
+
+  /** Subscribes to one server event type with its generated payload; returns an independent unsubscribe function. */
+  on<Type extends ServerEvent['type']>(
+    type: Type,
+    handler: (event: Extract<ServerEvent, { type: Type }>) => unknown,
+  ): () => void {
+    this.assertActive();
+    // The shared dispatcher matches the original discriminator before invoking this callback.
+    return this.events.add((event) => handler(event as Extract<ServerEvent, { type: Type }>), type);
+  }
+
+  /** Subscribes to future server events, including raw API errors; returns an unsubscribe function. */
+  onEvent(handler: (event: ServerEvent) => unknown): () => void {
+    this.assertActive();
+    return this.events.add(handler);
+  }
+
+  /** Observes only this channel's local errors and lifecycle, not its owning peer connection. */
+  onConnectionEvent(handler: (event: WebRTCConnectionEvent) => unknown): () => void {
+    this.assertActive();
+    return this.connectionEvents.add(handler);
+  }
+
+  /** Sends immediately on an open channel. Throws on local failure; API acceptance is reported by server events. */
+  send(event: ClientEvent): void {
+    this.assertActive();
+    if (this.channel.readyState !== 'open') {
+      throw new WebRTCError('not_open', 'send', 'The WebRTC data channel is not open.');
+    }
+    try {
+      const data = JSON.stringify(event);
+      if (data === undefined) {
+        throw new TypeError('The event is not JSON serializable.');
+      }
+      this.channel.send(data);
+    } catch (error) {
+      throw new WebRTCError('send_failed', 'send', 'Could not send the WebRTC event.', error);
+    }
+  }
+
+  /** Detaches all SDK listeners and subscriptions, without closing the channel or stopping tracks. */
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.channel.removeEventListener('message', this.onMessage);
+    this.channel.removeEventListener('error', this.onError);
+    this.channel.removeEventListener('open', this.onOpen);
+    this.channel.removeEventListener('close', this.onClose);
+    this.events.clear();
+    this.connectionEvents.clear();
+  }
+
+  private assertActive(): void {
+    if (this.disposed) {
+      throw new WebRTCError('invalid_state', 'transport', 'The WebRTC data-channel adapter is disposed.');
+    }
+  }
+
+  private readonly onMessage = (message: unknown): void => {
+    if (this.disposed) {
+      return;
+    }
+    let event: unknown;
+    try {
+      const { data } = message as { data?: unknown };
+      if (typeof data !== 'string') {
+        throw new TypeError('Invalid protocol message.');
+      }
+      event = JSON.parse(data);
+      if (
+        typeof event !== 'object' ||
+        event === null ||
+        Array.isArray(event) ||
+        typeof Object.getOwnPropertyDescriptor(event, 'type')?.value !== 'string'
+      ) {
+        throw new TypeError('Invalid protocol message.');
+      }
+    } catch {
+      // JSON SyntaxErrors can contain the payload. Do not retain their cause.
+      this.connectionEvents.emit({
+        type: 'error',
+        fatal: false,
+        error: new WebRTCError('invalid_message', 'message', 'Received an invalid WebRTC protocol message.'),
+      });
+      return;
+    }
+    // Like the generated SDK, accept future event types without a runtime schema registry.
+    this.events.emit(event as ServerEvent);
+  };
+
+  private readonly onError = (cause: unknown): void => {
+    if (this.disposed) {
+      return;
+    }
+    this.connectionEvents.emit({
+      type: 'error',
+      fatal: false,
+      error: new WebRTCError(
+        'transport_failed',
+        'transport',
+        'The WebRTC data channel reported an error.',
+        cause,
+      ),
+    });
+  };
+
+  private readonly onOpen = (): void => {
+    if (!this.disposed) {
+      this.connectionEvents.emit({ type: 'state.changed', state: 'connected' });
+    }
+  };
+
+  private readonly onClose = (): void => {
+    if (this.disposed) {
+      return;
+    }
+    this.connectionEvents.emit({ type: 'closed', reason: 'remote' });
+    this.dispose();
+  };
+}

package/src/lib/webrtc/errors.ts

@@ -0,0 +1,38 @@
+import { OpenAIError } from '../../core/error';
+
+/** Stable classifications of local WebRTC failures, independent of API error codes. */
+export type WebRTCErrorCode =
+  | 'invalid_state'
+  | 'not_open'
+  | 'send_failed'
+  | 'invalid_message'
+  | 'signaling_failed'
+  | 'negotiation_failed'
+  | 'transport_failed'
+  | 'connection_closed'
+  | 'timeout'
+  | 'aborted'
+  | 'unsupported_environment';
+
+/** The operation in which a local error originated. */
+export type WebRTCErrorPhase = 'offer' | 'signaling' | 'answer' | 'transport' | 'message' | 'send';
+
+/** A local SDK/transport failure. Server error events remain unchanged in onEvent(). */
+export class WebRTCError extends OpenAIError {
+  /** Distinguishes this error from API errors and application callback exceptions. */
+  override readonly name = 'WebRTCError';
+  /** Stable failure classification, suitable for detecting expected cancellation. */
+  readonly code: WebRTCErrorCode;
+  /** The failing setup, transport, or message operation. */
+  readonly phase: WebRTCErrorPhase;
+  /** Original exception or abort reason. It may contain application-sensitive details; do not log blindly. */
+  readonly cause: unknown;
+
+  /** Creates a safe diagnostic while retaining the original cause separately. */
+  constructor(code: WebRTCErrorCode, phase: WebRTCErrorPhase, message: string, cause?: unknown) {
+    super(message);
+    this.code = code;
+    this.phase = phase;
+    this.cause = cause;
+  }
+}

package/src/lib/webrtc/subscriptions.ts

@@ -0,0 +1,62 @@
+function reportApplicationError(error: unknown): void {
+  const host = globalThis as typeof globalThis & { reportError?: (error: unknown) => void };
+  if (typeof host.reportError === 'function') {
+    host.reportError(error);
+  } else {
+    setTimeout(() => {
+      throw error;
+    }, 0);
+  }
+}
+
+async function observeResult(result: unknown): Promise<void> {
+  try {
+    await result;
+  } catch (error) {
+    reportApplicationError(error);
+  }
+}
+
+/** Internal callback subscriptions with optional discriminator filters; no buffering or replay. */
+export class Subscriptions<Event extends { type: string }> {
+  private readonly listeners = new Set<{
+    listener: (event: Event) => unknown;
+    type: Event['type'] | undefined;
+  }>();
+
+  /** Registers independently, including when the same function is supplied twice. */
+  add(listener: (event: Event) => unknown, type?: Event['type']): () => void {
+    const registration = { listener, type };
+    this.listeners.add(registration);
+    return () => {
+      this.listeners.delete(registration);
+    };
+  }
+
+  /** Delivers in registration order, isolating application exceptions from the transport. */
+  emit(event: Event): void {
+    const { type } = event;
+    const snapshot = [...this.listeners];
+    for (const registration of snapshot) {
+      if (
+        !this.listeners.has(registration) ||
+        (registration.type !== undefined && registration.type !== type)
+      ) {
+        continue;
+      }
+      try {
+        const result = registration.listener(event);
+        if (result !== null && (typeof result === 'object' || typeof result === 'function')) {
+          void observeResult(result);
+        }
+      } catch (error) {
+        reportApplicationError(error);
+      }
+    }
+  }
+
+  /** Releases all subscriber references. Existing unsubscribe functions remain safe. */
+  clear(): void {
+    this.listeners.clear();
+  }
+}

package/src/lib/webrtc/types.ts

@@ -0,0 +1,109 @@
+import type { WebRTCError } from './errors';
+
+/** A native event source, without requiring DOM declarations in server projects. */
+export interface WebRTCEventTarget {
+  /** Registers a native event listener. */
+  addEventListener: (type: string, listener: (event: unknown) => void) => void;
+  /** Removes a previously registered native event listener. */
+  removeEventListener: (type: string, listener: (event: unknown) => void) => void;
+}
+
+/** The subset of a native data channel used by the SDK. */
+export interface WebRTCDataChannel extends WebRTCEventTarget {
+  /** Native channel readiness; sending requires `open`. */
+  readonly readyState: string;
+  /** Sends one serialized protocol message. */
+  send: (data: string) => void;
+  /** Closes this channel. Borrowed adapters never call this method. */
+  close: () => void;
+}
+
+/** The subset of a native peer connection used by negotiation. */
+export interface WebRTCPeerConnection extends WebRTCEventTarget {
+  /** Native connection state, including transient `disconnected` states. */
+  readonly connectionState: string;
+  /** The local description after `setLocalDescription`. */
+  readonly localDescription: { readonly sdp: string } | null;
+  /** Creates the protocol data channel before generating an SDP offer. */
+  createDataChannel: (label: string) => WebRTCDataChannel;
+  /** Generates the local SDP offer. */
+  createOffer: () => Promise<{ type: 'answer' | 'offer' | 'pranswer' | 'rollback'; sdp?: string }>;
+  /** Applies the offer to the local peer. */
+  setLocalDescription: (description: {
+    type?: 'answer' | 'offer' | 'pranswer' | 'rollback';
+    sdp?: string;
+  }) => Promise<void>;
+  /** Applies the application's SDP answer. */
+  setRemoteDescription: (description: { type: 'answer'; sdp: string }) => Promise<void>;
+  /** Releases the peer connection, without stopping application-owned tracks. */
+  close: () => void;
+}
+
+/** Native browser peer type when DOM types are available; otherwise the SDK's minimal view. */
+export type BrowserPeerConnection = typeof globalThis extends {
+  RTCPeerConnection: { prototype: infer Peer };
+}
+  ? Peer
+  : WebRTCPeerConnection;
+
+/** Native browser channel type when DOM types are available. */
+export type BrowserDataChannel = typeof globalThis extends {
+  RTCDataChannel: { prototype: infer Channel };
+}
+  ? Channel
+  : WebRTCDataChannel;
+
+/** Standard RTCConfiguration in a browser project; no runtime polyfill is installed. */
+export type WebRTCConfiguration = typeof globalThis extends {
+  RTCPeerConnection: new (configuration?: infer Configuration) => unknown;
+}
+  ? Configuration
+  : object;
+
+/** Exchanges a local SDP offer for an SDP answer using application-owned signaling. */
+export type ExchangeSdp = (
+  offer: string,
+  options: {
+    /** Aborted when setup is cancelled, times out, or fails; pass it to fetch. */
+    signal: AbortSignal;
+  },
+) => Promise<string>;
+
+/** Options for one connection attempt. No retries or reconnection are performed. */
+export interface WebRTCConnectOptions {
+  /** Application callback that submits the offer and returns the SDP answer. */
+  exchangeSdp: ExchangeSdp;
+  /** Cancels setup only. After connection succeeds, use close() to end the connection. */
+  signal?: AbortSignal;
+  /** Total setup deadline in milliseconds; defaults to 30,000. Must be positive and finite. */
+  timeoutMs?: number;
+}
+
+/** SDK connection state. A closed instance cannot be connected again. */
+export type WebRTCState = 'new' | 'connecting' | 'connected' | 'closed';
+
+/** Why a connection ended. Setup failures are also returned by connect(). */
+export type WebRTCCloseReason = 'local' | 'remote' | 'failed' | 'aborted' | 'timeout';
+
+/** Local lifecycle and diagnostics, separate from server protocol events. */
+export type WebRTCConnectionEvent =
+  | {
+      /** A connection became usable or began setup. */
+      type: 'state.changed';
+      /** The new state. There is no replay on subscription. */
+      state: 'connecting' | 'connected';
+    }
+  | {
+      /** An unsolicited local failure, not an API error event. */
+      type: 'error';
+      /** The local diagnostic. Messages never contain raw protocol payloads. */
+      error: WebRTCError;
+      /** Whether the managed helper is ending this connection. */
+      fatal: boolean;
+    }
+  | {
+      /** The connection ended; emitted at most once. */
+      type: 'closed';
+      /** Whether closure was requested, observed, or caused by a setup/transport failure. */
+      reason: WebRTCCloseReason;
+    };

package/src/live/webrtc.ts

@@ -0,0 +1,10 @@
+export { OpenAILiveWebRTC, LiveDataChannel, WebRTCError } from '../lib/live/webrtc';
+export type {
+  ExchangeSdp,
+  WebRTCConnectOptions,
+  WebRTCConnectionEvent,
+  WebRTCConfiguration,
+  WebRTCErrorCode,
+  WebRTCErrorPhase,
+  WebRTCState,
+} from '../lib/live/webrtc';

package/src/realtime/webrtc.ts

@@ -0,0 +1,10 @@
+export { OpenAIRealtimeWebRTC, RealtimeDataChannel, WebRTCError } from '../lib/realtime/webrtc';
+export type {
+  ExchangeSdp,
+  WebRTCConnectOptions,
+  WebRTCConnectionEvent,
+  WebRTCConfiguration,
+  WebRTCErrorCode,
+  WebRTCErrorPhase,
+  WebRTCState,
+} from '../lib/realtime/webrtc';