@talqing/client 0.5.0 → 0.7.0

package/dist/esm/chat.js

@@ -0,0 +1,153 @@
+/* ── chats ────────────────────────────────────────────────────────────────
+ *
+ * A text chat with an agent, from a browser. Your SERVER starts the chat
+ * (`POST /v1/chats`) and mints a token for it (`POST /v1/chats/{id}/token`);
+ * the browser holds only that token, which opens that one chat and nothing
+ * else.
+ */
+/** An error response from the API. */
+export class TalqingChatError extends Error {
+    constructor(status, message, errors) {
+        super(message);
+        this.name = "TalqingChatError";
+        this.status = status;
+        this.errors = errors;
+    }
+}
+/** How long before `expires_at` a new token is fetched. */
+const REFRESH_BEFORE_EXPIRY_MS = 60000;
+/** One chat, driven from a browser.
+ *
+ *  `fetchToken` asks YOUR server for the chat's token, and is called again
+ *  shortly before each one expires. */
+export class TalqingChat {
+    constructor(options) {
+        this.minted = null;
+        this.fetchToken = options.fetchToken;
+    }
+    /** Send a message. `events` yields the reply as it is generated; `result`
+     *  resolves with the whole turn. Either can be used without the other. */
+    send(text, options = {}) {
+        const queue = [];
+        let finished = false;
+        let failure;
+        let wake = null;
+        const notify = () => {
+            wake?.();
+            wake = null;
+        };
+        const result = (async () => {
+            const response = await this.request("/messages", {
+                method: "POST",
+                body: JSON.stringify({
+                    message: text,
+                    images: options.images ?? [],
+                    client_message_id: crypto.randomUUID(),
+                    stream: true,
+                }),
+            });
+            for await (const event of readEvents(response)) {
+                queue.push(event);
+                notify();
+                if (event.event === "turn.result") {
+                    const { event: _name, ...turn } = event;
+                    return turn;
+                }
+            }
+            throw new TalqingChatError(response.status, "the reply ended before it finished", []);
+        })();
+        result
+            .catch((error) => {
+            failure = error;
+        })
+            .finally(() => {
+            finished = true;
+            notify();
+        });
+        const events = {
+            [Symbol.asyncIterator]: async function* () {
+                for (;;) {
+                    while (queue.length > 0)
+                        yield queue.shift();
+                    if (finished) {
+                        if (failure !== undefined)
+                            throw failure;
+                        return;
+                    }
+                    await new Promise((resolve) => {
+                        wake = resolve;
+                    });
+                }
+            },
+        };
+        return { events, result };
+    }
+    /** The chat so far, oldest first. */
+    async items() {
+        const items = [];
+        for (;;) {
+            const response = await this.request(`/items?limit=500&offset=${items.length}`, {
+                method: "GET",
+            });
+            const page = (await response.json());
+            items.push(...page.items);
+            if (!page.has_more)
+                return items;
+        }
+    }
+    /** End the chat. Further messages are refused. */
+    async end() {
+        await this.request("/end", { method: "POST" });
+    }
+    credentials() {
+        const current = this.minted;
+        this.minted = (async () => {
+            const held = await current?.catch(() => null);
+            if (held && Date.parse(held.expires_at) - Date.now() > REFRESH_BEFORE_EXPIRY_MS) {
+                return held;
+            }
+            return this.fetchToken();
+        })();
+        return this.minted;
+    }
+    async request(path, init) {
+        const { api_url, chat_id, token } = await this.credentials();
+        const response = await fetch(`${api_url}/v1/chats/${chat_id}${path}`, {
+            ...init,
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => null));
+            throw new TalqingChatError(response.status, body?.detail?.message ?? response.statusText, body?.detail?.errors ?? []);
+        }
+        return response;
+    }
+}
+/** Parse a `text/event-stream` body into its frames. Keep-alive comments are dropped. */
+async function* readEvents(response) {
+    if (!response.body)
+        return;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            return;
+        buffer += decoder.decode(value, { stream: true });
+        let boundary = buffer.indexOf("\n\n");
+        while (boundary !== -1) {
+            const frame = buffer.slice(0, boundary);
+            buffer = buffer.slice(boundary + 2);
+            const data = frame
+                .split("\n")
+                .filter((line) => line.startsWith("data:"))
+                .map((line) => line.slice(5).trimStart())
+                .join("\n");
+            if (data)
+                yield JSON.parse(data);
+            boundary = buffer.indexOf("\n\n");
+        }
+    }
+}
+//# sourceMappingURL=chat.js.map

