@guava-ai/guava-sdk 0.2.0 → 0.4.0

package/src/index.ts

@@ -1,358 +1,37 @@
 import WebSocket from "ws";
-import { type Logger, getConsoleLogger } from "./logging.ts";
+import { type Logger, getDefaultLogger } from "./logging.ts";
 import {
-  acceptInboundCallCommand,
-  type Command,
-  startOutboundCallCommand,
-  setPersona,
-  setTaskCommand,
-  answerQuestionCommand,
-  sendInstructionCommand,
-  readScriptCommand,
-  rejectInboundCallCommand,
-  transferCommand,
-  listenInboundCommand,
-  inboundTunnelCommand,
+  StartOutboundCallCommand,
+  ListenInboundCommand,
+  InboundTunnelCommand,
 } from "./commands.ts";
 import * as z from "zod";
-import {
-  errorEvent,
-  type GuavaEvent,
-  sessionStartedEvent,
-  decodeEvent,
-  type CallerSpeechEvent,
-  type AgentSpeechEvent,
-  inboundTunnelEvent,
-} from "./events.ts";
-import type { ActionItem, Field, Say, Todo } from "./action_item.ts";
+import { ErrorEvent, SessionStartedEvent, decodeEvent, InboundTunnelEvent } from "./events.ts";
 import pkgdata from "../package.json" with { type: "json" };
 import os from "node:os";
+import { getBaseUrl, fetchOrThrow } from "./utils.ts";
+import { telemetryClient } from "./telemetry.ts";
+import type { CallController } from "./call-controller.ts";
+export { CallController, type TaskObjective } from "./call-controller.ts";
+export { Say, Field } from "./action_item.ts";
+
+const SDK_NAME = "typescript-sdk";
 
-const DEFAULT_BASE_URL = "https://guava-dev.gridspace.com/";
-const DEFAULT_LOG_LEVEL = "debug";
+let firstClient = false;
 
 /**
  * @description convenience function for stringifying data according to a schema
  */
