@guava-ai/guava-sdk 0.26.0 → 0.27.1

package/examples/help-desk.ts

@@ -1,7 +1,9 @@
+import { Command } from "commander";
 import * as guava from "@guava-ai/guava-sdk";
 import { DocumentQA } from "@guava-ai/guava-sdk/helpers";
 import { IntentRecognizer } from "@guava-ai/guava-sdk/helpers";
 import { FURNITURE_RETAILER_QA } from "@guava-ai/guava-sdk/example-data";
+import { getAgentNumber } from "@guava-ai/guava-sdk/example-utils";
 
 export const agent = new guava.Agent({
   name: "Nova",
@@ -57,24 +59,44 @@ agent.onAction("other", async (call: guava.Call) => {
   );
 });
 
-export async function run(args: string[]) {
-  if (args.includes("--webrtc")) {
-    await agent.listenWebrtc();
-  } else if (args.includes("--phone")) {
-    agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);
-  } else if (args.includes("--sip")) {
-    const sipCode = args[args.indexOf("--sip") + 1];
-    if (!sipCode) {
-      console.error("Error: --sip requires a SIP code argument.");
-      process.exit(1);
-    }
-    await agent.listenSip(sipCode);
-  } else if (args.includes("--local")) {
-    await agent.callLocal();
-  } else if (args.includes("--chat")) {
-    await agent.chat();
-  } else {
-    console.error("Usage: guava-example help-desk --phone | --webrtc | --sip | --local | --chat");
-    process.exit(1);
-  }
+export async function run(prog: string, args: string[]) {
+  const program = new Command().name(prog).showHelpAfterError();
+
+  // Every Agent can be attached to one of many different channels.
+  program
+    .command("phone [number]")
+    .description("Listen for phone calls.")
+    .action(async (number?: string) => {
+      await agent.listenPhone(number ?? (await getAgentNumber()));
+    });
+
+  program
+    .command("webrtc [code]")
+    .description("Listen on a WebRTC code.")
+    .action(async (code?: string) => {
+      await agent.listenWebrtc(code);
+    });
+
+  program
+    .command("sip <code>")
+    .description("Listen on a SIP code 'guavasip-...'.")
+    .action(async (code: string) => {
+      await agent.listenSip(code);
+    });
+
+  program
+    .command("local")
+    .description("Start a local call.")
+    .action(async () => {
+      await agent.callLocal();
+    });
+
+  program
+    .command("chat")
+    .description("Start a local chat session (for testing).")
+    .action(async () => {
+      await agent.chat();
+    });
+
+  await program.parseAsync(args, { from: "user" });
 }

package/examples/multiple-agents.ts

@@ -10,7 +10,7 @@ const agentB = new guava.Agent({
   purpose: "You are a helpful voice agent.",
 });
 
-export async function run(_args: string[]) {
+export async function run(_prog: string, _args: string[]) {
   const runner = new guava.Runner();
   runner.listenPhone(agentA, process.env.GUAVA_AGENT_NUMBER!);
   runner.listenWebrtc(agentB);

package/examples/polling-campaign.ts

@@ -7,6 +7,7 @@
  *
  * Usage: guava-example polling-campaign <campaign-code>
  */
+import { Command } from "commander";
 import * as guava from "@guava-ai/guava-sdk";
 
 const agent = new guava.Agent({
@@ -67,13 +68,17 @@ agent.onTaskComplete("political_poll", async (call) => {
   );
 });
 
-export async function run(args: string[]) {
-  const [campaignCode] = args;
+export async function run(prog: string, args: string[]) {
+  const program = new Command().name(prog).showHelpAfterError();
 
-  if (!campaignCode) {
-    console.error("Usage: guava-example polling-campaign <campaign-code>");
-    process.exit(1);
-  }
+  program
+    .argument(
+      "<campaign_code>",
+      "The campaign code to attach to (e.g. gcp-...). Use the CLI or dashboard to create a campaign.",
+    )
+    .action(async (campaignCode: string) => {
+      await agent.attachCampaign(campaignCode);
+    });
 
-  await agent.attachCampaign(campaignCode);
+  await program.parseAsync(args, { from: "user" });
 }

package/examples/property-insurance.ts

@@ -1,6 +1,8 @@
+import { Command } from "commander";
 import * as guava from "@guava-ai/guava-sdk";
 import { DocumentQA } from "@guava-ai/guava-sdk/helpers";
 import { PROPERTY_INSURANCE_POLICY } from "@guava-ai/guava-sdk/example-data";
+import { getAgentNumber } from "@guava-ai/guava-sdk/example-utils";
 
 const agent = new guava.Agent({
   organization: "Harper Valley Property Insurance",
@@ -21,26 +23,44 @@ agent.onQuestion(async (call: guava.Call, question: string) => {
   return await documentQA.ask(question);
 });
 
-export async function run(args: string[]) {
-  if (args.includes("--webrtc")) {
-    await agent.listenWebrtc();
-  } else if (args.includes("--phone")) {
-    agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);
-  } else if (args.includes("--sip")) {
-    const sipCode = args[args.indexOf("--sip") + 1];
-    if (!sipCode) {
-      console.error("Error: --sip requires a SIP code argument.");
-      process.exit(1);
-    }
-    await agent.listenSip(sipCode);
-  } else if (args.includes("--local")) {
-    await agent.callLocal();
-  } else if (args.includes("--chat")) {
-    await agent.chat();
-  } else {
-    console.error(
-      "Usage: guava-example property-insurance --phone | --webrtc | --sip | --local | --chat",
-    );
-    process.exit(1);
-  }
+export async function run(prog: string, args: string[]) {
+  const program = new Command().name(prog).showHelpAfterError();
+
+  // Every Agent can be attached to one of many different channels.
+  program
+    .command("phone [number]")
+    .description("Listen for phone calls.")
+    .action(async (number?: string) => {
+      await agent.listenPhone(number ?? (await getAgentNumber()));
+    });
+
+  program
+    .command("webrtc [code]")
+    .description("Listen on a WebRTC code.")
+    .action(async (code?: string) => {
+      await agent.listenWebrtc(code);
+    });
+
+  program
+    .command("sip <code>")
+    .description("Listen on a SIP code 'guavasip-...'.")
+    .action(async (code: string) => {
+      await agent.listenSip(code);
+    });
+
+  program
+    .command("local")
+    .description("Start a local call.")
+    .action(async () => {
+      await agent.callLocal();
+    });
+
+  program
+    .command("chat")
+    .description("Start an interactive terminal chat.")
+    .action(async () => {
+      await agent.chat();
+    });
+
+  await program.parseAsync(args, { from: "user" });
 }

package/examples/restaurant-waitlist.ts

@@ -1,5 +1,7 @@
+import { Command } from "commander";
 import * as guava from "@guava-ai/guava-sdk";
 import { getDefaultLogger } from "@guava-ai/guava-sdk";
+import { getAgentNumber } from "@guava-ai/guava-sdk/example-utils";
 
 const logger = getDefaultLogger();
 
@@ -42,26 +44,44 @@ agent.onTaskComplete("waitlist", async (call: guava.Call) => {
   await call.hangup("Thank the caller and let them know we'll text when their table is ready.");
 });
 
-export async function run(args: string[]) {
-  if (args.includes("--webrtc")) {
-    await agent.listenWebrtc();
-  } else if (args.includes("--phone")) {
-    agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);
-  } else if (args.includes("--sip")) {
-    const sipCode = args[args.indexOf("--sip") + 1];
-    if (!sipCode) {
-      console.error("Error: --sip requires a SIP code argument.");
-      process.exit(1);
-    }
-    await agent.listenSip(sipCode);
-  } else if (args.includes("--local")) {
-    await agent.callLocal();
-  } else if (args.includes("--chat")) {
-    await agent.chat();
-  } else {
-    console.error(
-      "Usage: guava-example restaurant-waitlist --phone | --webrtc | --sip | --local | --chat",
-    );
-    process.exit(1);
-  }
+export async function run(prog: string, args: string[]) {
+  const program = new Command().name(prog).showHelpAfterError();
+
+  // Every Agent can be attached to one of many different channels.
+  program
+    .command("phone [number]")
+    .description("Listen for phone calls.")
+    .action(async (number?: string) => {
+      await agent.listenPhone(number ?? (await getAgentNumber()));
+    });
+
+  program
+    .command("webrtc [code]")
+    .description("Listen on a WebRTC code.")
+    .action(async (code?: string) => {
+      await agent.listenWebrtc(code);
+    });
+
+  program
+    .command("sip <code>")
+    .description("Listen on a SIP code 'guavasip-...'.")
+    .action(async (code: string) => {
+      await agent.listenSip(code);
+    });
+
+  program
+    .command("local")
+    .description("Start a local call.")
+    .action(async () => {
+      await agent.callLocal();
+    });
+
+  program
+    .command("chat")
+    .description("Start an interactive terminal chat.")
+    .action(async () => {
+      await agent.chat();
+    });
+
+  await program.parseAsync(args, { from: "user" });
 }

package/examples/scheduling-outbound.ts

@@ -1,3 +1,4 @@
+import { Command } from "commander";
 import * as guava from "@guava-ai/guava-sdk";
 import { DatetimeFilter } from "@guava-ai/guava-sdk/helpers";
 import { mockAppointmentsForFuture } from "@guava-ai/guava-sdk/example-data";
@@ -42,22 +43,32 @@ agent.onTaskComplete("schedule_appointment", async (call) => {
   await call.hangup("Thank them for their time and hang up the call.");
 });
 
-export async function run(args: string[]) {
-  if (args.includes("--chat")) {
-    const patientName = args[args.indexOf("--chat") + 1] ?? "Benjamin Buttons";
-    await agent.chat({ patientName });
-    return;
-  }
+export async function run(prog: string, args: string[]) {
+  const program = new Command().name(prog).showHelpAfterError();
 
-  const [toNumber, patientName = "Benjamin Buttons"] = args;
+  program
+    .command("phone <number>")
+    .description("Call a phone number.")
+    .option("-n, --name <name>", "Name of the patient.", "Benjamin Buttons")
+    .action(async (number: string, options: { name: string }) => {
+      await agent.callPhone(await getAgentNumber(), number, { patientName: options.name });
+    });
 
-  if (!toNumber) {
-    console.error("Usage: guava-example scheduling-outbound <phone> [name]");
-    console.error("       guava-example scheduling-outbound --chat [name]");
-    process.exit(1);
-  }
+  program
+    .command("local")
+    .description("Start a local call (for testing).")
+    .option("-n, --name <name>", "Name of the patient.", "Benjamin Buttons")
+    .action(async (options: { name: string }) => {
+      await agent.callLocal({ patientName: options.name });
+    });
+
+  program
+    .command("chat")
+    .description("Start a local chat session (for testing).")
+    .option("-n, --name <name>", "Name of the patient.", "Benjamin Buttons")
+    .action(async (options: { name: string }) => {
+      await agent.chat({ patientName: options.name });
+    });
 
-  agent.callPhone(await getAgentNumber(), toNumber, {
-    patientName: patientName,
-  });
+  await program.parseAsync(args, { from: "user" });
 }

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.26.0",
+  "version": "0.27.1",
   "type": "commonjs",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -46,6 +46,7 @@
     "guava-example": "dist/bin/example-runner.js"
   },
   "dependencies": {
+    "commander": "^15.0.0",
     "openai": "^6.16.0",
     "ws": "^8.19.0",
     "zod": "^4.3.5"

package/src/agent.ts

@@ -276,12 +276,14 @@ export class Agent {
     return this._listenInbound(healthCtx, { sip_code: sipCode });
   }
 
-  async callLocal(): Promise<void> {
+  async callLocal(variables: Record<string, any> = {}): Promise<void> {
     const webrtcCode = await this._client.createWebrtcAgent(300);
     // No health-server for call_local.
-    this._listenInbound(new HealthContext(), { webrtc_code: webrtcCode }).catch((err) => {
-      this._logger.error("Listen loop error: %s", err);
-    });
+    this._listenInbound(new HealthContext(), { webrtc_code: webrtcCode }, variables).catch(
+      (err) => {
+        this._logger.error("Listen loop error: %s", err);
+      },
+    );
     await runWebrtcHelper(webrtcCode, getBaseUrl());
   }
 
@@ -574,7 +576,11 @@ export class Agent {
     }
   }
 
-  async _listenInbound(healthCtx: HealthContext, conn: InboundConnection): Promise<void> {
+  async _listenInbound(
+    healthCtx: HealthContext,
+    conn: InboundConnection,
+    initialVariables: Record<string, any> = {},
+  ): Promise<void> {
     const url = new URL("v2/listen-inbound", this._client.getWebsocketBase());
     if ("agent_number" in conn) {
       url.searchParams.set("phone_number", conn.agent_number);
@@ -632,9 +638,11 @@ export class Agent {
             case "assign-call": {
               const { call_id, call_info } = msg;
               this._logger.info("Received call (session ID: %s)", call_id);
-              this._handleAssignedCall(call_id, call_info, socket).catch((err) => {
-                this._logger.error("Error handling assigned call %s: %s", call_id, err);
-              });
+              this._handleAssignedCall(call_id, call_info, socket, initialVariables).catch(
+                (err) => {
+                  this._logger.error("Error handling assigned call %s: %s", call_id, err);
+                },
+              );
               break;
             }
           }

package/src/call.ts

@@ -10,7 +10,9 @@ import {
   ReadScriptCommand,
   RetryTaskCommand,
   SetAgentDTMFCommand,
+  SendAgentDTMFCommand,
 } from "./commands.ts";
+import { DTMF_DIGITS, type DTMFDigit } from "./events.ts";
 import type * as z from "zod";
 import type {
   ActionItem,
@@ -133,12 +135,35 @@ export class Call {
   }
 
   async setAgentDtmf(enabled: boolean) {
+    if (this._callInfo.call_type === "webrtc") {
+      throw new Error("WebRTC calls do not support sending DTMF.");
+    }
     await this.sendCommand(SetAgentDTMFCommand, {
       command_type: "set-agent-dtmf",
       enabled,
     });
   }
 
+  async sendDtmf(digits: DTMFDigit[] | string) {
+    if (this._callInfo.call_type === "webrtc") {
+      throw new Error("WebRTC calls do not support sending DTMF.");
+    }
+
+    const digitsList = (typeof digits === "string" ? [...digits] : digits) as DTMFDigit[];
+
+    const validSet = new Set<string>(DTMF_DIGITS);
+    if (!digitsList.every((d) => validSet.has(d))) {
+      throw new Error(
+        `Please input a valid set of DTMF digits. The valid DTMF digits are: ${JSON.stringify(DTMF_DIGITS)}.`,
+      );
+    }
+
+    await this.sendCommand(SendAgentDTMFCommand, {
+      command_type: "send-agent-dtmf",
+      digits: digitsList,
+    });
+  }
+
   async setLanguageMode(args: { primary?: Language; secondary?: Language[] }) {
     await this.sendCommand(SetLanguageModeCommand, {
       command_type: "set-language-mode",

package/src/client.ts

@@ -1,19 +1,10 @@
-import WebSocket from "ws";
 import { type Logger, getDefaultLogger } from "./logging.ts";
-import {
-  StartOutboundCallCommand,
-  ListenInboundCommand,
-  InboundTunnelCommand,
-} from "./commands.ts";
-import * as z from "zod";
-import { ErrorEvent, SessionStartedEvent, decodeEvent, InboundTunnelEvent } from "./events.ts";
 import { SDK_VERSION } from "./version.ts";
 import os from "node:os";
 import * as fs from "node:fs";
 import { getBaseUrl, fetchOrThrow, sleep } from "./utils.ts";
 import { SmsMessage } from "./sms.ts";
 import { telemetryClient } from "./telemetry.ts";
-import type { CallController } from "./call-controller.ts";
 import {
   type AuthStrategy,
   APIKeyAuth,
@@ -35,10 +26,6 @@ export interface ClientOptions {
 
 let firstClient = false;
 
-function stringifyZod<Schema extends z.ZodType>(schema: Schema, data: z.input<Schema>): string {
-  return JSON.stringify(schema.parse(data));
-}
-
 export type InboundConnection = { agent_number: string } | { webrtc_code: string };
 
 const http_start = /^http:\/\//;
@@ -49,9 +36,6 @@ export class Client {
   private _auth: AuthStrategy;
   private _baseUrl: string;
   private _logger: Logger;
-  private _ws?: WebSocket;
-  private _controller?: CallController;
-  private messageHandler?: (_: WebSocket.MessageEvent) => void;
 
   constructor({
     apiKey,
@@ -245,185 +229,4 @@ export class Client {
       await sleep(Math.min(pollIntervalMs, remaining));
     }
   }
-
-  /**
-   * @description use the Guava API to call out to a number
-   */
-  async createOutbound(
-    fromNumber: string | undefined,
-    toNumber: string,
-    callController: CallController,
-  ) {
-    const url = new URL("v1/create-outbound", this.getWebsocketBase());
-    const ws = new WebSocket(url, {
-      headers: await this.headers(),
-    });
-
-    ws.addEventListener("open", async (_ev) => {
-      ws.send(
-        stringifyZod(StartOutboundCallCommand, {
-          command_type: "start-outbound",
-          to_number: toNumber,
-          from_number: fromNumber,
-        }),
-      );
-
-      // set the callController drain function to send all commands
-      // through the now open websocket
-      callController.setDrain(async (commands) => {
-        for (const command of commands.splice(0)) {
-          this._logger.debug(`Sending command ${JSON.stringify(command)}`);
-          ws.send(JSON.stringify(command));
-        }
-      });
-
-      await callController.onCallStart();
-    });
-
-    ws.addEventListener("close", (_ev) => {
-      // we are closing the socket, so don't trigger any other listeners
-      ws.removeAllListeners();
-      this._ws = undefined;
-      this._controller = undefined;
-    });
-
-    this._ws = ws;
-    this._controller = callController;
-    this.replaceHandler(this.uninitializedOutbound.bind(this));
-  }
-
-  private replaceHandler(newHandler?: (_: WebSocket.MessageEvent) => void) {
-    if (this.messageHandler) {
-      this._ws?.removeEventListener("message", this.messageHandler);
-    }
-    if (newHandler) {
-      this._ws?.addEventListener("message", newHandler);
-    }
-    this.messageHandler = newHandler;
-  }
-
-  // eventlistener handlers for server events
-  // (a state machine in functions)
-  private uninitializedOutbound(ev: WebSocket.MessageEvent) {
-    // for correctness (and type correctness)
-    if (!this._ws) {
-      throw new Error("[internal] Uninitialized WebSocket");
-    }
-
-    const session_started = z
-      .union([SessionStartedEvent, ErrorEvent])
-      .parse(JSON.parse(ev.data.toString("utf8")));
-    if (session_started.event_type === "error") {
-      throw new Error(`Outbound call failed: ${session_started.content}`);
-    } else {
-      this._logger.info(`Started session with ID: ${session_started.session_id}`);
-      // move to next state
-      this.replaceHandler(this.initializedOutbound.bind(this));
-    }
-  }
-
-  private async initializedOutbound(ev: WebSocket.MessageEvent) {
-    // for correctness (and type correctness)
-    if (!this._ws) {
-      throw new Error("[internal] Uninitialized WebSocket");
-    }
-
-    // handle the received event
-    const event = decodeEvent(ev.data);
-    if (event) {
-      if (this._controller) {
-        await this._controller.onEvent(event);
-      }
-      if (event.event_type === "outbound-call-failed" || event.event_type === "bot-session-ended") {
-        // shutdown the websocket
-        this._ws.close();
-      }
-    }
-  }
-
-  /**
-   * @description use the Guava API to receive calls at a given number
-   */
-  async listenInbound<U extends CallController>(
-    conn: InboundConnection,
-    controllerClassFactory: (logger: Logger) => U,
-  ): Promise<InboundListener> {
-    const callControllers: Record<string, U> = {};
-
-    // return a way to *stop* listening
-    const url = new URL("v1/listen-inbound", this.getWebsocketBase());
-    const ws = new WebSocket(url, {
-      headers: await this.headers(),
-    });
-    let agent_number: string | undefined;
-    let webrtc_code: string | undefined;
-    if ("agent_number" in conn) {
-      agent_number = conn.agent_number;
-    } else {
-      webrtc_code = conn.webrtc_code;
-    }
-
-    this._logger.info(`Listening for calls to ${agent_number ?? webrtc_code}`);
-
-    if (webrtc_code) {
-      const debugurl = new URL(`debug-webrtc?webrtc_code=${webrtc_code}`, this.getHttpBase());
-      this._logger.debug(`WebRTC DebugURL: ${debugurl}`);
-    }
-
-    ws.addEventListener("open", (_ev) => {
-      ws.send(
-        stringifyZod(ListenInboundCommand, {
-          command_type: "listen-inbound",
-          agent_number: agent_number,
-          webrtc_code: webrtc_code,
-        }),
-      );
-    });
-
-    ws.addEventListener("close", (_ev) => {
-      ws.removeAllListeners();
-    });
-
-    ws.addEventListener("message", (ev) => {
-      const tunnel_event = InboundTunnelEvent.parse(JSON.parse(ev.data.toString("utf8")));
-      if (!(tunnel_event.call_id in callControllers)) {
-        this._logger.info(
-          `Received tunnel event for new call ID: ${tunnel_event.call_id}. Creating call controller.`,
-        );
-
-        const newController = controllerClassFactory(this._logger);
-        newController.setDrain(async (commands) => {
-          for (const command of commands.splice(0)) {
-            this._logger.debug(
-              `Sending command: ${JSON.stringify(command)} for call ID: ${tunnel_event.call_id}`,
-            );
-            ws.send(
-              stringifyZod(InboundTunnelCommand, {
-                call_id: tunnel_event.call_id,
-                command,
-              }),
-            );
-          }
-        });
-        callControllers[tunnel_event.call_id] = newController;
-        newController.onEvent(tunnel_event.event);
-      } else {
-        // no threading, so manually forward to onEvent!
-        callControllers[tunnel_event.call_id].onEvent(tunnel_event.event);
-      }
-    });
-
-    return new InboundListener(ws);
-  }
-}
-
-class InboundListener {
-  private ws: WebSocket;
-  constructor(ws: WebSocket) {
-    this.ws = ws;
-  }
-
-  close() {
-    this.ws.close();
-  }
 }