@sales-bot-llm/sdk 0.2.0

package/biome.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "complexity": {
+        "noForEach": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "warn"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  },
+  "files": {
+    "ignore": ["dist/**", "node_modules/**", "coverage/**"]
+  }
+}

package/docs/superpowers/plans/2026-05-08-sales-bot-sdk-plan.md

@@ -0,0 +1,258 @@
+# Sales Bot SDK — Implementation Plan
+
+**Date:** 2026-05-08
+**Status:** Active
+**Author:** Claude (autonomous)
+
+Each phase is TDD: write the failing test(s) first, implement to make them pass, commit.
+
+---
+
+## Phase 0 — Bootstrap (package.json, tsconfig, tooling)
+
+### Tasks
+- [ ] 0.1 Create `package.json` with name `@sales-bot/sdk`, TypeScript, tsup, vitest, biome, React/Vue as peerDeps
+- [ ] 0.2 Create `tsconfig.json` — strict mode, ESNext, bundler module resolution
+- [ ] 0.3 Create `tsup.config.ts` — ESM+CJS for core/react/vue/widget; IIFE for vanilla
+- [ ] 0.4 Create `vitest.config.ts` — happy-dom environment, coverage
+- [ ] 0.5 Create `biome.json` — formatting + lint rules
+- [ ] 0.6 Install dependencies
+
+**Commit:** `chore: bootstrap package — tsup, vitest, biome, tsconfig`
+
+---
+
+## Phase 1 — Core types
+
+### Tasks
+- [ ] 1.1 Write `tests/contract/wire-format.test.ts` — imports types, asserts shape assignability
+- [ ] 1.2 Create `src/core/types.ts` — verbatim event interfaces from backend, `SalesBotEvent` union, `SalesBotErrorCode`, `IdentifyInput`, `AskOptions`, `PostTurnInput`, `StorageAdapter`, `Unsubscribe`
+- [ ] 1.3 Make contract test pass (compile-time + runtime shape assertions)
+
+**Commit:** `feat(core): wire-format types + contract tests`
+
+---
+
+## Phase 2 — SSE parser
+
+### TDD steps
+1. Write `tests/core/sse-parser.test.ts`:
+   - parse single `turn_started` frame
+   - parse multiple frames in one chunk
+   - parse frames split across chunk boundaries
+   - parse `error` frame
+   - handle malformed frame → `SalesBotError({ code: 'parse_error' })`
+   - handle empty stream
+2. Implement `src/core/sse-parser.ts`
+3. All tests pass
+
+**Commit:** `feat(core): SSE parser with boundary-spanning chunk handling`
+
+---
+
+## Phase 3 — Storage adapters
+
+### TDD steps
+1. Write `tests/core/storage.test.ts`:
+   - `LocalStorageAdapter` get/set/remove (happy-dom has localStorage)
+   - `MemoryStorageAdapter` get/set/remove
+   - `MemoryStorageAdapter` isolation between instances
+2. Implement `src/core/storage.ts`
+3. All tests pass
+
+**Commit:** `feat(core): LocalStorageAdapter + MemoryStorageAdapter`
+
+---
+
+## Phase 4 — Visitor token
+
+### TDD steps
+1. Write `tests/core/visitor.test.ts`:
+   - generates UUID on first call
+   - returns same UUID on subsequent calls (same storage)
+   - namespaces key by embedKey
+   - uses injected storage adapter
+2. Implement `src/core/visitor.ts`
+3. All tests pass
+
+**Commit:** `feat(core): visitor token generation + persistence`
+
+---
+
+## Phase 5 — SalesBotError
+
+### Tasks
+- [ ] 5.1 Add `SalesBotError` class to `src/core/types.ts`
+- [ ] 5.2 Write test asserting it extends `Error`, has `.code`, `.retryable`, `.details`
+- [ ] 5.3 Make test pass
+
+**Commit:** `feat(core): SalesBotError class`
+
+---
+
+## Phase 6 — HTTP transport
+
+### TDD steps
+1. Write `tests/core/transport.test.ts`:
+   - sets `Authorization: Bearer <embedKey>` header
+   - sets `Idempotency-Key` header
+   - sets `Accept: text/event-stream`
+   - sets `Content-Type: application/json`
+   - sends correct JSON body
+   - returns `ReadableStream` on 200
+   - maps 401 → `SalesBotError({ code: 'invalid_embed_key' })` when body has that code
+   - maps 402 → `out_of_credits`
+   - maps 429 → `rate_limited`
+   - maps 500 → `internal`
+   - maps fetch throw → `network_error`
+   - `getResumeStream` calls `GET /api/chat/turns/:turnId/stream`
+   - merges `customHeaders`
+2. Implement `src/core/transport.ts`
+3. All tests pass
+
+**Commit:** `feat(core): fetch-based HTTP transport with error mapping`
+
+---
+
+## Phase 7 — SalesBotClient class
+
+### TDD steps
+1. Write `tests/core/client.test.ts`:
+   - constructor stores embedKey, creates storage, generates visitor token
+   - `identify()` stores traits for next ask
+   - `ask()` calls postTurn with correct body (visitorToken, message, identify, conversationId)
+   - `ask()` yields events from the SSE stream
+   - `ask()` emits events on the event bus simultaneously
+   - `ask()` auto-updates conversationId from `turn_started`
+   - `resume(turnId)` calls getResumeStream
+   - `on()` returns unsubscribe function that actually unsubscribes
+   - `getVisitorToken()` returns stable UUID
+   - `getConversationId()` / `setConversationId()`
+2. Implement `src/core/client.ts`
+3. Implement `src/core/index.ts` re-exports
+4. All tests pass
+
+**Commit:** `feat(core): SalesBotClient with ask/identify/resume/on API`
+
+---
+
+## Phase 8 — React adapter
+
+### TDD steps
+1. Write `tests/react/use-sales-bot.test.tsx`:
+   - `renderHook(() => useSalesBot({ embedKey }))` returns stable shape
+   - `ask()` appends user message to `messages`
+   - `isStreaming` becomes true during ask, false after done
+   - `messages` accumulates assistant deltas
+   - `error` is set on SalesBotError
+   - `reset()` clears messages and conversationId
+   - client is not re-created on re-render
+2. Implement `src/react/use-sales-bot.tsx`
+3. Implement `src/react/index.ts`
+4. All tests pass
+
+**Commit:** `feat(react): useSalesBot hook`
+
+---
+
+## Phase 9 — Vue adapter
+
+### TDD steps
+1. Write `tests/vue/use-sales-bot.test.ts`:
+   - composable returns reactive refs
+   - `ask()` updates `messages` ref
+   - `isStreaming` ref transitions correctly
+   - `error` ref set on failure
+   - `reset()` clears state
+   - handlers unsubscribed on unmount
+2. Implement `src/vue/use-sales-bot.ts`
+3. Implement `src/vue/index.ts`
+4. All tests pass
+
+**Commit:** `feat(vue): useSalesBot composable`
+
+---
+
+## Phase 10 — Widget UI
+
+### Tasks
+- [ ] 10.1 Write `tests/widget/widget.test.ts`:
+   - `createWidget(opts)` appends `<sales-bot-widget>` to body
+   - shadow root contains launcher button and panel
+   - clicking launcher opens/closes panel
+   - `destroy()` removes element from DOM
+   - basic message rendering in shadow DOM
+- [ ] 10.2 Implement `src/widget/styles.ts` — CSS string for shadow root
+- [ ] 10.3 Implement `src/widget/widget.ts` — shadow DOM, message rendering, event wiring
+- [ ] 10.4 Implement `src/widget/index.ts`
+- [ ] 10.5 All tests pass
+
+**Commit:** `feat(widget): shadow-DOM floating chat widget`
+
+---
+
+## Phase 11 — Vanilla / IIFE bundle entry
+
+### Tasks
+- [ ] 11.1 Implement `src/vanilla/index.ts` — `window.SalesBot = { init, widget }`
+- [ ] 11.2 Write a smoke test asserting `init()` returns a `SalesBotClient`
+- [ ] 11.3 All tests pass
+
+**Commit:** `feat(vanilla): IIFE entry with window.SalesBot`
+
+---
+
+## Phase 12 — Build pipeline
+
+### Tasks
+- [ ] 12.1 Finalize `tsup.config.ts` with all entry points
+- [ ] 12.2 Finalize `package.json` exports map
+- [ ] 12.3 Run `pnpm build` and verify `dist/` contains expected files
+- [ ] 12.4 Spot-check each bundle imports cleanly
+
+**Commit:** `build: finalize tsup config + exports map`
+
+---
+
+## Phase 13 — size-limit
+
+### Tasks
+- [ ] 13.1 Add `size-limit` config to `package.json`
+- [ ] 13.2 Run `size-limit` and verify budgets pass (core <8KB, react/vue <12KB, widget <25KB, vanilla <20KB)
+
+**Commit:** `ci: add size-limit bundle budget checks`
+
+---
+
+## Phase 14 — Final review + cleanup
+
+### Tasks
+- [ ] 14.1 Run full test suite — all pass
+- [ ] 14.2 Run biome check — no errors
+- [ ] 14.3 Verify builds produce correct output
+- [ ] 14.4 Review public API surface for consistency
+
+**Commit:** `chore: final cleanup and verification`
+
+---
+
+## Dependency matrix
+
+| Package | Role | Dev/Peer/Prod |
+|---|---|---|
+| `typescript` | Language | dev |
+| `tsup` | Bundler | dev |
+| `vitest` | Test runner | dev |
+| `happy-dom` | DOM env | dev |
+| `@testing-library/react` | React test utils | dev |
+| `@testing-library/user-event` | User interaction | dev |
+| `@vue/test-utils` | Vue test utils | dev |
+| `@vitejs/plugin-react` | React support in vitest | dev |
+| `biome` | Lint + format | dev |
+| `size-limit` | Bundle budget | dev |
+| `@size-limit/preset-small-lib` | size-limit preset | dev |
+| `react` | React framework | peerDep |
+| `react-dom` | React DOM | peerDep |
+| `vue` | Vue framework | peerDep |
+
+**Zero runtime dependencies.** All helpers (SSE parser, markdown renderer, storage) are hand-rolled and tree-shakeable.