@talqing/client 0.4.0 → 0.6.0

package/README.md

@@ -83,6 +83,42 @@ mid-upload, which is a third outcome and not a failure you can describe.
 `talqingImageDataUrl(file)` are the three steps on their own. The last produces
 the `data:` URL a **text** message carries.
 
+## Chats
+
+The one thing here with no room behind it: a text chat, over HTTP. Your
+**server** starts the chat with `POST /v1/chats`, mints a token for it with
+`POST /v1/chats/{id}/token`, and hands the browser that response unchanged. The
+token opens that one chat and nothing else.
+
+```ts
+import { TalqingChat } from "@talqing/client";
+
+const chat = new TalqingChat({
+  fetchToken: async () => {
+    const response = await fetch("/api/talqing-chat-token", { method: "POST" });
+    return await response.json(); // { chat_id, token, expires_at, api_url }
+  },
+});
+
+const { events, result } = chat.send("Where is my order?");
+for await (const event of events) {
+  if (event.event === "assistant.delta") append(event.text);
+}
+const turn = await result; // { status, items, chat_status, … }
+```
+
+`events` and `result` are two views of one request; use either alone. A turn's
+`status` is `canceled` when the person sent a newer message first — that
+message's own `send` carries the reply — and `chat_status` is `ended` when the
+agent closed the chat. `send` takes `{ images }` as `data:` URLs, which
+`talqingImageDataUrl(file)` produces.
+
+`chat.items()` is the chat so far, oldest first, and `chat.end()` ends it. A
+browser only ever receives what the person can see — never the agent's tool
+calls. A token lasts an hour, so `fetchToken` is called again shortly before
+each one expires: have it mint a token for the **same** chat rather than start a
+new one. A refused request throws `TalqingChatError`, with the HTTP `status`.
+
 ## Frontend RPC
 
 A tool's `frontend_rpc` operation calls into your page. The agent sends one

package/dist/cjs/chat.d.ts

@@ -0,0 +1,104 @@
+/** 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 declare 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[]);
+}
+/** 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 declare class TalqingChat {
+    private readonly fetchToken;
+    private minted;
+    constructor(options: {
+        fetchToken: () => Promise<TalqingChatCredentials>;
+    });
+    /** 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>;
+    };
+    /** The chat so far, oldest first. */
+    items(): Promise<TalqingChatItem[]>;
+    /** End the chat. Further messages are refused. */
+    end(): Promise<void>;
+    private credentials;
+    private request;
+}
+//# sourceMappingURL=chat.d.ts.map

package/dist/cjs/chat.d.ts.map

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

package/dist/cjs/chat.js

