@sales-bot-llm/sdk 0.2.0

package/example/src/routes/VanillaDemo.tsx

@@ -0,0 +1,67 @@
+import { useEffect } from 'react'
+
+// The IIFE bundle (vanilla.global.js) is copied to public/ by the predev/prebuild script.
+// Top-level `var SalesBot` in a <script> tag becomes window.SalesBot in browsers.
+// However, tsup's IIFE output wraps exports as:
+//   var SalesBot = (function(exports){ ... exports.SalesBot = {...}; exports.default = {...}; return exports; })({})
+// so window.SalesBot is the exports wrapper object, not the SDK object directly.
+// Use window.SalesBot.default.widget(...) or window.SalesBot.SalesBot.widget(...)
+// See README Known gotchas § Vanilla IIFE wrapping.
+
+declare global {
+  interface Window {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    SalesBot?: any
+  }
+}
+
+export function VanillaDemo() {
+  const embedKey = (import.meta.env.VITE_EMBED_KEY as string | undefined) ?? ''
+  const baseUrl =
+    (import.meta.env.VITE_BACKEND_URL as string | undefined) ?? 'http://localhost:3000'
+
+  useEffect(() => {
+    if (!embedKey) return
+
+    const script = document.createElement('script')
+    // public/vanilla.global.js is copied there by the predev script
+    script.src = '/vanilla.global.js'
+    script.onload = () => {
+      const sb = window.SalesBot?.default ?? window.SalesBot?.SalesBot
+      if (!sb) {
+        console.error('[VanillaDemo] window.SalesBot not found after script load')
+        return
+      }
+      const mountEl = document.getElementById('vanilla-mount')
+      if (mountEl) {
+        sb.widget({ embedKey, baseUrl, container: mountEl })
+      }
+    }
+    document.head.appendChild(script)
+
+    return () => {
+      document.head.removeChild(script)
+      delete window.SalesBot
+    }
+  }, [embedKey, baseUrl])
+
+  return (
+    <div>
+      <h2>Vanilla / IIFE demo</h2>
+      <p>
+        Exercises <code>dist/vanilla.global.js</code> loaded via <code>&lt;script&gt;</code> ·
+        uses <code>window.SalesBot.default.widget()</code> to mount a chat widget.
+      </p>
+      <p>
+        The IIFE bundle is served from <code>/vanilla.global.js</code> (copied to{' '}
+        <code>public/</code> by the <code>predev</code> script).
+      </p>
+      {!embedKey && (
+        <div className="error">
+          VITE_EMBED_KEY is not set — widget will not mount.
+        </div>
+      )}
+      <div id="vanilla-mount" style={{ position: 'relative', height: '400px', border: '1px dashed #ccc', borderRadius: '8px', marginTop: '1rem' }} />
+    </div>
+  )
+}

package/example/src/routes/WidgetDemo.tsx

@@ -0,0 +1,55 @@
+import { useEffect, useRef } from 'react'
+import { createWidget } from '@sales-bot/sdk/widget'
+import type { WidgetInstance } from '@sales-bot/sdk/core'
+
+export function WidgetDemo() {
+  const embedKey = (import.meta.env.VITE_EMBED_KEY as string | undefined) ?? ''
+  const baseUrl =
+    (import.meta.env.VITE_BACKEND_URL as string | undefined) ?? 'http://localhost:3000'
+
+  const instanceRef = useRef<WidgetInstance | null>(null)
+
+  useEffect(() => {
+    if (!embedKey) return
+
+    const widget = createWidget({ embedKey, baseUrl, container: document.body })
+    instanceRef.current = widget
+
+    return () => {
+      widget.destroy()
+      instanceRef.current = null
+    }
+  }, [embedKey, baseUrl])
+
+  return (
+    <div>
+      <h2>Widget demo</h2>
+      <p>
+        Exercises <code>@sales-bot/sdk/widget</code> · <code>createWidget()</code> · shadow DOM.
+      </p>
+      <p>
+        The floating chat button appears in the <strong>bottom-right corner</strong> of the
+        viewport. The widget is mounted into <code>document.body</code> using shadow DOM and is
+        cleaned up when you navigate away.
+      </p>
+      {!embedKey && (
+        <div className="error">
+          VITE_EMBED_KEY is not set — widget will not mount. Copy{' '}
+          <code>.env.example</code> to <code>.env.local</code> and restart Vite.
+        </div>
+      )}
+
+      <div style={{ marginTop: '1rem', display: 'flex', gap: '0.5rem' }}>
+        <button type="button" onClick={() => instanceRef.current?.open()}>
+          Open widget
+        </button>
+        <button type="button" onClick={() => instanceRef.current?.close()}>
+          Close widget
+        </button>
+        <button type="button" onClick={() => instanceRef.current?.toggle()}>
+          Toggle widget
+        </button>
+      </div>
+    </div>
+  )
+}

