# @xanots/chatbot A [XanoTS](https://www.npmjs.com/package/@xanots/sdk) package that ships a working conversational AI assistant — the `conversation` and `conversation_message` tables, a Xano AI **agent**, and the chat endpoints that drive them — as typed defs you can register into any workspace and version behind npm. Install it, point it at the table your users live in, write a system prompt. That is the whole setup: the thread, its history, and the model call are already wired. ```bash npm install @xanots/chatbot @xanots/sdk # or, inside a scaffolded project: xanots marketplace install @xanots/chatbot ``` ```ts // xano/index.ts import { workspace } from "@xanots/sdk"; import { registerAuth, userTable } from "@xanots/auth"; import { registerChatbot } from "@xanots/chatbot"; const xano = registerAuth(workspace("my-app"), { canonical: "authn" }); export const bot = registerChatbot(xano, { authTable: userTable, llm: { type: "xano-free", systemPrompt: "You are a support agent for Acme." }, }); export default bot.xano; // the default export must be the Xano registry ``` ```bash npx xanots deploy ./xano/index.ts ``` ```bash curl -X POST "$BASE/api:$CANONICAL/chat/conversations/create" \ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}' # → { "id": 1, "created_at": …, "title": "", "last_message_at": null } curl -X POST "$BASE/api:$CANONICAL/chat/conversations/1/send" \ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ -d '{"content":"My favourite colour is chartreuse. Just acknowledge."}' # → { "conversation_id": 1, "reply": "Acknowledged.", "message_id": 2 } curl -X POST "$BASE/api:$CANONICAL/chat/conversations/1/send" \ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ -d '{"content":"What is my favourite colour?"}' # → { "reply": "Your favourite colour is chartreuse.", … } ``` That second reply is the point of the package. Nothing in your stack had to assemble a transcript, and nothing in the client had to resend one. ## It does not depend on `@xanots/auth` Nothing here imports it. `authTable` takes any `table()` handle or table name, so the `@xanots/auth` example above is a convention, not a coupling — your own auth table works identically: ```ts const members = table({ name: "members", auth: true, schema: { /* … */ } }); registerChatbot(xano, { authTable: members }); ``` `table({ auth: true })` is the **convention**, not the mechanism. Xano gates a request by comparing the token's table against the endpoint's configured table *by name*, and mints a token for any table by name — neither side reads the flag, which only decides what the editor's auth picker offers. So an unflagged table authenticates fine; the SDK just warns at export. Two things to know when passing a **bare name**: - The table must still be registered on the workspace. The SDK resolves the reference to a name-derived guid with no registry lookup, then errors at export if nothing matches — deliberately, since a mistyped name would otherwise produce a valid-looking guid that only fails at deploy. - The SDK cannot read a primary-key type off a name, so pass `{ userIdType: "uuid" }` for a uuid-keyed table. With a **handle** the SDK reads `idType` itself and throws on a mismatch, which is why the handle is preferred. A raw numeric `dbo.id` is **not** accepted, unlike the SDK's `auth` option. The same table is also the target of `conversation.user_id`, and `f.tableRef` resolves through `ObjectRef` (`string | { name, guid? }`), which has no numeric form. ## Building a frontend The short version, in order: generate `xano/routes.gen.ts` with `npx xanots routes ./xano/index.ts --emit xano/routes.gen.ts`, `import type` the request/response types from this package, and wire four calls — list, create, transcript, send. Render assistant turns as Markdown with raw HTML disabled and user turns as plain text, serialize sends per thread, and handle `401`/`404`/`429`. `llms.txt` carries the same path as a single checklist, and each item has a section of its own below. ## Endpoints Paths below assume the default `routePrefix: "chat"`. ### Authenticated (`{ authenticated: true }`, the default) Every endpoint takes `Authorization: Bearer ` for `authTable` and is scoped to `auth("id")`. | Verb | Path | Returns | |---|---|---| | POST | `chat/conversations/create` | the new conversation | | GET | `chat/conversations` | the caller's conversations, most recently active first | | GET | `chat/conversations/{conversation_id}/messages` | the transcript, oldest first | | POST | `chat/conversations/{conversation_id}/send` | `{ conversation_id, reply, message_id, tool_calls }` | | DELETE | `chat/conversations/{conversation_id}` | `null` | | POST | `chat/conversations/{conversation_id}/claim` | the claimed conversation *(only with `guest: true`)* | ### Guest (`{ guest: true }`, off by default) Public endpoints scoped by an unguessable `session_token` instead of a login. **Read [Guest threads are protected by a bearer capability](#guest-threads-are-protected-by-a-bearer-capability) before enabling this.** | Verb | Path | Returns | |---|---|---| | POST | `chat/guest/conversations/create` | the conversation **plus its `session_token`** | | GET | `chat/guest/conversations/{conversation_id}/messages` | the transcript | | POST | `chat/guest/conversations/{conversation_id}/send` | `{ conversation_id, reply, message_id, tool_calls }` | | POST | `chat/guest/conversations/{conversation_id}/delete` | `null` | Guest endpoints take `session_token` as a parameter. The delete is a `POST` rather than a `DELETE` on purpose: a `DELETE` would have to carry the token in the query string, and a URL travels into access logs, proxies and `Referer` headers. ### Why the routes are not RESTful verb pairs Two reasons, and **both are now history** — worth knowing because the names cannot change now: 1. A query's identity used to derive from its **name alone**, so `GET chat/conversations` and `POST chat/conversations` were two defs claiming one guid, which collides at export. The SDK composes it from `(api group, verb, name)` as of **0.0.7** (xanots/sdk#278). 2. `xanots routes --emit` keyed its manifest on the endpoint **name**, so a verb pair was refused there as well — *after* the names had exported, locked and deployed, making the fix a rename plus a lock re-mint. Keyed on `" "` as of **0.0.13** (xanots/sdk#318). This package's peer floor reaches below both, so on an older SDK they still apply. And the names stay as they are regardless: a query's identity includes its name, so renaming one moves its identity and every consumer's `xano.lock` with it. `create` / `send` read as Xano-idiomatic anyway — the same shape as `auth/signup` and `auth/login`. Before reaching for a verb pair in **your** endpoints, check which SDK version you are on. ## Authenticated *and* anonymous, in one install ```ts registerChatbot(xano, { authTable: userTable, guest: true }); ``` A visitor chats before signing up; after they log in, the client calls `chat/conversations/{id}/claim` with the `session_token` it held, and the thread becomes theirs. Claiming sets `user_id` and thereby **ends the token's authority** — the guest endpoints reject it from then on, so logging in does not leave a second, weaker credential valid against the thread. These are two endpoint families rather than one flexible family because Xano endpoints enforce authentication at the endpoint level (`auth` is binary). In public endpoints, accessing authentication context raises `ACCESS_DENIED` rather than resolving to null. Providing separate authenticated and guest endpoints ensures clear access rules and security boundaries, while both delegate to a single shared reply function. ## The agent `llm` is passed straight through to the SDK's `agent({ llm })`, minus the run prompt. It defaults to `{ type: "xano-free" }` — Xano's keyless provider — so a fresh install answers a message with no credential wiring at all. Swap in a keyed provider whenever you like: ```ts registerChatbot(xano, { authTable: userTable, llm: { type: "anthropic", model: "claude-opus-5", apiKey: "{{ $env.ANTHROPIC_API_KEY }}", // env var, not a literal in the bundle systemPrompt: "You are a support agent for Acme. Never discuss pricing.", }, }); ``` **`llm.prompt` and `llm.messages` are rejected**, at compile time and again at runtime. This package owns the run prompt because that is how the transcript reaches the model, and Xano stores exactly one prompt behind a `prompt_type` discriminator — so a supplied prompt would *replace* the history rather than add to it. Put your instructions in `systemPrompt`. ### How history reaches the model The send endpoint reads the last `historyLimit` turns, projects them to `[{ role, content }]`, JSON-encodes them, and hands the result to the agent's `messages` template. The engine decodes it back into native LLM message roles. Using structured message roles allows the model to process conversation history natively rather than relying on unstructured text interpolation, optimizing token efficiency and preserving role boundaries. To maintain conversation integrity: - `role` is constrained to an enum (`["user", "assistant", "system"]`). - `content` requires a non-empty string (`min: 1`) and is automatically trimmed so blank or invalid turns cannot enter the history. ## Options | Option | Default | Notes | |---|---|---| | `authTable` | — | Required unless `authenticated: false`. A `table()` handle or a table name. | | `userIdType` | `"int"` | The primary-key type of `authTable`. Only needed with a bare name. | | `authenticated` | `true` | Register the token-authenticated family. | | `guest` | `false` | Register the public guest family. | | `llm` | `{ type: "xano-free" }` | Provider settings; `systemPrompt` is the field most installs set. | | `historyLimit` | `20` | **Messages** replayed to the model per send, including the current one. | | `listLimit` | `100` | Conversations returned by the list endpoint. | | `transcriptLimit` | `200` | Messages returned by a transcript endpoint. | | `canonical` | *(unset)* | Pin the API group's URL segment so `getPath()` resolves without a lock. | | `tools` | `[]` | Tools the agent may call. You register them; this package only references them. | | `rateLimit` | `{ max: 20, ttl: 60 }` | Per-caller ceiling on the model-invoking endpoints; `false` disables. | | `history` | `false` | Request-history capture. Off by default — see below. | | `routePrefix` | `"chat"` | Leading segment of every endpoint path. | | `names` | see below | Stored object names: `conversation`, `message`, `agent`, `apiGroup`, `replyFn`. | | `tags` | `["xano:chatbot"]` | Tags applied to every def. | ### Request history is off by default Xano's request history defaults **on** and records the request body. Here that body is the user's message text and — on the guest family — the `session_token` that grants access to the entire thread. A turnkey install should persist neither, so `registerChatbot` sets the group's history to `false` and the endpoints inherit it. Opt back in for local debugging: ```ts registerChatbot(xano, { authTable: userTable, history: true }); // engine default depth registerChatbot(xano, { authTable: userTable, history: 25 }); // capture depth 25 registerChatbot(xano, { authTable: userTable, history: "all" }); // unlimited depth ``` The depth caps how many statement executions one history record's stack trace keeps — it is not a retention limit. ## Identity & the lock This package pins **no** guids, and no canonical unless you ask for one. - **With `xano.lock` (recommended):** your first locked export mints and freezes a guid for every object and a canonical for the API group, then reuses them on every later export. Repeated imports are idempotent and your API URL is stable. Commit `xano.lock`. - **Without a lock:** each guid derives from its name (`md5(":")`; a query's from its api group, verb and name) and the engine assigns a random canonical at import. Fine for a one-shot import. Pin the canonical instead if you want a browser to resolve `getPath()` with no lock file: ```ts export const bot = registerChatbot(xano, { authTable: userTable, canonical: "chat" }); export default bot.xano; // → sendMessage.getPath({ params: { conversation_id: 42 } }) // "/api:chat/chat/conversations/42/send" ``` The segment must match `[A-Za-z0-9_-]+` and be unique across the instance's API groups — which this package cannot check, so a collision surfaces at Xano import. ## Calling it from a typed client Every request and response type is exported directly, so a client never re-types a body. They are types, so `import type` erases them — a browser bundle pays nothing: ```ts import type { SendMessageBody, ChatReply } from "@xanots/chatbot"; const body: SendMessageBody = { content: "Hello" }; // no conversation_id — it rides in the path ``` Names follow one rule — ``, where the handle name is the property on `bot.authenticated` / `bot.guest`: | part | is | goes | |---|---|---| | `…Params` | path parameters | interpolated into the URL | | `…Query` | query-string parameters | `?a=b` | | `…Body` | the JSON body | the request body | | `…Input` | all of the above at once (what the SDK derives) | — | | `…Response` | what comes back | — | A part an endpoint does not take is **not exported**, so the existence of a name answers "does this take a body?". Never send `…Input` as the body: it contains the path params, which the endpoint reads off the URL — that is what used to force `Partial<…>` and throw away the check on the fields you do send. ```ts import type { SendMessageParams, SendMessageBody, ChatReply } from "@xanots/chatbot"; async function ask(token: string, conversationId: number, content: string): Promise { const params: SendMessageParams = { conversation_id: conversationId }; const body: SendMessageBody = { content }; const res = await fetch(`${BASE}/api:chat/chat/conversations/${params.conversation_id}/send`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` }, body: JSON.stringify(body), }); return res.json(); } ``` ### `ChatbotEndpoints` — the whole surface as one map Keyed by the same names as the def handles, so `bot.authenticated.sendMessage` and `ChatbotEndpoints["sendMessage"]` describe one thing: ```ts type Send = ChatbotEndpoints["sendMessage"]; // Send["verb"] → "POST" // Send["route"] → "conversations/{conversation_id}/send" (relative to routePrefix) // Send["auth"] → "token" // Send["params"] → { conversation_id: number } // Send["query"] → never // Send["body"] → { content: string } // Send["response"] → ChatReply ``` Keys: `createConversation`, `listConversations`, `listMessages`, `sendMessage`, `deleteConversation`, `claimConversation`, `guestCreateConversation`, `guestListMessages`, `guestSendMessage`, `guestDeleteConversation`. The map also records **where the guest bearer token travels**, which is a security property rather than a style choice: `guestListMessages` is a `GET`, so `session_token` rides in the query string — and therefore into access logs, proxies and `Referer` headers — while `guestDeleteConversation` is a `POST` *specifically* so it rides in the body instead. ### Where the URL comes from Don't hand-type it, and **don't import a def to call `getPath()` in the browser**. A def import is a *runtime* import: the `s.*`/`c.*` factories in its stack execute at module load and cannot be tree-shaken, so reaching for a path costs ~236 kB minified (~62 kB gzipped). Instead generate the routes as plain data — the file imports nothing and a rename becomes a type error rather than a 404: ```bash npx xanots routes ./xano/index.ts --emit xano/routes.gen.ts ``` ```ts import { routePath } from "../xano/routes.gen.js"; routePath("POST chat/conversations/{conversation_id}/send", { conversation_id: 42 }); // → "/api:chat/chat/conversations/42/send" ``` Server-side, where bundle size is irrelevant, the def handle is the direct route: `bot.authenticated.sendMessage.getPath({ params: { conversation_id: 42 } })`. ### Reaching the defs themselves `registerChatbot` returns the def set (the instance is on `.xano`), so export it and a client can `import type` the handle — which erases, unlike a value import: ```ts // xano/index.ts export const bot = registerChatbot(xano, { authTable: userTable, canonical: "chat" }); export default bot.xano; // frontend — costs the bundle nothing import type { bot } from "../xano/index.js"; type Send = typeof bot.authenticated.sendMessage; ``` ### Render the reply as Markdown Any frontend works — the endpoints are ordinary JSON over HTTP. But replies read markedly better rendered as **Markdown** than as plain text, so the default system prompt asks the model for light markdown (emphasis, lists, fenced code) and your UI should render it. Drop it into a text node instead and the reader sees literal `**asterisks**`. ```tsx import Markdown from "react-markdown";
{message.content}
``` Two things to get right: - **Treat the reply as untrusted input.** It is model output shaped by whatever the user typed, so a prompt-injection attempt can try to steer it into `