@bootstrapware/answers
v0.2.16
Published
Embeddable source-backed Q&A for your site: React widget plus a server engine (crawl, hybrid search, grounded OpenAI answers with citations) for BYO backends.
Maintainers
Readme
@bootstrapware/answers
Visitors ask a question. The widget shows a cited answer, or an explicit fallback when nothing matches.
Local mode is free. BYO is $9.99 / month (you store knowledge and answers). Hosted is $19.99 / month. Hosted stores approved sources, the derived index, visitor questions, optional conversations, unanswered items, and citations. Hosted includes 2,500 answers per workspace each month, 1 GiB of knowledge and index, 2,000 sources, 4,000 indexed chunks per app, 20 MiB per file, and 30 days of conversation history. Test keys are free. Pass appId and publishableKey and the widget calls Hosted ask. Pass createLocalAdapter() for the sample, or your own adapter for BYO.
pnpm add @bootstrapware/answersNon-React pages can use the Hosted script embed instead (see Script below).
Peer dependencies: react and react-dom (>= 18).
Local
import { Answers, createLocalAdapter } from "@bootstrapware/answers";
import "@bootstrapware/answers/styles.css";
<Answers adapter={createLocalAdapter()} />The default presentation is a closed corner launcher. presentation can be launcher, section, modal, or window. Modal, window, and launcher start closed unless defaultOpen.
The local adapter is a deterministic sample for Northwind Outfitters (hours, returns, shipping). It does not call the network.
Script
pnpm build writes dist/answers.iife.js. A non-React page can mount the same component:
<div id="answers"></div>
<script src="./dist/answers.iife.js"></script>
<script>
BootstrapwareAnswers.mount(document.getElementById("answers"), {});
</script>The hosted script is GET https://answers.bootstrapware.co/embed/v1.js. Pass appId and publishableKey and it calls Hosted ask. suggestedQuestions renders starter chips. shortcut="mod+k" opens the widget and focuses the question (Command on macOS, Control elsewhere).
<script>
BootstrapwareAnswers.mount(document.getElementById("answers"), {
appId: "ana_…",
publishableKey: publishableKey,
suggestedQuestions: ["What is your return window?"],
shortcut: "mod+k",
});
</script>Hosted
import { Answers } from "@bootstrapware/answers";
import "@bootstrapware/answers/styles.css";
<Answers
appId="ana_…"
publishableKey={process.env.NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY}
suggestedQuestions={["What is your return window?"]}
shortcut="mod+k"
/>That posts to POST https://answers.bootstrapware.co/api/v1/ask?appId=. createHostedAdapter({ appId, publishableKey, apiBaseUrl }) is the same client when you want to pass adapter yourself. Optional apiBaseUrl defaults to https://answers.bootstrapware.co.
BYO
Run the engine on your server with your OpenAI key. Questions, knowledge, and the key stay on your infrastructure.
// app/api/answers/route.ts (Next.js) — any runtime with fetch works
import { createAnswersBackend } from "@bootstrapware/answers/server";
const answers = createAnswersBackend({
siteName: "Acme",
openaiApiKey: process.env.OPENAI_API_KEY, // server env only
sitemap: "https://acme.com/sitemap.xml", // or urls: [...], or documents: [{ id, title, url, text }]
qa: [{ question: "Do you offer refunds?", answer: "Yes, within 14 days of purchase." }],
});
export const POST = (request: Request) => answers.handler(request);The index is built on the first question and kept in memory. Call answers.refresh() after your content changes (it returns { pages, chunks, skipped }; skipped lists every page left out and why, including a URL that redirects to a different page, and onRefresh receives the same report after the automatic first build), or save answers.index.toJSON() and pass it back as snapshot to skip re-embedding on restart. Pass retrieve to use your own vector store instead.
Answers come only from the indexed passages. refresh() also fetches /llms.txt and /llms-full.txt for each origin in urls or the sitemap when the host publishes them as text or Markdown, and ignores a missing file. A draft that cites something it did not retrieve, or states a price or number that is not in a cited passage and does not follow from cited figures (a single-step percent-off or percent-of of a cited amount, rounded to the nearest cent, or a sequential stack total with each line rounded to the nearest cent), is rejected and the visitor gets the fallback. The same number with a comma, dot, space, or apostrophe as the thousands separator counts as the figure in the source, and a comma decimal such as 19,99 counts as $19.99. A stack total that depends on billing order is rejected unless the visitor set the order, or the answer says order matters and gives the catalog-order total, every order total, or the min-to-max range. A partial set is rejected. The itemized sum is checked even when the answer caveats order, and separate order alternatives are not added into one sum. A stated range must run from the lowest to the highest order total, and "if this product is first, $T" must be the total with that product first and the others in catalog order. Equal list prices are one total, for Hosted and for BYO. A discounted total described as a list price is rejected, and so is a claim that the discount waits for more products when two or more paid products are already named. A question about limiting the index to some pages still retrieves the passage that explains how to scope sources. A reply in a different language than the question is retried once. Custom Q&A is always considered, and a matching entry is answered first. When the sources are silent on a yes/no question, the answer says the site does not state it (with the support contact if a source has one). How-to questions cite the docs page; no new code is written.
Custom Q&A can change at runtime without a refresh: call await answers.upsertQa({ id, question, answer }), answers.removeQa(id), or answers.setQa([...]) from your save handler. Only the changed entry is embedded and it answers on the next question. Relevant custom Q&A are always offered to the model, even when many page passages outrank them, and that includes setups that pass their own retrieve.
Then point the widget at that route:
<Answers
appId="ana_..."
adapter={createByoAdapter({
ask: async ({ sessionId, question, pageContext }) => {
const response = await fetch("/api/answers", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ sessionId, question, pageContext }),
});
return response.json();
},
})}
/>Question text stays on your backend. pageContext is the page URL and title only.