package/example/src/styles.css

@@ -0,0 +1,18 @@
+body { font-family: system-ui, sans-serif; max-width: 720px; margin: 2rem auto; padding: 0 1rem; }
+nav { display: flex; gap: 1rem; margin-bottom: 1.5rem; }
+nav a { padding: 0.4rem 0.8rem; border-radius: 6px; background: #f0f0f0; text-decoration: none; color: inherit; }
+nav a.active { background: #111; color: #fff; }
+.env-warning { background: #fff8e1; border: 1px solid #f9c23c; border-radius: 6px; padding: 0.6rem 1rem; margin: 0.5rem 0 1rem; }
+.env-ok { font-size: 0.85rem; color: #555; }
+.messages { list-style: none; padding: 0; }
+.messages li { padding: 0.5rem 0.75rem; border-radius: 6px; margin: 0.4rem 0; }
+.messages .role-user { background: #e6f3ff; }
+.messages .role-assistant { background: #f5f5f5; }
+form { display: flex; gap: 0.5rem; margin-top: 1rem; flex-wrap: wrap; }
+input { flex: 1; padding: 0.5rem; border: 1px solid #ccc; border-radius: 6px; min-width: 0; }
+button { padding: 0.5rem 1rem; border: 1px solid #ccc; border-radius: 6px; cursor: pointer; background: #fff; }
+button:disabled { opacity: 0.5; cursor: not-allowed; }
+.error { color: #c00; padding: 0.5rem; background: #fff0f0; border-radius: 4px; margin: 0.5rem 0; }
+.streaming-cursor { animation: blink 1s step-end infinite; }
+@keyframes blink { 50% { opacity: 0; } }
+.identify-form { display: flex; gap: 0.5rem; margin-top: 0.5rem; flex-wrap: wrap; }

package/example/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"]
+}

package/example/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/app.tsx","./src/main.tsx","./src/routes/hookdemo.tsx","./src/routes/vanillademo.tsx","./src/routes/widgetdemo.tsx"],"version":"5.9.3"}

package/example/vite.config.ts

@@ -0,0 +1,4 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({ plugins: [react()] })

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@sales-bot-llm/sdk",
+  "version": "0.2.0",
+  "description": "Frontend SDK for the Sales Bot chat API — framework-agnostic core with React, Vue, and vanilla adapters",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js",
+      "require": "./dist/core.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js",
+      "require": "./dist/vue.cjs"
+    },
+    "./widget": {
+      "types": "./dist/widget.d.ts",
+      "import": "./dist/widget.js",
+      "require": "./dist/widget.cjs"
+    },
+    "./vanilla": {
+      "script": "./dist/vanilla.global.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "size": "size-limit",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "vue": ">=3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^4.7.0",
+    "@vue/test-utils": "^2.4.10",
+    "happy-dom": "^15.11.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "size-limit": "^11.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9",
+    "vue": "^3.5.34"
+  },
+  "size-limit": [
+    {
+      "name": "core",
+      "path": "./dist/core.js",
+      "limit": "8 KB"
+    },
+    {
+      "name": "react",
+      "path": "./dist/react.js",
+      "limit": "12 KB"
+    },
+    {
+      "name": "vue",
+      "path": "./dist/vue.js",
+      "limit": "12 KB"
+    },
+    {
+      "name": "widget",
+      "path": "./dist/widget.js",
+      "limit": "25 KB"
+    },
+    {
+      "name": "vanilla",
+      "path": "./dist/vanilla.global.js",
+      "limit": "20 KB"
+    }
+  ]
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+packages:
+  - .
+  - example

package/src/core/client.ts

@@ -0,0 +1,245 @@
+import type {
+  SalesBotClientOptions,
+  IdentifyInput,
+  AskOptions,
+  SalesBotEvent,
+  SseEventName,
+  TurnStartedEvent,
+  DeltaEvent,
+  ToolCallStartedEvent,
+  ToolCallFinishedEvent,
+  MessageCompleteEvent,
+  UsageEventData,
+  DoneEvent,
+  ErrorEvent,
+  Unsubscribe,
+} from './types'
+import { createDefaultStorage } from './storage'
+import { getOrCreateVisitorToken } from './visitor'
+import { loadConversationId, saveConversationId } from './conversation'
+import { parseSseStream } from './sse-parser'
+import { postTurn, getResumeStream, getBotConfig, getConversationHistory, postEndConversation } from './transport'
+import type { PublicBotConfig, HistoryMessage } from './transport'
+import type { StorageAdapter } from './types'
+
+type EventHandler<T> = (data: T) => void
+
+type EventMap = {
+  turn_started: TurnStartedEvent
+  delta: DeltaEvent
+  tool_call_started: ToolCallStartedEvent
+  tool_call_finished: ToolCallFinishedEvent
+  message_complete: MessageCompleteEvent
+  usage: UsageEventData
+  done: DoneEvent
+  error: ErrorEvent
+}
+
+/**
+ * The core Sales Bot client.
+ *
+ * Framework-agnostic. Works in any environment that has:
+ *   - fetch
+ *   - crypto.randomUUID
+ *   - ReadableStream
+ */
+export class SalesBotClient {
+  private readonly embedKey: string
+  private readonly baseUrl: string
+  private readonly customHeaders?: Record<string, string>
+  private readonly storage: StorageAdapter
+  private readonly visitorToken: string
+  private conversationId: string | null
+  private pendingIdentify: IdentifyInput | null = null
+
+  // Event bus: map of event name → Set of handlers
+  private readonly handlers = new Map<string, Set<EventHandler<unknown>>>()
+
+  constructor(opts: SalesBotClientOptions) {
+    this.embedKey = opts.embedKey
+    this.baseUrl = opts.baseUrl ?? 'http://localhost:3000'
+    this.customHeaders = opts.customHeaders
+
+    this.storage = opts.storage ?? createDefaultStorage()
+    this.visitorToken = getOrCreateVisitorToken(opts.embedKey, this.storage)
+    // Hydrate conversationId from storage so refresh/reopen continues the
+    // same conversation server-side (last-20-messages window keeps the LLM
+    // in context). Cleared explicitly via setConversationId(null).
+    this.conversationId = loadConversationId(opts.embedKey, this.storage)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Identification
+  // ---------------------------------------------------------------------------
+
+  /** Merge identify traits into the next ask() call. */
+  identify(traits: IdentifyInput): void {
+    this.pendingIdentify = { ...this.pendingIdentify, ...traits }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Ask — starts a new agent turn
+  // ---------------------------------------------------------------------------
+
+  async *ask(message: string, opts?: AskOptions): AsyncIterable<SalesBotEvent> {
+    const input = {
+      visitorToken: this.visitorToken,
+      message,
+      identify: this.pendingIdentify ?? undefined,
+      conversationId: opts?.conversationId ?? this.conversationId ?? undefined,
+      metadata: opts?.metadata,
+    }
+
+    const transportOpts = {
+      embedKey: this.embedKey,
+      baseUrl: this.baseUrl,
+      customHeaders: this.customHeaders,
+    }
+
+    const stream = await postTurn(input, transportOpts)
+    yield* this.consumeStream(stream)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Resume — re-attach to an in-flight turn
+  // ---------------------------------------------------------------------------
+
+  async *resume(turnId: string): AsyncIterable<SalesBotEvent> {
+    const transportOpts = {
+      embedKey: this.embedKey,
+      baseUrl: this.baseUrl,
+      customHeaders: this.customHeaders,
+    }
+    const stream = await getResumeStream(turnId, transportOpts)
+    yield* this.consumeStream(stream)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Stream consumer — parses SSE and emits on both iterable and event bus
+  // ---------------------------------------------------------------------------
+
+  private async *consumeStream(stream: ReadableStream<Uint8Array>): AsyncIterable<SalesBotEvent> {
+    for await (const event of parseSseStream(stream)) {
+      // Side-effects: update client state
+      if (event.event === 'turn_started') {
+        const next = (event.data as TurnStartedEvent).conversationId
+        this.conversationId = next
+        saveConversationId(this.embedKey, next, this.storage)
+      }
+
+      // Emit on event bus
+      this.emit(event.event, event.data)
+
+      // Yield to the async iterable consumer
+      yield event
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Conversation state
+  // ---------------------------------------------------------------------------
+
+  getVisitorToken(): string {
+    return this.visitorToken
+  }
+
+  getConversationId(): string | null {
+    return this.conversationId
+  }
+
+  setConversationId(id: string | null): void {
+    this.conversationId = id
+    saveConversationId(this.embedKey, id, this.storage)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Bot config — fetched once per client instance
+  // ---------------------------------------------------------------------------
+
+  private botConfigPromise: Promise<PublicBotConfig> | null = null
+
+  /**
+   * Fetch the public bot config (name + greeting). Cached per client
+   * instance — repeated calls return the same in-flight or resolved promise.
+   * Throws SalesBotError on network/HTTP failure; callers should fall back
+   * gracefully (e.g. skip greeting rather than fail the whole widget).
+   */
+  getBotConfig(): Promise<PublicBotConfig> {
+    if (!this.botConfigPromise) {
+      this.botConfigPromise = getBotConfig({
+        embedKey: this.embedKey,
+        baseUrl: this.baseUrl,
+        customHeaders: this.customHeaders,
+      })
+    }
+    return this.botConfigPromise
+  }
+
+  /**
+   * Load the persisted transcript for the currently-tracked conversation
+   * (or an explicit override). Returns an empty array when there is no
+   * conversation to load — safe to call unconditionally on widget mount.
+   * Used by the widget to repopulate message bubbles after page refresh.
+   */
+  async loadHistory(conversationId?: string): Promise<HistoryMessage[]> {
+    const id = conversationId ?? this.conversationId
+    if (!id) return []
+    return getConversationHistory(id, this.visitorToken, {
+      embedKey: this.embedKey,
+      baseUrl: this.baseUrl,
+      customHeaders: this.customHeaders,
+    })
+  }
+
+  /**
+   * End the current conversation. Server-side: soft-deletes the row so
+   * future history fetches return empty and the admin list drops it.
+   * Client-side: clears the persisted conversationId so the next ask()
+   * starts a fresh conversation. Idempotent — safe to call when there's
+   * no active conversation (no-op + clears local state defensively).
+   */
+  async endConversation(): Promise<void> {
+    const id = this.conversationId
+    if (id) {
+      try {
+        await postEndConversation(id, this.visitorToken, {
+          embedKey: this.embedKey,
+          baseUrl: this.baseUrl,
+          customHeaders: this.customHeaders,
+        })
+      } catch (err) {
+        // Network/auth failure — still clear local state so the user can
+        // start a new conversation locally. The server-side row may stay
+        // alive; retention will purge it eventually.
+        this.setConversationId(null)
+        throw err
+      }
+    }
+    this.setConversationId(null)
+  }
+
+  // ---------------------------------------------------------------------------
+  // Event bus
+  // ---------------------------------------------------------------------------
+
+  on<K extends SseEventName>(event: K, handler: EventHandler<EventMap[K]>): Unsubscribe
+  on(event: string, handler: EventHandler<unknown>): Unsubscribe
+  on(event: string, handler: EventHandler<unknown>): Unsubscribe {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set())
+    }
+    this.handlers.get(event)!.add(handler)
+
+    return () => {
+      this.handlers.get(event)?.delete(handler)
+    }
+  }
+
+  private emit(event: string, data: unknown): void {
+    const listeners = this.handlers.get(event)
+    if (!listeners) return
+    for (const handler of listeners) {
+      handler(data)
+    }
+  }
+}

package/src/core/conversation.ts

@@ -0,0 +1,34 @@
+import type { StorageAdapter } from './types'
+
+export const CONVERSATION_ID_KEY_PREFIX = 'salesbot:conversation:'
+
+/**
+ * Returns the persisted conversationId for a given embed key, or null if none.
+ *
+ * Stored in the provided storage adapter under:
+ *   salesbot:conversation:<embedKey>
+ *
+ * Persisting the conversation id across page loads (in browser localStorage by
+ * default) is what makes the chat feel continuous: the same EndUser keeps
+ * talking to the same Conversation row, and the backend's last-20-messages
+ * sliding window keeps the model in context.
+ */
+export function loadConversationId(embedKey: string, storage: StorageAdapter): string | null {
+  return storage.getItem(`${CONVERSATION_ID_KEY_PREFIX}${embedKey}`)
+}
+
+/**
+ * Persist (or clear, when id is null) the active conversation id.
+ */
+export function saveConversationId(
+  embedKey: string,
+  id: string | null,
+  storage: StorageAdapter,
+): void {
+  const key = `${CONVERSATION_ID_KEY_PREFIX}${embedKey}`
+  if (id === null) {
+    storage.removeItem(key)
+  } else {
+    storage.setItem(key, id)
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+export * from './types'
+export { SalesBotClient } from './client'
+export { LocalStorageAdapter, MemoryStorageAdapter, createDefaultStorage } from './storage'
+export { getOrCreateVisitorToken, VISITOR_TOKEN_KEY_PREFIX } from './visitor'
+export { parseSseStream } from './sse-parser'
+export { postTurn, getResumeStream } from './transport'

package/src/core/sse-parser.ts

@@ -0,0 +1,87 @@
+import { SalesBotError } from './types'
+import type { SalesBotEvent, SseEventName } from './types'
+
+/**
+ * Parse a Server-Sent Events stream from the Sales Bot backend.
+ *
+ * Consumes a ReadableStream<Uint8Array> and yields typed SalesBotEvent objects.
+ * Handles frames split across chunk boundaries correctly.
+ *
+ * Wire format (per backend contract):
+ *   event: <name>\ndata: <json>\n\n
+ */
+export async function* parseSseStream(
+  stream: ReadableStream<Uint8Array>,
+): AsyncIterable<SalesBotEvent> {
+  const decoder = new TextDecoder()
+  const reader = stream.getReader()
+  let buffer = ''
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+
+      buffer += decoder.decode(value, { stream: true })
+
+      // Split on the double-newline SSE frame delimiter
+      const frames = buffer.split('\n\n')
+
+      // The last element is either empty (complete frame ended with \n\n)
+      // or an incomplete frame to carry over in the buffer.
+      buffer = frames.pop() ?? ''
+
+      for (const frame of frames) {
+        const trimmed = frame.trim()
+        if (!trimmed) continue
+
+        const event = parseFrame(trimmed)
+        if (event !== null) yield event
+      }
+    }
+
+    // Flush any remaining content in the decoder
+    const tail = decoder.decode(undefined, { stream: false })
+    if (tail) buffer += tail
+
+    // Process any final frame
+    const frames = buffer.split('\n\n')
+    for (const frame of frames) {
+      const trimmed = frame.trim()
+      if (!trimmed) continue
+      const event = parseFrame(trimmed)
+      if (event !== null) yield event
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+function parseFrame(frame: string): SalesBotEvent | null {
+  let eventName: string | null = null
+  let dataLine: string | null = null
+
+  for (const line of frame.split('\n')) {
+    if (line.startsWith('event:')) {
+      eventName = line.slice('event:'.length).trim()
+    } else if (line.startsWith('data:')) {
+      dataLine = line.slice('data:'.length).trim()
+    }
+  }
+
+  // Frames without an event name are skipped (keepalive pings, etc.)
+  if (eventName === null || dataLine === null) return null
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(dataLine)
+  } catch {
+    throw new SalesBotError({
+      code: 'parse_error',
+      message: `Failed to parse SSE data as JSON for event "${eventName}": ${dataLine}`,
+      retryable: false,
+    })
+  }
+
+  return { event: eventName as SseEventName, data: parsed } as SalesBotEvent
+}