@guava-ai/guava-sdk 0.24.0 → 0.25.0

package/src/call.ts

@@ -33,6 +33,29 @@ export type ReachPersonOutcome = {
   nextActionPreview?: string;
 };
 
+export const DEFAULT_REACH_PERSON_OUTCOMES: ReachPersonOutcome[] = [
+  { key: "available", description: "The intended contact is confirmed on the line." },
+  {
+    key: "unavailable",
+    description:
+      "The contact could not be reached. A third party, gatekeeper, or IVR was unable to transfer the call to the contact.",
+  },
+  { key: "voicemail", description: "An answering machine or voicemail system was reached." },
+  { key: "wrong_number", description: "The number does not reach the intended contact." },
+  {
+    key: "do_not_contact",
+    description: "The person on the line has indicated this number should not be called.",
+  },
+];
+
+function voicemailHangupInstruction(): string {
+  return "DO NOT leave a message. REMAIN SILENT AND HANG UP WITHOUT RESPONDING.";
+}
+
+function voicemailMessageInstruction(message: string): string {
+  return `Say this message VERBATIM: "${message}" Then hang up.`;
+}
+
 @telemetryClient.trackClass()
 export class Call {
   private _callId: string;
@@ -242,19 +265,38 @@ export class Call {
 
   async reachPerson(
     contactFullName: string,
-    options: { outcomes?: ReachPersonOutcome[]; greeting?: string } = {},
+    options: {
+      outcomes?: ReachPersonOutcome[];
+      greeting?: string;
+      voicemailMessage?: string;
+      voicemailHangup?: boolean;
+    } = {},
   ) {
-    const outcomes = options.outcomes ?? [
-      { key: "available", description: "The contact is available to speak." },
-      {
-        key: "unavailable",
-        description:
-          "The contact is not available to speak. This includes reaching a wrong number.",
-      },
-    ];
+    if ((await this.getVariable("_voicemail_handler")) === "set_voicemail_action") {
+      throw new Error(
+        "Cannot call reachPerson() after setVoicemailAction(). " +
+          "Use the voicemailMessage or voicemailHangup parameters on reachPerson() instead.",
+      );
+    }
+    await this.setVariable("_voicemail_handler", "reach_person");
+
+    if (options.voicemailMessage && options.voicemailHangup) {
+      throw new Error("Cannot specify both 'voicemailMessage' and 'voicemailHangup'.");
+    }
+
+    const outcomes = options.outcomes ?? DEFAULT_REACH_PERSON_OUTCOMES;
+
+    let voicemailRule: string;
+    if (options.voicemailHangup) {
+      voicemailRule = voicemailHangupInstruction();
+    } else if (options.voicemailMessage) {
+      voicemailRule = voicemailMessageInstruction(options.voicemailMessage);
+    } else {
+      voicemailRule = "Leave an appropriate voicemail message.";
+    }
 
     const availabilityDescription =
-      `The availability of ${contactFullName}` +
+      `The availability of ${contactFullName}.` +
       (outcomes.some((o) => o.description)
         ? "\nDetailed descriptions of each choice:\n" +
           outcomes
@@ -266,7 +308,7 @@ export class Call {
     const checklist: (FieldItem | SayItem | string)[] = [
       options.greeting !== undefined
         ? Say(options.greeting)
-        : `Greet the person who answered the phone. Notify them who you are calling on behalf of and the purpose of the call. Ask to speak with ${contactFullName}`,
+        : `Greet the person, IVR, or system who answered the phone. Notify them who you are calling on behalf of and the purpose of the call. Ask to speak with ${contactFullName}. Do not greet if you detect an answering machine or voicemail system.`,
       {
         item_type: "field",
         key: "contact_availability",
@@ -281,38 +323,51 @@ export class Call {
       .map((o) => `- ${o.key} → ${o.nextActionPreview}`);
     if (nextActionLines.length > 0) {
       checklist.push(
-        "If a next action is defined below for the value of `contact_availability`, briefly ask the contact to wait just a second while you perform it.\n" +
+        "If a next action is defined below for the recorded value of `contact_availability`, briefly let the contact know while you perform it.\n" +
           nextActionLines.join("\n"),
       );
     }
 
     const objective = `\
 OBJECTIVE:
-Your goal is to reach ${contactFullName} and determine their availability to proceed with this call.
+Your goal is to reach ${contactFullName} and confirm they are on the line.
 
 RULES:
-1. If the initial respondent is NOT ${contactFullName}:
-   - Politely ask to speak with ${contactFullName}
-   - Wait to be transferred or for ${contactFullName} to come to the phone
-2. Once you have ${contactFullName} on the line:
+1. If someone other than ${contactFullName} answers - including a person or IVR:
+   - Politely ask to speak with ${contactFullName}, or navigate menus and prompts to reach them.
+   - Wait to be transferred or for ${contactFullName} to come to the phone.
+   - If ${contactFullName} cannot be reached, record \`contact_availability\` appropriately.
+2. Once ${contactFullName} is confirmed on the line:
    - Briefly restate who you are and the purpose of your call
-   - Determine and record their current availability status
-3. DO NOT hang up the call under any circumstances, unless it's a wrong number.
+   - Record their availability as available, or equivalent, in \`contact_availability\`.
+3. If it is clearly a wrong number or you have been asked not to call, politely end the call and hang up.
+4. If you reach an answering machine or voicemail: ${voicemailRule}
+`;
 
+    const completionCriteria = `\
 TASK COMPLETION REQUIREMENTS:
-- The availability of ${contactFullName} must be recorded in \`contact_availability\`.`;
+- The availability of ${contactFullName} must be recorded in \`contact_availability\`.
+`;
 
-    await this.setTask({ taskId: "reach_person", objective, checklist });
+    await this.setTask({ taskId: "reach_person", objective, checklist, completionCriteria });
   }
 
   async setVoicemailAction(action: { hangup: true } | { message: string }) {
+    if ((await this.getVariable("_voicemail_handler")) === "reach_person") {
+      throw new Error(
+        "Cannot call setVoicemailAction() after reachPerson(). " +
+          "Use the voicemailMessage or voicemailHangup parameters on reachPerson() instead.",
+      );
+    }
+    await this.setVariable("_voicemail_handler", "set_voicemail_action");
+
     if ("hangup" in action) {
       await this.sendInstruction(
-        "If you encounter an answering machine, DO NOT leave a message. REMAIN SILENT AND HANG UP WITHOUT RESPONDING. You should only do this when it's clear you are unable to reach the person.",
+        `If you encounter an answering machine, ${voicemailHangupInstruction()} You should only do this when it's clear you are unable to reach the person.`,
       );
     } else {
       await this.sendInstruction(
-        `If you encounter an answering machine, say this message VERBATIM: ${action.message}. You should only leave this message if it's clear you are unable to reach the person.`,
+        `If you encounter an answering machine, ${voicemailMessageInstruction(action.message)} You should only do this when it's clear you are unable to reach the person.`,
       );
     }
   }

package/src/client.ts

@@ -172,6 +172,13 @@ export class Client {
     return body.webrtc_code;
   }
 
+  async listNumbers(): Promise<{ phoneNumber: string }[]> {
+    const url = new URL("v1/phone-numbers", this.getHttpBase());
+    const response = await fetchOrThrow(url, { headers: await this.headers() });
+    const items = (await response.json()) as { phone_number: string }[];
+    return items.map((item) => ({ phoneNumber: item.phone_number }));
+  }
+
   /**
    * Sends an SMS message from one of your Guava numbers.
    * @param fromNumber - One of your Guava numbers (E.164). Must have SMS configured.

package/src/example-utils.ts

@@ -0,0 +1,87 @@
+import * as process from "node:process";
+import { Client } from "./client.ts";
+
+export async function getAgentNumber(): Promise<string> {
+  if (process.env.GUAVA_AGENT_NUMBER) return process.env.GUAVA_AGENT_NUMBER;
+
+  const client = new Client();
+  const numbers = await client.listNumbers();
+
+  if (numbers.length === 0) {
+    console.error("No agent phone numbers found. Please purchase a number first.");
+    process.exit(1);
+  }
+  if (numbers.length === 1) return numbers[0].phoneNumber;
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    return terminalPicker(
+      numbers.map((n) => n.phoneNumber),
+      "Multiple agent phone numbers found. Select one",
+    );
+  }
+  console.error(
+    `Multiple agent phone numbers found: ${numbers.map((n) => n.phoneNumber).join(", ")}. Please set GUAVA_AGENT_NUMBER.`,
+  );
+  process.exit(1);
+}
+
+export async function terminalPicker(
+  options: string[],
+  prompt = "Select an option",
+): Promise<string> {
+  if (!options.length) throw new Error("options must be non-empty");
+  if (!process.stdin.isTTY || !process.stdout.isTTY)
+    throw new Error("terminalPicker requires a TTY stdin and stdout");
+
+  return new Promise((resolve, reject) => {
+    let selected = 0;
+    let renderedLines = 0;
+
+    function render() {
+      const lines = [`${prompt}:`];
+      for (let i = 0; i < options.length; i++) {
+        lines.push(`${i === selected ? "❯" : " "} ${options[i]}`);
+      }
+      if (renderedLines > 0) process.stdout.write(`\x1b[${renderedLines}F`);
+      for (const line of lines) {
+        process.stdout.write("\r\x1b[2K");
+        process.stdout.write(line);
+        process.stdout.write("\n");
+      }
+      for (let i = 0; i < renderedLines - lines.length; i++) {
+        process.stdout.write("\r\x1b[2K\n");
+      }
+      renderedLines = lines.length;
+    }
+
+    function cleanup() {
+      process.stdin.removeListener("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\x1b[?25h");
+    }
+
+    function onData(data: Buffer) {
+      const ch = data.toString();
+      if (ch === "\r" || ch === "\n") {
+        cleanup();
+        process.stdout.write(`\r\x1b[2KSelected: ${options[selected]}\n`);
+        resolve(options[selected]);
+      } else if (ch === "\x03") {
+        cleanup();
+        reject(new Error("Interrupted"));
+      } else if (ch === "\x1b[A") {
+        selected = (selected - 1 + options.length) % options.length;
+        render();
+      } else if (ch === "\x1b[B") {
+        selected = (selected + 1) % options.length;
+        render();
+      }
+    }
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdout.write("\x1b[?25l");
+    render();
+    process.stdin.on("data", onData);
+  });
+}

package/src/helpers/llm.ts

@@ -1,3 +1,4 @@
+import * as z from "zod";
 import type { SuggestedAction } from "../agent.ts";
 import { Client } from "../client.ts";
 import { telemetryClient } from "../telemetry.ts";
@@ -81,15 +82,10 @@ export class DocumentQA {
   }
 }
 
-const _filterSchema = {
-  type: "object",
-  properties: {
-    matching_appointments: { type: "array", items: { type: "string" } },
-    other_appointments: { type: "array", items: { type: "string" } },
-  },
-  required: ["matching_appointments", "other_appointments"],
-  additionalProperties: false,
-};
+export const _filterSchema = z.object({
+  matching_appointments: z.array(z.string()),
+  other_appointments: z.array(z.string()),
+});
 
 @telemetryClient.trackClass()
 export class DatetimeFilter {
@@ -122,11 +118,8 @@ ${this._slotsStr}
 
 Return at most ${maxResults} items per list.`;
 
-    const text = await _generate(this._client, prompt, _filterSchema);
-    const result = JSON.parse(text) as {
-      matching_appointments: string[];
-      other_appointments: string[];
-    };
+    const text = await _generate(this._client, prompt, z.toJSONSchema(_filterSchema));
+    const result = _filterSchema.parse(JSON.parse(text));
     return [
       result.matching_appointments.slice(0, maxResults),
       result.other_appointments.slice(0, maxResults),
@@ -134,30 +127,29 @@ Return at most ${maxResults} items per list.`;
   }
 }
 
+export function _makeIntentSchema(choiceList: [string, ...string[]]) {
+  return z
+    .object({
+      possible_matches: z
+        .array(z.enum(choiceList))
+        .describe(
+          "Choices that could match the caller's intent, ordered by likelihood. Include all plausible matches.",
+        ),
+    })
+    .meta({ title: "ChoiceModel" });
+}
+
 @telemetryClient.trackClass()
 export class IntentRecognizer {
   private readonly _client: Client;
   private readonly _intentChoices: string[] | Record<string, string>;
-  private readonly _schema: object;
+  private readonly _schema: ReturnType<typeof _makeIntentSchema>;
 
   constructor(intentChoices: string[] | Record<string, string>) {
     this._client = new Client();
     this._intentChoices = intentChoices;
     const choiceList = Array.isArray(intentChoices) ? intentChoices : Object.keys(intentChoices);
-    this._schema = {
-      type: "object",
-      title: "ChoiceModel",
-      properties: {
-        possible_matches: {
-          type: "array",
-          items: { type: "string", enum: choiceList },
-          description:
-            "Choices that could match the caller's intent, ordered by likelihood. Include all plausible matches.",
-        },
-      },
-      required: ["possible_matches"],
-      additionalProperties: false,
-    };
+    this._schema = _makeIntentSchema(choiceList as [string, ...string[]]);
   }
 
   async classify(intent: string): Promise<SuggestedAction[] | null> {
@@ -183,8 +175,8 @@ Rules:
       prompt += `\n\nDetailed descriptions of each choice:\n  ${descriptionString}`;
     }
 
-    const text = await _generate(this._client, prompt, this._schema);
-    const keys = (JSON.parse(text) as { possible_matches: string[] }).possible_matches;
+    const text = await _generate(this._client, prompt, z.toJSONSchema(this._schema));
+    const { possible_matches: keys } = this._schema.parse(JSON.parse(text));
 
     if (!keys.length) return null;
 

package/src/index.ts

@@ -1,10 +1,12 @@
 export { Client, type InboundConnection } from "./client.ts";
+export { Runner } from "./runner.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 { Call, DEFAULT_REACH_PERSON_OUTCOMES } from "./call.ts";
+export type { ReachPersonOutcome } 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/runner.ts

@@ -0,0 +1,39 @@
+import type { Agent } from "./agent.ts";
+import { MultiHealthContext, getHealthServer } from "./health.ts";
+
+export class Runner {
+  private _healthCtx = new MultiHealthContext();
+  private _tasks: Array<() => Promise<void>> = [];
+
+  listenPhone(agent: Agent, agentNumber: string): this {
+    const ctx = this._healthCtx.createCtx();
+    this._tasks.push(() => agent._listenInbound(ctx, { agent_number: agentNumber }));
+    return this;
+  }
+
+  listenWebrtc(agent: Agent, webrtcCode?: string): this {
+    const ctx = this._healthCtx.createCtx();
+    this._tasks.push(async () => {
+      const code = webrtcCode ?? (await agent._client.createWebrtcAgent(3600));
+      return agent._listenInbound(ctx, { webrtc_code: code });
+    });
+    return this;
+  }
+
+  listenSip(agent: Agent, sipCode: string): this {
+    const ctx = this._healthCtx.createCtx();
+    this._tasks.push(() => agent._listenInbound(ctx, { sip_code: sipCode }));
+    return this;
+  }
+
+  attachCampaign(agent: Agent, campaignCode: string): this {
+    const ctx = this._healthCtx.createCtx();
+    this._tasks.push(() => agent._serveCampaign(ctx, campaignCode));
+    return this;
+  }
+
+  async run(): Promise<void> {
+    await using _server = await getHealthServer(this._healthCtx);
+    await Promise.all(this._tasks.map((task) => task()));
+  }
+}

package/src/testing/session.ts

@@ -7,7 +7,7 @@ import { _generate } from "../helpers/llm.ts";
 
 type SessionEvent = InjectASR | BotTTS;
 
-const _evalResponseSchema = z.object({
+export const _evalResponseSchema = z.object({
   results: z.array(
     z.object({
       passed: z.boolean(),
@@ -166,28 +166,8 @@ ${transcript || "(empty — no conversation occurred)"}
 Criteria:
 ${criteriaList}`;
 
-    const evalSchema = {
-      type: "object",
-      properties: {
-        results: {
-          type: "array",
-          items: {
-            type: "object",
-            properties: {
-              passed: { type: "boolean" },
-              reasoning: { type: "string" },
-            },
-            required: ["passed"],
-            additionalProperties: false,
-          },
-        },
-      },
-      required: ["results"],
-      additionalProperties: false,
-    };
-
     const evalResponse = _evalResponseSchema.parse(
-      JSON.parse(await _generate(this._client, prompt, evalSchema)),
+      JSON.parse(await _generate(this._client, prompt, z.toJSONSchema(_evalResponseSchema))),
     );
 
     if (evalResponse.results.length !== allCriteria.length) {

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.24.0";
+export const SDK_VERSION = "0.25.0";

package/dist/examples/example.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"example.test.js","sourceRoot":"","sources":["../../examples/example.test.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAGH,mDAA+C;AAC/C,sEAA+D;AAE/D,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,IAAI,CAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QAClE,MAAM,UAAU,GAAG,MAAM,iBAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,oBAAQ,EAAE,EAAE,qBAAqB,CAAC,CAAC;QAC/F,MAAM,CAAC,UAAU,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8BAA8B,EAAE,KAAK,IAAI,EAAE;QAC9C,MAAM,OAAO,GAAG,MAAM,iBAAK,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YACjD,iFAAiF;YACjF,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;YAEvD,6CAA6C;YAC7C,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QAC7B,CAAC,CAAC,CAAC;QAEH,mEAAmE;QAEnE,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,gCAAgC,EAAE,KAAK,IAAI,EAAE;QAChD,mFAAmF;QACnF,MAAM,OAAO,GAAG,MAAM,iBAAK,CAAC,YAAY,CAAC,6CAA6C,CAAC,CAAC;QAExF,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACzD,4EAA4E;QAC5E,MAAM,OAAO,GAAG,iBAAK,CAAC,KAAK,EAAE,CAAC;QAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,IAAU,EAAE,EAAE;YAC7C,IAAI,CAAC,MAAM,CACT,8GAA8G,CAC/G,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,6CAA6C,CAAC,CAAC;QAE1F,8FAA8F;QAC9F,MAAM,OAAO,CAAC,QAAQ,CAAC;YACrB,YAAY,EAAE,CAAC,sEAAsE,CAAC;YACtF,YAAY,EAAE,CAAC,2DAA2D,CAAC;SAC5E,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}