@sales-bot-llm/sdk 0.2.0

package/src/core/storage.ts

@@ -0,0 +1,72 @@
+import type { StorageAdapter } from './types'
+
+/**
+ * In-memory storage adapter — used as a fallback when localStorage is
+ * unavailable (SSR, Node, private browsing quota errors).
+ */
+export class MemoryStorageAdapter implements StorageAdapter {
+  private readonly store = new Map<string, string>()
+
+  getItem(key: string): string | null {
+    return this.store.get(key) ?? null
+  }
+
+  setItem(key: string, value: string): void {
+    this.store.set(key, value)
+  }
+
+  removeItem(key: string): void {
+    this.store.delete(key)
+  }
+}
+
+/**
+ * localStorage-backed adapter.
+ * Throws at construction if window.localStorage is unavailable.
+ * Callers should catch and fall back to MemoryStorageAdapter.
+ */
+export class LocalStorageAdapter implements StorageAdapter {
+  private readonly ls: Storage
+
+  constructor() {
+    if (typeof window === 'undefined' || !window.localStorage) {
+      throw new Error('localStorage is not available in this environment')
+    }
+    this.ls = window.localStorage
+  }
+
+  getItem(key: string): string | null {
+    return this.ls.getItem(key)
+  }
+
+  setItem(key: string, value: string): void {
+    this.ls.setItem(key, value)
+  }
+
+  removeItem(key: string): void {
+    this.ls.removeItem(key)
+  }
+}
+
+/**
+ * Creates the best available storage adapter.
+ * Prefers localStorage; falls back silently to MemoryStorageAdapter.
+ */
+export function createDefaultStorage(): StorageAdapter {
+  try {
+    const adapter = new LocalStorageAdapter()
+    // Probe for quota errors in private browsing
+    const probe = '__sb_probe__'
+    adapter.setItem(probe, '1')
+    adapter.removeItem(probe)
+    return adapter
+  } catch {
+    if (typeof console !== 'undefined') {
+      console.warn(
+        '[SalesBot] localStorage unavailable — falling back to in-memory storage. ' +
+          'Visitor token will not persist across page reloads.',
+      )
+    }
+    return new MemoryStorageAdapter()
+  }
+}

package/src/core/transport.ts

