@guava-ai/guava-sdk 0.33.0 → 0.35.0

package/src/agent.ts

@@ -6,8 +6,11 @@ import {
   type Command,
   ExpertErrorCommand,
   RegisteredHooksCommand,
+  type SpeedPreset,
+  validateSpeedPreset,
 } from "./commands.ts";
 import {
+  type AgentDTMFSentEvent,
   type AgentSpeechEvent,
   type BotSessionEnded,
   type CallerSpeechEvent,
@@ -63,6 +66,7 @@ export class Agent {
   private _purpose?: string;
   private _voice?: string;
   private _ttsReplacements?: Record<string, string>;
+  private _speechSpeed?: SpeedPreset;
   private _acceptDtmfForNumbers: boolean;
   private _logger: Logger;
 
@@ -93,7 +97,8 @@ export class Agent {
   > = {};
   private _onSessionEnd?: (call: Call, event: BotSessionEnded) => Promise<void>;
   private _onEscalate?: (call: Call, event: EscalateEvent) => Promise<void>;
-  private _onDtmf?: (call: Call, event: DTMFPressedEvent) => Promise<void>;
+  private _onCallerDtmf?: (call: Call, event: DTMFPressedEvent) => Promise<void>;
+  private _onAgentDtmf?: (call: Call, event: AgentDTMFSentEvent) => Promise<void>;
   private _onOutboundFailed?: (call: Call, event: OutboundCallFailed) => Promise<void>;
 
   constructor(args?: {
@@ -103,6 +108,7 @@ export class Agent {
     voice?: string;
     pronunciations?: Record<string, string>;
     acceptDtmf?: boolean;
+    speechSpeed?: SpeedPreset;
   }) {
     this._name = args?.name;
     this._organization = args?.organization;
@@ -110,6 +116,8 @@ export class Agent {
     this._voice = args?.voice;
     this._ttsReplacements = args?.pronunciations;
     this._acceptDtmfForNumbers = args?.acceptDtmf ?? true;
+    validateSpeedPreset(args?.speechSpeed); // Validate the preset name early, at construction.
+    this._speechSpeed = args?.speechSpeed;
     this._logger = getDefaultLogger();
   }
 
@@ -196,8 +204,17 @@ export class Agent {
     this._onEscalate = callback;
   }
 
+  onCallerDtmf(callback: (call: Call, event: DTMFPressedEvent) => Promise<void>): void {
+    this._onCallerDtmf = callback;
+  }
+
+  /** Alias for {@link onCallerDtmf}; will be marked deprecated in a future release. */
   onDtmf(callback: (call: Call, event: DTMFPressedEvent) => Promise<void>): void {
-    this._onDtmf = callback;
+    this._onCallerDtmf = callback;
+  }
+
+  onAgentDtmf(callback: (call: Call, event: AgentDTMFSentEvent) => Promise<void>): void {
+    this._onAgentDtmf = callback;
   }
 
   onOutboundFailed(callback: (call: Call, event: OutboundCallFailed) => Promise<void>): void {
@@ -260,7 +277,7 @@ export class Agent {
   async listenPhone(phoneNumber: string): Promise<void> {
     const healthCtx = new HealthContext();
     await using _server = await getHealthServer(healthCtx);
-    return this._listenInbound(healthCtx, { agent_number: phoneNumber });
+    return await this._listenInbound(healthCtx, { agent_number: phoneNumber });
   }
 
   async listenWebrtc(webrtcCode?: string): Promise<void> {
@@ -270,13 +287,13 @@ export class Agent {
     }
     const healthCtx = new HealthContext();
     await using _server = await getHealthServer(healthCtx);
-    return this._listenInbound(healthCtx, { webrtc_code: webrtcCode });
+    return await this._listenInbound(healthCtx, { webrtc_code: webrtcCode });
   }
 
   async listenSip(sipCode: string): Promise<void> {
     const healthCtx = new HealthContext();
     await using _server = await getHealthServer(healthCtx);
-    return this._listenInbound(healthCtx, { sip_code: sipCode });
+    return await this._listenInbound(healthCtx, { sip_code: sipCode });
   }
 
   async callLocal(variables: Record<string, any> = {}): Promise<void> {
@@ -483,8 +500,16 @@ export class Agent {
         );
       }
     } else if (event.event_type === "dtmf") {
-      if (this._onDtmf !== undefined) {
-        await this._invokeHandler(call, "onDtmf", false, () => this._onDtmf!(call, event));
+      if (this._onCallerDtmf !== undefined) {
+        await this._invokeHandler(call, "onCallerDtmf", false, () =>
+          this._onCallerDtmf!(call, event),
+        );
+      }
+    } else if (event.event_type === "agent-dtmf") {
+      if (this._onAgentDtmf !== undefined) {
+        await this._invokeHandler(call, "onAgentDtmf", false, () =>
+          this._onAgentDtmf!(call, event),
+        );
       }
     } else if (event.event_type === "escalate") {
       if (this._onEscalate !== undefined) {
@@ -523,6 +548,7 @@ export class Agent {
       agentPurpose: this._purpose,
       organizationName: this._organization,
       voice: this._voice,
+      speechSpeed: this._speechSpeed,
       pronunciations: this._ttsReplacements,
     });
     await call.sendCommand(RegisteredHooksCommand, {
@@ -532,6 +558,7 @@ export class Agent {
       has_on_action_requested: this._onActionRequested !== undefined,
       has_on_escalate: this._onEscalate !== undefined,
       accept_dtmf_for_numbers: this._acceptDtmfForNumbers,
+      has_on_agent_dtmf: this._onAgentDtmf !== undefined,
     });
     if (this._onCallStart !== undefined) {
       await this._onCallStart(call);
@@ -897,6 +924,7 @@ Choose "speak" and provide your next utterance, or choose "hangup" if the conver
       voice: this._voice,
       pronunciations: this._ttsReplacements,
       acceptDtmf: this._acceptDtmfForNumbers,
+      speechSpeed: this._speechSpeed,
     });
     cloned._onCallReceived = this._onCallReceived;
     cloned._onCallStart = this._onCallStart;
@@ -912,7 +940,8 @@ Choose "speak" and provide your next utterance, or choose "hangup" if the conver
     cloned._onActionHandlers = { ...this._onActionHandlers };
     cloned._onSessionEnd = this._onSessionEnd;
     cloned._onEscalate = this._onEscalate;
-    cloned._onDtmf = this._onDtmf;
+    cloned._onCallerDtmf = this._onCallerDtmf;
+    cloned._onAgentDtmf = this._onAgentDtmf;
     cloned._onOutboundFailed = this._onOutboundFailed;
     return cloned;
   }
@@ -1009,7 +1038,7 @@ Choose "speak" and provide your next utterance, or choose "hangup" if the conver
   async attachCampaign(campaignCode: string): Promise<void> {
     const healthCtx = new HealthContext();
     await using _server = await getHealthServer(healthCtx);
-    return this._serveCampaign(healthCtx, campaignCode);
+    return await this._serveCampaign(healthCtx, campaignCode);
   }
 
   /* ===== Aliases to be removed at some point. ===== */

package/src/call.ts

@@ -2,6 +2,7 @@ import { type Logger, getDefaultLogger } from "./logging.ts";
 import {
   type Command,
   SetPersona,
+  type SpeedPreset,
   SetLanguageModeCommand,
   type Language,
   SetTaskCommand,
@@ -180,6 +181,7 @@ export class Call {
     agentName?: string;
     agentPurpose?: string;
     voice?: string;
+    speechSpeed?: SpeedPreset;
     pronunciations?: Record<string, string>;
   }) {
     await this.sendCommand(SetPersona, {
@@ -188,6 +190,7 @@ export class Call {
       agent_name: args.agentName,
       agent_purpose: args.agentPurpose,
       voice: args.voice,
+      tts_speed: args.speechSpeed,
       tts_replacements: args.pronunciations,
     });
   }

package/src/commands.ts

@@ -57,12 +57,27 @@ export const AnswerQuestionCommand = z.strictObject({
 });
 export type AnswerQuestionCommand = z.input<typeof AnswerQuestionCommand>;
 
+export const SpeedPreset = z.enum(["x-slow", "slow", "medium", "fast", "x-fast"]);
+export type SpeedPreset = z.infer<typeof SpeedPreset>;
+
+/**
+ * @description throw on an unrecognized speech speed preset, with the valid presets listed
+ */
+export function validateSpeedPreset(speed: unknown): void {
+  if (speed !== undefined && !SpeedPreset.safeParse(speed).success) {
+    throw new Error(
+      `speechSpeed must be one of ${JSON.stringify(SpeedPreset.options)} (got ${JSON.stringify(speed)}).`,
+    );
+  }
+}
+
 export const SetPersona = z.strictObject({
   command_type: z.literal("set-persona"),
   agent_name: z.string().optional(),
   organization_name: z.string().optional(),
   agent_purpose: z.string().optional(),
   voice: z.string().optional(),
+  tts_speed: SpeedPreset.optional(),
   tts_replacements: z.record(z.string().min(1), z.string()).optional(),
 });
 export type SetPersona = z.input<typeof SetPersona>;
@@ -98,6 +113,7 @@ export const RegisteredHooksCommand = z.strictObject({
   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),
+  has_on_agent_dtmf: z.boolean().optional().default(false),
 });
 export type RegisteredHooksCommand = z.input<typeof RegisteredHooksCommand>;
 

package/src/events.ts

@@ -99,6 +99,7 @@ export const BotSessionEnded = z.object({
     "voicemail",
   ]),
   dnc: z.boolean().default(false),
+  pickup: z.boolean().default(true),
 });
 export type BotSessionEnded = z.infer<typeof BotSessionEnded>;
 
@@ -153,6 +154,17 @@ export const DTMFPressedEvent = z.object({
 });
 export type DTMFPressedEvent = z.infer<typeof DTMFPressedEvent>;
 
+/**
+ * The agent pressed DTMF digits, either on its own after `call.setAgentDtmf(true)`
+ * or because the developer called `call.sendDtmf(...)`; `requested_by` says which.
+ */
+export const AgentDTMFSentEvent = z.object({
+  event_type: z.literal("agent-dtmf"),
+  digits: z.array(z.enum(DTMF_DIGITS)),
+  requested_by: z.enum(["agent", "developer"]).default("agent"),
+});
+export type AgentDTMFSentEvent = z.infer<typeof AgentDTMFSentEvent>;
+
 export const EscalateEvent = z.object({
   event_type: z.literal("escalate"),
   requested_by: z.enum(["human", "agent"]).default("human"),
@@ -178,6 +190,7 @@ export const GuavaEvent = z.discriminatedUnion("event_type", [
   ExecuteActionEvent,
   EscalateEvent,
   DTMFPressedEvent,
+  AgentDTMFSentEvent,
 ]);
 export type GuavaEvent = z.infer<typeof GuavaEvent>;
 

package/src/index.ts

@@ -14,10 +14,12 @@ export { Logger, getConsoleLogger, getDefaultLogger } from "./logging.ts";
 export { Agent, CallInfo } from "./agent.ts";
 export { Call, DEFAULT_REACH_PERSON_OUTCOMES } from "./call.ts";
 export type { ReachPersonOutcome } from "./call.ts";
+export type { SpeedPreset, Language } from "./commands.ts";
 export type {
   BotSessionEnded,
   TerminationReason,
   DTMFPressedEvent,
+  AgentDTMFSentEvent,
   DTMFDigit,
   OutboundCallFailed,
 } from "./events.ts";

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.33.0";
+export const SDK_VERSION = "0.35.0";