@guava-ai/guava-sdk 0.18.0 → 0.19.0

package/dist/src/testing/protocol.js

@@ -0,0 +1,61 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestingEvent = exports.SessionStarted = exports.TurnStarted = exports.BotTTS = exports.WaitForTurn = exports.InjectASR = exports.Pong = exports.Ping = void 0;
+const z = __importStar(require("zod"));
+exports.Ping = z.object({ message_type: z.literal("ping") });
+exports.Pong = z.object({ message_type: z.literal("pong") });
+exports.InjectASR = z.object({
+    message_type: z.literal("inject-asr"),
+    utterance: z.string(),
+});
+exports.WaitForTurn = z.object({
+    message_type: z.literal("wait-for-caller-turn"),
+    request_id: z.string(),
+});
+exports.BotTTS = z.object({
+    message_type: z.literal("bot-tts"),
+    transcript: z.string(),
+});
+exports.TurnStarted = z.object({
+    message_type: z.literal("caller-turn-started"),
+    request_id: z.string(),
+});
+exports.SessionStarted = z.object({
+    message_type: z.literal("session-started"),
+    session_id: z.string(),
+});
+exports.TestingEvent = z.discriminatedUnion("message_type", [exports.Ping, exports.Pong, exports.BotTTS, exports.TurnStarted]);
+//# sourceMappingURL=protocol.js.map

package/dist/src/testing/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/testing/protocol.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AAEZ,QAAA,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAGrD,QAAA,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAGrD,QAAA,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAGU,QAAA,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC;IAC/C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAGU,QAAA,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAGU,QAAA,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC;IAC9C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAGU,QAAA,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC;IAC1C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAGU,QAAA,YAAY,GAAG,CAAC,CAAC,kBAAkB,CAAC,cAAc,EAAE,CAAC,YAAI,EAAE,YAAI,EAAE,cAAM,EAAE,mBAAW,CAAC,CAAC,CAAC"}

package/dist/src/testing/session.d.ts

@@ -0,0 +1,26 @@
+import type WebSocket from "ws";
+import { type BotTTS, type InjectASR, TestingEvent } from "./protocol.ts";
+import type { Client } from "../client.ts";
+export declare class TestSession {
+    private readonly _ws;
+    private readonly _client;
+    private _sessionEvents;
+    private _recvBuffer;
+    private _recvWaiters;
+    private _closed;
+    executedActions: string[];
+    terminationReason: string | null;
+    /** @internal */
+    get _events(): ReadonlyArray<InjectASR | BotTTS>;
+    constructor(ws: WebSocket, client: Client);
+    private _rawSend;
+    say(utterance: string): void;
+    recv(): Promise<TestingEvent>;
+    getTranscript(): string;
+    waitForTurn(): Promise<void>;
+    waitForEnd(): Promise<void>;
+    evaluate({ passCriteria, failCriteria, }?: {
+        passCriteria?: string[];
+        failCriteria?: string[];
+    }): Promise<void>;
+}

package/dist/src/testing/session.js

