@rebyteai/agent-sdk 0.2.0

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/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';