@@ -0,0 +1,271 @@
+import { SalesBotError } from './types'
+import type { PostTurnInput, SalesBotErrorCode } from './types'
+
+export interface TransportOptions {
+  embedKey: string
+  baseUrl: string
+  customHeaders?: Record<string, string>
+}
+
+/**
+ * POST /api/chat/turns — starts a new agent turn.
+ * Returns the raw SSE ReadableStream on success.
+ * Throws SalesBotError on HTTP errors or network failures.
+ */
+export async function postTurn(
+  input: PostTurnInput,
+  opts: TransportOptions,
+): Promise<ReadableStream<Uint8Array>> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${opts.embedKey}`,
+    'Content-Type': 'application/json',
+    Accept: 'text/event-stream',
+    'Idempotency-Key': crypto.randomUUID(),
+    ...opts.customHeaders,
+  }
+
+  let response: Response
+  try {
+    response = await fetch(`${opts.baseUrl}/api/chat/turns`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(input),
+    })
+  } catch (err) {
+    throw new SalesBotError({
+      code: 'network_error',
+      message: err instanceof Error ? err.message : 'Network request failed',
+      retryable: true,
+    })
+  }
+
+  if (!response.ok) {
+    await throwHttpError(response)
+  }
+
+  if (!response.body) {
+    throw new SalesBotError({ code: 'internal', message: 'Response body is null', retryable: false })
+  }
+
+  return response.body
+}
+
+/**
+ * Public bot config keyed by the embed key. Read once on widget mount;
+ * shape is what GET /api/chat/bots/me returns.
+ */
+export interface PublicBotConfig {
+  name: string
+  greetingMessage: string | null
+}
+
+/**
+ * GET /api/chat/bots/me — returns the public-safe config (name, greeting)
+ * for the bot this embed key authenticates as. Used by the widget to render
+ * the welcome message on first open.
+ */
+export async function getBotConfig(opts: TransportOptions): Promise<PublicBotConfig> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${opts.embedKey}`,
+    Accept: 'application/json',
+    ...opts.customHeaders,
+  }
+
+  let response: Response
+  try {
+    response = await fetch(`${opts.baseUrl}/api/chat/bots/me`, { method: 'GET', headers })
+  } catch (err) {
+    throw new SalesBotError({
+      code: 'network_error',
+      message: err instanceof Error ? err.message : 'Network request failed',
+      retryable: true,
+    })
+  }
+
+  if (!response.ok) {
+    await throwHttpError(response)
+  }
+
+  return (await response.json()) as PublicBotConfig
+}
+
+/**
+ * Persisted message as returned by GET /api/chat/conversations/:id/messages.
+ * Tool-call rows are filtered server-side — the SDK only ever sees user +
+ * assistant turns. createdAt is an ISO 8601 string.
+ */
+export interface HistoryMessage {
+  id: string
+  role: 'user' | 'assistant'
+  content: string
+  createdAt: string
+}
+
+/**
+ * GET /api/chat/conversations/:id/messages — fetches the persisted transcript
+ * for a conversation scoped to (embedKey's bot, visitorToken's end-user).
+ * The backend silently returns { messages: [] } for unknown visitors or
+ * stale conversation ids so a fresh widget never errors on a missing
+ * client-side persisted id.
+ */
+export async function getConversationHistory(
+  conversationId: string,
+  visitorToken: string,
+  opts: TransportOptions,
+): Promise<HistoryMessage[]> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${opts.embedKey}`,
+    Accept: 'application/json',
+    ...opts.customHeaders,
+  }
+  const url = `${opts.baseUrl}/api/chat/conversations/${encodeURIComponent(
+    conversationId,
+  )}/messages?visitorToken=${encodeURIComponent(visitorToken)}`
+
+  let response: Response
+  try {
+    response = await fetch(url, { method: 'GET', headers })
+  } catch (err) {
+    throw new SalesBotError({
+      code: 'network_error',
+      message: err instanceof Error ? err.message : 'Network request failed',
+      retryable: true,
+    })
+  }
+
+  if (!response.ok) {
+    await throwHttpError(response)
+  }
+
+  const body = (await response.json()) as { messages: HistoryMessage[] }
+  return body.messages ?? []
+}
+
+/**
+ * POST /api/chat/conversations/:id/end — mark the conversation as ended.
+ * Server soft-deletes the row; future history fetches return empty. The
+ * SDK clears its persisted conversationId after a successful call. The
+ * server is idempotent — already-ended conversations return ok:true.
+ */
+export async function postEndConversation(
+  conversationId: string,
+  visitorToken: string,
+  opts: TransportOptions,
+): Promise<void> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${opts.embedKey}`,
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    ...opts.customHeaders,
+  }
+  let response: Response
+  try {
+    response = await fetch(
+      `${opts.baseUrl}/api/chat/conversations/${encodeURIComponent(conversationId)}/end`,
+      { method: 'POST', headers, body: JSON.stringify({ visitorToken }) },
+    )
+  } catch (err) {
+    throw new SalesBotError({
+      code: 'network_error',
+      message: err instanceof Error ? err.message : 'Network request failed',
+      retryable: true,
+    })
+  }
+  if (!response.ok) await throwHttpError(response)
+}
+
+/**
+ * GET /api/chat/turns/:turnId/stream — re-attaches to an in-flight turn.
+ * Returns the raw SSE ReadableStream on success.
+ */
+export async function getResumeStream(
+  turnId: string,
+  opts: TransportOptions,
+): Promise<ReadableStream<Uint8Array>> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${opts.embedKey}`,
+    Accept: 'text/event-stream',
+    ...opts.customHeaders,
+  }
+
+  let response: Response
+  try {
+    response = await fetch(`${opts.baseUrl}/api/chat/turns/${turnId}/stream`, {
+      method: 'GET',
+      headers,
+    })
+  } catch (err) {
+    throw new SalesBotError({
+      code: 'network_error',
+      message: err instanceof Error ? err.message : 'Network request failed',
+      retryable: true,
+    })
+  }
+
+  if (!response.ok) {
+    await throwHttpError(response)
+  }
+
+  if (!response.body) {
+    throw new SalesBotError({ code: 'internal', message: 'Response body is null', retryable: false })
+  }
+
+  return response.body
+}
+
+// ---------------------------------------------------------------------------
+// Error mapping
+// ---------------------------------------------------------------------------
+
+async function throwHttpError(response: Response): Promise<never> {
+  let body: { code?: string; message?: string; retryable?: boolean; details?: Record<string, unknown> } = {}
+
+  try {
+    const contentType = response.headers.get('content-type') ?? ''
+    if (contentType.includes('application/json')) {
+      body = (await response.json()) as typeof body
+    }
+  } catch {
+    // ignore parse errors — fall through to status-based mapping
+  }
+
+  // Prefer the code from the response body; fall back to status-based mapping
+  const code: SalesBotErrorCode = isValidErrorCode(body.code)
+    ? body.code
+    : statusToCode(response.status)
+
+  throw new SalesBotError({
+    code,
+    message: body.message ?? response.statusText,
+    retryable: body.retryable ?? isRetryableStatus(response.status),
+    details: body.details,
+  })
+}
+
+const VALID_CODES = new Set<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', 'parse_error',
+])
+
+function isValidErrorCode(code: unknown): code is SalesBotErrorCode {
+  return typeof code === 'string' && VALID_CODES.has(code as SalesBotErrorCode)
+}
+
+function statusToCode(status: number): SalesBotErrorCode {
+  switch (status) {
+    case 400: return 'bad_request'
+    case 401: return 'unauthorized'
+    case 402: return 'out_of_credits'
+    case 403: return 'forbidden'
+    case 404: return 'not_found'
+    case 409: return 'conflict'
+    case 422: return 'unprocessable_entity'
+    case 429: return 'rate_limited'
+    default:  return 'internal'
+  }
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500
+}

package/src/core/types.ts

@@ -0,0 +1,314 @@
+/**
+ * Core wire-format types for the Sales Bot SDK.
+ *
+ * These interfaces are kept verbatim-compatible with the backend's
+ * sse-events.ts (sub-project #1). Any change here is a breaking change
+ * to the wire format and must be coordinated with the backend team.
+ */
+
+// ---------------------------------------------------------------------------
+// SSE event names (locked wire format)
+// ---------------------------------------------------------------------------
+
+export type SseEventName =
+  | 'turn_started'
+  | 'delta'
+  | 'tool_call_started'
+  | 'tool_call_finished'
+  | 'message_complete'
+  | 'usage'
+  | 'done'
+  | 'error'
+
+// ---------------------------------------------------------------------------
+// SSE event payload types (verbatim from backend sse-events.ts)
+// ---------------------------------------------------------------------------
+
+export interface TurnStartedEvent {
+  turnId: string
+  conversationId: string
+  endUserId: string
+}
+
+export interface DeltaEvent {
+  content: string
+}
+
+export interface ToolCallStartedEvent {
+  id: string
+  name: string
+  args: unknown
+}
+
+export interface ToolCallFinishedEvent {
+  id: string
+  ok: boolean
+  result?: unknown
+  error?: string
+  durationMs: number
+}
+
+export interface MessageCompleteEvent {
+  messageId: string
+  content: string
+  modelId: string
+  promptTokens: number
+  completionTokens: number
+}
+
+export interface UsageEventData {
+  kind: 'chat_completion' | 'mcp_tool_call' | 'dns_verification'
+  quantity: number
+  costBasisCents: number
+}
+
+export interface DoneEvent {
+  turnId: string
+}
+
+export interface ErrorEvent {
+  code: string
+  message: string
+  retryable: boolean
+  details?: Record<string, unknown>
+}
+
+// ---------------------------------------------------------------------------
+// Discriminated union over all SSE events
+// ---------------------------------------------------------------------------
+
+export type SalesBotEvent =
+  | { event: 'turn_started'; data: TurnStartedEvent }
+  | { event: 'delta'; data: DeltaEvent }
+  | { event: 'tool_call_started'; data: ToolCallStartedEvent }
+  | { event: 'tool_call_finished'; data: ToolCallFinishedEvent }
+  | { event: 'message_complete'; data: MessageCompleteEvent }
+  | { event: 'usage'; data: UsageEventData }
+  | { event: 'done'; data: DoneEvent }
+  | { event: 'error'; data: ErrorEvent }
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+/** All error codes the SDK may produce — backend codes + SDK-only codes. */
+export type SalesBotErrorCode =
+  // Backend error codes
+  | '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'
+  // SDK-only codes
+  | 'network_error'
+  | 'parse_error'
+
+export class SalesBotError extends Error {
+  readonly code: SalesBotErrorCode
+  readonly retryable: boolean
+  readonly details: Record<string, unknown> | undefined
+
+  constructor(opts: {
+    code: SalesBotErrorCode
+    message: string
+    retryable?: boolean
+    details?: Record<string, unknown>
+  }) {
+    super(opts.message)
+    this.name = 'SalesBotError'
+    this.code = opts.code
+    this.retryable = opts.retryable ?? false
+    this.details = opts.details !== undefined ? opts.details : undefined
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Client input types
+// ---------------------------------------------------------------------------
+
+export interface IdentifyInput {
+  externalId?: string
+  email?: string
+  name?: string
+  traits?: Record<string, unknown>
+}
+
+export interface AskOptions {
+  conversationId?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface PostTurnInput {
+  visitorToken: string
+  message: string
+  identify?: IdentifyInput
+  conversationId?: string
+  metadata?: Record<string, unknown>
+}
+
+// ---------------------------------------------------------------------------
+// Storage adapter
+// ---------------------------------------------------------------------------
+
+export interface StorageAdapter {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+}
+
+// ---------------------------------------------------------------------------
+// Client options
+// ---------------------------------------------------------------------------
+
+export interface SalesBotClientOptions {
+  /** The embed key from the bot config — format: pk_live_<32 chars> */
+  embedKey: string
+  /** Backend base URL. Defaults to 'http://localhost:3000' */
+  baseUrl?: string
+  /** Custom storage adapter. Defaults to localStorage with MemoryStorage fallback */
+  storage?: StorageAdapter
+  /** Extra headers merged into every request (e.g. { Origin: 'https://...' } for Node) */
+  customHeaders?: Record<string, string>
+}
+
+// ---------------------------------------------------------------------------
+// Message (used by framework adapters)
+// ---------------------------------------------------------------------------
+
+export interface Message {
+  id: string
+  role: 'user' | 'assistant'
+  content: string
+  /** True while the assistant is still streaming this message */
+  streaming?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Unsubscribe function returned by on()
+// ---------------------------------------------------------------------------
+
+export type Unsubscribe = () => void
+
+// ---------------------------------------------------------------------------
+// Widget options
+// ---------------------------------------------------------------------------
+
+/**
+ * Typed CSS-variable theme. Every field maps to a `--sb-<kebab-case>` custom
+ * property set on the widget's shadow host. Pass any subset; omitted keys
+ * inherit the default. For anything not exposed here, use `customCss`.
+ */
+export interface WidgetTheme {
+  // ─── Colors ─────────────────────────────────────────────────────────────
+  primary?: string
+  primaryHover?: string
+  /** Text color used on top of `primary` surfaces (header, send button, user bubble). Default: white. */
+  primaryText?: string
+  text?: string
+  textLight?: string
+  bg?: string
+  bgUser?: string
+  bgAssistant?: string
+  bgError?: string
+  textError?: string
+  border?: string
+  focusRing?: string
+
+  // ─── Layout & sizing ────────────────────────────────────────────────────
+  /** Outer panel border-radius. */
+  radius?: string
+  /** Message bubble border-radius. */
+  messageRadius?: string
+  /** Input pill border-radius. */
+  inputRadius?: string
+  z?: string | number
+  /** Launcher button diameter. */
+  launcherSize?: string
+  /** Panel width when open. */
+  panelWidth?: string
+  /** Panel height when open. */
+  panelHeight?: string
+  /** Panel max-height on small screens. */
+  panelMaxHeight?: string
+  /** Distance between launcher and viewport bottom edge. */
+  bottomOffset?: string
+  /** Distance between launcher and viewport left/right edge. */
+  sideOffset?: string
+  /** Vertical gap between launcher and the open panel. */
+  panelGap?: string
+  /** Send-button diameter. */
+  sendSize?: string
+
+  // ─── Typography ─────────────────────────────────────────────────────────
+  fontFamily?: string
+  /** Base font size used by message bubbles and input. */
+  fontSize?: string
+  fontSizeHeader?: string
+  fontSizeSmall?: string
+
+  // ─── Effects ────────────────────────────────────────────────────────────
+  shadow?: string
+  /** CSS transition shorthand used by buttons and hover states. */
+  transition?: string
+}
+
+export interface WidgetOptions extends SalesBotClientOptions {
+  container?: HTMLElement
+  position?: 'bottom-right' | 'bottom-left'
+  title?: string
+  placeholder?: string
+  /**
+   * Typed CSS-variable overrides. Granular control of colors, sizing,
+   * typography, and effects without leaving the shadow DOM.
+   */
+  theme?: WidgetTheme
+  /**
+   * Escape hatch: raw CSS injected into the shadow root AFTER the built-in
+   * styles. Overrides anything by selector (e.g. `.sb-launcher { ... }`).
+   * Use sparingly — class names are not a stable API.
+   */
+  customCss?: string
+  /** @deprecated Use `theme.primary` instead. */
+  primaryColor?: string
+}
+
+export interface WidgetInstance {
+  open(): void
+  close(): void
+  toggle(): void
+  destroy(): void
+}
+
+// ---------------------------------------------------------------------------
+// Sales-workflow tool name discriminators
+// ---------------------------------------------------------------------------
+//
+// The backend's SalesWorkflowDispatcher registers these tools with the LLM
+// alongside MCP tools. They surface to the SDK via standard `tool_call_started`
+// / `tool_call_finished` events with the names below. Consumers can narrow on
+// these names via `isSalesWorkflowTool` for typed handling.
+
+/** All sales-workflow tool names. Order is intentional (set_field/get_current
+ *  first, quotes after). */
+export const SALES_WORKFLOW_TOOL_NAMES = [
+  'project_brief__set_field',
+  'project_brief__get_current',
+  'quotes__generate',
+  'quotes__send_as_pdf',
+  'quotes__send_as_proposal',
+] as const
+
+export type SalesWorkflowToolName = (typeof SALES_WORKFLOW_TOOL_NAMES)[number]
+
+/** Type guard for narrowing tool-call event names to SalesWorkflowToolName. */
+export function isSalesWorkflowTool(name: string): name is SalesWorkflowToolName {
+  return (SALES_WORKFLOW_TOOL_NAMES as readonly string[]).includes(name)
+}

package/src/core/visitor.ts

@@ -0,0 +1,21 @@
+import type { StorageAdapter } from './types'
+
+export const VISITOR_TOKEN_KEY_PREFIX = 'salesbot:visitor:'
+
+/**
+ * Returns the persisted visitor token for a given embed key,
+ * or generates and persists a new UUID if none exists.
+ *
+ * The token is a stable identifier for this browser+bot combination,
+ * stored in the provided storage adapter under:
+ *   salesbot:visitor:<embedKey>
+ */
+export function getOrCreateVisitorToken(embedKey: string, storage: StorageAdapter): string {
+  const key = `${VISITOR_TOKEN_KEY_PREFIX}${embedKey}`
+  const existing = storage.getItem(key)
+  if (existing !== null) return existing
+
+  const token = crypto.randomUUID()
+  storage.setItem(key, token)
+  return token
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export { useSalesBot } from './use-sales-bot'
+export type { UseSalesBotOptions, UseSalesBotResult } from './use-sales-bot'