@guava-ai/guava-sdk 0.18.0 → 0.19.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,9 +9,18 @@ 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 * as fs from "node:fs";
 import { getBaseUrl, fetchOrThrow } from "./utils.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";
 
@@ -28,7 +37,7 @@ const https_start = /^https:\/\//;
 
 @telemetryClient.trackClass()
 export class Client {
-  private _apiKey: string;
+  private _auth: AuthStrategy;
   private _baseUrl: string;
   private _logger: Logger;
   private _ws?: WebSocket;
@@ -50,14 +59,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,7 +83,7 @@ export class Client {
         });
       }
 
-      telemetryClient.setSdkHeaders(this.headers());
+      telemetryClient.setSdkClient(this);
       this._checkSdkDeprecation();
     }
   }
@@ -89,9 +102,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 +121,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,7 +149,7 @@ 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;
@@ -145,10 +158,14 @@ export class Client {
   /**
    * @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 +253,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,6 +89,13 @@ 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>;
 
@@ -133,10 +140,25 @@ export const GuavaEvent = z.discriminatedUnion("event_type", [
 ]);
 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 +176,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

@@ -4,3 +4,5 @@ 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 { 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/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>;