@guava-ai/guava-sdk 0.1.0

package/examples/property-insurance.ts

@@ -0,0 +1,49 @@
+import { parseArgs } from "node:util";
+import * as guava from "../src/index.ts";
+import { DocumentQA } from "../src/helpers/openai.ts";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { type Logger } from "../src/logging.ts";
+import {PROPERTY_INSURANCE_POLICY} from "../src/example_data.ts";
+
+class InsuranceCallController extends guava.CallController {
+  private documentQA: DocumentQA;
+  constructor(logger: Logger) {
+    super(logger);
+
+    this.documentQA = new DocumentQA(
+      "harper-valley-property-insurance",
+      PROPERTY_INSURANCE_POLICY,
+      logger,
+    );
+  }
+  override async onCallStart(): Promise<void> {
+    await this.setPersona("Harper Valley Property Insurance");
+    await this.setTask(
+      "You are making an outbound call to a potential customer. Your task is to answer questions regarding property insurance policy until there are no more questions.",
+    );
+  }
+
+  override async onQuestion(question: string): Promise<string> {
+    return await this.documentQA.ask(question);
+  }
+}
+
+export function run(args: string[]) {
+  const [phone] = args;
+
+  if (!phone) {
+    console.error("Usage: guava-example property-insurance <phone>");
+    process.exit(1);
+  }
+
+  new guava.Client().createOutbound(
+    process.env.GUAVA_AGENT_NUMBER!,
+    phone,
+    (logger) => new InsuranceCallController(logger),
+  );
+}
+
+if (import.meta.main) {
+  run(process.argv.slice(2))
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@guava-ai/guava-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@types/node": "^25.0.7",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3"
+  },
+  "bin": {
+    "guava-example": "./bin/example-runner.js"
+  },
+  "dependencies": {
+    "openai": "^6.16.0",
+    "ws": "^8.19.0",
+    "zod": "^4.3.5"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint",
+    "format": "biome format --write ./src",
+    "format-ex": "biome format --write ./examples",
+    "check": "npm run typecheck && npm audit",
+    "clean": "rm -rf ./dist",
+    "build": "tsc",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "/src",
+    "/dist",
+    "/examples",
+    "/bin"
+  ]
+}

package/src/action_item.ts

@@ -0,0 +1,42 @@
+import * as z from "zod";
+
+export const fieldItemType = z.union(
+  (["text", "date", "datetime", "integer", "multiple_choice"] as const).map(
+    (val) => z.literal(val),
+  ),
+);
+export type FieldItemType = z.input<typeof fieldItemType>;
+
+export const fieldItem = z
+  .object({
+    item_type: z.literal("field"),
+    key: z.string(),
+    description: z.string(),
+    field_type: fieldItemType,
+    required: z.boolean().default(true),
+    choices: z.array(z.string()),
+  })
+  .refine((field) => {
+    if (field.field_type == "multiple_choice" && field.choices.length > 10) {
+      process.emitWarning("Performance degrades with large number of choices for multiple choice field.", "ACTION_ITEM")
+    }
+    return true;
+  });
+export type Field = z.input<typeof fieldItem>;
+
+export const sayItem = z.object({
+  item_type: z.literal("say"),
+  statement: z.string(),
+  key: z.string().default(() => Math.random().toString(16).substring(2, 6)),
+});
+export type Say = z.input<typeof sayItem>;
+
+export const todoItem = z.object({
+  item_type: z.literal("todo"),
+  description: z.string(),
+  key: z.string().default(() => Math.random().toString(16).substring(2, 6)),
+});
+export type Todo = z.input<typeof todoItem>;
+
+export const actionItem = z.union([fieldItem, sayItem, todoItem]);
+export type ActionItem = z.input<typeof actionItem>;

package/src/commands.ts

@@ -0,0 +1,94 @@
+import * as z from "zod";
+import { actionItem } from "./action_item.ts";
+
+export const startOutboundCallCommand = z.strictObject({
+  command_type: z.literal("start-outbound"),
+
+  from_number: z.e164().optional(),
+  to_number: z.e164(),
+});
+export type StartOutboundCallCommand = z.input<typeof startOutboundCallCommand>;
+
+export const listenInboundCommand = z
+  .strictObject({
+    command_type: z.literal("listen-inbound"),
+
+    agent_number: z.e164().optional(),
+    webrtc_code: z.string().optional(),
+  })
+  .refine((obj) => {
+    !!obj.agent_number || !!obj.webrtc_code;
+  });
+export type ListenInboundCommand = z.input<typeof listenInboundCommand>;
+
+export const rejectInboundCallCommand = z.strictObject({
+  command_type: z.literal("reject-inbound"),
+});
+export type RejectInboundCallCommand = z.input<typeof rejectInboundCallCommand>;
+
+export const acceptInboundCallCommand = z.strictObject({
+  command_type: z.literal("accept-inbound"),
+});
+export type AcceptInboundCallCommand = z.input<typeof acceptInboundCallCommand>;
+
+export const setTaskCommand = z.strictObject({
+  command_type: z.literal("set-task"),
+  task_id: z.string(),
+  objective: z.string(),
+  action_items: z.array(actionItem),
+});
+export type SetTaskCommand = z.input<typeof setTaskCommand>;
+
+export const readScriptCommand = z.strictObject({
+  command_type: z.literal("read-script"),
+  script: z.string(),
+});
+export type ReadScriptCommand = z.input<typeof readScriptCommand>;
+
+export const answerQuestionCommand = z.strictObject({
+  command_type: z.literal("answer-question"),
+  question_id: z.string(),
+  answer: z.string(),
+});
+export type AnswerQuestionCommand = z.input<typeof answerQuestionCommand>;
+
+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(),
+});
+export type SetPersona = z.input<typeof setPersona>;
+
+export const sendInstructionCommand = z.strictObject({
+  command_type: z.literal("send-instruction"),
+  instruction: z.string(),
+});
+export type SendInstructionCommand = z.input<typeof sendInstructionCommand>;
+
+export const transferCommand = z.strictObject({
+  command_type: z.literal("transfer-call"),
+  transfer_message: z.string(),
+  to_number: z.string(),
+});
+export type TransferCommand = z.input<typeof transferCommand>;
+
+export const anyCommand = z.union([
+  startOutboundCallCommand,
+  listenInboundCommand,
+  rejectInboundCallCommand,
+  acceptInboundCallCommand,
+  setTaskCommand,
+  readScriptCommand,
+  answerQuestionCommand,
+  setPersona,
+  sendInstructionCommand,
+  transferCommand,
+]);
+export type Command = z.input<typeof anyCommand>;
+
+export const inboundTunnelCommand = z.strictObject({
+  call_id: z.string(),
+  command: anyCommand,
+});
+export type InboundTunnelCommand = z.input<typeof inboundTunnelCommand>;

