@xano-sdk/chatbot 1.0.0

package/dist/index.js

@@ -0,0 +1,1128 @@
+// src/options.ts
+var DEFAULT_RATE_LIMIT_MAX = 20;
+var DEFAULT_RATE_LIMIT_TTL = 60;
+var DEFAULT_SYSTEM_PROMPT = "You are a helpful, concise assistant. Answer the user's questions directly. If you do not know something, say so rather than guessing. Format replies as light Markdown \u2014 emphasis, bullet lists, and fenced code blocks where they genuinely help. Keep it minimal: no headings or tables in a short answer, and never wrap an ordinary sentence in formatting. Do not emit raw HTML.";
+var TOOLS_SYSTEM_PROMPT = " You have tools available. When a question needs information you do not have, call the appropriate tool rather than guessing or saying you do not know. Use what a tool returns to answer in your own words \u2014 never paste the raw tool response or its wrapper into your reply.";
+var DEFAULT_HISTORY_LIMIT = 20;
+var DEFAULT_LIST_LIMIT = 100;
+var DEFAULT_TRANSCRIPT_LIMIT = 200;
+var DEFAULT_ROUTE_PREFIX = "chat";
+var DEFAULT_NAMES = {
+  conversation: "conversation",
+  message: "conversation_message",
+  replyFn: "chatbot/generate_reply",
+  agent: "chatbot_agent",
+  apiGroup: "Chatbot"
+};
+var CANONICAL_PATTERN = /^[A-Za-z0-9_-]+$/;
+function isToolWrapper(entry) {
+  const ref4 = entry;
+  return ref4.tool !== void 0 || ref4.id !== void 0;
+}
+function applyDefaultToolAuth(tools, authTable) {
+  return tools.map((entry) => {
+    if (typeof entry === "object" && entry !== null && isToolWrapper(entry)) {
+      return "auth" in entry && entry.auth !== void 0 ? entry : { ...entry, auth: authTable };
+    }
+    return { tool: entry, auth: authTable };
+  });
+}
+var isPublicToolEntry = (entry) => typeof entry === "object" && entry !== null && isToolWrapper(entry) && entry.auth === false;
+var show = (v) => typeof v === "number" ? String(v) : JSON.stringify(v);
+function resolveOptions(opts = {}) {
+  const authenticated = opts.authenticated ?? true;
+  const guest = opts.guest ?? false;
+  if (!authenticated && !guest) {
+    throw new Error(
+      "createChatbot: both endpoint families are disabled ({ authenticated: false, guest: false }), which would register tables and an agent with no way to reach them. Enable at least one."
+    );
+  }
+  if (authenticated && opts.authTable === void 0) {
+    if ("authTable" in opts) {
+      throw new Error(
+        "createChatbot: `authTable` was passed but is undefined at the time registerChatbot/createChatbot ran. The table handle you passed has not been initialized yet \u2014 usually a circular import (the file defining the table imports, directly or indirectly, the file calling registerChatbot), or an import of a name the module does not export. Define the table in a module that does not import the chatbot wiring, or pass its name as a string."
+      );
+    }
+    throw new Error(
+      "createChatbot: `authTable` is required when the authenticated endpoint family is enabled. Pass the table conversations belong to \u2014 a table() handle (preferred) or its name: `registerChatbot(xano, { authTable: userTable })`. For an anonymous-only bot pass { authenticated: false, guest: true } instead, which needs no auth table."
+    );
+  }
+  const userIdType = opts.userIdType ?? "int";
+  if (userIdType !== "int" && userIdType !== "uuid") {
+    throw new Error(
+      `createChatbot: userIdType ${show(userIdType)} is not valid \u2014 pass "int" (the default) or "uuid". It must match the primary-key type of \`authTable\`; Xano allows no other primary-key type.`
+    );
+  }
+  const limits = {
+    historyLimit: {
+      value: opts.historyLimit ?? DEFAULT_HISTORY_LIMIT,
+      note: "It caps how many prior messages are replayed into the model on each send."
+    },
+    listLimit: {
+      value: opts.listLimit ?? DEFAULT_LIST_LIMIT,
+      note: "It caps how many conversations the list endpoint returns."
+    },
+    transcriptLimit: {
+      value: opts.transcriptLimit ?? DEFAULT_TRANSCRIPT_LIMIT,
+      note: "It caps how many messages a transcript endpoint returns."
+    }
+  };
+  for (const [name, { value, note }] of Object.entries(limits)) {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error(
+        `createChatbot: ${name} ${show(value)} is not valid \u2014 pass a positive integer. ${note}`
+      );
+    }
+  }
+  let rateLimit = false;
+  if (opts.rateLimit !== false) {
+    const rl = opts.rateLimit ?? {};
+    if (typeof rl !== "object" || rl === null) {
+      throw new Error(
+        `createChatbot: rateLimit ${show(rl)} is not valid \u2014 pass an object ({ max?, ttl?, error? }) or \`false\` to disable it.`
+      );
+    }
+    const max = rl.max ?? DEFAULT_RATE_LIMIT_MAX;
+    const ttl = rl.ttl ?? DEFAULT_RATE_LIMIT_TTL;
+    for (const [name, value] of Object.entries({ max, ttl })) {
+      if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(
+          `createChatbot: rateLimit.${name} ${show(value)} is not valid \u2014 pass a positive integer. It bounds the model-invoking endpoints per caller; pass \`rateLimit: false\` to remove the limit.`
+        );
+      }
+    }
+    if (rl.error !== void 0 && (typeof rl.error !== "string" || rl.error.length === 0)) {
+      throw new Error(
+        `createChatbot: rateLimit.error ${show(rl.error)} is not valid \u2014 pass a non-empty string.`
+      );
+    }
+    rateLimit = { max, ttl, error: rl.error ?? "Too many messages. Please wait a moment and try again." };
+  }
+  const authoredTools = opts.tools ?? [];
+  if (!Array.isArray(authoredTools)) {
+    throw new Error(
+      `createChatbot: tools ${show(opts.tools)} is not valid \u2014 pass an array of tool() handles, tool names, or { tool, enabled?, auth? } entries.`
+    );
+  }
+  for (const [i, entry] of authoredTools.entries()) {
+    const ok = typeof entry === "string" && entry.length > 0 || typeof entry === "object" && entry !== null;
+    if (!ok) {
+      throw new Error(
+        `createChatbot: tools[${i}] ${show(entry)} is not valid \u2014 pass a tool() handle, a non-empty tool name, or a { tool, enabled?, auth? } entry.`
+      );
+    }
+  }
+  const scopedAgainst = authenticated ? opts.authTable : void 0;
+  const tools = scopedAgainst !== void 0 ? applyDefaultToolAuth(authoredTools, scopedAgainst) : authoredTools;
+  if (scopedAgainst !== void 0 && guest && tools.some((entry) => !isPublicToolEntry(entry))) {
+    console.warn(
+      "xanosdk: chatbot \u2014 both endpoint families are enabled and the agent's tools are scoped to the auth table, so a tool binds the caller on the authenticated endpoints and has no identity to bind on the PUBLIC guest ones. One agent serves both families and an entry carries one `auth`, so this cannot be resolved for you. Give a tool the model may call for a guest `{ tool, auth: false }` and keep `auth()` out of it, or register the guest bot as its own chatbot (own `routePrefix` and `names`) with its own tools."
+    );
+  }
+  if (opts.canonical !== void 0) {
+    if (typeof opts.canonical !== "string" || !CANONICAL_PATTERN.test(opts.canonical)) {
+      throw new Error(
+        `createChatbot: canonical ${show(opts.canonical)} is not a valid URL segment \u2014 it must be a non-empty string matching [A-Za-z0-9_-]+ (the alphabet Xano mints). It becomes the "<canonical>" in /api:<canonical>/chat/conversations.`
+      );
+    }
+  }
+  const routePrefix = opts.routePrefix ?? DEFAULT_ROUTE_PREFIX;
+  if (typeof routePrefix !== "string" || !/^[A-Za-z0-9_\-/]+$/.test(routePrefix) || routePrefix.startsWith("/") || routePrefix.endsWith("/")) {
+    throw new Error(
+      `createChatbot: routePrefix ${show(routePrefix)} is not valid \u2014 pass a non-empty path segment matching [A-Za-z0-9_-/]+ with no leading or trailing slash (e.g. "chat" or "support/chat"). It becomes the leading segment of every endpoint, as in <prefix>/conversations/{id}/send. A \`{param}\` marker is rejected: a prefix is not a place for a path param.`
+    );
+  }
+  const history = opts.history ?? false;
+  if (!(typeof history === "boolean" || history === "all" || typeof history === "number" && Number.isInteger(history) && history > 0)) {
+    throw new Error(
+      `createChatbot: history ${show(history)} is not a valid setting \u2014 pass \`false\` (off, the default), \`true\` (on at the engine's default capture depth), a positive integer (capture depth), or "all" (unlimited depth). The depth caps statements captured per record, not retention.`
+    );
+  }
+  const llmIn = opts.llm ?? {};
+  for (const field of ["prompt", "messages"]) {
+    if (field in llmIn && llmIn[field] !== void 0) {
+      throw new Error(
+        `createChatbot: llm.${field} is not configurable \u2014 this package owns the agent's run prompt, because that is how the conversation transcript reaches the model. Xano stores ONE prompt behind a prompt_type discriminator, so a supplied \`${field}\` would replace the transcript rather than add to it. Put your instructions in \`llm.systemPrompt\`, which is passed through.`
+      );
+    }
+  }
+  const basePrompt = llmIn.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+  const systemPrompt = tools.length > 0 ? basePrompt + TOOLS_SYSTEM_PROMPT : basePrompt;
+  const llm = {
+    type: "xano-free",
+    ...llmIn,
+    systemPrompt,
+    // Set last: the transcript delivery mechanism, verified against a live
+    // instance. See `src/agent/chat-agent.ts` for why `messages` and not `prompt`.
+    messages: MESSAGES_TEMPLATE
+  };
+  return {
+    authTable: opts.authTable,
+    userIdType,
+    authenticated,
+    guest,
+    llm,
+    historyLimit: limits.historyLimit.value,
+    listLimit: limits.listLimit.value,
+    rateLimit,
+    tools,
+    transcriptLimit: limits.transcriptLimit.value,
+    canonical: opts.canonical,
+    history,
+    routePrefix,
+    names: { ...DEFAULT_NAMES, ...opts.names },
+    tags: opts.tags ?? ["xano:chatbot"]
+  };
+}
+var MESSAGES_TEMPLATE = "{{ $args.messages }}";
+
+// src/tables/conversation.ts
+import { table, f } from "@xano/sdk";
+function conversationTable(opts) {
+  return table({
+    name: opts.names.conversation,
+    description: "A single chat thread. Owned by a user (authenticated) and/or reachable with a session token (guest).",
+    auth: false,
+    // Pinned rather than inherited: a table with no explicit `useXdo` takes the
+    // CONSUMER workspace's `use_xdo` at export, which would silently change this
+    // table's storage mode — and therefore its emitted bytes — depending on who
+    // installed it. `true` keeps the non-key columns in the internal `xdo` JSON
+    // column (and auto-prepends the engine's `gin(xdo)` index in canonical order).
+    useXdo: true,
+    tags: opts.tags,
+    schema: {
+      // Present only when the authenticated family is on. A guest-only install
+      // has no auth table to point at, and a nullable FK to nothing is worse
+      // than no column: it would still emit an `@` method carrying a guid that
+      // resolves to no registered table, which fails the export.
+      ...opts.authenticated ? {
+        user_id: f.tableRef(opts.authTable, {
+          type: opts.userIdType,
+          // Nullable exactly when guests are also enabled: a guest thread has
+          // no owner until it is claimed. With guests off, every conversation
+          // is created by an authenticated endpoint that always fills this in,
+          // so the tighter column is the honest one.
+          ...opts.guest ? { nullable: true } : {},
+          description: "The user this conversation belongs to. Null until a guest thread is claimed."
+        })
+      } : {},
+      // Present only when guests are enabled. This is a BEARER CAPABILITY: it is
+      // the whole of a guest's authorization, so it is minted by
+      // `security.create_uuid` (not derived from anything guessable) and its
+      // column is `internal` so a stray `db.get` without an explicit `output`
+      // list cannot leak another thread's token into a response.
+      ...opts.guest ? {
+        session_token: f.text({
+          access: "internal",
+          description: "Opaque bearer capability for guest access to this thread. Treat it like a password."
+        })
+      } : {},
+      title: f.text({
+        methods: ["trim"],
+        description: "Human-readable thread title. Seeded from the first user message."
+      }),
+      // Maintained by the reply function so a conversation list can sort by
+      // recency without joining the message table.
+      last_message_at: f.timestamp({
+        nullable: true,
+        description: "When the most recent message was appended. Null until the first send."
+      })
+    },
+    index: [
+      // The authenticated list endpoint's access path: every user's threads,
+      // newest first. Without it that endpoint is a full scan of every
+      // conversation in the workspace.
+      ...opts.authenticated ? [{ type: "btree", fields: [{ name: "user_id", op: "asc" }] }] : [],
+      // Unique, not merely indexed: a guest's entire authorization is "I hold
+      // this token", so two rows sharing one would make a single token address
+      // two threads. Uniqueness is what makes the lookup unambiguous.
+      ...opts.guest ? [{ type: "btree|unique", fields: [{ name: "session_token", op: "asc" }] }] : []
+    ]
+  });
+}
+var PUBLIC_CONVERSATION_FIELDS = [
+  "id",
+  "created_at",
+  "title",
+  "last_message_at"
+];
+
+// src/tables/message.ts
+import { table as table2, f as f2 } from "@xano/sdk";
+var MESSAGE_ROLES = ["user", "assistant", "system"];
+function messageTable(opts, conversation) {
+  return table2({
+    name: opts.names.message,
+    description: "One turn in a conversation. Replayed to the agent as an LLM message.",
+    auth: false,
+    // Pinned for the same reason as `conversation` — see that module.
+    useXdo: true,
+    tags: opts.tags,
+    schema: {
+      conversation_id: f2.tableRef(conversation, {
+        required: true,
+        description: "The thread this message belongs to."
+      }),
+      // An enum, NOT free text. An unrecognized role is a fatal agent error on
+      // the NEXT send, so the database is the right place to make it impossible.
+      role: f2.enum(MESSAGE_ROLES, {
+        required: true,
+        description: "Who produced this turn. The engine rejects any other value when replaying it."
+      }),
+      // `min:1` is the guard against the confabulation described in the header:
+      // an empty turn does not fail loudly, it produces a plausible fabrication.
+      content: f2.text({
+        required: true,
+        methods: ["min:1"],
+        description: "The message text. Must be non-empty \u2014 a blank turn makes the model confabulate."
+      })
+    },
+    index: [
+      // The access path for both the transcript endpoint and the reply
+      // function's history window: one thread's turns in order. A composite with
+      // `created_at` so the sort is served by the index rather than a filesort.
+      {
+        type: "btree",
+        fields: [
+          { name: "conversation_id", op: "asc" },
+          { name: "created_at", op: "asc" }
+        ]
+      }
+    ]
+  });
+}
+var PUBLIC_MESSAGE_FIELDS = [
+  "id",
+  "created_at",
+  "conversation_id",
+  "role",
+  "content"
+];
+
+// src/agent/chat-agent.ts
+import { agent } from "@xano/sdk";
+function chatAgent(opts) {
+  return agent({
+    name: opts.names.agent,
+    description: "Conversational assistant. Receives the thread's recent turns as decoded LLM messages and returns the next one.",
+    tags: opts.tags,
+    tools: opts.tools,
+    llm: opts.llm
+  });
+}
+
+// src/functions/generate-reply.ts
+import { defineFunction, input, s, c, inp, ref, expr, obj, col, withFilters, fl } from "@xano/sdk";
+var TITLE_LENGTH = 60;
+function generateReplyFn(opts, conversation, message, chatAgent2) {
+  return defineFunction({
+    name: opts.names.replyFn,
+    description: "Appends a user message, runs the chat agent over recent history, appends the reply, and returns it. Performs no authorization.",
+    tags: opts.tags,
+    input: {
+      conversation_id: input.int({
+        required: true,
+        description: "The thread to append to. NOT authorized here \u2014 the caller must have checked ownership."
+      }),
+      content: input.text({
+        required: true,
+        description: "The user's message text. Must be non-empty."
+      })
+    },
+    stack: [
+      // Defence in depth. Every endpoint in this package already rejects a blank
+      // message, so reaching this is a direct-caller mistake — but the failure it
+      // prevents is silent rather than loud, which is what earns it a second
+      // check here. An empty turn does not error at the provider; the model
+      // receives a blank message and fabricates a plausible prior conversation
+      // (verified — see AGENTS.md). A confabulated reply written into the
+      // transcript then poisons every subsequent turn's context.
+      // Compared TRIMMED: the endpoints trim at the input, but a direct
+      // `s.function.run` caller supplies `content` straight into this function
+      // and no input method runs for them. Comparing the raw value would let
+      // "   " through on that path.
+      s.precondition({
+        expr: expr(withFilters(inp("content"), fl.trim()), "!=", c.text("")),
+        error_type: "badrequest",
+        error: c.text("Message content cannot be empty.")
+      }),
+      // 1. The user's turn. Written first so the history read below includes it —
+      //    see the ordering note in the module header.
+      s.db.add({
+        table: message,
+        as: "user_message",
+        data: [
+          { name: "created_at", value: c.text("now") },
+          { name: "conversation_id", value: inp("conversation_id") },
+          { name: "role", value: c.text("user") },
+          { name: "content", value: inp("content") }
+        ]
+      }),
+      // 2. The context window: the most recent `historyLimit` turns of this
+      //    thread. Sorted DESC and capped in the database so a long conversation
+      //    costs a bounded read — then reversed below, because the model needs
+      //    them oldest-first. `id` breaks a `created_at` tie: two messages written
+      //    in the same second must still order deterministically, or a turn can
+      //    appear to precede the one it answered.
+      s.db.query({
+        table: message,
+        where: expr(col("conversation_id"), "=", inp("conversation_id")),
+        output: ["role", "content"],
+        sort: [
+          { sortBy: "created_at", dir: "desc" },
+          { sortBy: "id", dir: "desc" }
+        ],
+        // `metadata: false` keeps this a bare array rather than the engine's
+        // paging envelope — `fl.reverse` and the map below both want the array.
+        paging: { per_page: opts.historyLimit, metadata: false },
+        as: "recent"
+      }),
+      // 3. Build exactly `[{ role, content }]`, oldest first.
+      //
+      //    The projection is explicit rather than relying on the `output` list
+      //    above. Extra keys are tolerated by the engine (verified), so this is
+      //    not load-bearing today — it is load-bearing the moment someone adds a
+      //    column to the message table, at which point the shape the provider
+      //    sees stops depending on an `output` list edited in a different file.
+      s.array.map({
+        source: withFilters(ref("recent"), fl.reverse()),
+        transform: { role: ref("$this.role"), content: ref("$this.content") },
+        as: "turns"
+      }),
+      // 4. Render to JSON text. `messages` is a Twig-templated STRING, so the
+      //    array has to arrive as its JSON serialization; the engine decodes it
+      //    back into real message roles on the other side (verified — AGENTS.md).
+      s.set_var("messages_json", withFilters(ref("turns"), fl.json_encode())),
+      // 5. Run the agent. `args.messages` is what `{{ $args.messages }}` in the
+      //    agent's `messages` template resolves to.
+      s.ai.agent.run({
+        agent: chatAgent2,
+        args: obj({ messages: ref("messages_json") }),
+        // Attaching tools to the agent is NOT enough — the RUN has to permit
+        // executing them. Without this the model is told the tools exist and can
+        // never call one, so it answers "I don't have access to that" and the
+        // whole feature silently does nothing (observed live before this line
+        // existed). Emitted only when tools are configured, so a tool-less
+        // install's bundle is unchanged.
+        ...opts.tools.length > 0 ? { allowToolExecution: c.bool(true) } : {},
+        as: "run"
+      }),
+      // 5b. The names of the tools this run actually executed — the only
+      //     observable a client has that a tool ran at all. It exists because a
+      //     live debugging session cost three deploy cycles when `tool_calls`
+      //     came back null whether a tool had run, thrown, or never been called
+      //     (see AGENTS.md).
+      //
+      //     ⚠ WHERE the calls live was settled against a live instance, because
+      //     the two obvious answers are both wrong. This package used to read
+      //     `run.tool_calls`, a key the envelope does not carry. Core types the
+      //     envelope with a top-level `toolCalls` — which IS present and is
+      //     always `[]` on a live run, even one whose tool wrote a row. The
+      //     calls are in
+      //     `steps[].content[]`: one entry of `type: "tool-call"` carrying
+      //     `toolName`, followed by a `tool-result` entry carrying the tool's
+      //     whole return value.
+      //
+      //     NAMES only, never the entries. A tool-call carries the arguments the
+      //     model produced and a tool-result carries what the tool returned;
+      //     both can hold data the caller never asked for. The name is the whole
+      //     of what a client needs to know a tool ran.
+      //
+      //     A loop rather than the one-line `fl.map` lambda that also works
+      //     (verified). Core is explicit that a lambda is an escape hatch drawing
+      //     on a workspace-wide worker pool, and every send in every install
+      //     would pay it — for work four ordinary statements express.
+      //
+      //     Emitted only when tools are configured, so a tool-less install's
+      //     bundle is unchanged — the same rule as `allowToolExecution` above.
+      ...opts.tools.length > 0 ? [
+        // `fl.get` with a default rather than `ref(..., { safe: true })`:
+        // the safe form defaults to NULL, and looping over null is not a
+        // shape worth relying on. No steps means no names.
+        s.set_var("run_steps", withFilters(ref("run"), fl.get(c.text("steps"), c.array([])))),
+        s.set_var("tool_call_names", c.array([])),
+        s.foreach({
+          as: "step",
+          list: ref("run_steps"),
+          body: [
+            // `index_by` groups the step's parts by `type` and `get` takes
+            // one group — which is how the tool-CALLS are kept apart from
+            // the tool-RESULTS. Both carry `toolName`, so skipping this
+            // would report every call twice.
+            s.set_var(
+              "step_calls",
+              withFilters(
+                ref("step.content", { safe: true }),
+                fl.safe_array(),
+                fl.index_by(c.text("type")),
+                fl.get(c.text("tool-call"), c.array([]))
+              )
+            ),
+            s.array.map({
+              source: ref("step_calls"),
+              as: "step_names",
+              // The entry's key for the name is not a contract this package
+              // owns, so all three spellings are tried and the first
+              // non-null wins. Safe refs throughout: a missing key must
+              // resolve to null, not take the request down.
+              transform: withFilters(
+                ref("$this.toolName", { safe: true }),
+                fl.first_notnull(ref("$this.tool_name", { safe: true })),
+                fl.first_notnull(ref("$this.name", { safe: true }))
+              )
+            }),
+            // Append, so a tool called twice is reported twice and the order
+            // is the order the model called them in.
+            s.set_var(
+              "tool_call_names",
+              withFilters(ref("tool_call_names"), fl.array_merge(ref("step_names")))
+            )
+          ]
+        })
+      ] : [],
+      // 6. A blank completion would fail the message table's `min:1` check as an
+      //    opaque column-validation error naming a column the caller never sent.
+      //    Report it as what it is instead: the model returned nothing.
+      s.precondition({
+        expr: expr(ref("run.result"), "!=", c.text("")),
+        error_type: "standard",
+        error: c.text("The assistant returned an empty reply. Try again.")
+      }),
+      // 7. The assistant's turn.
+      s.db.add({
+        table: message,
+        as: "assistant_message",
+        data: [
+          { name: "created_at", value: c.text("now") },
+          { name: "conversation_id", value: inp("conversation_id") },
+          { name: "role", value: c.text("assistant") },
+          { name: "content", value: ref("run.result") }
+        ]
+      }),
+      // 8. Touch the thread so a conversation list can sort by recency without
+      //    joining the message table. Read first, because the title is seeded
+      //    from the first message only when it is still blank.
+      s.db.get({
+        table: conversation,
+        fieldName: "id",
+        fieldValue: inp("conversation_id"),
+        output: ["id", "title"],
+        as: "conversation"
+      }),
+      s.conditional({
+        when: expr(ref("conversation.title"), "=", c.text("")),
+        then: [
+          s.db.edit({
+            table: conversation,
+            fieldName: "id",
+            fieldValue: inp("conversation_id"),
+            data: [
+              { name: "last_message_at", value: c.text("now") },
+              // First message wins the title, truncated. `substr` rather than a
+              // model-generated summary on purpose: titling is not worth a second
+              // LLM call on the request path, and a deterministic prefix cannot
+              // fail, cost tokens, or return something unsafe to display.
+              {
+                name: "title",
+                value: withFilters(inp("content"), fl.substr(c.int(0), c.int(TITLE_LENGTH)))
+              }
+            ]
+          })
+        ],
+        else: [
+          s.db.edit({
+            table: conversation,
+            fieldName: "id",
+            fieldValue: inp("conversation_id"),
+            data: [{ name: "last_message_at", value: c.text("now") }]
+          })
+        ]
+      })
+    ],
+    response: {
+      conversation_id: inp("conversation_id"),
+      reply: ref("run.result"),
+      message_id: ref("assistant_message.id"),
+      // Always an ARRAY of tool names, never null — see step 5b. A tool-less
+      // install returns the empty array as a constant: no tool can have run, and
+      // a client's `tool_calls.length` should not have to branch on how the bot
+      // was configured. `filter_null` drops any record whose name could not be
+      // read, so the field never reports a call it cannot name.
+      tool_calls: opts.tools.length > 0 ? withFilters(ref("tool_call_names"), fl.filter_null()) : c.array([])
+    },
+    // Declared for the same reason the send endpoints declare it (see
+    // `api/types.ts`), and load-bearing for the build: a `function.run` of this
+    // def carries `InferResponse` of it, and the derived shape
+    // is too deep for the dts emit of either send endpoint (TS2589).
+    responseShape: {}
+  });
+}
+
+// src/api/group.ts
+import { apiGroup } from "@xano/sdk";
+function chatbotGroup(opts) {
+  return apiGroup({
+    name: opts.names.apiGroup,
+    description: "Conversational AI endpoints: create and list conversations, read a transcript, and send a message to the agent.",
+    tags: opts.tags,
+    // Only set when pinned — leaving it undefined is what defers identity to the
+    // consumer's `xano.lock` (or to a random segment assigned at import).
+    ...opts.canonical !== void 0 ? { canonical: opts.canonical } : {},
+    history: opts.history
+  });
+}
+
+// src/api/authenticated.ts
+import { query, input as input2, s as s2, c as c2, inp as inp2, ref as ref2, expr as expr2, col as col2, auth, withFilters as withFilters2, fl as fl2, statements, setVar } from "@xano/sdk";
+var ownershipGuard = (conversation) => statements(
+  s2.db.get({
+    table: conversation,
+    fieldName: "id",
+    fieldValue: inp2("conversation_id"),
+    output: ["id", "user_id"],
+    as: "conversation"
+  }),
+  s2.precondition({
+    expr: expr2(ref2("conversation.user_id", { safe: true }), "=", auth("id")),
+    error_type: "notfound",
+    error: c2.text("Conversation not found.")
+  })
+);
+function authenticatedQueries(opts, group, conversation, message, replyFn) {
+  const base = { apiGroup: group, auth: opts.authTable, tags: opts.tags };
+  const p = opts.routePrefix;
+  const mintSessionToken = s2.security.create_uuid({ as: "session_token" });
+  const addConversation = (withToken) => s2.db.add({
+    table: conversation,
+    as: "conversation",
+    output: PUBLIC_CONVERSATION_FIELDS,
+    data: [
+      { name: "created_at", value: c2.text("now") },
+      { name: "user_id", value: auth("id") },
+      // Truncated to the same length the reply function's auto-title uses, so
+      // a caller-supplied title and a generated one cannot differ in bound.
+      { name: "title", value: withFilters2(inp2("title"), fl2.substr(c2.int(0), c2.int(TITLE_LENGTH))) },
+      // Never returned: absent from PUBLIC_CONVERSATION_FIELDS, and the column
+      // is `internal`.
+      ...withToken ? [{ name: "session_token", value: ref2("session_token") }] : []
+    ]
+  });
+  const createConversation = query({
+    ...base,
+    name: `${p}/conversations/create`,
+    verb: "POST",
+    description: "Create a new conversation owned by the authenticated user",
+    input: {
+      title: input2.text({
+        methods: ["trim"],
+        description: "Optional thread title. Left blank, the first message's opening words become the title."
+      })
+    },
+    // Two `statements(...)` branches rather than one array with a
+    // `...(opts.guest ? [x] : [])` spread. That spread is not a fixed tuple, so
+    // it widens the stack and resolves this endpoint's `ref("conversation")` —
+    // and therefore its whole response type — to `unknown` in every consumer.
+    // Same trap as a `Statement[]` helper; see `ownershipGuard` above.
+    //
+    // The `data` array below keeps its conditional spread: it is a statement
+    // FIELD, not the stack, so no `as`/`ref()` inference depends on its tuple.
+    stack: opts.guest ? statements(mintSessionToken, addConversation(true)) : statements(addConversation(false)),
+    response: ref2("conversation")
+  });
+  const listConversations = query({
+    ...base,
+    name: `${p}/conversations`,
+    verb: "GET",
+    description: "List the authenticated user's conversations, most recently active first",
+    input: {},
+    stack: [
+      s2.db.query({
+        table: conversation,
+        where: expr2(col2("user_id"), "=", auth("id")),
+        output: PUBLIC_CONVERSATION_FIELDS,
+        // `last_message_at` is null until the first send, so a brand-new empty
+        // thread sorts last under `desc`. `id desc` is the tiebreak that keeps it
+        // visible at a stable position rather than shuffling between requests.
+        sort: [
+          { sortBy: "last_message_at", dir: "desc" },
+          { sortBy: "id", dir: "desc" }
+        ],
+        paging: { per_page: opts.listLimit, metadata: false },
+        as: "conversations"
+      })
+    ],
+    response: ref2("conversations")
+  });
+  const listMessages = query({
+    ...base,
+    name: `${p}/conversations/{conversation_id}/messages`,
+    verb: "GET",
+    description: "Read a conversation's transcript, oldest message first",
+    input: { conversation_id: input2.int({ required: true }) },
+    stack: [
+      ...ownershipGuard(conversation),
+      // Newest-N in the database, then reversed for display — the same shape the
+      // reply function uses, and for the same reason: a capped read. A thread
+      // longer than the cap loses its OLDEST messages from this response, which
+      // is the right end to drop for a chat UI that renders from the bottom.
+      s2.db.query({
+        table: message,
+        where: expr2(col2("conversation_id"), "=", inp2("conversation_id")),
+        output: PUBLIC_MESSAGE_FIELDS,
+        sort: [
+          { sortBy: "created_at", dir: "desc" },
+          { sortBy: "id", dir: "desc" }
+        ],
+        paging: { per_page: opts.transcriptLimit, metadata: false },
+        as: "recent"
+      }),
+      s2.set_var("messages", withFilters2(ref2("recent"), fl2.reverse()))
+    ],
+    response: ref2("messages"),
+    // Declared, not derived — the same exception `sendMessage` makes, for the
+    // same reason. The response is a `set_var` bound to an UNTYPED filter
+    // (`fl.reverse` is `typed: false`, result `<T>[]`), and core's static walk
+    // resolves both a `set_var` output and an untyped filter's result to
+    // `unknown`. Without this the transcript endpoint hands every consumer
+    // `unknown` and the frontend loses the projection entirely.
+    //
+    // The shape is not a guess: `output: PUBLIC_MESSAGE_FIELDS` is what the
+    // db.query above projects, and `PublicMessage` is derived from that same
+    // array — so editing the array still moves this type.
+    responseShape: []
+  });
+  const sendRateLimit = opts.rateLimit ? statements(
+    s2.redis.ratelimit({
+      key: withFilters2(c2.text(`${p}:send:`), fl2.concat(auth("id"))),
+      max: c2.int(opts.rateLimit.max),
+      ttl: c2.int(opts.rateLimit.ttl),
+      error: c2.text(opts.rateLimit.error)
+    })
+  ) : statements();
+  const sendMessage = query({
+    ...base,
+    name: `${p}/conversations/{conversation_id}/send`,
+    verb: "POST",
+    description: "Append a message to the conversation and return the agent's reply",
+    input: {
+      conversation_id: input2.int({ required: true }),
+      // `trim` is load-bearing, not cosmetic. Without it a whitespace-only
+      // message ("   ") passes `required` (length 3) AND passes the reply
+      // function's `content != ""` guard, so a blank turn reaches the model,
+      // which confabulates — verified live: it replied "I can't respond to an
+      // empty message" and BOTH turns were written to the transcript, poisoning
+      // every later turn's context. Trimmed, "   " becomes "" and the engine
+      // refuses it up front as a missing param, like any other empty content.
+      content: input2.text({
+        required: false,
+        methods: ["trim"],
+        description: "The user's message. Must be non-empty after trimming."
+      }),
+      message: input2.text({
+        required: false,
+        methods: ["trim"],
+        description: "Alias for `content`."
+      }),
+      prompt: input2.text({
+        required: false,
+        methods: ["trim"],
+        description: "Alias for `content`."
+      })
+    },
+    stack: [
+      ...sendRateLimit,
+      ...ownershipGuard(conversation),
+      setVar(
+        "resolved_turn_content",
+        withFilters2(inp2("content"), [
+          fl2.first_notempty(inp2("message")),
+          fl2.first_notempty(inp2("prompt"))
+        ])
+      ),
+      s2.precondition({
+        expr: expr2(ref2("resolved_turn_content"), "!=", c2.text("")),
+        error_type: "badrequest",
+        error: c2.text("send: non-empty message content must be provided via `content`, `message`, or `prompt`.")
+      }),
+      // Everything past the guard is shared with the guest family — see
+      // `functions/generate-reply.ts`.
+      s2.function.run({
+        fn: replyFn,
+        as: "reply",
+        input: { conversation_id: inp2("conversation_id"), content: ref2("resolved_turn_content") }
+      })
+    ],
+    response: ref2("reply"),
+    // Declared, not derived: `reply` is the agent run's `.result`, which core
+    // resolves to `unknown` because the agent carries no structured-output
+    // schema. See `api/types.ts`.
+    responseShape: {}
+  });
+  const deleteConversation = query({
+    ...base,
+    name: `${p}/conversations/{conversation_id}`,
+    verb: "DELETE",
+    description: "Delete a conversation and every message in it",
+    input: { conversation_id: input2.int({ required: true }) },
+    stack: [
+      ...ownershipGuard(conversation),
+      // Messages first. The other order would leave orphaned message rows behind
+      // if the second delete failed, and nothing would ever collect them — the FK
+      // is a reference, not a cascade.
+      s2.db.bulk.delete({
+        table: message,
+        where: expr2(col2("conversation_id"), "=", inp2("conversation_id"))
+      }),
+      s2.db.del({ table: conversation, fieldName: "id", fieldValue: inp2("conversation_id") })
+    ],
+    // No body. The thread is gone; there is nothing truthful to return about it.
+    response: c2.null()
+  });
+  const claimConversation = opts.guest ? query({
+    ...base,
+    name: `${p}/conversations/{conversation_id}/claim`,
+    verb: "POST",
+    description: "Attach an unclaimed guest conversation to the authenticated user",
+    input: {
+      conversation_id: input2.int({ required: true }),
+      session_token: input2.text({
+        required: true,
+        description: "The guest session token the thread was created with."
+      })
+    },
+    stack: [
+      s2.db.get({
+        table: conversation,
+        fieldName: "id",
+        fieldValue: inp2("conversation_id"),
+        // `session_token` is an `internal` column, so it must be named
+        // explicitly — an `output` list overrides column visibility. It stays
+        // inside this stack and is never returned.
+        output: ["id", "user_id", "session_token"],
+        as: "conversation"
+      }),
+      // The token must match. Same `notfound` as everywhere else, so a wrong
+      // token cannot be distinguished from a wrong id.
+      s2.precondition({
+        expr: expr2(ref2("conversation.session_token", { safe: true }), "=", inp2("session_token")),
+        error_type: "notfound",
+        error: c2.text("Conversation not found.")
+      }),
+      // And it must be UNCLAIMED. Without this, anyone who ever held the guest
+      // token could re-claim the thread away from its current owner — the
+      // token outlives the guest phase, so this is what ends its authority.
+      s2.precondition({
+        expr: expr2(ref2("conversation.user_id", { safe: true }), "=", c2.null()),
+        error_type: "accessdenied",
+        error: c2.text("This conversation has already been claimed.")
+      }),
+      s2.db.edit({
+        table: conversation,
+        fieldName: "id",
+        fieldValue: inp2("conversation_id"),
+        output: PUBLIC_CONVERSATION_FIELDS,
+        data: [{ name: "user_id", value: auth("id") }],
+        as: "claimed"
+      })
+    ],
+    response: ref2("claimed")
+  }) : void 0;
+  return {
+    createConversation,
+    listConversations,
+    listMessages,
+    sendMessage,
+    deleteConversation,
+    /** `undefined` unless the guest family is also enabled — see above. */
+    claimConversation,
+    /**
+     * Every def above that actually exists, ready to register. Built as one array
+     * literal rather than a `push`, so the element type is the union of the
+     * handles rather than the first one's — each `query()` handle carries its own
+     * literal `name` in its type, so a mutable array would fix that type to
+     * whichever def happened to be first.
+     */
+    all: [
+      createConversation,
+      listConversations,
+      listMessages,
+      sendMessage,
+      deleteConversation,
+      ...claimConversation ? [claimConversation] : []
+    ]
+  };
+}
+
+// src/api/guest.ts
+import { query as query2, input as input3, s as s3, c as c3, inp as inp3, ref as ref3, expr as expr3, col as col3, withFilters as withFilters3, fl as fl3, statements as statements2, sys, setVar as setVar2 } from "@xano/sdk";
+var capabilityGuard = (conversation, authenticated) => {
+  const nonEmptyToken = s3.precondition({
+    expr: expr3(inp3("session_token"), "!=", c3.text("")),
+    error_type: "notfound",
+    error: c3.text("Conversation not found.")
+  });
+  const load = s3.db.get({
+    table: conversation,
+    fieldName: "id",
+    fieldValue: inp3("conversation_id"),
+    // `session_token` is `internal`; an explicit `output` list is what makes it
+    // readable inside the stack. It is never placed in a response.
+    output: authenticated ? ["id", "user_id", "session_token"] : ["id", "session_token"],
+    as: "conversation"
+  });
+  const tokenMatches = s3.precondition({
+    expr: expr3(ref3("conversation.session_token", { safe: true }), "=", inp3("session_token")),
+    error_type: "notfound",
+    error: c3.text("Conversation not found.")
+  });
+  const stillUnclaimed = s3.precondition({
+    expr: expr3(ref3("conversation.user_id", { safe: true }), "=", c3.null()),
+    error_type: "accessdenied",
+    error: c3.text("This conversation now belongs to an account. Sign in to continue it.")
+  });
+  return authenticated ? statements2(nonEmptyToken, load, tokenMatches, stillUnclaimed) : statements2(nonEmptyToken, load, tokenMatches);
+};
+function guestQueries(opts, group, conversation, message, replyFn) {
+  const base = { apiGroup: group, tags: opts.tags };
+  const guard = capabilityGuard(conversation, opts.authenticated);
+  const p = opts.routePrefix;
+  const limit = (scope) => opts.rateLimit ? statements2(
+    s3.redis.ratelimit({
+      key: withFilters3(c3.text(`${p}:guest:${scope}:`), fl3.concat(sys.remoteIp())),
+      max: c3.int(opts.rateLimit.max),
+      ttl: c3.int(opts.rateLimit.ttl),
+      error: c3.text(opts.rateLimit.error)
+    })
+  ) : statements2();
+  const createConversation = query2({
+    ...base,
+    name: `${p}/guest/conversations/create`,
+    verb: "POST",
+    description: "Create an anonymous conversation and return its session token",
+    input: {
+      title: input3.text({
+        methods: ["trim"],
+        description: "Optional thread title. Left blank, the first message's opening words become the title."
+      })
+    },
+    stack: [
+      ...limit("create"),
+      s3.security.create_uuid({ as: "session_token" }),
+      s3.db.add({
+        table: conversation,
+        as: "conversation",
+        output: PUBLIC_CONVERSATION_FIELDS,
+        data: [
+          { name: "created_at", value: c3.text("now") },
+          { name: "session_token", value: ref3("session_token") },
+          { name: "title", value: withFilters3(inp3("title"), fl3.substr(c3.int(0), c3.int(TITLE_LENGTH))) }
+          // `user_id` is deliberately not written. It stays null, which is what
+          // marks the thread claimable.
+        ]
+      })
+    ],
+    // Spread the conversation projection, then add the token beside it. The token
+    // comes from `ref("session_token")` — the minted value — NOT from the written
+    // row, so the `internal` column never has to be read back to serve it.
+    response: {
+      id: ref3("conversation.id"),
+      created_at: ref3("conversation.created_at"),
+      title: ref3("conversation.title"),
+      last_message_at: ref3("conversation.last_message_at"),
+      session_token: ref3("session_token")
+    }
+  });
+  const listMessages = query2({
+    ...base,
+    name: `${p}/guest/conversations/{conversation_id}/messages`,
+    verb: "GET",
+    description: "Read a guest conversation's transcript, oldest message first",
+    input: {
+      conversation_id: input3.int({ required: true }),
+      session_token: input3.text({
+        required: true,
+        description: "The token returned when the conversation was created."
+      })
+    },
+    stack: [
+      ...guard,
+      s3.db.query({
+        table: message,
+        where: expr3(col3("conversation_id"), "=", inp3("conversation_id")),
+        output: PUBLIC_MESSAGE_FIELDS,
+        sort: [
+          { sortBy: "created_at", dir: "desc" },
+          { sortBy: "id", dir: "desc" }
+        ],
+        paging: { per_page: opts.transcriptLimit, metadata: false },
+        as: "recent"
+      }),
+      s3.set_var("messages", withFilters3(ref3("recent"), fl3.reverse()))
+    ],
+    response: ref3("messages"),
+    // Declared, not derived — the same exception `sendMessage` makes, for the
+    // same reason. The response is a `set_var` bound to an UNTYPED filter
+    // (`fl.reverse` is `typed: false`, result `<T>[]`), and core's static walk
+    // resolves both a `set_var` output and an untyped filter's result to
+    // `unknown`. Without this the transcript endpoint hands every consumer
+    // `unknown` and the frontend loses the projection entirely.
+    //
+    // The shape is not a guess: `output: PUBLIC_MESSAGE_FIELDS` is what the
+    // db.query above projects, and `PublicMessage` is derived from that same
+    // array — so editing the array still moves this type.
+    responseShape: []
+  });
+  const sendMessage = query2({
+    ...base,
+    name: `${p}/guest/conversations/{conversation_id}/send`,
+    verb: "POST",
+    description: "Append a message to a guest conversation and return the agent's reply",
+    input: {
+      conversation_id: input3.int({ required: true }),
+      session_token: input3.text({ required: true }),
+      // `trim` is load-bearing, not cosmetic. Without it a whitespace-only
+      // message ("   ") passes `required` (length 3) AND passes the reply
+      // function's `content != ""` guard, so a blank turn reaches the model,
+      // which confabulates — verified live: it replied "I can't respond to an
+      // empty message" and BOTH turns were written to the transcript, poisoning
+      // every later turn's context. Trimmed, "   " becomes "" and the engine
+      // refuses it up front as a missing param, like any other empty content.
+      content: input3.text({
+        required: false,
+        methods: ["trim"],
+        description: "The user's message. Must be non-empty after trimming."
+      }),
+      message: input3.text({
+        required: false,
+        methods: ["trim"],
+        description: "Alias for `content`."
+      }),
+      prompt: input3.text({
+        required: false,
+        methods: ["trim"],
+        description: "Alias for `content`."
+      })
+    },
+    stack: [
+      ...limit("send"),
+      ...guard,
+      setVar2(
+        "resolved_turn_content",
+        withFilters3(inp3("content"), [
+          fl3.first_notempty(inp3("message")),
+          fl3.first_notempty(inp3("prompt"))
+        ])
+      ),
+      s3.precondition({
+        expr: expr3(ref3("resolved_turn_content"), "!=", c3.text("")),
+        error_type: "badrequest",
+        error: c3.text("send: non-empty message content must be provided via `content`, `message`, or `prompt`.")
+      }),
+      s3.function.run({
+        fn: replyFn,
+        as: "reply",
+        input: { conversation_id: inp3("conversation_id"), content: ref3("resolved_turn_content") }
+      })
+    ],
+    response: ref3("reply"),
+    // Declared, not derived: `reply` is the agent run's `.result`, which core
+    // resolves to `unknown` because the agent carries no structured-output
+    // schema. See `api/types.ts`.
+    responseShape: {}
+  });
+  const deleteConversation = query2({
+    ...base,
+    // A POST, not a DELETE. The token is the credential and it would have to
+    // travel as a query string on a DELETE — into access logs, proxies and
+    // `Referer` headers. A body keeps it out of the URL. Deliberate deviation
+    // from the authenticated family, whose DELETE carries no secret in the URL.
+    name: `${p}/guest/conversations/{conversation_id}/delete`,
+    verb: "POST",
+    description: "Delete a guest conversation and every message in it",
+    input: {
+      conversation_id: input3.int({ required: true }),
+      session_token: input3.text({ required: true })
+    },
+    stack: [
+      ...guard,
+      s3.db.bulk.delete({
+        table: message,
+        where: expr3(col3("conversation_id"), "=", inp3("conversation_id"))
+      }),
+      s3.db.del({ table: conversation, fieldName: "id", fieldValue: inp3("conversation_id") })
+    ],
+    response: c3.null()
+  });
+  return {
+    createConversation,
+    listMessages,
+    sendMessage,
+    deleteConversation,
+    all: [createConversation, listMessages, sendMessage, deleteConversation]
+  };
+}
+
+// src/register.ts
+var installed = /* @__PURE__ */ new WeakSet();
+function createChatbot(opts = {}) {
+  const options = resolveOptions(opts);
+  const conversation = conversationTable(options);
+  const message = messageTable(options, conversation);
+  const agent2 = chatAgent(options);
+  const replyFn = generateReplyFn(options, conversation, message, agent2);
+  const group = chatbotGroup(options);
+  const authenticated = options.authenticated ? authenticatedQueries(options, group, conversation, message, replyFn) : void 0;
+  const guest = options.guest ? guestQueries(options, group, conversation, message, replyFn) : void 0;
+  return {
+    options,
+    conversation,
+    message,
+    agent: agent2,
+    replyFn,
+    group,
+    authenticated,
+    guest,
+    queries: [...authenticated?.all ?? [], ...guest?.all ?? []]
+    // The conditional families are decided by `AuthenticatedOf`/`GuestOf` from
+    // the OPTIONS type, while the values above are decided by the RESOLVED
+    // options at runtime. The two agree by construction — `resolveOptions`
+    // applies exactly the defaults those conditionals encode — but the compiler
+    // cannot see that a resolved boolean came from a literal, so the bridge is
+    // asserted once, here, rather than by every caller writing `!`.
+  };
+}
+function registerChatbot(xano, opts = {}) {
+  if (installed.has(xano)) {
+    throw new Error(
+      "registerChatbot: already called on this Xano instance. Register the chatbot set once \u2014 a second registration duplicates every def, which core cannot catch (the two sets are distinct objects sharing names) and which surfaces at export() as \"Duplicate object guid \u2026 shared by \\\"dbo/conversation\\\" and \\\"dbo/conversation\\\"\". To run TWO chatbots in one workspace, give the second one its own `routePrefix` AND `names` \u2014 the prefix is what keeps the ENDPOINT guids apart (a query's identity derives from its route name), and `names` keeps the tables, agent, function and group apart: registerChatbot(xano, { routePrefix: 'support', names: { conversation: 'support_conversation', message: 'support_message', agent: 'support_agent', apiGroup: 'Support', replyFn: 'support/reply' } })."
+    );
+  }
+  const bot = createChatbot(opts);
+  xano.registerTables([bot.conversation, bot.message]).registerAgents([bot.agent]).registerFunctions([bot.replyFn]).registerApiGroups([bot.group]).registerQueries(bot.queries);
+  installed.add(xano);
+  return { ...bot, xano };
+}
+export {
+  DEFAULT_HISTORY_LIMIT,
+  DEFAULT_LIST_LIMIT,
+  DEFAULT_NAMES,
+  DEFAULT_SYSTEM_PROMPT,
+  DEFAULT_TRANSCRIPT_LIMIT,
+  MESSAGES_TEMPLATE,
+  MESSAGE_ROLES,
+  PUBLIC_CONVERSATION_FIELDS,
+  PUBLIC_MESSAGE_FIELDS,
+  TITLE_LENGTH,
+  TOOLS_SYSTEM_PROMPT,
+  authenticatedQueries,
+  chatAgent,
+  chatbotGroup,
+  conversationTable,
+  createChatbot,
+  generateReplyFn,
+  guestQueries,
+  messageTable,
+  registerChatbot,
+  resolveOptions
+};
+//# sourceMappingURL=index.js.map