package/dist/esm/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../src/chat.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoEH,sCAAsC;AACtC,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAMzC,YAAY,MAAc,EAAE,OAAe,EAAE,MAAgB;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC;QANR,SAAI,GAAG,kBAAkB,CAAC;QAOjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,wBAAwB,GAAG,KAAM,CAAC;AAExC;;;uCAGuC;AACvC,MAAM,OAAO,WAAW;IAItB,YAAY,OAA8D;QAFlE,WAAM,GAA2C,IAAI,CAAC;QAG5D,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACvC,CAAC;IAED;8EAC0E;IAC1E,IAAI,CACF,IAAY,EACZ,UAA2C,EAAE;QAE7C,MAAM,KAAK,GAAuB,EAAE,CAAC;QACrC,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,OAAgB,CAAC;QACrB,IAAI,IAAI,GAAwB,IAAI,CAAC;QACrC,MAAM,MAAM,GAAG,GAAG,EAAE;YAClB,IAAI,EAAE,EAAE,CAAC;YACT,IAAI,GAAG,IAAI,CAAC;QACd,CAAC,CAAC;QAEF,MAAM,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;YACzB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE;gBAC/C,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,OAAO,EAAE,IAAI;oBACb,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;oBAC5B,iBAAiB,EAAE,MAAM,CAAC,UAAU,EAAE;oBACtC,MAAM,EAAE,IAAI;iBACb,CAAC;aACH,CAAC,CAAC;YACH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC/C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAClB,MAAM,EAAE,CAAC;gBACT,IAAI,KAAK,CAAC,KAAK,KAAK,aAAa,EAAE,CAAC;oBAClC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;oBACxC,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;YACD,MAAM,IAAI,gBAAgB,CAAC,QAAQ,CAAC,MAAM,EAAE,oCAAoC,EAAE,EAAE,CAAC,CAAC;QACxF,CAAC,CAAC,EAAE,CAAC;QACL,MAAM;aACH,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;QAEL,MAAM,MAAM,GAAoC;YAC9C,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,KAAK,SAAS,CAAC;gBACrC,SAAS,CAAC;oBACR,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC;wBAAE,MAAM,KAAK,CAAC,KAAK,EAAsB,CAAC;oBACjE,IAAI,QAAQ,EAAE,CAAC;wBACb,IAAI,OAAO,KAAK,SAAS;4BAAE,MAAM,OAAO,CAAC;wBACzC,OAAO;oBACT,CAAC;oBACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;wBAClC,IAAI,GAAG,OAAO,CAAC;oBACjB,CAAC,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;SACF,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK;QACT,MAAM,KAAK,GAAsB,EAAE,CAAC;QACpC,SAAS,CAAC;YACR,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,2BAA2B,KAAK,CAAC,MAAM,EAAE,EAAE;gBAC7E,MAAM,EAAE,KAAK;aACd,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAoD,CAAC;YACxF,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,QAAQ;gBAAE,OAAO,KAAK,CAAC;QACnC,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,GAAG;QACP,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;IAEO,WAAW;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;YACxB,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;YAC9C,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,wBAAwB,EAAE,CAAC;gBAChF,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;QAC3B,CAAC,CAAC,EAAE,CAAC;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,IAAiB;QACnD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QAC7D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,aAAa,OAAO,GAAG,IAAI,EAAE,EAAE;YACpE,GAAG,IAAI;YACP,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAClF,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAE7C,CAAC;YACT,MAAM,IAAI,gBAAgB,CACxB,QAAQ,CAAC,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,OAAO,IAAI,QAAQ,CAAC,UAAU,EAC5C,IAAI,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,CAC3B,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAED,yFAAyF;AACzF,KAAK,SAAS,CAAC,CAAC,UAAU,CAAC,QAAkB;IAC3C,IAAI,CAAC,QAAQ,CAAC,IAAI;QAAE,OAAO;IAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,SAAS,CAAC;QACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,IAAI;YAAE,OAAO;QACjB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,IAAI,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YACxC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;YACpC,MAAM,IAAI,GAAG,KAAK;iBACf,KAAK,CAAC,IAAI,CAAC;iBACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;iBAC1C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;iBACxC,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,IAAI,IAAI;gBAAE,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAqB,CAAC;YACrD,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/esm/images.js

