@guava-ai/guava-sdk 0.37.0 → 0.38.0

package/src/sip.ts

@@ -0,0 +1,62 @@
+// Characters allowed unescaped in each component beyond RFC 3261's `unreserved`,
+// which encodeURIComponent already leaves alone. See RFC 3261 section 25.1.
+const USER_SAFE = "&=+$,;?/";
+const PARAM_SAFE = "[]/:&+$";
+const HEADER_SAFE = "[]/?:+$";
+
+function sipEscape(value: string, safe: string): string {
+  return encodeURIComponent(value).replace(/%[0-9A-F]{2}/g, (escaped) => {
+    // Not decodeURIComponent, which throws on single bytes of multibyte UTF-8 sequences.
+    const char = String.fromCharCode(Number.parseInt(escaped.slice(1), 16));
+    return safe.includes(char) ? char : escaped;
+  });
+}
+
+export class SipUri {
+  host: string;
+  user?: string;
+  /** A `null` value renders as a valueless param, e.g. `;lr`. */
+  uriParams: Record<string, string | null>;
+  /** A `null` value renders as a valueless header, e.g. `?X-Foo=`. */
+  headers: Record<string, string | null>;
+
+  constructor(args: {
+    host: string;
+    user?: string;
+    uriParams?: Record<string, string | null>;
+    headers?: Record<string, string | null>;
+  }) {
+    this.host = args.host;
+    this.user = args.user;
+    this.uriParams = args.uriParams ?? {};
+    this.headers = args.headers ?? {};
+  }
+
+  toString(): string {
+    let url = "sip:";
+    if (this.user !== undefined) {
+      url += `${sipEscape(this.user, USER_SAFE)}@`;
+    }
+    url += this.host;
+
+    for (const [name, value] of Object.entries(this.uriParams)) {
+      url += `;${sipEscape(name, PARAM_SAFE)}`;
+      if (value !== null) {
+        url += `=${sipEscape(value, PARAM_SAFE)}`;
+      }
+    }
+
+    // Headers always need an "=", so a null value renders as "name=".
+    const headers = Object.entries(this.headers);
+    if (headers.length > 0) {
+      url += `?${headers
+        .map(
+          ([name, value]) =>
+            `${sipEscape(name, HEADER_SAFE)}=${sipEscape(value === null ? "" : String(value), HEADER_SAFE)}`,
+        )
+        .join("&")}`;
+    }
+
+    return url;
+  }
+}

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.37.0";
+export const SDK_VERSION = "0.38.0";

package/src/webrtc/index.ts

