@guava-ai/guava-sdk 0.19.0 → 0.21.0

package/examples/polling-campaign.ts

@@ -0,0 +1,79 @@
+/**
+ * This example attaches a political polling agent to an ongoing Guava campaign.
+ *
+ * To use this, first create a campaign from the dashboard or CLI and add contacts.
+ * Then, run this script with the campaign code and the Agent will start making calls
+ * to those registered contacts.
+ *
+ * Usage: guava-example polling-campaign <campaign-code>
+ */
+import * as guava from "@guava-ai/guava-sdk";
+
+const agent = new guava.Agent({
+  name: "Jordan",
+  organization: "Harper Valley Research Center",
+  purpose: "Conduct a non-partisan political opinion poll",
+});
+
+agent.onCallStart(async (call: guava.Call) => {
+  const firstName = await call.getVariable("first_name");
+  await call.reachPerson(firstName, {
+    greeting:
+      `Hi, is this ${firstName}? I'm calling from the Harper Valley Research Center. ` +
+      "We're conducting a brief, non-partisan poll about issues affecting your State.",
+  });
+});
+
+agent.onReachPerson(async (call: guava.Call, outcome: string) => {
+  if (outcome === "available") {
+    const firstName = await call.getVariable("first_name");
+    await call.setTask({
+      taskId: "political_poll",
+      objective:
+        `Conduct a brief political opinion poll with ${firstName}. ` +
+        "Be polite, non-partisan, and respect their time.",
+      checklist: [
+        guava.Field({
+          key: "top_issue",
+          description: "The most important issue to the respondent right now",
+          fieldType: "text",
+          question: "What would you say is the most important issue facing your state right now?",
+        }),
+        guava.Field({
+          key: "governor_approval",
+          description: "Approval rating of the current governor",
+          fieldType: "multiple_choice",
+          question: "Do you approve or disapprove of the job the current governor is doing?",
+          choices: ["approve", "disapprove", "no_opinion"],
+        }),
+        guava.Field({
+          key: "likely_to_vote",
+          description: "How likely the respondent is to vote in the next election",
+          fieldType: "multiple_choice",
+          question: "How likely are you to vote in the upcoming election?",
+          choices: ["very_likely", "likely", "unlikely", "very_unlikely"],
+        }),
+      ],
+    });
+  } else {
+    await call.hangup("Appropriately end the call.");
+  }
+});
+
+agent.onTaskComplete("political_poll", async (call) => {
+  // Here is where you would read the poll results using call.getField(...)
+  await call.hangup(
+    "Thank them for participating and let them know the results will be published next month.",
+  );
+});
+
+export async function run(args: string[]) {
+  const [campaignCode] = args;
+
+  if (!campaignCode) {
+    console.error("Usage: guava-example polling-campaign <campaign-code>");
+    process.exit(1);
+  }
+
+  await agent.attachCampaign(campaignCode);
+}

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.19.0",
+  "version": "0.21.0",
   "type": "commonjs",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -50,7 +50,7 @@
     "check-format": "biome format ./src ./examples",
     "format": "biome format --write ./src ./examples",
     "test": "jest",
-    "check": "npm run typecheck && npm audit && npm run lint && npm run check-format",
+    "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",
     "prepare": "npm run clean && npm run build",

package/src/action-item.ts