@@ -1,4 +1,4 @@
-import { talqingAgentParticipant } from "./userdata.js";
+import { talqingAgentParticipant } from "./participant.js";
 /* ── images ───────────────────────────────────────────────────────────────
  *
  * A caller attaches a photo on a web voice or video call and the agent sees

package/dist/esm/images.js.map

@@ -1 +1 @@
-{"version":3,"file":"images.js","sourceRoot":"","sources":["../../src/images.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AACpD;2EAC2E;AAC3E,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACxD;;gEAEgE;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAC9C,MAAM,mBAAmB,GAAG,CAAC,YAAY,EAAE,WAAW,EAAE,YAAY,CAAU,CAAC;AAC/E;;uBAEuB;AACvB,MAAM,CAAC,MAAM,4BAA4B,GAAG,KAAM,CAAC;AAEnD;;;wBAGwB;AACxB,MAAM,UAAU,qBAAqB,CAAC,IAAU;IAC9C,IAAI,CAAE,mBAAyC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpE,OAAO,sCAAsC,CAAC;IAChD,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,GAAG,uBAAuB;QAAE,OAAO,6BAA6B,CAAC;IAC9E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;gCAIgC;AAChC,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAU;IACpD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,OAAO,GAAG,yBAAyB,CAAC,CAAC,CAAC,yBAAyB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5F,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACnE,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7D,wEAAwE;QACxE,8BAA8B;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC;QACpE,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,EAAE,CACtD,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CACnC,CAAC;QACF,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;6EAI6E;AAC7E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAU;IAClD,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnD,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,CAAC;QACzE,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACrD,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC;AAoBD;;;;6EAI6E;AAC7E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAU,EAAE,IAAU;IAC3D,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAE1C,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC/C,yEAAyE;IACzE,4DAA4D;IAC5D,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CACjD,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAChD;QACE,KAAK,EAAE,mBAAmB;QAC1B,QAAQ,EAAE,IAAI,CAAC,IAAI;QACnB,qBAAqB,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;KACxC,CACF,CAAC;IACF,OAAO;QACL,QAAQ,EAAE,EAAE;QACZ,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,UAAU,EAAE,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC;QACrC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE;QAClB,MAAM,EAAE,SAAS;KAClB,CAAC;AACJ,CAAC;AAED;;;4EAG4E;AAC5E,MAAM,UAAU,oBAAoB,CAClC,IAAU,EACV,QAA6E;IAE7E,IAAI,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,IAAuB,EAAE,EAAE;QAC/E,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAI/D,CAAC;QACF,QAAQ,CAAC;YACP,QAAQ,EAAE,SAAS;YACnB,EAAE;YACF,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,6BAA6B;SAC/D,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"images.js","sourceRoot":"","sources":["../../src/images.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AACpD;2EAC2E;AAC3E,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACxD;;gEAEgE;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAC9C,MAAM,mBAAmB,GAAG,CAAC,YAAY,EAAE,WAAW,EAAE,YAAY,CAAU,CAAC;AAC/E;;uBAEuB;AACvB,MAAM,CAAC,MAAM,4BAA4B,GAAG,KAAM,CAAC;AAEnD;;;wBAGwB;AACxB,MAAM,UAAU,qBAAqB,CAAC,IAAU;IAC9C,IAAI,CAAE,mBAAyC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpE,OAAO,sCAAsC,CAAC;IAChD,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,GAAG,uBAAuB;QAAE,OAAO,6BAA6B,CAAC;IAC9E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;gCAIgC;AAChC,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAU;IACpD,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,OAAO,GAAG,yBAAyB,CAAC,CAAC,CAAC,yBAAyB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5F,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACnE,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7D,wEAAwE;QACxE,8BAA8B;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC;QACpE,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,EAAE,CACtD,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CACnC,CAAC;QACF,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;6EAI6E;AAC7E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAU;IAClD,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnD,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,CAAC;QACzE,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACrD,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC;AAoBD;;;;6EAI6E;AAC7E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAU,EAAE,IAAU;IAC3D,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAE1C,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC/C,yEAAyE;IACzE,4DAA4D;IAC5D,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CACjD,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAChD;QACE,KAAK,EAAE,mBAAmB;QAC1B,QAAQ,EAAE,IAAI,CAAC,IAAI;QACnB,qBAAqB,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;KACxC,CACF,CAAC;IACF,OAAO;QACL,QAAQ,EAAE,EAAE;QACZ,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,UAAU,EAAE,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC;QACrC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE;QAClB,MAAM,EAAE,SAAS;KAClB,CAAC;AACJ,CAAC;AAED;;;4EAG4E;AAC5E,MAAM,UAAU,oBAAoB,CAClC,IAAU,EACV,QAA6E;IAE7E,IAAI,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,IAAuB,EAAE,EAAE;QAC/E,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAI/D,CAAC;QACF,QAAQ,CAAC;YACP,QAAQ,EAAE,SAAS;YACnB,EAAE;YACF,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,6BAA6B;SAC/D,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,sBAAsB,CAAC,CAAC;AAChE,CAAC"}

package/dist/esm/index.d.ts

@@ -1,10 +1,12 @@
 export { createTalqingTokenSource } from "./token.js";
 export type { TalqingCallCredentials } from "./token.js";
-export { getTalqingUserdata, setTalqingUserdata, talqingAgentParticipant, } from "./userdata.js";
+export { talqingAgentParticipant } from "./participant.js";
 export { onTalqingImageResult, sendTalqingImage, talqingDownscaleImage, talqingImageDataUrl, talqingImageRejection, TALQING_IMAGE_ACK_TIMEOUT_MS, TALQING_IMAGE_MAX_BYTES, TALQING_IMAGE_MAX_EDGE_PX, TALQING_IMAGE_TOPIC, } from "./images.js";
 export type { TalqingImageStatus, TalqingSentImage } from "./images.js";
 export { registerTalqingRpcHandlers, TalqingRpcError } from "./rpc.js";
 export type { TalqingFrontendRpcEnvelope, TalqingRpcHandler, TalqingRpcHandlers, TalqingRpcInvocation, } from "./rpc.js";
 export { TALQING_AUDIO_CAPTURE_DEFAULTS, TALQING_SCREEN_SHARE_CAPTURE, TALQING_SCREEN_SHARE_PUBLISH, } from "./media.js";
+export { TalqingChat, TalqingChatError } from "./chat.js";
+export type { TalqingChatAttachment, TalqingChatCredentials, TalqingChatEvent, TalqingChatImage, TalqingChatItem, TalqingChatTurn, } from "./chat.js";
 export type { JsonObject, JsonPrimitive, JsonValue } from "./json.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAExE,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACvE,YAAY,EACV,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAExE,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACvE,YAAY,EACV,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/esm/index.js

@@ -1,16 +1,20 @@
 /* The Talqing call protocol, over a LiveKit `Room`. Framework-free.
  *
  * Everything here is something only Talqing can write: the mint-once token
- * source, the two userdata RPC methods, the `talqing.images` byte-stream topic
+ * source, the `talqing.images` byte-stream topic
  * and its ack, the `talqing.frontend_rpc` envelope, and the measured capture
  * settings. Nothing here renames LiveKit — for a room, a track or a
  * participant, use `livekit-client` directly.
  *
  * React bindings for all of it are `@talqing/react`.
+ *
+ * `TalqingChat` is the one thing here with no room behind it: a text chat, over
+ * HTTP, on a chat token.
  */
 export { createTalqingTokenSource } from "./token.js";
