@sales-bot-llm/sdk 0.2.0

package/src/widget/widget.ts

@@ -0,0 +1,442 @@
+import { SalesBotClient } from '../core/client'
+import { SalesBotError, isSalesWorkflowTool } from '../core/types'
+import type {
+  WidgetOptions,
+  WidgetInstance,
+  WidgetTheme,
+  DeltaEvent,
+  MessageCompleteEvent,
+  ToolCallStartedEvent,
+  ToolCallFinishedEvent,
+  SalesWorkflowToolName,
+} from '../core/types'
+import { WIDGET_CSS } from './styles'
+import { renderMarkdown } from './markdown'
+
+/** Friendly status text shown for each sales-workflow tool. */
+const SALES_TOOL_PILL_TEXT: Record<SalesWorkflowToolName, string> = {
+  'project_brief__set_field': 'Saving project details…',
+  'project_brief__get_current': 'Checking project details…',
+  'quotes__generate': 'Generating quote…',
+  'quotes__send_as_pdf': 'Sending quote PDF…',
+  'quotes__send_as_proposal': 'Sending proposal for signing…',
+}
+
+/**
+ * Create and mount a floating chat widget using shadow DOM.
+ *
+ * Security note: All text content that gets rendered as HTML passes through
+ * renderMarkdown(), which HTML-escapes the source before applying markdown
+ * transforms. User-entered content is rendered with escapeHtml() only.
+ * No unsanitized external content is ever written to innerHTML.
+ *
+ * @example
+ * const widget = createWidget({ embedKey: 'pk_live_xxx' })
+ * widget.open()
+ */
+export function createWidget(opts: WidgetOptions): WidgetInstance {
+  const container = opts.container ?? document.body
+  const position = opts.position ?? 'bottom-right'
+  const title = opts.title ?? 'Chat with us'
+  const placeholder = opts.placeholder ?? 'Type a message...'
+
+  // Create the custom element
+  const host = document.createElement('sales-bot-widget') as HTMLElement
+  if (position === 'bottom-left') host.classList.add('sb-position--bottom-left')
+
+  // Theme: typed CSS-var overrides land as inline custom properties on :host.
+  // Order is intentional: legacy `primaryColor` first, then `theme` so the
+  // typed API wins on collision.
+  if (opts.primaryColor) {
+    host.style.setProperty('--sb-primary', opts.primaryColor)
+  }
+  if (opts.theme) applyTheme(host, opts.theme)
+
+  // Attach shadow root
+  const shadow = host.attachShadow({ mode: 'open' })
+
+  // Inject base styles
+  const styleEl = document.createElement('style')
+  // Safe: WIDGET_CSS is a static compile-time string literal, not user input
+  styleEl.textContent = WIDGET_CSS
+  shadow.appendChild(styleEl)
+
+  // Escape-hatch: integrators inject raw CSS that wins via cascade order.
+  // It targets the same class names used internally and is scoped to the
+  // shadow root, so it can never leak out or be polluted by host-page CSS.
+  if (opts.customCss && opts.customCss.trim()) {
+    const customStyleEl = document.createElement('style')
+    customStyleEl.setAttribute('data-sb-custom', '1')
+    customStyleEl.textContent = opts.customCss
+    shadow.appendChild(customStyleEl)
+  }
+
+  // Build DOM structure using textContent / setAttribute for safety
+  const launcher = createElement('button', 'sb-launcher', { 'aria-label': 'Open chat', type: 'button' })
+  // Safe: static SVG icon string, not user-supplied
+  setStaticSvgContent(launcher, CHAT_ICON_SVG)
+
+  const panel = createElement('div', 'sb-panel', { role: 'dialog', 'aria-label': title })
+
+  const header = createElement('div', 'sb-header')
+  const headerTitle = createElement('p', 'sb-header-title')
+  headerTitle.textContent = title  // plain text — safe
+  const headerActions = createElement('div', 'sb-header-actions')
+  const newChatBtn = createElement('button', 'sb-new-chat-btn', {
+    'aria-label': 'Start a new chat',
+    title: 'Start a new chat',
+    type: 'button',
+  })
+  setStaticSvgContent(newChatBtn, NEW_CHAT_ICON_SVG)
+  const closeBtn = createElement('button', 'sb-close-btn', { 'aria-label': 'Close chat', type: 'button' })
+  closeBtn.textContent = '×'  // plain text — safe
+  headerActions.appendChild(newChatBtn)
+  headerActions.appendChild(closeBtn)
+  header.appendChild(headerTitle)
+  header.appendChild(headerActions)
+
+  const messagesEl = createElement('div', 'sb-messages', { 'aria-live': 'polite' })
+
+  const inputRow = createElement('div', 'sb-input-row')
+  const input = createElement('input', 'sb-input', {
+    type: 'text',
+    placeholder,
+    'aria-label': 'Message input',
+  }) as HTMLInputElement
+  const sendBtn = createElement('button', 'sb-send', { 'aria-label': 'Send message', type: 'button' }) as HTMLButtonElement
+  setStaticSvgContent(sendBtn, SEND_ICON_SVG)
+  inputRow.appendChild(input)
+  inputRow.appendChild(sendBtn)
+
+  panel.appendChild(header)
+  panel.appendChild(messagesEl)
+  panel.appendChild(inputRow)
+
+  shadow.appendChild(launcher)
+  shadow.appendChild(panel)
+  container.appendChild(host)
+
+  // SalesBotClient
+  const client = new SalesBotClient(opts)
+
+  // Message rendering helpers
+  let streamingMsgEl: HTMLElement | null = null
+  let streamingContent = ''
+
+  function appendUserMessage(text: string): void {
+    const msg = createElement('div', 'sb-message sb-message--user')
+    msg.textContent = text  // plain text — no HTML in user messages
+    messagesEl.appendChild(msg)
+    scrollToBottom()
+  }
+
+  function appendAssistantMessage(markdownContent: string): HTMLElement {
+    const msg = createElement('div', 'sb-message sb-message--assistant')
+    // Safe: renderMarkdown() HTML-escapes the source before applying transforms
+    setRenderedMarkdown(msg, markdownContent)
+    messagesEl.appendChild(msg)
+    scrollToBottom()
+    return msg
+  }
+
+  function appendErrorMessage(text: string): void {
+    const msg = createElement('div', 'sb-message sb-message--error')
+    msg.textContent = text  // plain text — safe
+    messagesEl.appendChild(msg)
+    scrollToBottom()
+  }
+
+  function scrollToBottom() {
+    messagesEl.scrollTop = messagesEl.scrollHeight
+  }
+
+  function showThinking(): HTMLElement {
+    const el = createElement('div', 'sb-message sb-message--assistant sb-thinking')
+    el.dataset['thinking'] = '1'
+    // Dots are created as real elements, not innerHTML
+    for (let i = 0; i < 3; i++) el.appendChild(document.createElement('span'))
+    messagesEl.appendChild(el)
+    scrollToBottom()
+    return el
+  }
+
+  // Interaction
+  async function sendMessage() {
+    const text = input.value.trim()
+    if (!text || sendBtn.disabled) return
+
+    input.value = ''
+    sendBtn.disabled = true
+    input.disabled = true
+
+    appendUserMessage(text)
+
+    // A single thinking indicator follows the conversation throughout the turn.
+    // We move it to the bottom every time it should be visible (after a segment
+    // completes, during tool calls) and only finally remove it on done/error.
+    let thinkingEl: HTMLElement | null = showThinking()
+
+    streamingMsgEl = null
+    streamingContent = ''
+
+    // Track ephemeral sales-workflow status pills by tool-call id so we can
+    // remove (or briefly flip to "Error") on the matching tool_call_finished.
+    const salesPills = new Map<string, HTMLElement>()
+
+    const ensureThinking = () => {
+      if (thinkingEl && thinkingEl.isConnected) {
+        messagesEl.appendChild(thinkingEl) // move to bottom
+      } else {
+        thinkingEl = showThinking()
+      }
+      scrollToBottom()
+    }
+    const hideThinking = () => {
+      if (thinkingEl && thinkingEl.isConnected) thinkingEl.remove()
+    }
+
+    try {
+      for await (const event of client.ask(text)) {
+        switch (event.event) {
+          case 'delta': {
+            const data = event.data as DeltaEvent
+            streamingContent += data.content
+            if (!streamingMsgEl) {
+              hideThinking()
+              streamingMsgEl = appendAssistantMessage(streamingContent)
+            } else {
+              setRenderedMarkdown(streamingMsgEl, streamingContent)
+              scrollToBottom()
+            }
+            break
+          }
+          case 'message_complete': {
+            // Finalize the current bubble with the server-confirmed content,
+            // then RESET so the next delta starts a fresh bubble. If a tool
+            // call or another LLM round follows, show "thinking" so the UI
+            // doesn't look frozen during the pause.
+            const data = event.data as MessageCompleteEvent
+            if (streamingMsgEl) setRenderedMarkdown(streamingMsgEl, data.content)
+            streamingMsgEl = null
+            streamingContent = ''
+            ensureThinking()
+            break
+          }
+          case 'tool_call_started': {
+            // Keep the thinking indicator visible during the tool call.
+            ensureThinking()
+            const tStart = event.data as ToolCallStartedEvent
+            if (isSalesWorkflowTool(tStart.name)) {
+              const pill = createElement('div', 'sb-sales-pill')
+              pill.textContent = SALES_TOOL_PILL_TEXT[tStart.name]
+              // Insert into the message stream container; placed before the
+              // thinking indicator so the pill sits above the next assistant
+              // bubble that will appear after the tool round-trip.
+              if (thinkingEl && thinkingEl.isConnected) {
+                messagesEl.insertBefore(pill, thinkingEl)
+              } else {
+                messagesEl.appendChild(pill)
+              }
+              salesPills.set(tStart.id, pill)
+              scrollToBottom()
+            }
+            break
+          }
+          case 'tool_call_finished': {
+            // Stay in "thinking" until the next delta (next LLM segment) starts.
+            ensureThinking()
+            const tEnd = event.data as ToolCallFinishedEvent
+            const pill = salesPills.get(tEnd.id)
+            if (pill) {
+              if (tEnd.ok === false) {
+                pill.textContent = 'Error'
+                pill.classList.add('sb-sales-pill-error')
+                salesPills.delete(tEnd.id)
+                setTimeout(() => {
+                  pill.remove()
+                }, 4000)
+              } else {
+                pill.remove()
+                salesPills.delete(tEnd.id)
+              }
+            }
+            break
+          }
+          case 'done': {
+            hideThinking()
+            break
+          }
+          case 'error': {
+            hideThinking()
+            appendErrorMessage(`Error: ${(event.data as { message: string }).message}`)
+            break
+          }
+        }
+      }
+      // Stream ended without an explicit done — safety net.
+      hideThinking()
+    } catch (err) {
+      hideThinking()
+      const msg = err instanceof SalesBotError ? err.message : 'Something went wrong. Please try again.'
+      appendErrorMessage(msg)
+    } finally {
+      sendBtn.disabled = false
+      input.disabled = false
+      input.focus()
+    }
+  }
+
+  // Event wiring
+  launcher.addEventListener('click', () => toggle())
+  closeBtn.addEventListener('click', () => close())
+  newChatBtn.addEventListener('click', () => void startNewChat())
+  sendBtn.addEventListener('click', () => { void sendMessage() })
+  input.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      void sendMessage()
+    }
+  })
+
+  // First-open hydration: either replay the prior conversation's transcript
+  // (after a page reload, when the SDK has a persisted conversationId) OR
+  // show the greeting (brand-new session). Runs at most once per widget
+  // instance — closing and reopening doesn't re-fetch.
+  let hydrated = false
+  async function hydrateOnce(): Promise<void> {
+    if (hydrated) return
+    hydrated = true
+
+    const existingConvId = client.getConversationId()
+    if (existingConvId) {
+      try {
+        const history = await client.loadHistory(existingConvId)
+        if (history.length === 0) {
+          // Conversation id was stored locally but the server has nothing
+          // for it (cleared DB in dev, expired, deleted, etc.). Clear the
+          // stale id and fall back to greeting so the widget isn't blank.
+          client.setConversationId(null)
+          await showGreetingIfConfigured()
+          return
+        }
+        for (const m of history) {
+          if (m.role === 'user') appendUserMessage(m.content)
+          else appendAssistantMessage(m.content)
+        }
+      } catch {
+        // Network / auth error fetching history — don't break the widget.
+        // User can still type a new message; any structural problem will
+        // surface on their first turn.
+      }
+      return
+    }
+
+    await showGreetingIfConfigured()
+  }
+
+  /**
+   * Reset to a fresh conversation. Server-side: ends the current
+   * conversation (soft-deleted, dropped from admin list, history fetch
+   * returns empty). Client-side: clears the persisted conversationId so
+   * the next message starts a new Conversation row, wipes message
+   * bubbles, allows the greeting to fire again on this same widget
+   * instance.
+   *
+   * Swallows network errors — the user has clicked "start new chat" and
+   * they shouldn't see a failure; their local state still resets and
+   * the next turn will surface any structural issue.
+   */
+  async function startNewChat(): Promise<void> {
+    try {
+      await client.endConversation()
+    } catch {
+      // already cleared local state inside endConversation on failure
+    }
+    // Wipe message bubbles + allow hydrateOnce to fire again.
+    while (messagesEl.firstChild) messagesEl.removeChild(messagesEl.firstChild)
+    streamingMsgEl = null
+    streamingContent = ''
+    hydrated = false
+    await hydrateOnce()
+  }
+
+  async function showGreetingIfConfigured(): Promise<void> {
+    try {
+      const cfg = await client.getBotConfig()
+      const greeting = (cfg.greetingMessage ?? '').trim()
+      if (greeting) appendAssistantMessage(greeting)
+    } catch {
+      // Bot config fetch failed (network, invalid key, etc.). Skip silently.
+    }
+  }
+
+  // Public API
+  function open() {
+    panel.classList.add('sb-panel--open')
+    input.focus()
+    void hydrateOnce()
+  }
+  function close() { panel.classList.remove('sb-panel--open') }
+  function toggle() { panel.classList.contains('sb-panel--open') ? close() : open() }
+  function destroy() { host.remove() }
+
+  return { open, close, toggle, destroy }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createElement(
+  tag: string,
+  className: string,
+  attrs: Record<string, string> = {},
+): HTMLElement {
+  const el = document.createElement(tag)
+  if (className) el.className = className
+  for (const [k, v] of Object.entries(attrs)) {
+    el.setAttribute(k, v)
+  }
+  return el
+}
+
+/**
+ * Map a WidgetTheme to `--sb-<kebab>` custom properties on the shadow host.
+ * camelCase → kebab-case so the keys read naturally in TS while landing as
+ * the documented CSS-var names. Number values stringify (useful for `z`).
+ */
+function applyTheme(host: HTMLElement, theme: WidgetTheme): void {
+  for (const [key, value] of Object.entries(theme)) {
+    if (value === undefined || value === null) continue
+    const cssName = '--sb-' + key.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase())
+    host.style.setProperty(cssName, String(value))
+  }
+}
+
+/**
+ * Set HTML content from a static compile-time SVG string.
+ * Only call this with string literals from this module — never user data.
+ */
+function setStaticSvgContent(el: HTMLElement, svgLiteral: string): void {
+  // eslint-disable-next-line -- intentional: static literal only, audited safe
+  el.innerHTML = svgLiteral
+}
+
+/**
+ * Set rendered markdown content.
+ * renderMarkdown() HTML-escapes all input before processing — safe against XSS.
+ */
+function setRenderedMarkdown(el: HTMLElement, markdownSource: string): void {
+  // eslint-disable-next-line -- intentional: source is HTML-escaped by renderMarkdown()
+  el.innerHTML = renderMarkdown(markdownSource)
+}
+
+// Static SVG icon literals (not user input)
+const NEW_CHAT_ICON_SVG =
+  `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 5v14"></path><path d="M5 12h14"></path></svg>`
+
+const CHAT_ICON_SVG =
+  `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"></path></svg>`
+
+const SEND_ICON_SVG =
+  `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><line x1="22" y1="2" x2="11" y2="13"></line><polygon points="22 2 15 22 11 13 2 9 22 2"></polygon></svg>`

