@guava-ai/guava-sdk 0.1.0 → 0.3.0

package/src/index.ts

@@ -12,6 +12,7 @@ import {
   rejectInboundCallCommand,
   transferCommand,
   listenInboundCommand,
+  inboundTunnelCommand,
 } from "./commands.ts";
 import * as z from "zod";
 import {
@@ -21,13 +22,14 @@ import {
   decodeEvent,
   type CallerSpeechEvent,
   type AgentSpeechEvent,
+  inboundTunnelEvent,
 } from "./events.ts";
 import type { ActionItem, Field, Say, Todo } from "./action_item.ts";
 import pkgdata from "../package.json" with { type: "json" };
 import os from "node:os";
 
-const DEFAULT_BASE_URL = "wss://guava-dev.gridspace.com/guava/";
-const DEFAULT_LOG_LEVEL = "info";
+const DEFAULT_BASE_URL = "https://guava-dev.gridspace.com/";
+const DEFAULT_LOG_LEVEL = "debug";
 
 /**
  * @description convenience function for stringifying data according to a schema
@@ -39,33 +41,53 @@ function stringifyZod<Schema extends z.ZodType>(
   return JSON.stringify(schema.parse(data));
 }
 
+/**
+ * Interface between Guava services and user-supplied code
+ */
 export class CallController {
   private _commandQueue: Command[] = [];
   private _on_complete_current_task?: () => void;
   // private _field_values: Record<string, any>;
   private _current_task_id?: string;
-  private _logger: Logger;
+  /**
+   * @protected
+   * @description logger used to emit diagnostics
+   */
+  protected logger: Logger;
   // drain functions are expected to cleanup
   // the part of the queue that is successfully sent from its
   // input (mutating it) (i.e. _drain should use Array.splice)
   private _drain?: (_: Command[]) => Promise<void>;
+  private _fieldValues: Record<string, unknown> = {};
 
   constructor(logger: Logger) {
     // Set up the default logger.
-    this._logger = logger;
+    this.logger = logger;
   }
 
+  /**
+   * @description Supply a function used to consume commands from the internal command queue.
+   *
+   * The function is expected to remove from the argument array commands that it has handled (iterating
+   * through the result of `Array.splice(0)` is sufficient)
+   */
   setDrain(newDrain: (_: Command[]) => Promise<void>) {
     this._drain = newDrain;
     this.flush();
   }
 
+  /**
+   * @description [inbound] receive a call, and process further.
+   */
   protected async acceptCall() {
     await this.sendCommand(acceptInboundCallCommand, {
       command_type: "accept-inbound",
     });
   }
 
+  /**
+   * @description read a span of text verbatim
+   */
   protected async readScript(script: string) {
     await this.sendCommand(readScriptCommand, {
       command_type: "read-script",
@@ -73,16 +95,22 @@ export class CallController {
     });
   }
 
+  /**
+   * @description [inbound] reject a call
+   */
   protected async rejectCall() {
     await this.sendCommand(rejectInboundCallCommand, {
       command_type: "reject-inbound",
     });
   }
 
-  protected async addInfo(info: string) {
+  protected async addInfo(_info: string) {
     throw new Error("not implemeneted");
   }
 
+  /**
+   * @description read a span of text non-verbatim
+   */
   protected async sendInstruction(instruction: string) {
     await this.sendCommand(sendInstructionCommand, {
       command_type: "send-instruction",
@@ -90,49 +118,87 @@ export class CallController {
     });
   }
 
-  protected async setPersona(
-    organization_name?: string,
-    agent_name?: string,
-    agent_purpose?: string,
-  ) {
+  /**
+   * @description provide identifiers the agent will use to identify the virtual agent
+   */
+  protected async setPersona(args: {
+    organizationName?: string;
+    agentName?: string;
+    agentPurpose?: string;
+  }) {
     await this.sendCommand(setPersona, {
       command_type: "set-persona",
-      organization_name: organization_name,
-      agent_name: agent_name,
-      agent_purpose: agent_purpose,
+      organization_name: args.organizationName,
+      agent_name: args.agentName,
+      agent_purpose: args.agentPurpose,
     });
   }
 
-  protected async setTask(
-    objective: string = "",
-    checklist?: (Field | Say | string)[],
-    on_complete: (...c) => void = () => {},
-    ...args
+  /**
+   * @description direct the agent to collect information
+   * @param goal {} an objective string and/or a checklist of information to collect
+   * @param on_complete {} a callback to call once the information is available from the agent
+   * @param args {} arguments to pass through to the `on_complete` callback
+   */
+  protected setTask(
+    goal: TaskObjective,
+    on_complete: (...c: any[]) => void = () => {},
+    ...args: any[]
   ) {
-    if (!objective && !checklist) {
-      throw new Error(
-        "At least one of args ['objective','checklist'] must be provided.",
-      );
-    }
     this._current_task_id = Math.random().toString(16).substring(2, 8);
-    checklist = checklist ?? [];
-    const action_items = checklist.map((item) =>
-      typeof item == "string"
-        ? ({
-            item_type: "todo",
-            description: item,
-          } satisfies Todo)
-        : item,
-    ) satisfies ActionItem[];
-    this._on_complete_current_task = on_complete.apply(this, args);
-    this.sendCommand(setTaskCommand, {
-      command_type: "set-task",
-      task_id: this._current_task_id,
-      objective: objective,
-      action_items: action_items,
+    this._on_complete_current_task = on_complete.bind(this, ...args);
+    if (!("checklist" in goal)) {
+      this.sendCommand(setTaskCommand, {
+        command_type: "set-task",
+        task_id: this._current_task_id,
+        objective: goal.objective,
+        action_items: [],
+      });
+    } else {
+      const action_items = goal.checklist.map((item) =>
+        typeof item == "string"
+          ? ({
+              item_type: "todo",
+              description: item,
+            } satisfies Todo)
+          : item,
+      ) satisfies ActionItem[];
+      this.sendCommand(setTaskCommand, {
+        command_type: "set-task",
+        task_id: this._current_task_id,
+        objective: goal.objective ?? "",
+        action_items,
+      });
+    }
+  }
+
+  /**
+   * @description direct the agent to collect information, continuing execution once the agent has collected the information
+   * @param goal {} an objective string and/or a checklist of information to collect
+   */
+  protected async awaitTask(goal: TaskObjective): Promise<void> {
+    return new Promise((resolve) => {
+      this.setTask(goal, (_args) => {
+        resolve();
+      });
     });
   }
 
+  /**
+   * @description retrieve a piece of information that the agent has collected
+   * @param key {string} key of the field checklist item
+   */
+  protected getField(key: string) {
+    if (key in this._fieldValues) {
+      return this._fieldValues[key];
+    } else {
+      return null;
+    }
+  }
+
+  /**
+   * @description [inbound] hang up an accepted call
+   */
   protected async hangup(final_instructions: string = "") {
     let instructions: string;
     if (final_instructions) {
@@ -144,6 +210,9 @@ export class CallController {
     this.sendInstruction(instructions);
   }
 
+  /**
+   * @description transfer an accepted call
+   */
   protected transfer(to_number: string, transfer_message?: string) {
     const message = transfer_message ?? "I'm transferring you now";
     this.sendCommand(transferCommand, {
@@ -159,7 +228,7 @@ export class CallController {
   ) {
     const command = schema.parse(data);
     this._commandQueue.push(command);
-    this._logger.debug(`Command queued: ${JSON.stringify(command)}`);
+    this.logger.debug(`Command queued: ${JSON.stringify(command)}`);
     await this.flush();
   }
 
@@ -174,7 +243,7 @@ export class CallController {
       this.onAgentSpeech(event);
     } else if (event.event_type == "agent-question") {
       try {
-        this._logger.info(`Received question from bot: ${event.question}`);
+        this.logger.info(`Received question from bot: ${event.question}`);
         const answer = await this.onQuestion(event.question);
         await this.sendCommand(answerQuestionCommand, {
           command_type: "answer-question",
@@ -182,7 +251,7 @@ export class CallController {
           answer: answer,
         });
       } catch (e) {
-        this._logger.error("Error occured while answering question.");
+        this.logger.error("Error occured while answering question.");
         await this.sendCommand(answerQuestionCommand, {
           command_type: "answer-question",
           question_id: event.question_id,
@@ -190,14 +259,14 @@ export class CallController {
         });
       }
     } else if (event.event_type == "intent") {
-      this._logger.info(
+      this.logger.info(
         `Received intent ${event.intent_id} from bot: ${event.intent_summary}`,
       );
       const intent_response = await this.onIntent(event.intent_summary);
       if (intent_response) {
-        const response_str = `Responding to intent ${event.intent_id}: ${event.intent_summary}`;
-        this._logger.info(response_str);
-        this.sendInstruction(response_str);
+        const response_str = `Responding to intent ${event.intent_id}: ${intent_response}`;
+        this.logger.info(response_str);
+        this.sendInstruction(intent_response);
       }
     } else if (event.event_type == "task-done") {
       // ignore obsolete task_completed events
@@ -210,7 +279,12 @@ export class CallController {
         }
       }
     } else if (event.event_type == "action-item-done") {
-      // self._field_values...
+      this._fieldValues[event.key] = event.payload;
+      if (event.key && event.payload) {
+        this.logger.info(
+          `Field ${event.key} updated with value: ${event.payload}`,
+        );
+      }
     } else if (event.event_type == "inbound-call") {
       this.onIncomingCall(event.caller_number);
     } else if (
@@ -219,28 +293,51 @@ export class CallController {
     ) {
       // no-op, don't warn
     } else if (event.event_type == "error") {
-      this._logger.error(`The Guava agent reported an error: ${event.content}`);
+      this.logger.error(`The Guava agent reported an error: ${event.content}`);
     } else {
-      this._logger.warn(`Unhandled event: ${JSON.stringify(event)}`);
+      this.logger.warn(`Unhandled event: ${JSON.stringify(event)}`);
     }
   }
 
   // callbacks
 
   /**
-   * @requires super call
+   * @abstract
+   * @description called when an inbound call is received. The overriding function must start
+   * with `await super.onIncomingCall(from_number)`
    */
   async onIncomingCall(from_number?: string) {
     await this.onCallStart();
   }
 
+  /**
+   * @abstract
+   * @description called when a call is connected by the API, whether inbound or outbound
+   */
   async onCallStart(): Promise<void> {}
 
+  /**
+   * @abstract
+   * @description called when the caller speaks to the agent.
+   */
   async onCallerSpeech(event: CallerSpeechEvent) {}
+  /**
+   * @abstract
+   * @description called when the agent speaks to the caller.
+   */
   async onAgentSpeech(event: AgentSpeechEvent) {}
+  /**
+   * @abstract
+   * @description called when the caller expresses a task they wish to execute
+   */
   async onIntent(intent: string): Promise<string | null> {
     return "Unfortunately I'm not able to help with that.";
   }
+  /**
+   * @abstract
+   * @description called when the agent needs to respond to a question that it doesn't know
+   * the answer to.
+   */
   async onQuestion(question: string): Promise<string> {
     return "I don't have an answer to that question.";
   }
@@ -250,8 +347,12 @@ export type InboundConnection =
   | { agent_number: string }
   | { webrtc_code: string };
 
-const ws_start = /^ws:\/\//;
-const wss_start = /^wss:\/\//;
+export type TaskObjective =
+  | { objective: string }
+  | { objective?: string; checklist: (Field | Say | string)[] };
+
+const http_start = /^http:\/\//;
+const https_start = /^https:\/\//;
 export class Client {
   private _apiKey: string;
   private _baseUrl: string;
@@ -289,17 +390,17 @@ export class Client {
     }
   }
 
-  private getHttpBase() {
-    if (ws_start.test(this._baseUrl)) {
+  private getWebsocketBase() {
+    if (http_start.test(this._baseUrl)) {
       return `ws://${this._baseUrl.substring("ws://".length)}`;
-    } else if (wss_start.test(this._baseUrl)) {
+    } else if (https_start.test(this._baseUrl)) {
       return `wss://${this._baseUrl.substring("wss://".length)}`;
     } else {
       throw new Error(`Invalid base URL: ${this._baseUrl}}`);
     }
   }
 
-  private getWebsocketBase() {
+  private getHttpBase() {
     return this._baseUrl;
   }
 
@@ -314,16 +415,21 @@ export class Client {
     };
   }
 
+  /**
+   * @description use the Guava API to call out to a number
+   */
   createOutbound(
     fromNumber: string | undefined,
     toNumber: string,
     callControllerFactory?: (logger: Logger) => CallController,
   ) {
-    const url = new URL("create-outbound", this.getWebsocketBase()).toString();
+    const url = new URL("v1/create-outbound", this.getWebsocketBase());
     const ws = new WebSocket(url, {
       headers: this.headers(),
     });
-    const callController = (callControllerFactory ?? ((_) => undefined))(this._logger);
+    const callController = (callControllerFactory ?? ((_) => undefined))(
+      this._logger,
+    );
 
     ws.addEventListener("open", async (_ev) => {
       ws.send(
@@ -356,7 +462,7 @@ export class Client {
     });
   }
 
-  replaceHandler(newHandler?: (_: WebSocket.MessageEvent) => void) {
+  private replaceHandler(newHandler?: (_: WebSocket.MessageEvent) => void) {
     if (this.messageHandler) {
       this._ws?.removeEventListener("message", this.messageHandler);
     }
@@ -386,8 +492,6 @@ export class Client {
       // move to next state
       this.replaceHandler(this.initializedOutbound.bind(this));
     }
-
-    // this._controller?.flush();
   }
 
   private async initializedOutbound(ev: WebSocket.MessageEvent) {
@@ -410,26 +514,41 @@ export class Client {
         this._ws.close();
       }
     }
-
-    // this._controller?.flush();
   }
 
-  setInboundHandler(
+  async setInboundHandler(
     agent_number: string,
     public_url: string,
     inbound_token: string,
   ) {
-    // TODO
+    const response = await fetch(
+      new URL(`v1/inbound-handler/${agent_number}`, this.getHttpBase()),
+      {
+        method: "PUT",
+        headers: this.headers(),
+        body: JSON.stringify({
+          handler_url: public_url,
+          handler_token: inbound_token,
+        }),
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error("Failed to set inbound handler");
+    }
   }
 
-  // why use a typevar here and not for outbound?
+  /**
+   * @description use the Guava API to receive calls at a given number
+   */
   listenInbound<U extends CallController>(
     conn: InboundConnection,
-    controller_class: U,
+    controllerClassFactory: (logger: Logger) => U,
   ) {
-    const call_controllers: Record<string, U> = {};
+    const callControllers: Record<string, U> = {};
 
-    const url = new URL("listen-inbound", this.getWebsocketBase()).toString();
+    // return a way to *stop* listening
+    const url = new URL("v1/listen-inbound", this.getWebsocketBase());
     const ws = new WebSocket(url, {
       headers: this.headers(),
     });
@@ -441,23 +560,72 @@ export class Client {
       webrtc_code = conn.webrtc_code;
     }
 
-    ws.send(
-      stringifyZod(listenInboundCommand, {
-        command_type: "listen-inbound",
-        agent_number: agent_number,
-        webrtc_code: webrtc_code,
-      }),
-    );
-
     this._logger.info(`Listening for calls to ${agent_number ?? webrtc_code}`);
 
     if (webrtc_code) {
-      // converted to print, but should be logger?
       const debugurl = new URL(
         `debug-webrtc?webrtc_code=${webrtc_code}`,
         this.getHttpBase(),
       );
-      this._logger.debug(`WebRTC DebugURL: ${new URL("debug-webrtc?we")}`);
+      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();
   }
 }