@guava-ai/guava-sdk 0.27.0 → 0.28.0

package/examples/property-insurance.ts

@@ -1,6 +1,8 @@
+import { Command } from "commander";
 import * as guava from "@guava-ai/guava-sdk";
 import { DocumentQA } from "@guava-ai/guava-sdk/helpers";
 import { PROPERTY_INSURANCE_POLICY } from "@guava-ai/guava-sdk/example-data";
+import { getAgentNumber } from "@guava-ai/guava-sdk/example-utils";
 
 const agent = new guava.Agent({
   organization: "Harper Valley Property Insurance",
@@ -21,26 +23,44 @@ agent.onQuestion(async (call: guava.Call, question: string) => {
   return await documentQA.ask(question);
 });
 
-export async function run(args: string[]) {
-  if (args.includes("--webrtc")) {
-    await agent.listenWebrtc();
-  } else if (args.includes("--phone")) {
-    agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);
-  } else if (args.includes("--sip")) {
-    const sipCode = args[args.indexOf("--sip") + 1];
-    if (!sipCode) {
-      console.error("Error: --sip requires a SIP code argument.");
-      process.exit(1);
-    }
-    await agent.listenSip(sipCode);
-  } else if (args.includes("--local")) {
-    await agent.callLocal();
-  } else if (args.includes("--chat")) {
-    await agent.chat();
-  } else {
-    console.error(
-      "Usage: guava-example property-insurance --phone | --webrtc | --sip | --local | --chat",
-    );
-    process.exit(1);
-  }
+export async function run(prog: string, args: string[]) {
+  const program = new Command().name(prog).showHelpAfterError();
+
+  // Every Agent can be attached to one of many different channels.
+  program
+    .command("phone [number]")
+    .description("Listen for phone calls.")
+    .action(async (number?: string) => {
+      await agent.listenPhone(number ?? (await getAgentNumber()));
+    });
+
+  program
+    .command("webrtc [code]")
+    .description("Listen on a WebRTC code.")
+    .action(async (code?: string) => {
+      await agent.listenWebrtc(code);
+    });
+
+  program
+    .command("sip <code>")
+    .description("Listen on a SIP code 'guavasip-...'.")
+    .action(async (code: string) => {
+      await agent.listenSip(code);
+    });
+
+  program
+    .command("local")
+    .description("Start a local call.")
+    .action(async () => {
+      await agent.callLocal();
+    });
+
+  program
+    .command("chat")
+    .description("Start an interactive terminal chat.")
+    .action(async () => {
+      await agent.chat();
+    });
+
+  await program.parseAsync(args, { from: "user" });
 }

package/examples/restaurant-waitlist.ts

@@ -1,5 +1,7 @@
+import { Command } from "commander";
 import * as guava from "@guava-ai/guava-sdk";
 import { getDefaultLogger } from "@guava-ai/guava-sdk";
+import { getAgentNumber } from "@guava-ai/guava-sdk/example-utils";
 
 const logger = getDefaultLogger();
 
@@ -42,26 +44,44 @@ agent.onTaskComplete("waitlist", async (call: guava.Call) => {
   await call.hangup("Thank the caller and let them know we'll text when their table is ready.");
 });
 
-export async function run(args: string[]) {
-  if (args.includes("--webrtc")) {
-    await agent.listenWebrtc();
-  } else if (args.includes("--phone")) {
-    agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);
-  } else if (args.includes("--sip")) {
-    const sipCode = args[args.indexOf("--sip") + 1];
-    if (!sipCode) {
-      console.error("Error: --sip requires a SIP code argument.");
-      process.exit(1);
-    }
-    await agent.listenSip(sipCode);
-  } else if (args.includes("--local")) {
-    await agent.callLocal();
-  } else if (args.includes("--chat")) {
-    await agent.chat();
-  } else {
-    console.error(
-      "Usage: guava-example restaurant-waitlist --phone | --webrtc | --sip | --local | --chat",
-    );
-    process.exit(1);
-  }
+export async function run(prog: string, args: string[]) {
+  const program = new Command().name(prog).showHelpAfterError();
+
+  // Every Agent can be attached to one of many different channels.
+  program
+    .command("phone [number]")
+    .description("Listen for phone calls.")
+    .action(async (number?: string) => {
+      await agent.listenPhone(number ?? (await getAgentNumber()));
+    });
+
+  program
+    .command("webrtc [code]")
+    .description("Listen on a WebRTC code.")
+    .action(async (code?: string) => {
+      await agent.listenWebrtc(code);
+    });
+
+  program
+    .command("sip <code>")
+    .description("Listen on a SIP code 'guavasip-...'.")
+    .action(async (code: string) => {
+      await agent.listenSip(code);
+    });
+
+  program
+    .command("local")
+    .description("Start a local call.")
+    .action(async () => {
+      await agent.callLocal();
+    });
+
+  program
+    .command("chat")
+    .description("Start an interactive terminal chat.")
+    .action(async () => {
+      await agent.chat();
+    });
+
+  await program.parseAsync(args, { from: "user" });
 }

package/examples/scheduling-outbound.ts

@@ -1,3 +1,4 @@
+import { Command } from "commander";
 import * as guava from "@guava-ai/guava-sdk";
 import { DatetimeFilter } from "@guava-ai/guava-sdk/helpers";
 import { mockAppointmentsForFuture } from "@guava-ai/guava-sdk/example-data";
@@ -42,22 +43,32 @@ agent.onTaskComplete("schedule_appointment", async (call) => {
   await call.hangup("Thank them for their time and hang up the call.");
 });
 
-export async function run(args: string[]) {
-  if (args.includes("--chat")) {
-    const patientName = args[args.indexOf("--chat") + 1] ?? "Benjamin Buttons";
-    await agent.chat({ patientName });
-    return;
-  }
+export async function run(prog: string, args: string[]) {
+  const program = new Command().name(prog).showHelpAfterError();
 
-  const [toNumber, patientName = "Benjamin Buttons"] = args;
+  program
+    .command("phone <number>")
+    .description("Call a phone number.")
+    .option("-n, --name <name>", "Name of the patient.", "Benjamin Buttons")
+    .action(async (number: string, options: { name: string }) => {
+      await agent.callPhone(await getAgentNumber(), number, { patientName: options.name });
+    });
 
-  if (!toNumber) {
-    console.error("Usage: guava-example scheduling-outbound <phone> [name]");
-    console.error("       guava-example scheduling-outbound --chat [name]");
-    process.exit(1);
-  }
+  program
+    .command("local")
+    .description("Start a local call (for testing).")
+    .option("-n, --name <name>", "Name of the patient.", "Benjamin Buttons")
+    .action(async (options: { name: string }) => {
+      await agent.callLocal({ patientName: options.name });
+    });
+
+  program
+    .command("chat")
+    .description("Start a local chat session (for testing).")
+    .option("-n, --name <name>", "Name of the patient.", "Benjamin Buttons")
+    .action(async (options: { name: string }) => {
+      await agent.chat({ patientName: options.name });
+    });
 
-  agent.callPhone(await getAgentNumber(), toNumber, {
-    patientName: patientName,
-  });
+  await program.parseAsync(args, { from: "user" });
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@guava-ai/guava-sdk",
   "description": "The official TypeScript SDK for building Guava voice agents.",
   "homepage": "https://docs.goguava.ai/typescript-sdk/",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "type": "commonjs",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -46,6 +46,7 @@
     "guava-example": "dist/bin/example-runner.js"
   },
   "dependencies": {
+    "commander": "^15.0.0",
     "openai": "^6.16.0",
     "ws": "^8.19.0",
     "zod": "^4.3.5"

package/src/action-item.ts

@@ -1,9 +1,17 @@
 import * as z from "zod";
 
 export const FieldItemType = z.union(
-  (["text", "date", "integer", "digit_sequence", "multiple_choice", "calendar_slot"] as const).map(
-    (val) => z.literal(val),
-  ),
+  (
+    [
+      "text",
+      "date",
+      "integer",
+      "digit_sequence",
+      "multiple_choice",
+      "calendar_slot",
+      "cvv",
+    ] as const
+  ).map((val) => z.literal(val)),
 );
 export type FieldItemType = z.input<typeof FieldItemType>;
 
@@ -20,15 +28,27 @@ export const FieldItem = z
     choices: z.array(z.string()).default([]),
     choiceGenerator: z.custom<ChoiceGenerator>((val) => typeof val === "function").optional(),
     searchable: z.boolean().default(false),
+    sensitive: z.boolean().default(false),
   })
-  .refine((field) => {
+  .superRefine((field, ctx) => {
+    const hasChoices = field.choices.length > 0 || field.choiceGenerator !== undefined;
+    if (
+      hasChoices &&
+      field.field_type !== "multiple_choice" &&
+      field.field_type !== "calendar_slot"
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        message: `Field type ${field.field_type} does not support choices attribute.`,
+      });
+    }
+
     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 FieldItem = z.input<typeof FieldItem>;
 
@@ -41,6 +61,7 @@ export const SerializableFieldItem = z.object({
   required: z.boolean().default(true),
   choices: z.array(z.string()).default([]),
   is_search_field: z.boolean().default(false),
+  sensitive: z.boolean().default(false),
 });
 export type SerializableFieldItem = z.input<typeof SerializableFieldItem>;
 
@@ -70,6 +91,7 @@ export function Field(options: {
   choices?: string[];
   choiceGenerator?: ChoiceGenerator;
   searchable?: boolean;
+  sensitive?: boolean;
 }): FieldItem {
   return FieldItem.parse({
     item_type: "field",
@@ -81,6 +103,7 @@ export function Field(options: {
     choices: options.choices,
     choiceGenerator: options.choiceGenerator,
     searchable: options.searchable,
+    sensitive: options.sensitive,
   });
 }
 

package/src/agent.ts

@@ -276,12 +276,14 @@ export class Agent {
     return this._listenInbound(healthCtx, { sip_code: sipCode });
   }
 
-  async callLocal(): Promise<void> {
+  async callLocal(variables: Record<string, any> = {}): Promise<void> {
     const webrtcCode = await this._client.createWebrtcAgent(300);
     // No health-server for call_local.
-    this._listenInbound(new HealthContext(), { webrtc_code: webrtcCode }).catch((err) => {
-      this._logger.error("Listen loop error: %s", err);
-    });
+    this._listenInbound(new HealthContext(), { webrtc_code: webrtcCode }, variables).catch(
+      (err) => {
+        this._logger.error("Listen loop error: %s", err);
+      },
+    );
     await runWebrtcHelper(webrtcCode, getBaseUrl());
   }
 
@@ -574,7 +576,11 @@ export class Agent {
     }
   }
 
-  async _listenInbound(healthCtx: HealthContext, conn: InboundConnection): Promise<void> {
+  async _listenInbound(
+    healthCtx: HealthContext,
+    conn: InboundConnection,
+    initialVariables: Record<string, any> = {},
+  ): Promise<void> {
     const url = new URL("v2/listen-inbound", this._client.getWebsocketBase());
     if ("agent_number" in conn) {
       url.searchParams.set("phone_number", conn.agent_number);
@@ -632,9 +638,11 @@ export class Agent {
             case "assign-call": {
               const { call_id, call_info } = msg;
               this._logger.info("Received call (session ID: %s)", call_id);
-              this._handleAssignedCall(call_id, call_info, socket).catch((err) => {
-                this._logger.error("Error handling assigned call %s: %s", call_id, err);
-              });
+              this._handleAssignedCall(call_id, call_info, socket, initialVariables).catch(
+                (err) => {
+                  this._logger.error("Error handling assigned call %s: %s", call_id, err);
+                },
+              );
               break;
             }
           }
@@ -892,11 +900,7 @@ Choose "speak" and provide your next utterance, or choose "hangup" if the conver
 
   async _serveCampaign(healthCtx: HealthContext, campaignCode: string): Promise<void> {
     try {
-      const campaignUrl = new URL(`v1/campaigns/${campaignCode}`, this._client.getHttpBase());
-      const campaignResponse = await fetchOrThrow(campaignUrl, {
-        headers: await this._client.headers(),
-      });
-      const campaign = (await campaignResponse.json()) as { id: string; name: string };
+      const campaign = await this._client.getCampaign(campaignCode);
 
       const wsUrl = new URL(`v1/serve-campaign/${campaign.id}`, this._client.getWebsocketBase());
       this._logger.info("Connecting to campaign '%s' (id: %s).", campaign.name, campaign.id);

package/src/call.ts

@@ -404,4 +404,13 @@ TASK COMPLETION REQUIREMENTS:
   async getVariable(variableName: string) {
     return this._variables[variableName] ?? null;
   }
+
+  // Aliases for setVariable / getVariable, matching the Python SDK.
+  async setVar(variableName: string, variableValue: any) {
+    return this.setVariable(variableName, variableValue);
+  }
+
+  async getVar(variableName: string) {
+    return this.getVariable(variableName);
+  }
 }

package/src/campaigns.ts

@@ -0,0 +1,156 @@
+import { inspect } from "node:util";
+import * as z from "zod";
+import { fetchOrThrow } from "./utils.ts";
+import { telemetryClient } from "./telemetry.ts";
+import type { Client } from "./client.ts";
+
+/**
+ * Modality used for campaign agentic outreach.
+ *
+ * Currently only SMS is available.
+ */
+export const OutreachModality = z.enum(["sms"]);
+export type OutreachModality = z.infer<typeof OutreachModality>;
+
+/**
+ * A contact to upload to a campaign.
+ */
+export const Contact = z.object({
+  /** The contact's phone number in E.164 format (e.g. `"+14155550123"`). */
+  phoneNumber: z.e164(),
+  /**
+   * Arbitrary per-contact data. This is delivered to the agent when the call is
+   * initiated and can be read during the call (e.g. via `call.getVariable`).
+   */
+  data: z.record(z.string(), z.unknown()).default({}),
+  /**
+   * Modalities used to reach this contact. When omitted, falls back to the
+   * `outreachModalities` passed to {@link Campaign.uploadContacts}.
+   */
+  outreachModalities: z.array(OutreachModality).optional(),
+});
+export type Contact = z.input<typeof Contact>;
+
+/** Result of uploading contacts to a campaign. */
+export interface UploadContactsResult {
+  /** The number of contacts that were inserted. */
+  created: number;
+}
+
+/** Status of a campaign. */
+export interface CampaignStatus {
+  /**
+   * Mapping of contact status (e.g. `"trying"`, `"failed"`, `"completed"`,
+   * `"partially_completed"`, `"do_not_call"`) to the number of contacts in that
+   * status. Only statuses with at least one contact are included.
+   */
+  statusCounts: Record<string, number>;
+}
+
+/** Options for {@link Campaign.uploadContacts}. */
+export interface UploadContactsOptions {
+  /** Whether to insert contacts whose phone number is already in the campaign. */
+  allowDuplicates?: boolean;
+  /** Confirms you have consent to contact these numbers. Required by the server. */
+  acceptedTermsOfService?: boolean;
+  /** Default modalities applied to any contact that doesn't specify its own. */
+  outreachModalities?: OutreachModality[];
+}
+
+// Wire-format schemas for parsing responses (snake_case, as returned by the API).
+const UploadContactsResultWire = z.object({ created: z.number().int() });
+const CampaignStatusWire = z.object({
+  status_counts: z.record(z.string(), z.number()).default({}),
+});
+
+/**
+ * A handle to an existing Guava campaign.
+ *
+ * Obtain instances via {@link Client.getCampaign} or {@link Client.listCampaigns};
+ * do not construct directly. Campaigns are created via the Guava dashboard or CLI.
+ */
+@telemetryClient.trackClass()
+export class Campaign {
+  private _client: Client;
+  private _id: string;
+  private _code: string;
+  // Snapshot of the name at the time this handle was fetched. Used for
+  // display/logging only; identity is keyed off id/code, never name.
+  private _name: string;
+
+  constructor(client: Client, id: string, code: string, name: string) {
+    this._client = client;
+    this._id = id;
+    this._code = code;
+    this._name = name;
+  }
+
+  get id(): string {
+    return this._id;
+  }
+
+  get name(): string {
+    return this._name;
+  }
+
+  /**
+   * Upload contacts to this campaign.
+   *
+   * @param contacts - The contacts to upload.
+   * @param options.allowDuplicates - Insert contacts whose number already
+   *   exists in the campaign. Defaults to `false`.
+   * @param options.acceptedTermsOfService - Confirms you have consent to
+   *   contact these numbers. Defaults to `false`.
+   * @param options.outreachModalities - Default modalities for any contact that
+   *   doesn't set its own {@link Contact.outreachModalities}.
+   * @returns The number of contacts that were inserted.
+   */
+  async uploadContacts(
+    contacts: Contact[],
+    options: UploadContactsOptions = {},
+  ): Promise<UploadContactsResult> {
+    const { allowDuplicates = false, acceptedTermsOfService = false, outreachModalities } = options;
+
+    const wireContacts = contacts.map((contact) => {
+      const parsed = Contact.parse(contact);
+      return {
+        phone_number: parsed.phoneNumber,
+        data: parsed.data,
+        // Per-contact modalities take precedence; fall back to the method-level
+        // default, otherwise leave unset (server applies the campaign default).
+        outreach_modalities: parsed.outreachModalities ?? outreachModalities ?? null,
+      };
+    });
+
+    const url = new URL(`v2/campaigns/${this._code}/contacts`, this._client.getHttpBase());
+    url.searchParams.set("allow_duplicates", String(allowDuplicates));
+    url.searchParams.set("accepted_terms_of_service", String(acceptedTermsOfService));
+
+    const response = await fetchOrThrow(url, {
+      method: "POST",
+      headers: { ...(await this._client.headers()), "Content-Type": "application/json" },
+      body: JSON.stringify({ contacts: wireContacts }),
+    });
+
+    const { created } = UploadContactsResultWire.parse(await response.json());
+    return { created };
+  }
+
+  /** Fetch the current status of this campaign. */
+  async getStatus(): Promise<CampaignStatus> {
+    const url = new URL(`v1/campaigns/${this._id}/status`, this._client.getHttpBase());
+    const response = await fetchOrThrow(url, { headers: await this._client.headers() });
+    const { status_counts } = CampaignStatusWire.parse(await response.json());
+    return { statusCounts: status_counts };
+  }
+
+  /** Permanently delete this campaign. */
+  async delete(): Promise<void> {
+    const url = new URL(`v1/campaigns/${this._id}`, this._client.getHttpBase());
+    await fetchOrThrow(url, { method: "DELETE", headers: await this._client.headers() });
+  }
+
+  [inspect.custom](): string {
+    return `Campaign { name: '${this._name}', code: '${this._code}' }`;
+  }
+}

package/src/client.ts

@@ -4,6 +4,7 @@ import os from "node:os";
 import * as fs from "node:fs";
 import { getBaseUrl, fetchOrThrow, sleep } from "./utils.ts";
 import { SmsMessage } from "./sms.ts";
+import { Campaign } from "./campaigns.ts";
 import { telemetryClient } from "./telemetry.ts";
 import {
   type AuthStrategy,
@@ -156,6 +157,40 @@ export class Client {
     return body.webrtc_code;
   }
 
+  async createSipAgent(): Promise<string> {
+    const url = new URL("v1/sip-agents", this.getHttpBase());
+    const response = await fetchOrThrow(url, {
+      method: "POST",
+      headers: await this.headers(),
+    });
+    const body = (await response.json()) as { sip_code: string };
+    return body.sip_code;
+  }
+
+  /**
+   * Fetch an existing campaign by its code.
+   *
+   * @param campaignCode - The campaign code (e.g. `gcmp-...`).
+   */
+  async getCampaign(campaignCode: string): Promise<Campaign> {
+    const url = new URL(`v1/campaigns/${campaignCode}`, this.getHttpBase());
+    const response = await fetchOrThrow(url, { headers: await this.headers() });
+    const body = (await response.json()) as { id: string; campaign_code: string; name: string };
+    return new Campaign(this, body.id, body.campaign_code, body.name);
+  }
+
+  /** List all campaigns in your organization. */
+  async listCampaigns(): Promise<Campaign[]> {
+    const url = new URL("v1/campaigns", this.getHttpBase());
+    const response = await fetchOrThrow(url, { headers: await this.headers() });
+    const items = (await response.json()) as {
+      id: string;
+      campaign_code: string;
+      name: string;
+    }[];
+    return items.map((c) => new Campaign(this, c.id, c.campaign_code, c.name));
+  }
+
   async listNumbers(): Promise<{ phoneNumber: string }[]> {
     const url = new URL("v1/phone-numbers", this.getHttpBase());
     const response = await fetchOrThrow(url, { headers: await this.headers() });

package/src/index.ts

@@ -1,6 +1,14 @@
 export { Client, type InboundConnection } from "./client.ts";
 export { Runner } from "./runner.ts";
 export type { SmsMessage } from "./sms.ts";
+export { Campaign } from "./campaigns.ts";
+export type {
+  Contact,
+  CampaignStatus,
+  UploadContactsResult,
+  UploadContactsOptions,
+  OutreachModality,
+} from "./campaigns.ts";
 export { Say, Field } from "./action-item.ts";
 export { Logger, getConsoleLogger, getDefaultLogger } from "./logging.ts";
 export { Agent, CallInfo } from "./agent.ts";

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.27.0";
+export const SDK_VERSION = "0.28.0";