@guava-ai/guava-sdk 0.27.1 → 0.29.0

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/health.ts

@@ -1,7 +1,7 @@
 import { type Server, createServer } from "node:http";
 import { getDefaultLogger, type Logger } from "./logging.ts";
 
-export type HealthState = "starting" | "live" | "stopped";
+export type HealthState = "starting" | "running" | "draining" | "stopped";
 
 export class HealthContext {
   private _state: HealthState = "starting";
@@ -11,7 +11,11 @@ export class HealthContext {
   }
 
   ready(): void {
-    this.setState("live");
+    this.setState("running");
+  }
+
+  draining(): void {
+    this.setState("draining");
   }
 
   stopped(): void {
@@ -19,7 +23,11 @@ export class HealthContext {
   }
 
   isLive(): boolean {
-    return this._state === "live";
+    return this._state !== "stopped";
+  }
+
+  isReady(): boolean {
+    return this._state === "running";
   }
 }
 
@@ -35,6 +43,10 @@ export class MultiHealthContext {
   isLive(): boolean {
     return this._ctxs.length > 0 && this._ctxs.every((ctx) => ctx.isLive());
   }
+
+  isReady(): boolean {
+    return this._ctxs.length > 0 && this._ctxs.every((ctx) => ctx.isReady());
+  }
 }
 
 export interface HealthServerOptions {
@@ -64,6 +76,8 @@ export class HealthServer implements AsyncDisposable {
     const server = createServer((req, res) => {
       if (req.method === "GET" && req.url === "/live") {
         res.statusCode = healthCtx.isLive() ? 200 : 503;
+      } else if (req.method === "GET" && req.url === "/ready") {
+        res.statusCode = healthCtx.isReady() ? 200 : 503;
       } else {
         res.statusCode = 404;
       }

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.1";
+export const SDK_VERSION = "0.29.0";