-export { getTalqingUserdata, setTalqingUserdata, talqingAgentParticipant, } from "./userdata.js";
+export { talqingAgentParticipant } from "./participant.js";
 export { onTalqingImageResult, sendTalqingImage, talqingDownscaleImage, talqingImageDataUrl, talqingImageRejection, TALQING_IMAGE_ACK_TIMEOUT_MS, TALQING_IMAGE_MAX_BYTES, TALQING_IMAGE_MAX_EDGE_PX, TALQING_IMAGE_TOPIC, } from "./images.js";
 export { registerTalqingRpcHandlers, TalqingRpcError } from "./rpc.js";
 export { TALQING_AUDIO_CAPTURE_DEFAULTS, TALQING_SCREEN_SHARE_CAPTURE, TALQING_SCREEN_SHARE_PUBLISH, } from "./media.js";
+export { TalqingChat, TalqingChatError } from "./chat.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAGtD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAQvE,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAGtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAQvE,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/esm/participant.d.ts

@@ -0,0 +1,8 @@
+import { type RemoteParticipant, type Room } from "livekit-client";
+/** The agent on this call, or undefined before it has joined.
+ *
+ *  On a video call the avatar worker is an agent participant too, but it joins
+ *  on the agent's behalf and never answers RPCs, so the first one found is the
+ *  one to talk to. */
+export declare function talqingAgentParticipant(room: Room): RemoteParticipant | undefined;
+//# sourceMappingURL=participant.d.ts.map

