@guava-ai/guava-sdk 0.23.0 → 0.25.0

package/src/call.ts

@@ -9,6 +9,7 @@ import {
   TransferCommand,
   ReadScriptCommand,
   RetryTaskCommand,
+  SetAgentDTMFCommand,
 } from "./commands.ts";
 import type * as z from "zod";
 import type {
@@ -20,6 +21,7 @@ import type {
 } from "./action-item.ts";
 import { Say } from "./action-item.ts";
 import { telemetryClient } from "./telemetry.ts";
+import type { CallInfo } from "./socket/call-info.ts";
 
 export type TaskObjective =
   | { objective: string }
@@ -31,8 +33,33 @@ 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;
+  private _callInfo: CallInfo;
   protected _commandQueue: Command[] = [];
   private _variables: Record<string, any> = {};
   protected logger: Logger;
@@ -42,8 +69,17 @@ export class Call {
   // input (mutating it) (i.e. _drain should use Array.splice)
   private _drain?: (_: Command[]) => Promise<void>;
   _fieldValues: Record<string, unknown> = {};
+  _fieldKeysByTaskId: Record<string, string[]> = {};
+
+  constructor(
+    callId: string,
+    callInfo: CallInfo,
+    variables: Record<string, any> = {},
+    logger: Logger = getDefaultLogger(),
+  ) {
+    this._callId = callId;
+    this._callInfo = callInfo;
 
-  constructor(variables: Record<string, any> = {}, logger: Logger = getDefaultLogger()) {
     // Set initial variables.
     this._variables = { ...variables };
 
@@ -51,6 +87,14 @@ export class Call {
     this.logger = logger;
   }
 
+  get id(): string {
+    return this._callId;
+  }
+
+  get callInfo(): CallInfo {
+    return this._callInfo;
+  }
+
   /**
    * @description Supply a function used to consume commands from the internal command queue.
    *
@@ -75,6 +119,10 @@ export class Call {
     }
   }
 
+  hasField(key: string): boolean {
+    return key in this._fieldValues;
+  }
+
   async sendCommand<C extends Command, Schema extends z.ZodType<C>>(
     schema: Schema,
     data: z.input<Schema>,
@@ -84,6 +132,13 @@ export class Call {
     await this.flush();
   }
 
+  async setAgentDtmf(enabled: boolean) {
+    await this.sendCommand(SetAgentDTMFCommand, {
+      command_type: "set-agent-dtmf",
+      enabled,
+    });
+  }
+
   async setLanguageMode(args: { primary?: Language; secondary?: Language[] }) {
     await this.sendCommand(SetLanguageModeCommand, {
       command_type: "set-language-mode",
@@ -128,6 +183,7 @@ export class Call {
       throw new Error("At least one of ['objective', 'checklist'] must be provided.");
     }
 
+    const fieldKeys: string[] = [];
     const action_items = checklist.map((item): ActionItem => {
       if (typeof item === "string") {
         return { item_type: "todo", description: item } satisfies TodoItem;
@@ -138,12 +194,15 @@ export class Call {
             "choiceGenerator is not compatible with the Agent / Call API. Use searchable=true and register a handler.",
           );
         }
+        fieldKeys.push(item.key);
         const { choiceGenerator: _, ...fieldData } = item;
         return { ...fieldData, is_search_field: item.searchable } satisfies SerializableFieldItem;
       }
       return item;
     });
 
+    this._fieldKeysByTaskId[taskId] = fieldKeys;
+
     await this.sendCommand(SetTaskCommand, {
       command_type: "set-task",
       task_id: taskId,
@@ -206,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
@@ -230,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",
@@ -245,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/commands.ts

@@ -94,14 +94,21 @@ export const RegisteredHooksCommand = z.strictObject({
   has_on_question: z.boolean(),
   has_on_intent: z.boolean(),
   has_on_action_requested: z.boolean().optional().default(false),
+  has_on_escalate: z.boolean().optional().default(false),
+  accept_dtmf_for_numbers: z.boolean().default(true),
 });
 export type RegisteredHooksCommand = z.input<typeof RegisteredHooksCommand>;
 
+export const ActionCandidate = z.strictObject({
+  key: z.string(),
+  description: z.string().default(""),
+});
+export type ActionCandidate = z.input<typeof ActionCandidate>;
+
 export const ActionSuggestionCommand = z.strictObject({
   command_type: z.literal("action-suggestion"),
   intent_id: z.string(),
-  action_key: z.string().nullable(),
-  action_description: z.string().default(""),
+  actions: z.array(ActionCandidate),
 });
 export type ActionSuggestionCommand = z.input<typeof ActionSuggestionCommand>;
 
@@ -120,6 +127,12 @@ export const RetryTaskCommand = z.strictObject({
 });
 export type RetryTaskCommand = z.input<typeof RetryTaskCommand>;
 
+export const SetAgentDTMFCommand = z.strictObject({
+  command_type: z.literal("set-agent-dtmf"),
+  enabled: z.boolean(),
+});
+export type SetAgentDTMFCommand = z.input<typeof SetAgentDTMFCommand>;
+
 export const AnyCommand = z.union([
   StartOutboundCallCommand,
   ListenInboundCommand,
@@ -136,6 +149,7 @@ export const AnyCommand = z.union([
   ChoiceResultCommand,
   ActionSuggestionCommand,
   RetryTaskCommand,
+  SetAgentDTMFCommand,
 ]);
 export type Command = z.input<typeof AnyCommand>;
 

package/src/events.ts

@@ -14,12 +14,14 @@ export const InboundCallEvent = z.object({
 export type InboundCallEvent = z.infer<typeof InboundCallEvent>;
 
 /**
- * @description The caller has said something.
+ * @description The caller has said something. For utterances with the same id,
+ * all but the latest is out of date.
  */
 export const CallerSpeechEvent = z.object({
   event_type: z.literal("caller-speech"),
 
   utterance: z.string(),
+  utterance_id: z.string().optional(),
 });
 export type CallerSpeechEvent = z.infer<typeof CallerSpeechEvent>;
 
@@ -145,9 +147,16 @@ export type DTMFDigit =
 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"]),
+  recent_digits: z.string().default(""),
 });
 export type DTMFPressedEvent = z.infer<typeof DTMFPressedEvent>;
 
+export const EscalateEvent = z.object({
+  event_type: z.literal("escalate"),
+  requested_by: z.enum(["human", "agent"]).default("human"),
+});
+export type EscalateEvent = z.infer<typeof EscalateEvent>;
+
 export const GuavaEvent = z.discriminatedUnion("event_type", [
   SessionStartedEvent,
   InboundCallEvent,
@@ -165,6 +174,7 @@ export const GuavaEvent = z.discriminatedUnion("event_type", [
   ChoiceQueryEvent,
   ActionRequestEvent,
   ExecuteActionEvent,
+  EscalateEvent,
   DTMFPressedEvent,
 ]);
 export type GuavaEvent = z.infer<typeof GuavaEvent>;

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/health.ts

@@ -0,0 +1,120 @@
+import { type Server, createServer } from "node:http";
+import { getDefaultLogger, type Logger } from "./logging.ts";
+
+export type HealthState = "starting" | "live" | "stopped";
+
+export class HealthContext {
+  private _state: HealthState = "starting";
+
+  setState(newState: HealthState): void {
+    this._state = newState;
+  }
+
+  ready(): void {
+    this.setState("live");
+  }
+
+  stopped(): void {
+    this.setState("stopped");
+  }
+
+  isLive(): boolean {
+    return this._state === "live";
+  }
+}
+
+export class MultiHealthContext {
+  private _ctxs: HealthContext[] = [];
+
+  createCtx(): HealthContext {
+    const ctx = new HealthContext();
+    this._ctxs.push(ctx);
+    return ctx;
+  }
+
+  isLive(): boolean {
+    return this._ctxs.length > 0 && this._ctxs.every((ctx) => ctx.isLive());
+  }
+}
+
+export interface HealthServerOptions {
+  host?: string;
+  port?: number;
+  logger?: Logger;
+}
+
+export class HealthServer implements AsyncDisposable {
+  private readonly _server: Server;
+  private readonly _logger: Logger;
+  private _stopping: Promise<void> | null = null;
+
+  private constructor(server: Server, logger: Logger) {
+    this._server = server;
+    this._logger = logger;
+  }
+
+  static async start(
+    healthCtx: HealthContext | MultiHealthContext,
+    options: HealthServerOptions = {},
+  ): Promise<HealthServer> {
+    const host = options.host ?? "0.0.0.0";
+    const port = options.port ?? 4828;
+    const logger = options.logger ?? getDefaultLogger();
+
+    const server = createServer((req, res) => {
+      if (req.method === "GET" && req.url === "/live") {
+        res.statusCode = healthCtx.isLive() ? 200 : 503;
+      } else {
+        res.statusCode = 404;
+      }
+      res.end();
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, host, () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+
+    logger.info("Health check server listening on http://%s:%d/live", host, port);
+    return new HealthServer(server, logger);
+  }
+
+  stop(): Promise<void> {
+    if (this._stopping) return this._stopping;
+    this._logger.info("Health check server shutting down.");
+    this._stopping = new Promise<void>((resolve, reject) => {
+      this._server.closeAllConnections();
+      this._server.close((err) => (err ? reject(err) : resolve()));
+    });
+    return this._stopping;
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.stop();
+  }
+}
+
+const NOOP_DISPOSABLE: AsyncDisposable = {
+  async [Symbol.asyncDispose]() {},
+};
+
+function isEnabled(): boolean {
+  const value = (process.env.GUAVA_HEALTH_SERVER ?? "false").toLowerCase().trim();
+  return value === "yes" || value === "true" || value === "on";
+}
+
+/**
+ * Returns an AsyncDisposable that, when the GUAVA_HEALTH_SERVER env var is
+ * truthy ("yes", "true", "on"), starts an HTTP health check server exposing
+ * `/live` on port 4828. Otherwise returns a no-op disposable. Intended for use
+ * with `await using`.
+ */
+export async function getHealthServer(
+  healthCtx: HealthContext | MultiHealthContext,
+): Promise<AsyncDisposable> {
+  if (!isEnabled()) return NOOP_DISPOSABLE;
+  return HealthServer.start(healthCtx);
+}

package/src/helpers/index.ts

@@ -0,0 +1,2 @@
+/* This file must not include the OpenAI helpers. */
+export { DatetimeFilter, DocumentQA, IntentRecognizer } from "./llm.ts";