@@ -0,0 +1,372 @@
+import { type ConnectingTone, JingleTone } from "./tones.ts";
+
+export { type ConnectingTone, JingleTone, RingbackTone } from "./tones.ts";
+
+export type CallState =
+  | "not-started" // start() hasn't been called yet.
+  | "starting" // Starting the call. Do not play a Ringback yet.
+  | "waiting-for-permission" // We're waiting for the Microphone permission prompt. You may show a reminder UI here.
+  | "connecting" // The call is now connection to the remote. This is where you can play a ringback or other connecting tone.
+  | "connected" // The call is now connected and the audio channel is established.
+  | "ended"; // The call has ended.
+
+export type CallErrorCode =
+  | "MICROPHONE_ACCESS_FAILED"
+  | "CONNECTION_FAILED"
+  | "AUTHENTICATION_FAILED"
+  | "PROTOCOL_ERROR" // The server sent an unexpected message.
+  | "SERVER_ERROR" // The server sent an error message.
+  | "REMOTE_HANGUP"; // The remote hung up before the call connected.
+
+export class CallError extends Error {
+  readonly code: CallErrorCode;
+
+  constructor(code: CallErrorCode, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CallError";
+    this.code = code;
+  }
+}
+
+// Used if the server doesn't send ICE servers with the auth reply.
+const DEFAULT_ICE_SERVERS: RTCIceServer[] = [
+  { urls: ["stun:stun.l.google.com:19302", "stun:stun.sipgate.net:10000"] },
+];
+
+const SOCKET_PROTOCOLS: Record<string, string> = {
+  "http:": "ws:",
+  "https:": "wss:",
+  "ws:": "ws:",
+  "wss:": "wss:",
+};
+
+// Messages received on the signaling socket. See junkswitch/junkswitch/webrtcsocket.py.
+type SignalingMessage =
+  | {
+      type: "auth";
+      body: "OK" | "FAIL";
+      reason?: string;
+      ice_servers?: RTCIceServer[];
+    }
+  | { type: "desc"; body: RTCSessionDescriptionInit }
+  | { type: "candidate"; body: RTCIceCandidateInit }
+  | { type: "hangup" }
+  | { type: "error"; body?: string }
+  | { type: "transfer" };
+
+export class Call {
+  private _state: CallState = "not-started";
+  private _error?: CallError;
+  private readonly _stateHandlers = new Set<(state: CallState) => void>();
+  private readonly _remoteStreamHandlers = new Set<(stream: MediaStream) => void>();
+  private readonly _webrtcCode: string;
+  private readonly _sockUrl: URL;
+  private readonly _remoteAudio: HTMLAudioElement;
+  private readonly _connectingTone?: ConnectingTone;
+  private _sock?: WebSocket;
+  private _localStream?: MediaStream;
+  private _peerConnection?: RTCPeerConnection;
+  private _remoteStream?: MediaStream;
+  private _iceServers?: RTCIceServer[];
+  // Settles the promise returned by start().
+  private _pendingStart?: { resolve: () => void; reject: (error: CallError) => void };
+
+  constructor({
+    webrtcCode,
+    baseUrl = "https://app.goguava.ai/",
+    connectingTone = new JingleTone(),
+  }: {
+    webrtcCode: string;
+    baseUrl?: string;
+    // Played while the call is in the "connecting" state.
+    connectingTone?: ConnectingTone | "disabled";
+  }) {
+    this._webrtcCode = webrtcCode;
+    if (connectingTone !== "disabled") {
+      this._connectingTone = connectingTone;
+    }
+
+    this._sockUrl = new URL("/webrtc/", baseUrl);
+    const sockProtocol = SOCKET_PROTOCOLS[this._sockUrl.protocol];
+    if (sockProtocol === undefined) {
+      throw new Error(`Unsupported baseUrl protocol: ${this._sockUrl.protocol}`);
+    }
+    this._sockUrl.protocol = sockProtocol;
+
+    this._remoteAudio = document.createElement("audio");
+    this._remoteAudio.autoplay = true;
+  }
+
+  get state(): CallState {
+    return this._state;
+  }
+
+  // Set if the call ended due to a failure.
+  get error(): CallError | undefined {
+    return this._error;
+  }
+
+  // Set once the remote audio track arrives, which happens before the call reaches "connected".
+  get remoteStream(): MediaStream | undefined {
+    return this._remoteStream;
+  }
+
+  // Returns a function that unregisters the handler.
+  onStateChange(handler: (state: CallState) => void): () => void {
+    this._stateHandlers.add(handler);
+    return () => {
+      this._stateHandlers.delete(handler);
+    };
+  }
+
+  // Fires whenever the remote stream is replaced, including the first time it arrives.
+  // Returns a function that unregisters the handler.
+  onRemoteStream(handler: (stream: MediaStream) => void): () => void {
+    this._remoteStreamHandlers.add(handler);
+    return () => {
+      this._remoteStreamHandlers.delete(handler);
+    };
+  }
+
+  private _setState(state: CallState) {
+    if (state === this._state) {
+      return;
+    }
+    this._state = state;
+    if (state === "connecting") {
+      this._connectingTone?.start();
+    } else {
+      this._connectingTone?.stop();
+    }
+    for (const handler of this._stateHandlers) {
+      handler(state);
+    }
+  }
+
+  async start() {
+    if (this._state !== "not-started") {
+      throw new Error(`start() was already called.`);
+    }
+    this._setState("starting");
+
+    // Add the audio element.
+    document.body.appendChild(this._remoteAudio);
+
+    // We start by requesting device permissions first. The idea is that, after permission has been granted,
+    // it makes sence to play a ringback, but it doesn't make sense to do so during the permission prompt.
+
+    const permissionTimer = setTimeout(() => {
+      this._setState("waiting-for-permission");
+    }, 500);
+
+    try {
+      this._localStream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
+    } catch (error) {
+      const callError = new CallError("MICROPHONE_ACCESS_FAILED", "Failed to access microphone.", {
+        cause: error,
+      });
+      this._end(callError);
+      throw callError;
+    } finally {
+      clearTimeout(permissionTimer);
+    }
+
+    // hangup() was called during the permission prompt.
+    if (this.state === "ended") {
+      this._teardown();
+      return;
+    }
+
+    // Now open and authenticate the signaling socket.
+    this._setState("connecting"); // UI can start playing rinback tones here.
+    const started = new Promise<void>((resolve, reject) => {
+      this._pendingStart = { resolve, reject };
+    });
+
+    this._sock = new WebSocket(this._sockUrl);
+    this._sock.onopen = () => {
+      this._send({ type: "auth", body: this._webrtcCode });
+    };
+    this._sock.onmessage = (event) => {
+      this._onMessage(JSON.parse(event.data) as SignalingMessage);
+    };
+    this._sock.onclose = () => {
+      this._end(new CallError("CONNECTION_FAILED", "Signaling connection closed."));
+    };
+
+    await started;
+  }
+
+  async hangup() {
+    if (this._state === "not-started") {
+      throw new Error(`hangup() called before start().`);
+    }
+    if (this._state === "ended") {
+      return;
+    }
+    this._send({ type: "hangup" });
+    this._end();
+  }
+
+  private _send(message: { type: string; body?: unknown }) {
+    if (this._sock !== undefined && this._sock.readyState === WebSocket.OPEN) {
+      this._sock.send(JSON.stringify(message));
+    }
+  }
+
+  private _onMessage(message: SignalingMessage) {
+    switch (message.type) {
+      case "auth":
+        if (message.body !== "OK") {
+          this._end(
+            new CallError("AUTHENTICATION_FAILED", message.reason || "Authentication failed."),
+          );
+          return;
+        }
+        this._iceServers = message.ice_servers;
+        this._send({ type: "connect", body: {} });
+        void this._connectPeer();
+        break;
+      case "desc":
+        if (!this._peerConnection) {
+          this._end(
+            new CallError(
+              "PROTOCOL_ERROR",
+              "Received desc before the peer connection was created.",
+            ),
+          );
+          return;
+        }
+        this._peerConnection.setRemoteDescription(message.body).catch((error) => {
+          this._end(
+            new CallError("CONNECTION_FAILED", "Failed to set remote description.", {
+              cause: error,
+            }),
+          );
+        });
+        break;
+      case "candidate":
+        if (!this._peerConnection) {
+          this._end(
+            new CallError(
+              "PROTOCOL_ERROR",
+              "Received candidate before the peer connection was created.",
+            ),
+          );
+          return;
+        }
+        this._peerConnection.addIceCandidate(message.body).catch((error) => {
+          console.warn("Failed to add ICE candidate:", error);
+        });
+        break;
+      case "hangup":
+        if (this._state === "connected") {
+          this._end();
+        } else {
+          this._end(
+            new CallError("REMOTE_HANGUP", "The remote hung up before the call connected."),
+          );
+        }
+        break;
+      case "error":
+        this._end(new CallError("SERVER_ERROR", message.body || "Unknown server error."));
+        break;
+      case "transfer":
+        this._end(new CallError("PROTOCOL_ERROR", "Transfers are not supported."));
+        break;
+      default:
+        console.warn("Unknown signaling message:", message);
+    }
+  }
+
+  private async _connectPeer() {
+    if (!this._localStream) {
+      return;
+    }
+    this._peerConnection = new RTCPeerConnection({
+      iceServers: this._iceServers ?? DEFAULT_ICE_SERVERS,
+    });
+    this._peerConnection.onicecandidate = (event) => {
+      if (event.candidate) {
+        this._send({ type: "candidate", body: event.candidate });
+      }
+    };
+    this._peerConnection.ontrack = (event) => {
+      this._remoteStream = new MediaStream([event.track]);
+      this._remoteAudio.srcObject = this._remoteStream;
+      for (const handler of this._remoteStreamHandlers) {
+        handler(this._remoteStream);
+      }
+    };
+    this._peerConnection.onconnectionstatechange = () => {
+      if (this._peerConnection === undefined) {
+        return;
+      }
+      // "disconnected" is often transient, so wait for "failed" before ending the call.
+      if (this._peerConnection.connectionState === "connected") {
+        this._setState("connected");
+        if (this._pendingStart !== undefined) {
+          this._pendingStart.resolve();
+          this._pendingStart = undefined;
+        }
+      } else if (this._peerConnection.connectionState === "failed") {
+        this._end(new CallError("CONNECTION_FAILED", "Peer connection failed."));
+      }
+    };
+    for (const track of this._localStream.getAudioTracks()) {
+      this._peerConnection.addTrack(track);
+    }
+
+    try {
+      await this._peerConnection.setLocalDescription();
+    } catch (error) {
+      this._end(new CallError("CONNECTION_FAILED", "Failed to create offer.", { cause: error }));
+      return;
+    }
+
+    // The call may have ended while creating the offer.
+    if (this.state === "ended") {
+      return;
+    }
+    this._send({ type: "desc", body: this._peerConnection.localDescription });
+  }
+
+  private _end(error?: CallError) {
+    if (this._state === "ended") {
+      return;
+    }
+    this._error = error;
+    this._teardown();
+    this._setState("ended");
+
+    // If start() is still pending, it rejects on failure and resolves on hangup().
+    if (this._pendingStart !== undefined) {
+      if (error) {
+        this._pendingStart.reject(error);
+      } else {
+        this._pendingStart.resolve();
+      }
+      this._pendingStart = undefined;
+    }
+  }
+
+  private _teardown() {
+    if (this._sock) {
+      // Don't fire close handlers for a socket we closed ourselves.
+      this._sock.onclose = null;
+      this._sock.close();
+      this._sock = undefined;
+    }
+    if (this._peerConnection !== undefined) {
+      this._peerConnection.close();
+      this._peerConnection = undefined;
+    }
+    for (const track of this._localStream?.getTracks() ?? []) {
+      track.stop();
+    }
+    this._localStream = undefined;
+    this._remoteStream = undefined;
+    this._remoteAudio.srcObject = null;
+    this._remoteAudio.remove();
+  }
+}