package/dist/esm/participant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"participant.d.ts","sourceRoot":"","sources":["../../src/participant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEpF;;;;sBAIsB;AACtB,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,iBAAiB,GAAG,SAAS,CAIjF"}

package/dist/esm/participant.js

@@ -0,0 +1,10 @@
+import { ParticipantKind } from "livekit-client";
+/** The agent on this call, or undefined before it has joined.
+ *
+ *  On a video call the avatar worker is an agent participant too, but it joins
+ *  on the agent's behalf and never answers RPCs, so the first one found is the
+ *  one to talk to. */
+export function talqingAgentParticipant(room) {
+    return [...room.remoteParticipants.values()].find((participant) => participant.kind === ParticipantKind.AGENT);
+}
+//# sourceMappingURL=participant.js.map

package/dist/esm/participant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"participant.js","sourceRoot":"","sources":["../../src/participant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqC,MAAM,gBAAgB,CAAC;AAEpF;;;;sBAIsB;AACtB,MAAM,UAAU,uBAAuB,CAAC,IAAU;IAChD,OAAO,CAAC,GAAG,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAC/C,CAAC,WAA8B,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,KAAK,eAAe,CAAC,KAAK,CAC/E,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talqing/client",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "The Talqing call protocol over a LiveKit room — token, userdata, images, screen share and frontend RPC. Framework-free.",
   "license": "MIT",
   "homepage": "https://talqing.com",
@@ -56,7 +56,7 @@
     "livekit-client": "^2.20.2"
   },
   "devDependencies": {
-    "livekit-client": "^2.22.3",
+    "livekit-client": "^2.22.4",
     "typescript": "~5.9.3"
   }
 }

package/src/chat.ts