-function stringifyZod<Schema extends z.ZodType>(
-  schema: Schema,
-  data: z.input<Schema>,
-): string {
+function stringifyZod<Schema extends z.ZodType>(schema: Schema, data: z.input<Schema>): string {
   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;
-  /**
-   * @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;
-  }
-
-  /**
-   * @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",
-      script: script,
-    });
-  }
-
-  /**
-   * @description [inbound] reject a call
-   */
-  protected async rejectCall() {
-    await this.sendCommand(rejectInboundCallCommand, {
-      command_type: "reject-inbound",
-    });
-  }
-
-  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",
-      instruction: instruction,
-    });
-  }
-
-  /**
-   * @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: args.organizationName,
-      agent_name: args.agentName,
-      agent_purpose: args.agentPurpose,
-    });
-  }
-
-  /**
-   * @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[]
-  ) {
-    this._current_task_id = Math.random().toString(16).substring(2, 8);
-    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) {
-      instructions = `Start ending the conversation. Here are your final instructions: ${final_instructions} Once you've completed the final instructions, naturally end the conversation and hang up the call.`;
-    } else {
-      instructions = "Naturally end the conversation and hang up the call.";
-    }
-
-    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, {
-      command_type: "transfer-call",
-      transfer_message: message,
-      to_number: to_number,
-    });
-  }
-
-  private async sendCommand<C extends Command, Schema extends z.ZodType<C>>(
-    schema: Schema,
-    data: z.input<Schema>,
-  ) {
-    const command = schema.parse(data);
-    this._commandQueue.push(command);
-    this.logger.debug(`Command queued: ${JSON.stringify(command)}`);
-    await this.flush();
-  }
-
-  private async flush() {
-    await this._drain?.call(this, this._commandQueue);
-  }
-
-  async onEvent(event: GuavaEvent) {
-    if (event.event_type == "caller-speech") {
-      this.onCallerSpeech(event);
-    } else if (event.event_type == "agent-speech") {
-      this.onAgentSpeech(event);
-    } else if (event.event_type == "agent-question") {
-      try {
-        this.logger.info(`Received question from bot: ${event.question}`);
-        const answer = await this.onQuestion(event.question);
-        await this.sendCommand(answerQuestionCommand, {
-          command_type: "answer-question",
-          question_id: event.question_id,
-          answer: answer,
-        });
-      } catch (e) {
-        this.logger.error("Error occured while answering question.");
-        await this.sendCommand(answerQuestionCommand, {
-          command_type: "answer-question",
-          question_id: event.question_id,
-          answer: "An error occured and the question could not be answered.",
-        });
-      }
-    } else if (event.event_type == "intent") {
-      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}: ${intent_response}`;
-        this.logger.info(response_str);
-        this.sendInstruction(intent_response);
-      }
-    } else if (event.event_type == "task-done") {
-      // ignore obsolete task_completed events
-      if (event.task_id == this._current_task_id) {
-        // assertion is implied
-        const on_complete = this._on_complete_current_task;
-        this._on_complete_current_task = undefined;
-        if (on_complete) {
-          on_complete();
-        }
-      }
-    } else if (event.event_type == "action-item-done") {
-      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 (
-      event.event_type == "outbound-call-connected" ||
-      event.event_type == "bot-session-ended"
-    ) {
-      // no-op, don't warn
-    } else if (event.event_type == "error") {
-      this.logger.error(`The Guava agent reported an error: ${event.content}`);
-    } else {
-      this.logger.warn(`Unhandled event: ${JSON.stringify(event)}`);
-    }
-  }
-
-  // callbacks
-
-  /**
-   * @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.";
-  }
-}
-
-export type InboundConnection =
-  | { agent_number: string }
-  | { webrtc_code: string };
-
-export type TaskObjective =
-  | { objective: string }
-  | { objective?: string; checklist: (Field | Say | string)[] };
+export type InboundConnection = { agent_number: string } | { webrtc_code: string };
 
 const http_start = /^http:\/\//;
 const https_start = /^https:\/\//;
+
+@telemetryClient.trackClass()
 export class Client {
   private _apiKey: string;
   private _baseUrl: string;
@@ -361,21 +40,19 @@ export class Client {
   private _controller?: CallController;
   private messageHandler?: (_: WebSocket.MessageEvent) => void;
 
-  constructor(apiKey?: string, baseUrl?: string, logger?: Logger) {
+  constructor(apiKey?: string, baseUrl?: string, logger?: Logger, captureWarnings: boolean = true) {
     // Set up the default logger.
     if (logger) {
       this._logger = logger;
     } else {
-      this._logger = getConsoleLogger(DEFAULT_LOG_LEVEL);
+      this._logger = getDefaultLogger();
     }
 
     // Resolve the API base URL.
     if (baseUrl) {
       this._baseUrl = baseUrl;
-    } else if (process.env.GUAVA_BASE_URL) {
-      this._baseUrl = process.env.GUAVA_BASE_URL;
     } else {
-      this._baseUrl = DEFAULT_BASE_URL;
+      this._baseUrl = getBaseUrl();
     }
 
     // Resolve the API key.
@@ -388,6 +65,19 @@ export class Client {
         "Guava API key must be provided either as argument to client constructor, or in environment variable GUAVA_API_KEY.",
       );
     }
+
+    if (!firstClient) {
+      firstClient = true;
+
+      if (captureWarnings) {
+        process.on("warning", (warning) => {
+          this._logger.warn(warning.toString());
+        });
+      }
+
+      telemetryClient.setSdkHeaders(this.headers());
+      this._checkSdkDeprecation();
+    }
   }
 
   private getWebsocketBase() {
@@ -410,37 +100,66 @@ export class Client {
       "x-guava-platform": os.platform(),
       "x-guava-runtime": process.release.name,
       "x-guava-runtime-version": process.version,
-      "x-guava-sdk": "typescript-sdk",
+      "x-guava-sdk": SDK_NAME,
       "x-guava-sdk-version": pkgdata.version,
     };
   }
 
+  private async _checkSdkDeprecation() {
+    this._logger.debug(`Checking deprecation for SDK ${SDK_NAME}, ${pkgdata.version}.`);
+    try {
+      const url = new URL("v1/check-sdk-deprecation", this.getHttpBase());
+      url.searchParams.set("sdk_name", SDK_NAME);
+      url.searchParams.set("sdk_version", pkgdata.version);
+      const response = await fetchOrThrow(url, {
+        method: "POST",
+        headers: this.headers(),
+      });
+      const body = (await response.json()) as { deprecation_status: string };
+      if (body.deprecation_status === "supported") {
+        this._logger.info("SDK version still supported.");
+      } else if (body.deprecation_status === "deprecated") {
+        process.emitWarning(
+          "This SDK version is deprecated. Please update to a newer version of the SDK.",
+        );
+      } else {
+        this._logger.warn("SDK deprecation status unknown.");
+      }
+    } catch (e) {
+      this._logger.error("Encountered issue while checking for deprecation.");
+    }
+  }
+
   /**
    * @description use the Guava API to call out to a number
    */
