@sales-bot-llm/sdk 0.2.0

package/docs/superpowers/specs/2026-05-08-sales-bot-sdk-design.md

@@ -0,0 +1,587 @@
+# Sales Bot — Sub-project #2: Frontend SDK Design
+
+**Date:** 2026-05-08
+**Status:** Approved (drives Phase 2-N implementation)
+**Author:** Claude (autonomous build, delegated by Artem Zaitsev)
+**Scope:** Sub-project #2 of 5. Consumes the locked wire format from sub-project #1.
+
+---
+
+## 1. Goals & Non-Goals
+
+### 1.1 Goals
+
+- **Framework-agnostic TypeScript core** — a single `SalesBotClient` class that any framework adapter can wrap.
+- **React adapter** — `useSalesBot` hook, compatible with React 18 + Next.js App Router.
+- **Vue adapter** — `useSalesBot` Composition API composable, Vue 3.4+.
+- **Vanilla / IIFE adapter** — `window.SalesBot.init(...)` for plain `<script>` embed tags.
+- **Floating widget** — a self-contained shadow-DOM chat widget, zero host-page CSS bleed.
+- **Type-safe wire format** — TypeScript types verbatim from the backend's `sse-events.ts`; contract tests assert no drift.
+- **localStorage visitor-token persistence** — keyed per embed-key, with in-memory fallback for SSR/Node.
+- **SSE streaming consumer** — parses `event: <name>\ndata: <json>\n\n` frames from `fetch` responses.
+- **v1 ships ESM + CJS + IIFE bundles** — via `tsup`, all in one package.
+
+### 1.2 Non-Goals (v1)
+
+- Voice channel / WebRTC (sub-project #4)
+- File uploads
+- Multi-bot management UI
+- Server-side rendering of chat history
+- Deep theme customization beyond CSS custom-properties
+- Admin dashboard
+- Publishing to npm (local-only builds)
+
+---
+
+## 2. Repo Layout
+
+Single package (`@sales-bot/sdk`) with multiple entry points. This avoids version skew between adapters and halves dependency management overhead compared to a monorepo.
+
+```
+sales_bot_sdk/
+├── src/
+│   ├── core/
+│   │   ├── types.ts          ← SalesBotEvent union, SalesBotError, wire types
+│   │   ├── sse-parser.ts     ← ReadableStream → AsyncIterable<SalesBotEvent>
+│   │   ├── transport.ts      ← fetch-based HTTP layer
+│   │   ├── storage.ts        ← Storage interface + adapters
+│   │   ├── visitor.ts        ← visitor token management
+│   │   ├── client.ts         ← SalesBotClient class
+│   │   └── index.ts          ← re-exports for ./core entry
+│   ├── react/
+│   │   ├── use-sales-bot.tsx ← useSalesBot hook
+│   │   └── index.ts
+│   ├── vue/
+│   │   ├── use-sales-bot.ts  ← useSalesBot composable
+│   │   └── index.ts
+│   ├── vanilla/
+│   │   ├── index.ts          ← window.SalesBot.init
+│   │   └── iife-wrapper.ts
+│   └── widget/
+│       ├── widget.ts         ← shadow DOM floating widget
+│       ├── styles.ts         ← CSS-in-JS injected into shadow root
+│       └── index.ts
+├── tests/
+│   ├── core/
+│   │   ├── sse-parser.test.ts
+│   │   ├── transport.test.ts
+│   │   ├── storage.test.ts
+│   │   ├── visitor.test.ts
+│   │   └── client.test.ts
+│   ├── react/
+│   │   └── use-sales-bot.test.tsx
+│   ├── vue/
+│   │   └── use-sales-bot.test.ts
+│   ├── widget/
+│   │   └── widget.test.ts
+│   └── contract/
+│       └── wire-format.test.ts   ← asserts SDK types match backend
+├── docs/
+├── tsup.config.ts
+├── tsconfig.json
+├── vitest.config.ts
+├── package.json
+└── biome.json
+```
+
+---
+
+## 3. Public API
+
+### 3.1 Core class
+
+```typescript
+class SalesBotClient {
+  constructor(opts: SalesBotClientOptions)
+
+  // Identify the current visitor. Merged into the next ask() call.
+  identify(traits: IdentifyInput): void
+
+  // Start a new agent turn. Returns an AsyncIterable and also emits events
+  // on the client's event bus.
+  ask(message: string, opts?: AskOptions): AsyncIterable<SalesBotEvent>
+
+  // Re-attach to an in-flight or completed turn by turnId.
+  resume(turnId: string): AsyncIterable<SalesBotEvent>
+
+  // Visitor token — a UUID stable across page reloads.
+  getVisitorToken(): string
+
+  // Active conversation ID (set after turn_started, cleared on reset).
+  getConversationId(): string | null
+  setConversationId(id: string | null): void
+
+  // Event-bus interface (alternative to async iterable).
+  on(event: 'delta', handler: (e: DeltaEvent) => void): Unsubscribe
+  on(event: 'message_complete', handler: (e: MessageCompleteEvent) => void): Unsubscribe
+  on(event: 'turn_started', handler: (e: TurnStartedEvent) => void): Unsubscribe
+  on(event: 'done', handler: (e: DoneEvent) => void): Unsubscribe
+  on(event: 'error', handler: (e: ErrorEvent) => void): Unsubscribe
+  on(event: 'tool_call_started', handler: (e: ToolCallStartedEvent) => void): Unsubscribe
+  on(event: 'tool_call_finished', handler: (e: ToolCallFinishedEvent) => void): Unsubscribe
+  on(event: 'usage', handler: (e: UsageEventData) => void): Unsubscribe
+  on(event: string, handler: (e: unknown) => void): Unsubscribe
+}
+```
+
+### 3.2 Options
+
+```typescript
+interface SalesBotClientOptions {
+  embedKey: string          // pk_live_<32 chars>
+  baseUrl?: string          // default: 'http://localhost:3000'
+  storage?: StorageAdapter  // default: LocalStorageAdapter (with MemoryStorageAdapter fallback)
+  customHeaders?: Record<string, string>  // for Node: { Origin: 'https://...' }
+}
+
+interface AskOptions {
+  conversationId?: string
+  metadata?: Record<string, unknown>
+}
+
+interface IdentifyInput {
+  externalId?: string
+  email?: string
+  name?: string
+  traits?: Record<string, unknown>
+}
+```
+
+### 3.3 Error class
+
+```typescript
+class SalesBotError extends Error {
+  code: SalesBotErrorCode
+  retryable: boolean
+  details?: Record<string, unknown>
+}
+
+type SalesBotErrorCode =
+  | 'invalid_embed_key'
+  | 'origin_not_allowed'
+  | 'rate_limited'
+  | 'out_of_credits'
+  | 'unauthorized'
+  | 'forbidden'
+  | 'not_found'
+  | 'bad_request'
+  | 'unprocessable_entity'
+  | 'conflict'
+  | 'internal'
+  | 'llm_unavailable'
+  | 'mcp_unavailable'
+  | 'network_error'      // SDK-only: fetch failed
+  | 'parse_error'        // SDK-only: SSE frame malformed
+```
+
+### 3.4 React adapter
+
+```typescript
+// Returns stable references; re-renders only on state changes.
+function useSalesBot(opts: UseSalesBotOptions): UseSalesBotResult
+
+interface UseSalesBotOptions extends SalesBotClientOptions {
+  // Optional initial conversationId (e.g. restored from URL hash).
+  conversationId?: string
+}
+
+interface UseSalesBotResult {
+  ask: (message: string, opts?: AskOptions) => Promise<void>
+  messages: Message[]      // [{role, content, id?}]
+  isStreaming: boolean
+  error: SalesBotError | null
+  conversationId: string | null
+  reset: () => void        // clears messages + conversationId
+}
+```
+
+### 3.5 Vue adapter
+
+```typescript
+function useSalesBot(opts: UseSalesBotOptions): {
+  ask: (message: string, opts?: AskOptions) => Promise<void>
+  messages: Ref<Message[]>
+  isStreaming: Ref<boolean>
+  error: Ref<SalesBotError | null>
+  conversationId: Ref<string | null>
+  reset: () => void
+}
+```
+
+### 3.6 Vanilla / IIFE
+
+```typescript
+// Exposed as window.SalesBot
+interface SalesBotGlobal {
+  init(opts: SalesBotClientOptions): SalesBotClient
+  // Convenience: open the floating widget
+  widget(opts: WidgetOptions): WidgetInstance
+}
+```
+
+### 3.7 Widget API
+
+```typescript
+interface WidgetOptions extends SalesBotClientOptions {
+  container?: HTMLElement      // default: document.body
+  position?: 'bottom-right' | 'bottom-left'  // default: 'bottom-right'
+  title?: string               // default: 'Chat with us'
+  placeholder?: string         // default: 'Type a message...'
+  primaryColor?: string        // overrides --sb-primary CSS var
+}
+
+interface WidgetInstance {
+  open(): void
+  close(): void
+  toggle(): void
+  destroy(): void
+}
+```
+
+---
+
+## 4. SSE Parser
+
+The parser is a pure function consuming `ReadableStream<Uint8Array>` and yielding typed `SalesBotEvent` objects.
+
+Wire format (per backend contract):
+```
+event: turn_started\ndata: {"turnId":"...","conversationId":"...","endUserId":"..."}\n\n
+event: delta\ndata: {"content":"Hello"}\n\n
+event: done\ndata: {"turnId":"..."}\n\n
+```
+
+Algorithm:
+1. TextDecoder chunk-by-chunk from the readable stream.
+2. Buffer accumulates text; split on `\n\n` for complete frames.
+3. Each frame: extract `event:` line for the name, `data:` line for JSON.
+4. `JSON.parse` the data; cast to the matching interface by event name.
+5. Yield `{ event: SseEventName, data: <typed payload> }`.
+6. Malformed frames throw `SalesBotError({ code: 'parse_error' })`.
+
+Hand-rolled parser, under 80 lines, zero dependencies.
+
+---
+
+## 5. Storage
+
+```typescript
+interface StorageAdapter {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+}
+```
+
+- **`LocalStorageAdapter`** — wraps `window.localStorage`. Construction throws if `window` is undefined; callers should catch and fall back.
+- **`MemoryStorageAdapter`** — `Map<string, string>`. Used when localStorage is unavailable (SSR, Node, private browsing with quota error).
+- **Auto-detect** at `SalesBotClient` construction: try `LocalStorageAdapter`; catch → fall back to `MemoryStorageAdapter` with a `console.warn`.
+
+Visitor token key: `salesbot:visitor:<embedKey>` (embedKey suffix prevents collisions when multiple bots are embedded).
+
+---
+
+## 6. Visitor Token Management
+
+On first call to `getVisitorToken()`:
+1. Read key from storage.
+2. If present, return it.
+3. If absent, generate via `crypto.randomUUID()` (browser native, no polyfill needed for targets we support).
+4. Persist to storage, return.
+
+Tokens are UUIDs; they are stable across page reloads and cleared only when the storage is cleared. The SDK never exposes a `clearVisitorToken()` — consumers who need that can call `storage.removeItem(key)` directly.
+
+---
+
+## 7. Transport
+
+```typescript
+async function postTurn(
+  input: PostTurnInput,
+  opts: TransportOptions
+): Promise<ReadableStream<Uint8Array>>
+
+async function getResumeStream(
+  turnId: string,
+  opts: TransportOptions
+): Promise<ReadableStream<Uint8Array>>
+```
+
+- Sets `Authorization: Bearer <embedKey>`, `Accept: text/event-stream`, `Content-Type: application/json`.
+- Sets `Idempotency-Key` header with a fresh `crypto.randomUUID()` per `ask()` invocation.
+- `Origin` is set automatically by the browser; Node callers pass via `customHeaders`.
+- On non-2xx response: reads the JSON error body, maps to `SalesBotError`.
+- HTTP 429 → `rate_limited`, 402 → `out_of_credits`, 403 → `origin_not_allowed` or `forbidden`, etc.
+
+---
+
+## 8. Error Handling
+
+All errors thrown by the SDK are `SalesBotError` instances. The `.code` field is a stable TypeScript union that consumers can `switch` on.
+
+HTTP status → code mapping:
+- 400 → `bad_request`
+- 401 → `unauthorized` or `invalid_embed_key` (body.code takes precedence)
+- 402 → `out_of_credits`
+- 403 → body.code takes precedence; default `forbidden`
+- 404 → `not_found`
+- 409 → `conflict`
+- 422 → `unprocessable_entity`
+- 429 → `rate_limited`
+- 5xx → `internal` (or body.code if present)
+- fetch throws (network down) → `network_error`
+
+SSE `error` event → throw `SalesBotError` from the async iterable, emit on `on('error')` bus.
+
+---
+
+## 9. Reconnect / Resume
+
+The SDK tracks the latest `turnId` from `turn_started` on the active client instance. `resume(turnId)` calls `GET /api/chat/turns/:turnId/stream` and returns an `AsyncIterable` of remaining events.
+
+**Policy: opt-in, default off.** The `ask()` method does NOT auto-resume on stream drop. Consumers that want reconnect logic should:
+
+```typescript
+let lastTurnId: string | null = null
+client.on('turn_started', e => { lastTurnId = e.turnId })
+
+async function askWithResume(msg: string) {
+  try {
+    for await (const event of client.ask(msg)) { /* handle */ }
+  } catch (err) {
+    if (lastTurnId && err instanceof SalesBotError && err.retryable) {
+      for await (const event of client.resume(lastTurnId)) { /* handle */ }
+    }
+  }
+}
+```
+
+This keeps `ask()` behavior predictable and avoids ghost messages from double-processing.
+
+---
+
+## 10. Framework Adapters
+
+### 10.1 React (`./react`)
+
+- `useSalesBot(opts)` creates a `SalesBotClient` via `useRef` (stable across renders).
+- State: `messages: Message[]`, `isStreaming: boolean`, `error: SalesBotError | null`.
+- `ask()` appends the user message, sets `isStreaming = true`, drives the async iterable on each `delta`, appends a streaming assistant message, finalizes on `message_complete`, clears on `done` / `error`.
+- `'use client'` directive at top so it's compatible with Next.js App Router (the hook itself uses `useState`/`useEffect`).
+- React is a `peerDependency` (^18).
+
+### 10.2 Vue (`./vue`)
+
+- Same semantics as React adapter, built on `ref`, `shallowRef`, and the `SalesBotClient.on()` event bus.
+- Uses `onUnmounted` to unsubscribe event handlers.
+- Vue is a `peerDependency` (^3.4).
+- No `<script setup>` macro — pure function composable for testing clarity.
+
+### 10.3 Next.js
+
+The React adapter works out of the box with Next.js App Router. Document:
+- Add `'use client'` to any component that calls `useSalesBot`.
+- `baseUrl` should point to the production backend (not localhost).
+- SSR: the hook returns empty `messages` and noop `ask` until hydration. The `SalesBotClient` is constructed client-side only.
+
+### 10.4 Vanilla / IIFE (`./vanilla`)
+
+- `tsup` builds an IIFE bundle that sets `window.SalesBot = { init, widget }`.
+- `init(opts)` returns a `SalesBotClient`.
+- `widget(opts)` constructs and mounts the shadow-DOM widget.
+
+---
+
+## 11. Widget UI
+
+### 11.1 Shadow DOM approach
+
+The widget is mounted inside a shadow root attached to a `<sales-bot-widget>` custom element. This completely isolates its CSS from the host page. No CSS reset needed.
+
+```html
+<!-- Injected into document.body -->
+<sales-bot-widget>
+  #shadow-root
+    <style> ... </style>
+    <button class="sb-launcher">💬</button>
+    <div class="sb-panel">
+      <div class="sb-header">...</div>
+      <div class="sb-messages">...</div>
+      <div class="sb-input-row">
+        <input class="sb-input" />
+        <button class="sb-send">Send</button>
+      </div>
+    </div>
+</sales-bot-widget>
+```
+
+### 11.2 Theming
+
+Consumed as CSS custom properties declared on `:host`:
+
+```css
+:host {
+  --sb-primary: #2563eb;
+  --sb-text: #111827;
+  --sb-bg: #ffffff;
+  --sb-radius: 12px;
+  --sb-z: 9999;
+}
+```
+
+Override from the host page:
+```css
+sales-bot-widget {
+  --sb-primary: hotpink;
+}
+```
+
+Or via `WidgetOptions.primaryColor` which sets an inline style on the custom element.
+
+### 11.3 Markdown rendering
+
+Lightweight hand-rolled renderer:
+- `**bold**` → `<strong>`
+- `*italic*` → `<em>`
+- `` `code` `` → `<code>`
+- `[text](url)` → `<a target="_blank" rel="noopener">` (only https:// links)
+- Newlines → `<br>`
+
+No full Markdown parser dependency (keeps widget bundle small).
+
+### 11.4 Message flow in widget
+
+1. User types and presses Enter or clicks Send.
+2. Widget calls `client.ask(message)`.
+3. Widget appends user bubble immediately.
+4. On `turn_started`, shows a "thinking" indicator.
+5. On first `delta`, replaces thinking indicator with a streaming assistant bubble.
+6. Each `delta` appends to bubble content (rendered as markdown).
+7. On `message_complete`, marks the bubble as complete.
+8. On `done`, enables the input.
+9. On `error`, shows an error message in the chat.
+
+---
+
+## 12. Build & Bundling
+
+### 12.1 tsup config (conceptual)
+
+```typescript
+// tsup.config.ts
+export default defineConfig([
+  // Core, React, Vue — ESM + CJS
+  {
+    entry: {
+      core: 'src/core/index.ts',
+      react: 'src/react/index.ts',
+      vue: 'src/vue/index.ts',
+      widget: 'src/widget/index.ts',
+    },
+    format: ['esm', 'cjs'],
+    dts: true,
+    external: ['react', 'react-dom', 'vue'],
+  },
+  // Vanilla IIFE
+  {
+    entry: { vanilla: 'src/vanilla/index.ts' },
+    format: ['iife'],
+    globalName: 'SalesBot',
+    minify: true,
+    dts: false,
+  },
+])
+```
+
+### 12.2 package.json exports map
+
+```json
+{
+  "exports": {
+    "./core": {
+      "import": "./dist/core.mjs",
+      "require": "./dist/core.cjs"
+    },
+    "./react": {
+      "import": "./dist/react.mjs",
+      "require": "./dist/react.cjs"
+    },
+    "./vue": {
+      "import": "./dist/vue.mjs",
+      "require": "./dist/vue.cjs"
+    },
+    "./widget": {
+      "import": "./dist/widget.mjs",
+      "require": "./dist/widget.cjs"
+    },
+    "./vanilla": "./dist/vanilla.global.js"
+  }
+}
+```
+
+---
+
+## 13. Testing
+
+### 13.1 Framework
+
+**Vitest** with `happy-dom` environment for DOM tests. `@testing-library/react` for React adapter. `@vue/test-utils` for Vue adapter.
+
+### 13.2 Test categories
+
+| File | Approach |
+|---|---|
+| `sse-parser.test.ts` | Feeds mock `ReadableStream` with raw SSE bytes, asserts yielded events |
+| `transport.test.ts` | Mocks `globalThis.fetch` via `vi.stubGlobal`, asserts headers/body/error mapping |
+| `storage.test.ts` | Unit tests for both adapters |
+| `visitor.test.ts` | Asserts token generation + persistence + embedKey namespacing |
+| `client.test.ts` | Integration: mock fetch → full event sequence → state transitions |
+| `use-sales-bot.test.tsx` | React Testing Library, `renderHook`, asserts messages/isStreaming/error |
+| `use-sales-bot.test.ts` | Vue Test Utils, asserts refs update correctly |
+| `widget.test.ts` | happy-dom, asserts shadow DOM structure + interaction |
+| `wire-format.test.ts` | Contract test: TypeScript assignability + runtime shape assertions |
+
+### 13.3 Contract sync
+
+`tests/contract/wire-format.test.ts` imports the event type interfaces from `src/core/types.ts` and asserts they match the exact shapes from the backend's `sse-events.ts` (copied verbatim, not imported cross-project). Any shape mismatch is a compile error before the test even runs.
+
+---
+
+## 14. Bundle-size Budget
+
+Measured gzipped, tracked via `size-limit` in `package.json`.
+
+| Entry | Budget |
+|---|---|
+| `./core` | 8 KB |
+| `./react` | 12 KB (includes core) |
+| `./vue` | 12 KB (includes core) |
+| `./widget` | 25 KB (includes core + styles) |
+| `./vanilla` IIFE | 20 KB |
+
+---
+
+## 15. Decisions Log
+
+| # | Decision | Rationale |
+|---|---|---|
+| 1 | Single package, multiple entry points (not monorepo) | Eliminates version skew between adapters; one `npm install`, one `package.json` to maintain. |
+| 2 | Both `AsyncIterable` AND event-bus (`on()`) interfaces | `AsyncIterable` is cleaner for custom consumers (for-await); event-bus is better for React/Vue adapter internals (no need to manage async loop lifetime). Both are thin wrappers over the same stream. |
+| 3 | Hand-rolled SSE parser, no `eventsource-parser` dep | The backend's SSE format is fixed and simple; a hand-rolled parser stays under 80 lines, is zero-dependency, and is straightforwardly testable. Adds an `eventsource-parser` dep if complexity grows. |
+| 4 | Shadow DOM for widget | Host-page CSS bleed is the #1 real-world pain point for chat widgets. Shadow DOM eliminates it completely and is supported in all target browsers. |
+| 5 | `crypto.randomUUID()` instead of `nanoid` | One fewer dependency; native `crypto.randomUUID()` is available in all modern browsers and Node 15+. |
+| 6 | `MemoryStorageAdapter` fallback (silent warning) | Private browsing mode throws on `localStorage.setItem`. A silent fallback with a `console.warn` keeps the widget working while informing developers. |
+| 7 | `'use client'` on React adapter | Next.js App Router requires this for hooks that use `useState`/`useEffect`; making it explicit in the entry file avoids consumer confusion. |
+| 8 | No auto-reconnect | Opt-in reconnect prevents double-processing of messages; the turn lifecycle is well-defined by the backend, so consumers can implement exactly the reconnect policy they need. |
+| 9 | Biome for linting/formatting | Single binary, minimal config, significantly faster than ESLint + Prettier. Acceptable for a library project. |
+| 10 | Hand-rolled markdown renderer | `marked` is 22KB+ and overkill for the subset needed (`**bold**`, links, code). Hand-rolled renderer stays under 50 lines and keeps the widget bundle small. |
+
+---
+
+## 16. Known Limitations / Follow-ups
+
+- **No retry built into `ask()`** — callers must implement their own retry or use `resume()`.
+- **No conversation history pre-load** — `GET /api/chat/conversations/:id` exists on the backend but the SDK doesn't expose a `loadHistory()` method in v1. Add in a follow-up.
+- **No accessibility audit on widget** — shadow DOM requires explicit ARIA attributes. The v1 widget has basic `aria-label` on key elements but hasn't been audited against WCAG 2.1 AA.
+- **Vue SSR** — `useSalesBot` returns empty state safely in SSR context, but hydration mismatch avoidance hasn't been tested with Nuxt. Document as a known gap.
+- **iOS Safari `ReadableStream` tee** — some older iOS Safari versions have quirks with `ReadableStream`. If user targeting requires iOS < 16, consider adding a `getReader()` polyfill guard.

package/example/.env.example

@@ -0,0 +1,5 @@
+# Backend (NestJS) URL
+VITE_BACKEND_URL=http://localhost:3000
+
+# A bot embed key from /admin/bots/:id
+VITE_EMBED_KEY=pk_live_REPLACE_WITH_ACTUAL_KEY

package/example/README.md

@@ -0,0 +1,90 @@
+# Sales Bot SDK — Example app
+
+Vite + React app that exercises the SDK locally against a running backend.
+
+## Prereqs
+
+1. Backend running at `http://localhost:3000` (sub-project #1 / `sales_bot/`).
+2. A verified Resource on the backend whose `domain` allows `localhost` as an origin.
+   **This is the most common "I tried it and got 403" gotcha** — the SDK sends an `Origin` header
+   with every request. Browsers automatically send `Origin: http://localhost:5173`. The bot's
+   resource must have `localhost` as the verified domain (or use a wildcard match) for the backend
+   to permit the request. Verify a Resource with domain `localhost` for local dev.
+3. A Bot created against that Resource. Copy its `embedKey` (`pk_live_…`) from the admin UI.
+
+## Run
+
+```sh
+# From the SDK repo root (sales_bot_sdk/):
+pnpm build                              # build the SDK → dist/
+pnpm install                            # installs root + example via workspace
+pnpm --filter @sales-bot/sdk-example dev
+# Open http://localhost:5173
+```
+
+Configure via `example/.env.local` (copy from `.env.example`):
+
+```
+VITE_BACKEND_URL=http://localhost:3000
+VITE_EMBED_KEY=pk_live_…
+```
+
+## Pages
+
+| Route      | What it exercises |
+|------------|-------------------|
+| `/`        | `useSalesBot` hook from `@sales-bot/sdk/react` — text input, streaming messages, conversation continuity, identify form |
+| `/widget`  | `createWidget()` from `@sales-bot/sdk/widget` — floating button + panel in shadow DOM, mounted to `<body>` |
+| `/vanilla` | IIFE bundle (`dist/vanilla.global.js`) loaded via `<script>`, uses `window.SalesBot.default.widget()` |
+
+## Known gotchas
+
+### Origin header required
+
+The backend validates `Origin` on every chat request. Vite serves on `http://localhost:5173` by
+default — that is the origin browsers send automatically. Ensure the Bot's Resource has `localhost`
+as a verified domain. If you see `403 origin_not_allowed`, this is why.
+
+Fix: verify a Resource with domain `localhost` in the backend admin UI, then link a Bot to it and
+copy its `embedKey` to `.env.local`.
+
+### Vanilla IIFE global wrapping
+
+The SDK's vanilla bundle is built with `tsup` using `globalName: 'SalesBot'` and `format: 'iife'`.
+The output wraps the module as:
+
+```js
+var SalesBot = (function(exports) {
+  // ...
+  exports.SalesBot = { init, widget }
+  exports.default = { init, widget }
+  return exports
+})({})
+```
+
+In a browser, top-level `var` in a `<script>` tag becomes `window.SalesBot`. However `window.SalesBot`
+is the *exports wrapper object*, not the SDK object directly. The actual API is at:
+
+- `window.SalesBot.default.widget(...)` — recommended
+- `window.SalesBot.SalesBot.widget(...)` — also works
+
+`window.SalesBot.widget(...)` will be `undefined`. This is a known SDK-side quirk (follow-up item).
+The `VanillaDemo` page accounts for this automatically.
+
+### `useSalesBot` does not expose `identify()`
+
+The hook does not currently expose the underlying client's `identify()` method in its return value.
+To call `identify()` you need a direct reference to a `SalesBotClient` instance. This is a
+SDK-side follow-up. The Hook demo notes this inline with an alert.
+
+## Import paths used
+
+```ts
+import { useSalesBot } from '@sales-bot/sdk/react'
+import { createWidget } from '@sales-bot/sdk/widget'
+import type { WidgetInstance } from '@sales-bot/sdk/widget'
+// vanilla: loaded via <script src="/vanilla.global.js">
+// → window.SalesBot.default.widget(...)
+```
+
+These resolve through the SDK's `exports` map in `package.json`.

package/example/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Sales Bot SDK — Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>