@@ -0,0 +1,238 @@
+/* ── chats ────────────────────────────────────────────────────────────────
+ *
+ * A text chat with an agent, from a browser. Your SERVER starts the chat
+ * (`POST /v1/chats`) and mints a token for it (`POST /v1/chats/{id}/token`);
+ * the browser holds only that token, which opens that one chat and nothing
+ * else.
+ */
+
+/** What `POST /v1/chats/{id}/token` returns, named as the API names it — so a
+ *  server that mints one can forward the response through unchanged. */
+export interface TalqingChatCredentials {
+  chat_id: string;
+  token: string;
+  /** ISO 8601. A token lasts an hour. */
+  expires_at: string;
+  /** The API this chat lives on. */
+  api_url: string;
+}
+
+export interface TalqingChatAttachment {
+  id: string;
+  kind: "image";
+  mime_type: string;
+  bytes: number;
+  width: number;
+  height: number;
+  filename: string | null;
+  /** Signed, and short-lived: valid until `url_expires_at`. */
+  url: string;
+  url_expires_at: string;
+}
+
+/** One message in the chat. A browser only ever receives what the person
+ *  chatting can see — never the agent's tool calls. */
+export interface TalqingChatItem {
+  id: string;
+  /** The message this one answers; null on the person's own messages. */
+  trigger_item_id: string | null;
+  direction: "inbound" | "outbound" | "internal";
+  type: string;
+  role: "user" | "assistant" | "system" | "developer" | "tool" | null;
+  /** Null on a message that is only images. */
+  text: string | null;
+  attachments: TalqingChatAttachment[];
+  created_at: string;
+}
+
+/** What one message led to. */
+export interface TalqingChatTurn {
+  input: TalqingChatItem;
+  /** `canceled`: a newer message arrived first, named by `superseded_by_item_id`. */
+  status: "done" | "error" | "canceled" | "running";
+  error: string | null;
+  superseded_by_item_id: string | null;
+  /** Everything the agent said in reply, oldest first. */
+  items: TalqingChatItem[];
+  /** `ended` when the agent ended the chat on this turn. */
+  chat_status: "open" | "ended";
+}
+
+/** A frame of a reply as it is generated. `assistant.delta` chunks append. */
+export type TalqingChatEvent =
+  | { event: "assistant.started"; trigger_item_id: string }
+  | { event: "assistant.delta"; trigger_item_id: string; text: string }
+  | { event: "assistant.completed"; trigger_item_id: string; text: string | null }
+  | ({ event: "item.created" } & TalqingChatItem)
+  | ({ event: "turn.result" } & TalqingChatTurn);
+
+/** An image to send with a message, as a `data:` URL. */
+export interface TalqingChatImage {
+  data_url: string;
+  filename?: string;
+}
+
+/** An error response from the API. */
+export class TalqingChatError extends Error {
+  readonly name = "TalqingChatError";
+  readonly status: number;
+  /** Per-field problems, when the failure had more than one. */
+  readonly errors: string[];
+
+  constructor(status: number, message: string, errors: string[]) {
+    super(message);
+    this.status = status;
+    this.errors = errors;
+  }
+}
+
+/** How long before `expires_at` a new token is fetched. */
+const REFRESH_BEFORE_EXPIRY_MS = 60_000;
+
+/** One chat, driven from a browser.
+ *
+ *  `fetchToken` asks YOUR server for the chat's token, and is called again
+ *  shortly before each one expires. */
+export class TalqingChat {
+  private readonly fetchToken: () => Promise<TalqingChatCredentials>;
+  private minted: Promise<TalqingChatCredentials> | null = null;
+
+  constructor(options: { fetchToken: () => Promise<TalqingChatCredentials> }) {
+    this.fetchToken = options.fetchToken;
+  }
+
+  /** Send a message. `events` yields the reply as it is generated; `result`
+   *  resolves with the whole turn. Either can be used without the other. */
+  send(
+    text: string,
+    options: { images?: TalqingChatImage[] } = {},
+  ): { events: AsyncIterable<TalqingChatEvent>; result: Promise<TalqingChatTurn> } {
+    const queue: TalqingChatEvent[] = [];
+    let finished = false;
+    let failure: unknown;
+    let wake: (() => void) | null = null;
+    const notify = () => {
+      wake?.();
+      wake = null;
+    };
+
+    const result = (async () => {
+      const response = await this.request("/messages", {
+        method: "POST",
+        body: JSON.stringify({
+          message: text,
+          images: options.images ?? [],
+          client_message_id: crypto.randomUUID(),
+          stream: true,
+        }),
+      });
+      for await (const event of readEvents(response)) {
+        queue.push(event);
+        notify();
+        if (event.event === "turn.result") {
+          const { event: _name, ...turn } = event;
+          return turn;
+        }
+      }
+      throw new TalqingChatError(response.status, "the reply ended before it finished", []);
+    })();
+    result
+      .catch((error: unknown) => {
+        failure = error;
+      })
+      .finally(() => {
+        finished = true;
+        notify();
+      });
+
+    const events: AsyncIterable<TalqingChatEvent> = {
+      [Symbol.asyncIterator]: async function* () {
+        for (;;) {
+          while (queue.length > 0) yield queue.shift() as TalqingChatEvent;
+          if (finished) {
+            if (failure !== undefined) throw failure;
+            return;
+          }
+          await new Promise<void>((resolve) => {
+            wake = resolve;
+          });
+        }
+      },
+    };
+    return { events, result };
+  }
+
+  /** The chat so far, oldest first. */
+  async items(): Promise<TalqingChatItem[]> {
+    const items: TalqingChatItem[] = [];
+    for (;;) {
+      const response = await this.request(`/items?limit=500&offset=${items.length}`, {
+        method: "GET",
+      });
+      const page = (await response.json()) as { items: TalqingChatItem[]; has_more: boolean };
+      items.push(...page.items);
+      if (!page.has_more) return items;
+    }
+  }
+
+  /** End the chat. Further messages are refused. */
+  async end(): Promise<void> {
+    await this.request("/end", { method: "POST" });
+  }
+
+  private credentials(): Promise<TalqingChatCredentials> {
+    const current = this.minted;
+    this.minted = (async () => {
+      const held = await current?.catch(() => null);
+      if (held && Date.parse(held.expires_at) - Date.now() > REFRESH_BEFORE_EXPIRY_MS) {
+        return held;
+      }
+      return this.fetchToken();
+    })();
+    return this.minted;
+  }
+
+  private async request(path: string, init: RequestInit): Promise<Response> {
+    const { api_url, chat_id, token } = await this.credentials();
+    const response = await fetch(`${api_url}/v1/chats/${chat_id}${path}`, {
+      ...init,
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    });
+    if (!response.ok) {
+      const body = (await response.json().catch(() => null)) as {
+        detail?: { message?: string; errors?: string[] };
+      } | null;
+      throw new TalqingChatError(
+        response.status,
+        body?.detail?.message ?? response.statusText,
+        body?.detail?.errors ?? [],
+      );
+    }
+    return response;
+  }
+}
+
+/** Parse a `text/event-stream` body into its frames. Keep-alive comments are dropped. */
+async function* readEvents(response: Response): AsyncGenerator<TalqingChatEvent> {
+  if (!response.body) return;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) return;
+    buffer += decoder.decode(value, { stream: true });
+    let boundary = buffer.indexOf("\n\n");
+    while (boundary !== -1) {
+      const frame = buffer.slice(0, boundary);
+      buffer = buffer.slice(boundary + 2);
+      const data = frame
+        .split("\n")
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trimStart())
+        .join("\n");
+      if (data) yield JSON.parse(data) as TalqingChatEvent;
+      boundary = buffer.indexOf("\n\n");
+    }
+  }
+}

