@guava-ai/guava-sdk 0.18.0 → 0.20.0

package/src/auth.ts

@@ -0,0 +1,109 @@
+import * as fs from "node:fs";
+import { getCliConfigPath, getBaseUrl, fetchOrThrow } from "./utils.ts";
+import { getDefaultLogger } from "./logging.ts";
+
+const logger = getDefaultLogger();
+
+export interface AuthStrategy {
+  getHeaders(): Promise<Record<string, string>>;
+}
+
+export class APIKeyAuth implements AuthStrategy {
+  constructor(private readonly _apiKey: string) {}
+
+  async getHeaders(): Promise<Record<string, string>> {
+    return { Authorization: `Bearer ${this._apiKey}` };
+  }
+}
+
+export const GUAVA_DEPLOY_TOKEN_PATH = "/var/run/secrets/guava/token";
+const _GUAVA_DEPLOY_TOKEN_PREFIX = "gva-deploy2-";
+
+export class GuavaDeploy implements AuthStrategy {
+  constructor(private readonly _tokenPath: string = GUAVA_DEPLOY_TOKEN_PATH) {}
+
+  async getHeaders(): Promise<Record<string, string>> {
+    const token = fs.readFileSync(this._tokenPath, "utf8").trim();
+    return { Authorization: `Bearer ${_GUAVA_DEPLOY_TOKEN_PREFIX}${token}` };
+  }
+}
+
+const TOKEN_REFRESH_BUFFER_MS = 60_000;
+
+interface CliConfig {
+  access_token: string;
+  expires_at: number;
+  refresh_token: string;
+  org_id: string;
+  base_url?: string;
+}
+
+export class CLIAuth implements AuthStrategy {
+  static exists(): boolean {
+    const configPath = getCliConfigPath();
+    if (!fs.existsSync(configPath)) return false;
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8")) as Record<string, unknown>;
+    return "refresh_token" in config;
+  }
+
+  private _accessToken: string;
+  private _expiresAt: number; // ms since epoch
+  private _refreshToken: string;
+  private _orgId: string;
+  private _baseUrl: string;
+  private _pendingRefresh: Promise<void> | null = null;
+
+  constructor() {
+    const config = JSON.parse(fs.readFileSync(getCliConfigPath(), "utf8")) as CliConfig;
+    this._accessToken = config.access_token;
+    this._expiresAt = config.expires_at * 1000;
+    this._refreshToken = config.refresh_token;
+    this._orgId = config.org_id;
+    this._baseUrl = config.base_url ?? getBaseUrl();
+  }
+
+  private async _doRefresh(): Promise<void> {
+    logger.debug("Refreshing access token...");
+    const response = await fetchOrThrow(new URL("/oauth/token", this._baseUrl), {
+      method: "POST",
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: this._refreshToken,
+      }),
+    });
+    const token = (await response.json()) as {
+      access_token: string;
+      expires_in: number;
+      refresh_token?: string;
+    };
+    this._accessToken = token.access_token;
+    this._expiresAt = Date.now() + token.expires_in * 1000;
+    if (token.refresh_token) {
+      logger.warn("Unexpected refresh token in response.");
+    }
+  }
+
+  async getHeaders(): Promise<Record<string, string>> {
+    if (Date.now() >= this._expiresAt - TOKEN_REFRESH_BUFFER_MS) {
+      if (!this._pendingRefresh) {
+        this._pendingRefresh = this._doRefresh().finally(() => {
+          this._pendingRefresh = null;
+        });
+      }
+      await this._pendingRefresh;
+    }
+    return {
+      Authorization: `Bearer ${this._accessToken}`,
+      "x-guava-org-id": this._orgId,
+    };
+  }
+}
+
+let _cliAuthInstance: CLIAuth | null = null;
+
+export function getCLIAuth(): CLIAuth {
+  if (!_cliAuthInstance) {
+    _cliAuthInstance = new CLIAuth();
+  }
+  return _cliAuthInstance;
+}

package/src/call.ts

