@guava-ai/guava-sdk 0.36.0 → 0.38.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@guava-ai/guava-sdk",
   "description": "The official TypeScript SDK for building Guava voice agents.",
   "homepage": "https://docs.goguava.ai/typescript-sdk/",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "type": "commonjs",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -19,6 +19,10 @@
       "types": "./dist/src/helpers/openai.d.ts",
       "default": "./dist/src/helpers/openai.js"
     },
+    "./webrtc": {
+      "types": "./dist/src/webrtc/index.d.ts",
+      "default": "./dist/src/webrtc/index.js"
+    },
     "./example-data": {
       "types": "./dist/src/example-data.d.ts",
       "default": "./dist/src/example-data.js"
@@ -37,7 +41,9 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^25.0.7",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.28.2",
     "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.5.2",
     "openai": "^6.16.0",
     "ts-jest": "^29.4.11",
     "tsx": "^4.21.0",
@@ -70,17 +76,27 @@
     "test:e2e": "jest --config jest.e2e.config.cjs",
     "check": "npm run typecheck && npm audit --omit=dev && npm run lint && npm run check-format",
     "clean": "rm -rf ./dist",
-    "build": "tsx scripts/update-version.ts && tsc && chmod +x ./dist/bin/example-runner.js",
+    "build": "tsx scripts/update-version.ts && tsc && chmod +x ./dist/bin/example-runner.js && npm run build-webrtc && tsx scripts/update-readme.ts",
+    "build-webrtc": "npm run build-webrtc:esm && npm run build-webrtc:iife",
+    "build-webrtc:esm": "esbuild src/webrtc/index.ts --bundle --minify --sourcemap --target=es2020 --format=esm --outfile=dist/guava-webrtc.esm.min.js",
+    "build-webrtc:iife": "esbuild src/webrtc/index.ts --bundle --minify --sourcemap --target=es2020 --format=iife --global-name=Guava --outfile=dist/guava-webrtc.min.js",
     "prepare": "npm run clean && npm run build",
     "release": "npm publish --ignore-scripts=false"
   },
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "files": [
     "/src",
     "/dist",
     "/examples",
     "/bin"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goguava-ai/typescript-sdk.git"
+  }
 }

package/src/call.ts

@@ -25,6 +25,7 @@ import type {
 import { Say } from "./action-item.ts";
 import { telemetryClient } from "./telemetry.ts";
 import type { CallInfo } from "./socket/call-info.ts";
+import type { SipUri } from "./sip.ts";
 
 export type TaskObjective =
   | { objective: string }
@@ -248,13 +249,13 @@ export class Call {
    * This method does not interfere with turn-taking — use this when
    * you want the agent to naturally transfer the call.
    *
-   * @param destination - The phone number or SIP address to transfer the call to.
+   * @param destination - The phone number, SIP address, or SipUri to transfer the call to.
    * @param instructions - Optional guidance for how the agent should handle the transfer.
    */
-  async transfer(destination: string, instructions?: string) {
+  async transfer(destination: string | SipUri, instructions?: string) {
     await this.sendCommand(TransferCommand, {
       command_type: "transfer-call",
-      to_number: destination,
+      to_number: destination.toString(),
       transfer_message:
         instructions ?? "Notify the caller that you will be transferring them, and then transfer.",
       soft_transfer: true,
@@ -267,14 +268,14 @@ export class Call {
    * Unlike transfer(), this does not respect turn-taking. The agent immediately
    * initiates the transfer, saying the script (if provided).
    *
-   * @param destination - The phone number or SIP address to transfer the call to.
+   * @param destination - The phone number, SIP address, or SipUri to transfer the call to.
    * @param finalScript - Optional message for the agent to deliver immediately
    *   before transferring. Defaults to no message.
    */
-  async immediateTransfer(destination: string, finalScript?: string) {
+  async immediateTransfer(destination: string | SipUri, finalScript?: string) {
     await this.sendCommand(TransferCommand, {
       command_type: "transfer-call",
-      to_number: destination,
+      to_number: destination.toString(),
       transfer_message: finalScript ?? "",
       soft_transfer: false,
     });

package/src/index.ts

@@ -12,6 +12,8 @@ export type {
 export { Say, Field } from "./action-item.ts";
 export { Logger, getConsoleLogger, getDefaultLogger } from "./logging.ts";
 export { Agent, CallInfo } from "./agent.ts";
+export { SIPCallInfo } from "./socket/call-info.ts";
+export { SipUri } from "./sip.ts";
 export { Call, DEFAULT_REACH_PERSON_OUTCOMES } from "./call.ts";
 export type { ReachPersonOutcome } from "./call.ts";
 export type { SpeedPreset, Language } from "./commands.ts";

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/socket/call-info.ts

@@ -14,17 +14,59 @@ export const WebRTCCallInfo = z.object({
 });
 export type WebRTCCallInfo = z.infer<typeof WebRTCCallInfo>;
 
-export const SIPCallInfo = z.object({
-  call_type: z.literal("sip"),
-  from_aor: z.string(),
-  sip_code: z.string().optional(),
-  sip_headers: z.record(z.string(), z.string()).default({}),
-});
-export type SIPCallInfo = z.infer<typeof SIPCallInfo>;
+const SIPCallInfoSchema = z
+  .object({
+    call_type: z.literal("sip"),
+    from_aor: z
+      .string()
+      .describe(
+        'Despite the name, this field contains the entire SIP from-spec value, not just the AOR. Example: `"Display Name" <sip:user@example.com:5060>;tag=abc123`.',
+      ),
+    sip_code: z.string().optional(),
+    sip_headers: z.record(z.string(), z.string()).default({}),
+  })
+  .transform((data) => new SIPCallInfo(data.from_aor, data.sip_code, data.sip_headers));
+
+export class SIPCallInfo {
+  readonly call_type = "sip" as const;
+
+  constructor(
+    readonly from_aor: string,
+    readonly sip_code?: string,
+    readonly sip_headers: Record<string, string> = {},
+  ) {}
+
+  /** The from URI. */
+  get fromUri(): string {
+    const value = this.from_aor.trim();
+
+    // Skip a quoted display name, which may contain '<', '>' or escaped quotes.
+    let i = 0;
+    if (value.startsWith('"')) {
+      i = 1;
+      while (i < value.length && value[i] !== '"') {
+        i += value[i] === "\\" ? 2 : 1;
+      }
+      i += 1;
+    }
+
+    // A '<' after the first ';' is inside a header param, not the URI's bracket.
+    const start = value.indexOf("<", i);
+    const semi = value.indexOf(";", i);
+    if (start !== -1 && (semi === -1 || start < semi)) {
+      const end = value.indexOf(">", start);
+      if (end !== -1) {
+        return value.slice(start + 1, end).trim();
+      }
+    }
+
+    return value.split(";", 1)[0].trim();
+  }
+}
 
 export const CallInfo = z.discriminatedUnion("call_type", [
   PSTNCallInfo,
   WebRTCCallInfo,
-  SIPCallInfo,
+  SIPCallInfoSchema,
 ]);
 export type CallInfo = z.infer<typeof CallInfo>;

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.36.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();
+  }
+}