@@ -0,0 +1,219 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestSession = void 0;
+const node_crypto_1 = require("node:crypto");
+const z = __importStar(require("zod"));
+const protocol_ts_1 = require("./protocol.js");
+const llm_ts_1 = require("../helpers/llm.js");
+const _evalResponseSchema = z.object({
+    results: z.array(z.object({
+        passed: z.boolean(),
+        reasoning: z.string().optional(),
+    })),
+});
+class TestSession {
+    _ws;
+    _client;
+    _sessionEvents = [];
+    _recvBuffer = [];
+    _recvWaiters = [];
+    _closed = false;
+    executedActions = [];
+    terminationReason = null;
+    /** @internal */
+    get _events() {
+        return this._sessionEvents;
+    }
+    constructor(ws, client) {
+        this._ws = ws;
+        this._client = client;
+        ws.on("message", (data) => {
+            let event;
+            try {
+                event = protocol_ts_1.TestingEvent.parse(JSON.parse(data.toString()));
+            }
+            catch {
+                return;
+            }
+            const waiter = this._recvWaiters.shift();
+            if (waiter) {
+                waiter.resolve(event);
+            }
+            else {
+                this._recvBuffer.push(event);
+            }
+        });
+        const onClose = () => {
+            this._closed = true;
+            const err = new Error("Test session WebSocket closed");
+            for (const waiter of this._recvWaiters) {
+                waiter.reject(err);
+            }
+            this._recvWaiters = [];
+        };
+        ws.once("close", onClose);
+        ws.once("error", onClose);
+    }
+    _rawSend(msg) {
+        this._ws.send(JSON.stringify(msg));
+    }
+    say(utterance) {
+        const msg = { message_type: "inject-asr", utterance };
+        this._sessionEvents.push(msg);
+        this._rawSend(msg);
+    }
+    async recv() {
+        while (true) {
+            let event;
+            const buffered = this._recvBuffer.shift();
+            if (buffered !== undefined) {
+                event = buffered;
+            }
+            else {
+                event = await new Promise((resolve, reject) => {
+                    if (this._closed) {
+                        reject(new Error("Test session WebSocket closed"));
+                        return;
+                    }
+                    this._recvWaiters.push({ resolve, reject });
+                });
+            }
+            if (event.message_type === "ping") {
+                this._rawSend({ message_type: "pong" });
+                continue;
+            }
+            if (event.message_type === "bot-tts") {
+                this._sessionEvents.push(event);
+            }
+            return event;
+        }
+    }
+    getTranscript() {
+        const lines = [];
+        for (const event of this._sessionEvents) {
+            if (event.message_type === "inject-asr") {
+                lines.push(`[caller]: ${event.utterance}`);
+            }
+            else {
+                lines.push(`[agent]: ${event.transcript}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    async waitForTurn() {
+        const requestId = (0, node_crypto_1.randomBytes)(8).toString("hex");
+        this._rawSend({ message_type: "wait-for-caller-turn", request_id: requestId });
+        while (true) {
+            const event = await this.recv();
+            if (event.message_type === "caller-turn-started" && event.request_id === requestId) {
+                return;
+            }
+        }
+    }
+    async waitForEnd() {
+        try {
+            while (true) {
+                await this.recv();
+            }
+        }
+        catch {
+            // Connection closed — session has ended.
+        }
+    }
+    async evaluate({ passCriteria = [], failCriteria = [], } = {}) {
+        const allCriteria = [
+            ...passCriteria.map((c) => ({ kind: "pass", criterion: c })),
+            ...failCriteria.map((c) => ({ kind: "fail", criterion: c })),
+        ];
+        if (allCriteria.length === 0)
+            return;
+        const transcript = this.getTranscript();
+        const criteriaList = allCriteria.map((c, i) => `${i + 1}. ${c.criterion}`).join("\n");
+        const prompt = `Evaluate whether the following criteria are met based on the conversation transcript below.
+Return one result object per criterion in the same order as listed.
+
+Transcript:
+${transcript || "(empty — no conversation occurred)"}
+
+Criteria:
+${criteriaList}`;
+        const evalSchema = {
+            type: "object",
+            properties: {
+                results: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            passed: { type: "boolean" },
+                            reasoning: { type: "string" },
+                        },
+                        required: ["passed"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["results"],
+            additionalProperties: false,
+        };
+        const evalResponse = _evalResponseSchema.parse(JSON.parse(await (0, llm_ts_1._generate)(this._client, prompt, evalSchema)));
+        if (evalResponse.results.length !== allCriteria.length) {
+            throw new Error(`Evaluation returned ${evalResponse.results.length} results for ${allCriteria.length} criteria.`);
+        }
+        const failures = [];
+        for (let i = 0; i < allCriteria.length; i++) {
+            const { kind, criterion } = allCriteria[i];
+            const result = evalResponse.results[i];
+            if (kind === "pass" && !result.passed) {
+                let msg = `Pass criterion not met: ${JSON.stringify(criterion)}`;
+                if (result.reasoning)
+                    msg += ` — ${result.reasoning}`;
+                failures.push(msg);
+            }
+            else if (kind === "fail" && result.passed) {
+                let msg = `Fail criterion triggered: ${JSON.stringify(criterion)}`;
+                if (result.reasoning)
+                    msg += ` — ${result.reasoning}`;
+                failures.push(msg);
+            }
+        }
+        if (failures.length > 0) {
+            throw new Error(`Session evaluation failed:\n${failures.map((f) => `  • ${f}`).join("\n")}`);
+        }
+    }
+}
+exports.TestSession = TestSession;
+//# sourceMappingURL=session.js.map

package/dist/src/testing/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/testing/session.ts"],"names":[],"mappings":"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"}

package/dist/src/utils.d.ts

@@ -1,4 +1,5 @@
 export declare const DEFAULT_BASE_URL = "https://app.goguava.ai/";
 export declare function getPlatformConfigDir(): string;
+export declare function getCliConfigPath(): string;
 export declare function getBaseUrl(): string;
 export declare function fetchOrThrow(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/src/utils.js

@@ -35,8 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_BASE_URL = void 0;
 exports.getPlatformConfigDir = getPlatformConfigDir;
+exports.getCliConfigPath = getCliConfigPath;
 exports.getBaseUrl = getBaseUrl;
 exports.fetchOrThrow = fetchOrThrow;
+const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 exports.DEFAULT_BASE_URL = "https://app.goguava.ai/";
@@ -54,8 +56,20 @@ function getPlatformConfigDir() {
         return path.join(home, "Library", "Application Support");
     return process.env.XDG_CONFIG_HOME ?? path.join(home, ".config");
 }
+function getCliConfigPath() {
+    return path.join(getPlatformConfigDir(), "guava", "config.json");
+}
 function getBaseUrl() {
-    return process.env.GUAVA_BASE_URL ?? exports.DEFAULT_BASE_URL;
+    if (process.env.GUAVA_BASE_URL)
+        return process.env.GUAVA_BASE_URL;
+    // Try reading from the CLI config.
+    const configPath = getCliConfigPath();
+    if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        if (config.base_url)
+            return config.base_url;
+    }
+    return exports.DEFAULT_BASE_URL;
 }
 class HttpStatusError extends Error {
     status;

package/dist/src/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKA,oDAUC;AAED,gCAEC;AAcD,oCAaC;AA9CD,4CAA8B;AAC9B,gDAAkC;AAErB,QAAA,gBAAgB,GAAG,yBAAyB,CAAC;AAE1D,SAAgB,oBAAoB;IAClC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QACpC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC1F,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IAC9F,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,qBAAqB,CAAC,CAAC;IAC5F,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACnE,CAAC;AAED,SAAgB,UAAU;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,wBAAgB,CAAC;AACxD,CAAC;AAED,MAAM,eAAgB,SAAQ,KAAK;IAEf;IACA;IACA;IACA;IAJlB,YACkB,MAAc,EACd,UAAkB,EAClB,IAAY,EACZ,QAAkB;QAElC,KAAK,CAAC,QAAQ,MAAM,IAAI,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QALjD,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAQ;QACZ,aAAQ,GAAR,QAAQ,CAAU;QAGlC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAEM,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,IAAkB;IAElB,kDAAkD;IAClD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAErC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9C,MAAM,IAAI,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMA,oDAUC;AAED,4CAEC;AAED,gCAWC;AAcD,oCAaC;AA5DD,4CAA8B;AAC9B,4CAA8B;AAC9B,gDAAkC;AAErB,QAAA,gBAAgB,GAAG,yBAAyB,CAAC;AAE1D,SAAgB,oBAAoB;IAClC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QACpC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC1F,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IAC9F,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,qBAAqB,CAAC,CAAC;IAC5F,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACnE,CAAC;AAED,SAAgB,gBAAgB;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;AACnE,CAAC;AAED,SAAgB,UAAU;IACxB,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAElE,mCAAmC;IACnC,MAAM,UAAU,GAAG,gBAAgB,EAAE,CAAC;IACtC,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAA0B,CAAC;QACxF,IAAI,MAAM,CAAC,QAAQ;YAAE,OAAO,MAAM,CAAC,QAAQ,CAAC;IAC9C,CAAC;IAED,OAAO,wBAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,eAAgB,SAAQ,KAAK;IAEf;IACA;IACA;IACA;IAJlB,YACkB,MAAc,EACd,UAAkB,EAClB,IAAY,EACZ,QAAkB;QAElC,KAAK,CAAC,QAAQ,MAAM,IAAI,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QALjD,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAQ;QACZ,aAAQ,GAAR,QAAQ,CAAU;QAGlC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAEM,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,IAAkB;IAElB,kDAAkD;IAClD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAErC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9C,MAAM,IAAI,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.18.0";
+export declare const SDK_VERSION = "0.19.0";

package/dist/src/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
-exports.SDK_VERSION = "0.18.0";
+exports.SDK_VERSION = "0.19.0";
 //# sourceMappingURL=version.js.map

package/examples/example.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Agent testing example — demonstrates agent.test(), agent.testRoleplay(),
+ * agent.patch(), and session.evaluate().
+ */
+
+import type { Call } from "@guava-ai/guava-sdk";
+import { MockCall } from "@guava-ai/guava-sdk";
+import { agent } from "@guava-ai/guava-sdk/examples/help-desk";
+
+describe("HelpDeskAgent", () => {
+  test("handler unit test - new purchase routes to sales", async () => {
+    const suggestion = await agent.handlers.onActionRequest(new MockCall(), "make a new purchase");
+    expect(suggestion).toHaveProperty("key", "sales");
+  });
+
+  test("new purchase routes to sales", async () => {
+    const session = await agent.test(async (session) => {
+      // Wait for the agent to finish its opening turn, then inject a caller utterance.
+      await session.waitForTurn();
+      session.say("Hi, I'm looking to make a new purchase.");
+
+      // Wait for the bot to complete its transfer.
+      await session.waitForEnd();
+    });
+
+    // You can inspect the full transcript with session.getTranscript()
+
+    expect(session.executedActions).toContain("sales");
+    expect(session.terminationReason).toBe("bot-transfer");
+  });
+
+  test("roleplay - caller buys a table", async () => {
+    // testRoleplay() drives the conversation automatically using an LLM as the caller.
+    const session = await agent.testRoleplay("You are a caller trying to buy a new table.");
+
+    expect(session.executedActions).toContain("sales");
+    expect(session.terminationReason).toBe("bot-transfer");
+  });
+
+  test("patched agent - sales department closed", async () => {
+    // patch() returns a shallow clone with independently overridable callbacks.
+    const patched = agent.patch();
+
+    patched.onAction("sales", async (call: Call) => {
+      call.hangup(
+        "Tell the caller that the sales department is closed and that they should call back tomorrow from 9am to 5pm.",
+      );
+    });
+
+    const session = await patched.testRoleplay("You are a caller trying to buy a new table.");
+
+    // evaluate() uses an LLM to check natural-language pass/fail criteria against the transcript.
+    await session.evaluate({
+      passCriteria: ["The agent informed the caller of the business hours from 9am to 5pm."],
+      failCriteria: ["The agent transferred the caller to the sales department."],
+    });
+  });
+});

package/examples/help-desk.ts

@@ -3,7 +3,7 @@ import { DocumentQA, IntentRecognizer } from "@guava-ai/guava-sdk/helpers/openai
 import { FURNITURE_RETAILER_QA } from "@guava-ai/guava-sdk/example-data";
 import { getDefaultLogger } from "@guava-ai/guava-sdk";
 
-const agent = new guava.Agent({
+export const agent = new guava.Agent({
   name: "Nova",
   organization: "Clearfield Home & Living",
   purpose: "Answer questions and route callers to the appropriate department.",
@@ -55,6 +55,17 @@ agent.onAction("other", async (call: guava.Call) => {
   );
 });
 
-export async function run(_args: string[]) {
-  agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);
+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("--local")) {
+    await agent.callLocal();
+  } else if (args.includes("--chat")) {
+    await agent.chat();
+  } else {
+    console.error("Usage: guava-example help-desk --phone | --webrtc | --local | --chat");
+    process.exit(1);
+  }
 }

package/examples/property-insurance.ts

@@ -25,8 +25,10 @@ export async function run(args: string[]) {
     agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);
   } 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 | --local");
+    console.error("Usage: guava-example property-insurance --phone | --webrtc | --local | --chat");
     process.exit(1);
   }
 }

package/examples/restaurant-waitlist.ts

@@ -49,8 +49,10 @@ export async function run(args: string[]) {
     agent.listenPhone(process.env.GUAVA_AGENT_NUMBER!);
   } 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 | --local");
+    console.error("Usage: guava-example restaurant-waitlist --phone | --webrtc | --local | --chat");
     process.exit(1);
   }
 }

package/examples/scheduling-outbound.ts

@@ -44,10 +44,17 @@ agent.onTaskComplete("schedule_appointment", async (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;
+  }
+
   const [toNumber, patientName = "Benjamin Buttons"] = args;
 
   if (!toNumber) {
     console.error("Usage: guava-example scheduling-outbound <phone> [name]");
+    console.error("       guava-example scheduling-outbound --chat [name]");
     process.exit(1);
   }
 

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.18.0",
+  "version": "0.19.0",
   "type": "commonjs",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -18,12 +18,19 @@
     "./example-data": {
       "types": "./dist/src/example-data.d.ts",
       "default": "./dist/src/example-data.js"
+    },
+    "./examples/help-desk": {
+      "types": "./dist/examples/help-desk.d.ts",
+      "default": "./dist/examples/help-desk.js"
     }
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
+    "@types/jest": "^30.0.0",
     "@types/node": "^25.0.7",
     "@types/ws": "^8.18.1",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
@@ -42,6 +49,7 @@
     "autofix": "npm run format && npm run lint-fix",
     "check-format": "biome format ./src ./examples",
     "format": "biome format --write ./src ./examples",
+    "test": "jest",
     "check": "npm run typecheck && npm audit && npm run lint && npm run check-format",
     "clean": "rm -rf ./dist",
     "build": "tsx scripts/update-version.ts && tsc && chmod +x ./dist/bin/example-runner.js",