@@ -33,7 +33,7 @@ export type ReachPersonOutcome = {
 
 @telemetryClient.trackClass()
 export class Call {
-  private _commandQueue: Command[] = [];
+  protected _commandQueue: Command[] = [];
   private _variables: Record<string, any> = {};
   protected logger: Logger;
 
@@ -272,11 +272,11 @@ TASK COMPLETION REQUIREMENTS:
   async setVoicemailAction(action: { hangup: true } | { message: string }) {
     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.",
+        "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.",
       );
     } else {
       await this.sendInstruction(
-        `If you encounter an answering machine, say this message VERBATIM: ${action.message}`,
+        `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.`,
       );
     }
   }

package/src/client.ts

@@ -9,12 +9,30 @@ import * as z from "zod";
 import { ErrorEvent, SessionStartedEvent, decodeEvent, InboundTunnelEvent } from "./events.ts";
 import { SDK_VERSION } from "./version.ts";
 import os from "node:os";
-import { getBaseUrl, fetchOrThrow } from "./utils.ts";
+import * as fs from "node:fs";
+import { getBaseUrl, fetchOrThrow, sleep } from "./utils.ts";
+import { SmsMessage } from "./sms.ts";
 import { telemetryClient } from "./telemetry.ts";
 import type { CallController } from "./call-controller.ts";
+import {
+  type AuthStrategy,
+  APIKeyAuth,
+  GuavaDeploy,
+  CLIAuth,
+  getCLIAuth,
+  GUAVA_DEPLOY_TOKEN_PATH,
+} from "./auth.ts";
 
 const SDK_NAME = "typescript-sdk";
 
