@bootstrapware/answers 0.1.0

package/AGENTS.md

@@ -0,0 +1,245 @@
+# Integrating @bootstrapware/answers
+
+Use this file as agent instructions. The React widget and the Hosted Answers service are separate. This file is the install contract: config, keys, MCP, the widget, the script embed, and the Hosted ask route that already exists.
+
+## What this package does
+
+Visitors ask a question about the page. The widget shows one complete answer with citations, or an explicit fallback when the result is `unanswered`.
+
+**Free:** local sample and test keys. No card. Pass `createLocalAdapter()`, or omit `adapter` when you also omit `publishableKey`. The sample answers hours, returns, and shipping for Northwind Outfitters. It does not call the network.
+
+**BYO ($9.99):** live app config. Knowledge, retrieval, the model, and visitor logs stay on the customer backend. Pass an `AnswersAdapter`, or `createByoAdapter(impl)`.
+
+**Hosted ($19.99):** live app config, and 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. Hitting a ceiling stops that axis.
+
+Stack discount is company-wide: 25% off the second paid product's list, 35% off the third and later. Env names only: `STRIPE_PRICE_ANSWERS_BYO` and `STRIPE_PRICE_ANSWERS_HOSTED`. Do not invent Stripe price ids.
+
+`@bootstrapware/answers` is published to npm: `pnpm add @bootstrapware/answers`. Non-React pages can still use the Hosted script embed. The Cursor Marketplace listing is separate and is not implied by this file. Do not invent a version or a tarball. The imports in this file are the package contract.
+
+Publishable env: `NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY`.
+
+The React package does not call Hosted ask by itself. Passing `publishableKey` without `adapter` shows "This page is not ready to answer yet." and does not fetch.
+
+## Install algorithm (do this in order)
+
+1. Read this file. Call `list_answers_capabilities` on Answers MCP before inventing tools.
+2. If the user only needs a working UI in this app: Path A. Do not invent keys.
+3. If they need live Hosted ask: Path B.
+4. If they need their own backend: Path C.
+5. Never mint live or secret API keys via MCP or in the browser. For a test publishable key, call `ensure_answers_test_publishable`.
+
+### Path A: local, zero keys
+
+```tsx
+import { Answers, createLocalAdapter } from "@bootstrapware/answers";
+import "@bootstrapware/answers/styles.css";
+
+<Answers adapter={createLocalAdapter()} />
+```
+
+Try these questions, in order, on one session:
+
+1. `What is your return window?` Answered. Citation id `ane_returns`.
+2. `How long do I have?` Follow-up on that same session. A new session returns unanswered.
+3. `What are your hours?` Answered. Citation id `ane_hours`.
+4. `Is shipping free?` Answered. Citation id `ane_shipping`.
+5. `Do you price match?` Unanswered, with the sample fallback.
+
+`onFallback` runs for unanswered results. The widget does not render an answer body for that outcome.
+
+### Path B: Hosted
+
+1. Confirm Cursor MCP `bootstrapware-answers` at `https://answers.bootstrapware.co/mcp` (OAuth URL-only). If disconnected, tell the human to click **Add to Cursor (OAuth)** on https://app.bootstrapware.co/answers/keys
+2. `list_answers_capabilities` → `create_answers_app` → `update_answers_draft` (toggles + `allowedOrigins` for localhost and production; `name` is optional) → `publish_answers_app`
+3. `ensure_answers_test_publishable`. Put `envLine` in `.env.local`. The full test publishable is returned every time. The env name is `NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY`.
+4. `get_answers_install_snippet`. `appId` is real. Use `process.env.NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY`. Never invent a key and never put a secret in the snippet.
+5. Keep the adapter in the snippet. It posts to `POST /api/v1/ask?appId=`. Omitting `adapter` does not call that route.
+6. `add_answers_url_source` for each dedicated public page whose body already states the fact (`/pricing`, hours, returns). Do not stop at the homepage.
+7. After the index job succeeds, tell the human to retest in the dashboard playground: a product question, a follow-up that names no product, and a question the pages do not answer.
+
+`create_answers_app` returns these `nextSteps`, in order:
+
+1. Call `update_answers_draft` with `allowedOrigins` for localhost and production. Name is optional.
+2. Call `publish_answers_app`.
+3. Call `ensure_answers_test_publishable` to get or create a test publishable key.
+4. Call `get_answers_install_snippet`. The React package does not call Hosted ask unless you pass an adapter.
+5. Call `add_answers_url_source` with a dedicated public page whose body already states the fact. A homepage of product blurbs is a weak first source.
+6. After the index job succeeds, retest in the dashboard playground: a product question, a follow-up that names no product, and a question the pages do not answer.
+
+`publish_answers_app` returns:
+
+1. Call `ensure_answers_test_publishable` to get or create a test publishable key.
+2. Call `get_answers_install_snippet` and point the adapter at `POST /api/v1/ask`.
+3. Call `add_answers_url_source` with a dedicated public page whose body already states the fact. A homepage of product blurbs is a weak first source.
+4. After the index job succeeds, retest in the dashboard playground: a product question, a follow-up that names no product, and a question the pages do not answer.
+
+```tsx
+import { Answers, createByoAdapter } from "@bootstrapware/answers";
+import "@bootstrapware/answers/styles.css";
+
+<Answers
+  appId="ana_demo"
+  publishableKey={process.env.NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY}
+  adapter={createByoAdapter({
+    ask: async (input) => {
+      const response = await fetch("https://answers.bootstrapware.co/api/v1/ask?appId=ana_demo", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${process.env.NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(input),
+      });
+      const json = await response.json();
+      if (!response.ok) throw new Error(json?.error?.message ?? "Could not ask.");
+      return json.data;
+    },
+  })}
+/>
+```
+
+`get_answers_install_snippet` substitutes the published `ana_` id. Optional API host in the snippet defaults to `https://answers.bootstrapware.co`.
+
+The ask body is `{ sessionId, question, pageContext }`. `pageContext` is `{ url, title }` only. The widget does not send the DOM. Success is `{ data }` with `outcome` `answered` or `unanswered`. An answered result includes `answer` and citations whose ids came from retrieval. An unanswered result includes `fallback` and no answer text. There is no public confidence percentage. The response is complete. It does not stream.
+
+Live publishable config and live Hosted writes need a paid plan. Test keys work unpaid. Live Hosted writes need Hosted ($19.99). Live config needs BYO ($9.99) or Hosted ($19.99).
+
+Public URL sources are `add_answers_url_source` with `kind` `website`, `sitemap`, or `url`. `reindex_answers_app` takes that same URL, or omits `url` to reindex the app. Neither tool accepts file bytes or a question.
+
+### Path C: BYO
+
+Same MCP app config as Path B. Implement `AnswersAdapter` on the customer backend. `createByoAdapter(impl)` returns that adapter. Knowledge, retrieval, the model, and visitor logs never go to Bootstrapware.
+
+`ask` receives `{ sessionId, question, pageContext }` and returns `{ sessionId, answerId, outcome, answer?, citations?, fallback? }`. `outcome` is `answered` or `unanswered`. Optional `feedback({ sessionId, answerId, helpful })`.
+
+```tsx
+<Answers
+  appId="ana_demo"
+  adapter={createByoAdapter({
+    ask: async (input) => {
+      const response = await fetch("/api/answers/ask", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      });
+      if (!response.ok) throw new Error("Could not ask.");
+      return response.json();
+    },
+  })}
+/>
+```
+
+The reference backend is `examples/answers-nextjs`. It reads markdown knowledge on the server, ranks chunks, and grounds the answer on retrieved ids. `OPENAI_API_KEY` stays in server env. Without that key, the route quotes a retrieved sentence and does not call a model.
+
+Citations must be ids you retrieved. The widget links a URL only when that URL is on the returned citation. Other URLs stay text. HTML in the answer stays text.
+
+## Hosted MCP (Cursor)
+
+HTTP MCP endpoint: `https://answers.bootstrapware.co/mcp`
+
+**Preferred:** OAuth Connect, URL-only. Scope `answers:mcp`. **Add to Cursor (OAuth)** on https://app.bootstrapware.co/answers/keys
+
+**Fallback:** test secret as `Authorization: Bearer`. Live and secret keys stay on the dashboard. Cursor connects through the Answers MCP endpoint. A Cursor marketplace listing is optional and may not be listed yet.
+
+Tools:
+
+- `list_answers_apps`
+- `get_answers_app`
+- `create_answers_app`
+- `update_answers_draft` (does not publish; `name` optional)
+- `publish_answers_app`
+- `get_answers_published_config`
+- `get_answers_install_snippet`
+- `ensure_answers_test_publishable`
+- `list_answers_capabilities`
+- `add_answers_url_source` (public `http` or `https` URL only)
+- `reindex_answers_app` (that URL, or the app when `url` is omitted)
+
+**Dashboard-only (do not invent MCP tools):** live and secret key mint, webhooks, app delete, billing, file upload, manual sources, conversations, unanswered text, provider secrets, export, purge. Call `list_answers_capabilities`.
+
+Publishing stores hosted app config. There is no `GET /api/v1/config/:appId` route. `POST /api/v1/ask` reads the published revision.
+
+## Config
+
+Draft defaults: `assistantLabel` "Ask", `greeting` "Ask a question this site already answers.", `theme` "light", `presentation` "launcher", `fallbackMessage` "We could not find an answer in the published sources.", `allowedOrigins` `["*"]`, `retainHistory` true, `publicAnsweringEnabled` true, `allowCodeExcerpts` false.
+
+`["*"]` is the CORS default for the ask route. It is not content authorization. `update_answers_draft` accepts `assistantLabel`, `greeting`, `theme`, `presentation`, `fallbackMessage`, `allowedOrigins`, `retainHistory`, `publicAnsweringEnabled`, and `allowCodeExcerpts`. It rejects questions, answers, file bytes, and provider keys.
+
+`allowCodeExcerpts` defaults to false. How-to, install, and embed answers stay short sentences with a docs link. Set it true only when the app should quote code from a source.
+
+`publicAnsweringEnabled: false` pauses new asks. Sources and history stay.
+
+## Props
+
+- `appId`: published app id (`ana_`).
+- `publishableKey`: browser publishable key. Unused for fetch unless your adapter uses it.
+- `adapter`: `ask`, and optional `feedback`.
+- `presentation`: `launcher` (default), `section`, `modal`, or `window`.
+- `defaultOpen`: modal, window, and launcher start closed unless this is set.
+- `theme`: `light` or `dark`. Omit it and the shell stays the light cream default: no `data-theme`, and no `prefers-color-scheme`.
+- `pageContext`: `{ url, title }`. Omit it and the widget sends `location.href` and `document.title`.
+- `onFallback`: called with the sanitized unanswered result.
+- `className`: layout only.
+
+Escape closes modal, window, and launcher. The backdrop closes modal and launcher. Nudge the corner with `--bsw-an-frame-launcher-right` and `--bsw-an-frame-launcher-bottom`.
+
+Hosts may set `--bsw-an-bg`, `--bsw-an-panel`, `--bsw-an-fg`, `--bsw-an-muted`, `--bsw-an-line`, `--bsw-an-accent`, `--bsw-an-accent-fg`, and `--bsw-an-radius` on `.bsw-an` (with `theme="dark"`, `.bsw-an[data-theme="dark"]`).
+
+## Session
+
+The widget stores `ans_` plus 24 hex in `sessionStorage` under `bsw_an_session:<appId>` (`local` when `appId` is omitted). It does not write a cookie. The adapter's returned `sessionId` does not replace that value. Citation sources start collapsed. The visitor opens the source count to read titles and excerpts.
+
+Questions are limited to 1,000 Unicode code points. A longer draft stays in the composer and is not sent.
+
+## Script mount
+
+`GET https://answers.bootstrapware.co/embed/v1.js` serves the versioned IIFE. A local build writes `dist/answers.iife.js` (gitignored).
+
+```html
+<div id="answers"></div>
+<script src="https://answers.bootstrapware.co/embed/v1.js"></script>
+<script>
+  BootstrapwareAnswers.mount(document.getElementById("answers"), { presentation: "launcher" });
+</script>
+```
+
+`mount` returns an unmount function. Calling `mount` again on the same element updates props. `BootstrapwareAnswers.unmount(el)` removes it. The script is the same widget. Without an adapter, it does not call Hosted ask. Pass an adapter function from the page script when you want Path B or Path C.
+
+## Publish pages that can be quoted
+
+Hosted quotes the body after it drops navigation chrome. It does not invent a fact that is only implied by a homepage card. `list_answers_capabilities` returns `sourceAdvice` with the same rules.
+
+1. Add a dedicated public URL per fact you want quoted (`/pricing`, hours, returns), not only the site root.
+2. Put the product name and the price in the same sentence. Example: `Answers Hosted is $19.99 per workspace each month.`
+3. Put each product's comparison on that product's page. Do not leave Chat vs Comments only on the homepage.
+4. After `add_answers_url_source`, wait for the index job, then retest in the dashboard playground: a product question, a follow-up that names no product (`What about BYO?`), and a question the pages do not answer.
+5. A citation excerpt that starts with `Skip to content` means the page had no usable body. Add a better URL, or reindex after the body is public.
+6. Unanswered is the correct outcome when the pages do not have the fact. Add a URL or a dashboard manual FAQ. Do not send the question through MCP.
+
+## Knowledge, grounding, and provider
+
+Hosted knowledge kinds are website root, sitemap, single public URL, PDF, DOCX, TXT, Markdown, and manual FAQ. MCP can add a public URL and reindex it. Files, manual text, conversations, and unanswered question text stay on the dashboard.
+
+Every Hosted source is visitor-readable. Do not upload private runbooks or secrets. Crawl is public `http` and `https` only. Private hosts are rejected. `robots.txt` is honored. A failed crawl leaves the last good index in place. A page that is only navigation chrome is rejected and does not become a citation.
+
+Citations are ids from the retrieved revision. The model does not invent URLs. Unsupported and plausible-false questions return `unanswered` and the configured fallback. There is no model-memory fallback.
+
+Unanswered observations store normalized question text even when conversation history is off, so the dashboard can group them. MCP does not return that text.
+
+Hosted AI is managed OpenAI, or one Hosted BYOK OpenAI key. The secret route is `GET`, `PUT`, and `DELETE /api/v1/apps/:id/provider` with a secret key. `PUT` accepts only `{ "apiKey" }` and returns the key once. Later reads return a hint. MCP, the browser package, logs, and publishable config do not receive the key. Anthropic and Gemini are not in this version.
+
+## Pricing and retention
+
+- Free: local mode and test keys
+- BYO $9.99: live config; you store knowledge and visitor logs
+- Hosted $19.99: Hosted stores approved sources, the derived index, visitor questions, optional conversations, unanswered items, and citations
+- Cancel Hosted: writes freeze immediately. Dashboard JSON export for 30 days, then Hosted sources, index, conversations, and unanswered items are deleted
+- Hosted to BYO keeps the rows and does not start the 30-day clock
+
+## Security
+
+- Do not put `bsw_live_sec_` or `bsw_test_sec_` in client code, `NEXT_PUBLIC_*`, logs, or snippets.
+- Do not send visitor questions, file bytes, or provider keys to MCP or webhooks.
+- Publishable keys and `allowedOrigins` identify the workspace and apply CORS. They do not stop a script that replays the publishable key. Hosted ask still checks the key, the body size, the burst limits, and the monthly allowance before retrieval or a model call.
+- Visitor question text and indexed documents are untrusted. Render the safe markdown subset only.
+- Local and BYO question text stays in the browser or on the customer backend.

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+- `<Answers>` with `appId`, `publishableKey`, `adapter`, `presentation`, `defaultOpen`, `theme`, `pageContext`, and `onFallback`.
+- Presentations: `launcher` (default), `section`, `modal`, and `window`. Launcher and window use the corner host. Launcher and modal dim the page. Escape closes modal, window, and launcher.
+- `createLocalAdapter` answers a Northwind Outfitters sample: a supported fact, a follow-up, and an unanswered fallback. No network.
+- `createByoAdapter` returns the caller adapter.
+- Safe answer markdown (bold, italic, code, lists). Citation links only. HTML stays text.
+- Visitor `sessionId` in `sessionStorage` (`ans_` plus 24 hex). No cookie.
+- IIFE entry `window.BootstrapwareAnswers.mount` from `dist/answers.iife.js` after `pnpm build`.
+- Passing a publishable key without an adapter shows a not-ready state and does not fetch. Hosted ask is not in this version.
+- Hosted included amounts are documented: 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.
+- Feedback may include an optional `reason`. Webhook payloads omit that text.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bootstrapware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @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. The React package does not call Hosted ask by itself. Pass `createLocalAdapter()` or your own adapter.
+
+```bash
+pnpm add @bootstrapware/answers
+```
+
+Non-React pages can use the Hosted script embed instead (see Script below).
+
+Peer dependencies: `react` and `react-dom` (>= 18).
+
+## Local
+
+```tsx
+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:
+
+```html
+<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`.
+
+## BYO
+
+```tsx
+<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.