@@ -0,0 +1,158 @@
+"use strict";
+/* ── 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TalqingChat = exports.TalqingChatError = void 0;
+/** An error response from the API. */
+class TalqingChatError extends Error {
+    constructor(status, message, errors) {
+        super(message);
+        this.name = "TalqingChatError";
+        this.status = status;
+        this.errors = errors;
+    }
+}
+exports.TalqingChatError = TalqingChatError;
+/** 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. */
+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;
+    }
+}
+exports.TalqingChat = TalqingChat;
+/** 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/cjs/chat.js.map

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

package/dist/cjs/index.d.ts

@@ -6,5 +6,7 @@ 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/cjs/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,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,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/cjs/index.js

@@ -8,9 +8,12 @@
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TALQING_SCREEN_SHARE_PUBLISH = exports.TALQING_SCREEN_SHARE_CAPTURE = exports.TALQING_AUDIO_CAPTURE_DEFAULTS = exports.TalqingRpcError = exports.registerTalqingRpcHandlers = exports.TALQING_IMAGE_TOPIC = exports.TALQING_IMAGE_MAX_EDGE_PX = exports.TALQING_IMAGE_MAX_BYTES = exports.TALQING_IMAGE_ACK_TIMEOUT_MS = exports.talqingImageRejection = exports.talqingImageDataUrl = exports.talqingDownscaleImage = exports.sendTalqingImage = exports.onTalqingImageResult = exports.talqingAgentParticipant = exports.setTalqingUserdata = exports.getTalqingUserdata = exports.createTalqingTokenSource = void 0;
+exports.TalqingChatError = exports.TalqingChat = exports.TALQING_SCREEN_SHARE_PUBLISH = exports.TALQING_SCREEN_SHARE_CAPTURE = exports.TALQING_AUDIO_CAPTURE_DEFAULTS = exports.TalqingRpcError = exports.registerTalqingRpcHandlers = exports.TALQING_IMAGE_TOPIC = exports.TALQING_IMAGE_MAX_EDGE_PX = exports.TALQING_IMAGE_MAX_BYTES = exports.TALQING_IMAGE_ACK_TIMEOUT_MS = exports.talqingImageRejection = exports.talqingImageDataUrl = exports.talqingDownscaleImage = exports.sendTalqingImage = exports.onTalqingImageResult = exports.talqingAgentParticipant = exports.setTalqingUserdata = exports.getTalqingUserdata = exports.createTalqingTokenSource = void 0;
 var token_js_1 = require("./token.js");
 Object.defineProperty(exports, "createTalqingTokenSource", { enumerable: true, get: function () { return token_js_1.createTalqingTokenSource; } });
 var userdata_js_1 = require("./userdata.js");
@@ -34,4 +37,7 @@ var media_js_1 = require("./media.js");
 Object.defineProperty(exports, "TALQING_AUDIO_CAPTURE_DEFAULTS", { enumerable: true, get: function () { return media_js_1.TALQING_AUDIO_CAPTURE_DEFAULTS; } });
 Object.defineProperty(exports, "TALQING_SCREEN_SHARE_CAPTURE", { enumerable: true, get: function () { return media_js_1.TALQING_SCREEN_SHARE_CAPTURE; } });
 Object.defineProperty(exports, "TALQING_SCREEN_SHARE_PUBLISH", { enumerable: true, get: function () { return media_js_1.TALQING_SCREEN_SHARE_PUBLISH; } });
+var chat_js_1 = require("./chat.js");
+Object.defineProperty(exports, "TalqingChat", { enumerable: true, get: function () { return chat_js_1.TalqingChat; } });
+Object.defineProperty(exports, "TalqingChatError", { enumerable: true, get: function () { return chat_js_1.TalqingChatError; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,uCAAsD;AAA7C,oHAAA,wBAAwB,OAAA;AAGjC,6CAIuB;AAHrB,iHAAA,kBAAkB,OAAA;AAClB,iHAAA,kBAAkB,OAAA;AAClB,sHAAA,uBAAuB,OAAA;AAGzB,yCAUqB;AATnB,iHAAA,oBAAoB,OAAA;AACpB,6GAAA,gBAAgB,OAAA;AAChB,kHAAA,qBAAqB,OAAA;AACrB,gHAAA,mBAAmB,OAAA;AACnB,kHAAA,qBAAqB,OAAA;AACrB,yHAAA,4BAA4B,OAAA;AAC5B,oHAAA,uBAAuB,OAAA;AACvB,sHAAA,yBAAyB,OAAA;AACzB,gHAAA,mBAAmB,OAAA;AAIrB,mCAAuE;AAA9D,oHAAA,0BAA0B,OAAA;AAAE,yGAAA,eAAe,OAAA;AAQpD,uCAIoB;AAHlB,0HAAA,8BAA8B,OAAA;AAC9B,wHAAA,4BAA4B,OAAA;AAC5B,wHAAA,4BAA4B,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,uCAAsD;AAA7C,oHAAA,wBAAwB,OAAA;AAGjC,6CAIuB;AAHrB,iHAAA,kBAAkB,OAAA;AAClB,iHAAA,kBAAkB,OAAA;AAClB,sHAAA,uBAAuB,OAAA;AAGzB,yCAUqB;AATnB,iHAAA,oBAAoB,OAAA;AACpB,6GAAA,gBAAgB,OAAA;AAChB,kHAAA,qBAAqB,OAAA;AACrB,gHAAA,mBAAmB,OAAA;AACnB,kHAAA,qBAAqB,OAAA;AACrB,yHAAA,4BAA4B,OAAA;AAC5B,oHAAA,uBAAuB,OAAA;AACvB,sHAAA,yBAAyB,OAAA;AACzB,gHAAA,mBAAmB,OAAA;AAIrB,mCAAuE;AAA9D,oHAAA,0BAA0B,OAAA;AAAE,yGAAA,eAAe,OAAA;AAQpD,uCAIoB;AAHlB,0HAAA,8BAA8B,OAAA;AAC9B,wHAAA,4BAA4B,OAAA;AAC5B,wHAAA,4BAA4B,OAAA;AAG9B,qCAA0D;AAAjD,sGAAA,WAAW,OAAA;AAAE,2GAAA,gBAAgB,OAAA"}

package/dist/esm/chat.d.ts

@@ -0,0 +1,104 @@
+/** 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 declare 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[]);
+}
+/** 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 declare class TalqingChat {
+    private readonly fetchToken;
+    private minted;
+    constructor(options: {
+        fetchToken: () => Promise<TalqingChatCredentials>;
+    });
+    /** 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>;
+    };
+    /** The chat so far, oldest first. */
+    items(): Promise<TalqingChatItem[]>;
+    /** End the chat. Further messages are refused. */
+    end(): Promise<void>;
+    private credentials;
+    private request;
+}
+//# sourceMappingURL=chat.d.ts.map

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

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

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":"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"}

package/dist/esm/index.d.ts

@@ -6,5 +6,7 @@ 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,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,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

@@ -7,10 +7,14 @@
  * 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 { 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,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;AAEpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talqing/client",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -53,10 +53,10 @@
   },
   "dependencies": {},
   "peerDependencies": {
-    "livekit-client": "^2.19.1"
+    "livekit-client": "^2.20.2"
   },
   "devDependencies": {
-    "livekit-client": "^2.19.1",
+    "livekit-client": "^2.22.3",
     "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/index.ts

@@ -7,6 +7,9 @@
  * 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";
@@ -45,4 +48,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";