@guava-ai/guava-sdk 0.37.0 → 0.39.0

package/dist/src/webrtc/tones.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeavingTone = exports.JingleTone = exports.RingbackTone = void 0;
+// Seconds from the start of bar 0 to the given 0-indexed beat.
+function beatTime(beat, bpm) {
+    return beat * (60 / bpm);
+}
+// North American ringback: 440 + 480 Hz, 2s on, 4s off.
+class RingbackTone {
+    context = null;
+    intervalId = null;
+    volume = 0.15;
+    onSeconds = 2;
+    periodSeconds = 6;
+    // Delay before the first ring, so near-instant connections stay silent.
+    startDelay = 0.3;
+    start() {
+        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() {
+        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;
+    }
+}
+exports.RingbackTone = RingbackTone;
+class JingleTone {
+    context = null;
+    masterGain = null;
+    intervalId = null;
+    running = false;
+    pulseCount = 0;
+    // Audio-clock time of the next bar to schedule.
+    nextBarStart = 0;
+    // Configuration
+    volume = 0.3;
+    bpm = 120;
+    beatsPerBar = 4;
+    // Delay before the first note, so near-instant connections stay silent.
+    startDelay = 0.3;
+    start() {
+        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);
+    }
+    noteToFrequency(note) {
+        const match = note.match(/^([A-G])(#|b)?(-?\d+)$/);
+        if (!match) {
+            throw new Error(`Invalid note: ${note}`);
+        }
+        const [, name, accidental, octave] = match;
+        const semitones = {
+            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() {
+        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;
+    }
+    playPulse() {
+        if (!this.context || !this.masterGain)
+            return;
+        const bar = this.nextBarStart;
+        const beat = (n) => 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);
+    }
+    playNote(note, startTime, duration) {
+        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();
+        };
+    }
+}
+exports.JingleTone = JingleTone;
+class LeavingTone {
+    play() {
+        const ctx = new AudioContext();
+        if (ctx.state === "suspended") {
+            void ctx.resume();
+        }
+        const now = ctx.currentTime;
+        // First note: D4
+        const first = this.playNote(ctx, {
+            frequency: 293.665,
+            startTime: now,
+            attack: 0.065,
+            decay: 0.085,
+            volume: 0.2,
+        });
+        // Second note: A3, starts 139ms later
+        const second = this.playNote(ctx, {
+            frequency: 220.0,
+            startTime: now + 0.139,
+            attack: 0.018,
+            decay: 0.075,
+            volume: 0.2,
+        });
+        void Promise.all([first, second]).then(() => ctx.close());
+    }
+    // Resolves once the note has finished playing.
+    playNote(ctx, { frequency, startTime, attack, decay, volume, }) {
+        const oscillator = ctx.createOscillator();
+        const gain = ctx.createGain();
+        oscillator.type = "sine";
+        oscillator.frequency.setValueAtTime(frequency, startTime);
+        // Smooth onset
+        gain.gain.setValueAtTime(0, startTime);
+        gain.gain.linearRampToValueAtTime(volume, startTime + attack);
+        // Exponential decay
+        const peakTime = startTime + attack;
+        const endTime = peakTime + decay * 5;
+        gain.gain.setTargetAtTime(0.00001, peakTime, decay);
+        oscillator.connect(gain);
+        gain.connect(ctx.destination);
+        oscillator.start(startTime);
+        oscillator.stop(endTime);
+        return new Promise((resolve) => {
+            oscillator.onended = () => {
+                oscillator.disconnect();
+                gain.disconnect();
+                resolve();
+            };
+        });
+    }
+}
+exports.LeavingTone = LeavingTone;
+//# sourceMappingURL=tones.js.map

package/dist/src/webrtc/tones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tones.js","sourceRoot":"","sources":["../../../src/webrtc/tones.ts"],"names":[],"mappings":"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"}

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.37.0",
+  "version": "0.39.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,7 +76,10 @@
     "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"
   },
@@ -85,5 +94,9 @@
     "/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

@@ -13,6 +13,7 @@ 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

@@ -11,6 +11,7 @@ export type PSTNCallInfo = z.infer<typeof PSTNCallInfo>;
 export const WebRTCCallInfo = z.object({
   call_type: z.literal("webrtc"),
   webrtc_code: z.string(),
+  custom_payload: z.record(z.string(), z.unknown()).default({}),
 });
 export type WebRTCCallInfo = z.infer<typeof WebRTCCallInfo>;
 

package/src/version.ts

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