@cms.ai/brand_brain 0.0.1

package/README.md

@@ -0,0 +1,95 @@
+# @cms.ai/brand_brain
+
+Client-side SDK for building **CMS.ai Brand Brain (Guide)** experiences directly into your own website UI — your own chat, your own layout — instead of the drop-in overlay. It handles the visitor session, streaming chat across every guide skill, conversation history, and lead capture, all against your branded CMS.ai host.
+
+Framework-agnostic core + an optional React binding.
+
+## Install
+
+```bash
+npm install @cms.ai/brand_brain
+```
+
+## Quick start (vanilla JS/TS)
+
+```ts
+import { initGuide } from "@cms.ai/brand_brain";
+
+const guide = await initGuide({
+  baseUrl: "https://guide.yourcompany.com", // your branded CMS.ai host
+  slug: "default", // which guide to load
+});
+
+// Stream a reply into your own UI:
+for await (const event of guide.ask("How does pricing work?")) {
+  if (event.type === "text") {
+    appendToChatBubble(event.delta); // your render fn
+  } else if (event.type === "gate") {
+    // The guide is asking for an email before continuing.
+    await guide.submitGate("visitor@acme.com");
+  }
+}
+```
+
+> **`baseUrl` must be your branded CMS.ai host on your own root domain** (e.g. `guide.yourcompany.com`, the CNAME we provision). That keeps the visitor cookies same-site, so identity + analytics work in every browser without any third-party-cookie caveats.
+
+## Quick start (React)
+
+```tsx
+import { useGuide } from "@cms.ai/brand_brain/react";
+
+function Chat() {
+  const { messages, ask, isStreaming, isReady } = useGuide({
+    baseUrl: "https://guide.yourcompany.com",
+    slug: "default",
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <p key={m.id} data-role={m.role}>
+          {m.content}
+        </p>
+      ))}
+      <button disabled={!isReady || isStreaming} onClick={() => ask("What can you help me with?")}>
+        Ask
+      </button>
+    </div>
+  );
+}
+```
+
+## The `ask()` event stream
+
+`ask()` returns an async iterator of `GuideStreamEvent`s. The common case is `text`; `skill` carries every structured deliverable (documents, recommendations, how-to steps, diagnose questions, business cases, solution designs, …), discriminated by its `name`.
+
+| `event.type`                             | Meaning                                                                        |
+| ---------------------------------------- | ------------------------------------------------------------------------------ |
+| `run-started` / `run-finished`           | Turn lifecycle                                                                 |
+| `message-start` / `text` / `message-end` | The streamed chat reply (`text.delta` is the token chunk)                      |
+| `skill`                                  | A structured skill payload — `{ name, value }`, where `name` is a `GuideEvent` |
+| `gate`                                   | The guide needs an email before continuing — call `guide.submitGate(email)`    |
+| `error`                                  | A run or skill error — `{ message, code? }`                                    |
+
+Skill routing is automatic (the server picks the skill from the message). Force one with `guide.ask(text, { forcedSkill: SkillResponseType.HowTo })`.
+
+## API
+
+`initGuide(config)` → `GuideClient`. Config: `baseUrl`, `slug`, optional `domain` (defaults to `window.location.hostname`), `consent` (`"auto"` | `{ functional?, analytical? }` | `false`), `trackLoad` (default `true`), `fetch`.
+
+`GuideClient`:
+
+- `guide` — resolved metadata (`id`, `accountId`, `theme`, `customization`, …)
+- `ask(message, { forcedSkill?, signal? })` — stream a reply (see above)
+- `messages` / `reset()` — in-memory conversation history
+- `setConsent({ functional?, analytical? })` / `getStatus()`
+- `submitGate(email, options?)` — capture a lead (magic link when verification is required)
+- `track(eventType, properties?)` / `trackPageView(url?)` — analytics (call `trackPageView` on SPA route changes)
+- `endSession()` — end the visit (call on `pagehide`)
+- `conversations` — `getOrCreate()`, `list()`, `get(id, { cursor?, limit? })`, `delete(id)`
+- `skills` — `listHistory()`, `get(id)`, `update(id, data)`, `selectDraft(id)`, `markShared(id)`, `importShared(id)`
+
+## Notes
+
+- The SDK calls the existing public CMS.ai API — it introduces no new endpoints.
+- `@navless/*` internals are bundled in; the published package has no `@navless/*` runtime dependencies. `react` / `react-dom` are optional peers used only by `@cms.ai/brand_brain/react`.