package/src/images.ts

@@ -1,5 +1,5 @@
 import type { Room, RpcInvocationData } from "livekit-client";
-import { talqingAgentParticipant } from "./userdata.js";
+import { talqingAgentParticipant } from "./participant.js";
 
 /* ── images ───────────────────────────────────────────────────────────────
  *

package/src/index.ts

@@ -1,22 +1,21 @@
 /* The Talqing call protocol, over a LiveKit `Room`. Framework-free.
  *
  * Everything here is something only Talqing can write: the mint-once token
- * source, the two userdata RPC methods, the `talqing.images` byte-stream topic
+ * source, the `talqing.images` byte-stream topic
  * and its ack, the `talqing.frontend_rpc` envelope, and the measured capture
  * settings. Nothing here renames LiveKit — for a room, a track or a
  * participant, use `livekit-client` directly.
  *
  * React bindings for all of it are `@talqing/react`.
+ *
+ * `TalqingChat` is the one thing here with no room behind it: a text chat, over
+ * HTTP, on a chat token.
  */
 
 export { createTalqingTokenSource } from "./token.js";
 export type { TalqingCallCredentials } from "./token.js";
 
-export {
-  getTalqingUserdata,
-  setTalqingUserdata,
-  talqingAgentParticipant,
-} from "./userdata.js";
+export { talqingAgentParticipant } from "./participant.js";
 
 export {
   onTalqingImageResult,
@@ -45,4 +44,14 @@ export {
   TALQING_SCREEN_SHARE_PUBLISH,
 } from "./media.js";
 
+export { TalqingChat, TalqingChatError } from "./chat.js";
+export type {
+  TalqingChatAttachment,
+  TalqingChatCredentials,
+  TalqingChatEvent,
+  TalqingChatImage,
+  TalqingChatItem,
+  TalqingChatTurn,
+} from "./chat.js";
+
 export type { JsonObject, JsonPrimitive, JsonValue } from "./json.js";

package/src/participant.ts

@@ -0,0 +1,12 @@
+import { ParticipantKind, type RemoteParticipant, type Room } from "livekit-client";
+
+/** The agent on this call, or undefined before it has joined.
+ *
+ *  On a video call the avatar worker is an agent participant too, but it joins
+ *  on the agent's behalf and never answers RPCs, so the first one found is the
+ *  one to talk to. */
+export function talqingAgentParticipant(room: Room): RemoteParticipant | undefined {
+  return [...room.remoteParticipants.values()].find(
+    (participant: RemoteParticipant) => participant.kind === ParticipantKind.AGENT,
+  );
+}

package/src/userdata.ts

@@ -1,57 +0,0 @@
-import { ParticipantKind, type RemoteParticipant, type Room } from "livekit-client";
-import type { JsonObject } from "./json.js";
-
-/** The agent on this call, or undefined before it has joined.
- *
- *  On a video call the avatar worker is an agent participant too, but it joins
- *  on the agent's behalf and never answers RPCs, so the first one found is the
- *  one to talk to. */
-export function talqingAgentParticipant(room: Room): RemoteParticipant | undefined {
-  return [...room.remoteParticipants.values()].find(
-    (participant: RemoteParticipant) => participant.kind === ParticipantKind.AGENT,
-  );
-}
-
-/** Merge a patch into the live session's userdata, over RPC to the agent.
- *
- *  Resolves rather than throws when the agent is not there: a write that did
- *  not land is a state a page can render. */
-export async function setTalqingUserdata(
-  room: Room,
-  patch: JsonObject,
-  responseTimeout = 3,
-): Promise<{ ok: boolean; error?: string }> {
-  const agent = talqingAgentParticipant(room);
-  if (!agent) return { ok: false, error: "agent participant is not connected" };
-  const response = await room.localParticipant.performRpc({
-    destinationIdentity: agent.identity,
-    method: "talqing.client.userdata_set",
-    payload: JSON.stringify(patch),
-    responseTimeout,
-  });
-  return JSON.parse(response || "{}") as { ok: boolean; error?: string };
-}
-
-/** Read the live session's userdata, or only the keys named.
- *
- *  Throws when the agent is not there, unlike `setTalqingUserdata`: a read that
- *  returned nothing is not a state anything can render. */
-export async function getTalqingUserdata(
-  room: Room,
-  keys?: string[],
-  responseTimeout = 3,
-): Promise<JsonObject> {
-  const agent = talqingAgentParticipant(room);
-  if (!agent) throw new Error("agent participant is not connected");
-  const response = await room.localParticipant.performRpc({
-    destinationIdentity: agent.identity,
-    method: "talqing.client.userdata_get",
-    payload: JSON.stringify(keys ? { keys } : {}),
-    responseTimeout,
-  });
-  const parsed = JSON.parse(response || "{}") as JsonObject & { ok?: boolean; error?: string };
-  if (parsed.ok === false) {
-    throw new Error(String(parsed.error || "userdata RPC failed"));
-  }
-  return parsed;
-}