@sales-bot-llm/sdk 0.2.0

package/tests/core/client.test.ts

@@ -0,0 +1,292 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { SalesBotClient } from '../../src/core/client'
+import { MemoryStorageAdapter } from '../../src/core/storage'
+import { SalesBotError } from '../../src/core/types'
+import type { SalesBotEvent } from '../../src/core/types'
+
+const EMBED_KEY = 'pk_live_testkey123'
+const BASE_URL = 'http://localhost:3000'
+
+function encodeSse(name: string, data: unknown): string {
+  return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`
+}
+
+function makeSseStream(...events: Array<[string, unknown]>): ReadableStream<Uint8Array> {
+  const raw = events.map(([name, data]) => encodeSse(name, data)).join('')
+  const encoder = new TextEncoder()
+  return new ReadableStream({
+    start(ctrl) {
+      ctrl.enqueue(encoder.encode(raw))
+      ctrl.close()
+    },
+  })
+}
+
+function mockFetchSSE(...events: Array<[string, unknown]>) {
+  const body = makeSseStream(...events)
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValueOnce(
+      new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } }),
+    ),
+  )
+}
+
+function mockFetchError(status: number, code: string, message: string, retryable = false) {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValueOnce(
+      new Response(JSON.stringify({ code, message, retryable }), {
+        status,
+        headers: { 'content-type': 'application/json' },
+      }),
+    ),
+  )
+}
+
+afterEach(() => vi.unstubAllGlobals())
+
+function makeClient() {
+  return new SalesBotClient({
+    embedKey: EMBED_KEY,
+    baseUrl: BASE_URL,
+    storage: new MemoryStorageAdapter(),
+  })
+}
+
+describe('SalesBotClient', () => {
+  describe('construction', () => {
+    it('creates a stable visitor token', () => {
+      const c = makeClient()
+      const t1 = c.getVisitorToken()
+      const t2 = c.getVisitorToken()
+      expect(t1).toBe(t2)
+      expect(t1).toMatch(/^[0-9a-f-]{36}$/i)
+    })
+
+    it('starts with null conversationId', () => {
+      const c = makeClient()
+      expect(c.getConversationId()).toBeNull()
+    })
+
+    it('hydrates conversationId from storage (simulates page refresh)', () => {
+      // Shared storage represents the browser's localStorage surviving a reload.
+      const storage = new MemoryStorageAdapter()
+
+      // First client picks up a conversation id via turn_started.
+      const first = new SalesBotClient({ embedKey: EMBED_KEY, baseUrl: BASE_URL, storage })
+      first.setConversationId('conv-restored')
+
+      // A second client constructed against the same storage (i.e. after refresh)
+      // must read the persisted conversation id.
+      const second = new SalesBotClient({ embedKey: EMBED_KEY, baseUrl: BASE_URL, storage })
+      expect(second.getConversationId()).toBe('conv-restored')
+    })
+
+    it('scopes persisted conversationId by embed key', () => {
+      const storage = new MemoryStorageAdapter()
+      new SalesBotClient({ embedKey: 'pk_live_a', baseUrl: BASE_URL, storage }).setConversationId('conv-A')
+      const b = new SalesBotClient({ embedKey: 'pk_live_b', baseUrl: BASE_URL, storage })
+      expect(b.getConversationId()).toBeNull()
+    })
+  })
+
+  describe('setConversationId / getConversationId', () => {
+    it('sets and gets conversation id', () => {
+      const c = makeClient()
+      c.setConversationId('conv-1')
+      expect(c.getConversationId()).toBe('conv-1')
+    })
+
+    it('can be cleared to null', () => {
+      const c = makeClient()
+      c.setConversationId('conv-1')
+      c.setConversationId(null)
+      expect(c.getConversationId()).toBeNull()
+    })
+
+    it('persists across client instances when set explicitly', () => {
+      const storage = new MemoryStorageAdapter()
+      new SalesBotClient({ embedKey: EMBED_KEY, baseUrl: BASE_URL, storage }).setConversationId('conv-x')
+      const fresh = new SalesBotClient({ embedKey: EMBED_KEY, baseUrl: BASE_URL, storage })
+      expect(fresh.getConversationId()).toBe('conv-x')
+    })
+
+    it('clearing with setConversationId(null) removes it from storage too', () => {
+      const storage = new MemoryStorageAdapter()
+      const c = new SalesBotClient({ embedKey: EMBED_KEY, baseUrl: BASE_URL, storage })
+      c.setConversationId('conv-x')
+      c.setConversationId(null)
+      const fresh = new SalesBotClient({ embedKey: EMBED_KEY, baseUrl: BASE_URL, storage })
+      expect(fresh.getConversationId()).toBeNull()
+    })
+  })
+
+  describe('identify', () => {
+    it('stores identify data for the next ask', async () => {
+      const c = makeClient()
+      c.identify({ externalId: 'user-1', email: 'a@b.com' })
+      mockFetchSSE(['done', { turnId: 't' }])
+      // Consume the stream
+      for await (const _ of c.ask('hello')) {/* empty */}
+      const [, init] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit]
+      const body = JSON.parse(init.body as string)
+      expect(body.identify).toEqual({ externalId: 'user-1', email: 'a@b.com' })
+    })
+  })
+
+  describe('ask', () => {
+    it('calls postTurn with the right body', async () => {
+      mockFetchSSE(['done', { turnId: 't' }])
+      const c = makeClient()
+      c.setConversationId('conv-42')
+      for await (const _ of c.ask('test message', { metadata: { url: 'https://x.com' } })) {/* empty */}
+      const [, init] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit]
+      const body = JSON.parse(init.body as string)
+      expect(body.message).toBe('test message')
+      expect(body.conversationId).toBe('conv-42')
+      expect(body.metadata).toEqual({ url: 'https://x.com' })
+      expect(body.visitorToken).toMatch(/^[0-9a-f-]{36}$/i)
+    })
+
+    it('yields events from the SSE stream', async () => {
+      const turnStarted = { turnId: 't-1', conversationId: 'c-1', endUserId: 'e-1' }
+      const delta = { content: 'Hello' }
+      const done = { turnId: 't-1' }
+      mockFetchSSE(
+        ['turn_started', turnStarted],
+        ['delta', delta],
+        ['done', done],
+      )
+      const c = makeClient()
+      const events: SalesBotEvent[] = []
+      for await (const event of c.ask('hi')) {
+        events.push(event)
+      }
+      expect(events).toHaveLength(3)
+      expect(events[0]).toEqual({ event: 'turn_started', data: turnStarted })
+      expect(events[1]).toEqual({ event: 'delta', data: delta })
+      expect(events[2]).toEqual({ event: 'done', data: done })
+    })
+
+    it('auto-updates conversationId from turn_started', async () => {
+      mockFetchSSE(
+        ['turn_started', { turnId: 't-1', conversationId: 'new-conv', endUserId: 'e-1' }],
+        ['done', { turnId: 't-1' }],
+      )
+      const c = makeClient()
+      for await (const _ of c.ask('hi')) {/* empty */}
+      expect(c.getConversationId()).toBe('new-conv')
+    })
+
+    it('emits events on the event bus simultaneously', async () => {
+      const received: SalesBotEvent[] = []
+      const c = makeClient()
+      c.on('delta', (data) => received.push({ event: 'delta', data }))
+      c.on('done', (data) => received.push({ event: 'done', data }))
+
+      mockFetchSSE(
+        ['delta', { content: 'a' }],
+        ['delta', { content: 'b' }],
+        ['done', { turnId: 't' }],
+      )
+
+      // Consume async iterable (which drives the bus)
+      for await (const _ of c.ask('hi')) {/* empty */}
+
+      expect(received).toHaveLength(3)
+      expect(received[0]).toEqual({ event: 'delta', data: { content: 'a' } })
+      expect(received[1]).toEqual({ event: 'delta', data: { content: 'b' } })
+      expect(received[2]).toEqual({ event: 'done', data: { turnId: 't' } })
+    })
+
+    it('throws SalesBotError on HTTP error', async () => {
+      mockFetchError(429, 'rate_limited', 'Too fast', true)
+      const c = makeClient()
+      await expect(async () => {
+        for await (const _ of c.ask('hi')) {/* empty */}
+      }).rejects.toMatchObject({ code: 'rate_limited' })
+    })
+
+    it('each ask uses a different idempotency key', async () => {
+      const c = makeClient()
+
+      function makeBody(turnId: string): ReadableStream<Uint8Array> {
+        const raw = encodeSse('done', { turnId })
+        const encoder = new TextEncoder()
+        return new ReadableStream({ start(ctrl) { ctrl.enqueue(encoder.encode(raw)); ctrl.close() } })
+      }
+
+      // Set up a mock that responds twice, tracking all calls
+      const mockFn = vi.fn()
+        .mockResolvedValueOnce(new Response(makeBody('t1'), { status: 200, headers: { 'content-type': 'text/event-stream' } }))
+        .mockResolvedValueOnce(new Response(makeBody('t2'), { status: 200, headers: { 'content-type': 'text/event-stream' } }))
+      vi.stubGlobal('fetch', mockFn)
+
+      for await (const _ of c.ask('first')) {/* empty */}
+      for await (const _ of c.ask('second')) {/* empty */}
+
+      const [, init1] = mockFn.mock.calls[0] as [string, RequestInit]
+      const [, init2] = mockFn.mock.calls[1] as [string, RequestInit]
+      const key1 = (init1.headers as Record<string, string>)['Idempotency-Key']
+      const key2 = (init2.headers as Record<string, string>)['Idempotency-Key']
+
+      expect(key1).toMatch(/^[0-9a-f-]{36}$/i)
+      expect(key2).toMatch(/^[0-9a-f-]{36}$/i)
+      expect(key1).not.toBe(key2)
+    })
+  })
+
+  describe('resume', () => {
+    it('calls getResumeStream with the turn id', async () => {
+      mockFetchSSE(['done', { turnId: 'existing-turn' }])
+      const c = makeClient()
+      for await (const _ of c.resume('existing-turn')) {/* empty */}
+      const [url] = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [string]
+      expect(url).toBe(`${BASE_URL}/api/chat/turns/existing-turn/stream`)
+    })
+
+    it('yields events from the resumed stream', async () => {
+      mockFetchSSE(
+        ['delta', { content: 'resumed' }],
+        ['done', { turnId: 'rt-1' }],
+      )
+      const c = makeClient()
+      const events: SalesBotEvent[] = []
+      for await (const e of c.resume('rt-1')) events.push(e)
+      expect(events).toHaveLength(2)
+    })
+  })
+
+  describe('on / off', () => {
+    it('on() returns an unsubscribe function', () => {
+      const c = makeClient()
+      const unsub = c.on('delta', () => {})
+      expect(typeof unsub).toBe('function')
+    })
+
+    it('unsubscribe stops receiving events', async () => {
+      const c = makeClient()
+      const calls: string[] = []
+      const unsub = c.on('delta', (data) => calls.push((data as { content: string }).content))
+      unsub()
+
+      mockFetchSSE(['delta', { content: 'x' }], ['done', { turnId: 't' }])
+      for await (const _ of c.ask('hi')) {/* empty */}
+      expect(calls).toHaveLength(0)
+    })
+
+    it('multiple handlers for same event all fire', async () => {
+      const c = makeClient()
+      const a: string[] = []
+      const b: string[] = []
+      c.on('delta', (d) => a.push((d as { content: string }).content))
+      c.on('delta', (d) => b.push((d as { content: string }).content))
+
+      mockFetchSSE(['delta', { content: 'hi' }], ['done', { turnId: 't' }])
+      for await (const _ of c.ask('hello')) {/* empty */}
+      expect(a).toEqual(['hi'])
+      expect(b).toEqual(['hi'])
+    })
+  })
+})

package/tests/core/conversation.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest'
+import { MemoryStorageAdapter } from '../../src/core/storage'
+import {
+  loadConversationId,
+  saveConversationId,
+  CONVERSATION_ID_KEY_PREFIX,
+} from '../../src/core/conversation'
+
+describe('conversation id persistence', () => {
+  it('returns null when no conversation is stored', () => {
+    const storage = new MemoryStorageAdapter()
+    expect(loadConversationId('pk_live_x', storage)).toBeNull()
+  })
+
+  it('round-trips a conversation id through save/load', () => {
+    const storage = new MemoryStorageAdapter()
+    saveConversationId('pk_live_x', 'conv-123', storage)
+    expect(loadConversationId('pk_live_x', storage)).toBe('conv-123')
+  })
+
+  it('saveConversationId(null) clears the stored id', () => {
+    const storage = new MemoryStorageAdapter()
+    saveConversationId('pk_live_x', 'conv-123', storage)
+    saveConversationId('pk_live_x', null, storage)
+    expect(loadConversationId('pk_live_x', storage)).toBeNull()
+  })
+
+  it('scopes by embed key so multiple bots on the same browser do not collide', () => {
+    const storage = new MemoryStorageAdapter()
+    saveConversationId('pk_live_a', 'conv-A', storage)
+    saveConversationId('pk_live_b', 'conv-B', storage)
+    expect(loadConversationId('pk_live_a', storage)).toBe('conv-A')
+    expect(loadConversationId('pk_live_b', storage)).toBe('conv-B')
+  })
+
+  it('uses the documented key prefix', () => {
+    const storage = new MemoryStorageAdapter()
+    saveConversationId('pk_live_x', 'conv-1', storage)
+    expect(storage.getItem(`${CONVERSATION_ID_KEY_PREFIX}pk_live_x`)).toBe('conv-1')
+  })
+})

package/tests/core/sse-parser.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest'
+import { parseSseStream } from '../../src/core/sse-parser'
+import { SalesBotError } from '../../src/core/types'
+import type { SalesBotEvent } from '../../src/core/types'
+
+/** Helper: create a ReadableStream<Uint8Array> from a raw SSE string */
+function makeStream(raw: string): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode(raw))
+      controller.close()
+    },
+  })
+}
+
+/** Helper: create a stream split into multiple chunks */
+function makeChunkedStream(chunks: string[]): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) {
+        controller.enqueue(encoder.encode(chunk))
+      }
+      controller.close()
+    },
+  })
+}
+
+async function collectEvents(stream: ReadableStream<Uint8Array>): Promise<SalesBotEvent[]> {
+  const events: SalesBotEvent[] = []
+  for await (const event of parseSseStream(stream)) {
+    events.push(event)
+  }
+  return events
+}
+
+describe('parseSseStream', () => {
+  it('parses a single turn_started frame', async () => {
+    const data = { turnId: 't-1', conversationId: 'c-1', endUserId: 'e-1' }
+    const raw = `event: turn_started\ndata: ${JSON.stringify(data)}\n\n`
+    const events = await collectEvents(makeStream(raw))
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({ event: 'turn_started', data })
+  })
+
+  it('parses a delta frame', async () => {
+    const raw = `event: delta\ndata: {"content":"Hello"}\n\n`
+    const events = await collectEvents(makeStream(raw))
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({ event: 'delta', data: { content: 'Hello' } })
+  })
+
+  it('parses multiple frames in one chunk', async () => {
+    const raw =
+      `event: turn_started\ndata: {"turnId":"t","conversationId":"c","endUserId":"e"}\n\n` +
+      `event: delta\ndata: {"content":"a"}\n\n` +
+      `event: done\ndata: {"turnId":"t"}\n\n`
+    const events = await collectEvents(makeStream(raw))
+    expect(events).toHaveLength(3)
+    expect(events[0]!.event).toBe('turn_started')
+    expect(events[1]!.event).toBe('delta')
+    expect(events[2]!.event).toBe('done')
+  })
+
+  it('handles frames split across chunk boundaries', async () => {
+    const frame = `event: delta\ndata: {"content":"hi"}\n\n`
+    // Split the frame at an arbitrary byte boundary
+    const mid = Math.floor(frame.length / 2)
+    const chunks = [frame.slice(0, mid), frame.slice(mid)]
+    const events = await collectEvents(makeChunkedStream(chunks))
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({ event: 'delta', data: { content: 'hi' } })
+  })
+
+  it('handles two frames split across three chunks', async () => {
+    const a = `event: delta\ndata: {"content":"a"}\n\n`
+    const b = `event: delta\ndata: {"content":"b"}\n\n`
+    const combined = a + b
+    // split so the boundary falls in the middle of the second frame
+    const chunks = [combined.slice(0, a.length + 5), combined.slice(a.length + 5)]
+    const events = await collectEvents(makeChunkedStream(chunks))
+    expect(events).toHaveLength(2)
+    expect((events[0]!.data as { content: string }).content).toBe('a')
+    expect((events[1]!.data as { content: string }).content).toBe('b')
+  })
+
+  it('parses an error event', async () => {
+    const raw = `event: error\ndata: {"code":"rate_limited","message":"slow down","retryable":true}\n\n`
+    const events = await collectEvents(makeStream(raw))
+    expect(events).toHaveLength(1)
+    expect(events[0]).toEqual({
+      event: 'error',
+      data: { code: 'rate_limited', message: 'slow down', retryable: true },
+    })
+  })
+
+  it('parses all 8 event types', async () => {
+    const frames = [
+      `event: turn_started\ndata: {"turnId":"t","conversationId":"c","endUserId":"e"}\n\n`,
+      `event: delta\ndata: {"content":"x"}\n\n`,
+      `event: tool_call_started\ndata: {"id":"i","name":"n","args":{}}\n\n`,
+      `event: tool_call_finished\ndata: {"id":"i","ok":true,"durationMs":1}\n\n`,
+      `event: message_complete\ndata: {"messageId":"m","content":"c","modelId":"x","promptTokens":1,"completionTokens":1}\n\n`,
+      `event: usage\ndata: {"kind":"chat_completion","quantity":1,"costBasisCents":0}\n\n`,
+      `event: done\ndata: {"turnId":"t"}\n\n`,
+      `event: error\ndata: {"code":"internal","message":"e","retryable":false}\n\n`,
+    ]
+    const events = await collectEvents(makeStream(frames.join('')))
+    expect(events).toHaveLength(8)
+    const eventNames = events.map((e) => e.event)
+    expect(eventNames).toEqual([
+      'turn_started', 'delta', 'tool_call_started', 'tool_call_finished',
+      'message_complete', 'usage', 'done', 'error',
+    ])
+  })
+
+  it('returns no events for an empty stream', async () => {
+    const events = await collectEvents(makeStream(''))
+    expect(events).toHaveLength(0)
+  })
+
+  it('skips frames with no event line', async () => {
+    // A frame with only data (comment-only or ping): should be skipped
+    const raw = `data: {"content":"orphan"}\n\n`
+    const events = await collectEvents(makeStream(raw))
+    expect(events).toHaveLength(0)
+  })
+
+  it('throws SalesBotError with code parse_error on malformed JSON', async () => {
+    const raw = `event: delta\ndata: {not valid json}\n\n`
+    await expect(collectEvents(makeStream(raw))).rejects.toBeInstanceOf(SalesBotError)
+    await expect(collectEvents(makeStream(raw))).rejects.toMatchObject({ code: 'parse_error' })
+  })
+
+  it('handles unicode content correctly', async () => {
+    const content = 'こんにちは 🎉'
+    const raw = `event: delta\ndata: ${JSON.stringify({ content })}\n\n`
+    const events = await collectEvents(makeStream(raw))
+    expect((events[0]!.data as { content: string }).content).toBe(content)
+  })
+})

package/tests/core/storage.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { LocalStorageAdapter, MemoryStorageAdapter } from '../../src/core/storage'
+
+describe('MemoryStorageAdapter', () => {
+  it('returns null for missing keys', () => {
+    const s = new MemoryStorageAdapter()
+    expect(s.getItem('missing')).toBeNull()
+  })
+
+  it('stores and retrieves values', () => {
+    const s = new MemoryStorageAdapter()
+    s.setItem('key', 'value')
+    expect(s.getItem('key')).toBe('value')
+  })
+
+  it('overwrites existing values', () => {
+    const s = new MemoryStorageAdapter()
+    s.setItem('key', 'a')
+    s.setItem('key', 'b')
+    expect(s.getItem('key')).toBe('b')
+  })
+
+  it('removes items', () => {
+    const s = new MemoryStorageAdapter()
+    s.setItem('key', 'value')
+    s.removeItem('key')
+    expect(s.getItem('key')).toBeNull()
+  })
+
+  it('does not throw on removeItem for non-existent key', () => {
+    const s = new MemoryStorageAdapter()
+    expect(() => s.removeItem('ghost')).not.toThrow()
+  })
+
+  it('isolates data between instances', () => {
+    const a = new MemoryStorageAdapter()
+    const b = new MemoryStorageAdapter()
+    a.setItem('key', 'from-a')
+    expect(b.getItem('key')).toBeNull()
+  })
+})
+
+describe('LocalStorageAdapter', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('returns null for missing keys', () => {
+    const s = new LocalStorageAdapter()
+    expect(s.getItem('missing')).toBeNull()
+  })
+
+  it('stores and retrieves values', () => {
+    const s = new LocalStorageAdapter()
+    s.setItem('key', 'value')
+    expect(s.getItem('key')).toBe('value')
+  })
+
+  it('overwrites existing values', () => {
+    const s = new LocalStorageAdapter()
+    s.setItem('key', 'a')
+    s.setItem('key', 'b')
+    expect(s.getItem('key')).toBe('b')
+  })
+
+  it('removes items', () => {
+    const s = new LocalStorageAdapter()
+    s.setItem('key', 'value')
+    s.removeItem('key')
+    expect(s.getItem('key')).toBeNull()
+  })
+
+  it('shares data with window.localStorage', () => {
+    const s = new LocalStorageAdapter()
+    s.setItem('shared', 'yes')
+    expect(localStorage.getItem('shared')).toBe('yes')
+  })
+})