package/tests/contract/wire-format.test.ts

@@ -0,0 +1,158 @@
+/**
+ * CONTRACT TESTS — asserts the SDK's TypeScript types match the backend's
+ * locked wire format from sub-project #1's sse-events.ts.
+ *
+ * These are compile-time + runtime shape assertions. Any mismatch here
+ * means the SDK and backend are out of sync.
+ */
+
+import { describe, it, expect } from 'vitest'
+import type {
+  SseEventName,
+  TurnStartedEvent,
+  DeltaEvent,
+  ToolCallStartedEvent,
+  ToolCallFinishedEvent,
+  MessageCompleteEvent,
+  UsageEventData,
+  DoneEvent,
+  ErrorEvent,
+  SalesBotEvent,
+  SalesBotErrorCode,
+} from '../../src/core/types'
+
+describe('Wire format contract (locked for SDK)', () => {
+  it('SseEventName covers exactly the documented events', () => {
+    // These are the locked event names from the backend.
+    // Additive changes (new events) are allowed; removals require a version bump.
+    const names: SseEventName[] = [
+      'turn_started',
+      'delta',
+      'tool_call_started',
+      'tool_call_finished',
+      'message_complete',
+      'usage',
+      'done',
+      'error',
+    ]
+    expect(names).toHaveLength(8)
+    names.forEach((n) => expect(typeof n).toBe('string'))
+  })
+
+  it('TurnStartedEvent has turnId, conversationId, endUserId', () => {
+    const e: TurnStartedEvent = {
+      turnId: 'turn-1',
+      conversationId: 'conv-1',
+      endUserId: 'eu-1',
+    }
+    expect(e).toMatchObject({
+      turnId: expect.any(String),
+      conversationId: expect.any(String),
+      endUserId: expect.any(String),
+    })
+  })
+
+  it('DeltaEvent has content', () => {
+    const e: DeltaEvent = { content: 'Hello' }
+    expect(e).toMatchObject({ content: expect.any(String) })
+  })
+
+  it('ToolCallStartedEvent has id, name, args', () => {
+    const e: ToolCallStartedEvent = { id: 'call-1', name: 'llms_txt__search', args: { q: 'hi' } }
+    expect(e).toMatchObject({
+      id: expect.any(String),
+      name: expect.any(String),
+      args: expect.any(Object),
+    })
+  })
+
+  it('ToolCallFinishedEvent has id, ok, optional result/error, durationMs', () => {
+    const success: ToolCallFinishedEvent = { id: 'c1', ok: true, result: { x: 1 }, durationMs: 42 }
+    expect(success).toMatchObject({ id: expect.any(String), ok: true, durationMs: expect.any(Number) })
+
+    const failure: ToolCallFinishedEvent = { id: 'c1', ok: false, error: 'boom', durationMs: 10 }
+    expect(failure).toMatchObject({ id: expect.any(String), ok: false, error: expect.any(String) })
+  })
+
+  it('MessageCompleteEvent has messageId, content, modelId, promptTokens, completionTokens', () => {
+    const e: MessageCompleteEvent = {
+      messageId: 'm1',
+      content: 'hi',
+      modelId: 'anthropic/claude-sonnet-4-6',
+      promptTokens: 10,
+      completionTokens: 5,
+    }
+    expect(e).toMatchObject({
+      messageId: expect.any(String),
+      content: expect.any(String),
+      modelId: expect.any(String),
+      promptTokens: expect.any(Number),
+      completionTokens: expect.any(Number),
+    })
+  })
+
+  it('UsageEventData has kind, quantity, costBasisCents', () => {
+    const kinds: UsageEventData['kind'][] = ['chat_completion', 'mcp_tool_call', 'dns_verification']
+    kinds.forEach((kind) => {
+      const e: UsageEventData = { kind, quantity: 1, costBasisCents: 0.5 }
+      expect(e).toMatchObject({ kind: expect.any(String), quantity: expect.any(Number), costBasisCents: expect.any(Number) })
+    })
+  })
+
+  it('DoneEvent has turnId', () => {
+    const e: DoneEvent = { turnId: 'turn-1' }
+    expect(e).toMatchObject({ turnId: expect.any(String) })
+  })
+
+  it('ErrorEvent has code, message, retryable; details optional', () => {
+    const min: ErrorEvent = { code: 'out_of_credits', message: 'no credits', retryable: false }
+    expect(min).toMatchObject({
+      code: expect.any(String),
+      message: expect.any(String),
+      retryable: expect.any(Boolean),
+    })
+
+    const full: ErrorEvent = {
+      code: 'rate_limited',
+      message: 'slow down',
+      retryable: true,
+      details: { retryAfterSeconds: 5 },
+    }
+    expect(full.details).toBeDefined()
+  })
+
+  it('SalesBotEvent is a discriminated union over all event types', () => {
+    // Runtime check: each union branch is a valid SalesBotEvent
+    const events: SalesBotEvent[] = [
+      { event: 'turn_started', data: { turnId: 't', conversationId: 'c', endUserId: 'e' } },
+      { event: 'delta', data: { content: 'hi' } },
+      { event: 'tool_call_started', data: { id: 'i', name: 'n', args: {} } },
+      { event: 'tool_call_finished', data: { id: 'i', ok: true, durationMs: 1 } },
+      { event: 'message_complete', data: { messageId: 'm', content: 'c', modelId: 'x', promptTokens: 1, completionTokens: 1 } },
+      { event: 'usage', data: { kind: 'chat_completion', quantity: 1, costBasisCents: 0 } },
+      { event: 'done', data: { turnId: 't' } },
+      { event: 'error', data: { code: 'internal', message: 'err', retryable: false } },
+    ]
+    expect(events).toHaveLength(8)
+  })
+
+  it('SalesBotErrorCode includes all backend codes plus SDK-only codes', () => {
+    const backendCodes: 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',
+    ]
+    const sdkCodes: SalesBotErrorCode[] = ['network_error', 'parse_error']
+    ;[...backendCodes, ...sdkCodes].forEach((c) => expect(typeof c).toBe('string'))
+  })
+})