@guava-ai/guava-sdk 0.29.0 → 0.31.0

package/src/call.ts

@@ -237,6 +237,15 @@ export class Call {
     });
   }
 
+  /**
+   * Transfer the call to another destination.
+   *
+   * This method does not interfere with turn-taking — use this when
+   * you want the agent to naturally transfer the call.
+   *
+   * @param destination - The phone number or SIP address to transfer the call to.
+   * @param instructions - Optional guidance for how the agent should handle the transfer.
+   */
   async transfer(destination: string, instructions?: string) {
     await this.sendCommand(TransferCommand, {
       command_type: "transfer-call",
@@ -247,6 +256,25 @@ export class Call {
     });
   }
 
+  /**
+   * Transfer the call immediately.
+   *
+   * Unlike transfer(), this does not respect turn-taking. The agent immediately
+   * initiates the transfer, saying the script (if provided).
+   *
+   * @param destination - The phone number or SIP address to transfer the call to.
+   * @param finalScript - Optional message for the agent to deliver immediately
+   *   before transferring. Defaults to no message.
+   */
+  async immediateTransfer(destination: string, finalScript?: string) {
+    await this.sendCommand(TransferCommand, {
+      command_type: "transfer-call",
+      to_number: destination,
+      transfer_message: finalScript ?? "",
+      soft_transfer: false,
+    });
+  }
+
   async addInfo(label: string, info: unknown) {
     await this.sendInstruction(
       `Here is some information about the following topic ${label}:\n${JSON.stringify(info, null, 2)}`,

package/src/runner.ts

@@ -1,13 +1,27 @@
 import type { Agent } from "./agent.ts";
 import { MultiHealthContext, getHealthServer } from "./health.ts";
+import { nullDisposable, onSignal } from "./utils.ts";
+import { getDefaultLogger, type Logger } from "./logging.ts";
+
+export interface RunOptions {
+  /**
+   * Install SIGINT/SIGTERM handlers that drain in-flight calls on the first
+   * signal; a second signal terminates the process. Defaults to `true`.
+   */
+  handleSignals?: boolean;
+}
 
 export class Runner {
   private _healthCtx = new MultiHealthContext();
   private _tasks: Array<() => Promise<void>> = [];
+  private _drainController: AbortController = new AbortController();
+  private _logger: Logger = getDefaultLogger();
 
   listenPhone(agent: Agent, agentNumber: string): this {
     const ctx = this._healthCtx.createCtx();
-    this._tasks.push(() => agent._listenInbound(ctx, { agent_number: agentNumber }));
+    this._tasks.push(() =>
+      agent._listenInbound(ctx, { agent_number: agentNumber }, {}, this._drainController.signal),
+    );
     return this;
   }
 
@@ -15,25 +29,34 @@ export class Runner {
     const ctx = this._healthCtx.createCtx();
     this._tasks.push(async () => {
       const code = webrtcCode ?? (await agent._client.createWebrtcAgent(3600));
-      return agent._listenInbound(ctx, { webrtc_code: code });
+      return agent._listenInbound(ctx, { webrtc_code: code }, {}, this._drainController.signal);
     });
     return this;
   }
 
   listenSip(agent: Agent, sipCode: string): this {
     const ctx = this._healthCtx.createCtx();
-    this._tasks.push(() => agent._listenInbound(ctx, { sip_code: sipCode }));
+    this._tasks.push(() =>
+      agent._listenInbound(ctx, { sip_code: sipCode }, {}, this._drainController.signal),
+    );
     return this;
   }
 
   attachCampaign(agent: Agent, campaignCode: string): this {
     const ctx = this._healthCtx.createCtx();
-    this._tasks.push(() => agent._serveCampaign(ctx, campaignCode));
+    this._tasks.push(() => agent._serveCampaign(ctx, campaignCode, this._drainController.signal));
     return this;
   }
 
-  async run(): Promise<void> {
+  async run({ handleSignals = true }: RunOptions = {}): Promise<void> {
     await using _server = await getHealthServer(this._healthCtx);
+    using _ = handleSignals
+      ? onSignal((signal) => {
+          this._logger.info(`Received ${signal} - draining calls. Send signal again to terminate.`);
+          this._drainController.abort();
+        })
+      : nullDisposable;
     await Promise.all(this._tasks.map((task) => task()));
+    this._logger.info("All tasks done.");
   }
 }

package/src/socket/client.ts

@@ -49,6 +49,16 @@ export class GuavaSocketConnectionFailed extends Error {
   }
 }
 
+/** Raised when the server rejects the websocket handshake with an HTTP response. */
+class UnexpectedResponseError extends Error {
+  constructor(
+    readonly statusCode: number | undefined,
+    readonly body: string,
+  ) {
+    super(`Unexpected server response: ${statusCode ?? "unknown"}. Body: ${body || "<empty>"}`);
+  }
+}
+
 const HandshakeResponse = z.union([GuavaOpenAck, GuavaClose]);
 
 function _sendMessage(ws: WebSocket, message: GuavaClientMessage): void {
@@ -160,13 +170,7 @@ export class GuavaSocket<SendT, RecvT> {
               body += chunk.toString();
             });
             res.on("end", () => {
-              settle(() =>
-                reject(
-                  new Error(
-                    `Unexpected server response: ${res.statusCode}. Body: ${body || "<empty>"}`,
-                  ),
-                ),
-              );
+              settle(() => reject(new UnexpectedResponseError(res.statusCode, body)));
             });
           });
           socket.once("close", () =>
@@ -225,6 +229,7 @@ export class GuavaSocket<SendT, RecvT> {
         if (e instanceof GuavaSocketClosedError) throw e;
 
         if (attempt >= MAX_RECONNECT_ATTEMPTS) {
+          this._logger.error("Couldn't connect to server after %d attempts.", attempt);
           this._setCloseReason(
             "reconnection-failed",
             `Couldn't connect after ${attempt} attempts.`,
@@ -232,12 +237,25 @@ export class GuavaSocket<SendT, RecvT> {
           throw new GuavaSocketConnectionFailed();
         }
 
-        this._logger.error(
-          "Failed to connect (attempt %d/%d). Retrying in a few seconds...\n",
-          attempt,
-          MAX_RECONNECT_ATTEMPTS,
-          e,
-        );
+        if (e instanceof UnexpectedResponseError) {
+          const interpretation =
+            e.statusCode === 401 || e.statusCode === 403 ? "Authentication Failure" : "HTTP error";
+          this._logger.error(
+            "Failed to connect to websocket endpoint %s due to %s. HTTP %s, Body: %s. Retrying in a few seconds...",
+            this._connectionUrl,
+            interpretation,
+            e.statusCode ?? "unknown",
+            e.body || "No response body.",
+          );
+        } else {
+          this._logger.error(
+            "Failed to connect to %s (attempt %d/%d). Retrying in a few seconds...\n",
+            this._connectionUrl,
+            attempt,
+            MAX_RECONNECT_ATTEMPTS,
+            e,
+          );
+        }
         await sleep(reconnectDelay(attempt));
       }
     }

package/src/testing/session.ts

@@ -29,15 +29,17 @@ export class TestSession {
 
   executedActions: string[] = [];
   terminationReason: string | null = null;
+  readonly id: string;
 
   /** @internal */
   get _events(): ReadonlyArray<InjectASR | BotTTS> {
     return this._sessionEvents;
   }
 
-  constructor(ws: WebSocket, client: Client) {
+  constructor(ws: WebSocket, client: Client, id: string) {
     this._ws = ws;
     this._client = client;
+    this.id = id;
 
     ws.on("message", (data) => {
       let event: TestingEvent;

package/src/utils.ts

@@ -63,3 +63,41 @@ export async function fetchOrThrow(
 
   return res;
 }
+
+/** A Disposable whose disposal does nothing. Useful as a conditional no-op. */
+export const nullDisposable: Disposable = { [Symbol.dispose]() {} };
+
+export function onAbort(signal: AbortSignal, listener: () => void): Disposable {
+  signal.throwIfAborted();
+  signal.addEventListener("abort", listener, { once: true });
+
+  return {
+    [Symbol.dispose]() {
+      signal.removeEventListener("abort", listener);
+    },
+  };
+}
+
+export function onSignal(handler: (signal: "SIGINT" | "SIGTERM") => void): Disposable {
+  // Remove both handlers on the first signal so any second signal (of either
+  // type) falls through to Node's default behavior and terminates the process.
+  const remove = () => {
+    process.off("SIGINT", sigint);
+    process.off("SIGTERM", sigterm);
+  };
+  const sigint = () => {
+    remove();
+    handler("SIGINT");
+  };
+  const sigterm = () => {
+    remove();
+    handler("SIGTERM");
+  };
+
+  process.on("SIGINT", sigint);
+  process.on("SIGTERM", sigterm);
+
+  return {
+    [Symbol.dispose]: remove,
+  };
+}

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.29.0";
+export const SDK_VERSION = "0.31.0";