package/src/events.ts

@@ -0,0 +1,142 @@
+import * as z from "zod";
+
+export const sessionStartedEvent = z.object({
+  event_type: z.literal("session-started"),
+  session_id: z.string(),
+});
+export type SessionStartedEvent = z.input<typeof sessionStartedEvent>;
+
+export const inboundCallEvent = z.object({
+  event_type: z.literal("inbound-call"),
+  caller_number: z.e164().optional(),
+  agent_number: z.e164().optional(),
+});
+export type InboundCallEvent = z.input<typeof inboundCallEvent>;
+
+/**
+ * @description The caller has said something.
+ */
+export const callerSpeechEvent = z.object({
+  event_type: z.literal("caller-speech"),
+
+  utterance: z.string(),
+});
+export type CallerSpeechEvent = z.input<typeof callerSpeechEvent>;
+
+/**
+ * @description The agent has said something.
+ */
+export const agentSpeechEvent = z.object({
+  event_type: z.literal("agent-speech"),
+
+  utterance: z.string(),
+  interrupted: z.boolean().default(false),
+});
+export type AgentSpeechEvent = z.input<typeof agentSpeechEvent>;
+
+export const errorEvent = z.object({
+  event_type: z.literal("error"),
+  content: z.string(),
+});
+export type ErrorEvent = z.input<typeof errorEvent>;
+
+export const warningEvent = z.object({
+  event_type: z.literal("warning"),
+  content: z.string(),
+});
+export type WarningEvent = z.input<typeof warningEvent>;
+
+export const agentQuestionEvent = z.object({
+  event_type: z.literal("agent-question"),
+  question_id: z.string(),
+  question: z.string(),
+});
+export type AgentQuestionEvent = z.input<typeof agentQuestionEvent>;
+
+export const intentEvent = z.object({
+  event_type: z.literal("intent"),
+  intent_id: z.string(),
+  intent_summary: z.string(),
+});
+export type IntentEvent = z.input<typeof intentEvent>;
+
+export const actionItemCompletedEvent = z.object({
+  event_type: z.literal("action-item-done"),
+  key: z.string(),
+  payload: z.unknown(),
+});
+export type ActionItemCompletedEvent = z.input<typeof actionItemCompletedEvent>;
+
+export const taskCompletedEvent = z.object({
+  event_type: z.literal("task-done"),
+
+  task_id: z.string(),
+});
+export type TaskCompletedEvent = z.input<typeof taskCompletedEvent>;
+
+export const outboundCallConnected = z.object({
+  event_type: z.literal("outbound-call-connected"),
+});
+export type OutboundCallConnected = z.input<typeof outboundCallConnected>;
+
+export const outboundCallFailed = z.object({
+  event_type: z.literal("outbound-call-failed"),
+
+  error_code: z.int(),
+  error_reason: z.string(),
+});
+export type OutboundCallFailed = z.input<typeof outboundCallFailed>;
+
+export const botSessionEnded = z.object({
+  event_type: z.literal("bot-session-ended"),
+});
+export type BotSessionEnded = z.input<typeof botSessionEnded>;
+
+export const anyEvent = z.union([
+  sessionStartedEvent,
+  inboundCallEvent,
+  callerSpeechEvent,
+  agentSpeechEvent,
+  errorEvent,
+  warningEvent,
+  agentQuestionEvent,
+  intentEvent,
+  actionItemCompletedEvent,
+  taskCompletedEvent,
+  outboundCallConnected,
+  outboundCallFailed,
+  botSessionEnded,
+]);
+export type GuavaEvent = z.input<typeof anyEvent>;
+
+export function decodeEvent(
+  serialized_event: string | ArrayBuffer | Buffer | Buffer[],
+): GuavaEvent | null {
+  let data: Record<string, any>;
+  if (typeof serialized_event == "string") {
+    data = JSON.parse(serialized_event);
+  } else if (serialized_event instanceof ArrayBuffer) {
+    data = JSON.parse(new TextDecoder().decode(serialized_event));
+  } else if (serialized_event instanceof Array) {
+    let decoded = "";
+    for (const buf of serialized_event) {
+      decoded += buf.toString("utf8");
+    }
+    data = JSON.parse(decoded);
+  } else {
+    data = JSON.parse(serialized_event.toString("utf8"));
+  }
+
+  try {
+    return anyEvent.parse(data);
+  } catch (e) {
+    // TODO logging global use signleton to warn
+    return null;
+  }
+}
+
+export const inboundTunnelEvent = z.object({
+  call_id: z.string(),
+  event: anyEvent,
+});
+export type inboundTunnelEvent = z.input<typeof inboundTunnelEvent>;