-  createOutbound(
-    fromNumber: string | undefined,
-    toNumber: string,
-    callControllerFactory?: (logger: Logger) => CallController,
-  ) {
+  createOutbound(fromNumber: string | undefined, toNumber: string, callController: CallController) {
     const url = new URL("v1/create-outbound", this.getWebsocketBase());
     const ws = new WebSocket(url, {
       headers: this.headers(),
     });
-    const callController = (callControllerFactory ?? ((_) => undefined))(
-      this._logger,
-    );
 
     ws.addEventListener("open", async (_ev) => {
       ws.send(
-        stringifyZod(startOutboundCallCommand, {
+        stringifyZod(StartOutboundCallCommand, {
           command_type: "start-outbound",
           to_number: toNumber,
           from_number: fromNumber,
         }),
       );
-      await callController?.onCallStart();
+
+      // set the callController drain function to send all commands
+      // through the now open websocket
+      callController.setDrain(async (commands) => {
+        for (const command of commands.splice(0)) {
+          this._logger.debug(`Sending command ${JSON.stringify(command)}`);
+          ws.send(JSON.stringify(command));
+        }
+      });
+
+      await callController.onCallStart();
     });
+
     ws.addEventListener("close", (_ev) => {
       // we are closing the socket, so don't trigger any other listeners
       ws.removeAllListeners();
@@ -451,15 +170,6 @@ export class Client {
     this._ws = ws;
     this._controller = callController;
     this.replaceHandler(this.uninitializedOutbound.bind(this));
-
-    // set the callController drain function to send all commands
-    // through the websocket
-    callController?.setDrain(async (commands) => {
-      for (const command of commands.splice(0)) {
-        this._logger.debug(`Sending command ${JSON.stringify(command)}`);
-        ws.send(JSON.stringify(command));
-      }
-    });
   }
 
   private replaceHandler(newHandler?: (_: WebSocket.MessageEvent) => void) {
@@ -481,14 +191,12 @@ export class Client {
     }
 
     const session_started = z
-      .union([sessionStartedEvent, errorEvent])
+      .union([SessionStartedEvent, ErrorEvent])
       .parse(JSON.parse(ev.data.toString("utf8")));
-    if (session_started.event_type == "error") {
+    if (session_started.event_type === "error") {
       throw new Error(`Outbound call failed: ${session_started.content}`);
     } else {
-      this._logger.info(
-        `Started session with ID: ${session_started.session_id}`,
-      );
+      this._logger.info(`Started session with ID: ${session_started.session_id}`);
       // move to next state
       this.replaceHandler(this.initializedOutbound.bind(this));
     }
@@ -506,38 +214,13 @@ export class Client {
       if (this._controller) {
         await this._controller.onEvent(event);
       }
-      if (
-        event.event_type == "outbound-call-failed" ||
-        event.event_type == "bot-session-ended"
-      ) {
+      if (event.event_type === "outbound-call-failed" || event.event_type === "bot-session-ended") {
         // shutdown the websocket
         this._ws.close();
       }
     }
   }
 
-  async setInboundHandler(
-    agent_number: string,
-    public_url: string,
-    inbound_token: string,
-  ) {
-    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");
-    }
-  }
-
   /**
    * @description use the Guava API to receive calls at a given number
    */
@@ -563,16 +246,13 @@ export class Client {
     this._logger.info(`Listening for calls to ${agent_number ?? webrtc_code}`);
 
     if (webrtc_code) {
-      const debugurl = new URL(
-        `debug-webrtc?webrtc_code=${webrtc_code}`,
-        this.getHttpBase(),
-      );
+      const debugurl = new URL(`debug-webrtc?webrtc_code=${webrtc_code}`, this.getHttpBase());
       this._logger.debug(`WebRTC DebugURL: ${debugurl}`);
     }
 
     ws.addEventListener("open", (_ev) => {
       ws.send(
-        stringifyZod(listenInboundCommand, {
+        stringifyZod(ListenInboundCommand, {
           command_type: "listen-inbound",
           agent_number: agent_number,
           webrtc_code: webrtc_code,
@@ -585,9 +265,7 @@ export class Client {
     });
 
     ws.addEventListener("message", (ev) => {
-      const tunnel_event = inboundTunnelEvent.parse(
-        JSON.parse(ev.data.toString("utf8")),
-      );
+      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.`,
@@ -600,7 +278,7 @@ export class Client {
               `Sending command: ${JSON.stringify(command)} for call ID: ${tunnel_event.call_id}`,
             );
             ws.send(
-              stringifyZod(inboundTunnelCommand, {
+              stringifyZod(InboundTunnelCommand, {
                 call_id: tunnel_event.call_id,
                 command,
               }),

package/src/logging.ts

@@ -8,6 +8,15 @@ const LOG_RANKS: Record<LogLevel, number> = {
   debug: 4,
 };
 
+const ANSI_RESET = "\x1b[0m";
+const LEVEL_COLORS: Record<LogLevel, string> = {
+  off: "",
+  debug: "\x1b[38;5;245m", // gray
+  info: "",
+  warn: "\x1b[38;5;214m", // orange
+  error: "\x1b[38;5;196m", // red
+};
+
 export interface Logger {
   debug(format: string, ...args: unknown[]);
   info(format: string, ...args: unknown[]);
@@ -16,10 +25,10 @@ export interface Logger {
 }
 
 function shouldLog(messageLevel: LogLevel, loggerLevel: LogLevel) {
-  if (!LOG_RANKS.hasOwnProperty(messageLevel)) {
+  if (!Object.hasOwn(LOG_RANKS, messageLevel)) {
     throw new Error(`Invalid log level: ${String(messageLevel)}`);
   }
-  if (!LOG_RANKS.hasOwnProperty(loggerLevel)) {
+  if (!Object.hasOwn(LOG_RANKS, loggerLevel)) {
     throw new Error(`Invalid logger level: ${String(loggerLevel)}`);
   }
 
@@ -28,11 +37,34 @@ function shouldLog(messageLevel: LogLevel, loggerLevel: LogLevel) {
 
 function noop(format: string, ...args: unknown[]) {}
 
-export function getConsoleLogger(loggerLevel: LogLevel): Logger {
+function makeColoredMethod(
+  fn: (...args: unknown[]) => void,
+  level: LogLevel,
+  useColor: boolean,
+): (format: string, ...args: unknown[]) => void {
+  if (!useColor) return fn.bind(console);
+  return (format: string, ...args: unknown[]) =>
+    fn(`${LEVEL_COLORS[level]}[${level}] ${format}${ANSI_RESET}`, ...args);
+}
+
+export function getConsoleLogger(loggerLevel: LogLevel, useColor = false): Logger {
   return {
-    debug: shouldLog("debug", loggerLevel) ? console.debug.bind(console) : noop,
-    info: shouldLog("info", loggerLevel) ? console.info.bind(console) : noop,
-    warn: shouldLog("warn", loggerLevel) ? console.warn.bind(console) : noop,
-    error: shouldLog("error", loggerLevel) ? console.error.bind(console) : noop,
+    debug: shouldLog("debug", loggerLevel)
+      ? makeColoredMethod(console.debug, "debug", useColor)
+      : noop,
+    info: shouldLog("info", loggerLevel) ? makeColoredMethod(console.info, "info", useColor) : noop,
+    warn: shouldLog("warn", loggerLevel) ? makeColoredMethod(console.warn, "warn", useColor) : noop,
+    error: shouldLog("error", loggerLevel)
+      ? makeColoredMethod(console.error, "error", useColor)
+      : noop,
   };
 }
+
+export function getDefaultLogger(): Logger {
+  const level = (process.env.LOG_LEVEL ?? "info").toLowerCase();
+  if (!Object.hasOwn(LOG_RANKS, level)) {
+    throw new Error(`Unknown log level in LOG_LEVEL env var: ${level}`);
+  }
+  const useColor = process.stderr.isTTY === true && !process.env.NO_COLOR;
+  return getConsoleLogger(level as LogLevel, useColor);
+}