@@ -13,7 +13,8 @@ export const FieldItem = z
   .object({
     item_type: z.literal("field"),
     key: z.string(),
-    description: z.string(),
+    description: z.string().default(""),
+    question: z.string().default(""),
     field_type: FieldItemType,
     required: z.boolean().default(true),
     choices: z.array(z.string()).default([]),
@@ -34,7 +35,8 @@ export type FieldItem = z.input<typeof FieldItem>;
 export const SerializableFieldItem = z.object({
   item_type: z.literal("field"),
   key: z.string(),
-  description: z.string(),
+  description: z.string().default(""),
+  question: z.string().default(""),
   field_type: FieldItemType,
   required: z.boolean().default(true),
   choices: z.array(z.string()).default([]),
@@ -61,7 +63,8 @@ export type ActionItem = z.input<typeof ActionItem>;
 
 export function Field(options: {
   key: string;
-  description: string;
+  description?: string;
+  question?: string;
   fieldType: FieldItemType;
   required?: boolean;
   choices?: string[];
@@ -72,6 +75,7 @@ export function Field(options: {
     item_type: "field",
     key: options.key,
     description: options.description,
+    question: options.question,
     field_type: options.fieldType,
     required: options.required,
     choices: options.choices,

package/src/agent.ts

@@ -14,10 +14,17 @@ import {
   type GuavaEvent,
   type CallerSpeechEvent,
   type AgentSpeechEvent,
+  type BotSessionEnded,
+  type DTMFPressedEvent,
   decodeEventDict,
 } from "./events.ts";
 import { telemetryClient } from "./telemetry.ts";
 import { GuavaSocket, GuavaSocketClosedError } from "./socket/client.ts";
+import {
+  type ClientMessage as DialerClientMessage,
+  type ServerMessage as DialerServerMessage,
+  decodeServerMessage as decodeDialerServerMessage,
+} from "./guavadialer-events.ts";
 import * as ListenInbound from "./socket/listen-inbound.ts";
 import type { CallInfo } from "./socket/call-info.ts";
 import { TestSession } from "./testing/session.ts";
@@ -64,7 +71,8 @@ export class Agent {
   ) => Promise<SuggestedAction | undefined>;
   private _onActionGeneric?: (call: Call, actionKey: string) => Promise<void>;
   private _onActionHandlers: Record<string, (call: Call) => Promise<void>> = {};
-  private _onSessionEnd?: (call: Call) => Promise<void>;
+  private _onSessionEnd?: (call: Call, event: BotSessionEnded) => Promise<void>;
+  private _onDtmf?: (call: Call, event: DTMFPressedEvent) => Promise<void>;
 
   constructor(args?: { name?: string; organization?: string; purpose?: string }) {
     this._name = args?.name;
@@ -138,10 +146,14 @@ export class Agent {
     }
   }
 
-  onSessionEnd(callback: (call: Call) => Promise<void>): void {
+  onSessionEnd(callback: (call: Call, event: BotSessionEnded) => Promise<void>): void {
     this._onSessionEnd = callback;
   }
 
+  onDtmf(callback: (call: Call, event: DTMFPressedEvent) => Promise<void>): void {
+    this._onDtmf = callback;
+  }
+
   get handlers() {
     return {
       onCallReceived: (callInfo: CallInfo) => this._onCallReceived(callInfo),
@@ -181,9 +193,9 @@ export class Agent {
         if (actionKey in this._onActionHandlers) return this._onActionHandlers[actionKey](call);
         throw new Error(`No onAction handler registered for action '${actionKey}'.`);
       },
-      onSessionEnd: (call: Call) => {
+      onSessionEnd: (call: Call, event: BotSessionEnded) => {
         if (!this._onSessionEnd) throw new Error("No onSessionEnd handler registered.");
-        return this._onSessionEnd(call);
+        return this._onSessionEnd(call, event);
       },
     };
   }
@@ -310,8 +322,10 @@ export class Agent {
       if (testSession) {
         testSession.terminationReason = event.termination_reason;
       }
-      if (this._onSessionEnd !== undefined) {
-        await this._onSessionEnd(call);
+      await this._onSessionEnd?.(call, event);
+    } else if (event.event_type === "dtmf") {
+      if (this._onDtmf !== undefined) {
+        await this._onDtmf(call, event);
       }
     } else if (event.event_type === "error") {
       this._logger.error(`The Guava agent reported an error: ${event.content}`);
@@ -343,10 +357,11 @@ export class Agent {
     callId: string,
     initialVariables: Record<string, any> = {},
     testSession?: TestSession,
+    route: string = "v2/connect-call",
   ): Promise<void> {
     const call = await this._initCall(initialVariables);
 
-    const url = new URL(`v2/connect-call/${callId}`, this._client.getWebsocketBase());
+    const url = new URL(`${route}/${callId}`, this._client.getWebsocketBase());
     await using socket = await new GuavaSocket<Command, GuavaEvent | null>(
       `call-connection-${callId}`,
       url.toString(),
@@ -661,9 +676,79 @@ Choose "speak" and provide your next utterance, or choose "hangup" if the conver
     cloned._onActionGeneric = this._onActionGeneric;
     cloned._onActionHandlers = { ...this._onActionHandlers };
     cloned._onSessionEnd = this._onSessionEnd;
+    cloned._onDtmf = this._onDtmf;
     return cloned;
   }
 
+  private async _serveCampaign(campaignCode: string): Promise<void> {
+    const campaignUrl = new URL(`v1/campaigns/${campaignCode}`, this._client.getHttpBase());
+    const campaignResponse = await fetchOrThrow(campaignUrl, {
+      headers: await this._client.headers(),
+    });
+    const campaign = (await campaignResponse.json()) as { id: string; name: string };
+
+    const wsUrl = new URL(`v1/serve-campaign/${campaign.id}`, this._client.getWebsocketBase());
+    this._logger.info("Connecting to campaign '%s' (id: %s).", campaign.name, campaign.id);
+
+    await using socket = await new GuavaSocket<DialerClientMessage, DialerServerMessage>(
+      "serve-campaign",
+      wsUrl.toString(),
+      this._client,
+      (msg) => msg as unknown as Record<string, unknown>,
+      decodeDialerServerMessage,
+    ).connect();
+
+    const activeCalls: Promise<void>[] = [];
+
+    try {
+      for await (const msg of socket) {
+        switch (msg.message_type) {
+          case "listen-started":
+            this._logger.info("Listening for calls on campaign '%s'. Ready.", campaign.name);
+            break;
+          case "initiate-and-assign-call": {
+            const { call_id, contact_data } = msg;
+            const data = contact_data as Record<string, unknown> | null;
+            const logPhone = (data?.phone_number as string | undefined) ?? "?";
+            this._logger.info(
+              "Ready to make call, id %s — initiating call setup and dispatch for contact %s.",
+              call_id,
+              logPhone,
+            );
+            activeCalls.push(
+              (async () => {
+                socket.send({ message_type: "controller-ready", call_id });
+                const variables = (data?.data as Record<string, unknown>) ?? {};
+                await this._attachToCall(call_id, variables, undefined, "v2/connect-campaign-call");
+              })(),
+            );
+            break;
+          }
+        }
+      }
+    } catch (e) {
+      if (!(e instanceof GuavaSocketClosedError)) throw e;
+      this._logger.info("Campaign '%s' disconnected.", campaign.name);
+    }
+
+    await Promise.all(activeCalls);
+  }
+
+  /**
+   * Attach this agent to an active Guava campaign and handle outbound calls.
+   *
+   * Blocks until the campaign connection is closed.
+   *
+   * @param campaignCode - The campaign code (e.g. `gcmp-...`). Create a campaign
+   *   and upload contacts via the Guava dashboard or CLI before calling this.
+   *
+   * @example
+   * await agent.attachCampaign("gcmp-abc123");
+   */
+  async attachCampaign(campaignCode: string): Promise<void> {
+    return this._serveCampaign(campaignCode);
+  }
+
   /* ===== Aliases to be removed at some point. ===== */
   /** @deprecated Use {@link listenPhone} instead. */
   async inboundPhone(phoneNumber: string): Promise<void> {

package/src/client.ts

@@ -10,7 +10,8 @@ import { ErrorEvent, SessionStartedEvent, decodeEvent, InboundTunnelEvent } from
 import { SDK_VERSION } from "./version.ts";
 import os from "node:os";
 import * as fs from "node:fs";
-import { getBaseUrl, fetchOrThrow } from "./utils.ts";
+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 {
@@ -24,6 +25,14 @@ import {
 
 const SDK_NAME = "typescript-sdk";
 
+export interface ClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  logger?: Logger;
+  captureWarnings?: boolean;
+  checkDeprecation?: boolean;
+}
+
 let firstClient = false;
 
 function stringifyZod<Schema extends z.ZodType>(schema: Schema, data: z.input<Schema>): string {
@@ -44,7 +53,13 @@ export class Client {
   private _controller?: CallController;
   private messageHandler?: (_: WebSocket.MessageEvent) => void;
 
-  constructor(apiKey?: string, baseUrl?: string, logger?: Logger, captureWarnings: boolean = true) {
+  constructor({
+    apiKey,
+    baseUrl,
+    logger,
+    captureWarnings = true,
+    checkDeprecation = true,
+  }: ClientOptions = {}) {
     // Set up the default logger.
     if (logger) {
       this._logger = logger;
@@ -84,7 +99,9 @@ export class Client {
       }
 
       telemetryClient.setSdkClient(this);
-      this._checkSdkDeprecation();
+      if (checkDeprecation) {
+        this._checkSdkDeprecation();
+      }
     }
   }
 
@@ -155,6 +172,73 @@ export class Client {
     return body.webrtc_code;
   }
 
+  /**
+   * Sends an SMS message from one of your Guava numbers.
+   * @param fromNumber - One of your Guava numbers (E.164). Must have SMS configured.
+   * @param toNumber - The recipient's number (E.164).
+   * @param message - The message body to send.
+   */
+  async sendSms(fromNumber: string, toNumber: string, message: string): Promise<void> {
+    const url = new URL("v1/send-sms", this.getHttpBase());
+    await fetchOrThrow(url, {
+      method: "POST",
+      headers: { ...(await this.headers()), "Content-Type": "application/json" },
+      body: JSON.stringify({
+        from_number: fromNumber,
+        to_number: toNumber,
+        message,
+      }),
+    });
+  }
+
+  /**
+   * Waits for and returns the next inbound SMS sent from `fromNumber` to `toNumber`.
+   *
+   * Polls the inbox for messages received after this call begins, resolving once one
+   * arrives or `timeoutMs` elapses. Note the direction: `fromNumber` is the external
+   * number you're waiting to hear from, and `toNumber` is your Guava number — the
+   * opposite of {@link sendSms}.
+   *
+   * @param fromNumber - The external number to wait for a message from (E.164).
+   * @param toNumber - Your Guava number that will receive the message (E.164).
+   * @param options.timeoutMs - Max time to wait before giving up. Defaults to 60000.
+   * @param options.pollIntervalMs - Time between inbox checks. Defaults to 2000.
+   * @returns The message, or `null` if `timeoutMs` elapses with no new message.
+   */
+  async nextSms(
+    fromNumber: string,
+    toNumber: string,
+    options?: { timeoutMs?: number; pollIntervalMs?: number },
+  ): Promise<SmsMessage | null> {
+    const timeoutMs = options?.timeoutMs ?? 60_000;
+    const pollIntervalMs = options?.pollIntervalMs ?? 2_000;
+    const start = new Date().toISOString();
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const url = new URL("v1/messages", this.getHttpBase());
+      url.searchParams.set("to_number", toNumber);
+      url.searchParams.set("from_number", fromNumber);
+      url.searchParams.set("modality", "sms");
+      url.searchParams.set("start", start);
+      const response = await fetchOrThrow(url, {
+        method: "GET",
+        headers: await this.headers(),
+      });
+      // The endpoint returns matches oldest-first, so the earliest message after
+      // `start` is always the first element — we only need one, so `has_more`
+      // (which signals additional *later* messages) is irrelevant here.
+      const body = (await response.json()) as { messages: unknown[] };
+      if (body.messages?.length) {
+        return SmsMessage.parse(body.messages[0]);
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        return null;
+      }
+      await sleep(Math.min(pollIntervalMs, remaining));
+    }
+  }
+
   /**
    * @description use the Guava API to call out to a number
    */

package/src/events.ts

@@ -99,6 +99,9 @@ export const BotSessionEnded = z.object({
 });
 export type BotSessionEnded = z.infer<typeof BotSessionEnded>;
 
+/** Why a bot session ended. */
+export type TerminationReason = BotSessionEnded["termination_reason"];
+
 export const ChoiceQueryEvent = z.object({
   event_type: z.literal("choice-query"),
   field_key: z.string(),
@@ -120,6 +123,30 @@ export const ExecuteActionEvent = z.object({
 });
 export type ExecuteActionEvent = z.infer<typeof ExecuteActionEvent>;
 
+export type DTMFDigit =
+  | "0"
+  | "1"
+  | "2"
+  | "3"
+  | "4"
+  | "5"
+  | "6"
+  | "7"
+  | "8"
+  | "9"
+  | "*"
+  | "#"
+  | "A"
+  | "B"
+  | "C"
+  | "D";
+
+export const DTMFPressedEvent = z.object({
+  event_type: z.literal("dtmf"),
+  digit: z.enum(["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#", "A", "B", "C", "D"]),
+});
+export type DTMFPressedEvent = z.infer<typeof DTMFPressedEvent>;
+
 export const GuavaEvent = z.discriminatedUnion("event_type", [
   SessionStartedEvent,
   InboundCallEvent,
@@ -137,6 +164,7 @@ export const GuavaEvent = z.discriminatedUnion("event_type", [
   ChoiceQueryEvent,
   ActionRequestEvent,
   ExecuteActionEvent,
+  DTMFPressedEvent,
 ]);
 export type GuavaEvent = z.infer<typeof GuavaEvent>;
 

package/src/guavadialer-events.ts

@@ -0,0 +1,51 @@
+import * as z from "zod";
+
+export const ListenStarted = z.object({
+  message_type: z.literal("listen-started"),
+  other_listeners: z.number().int(),
+});
+export type ListenStarted = z.infer<typeof ListenStarted>;
+
+/**
+ * @description Sent from the server when it wants to start a call and has assigned it to the appropriate pod.
+ */
+export const InitiateAndAssignCall = z.object({
+  message_type: z.literal("initiate-and-assign-call"),
+  call_id: z.string(),
+  contact_data: z.unknown(),
+});
+export type InitiateAndAssignCall = z.infer<typeof InitiateAndAssignCall>;
+
+/**
+ * @description Sent from the client when it has initiated a call controller and is ready to connect to the call.
+ */
+export const ControllerReady = z.object({
+  message_type: z.literal("controller-ready"),
+  call_id: z.string(),
+});
+export type ControllerReady = z.infer<typeof ControllerReady>;
+
+/**
+ * @description Sent from the client when the controller failed to initialize (e.g. timeout). The server should release any resources held for this call.
+ */
+export const InitControllerFailed = z.object({
+  message_type: z.literal("init-controller-failed"),
+  call_id: z.string(),
+});
+export type InitControllerFailed = z.infer<typeof InitControllerFailed>;
+
+export const ServerMessage = z.discriminatedUnion("message_type", [
+  ListenStarted,
+  InitiateAndAssignCall,
+]);
+export type ServerMessage = z.infer<typeof ServerMessage>;
+
+export const ClientMessage = z.discriminatedUnion("message_type", [
+  ControllerReady,
+  InitControllerFailed,
+]);
+export type ClientMessage = z.infer<typeof ClientMessage>;
+
+export function decodeServerMessage(payload: Record<string, unknown>): ServerMessage {
+  return ServerMessage.parse(payload);
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 export { Client, type InboundConnection } from "./client.ts";
+export type { SmsMessage } from "./sms.ts";
 export { CallController, type TaskObjective } from "./call-controller.ts";
 export { Say, Field } from "./action-item.ts";
 export { Logger, getConsoleLogger, getDefaultLogger } from "./logging.ts";
 export { Agent, CallInfo } from "./agent.ts";
 export { Call } from "./call.ts";
+export type { BotSessionEnded, TerminationReason, DTMFPressedEvent, DTMFDigit } from "./events.ts";
 export { TestSession } from "./testing/session.ts";
 export { MockCall } from "./testing/mocks.ts";

package/src/sms.ts

@@ -0,0 +1,17 @@
+import * as z from "zod";
+
+/**
+ * An inbound SMS message received on one of your Guava numbers.
+ *
+ * Field names mirror the wire format returned by `GET /v1/messages`.
+ */
+export const SmsMessage = z.object({
+  id: z.string(),
+  from_number: z.string(),
+  to_number: z.string(),
+  content: z.string(),
+  received_at: z.string(),
+  modality: z.literal("sms"),
+  direction: z.enum(["inbound", "outbound"]),
+});
+export type SmsMessage = z.infer<typeof SmsMessage>;

package/src/utils.ts

@@ -45,6 +45,10 @@ class HttpStatusError extends Error {
   }
 }
 
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 export async function fetchOrThrow(
   input: RequestInfo | URL,
   init?: RequestInit,

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.19.0";
+export const SDK_VERSION = "0.21.0";