+export interface ClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  logger?: Logger;
+  captureWarnings?: boolean;
+  checkDeprecation?: boolean;
+}
+
 let firstClient = false;
 
 function stringifyZod<Schema extends z.ZodType>(schema: Schema, data: z.input<Schema>): string {
@@ -28,14 +46,20 @@ const https_start = /^https:\/\//;
 
 @telemetryClient.trackClass()
 export class Client {
-  private _apiKey: string;
+  private _auth: AuthStrategy;
   private _baseUrl: string;
   private _logger: Logger;
   private _ws?: WebSocket;
   private _controller?: CallController;
   private messageHandler?: (_: WebSocket.MessageEvent) => void;
 
-  constructor(apiKey?: string, baseUrl?: string, logger?: Logger, captureWarnings: boolean = true) {
+  constructor({
+    apiKey,
+    baseUrl,
+    logger,
+    captureWarnings = true,
+    checkDeprecation = true,
+  }: ClientOptions = {}) {
     // Set up the default logger.
     if (logger) {
       this._logger = logger;
@@ -50,14 +74,18 @@ export class Client {
       this._baseUrl = getBaseUrl();
     }
 
-    // Resolve the API key.
+    // Resolve auth strategy.
     if (apiKey) {
-      this._apiKey = apiKey;
+      this._auth = new APIKeyAuth(apiKey);
+    } else if (fs.existsSync(GUAVA_DEPLOY_TOKEN_PATH)) {
+      this._auth = new GuavaDeploy();
     } else if (process.env.GUAVA_API_KEY) {
-      this._apiKey = process.env.GUAVA_API_KEY;
+      this._auth = new APIKeyAuth(process.env.GUAVA_API_KEY);
+    } else if (CLIAuth.exists()) {
+      this._auth = getCLIAuth();
     } else {
       throw new Error(
-        "Guava API key must be provided either as argument to client constructor, or in environment variable GUAVA_API_KEY.",
+        "Unable to authenticate to Guava. You must do one of the following:\n- Sign in using the Guava CLI.\n- Or, provide an API key using the GUAVA_API_KEY environment variable.\n- Or, provide the API key as an argument to the constructor.",
       );
     }
 
@@ -70,8 +98,10 @@ export class Client {
         });
       }
 
-      telemetryClient.setSdkHeaders(this.headers());
-      this._checkSdkDeprecation();
+      telemetryClient.setSdkClient(this);
+      if (checkDeprecation) {
+        this._checkSdkDeprecation();
+      }
     }
   }
 
@@ -89,9 +119,9 @@ export class Client {
     return this._baseUrl;
   }
 
-  headers() {
+  async headers(): Promise<Record<string, string>> {
     return {
-      Authorization: `Bearer ${this._apiKey}`,
+      ...(await this._auth.getHeaders()),
       "x-guava-platform": os.platform(),
       "x-guava-runtime": process.release.name,
       "x-guava-runtime-version": process.version,
@@ -108,7 +138,7 @@ export class Client {
       url.searchParams.set("sdk_version", SDK_VERSION);
       const response = await fetchOrThrow(url, {
         method: "POST",
-        headers: this.headers(),
+        headers: await this.headers(),
       });
       const body = (await response.json()) as { deprecation_status: string };
       if (body.deprecation_status === "supported") {
@@ -136,19 +166,90 @@ export class Client {
     }
     const response = await fetchOrThrow(url, {
       method: "POST",
-      headers: this.headers(),
+      headers: await this.headers(),
     });
     const body = (await response.json()) as { webrtc_code: string };
     return body.webrtc_code;
   }
 
+  /**
+   * Sends an SMS message from one of your Guava numbers.
+   * @param fromNumber - One of your Guava numbers (E.164). Must have SMS configured.
+   * @param toNumber - The recipient's number (E.164).
+   * @param message - The message body to send.
+   */
+  async sendSms(fromNumber: string, toNumber: string, message: string): Promise<void> {
+    const url = new URL("v1/send-sms", this.getHttpBase());
+    await fetchOrThrow(url, {
+      method: "POST",
+      headers: { ...(await this.headers()), "Content-Type": "application/json" },
+      body: JSON.stringify({
+        from_number: fromNumber,
+        to_number: toNumber,
+        message,
+      }),
+    });
+  }
+
+  /**
+   * Waits for and returns the next inbound SMS sent from `fromNumber` to `toNumber`.
+   *
+   * Polls the inbox for messages received after this call begins, resolving once one
+   * arrives or `timeoutMs` elapses. Note the direction: `fromNumber` is the external
+   * number you're waiting to hear from, and `toNumber` is your Guava number — the
+   * opposite of {@link sendSms}.
+   *
+   * @param fromNumber - The external number to wait for a message from (E.164).
+   * @param toNumber - Your Guava number that will receive the message (E.164).
+   * @param options.timeoutMs - Max time to wait before giving up. Defaults to 60000.
+   * @param options.pollIntervalMs - Time between inbox checks. Defaults to 2000.
+   * @returns The message, or `null` if `timeoutMs` elapses with no new message.
+   */
+  async nextSms(
+    fromNumber: string,
+    toNumber: string,
+    options?: { timeoutMs?: number; pollIntervalMs?: number },
+  ): Promise<SmsMessage | null> {
+    const timeoutMs = options?.timeoutMs ?? 60_000;
+    const pollIntervalMs = options?.pollIntervalMs ?? 2_000;
+    const start = new Date().toISOString();
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+      const url = new URL("v1/messages", this.getHttpBase());
+      url.searchParams.set("to_number", toNumber);
+      url.searchParams.set("from_number", fromNumber);
+      url.searchParams.set("modality", "sms");
+      url.searchParams.set("start", start);
+      const response = await fetchOrThrow(url, {
+        method: "GET",
+        headers: await this.headers(),
+      });
+      // The endpoint returns matches oldest-first, so the earliest message after
+      // `start` is always the first element — we only need one, so `has_more`
+      // (which signals additional *later* messages) is irrelevant here.
+      const body = (await response.json()) as { messages: unknown[] };
+      if (body.messages?.length) {
+        return SmsMessage.parse(body.messages[0]);
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        return null;
+      }
+      await sleep(Math.min(pollIntervalMs, remaining));
+    }
+  }
+
   /**
    * @description use the Guava API to call out to a number
    */
-  createOutbound(fromNumber: string | undefined, toNumber: string, callController: CallController) {
+  async 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(),
+      headers: await this.headers(),
     });
 
     ws.addEventListener("open", async (_ev) => {
@@ -236,16 +337,16 @@ export class Client {
   /**
    * @description use the Guava API to receive calls at a given number
    */
-  listenInbound<U extends CallController>(
+  async listenInbound<U extends CallController>(
     conn: InboundConnection,
     controllerClassFactory: (logger: Logger) => U,
-  ) {
+  ): Promise<InboundListener> {
     const callControllers: Record<string, U> = {};
 
     // return a way to *stop* listening
     const url = new URL("v1/listen-inbound", this.getWebsocketBase());
     const ws = new WebSocket(url, {
-      headers: this.headers(),
+      headers: await this.headers(),
     });
     let agent_number: string | undefined;
     let webrtc_code: string | undefined;

package/src/events.ts

@@ -89,9 +89,19 @@ export type OutboundCallFailed = z.infer<typeof OutboundCallFailed>;
 
 export const BotSessionEnded = z.object({
   event_type: z.literal("bot-session-ended"),
+  termination_reason: z.enum([
+    "user-hangup",
+    "bot-hangup",
+    "bot-failure",
+    "bot-transfer",
+    "voicemail",
+  ]),
 });
 export type BotSessionEnded = z.infer<typeof BotSessionEnded>;
 
+/** Why a bot session ended. */
+export type TerminationReason = BotSessionEnded["termination_reason"];
+
 export const ChoiceQueryEvent = z.object({
   event_type: z.literal("choice-query"),
   field_key: z.string(),
@@ -113,6 +123,30 @@ export const ExecuteActionEvent = z.object({
 });
 export type ExecuteActionEvent = z.infer<typeof ExecuteActionEvent>;
 
+export type DTMFDigit =
+  | "0"
+  | "1"
+  | "2"
+  | "3"
+  | "4"
+  | "5"
+  | "6"
+  | "7"
+  | "8"
+  | "9"
+  | "*"
+  | "#"
+  | "A"
+  | "B"
+  | "C"
+  | "D";
+
+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"]),
+});
+export type DTMFPressedEvent = z.infer<typeof DTMFPressedEvent>;
+
 export const GuavaEvent = z.discriminatedUnion("event_type", [
   SessionStartedEvent,
   InboundCallEvent,
@@ -130,13 +164,29 @@ export const GuavaEvent = z.discriminatedUnion("event_type", [
   ChoiceQueryEvent,
   ActionRequestEvent,
   ExecuteActionEvent,
+  DTMFPressedEvent,
 ]);
 export type GuavaEvent = z.infer<typeof GuavaEvent>;
 
-const _KNOWN_EVENT_TYPES = new Set(
+const _KNOWN_EVENT_TYPES: Set<string> = new Set(
   GuavaEvent.options.map((schema) => schema.shape.event_type.value),
 );
 
+export function decodeEventDict(data: Record<string, unknown>): GuavaEvent | null {
+  if (typeof data.event_type !== "string") {
+    throw new Error(
+      `Received event with non-string event_type: ${JSON.stringify(data.event_type)}`,
+    );
+  }
+  if (!_KNOWN_EVENT_TYPES.has(data.event_type)) {
+    process.emitWarning(
+      `Received an unknown event type ${data.event_type}. Update to a newer version of this SDK.`,
+    );
+    return null;
+  }
+  return GuavaEvent.parse(data);
+}
+
 export function decodeEvent(
   serialized_event: string | ArrayBuffer | Buffer | Buffer[],
 ): GuavaEvent | null {
@@ -154,15 +204,7 @@ export function decodeEvent(
   } else {
     data = JSON.parse(serialized_event.toString("utf8"));
   }
-
-  if (!_KNOWN_EVENT_TYPES.has(data.event_type)) {
-    process.emitWarning(
-      `Received an unknown event type ${data.event_type}. Update to a newer version of this SDK.`,
-    );
-    return null;
-  }
-
-  return GuavaEvent.parse(data);
+  return decodeEventDict(data);
 }
 
 export const InboundTunnelEvent = z.object({

package/src/helpers/llm.ts

@@ -0,0 +1,20 @@
+import type { Client } from "../client.ts";
+import { fetchOrThrow } from "../utils.ts";
+
+export async function _generate(
+  client: Client,
+  prompt: string,
+  jsonSchema?: object,
+): Promise<string> {
+  const url = new URL("v1/llm/generate", client.getHttpBase());
+  const body: Record<string, unknown> = { prompt };
+  if (jsonSchema !== undefined) body.json_schema = jsonSchema;
+
+  const response = await fetchOrThrow(url, {
+    method: "POST",
+    headers: { ...(await client.headers()), "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  return ((await response.json()) as { text: string }).text;
+}

package/src/index.ts

@@ -1,6 +1,10 @@
 export { Client, type InboundConnection } from "./client.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 type { BotSessionEnded, TerminationReason, DTMFPressedEvent, DTMFDigit } from "./events.ts";
+export { TestSession } from "./testing/session.ts";
+export { MockCall } from "./testing/mocks.ts";

package/src/logging.ts

@@ -37,26 +37,34 @@ function shouldLog(messageLevel: LogLevel, loggerLevel: LogLevel) {
 
 function noop(format: string, ...args: unknown[]) {}
 
+type ConsoleLevel = "debug" | "info" | "warn" | "error";
+
 function makeColoredMethod(
-  fn: (...args: unknown[]) => void,
-  level: LogLevel,
+  level: ConsoleLevel,
   useColor: boolean,
 ): (format: string, ...args: unknown[]) => void {
-  if (!useColor) return fn.bind(console);
-  return (format: string, ...args: unknown[]) =>
-    fn(`${LEVEL_COLORS[level]}[${level.toLocaleUpperCase()}] ${format}${ANSI_RESET}`, ...args);
+  if (!useColor) return (format: string, ...args: unknown[]) => console[level](format, ...args);
+  return (format: string, ...args: unknown[]) => {
+    const now = new Date();
+    const time = now.toLocaleTimeString("en-US", {
+      hour12: false,
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    });
+    console[level](
+      `${LEVEL_COLORS[level]}[${level.toLocaleUpperCase().padEnd(5)} ${time}] ${format}${ANSI_RESET}`,
+      ...args,
+    );
+  };
 }
 
 export function getConsoleLogger(loggerLevel: LogLevel, useColor = false): Logger {
   return {
-    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,
+    debug: shouldLog("debug", loggerLevel) ? makeColoredMethod("debug", useColor) : noop,
+    info: shouldLog("info", loggerLevel) ? makeColoredMethod("info", useColor) : noop,
+    warn: shouldLog("warn", loggerLevel) ? makeColoredMethod("warn", useColor) : noop,
+    error: shouldLog("error", loggerLevel) ? makeColoredMethod("error", useColor) : noop,
   };
 }
 

package/src/sms.ts

@@ -0,0 +1,17 @@
+import * as z from "zod";
+
+/**
+ * An inbound SMS message received on one of your Guava numbers.
+ *
+ * Field names mirror the wire format returned by `GET /v1/messages`.
+ */
+export const SmsMessage = z.object({
+  id: z.string(),
+  from_number: z.string(),
+  to_number: z.string(),
+  content: z.string(),
+  received_at: z.string(),
+  modality: z.literal("sms"),
+  direction: z.enum(["inbound", "outbound"]),
+});
+export type SmsMessage = z.infer<typeof SmsMessage>;

package/src/socket/call-info.ts

@@ -0,0 +1,30 @@
+import * as z from "zod";
+
+export const PSTNCallInfo = z.object({
+  call_type: z.literal("pstn"),
+  from_number: z.string().nullable(),
+  to_number: z.string(),
+  caller_id: z.string().nullable(),
+});
+export type PSTNCallInfo = z.infer<typeof PSTNCallInfo>;
+
+export const WebRTCCallInfo = z.object({
+  call_type: z.literal("webrtc"),
+  webrtc_code: z.string(),
+});
+export type WebRTCCallInfo = z.infer<typeof WebRTCCallInfo>;
+
+export const SIPCallInfo = z.object({
+  call_type: z.literal("sip"),
+  from_aor: z.string(),
+  sip_code: z.string().optional(),
+  sip_headers: z.record(z.string(), z.string()).default({}),
+});
+export type SIPCallInfo = z.infer<typeof SIPCallInfo>;
+
+export const CallInfo = z.discriminatedUnion("call_type", [
+  PSTNCallInfo,
+  WebRTCCallInfo,
+  SIPCallInfo,
+]);
+export type CallInfo = z.infer<typeof CallInfo>;