package/src/webrtc/tones.ts

@@ -0,0 +1,200 @@
+// Seconds from the start of bar 0 to the given 0-indexed beat.
+function beatTime(beat: number, bpm: number): number {
+  return beat * (60 / bpm);
+}
+
+export interface ConnectingTone {
+  start(): void;
+  stop(): void;
+}
+
+// North American ringback: 440 + 480 Hz, 2s on, 4s off.
+export class RingbackTone implements ConnectingTone {
+  private context: AudioContext | null = null;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+
+  private readonly volume = 0.15;
+  private readonly onSeconds = 2;
+  private readonly periodSeconds = 6;
+  // Delay before the first ring, so near-instant connections stay silent.
+  private readonly startDelay = 0.3;
+
+  start(): void {
+    if (this.context) return;
+
+    const context = new AudioContext();
+    const gain = context.createGain();
+    gain.gain.value = 0;
+    gain.connect(context.destination);
+
+    for (const frequency of [440, 480]) {
+      const oscillator = context.createOscillator();
+      oscillator.frequency.value = frequency;
+      oscillator.connect(gain);
+      oscillator.start();
+    }
+
+    let nextRing = context.currentTime + this.startDelay;
+    const ring = () => {
+      gain.gain.setValueAtTime(this.volume, nextRing);
+      gain.gain.setValueAtTime(0, nextRing + this.onSeconds);
+      nextRing += this.periodSeconds;
+    };
+    ring();
+    this.intervalId = setInterval(ring, this.periodSeconds * 1000);
+    this.context = context;
+  }
+
+  stop(): void {
+    if (!this.context) return;
+
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    // Closing the context stops the oscillators.
+    void this.context.close();
+    this.context = null;
+  }
+}
+
+export class JingleTone implements ConnectingTone {
+  private context: AudioContext | null = null;
+  private masterGain: GainNode | null = null;
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private running = false;
+  private pulseCount = 0;
+  // Audio-clock time of the next bar to schedule.
+  private nextBarStart = 0;
+
+  // Configuration
+  private readonly volume = 0.25;
+  private readonly bpm = 120;
+  private readonly beatsPerBar = 4;
+  // Delay before the first note, so near-instant connections stay silent.
+  private readonly startDelay = 0.3;
+
+  start(): void {
+    if (this.running) return;
+
+    this.running = true;
+    this.pulseCount = 0;
+    this.context = new AudioContext();
+    this.masterGain = this.context.createGain();
+    this.masterGain.gain.value = this.volume;
+    this.masterGain.connect(this.context.destination);
+    this.nextBarStart = this.context.currentTime + this.startDelay;
+
+    // Stay one bar ahead so timer jitter doesn't shift the beat.
+    this.playPulse();
+    this.playPulse();
+
+    const barLength = beatTime(this.beatsPerBar, this.bpm);
+    this.intervalId = setInterval(() => {
+      this.playPulse();
+    }, barLength * 1000);
+  }
+
+  private noteToFrequency(note: string): number {
+    const match = note.match(/^([A-G])(#|b)?(-?\d+)$/);
+
+    if (!match) {
+      throw new Error(`Invalid note: ${note}`);
+    }
+
+    const [, name, accidental, octave] = match;
+
+    const semitones: Record<string, number> = {
+      C: 0,
+      D: 2,
+      E: 4,
+      F: 5,
+      G: 7,
+      A: 9,
+      B: 11,
+    };
+
+    const offset = accidental === "#" ? 1 : accidental === "b" ? -1 : 0;
+    const midi = (Number(octave) + 1) * 12 + semitones[name] + offset;
+
+    return 440 * Math.pow(2, (midi - 69) / 12);
+  }
+
+  stop(): void {
+    if (!this.running) return;
+
+    this.running = false;
+
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+
+    const context = this.context;
+    const gain = this.masterGain;
+
+    if (!context || !gain) return;
+
+    // Smooth fade-out
+    const now = context.currentTime;
+    gain.gain.setValueAtTime(gain.gain.value, now);
+    gain.gain.linearRampToValueAtTime(0, now + 0.15);
+
+    setTimeout(() => {
+      void context.close();
+    }, 200);
+
+    this.context = null;
+    this.masterGain = null;
+  }
+
+  private playPulse(): void {
+    if (!this.context || !this.masterGain) return;
+
+    const bar = this.nextBarStart;
+    const beat = (n: number) => bar + beatTime(n, this.bpm);
+    const beatLength = beatTime(1, this.bpm);
+
+    // Notes on beats 1-3, silence on beat 4.
+    if (this.pulseCount % 4 === 0 || this.pulseCount % 4 === 2) {
+      this.playNote("C5", beat(0), beatLength);
+      this.playNote("E5", beat(0.5), beatLength);
+      this.playNote("G4", beat(1), beatLength);
+    } else if (this.pulseCount % 4 === 3) {
+      this.playNote("E5", beat(0), beatLength);
+      this.playNote("G5", beat(0.5), beatLength);
+      this.playNote("C5", beat(1), beatLength);
+    } else {
+      this.playNote("E5", beat(0), beatLength);
+      this.playNote("G4", beat(0.5), beatLength);
+      this.playNote("C5", beat(1), beatLength);
+    }
+    this.pulseCount++;
+    this.nextBarStart = beat(this.beatsPerBar);
+  }
+
+  private playNote(note: string, startTime: number, duration: number): void {
+    if (!this.context || !this.masterGain) return;
+
+    const oscillator = this.context.createOscillator();
+    const envelope = this.context.createGain();
+
+    oscillator.type = "sine";
+    oscillator.frequency.value = this.noteToFrequency(note);
+
+    envelope.gain.setValueAtTime(0, startTime);
+    envelope.gain.linearRampToValueAtTime(0.7, startTime + 0.05);
+    envelope.gain.exponentialRampToValueAtTime(0.001, startTime + duration);
+
+    oscillator.connect(envelope);
+    envelope.connect(this.masterGain);
+
+    oscillator.start(startTime);
+    oscillator.stop(startTime + duration + 0.01);
+
+    oscillator.onended = () => {
+      oscillator.disconnect();
+      envelope.disconnect();
+    };
+  }
+}