@csntgao/uni-base 0.1.0

package/packages/core/tests/customer-support-client.test.ts

@@ -0,0 +1,576 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  CustomerSupportClient,
+  type CustomerSupportMessage,
+  type CustomerSupportSession,
+  type CustomerSupportTransport,
+} from '../src'
+import { FakeWebSocket } from './fake-websocket'
+
+const session: CustomerSupportSession = {
+  id: 'support-1',
+  sessionNo: 'CS-1',
+  title: '企业服务顾问',
+  status: 'active',
+  statusText: '服务中',
+  primaryAgent: null,
+  lastMessage: '您好，我是人工顾问。',
+  unreadCount: 0,
+  openedAt: '2026-08-18T08:00:00.000Z',
+  updatedAt: '2026-08-18T08:00:00.000Z',
+  version: '1',
+}
+
+const history: CustomerSupportMessage[] = [
+  {
+    id: 'support-message-1',
+    sessionId: 'support-1',
+    sequence: '1',
+    clientMessageId: '',
+    senderType: 'agent',
+    senderName: '王悦',
+    content: '您好，我是人工顾问。',
+    createdAt: '2026-08-18T08:00:00.000Z',
+  },
+]
+
+function createTransport(): CustomerSupportTransport {
+  return {
+    getAccessToken: vi.fn(async () => 'customer.support.jwt'),
+    listSessions: vi.fn(async () => [session]),
+    createSession: vi.fn(async () => ({ session })),
+    listMessages: vi.fn(async () => ({
+      messages: history,
+      latestSequence: '1',
+      sessionVersion: '1',
+    })),
+    sendMessage: vi.fn(async (_sessionId, clientMessageId, content) => ({
+      id: 'support-message-2',
+      sessionId: 'support-1',
+      sequence: '2',
+      clientMessageId,
+      senderType: 'customer' as const,
+      senderName: '',
+      content,
+      createdAt: '2026-08-18T08:01:00.000Z',
+    })),
+    markRead: vi.fn(async () => undefined),
+  }
+}
+
+function deferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve
+    reject = promiseReject
+  })
+  return { promise, resolve, reject }
+}
+
+describe('CustomerSupportClient', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('loads the current support session and authenticates the dedicated realtime channel', async () => {
+    const sockets: FakeWebSocket[] = []
+    const transport = createTransport()
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      requestIdFactory: () => 'b95e15b8-55df-4d84-9fbe-c00dc45ae3a7',
+      minimumHeartbeatMs: 1,
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+
+    await client.start()
+    expect(client.session?.id).toBe('support-1')
+    expect(client.messages).toEqual(history)
+    expect(transport.markRead).toHaveBeenCalledWith('support-1', '1')
+    sockets[0]?.open()
+    await Promise.resolve()
+    sockets[0]?.receive({
+      type: 'realtime_ready',
+      channels: { customer_support: { available: true } },
+      heartbeat_interval_seconds: 25,
+    })
+
+    expect(sockets[0]?.sent.map((frame) => JSON.parse(frame))).toEqual([
+      {
+        type: 'authenticate',
+        protocol_version: 1,
+        access_token: 'customer.support.jwt',
+        requested_channels: ['customer_support'],
+        cursors: {},
+      },
+    ])
+    expect(client.connectionState).toBe('connected')
+    expect(sockets[0]?.url).not.toContain('customer.support.jwt')
+    await Promise.resolve()
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+    for (let index = 0; index < 5; index += 1) {
+      sockets[0]?.receive({
+        type: 'realtime_event',
+        channel: 'customer_support',
+        event: {
+          type: 'support_event',
+          event_type: 'support_read_state_changed',
+          session_id: 'support-1',
+          payload: { last_read_sequence: '1' },
+        },
+      })
+    }
+    await Promise.resolve()
+    expect(transport.listMessages).toHaveBeenCalledTimes(1)
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+    vi.mocked(transport.listMessages).mockResolvedValue({
+      messages: [
+        ...history,
+        {
+          id: 'support-message-2',
+          sessionId: 'support-1',
+          sequence: '2',
+          clientMessageId: '',
+          senderType: 'agent',
+          senderName: '王悦',
+          content: '新的实时回复',
+          createdAt: '2026-08-18T08:01:00.000Z',
+        },
+      ],
+      latestSequence: '2',
+      sessionVersion: '2',
+    })
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'customer_support',
+      event: {
+        type: 'support_event',
+        event_type: 'support_message_created',
+        session_id: 'support-1',
+        payload: {},
+      },
+    })
+    await vi.waitFor(() => expect(client.messages).toHaveLength(2))
+    await vi.waitFor(() => expect(transport.markRead).toHaveBeenCalledTimes(2))
+    expect(transport.markRead).toHaveBeenLastCalledWith('support-1', '2')
+    expect(client.messages[1]?.content).toBe('新的实时回复')
+    sockets[0]?.receive({ type: 'channel_resync_required', channel: 'customer_support' })
+    await vi.waitFor(() => expect(transport.listMessages).toHaveBeenCalledTimes(3))
+    expect(transport.markRead).toHaveBeenCalledTimes(2)
+    client.destroy()
+  })
+
+  it('refreshes session projection without reloading history for non-message events', async () => {
+    const sockets: FakeWebSocket[] = []
+    const transport = {
+      ...createTransport(),
+      getSession: vi.fn(async () => ({ ...session, status: 'closed' as const, version: '2' })),
+    }
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+    await client.start()
+    await Promise.resolve()
+
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'customer_support',
+      event: {
+        type: 'support_event',
+        event_type: 'support_session_closed',
+        session_id: 'support-1',
+        payload: {},
+      },
+    })
+
+    await vi.waitFor(() => expect(transport.getSession).toHaveBeenCalledTimes(1))
+    expect(client.session?.status).toBe('closed')
+    expect(transport.listMessages).toHaveBeenCalledTimes(1)
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+    client.destroy()
+  })
+
+  it('refreshes the session list for events from another support conversation', async () => {
+    const sockets: FakeWebSocket[] = []
+    const otherSession: CustomerSupportSession = {
+      ...session,
+      id: 'support-2',
+      sessionNo: 'CS-2',
+      title: '其他客服会话',
+      lastMessage: '旧消息',
+      unreadCount: 0,
+    }
+    const updatedOtherSession = {
+      ...otherSession,
+      lastMessage: '其他会话的新回复',
+      unreadCount: 1,
+      version: '2',
+    }
+    const transport = createTransport()
+    vi.mocked(transport.listSessions)
+      .mockResolvedValueOnce([session, otherSession])
+      .mockResolvedValue([session, updatedOtherSession])
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+    const sessionLists: Array<readonly CustomerSupportSession[]> = []
+    client.on('sessions', ({ sessions }) => sessionLists.push(sessions))
+    await client.start()
+
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'customer_support',
+      event: {
+        type: 'support_event',
+        event_type: 'support_message_created',
+        session_id: 'support-2',
+        payload: {},
+      },
+    })
+
+    await vi.waitFor(() => expect(transport.listSessions).toHaveBeenCalledTimes(2))
+    expect(sessionLists.at(-1)?.find((candidate) => candidate.id === 'support-2')).toEqual(
+      updatedOtherSession,
+    )
+    expect(transport.listMessages).toHaveBeenCalledTimes(1)
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+    expect(client.messages).toEqual(history)
+    client.destroy()
+  })
+
+  it('uses read-state events to refresh unread projections without reloading history', async () => {
+    const sockets: FakeWebSocket[] = []
+    const otherSession: CustomerSupportSession = {
+      ...session,
+      id: 'support-2',
+      sessionNo: 'CS-2',
+      unreadCount: 2,
+    }
+    const transport = createTransport()
+    vi.mocked(transport.listSessions)
+      .mockResolvedValueOnce([session, otherSession])
+      .mockResolvedValue([session, { ...otherSession, unreadCount: 0 }])
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+    await client.start()
+
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'customer_support',
+      event: {
+        type: 'support_event',
+        event_type: 'support_read_state_changed',
+        session_id: 'support-2',
+        payload: { last_read_sequence: '2' },
+      },
+    })
+
+    await vi.waitFor(() => expect(transport.listSessions).toHaveBeenCalledTimes(2))
+    expect(transport.listMessages).toHaveBeenCalledTimes(1)
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+    client.destroy()
+  })
+
+  it('deduplicates in-flight cursors and submits only the newest pending cursor', async () => {
+    const sockets: FakeWebSocket[] = []
+    const firstRead = deferred<void>()
+    const transport = createTransport()
+    const markRead = vi.fn<(sessionId: string, cursor: string) => Promise<void>>(async () => {})
+    transport.markRead = markRead
+    vi.mocked(transport.listMessages).mockResolvedValue({
+      messages: history,
+      latestSequence: '5',
+      sessionVersion: '1',
+    })
+    markRead.mockImplementationOnce(() => firstRead.promise).mockResolvedValue(undefined)
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+    await client.start()
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+
+    for (const [index, latestSequence] of ['5', '4', '6', '6'].entries()) {
+      vi.mocked(transport.listMessages).mockResolvedValueOnce({
+        messages: history,
+        latestSequence,
+        sessionVersion: '1',
+      })
+      sockets[0]?.receive({ type: 'channel_resync_required', channel: 'customer_support' })
+      await vi.waitFor(() => expect(transport.listMessages).toHaveBeenCalledTimes(index + 2))
+    }
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+
+    firstRead.resolve()
+    await vi.waitFor(() => expect(transport.markRead).toHaveBeenCalledTimes(2))
+    expect(transport.markRead).toHaveBeenNthCalledWith(1, 'support-1', '5')
+    expect(transport.markRead).toHaveBeenNthCalledWith(2, 'support-1', '6')
+    client.destroy()
+  })
+
+  it('keeps acknowledged read cursors isolated across session switches', async () => {
+    const secondSession: CustomerSupportSession = {
+      ...session,
+      id: 'support-2',
+      sessionNo: 'CS-2',
+      version: '3',
+    }
+    const transport = createTransport()
+    vi.mocked(transport.listSessions).mockResolvedValue([session, secondSession])
+    vi.mocked(transport.listMessages).mockImplementation(async (sessionId) => ({
+      messages: [],
+      latestSequence: sessionId === 'support-1' ? '2' : '7',
+      sessionVersion: sessionId === 'support-1' ? '1' : '3',
+    }))
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      webSocketFactory: (url) => new FakeWebSocket(url).asWebSocket(),
+    })
+
+    await client.start()
+    await vi.waitFor(() => expect(transport.markRead).toHaveBeenCalledTimes(1))
+    await client.bindSession('support-2')
+    await vi.waitFor(() => expect(transport.markRead).toHaveBeenCalledTimes(2))
+    await client.bindSession('support-1')
+    await Promise.resolve()
+
+    expect(transport.markRead).toHaveBeenCalledTimes(2)
+    expect(transport.markRead).toHaveBeenNthCalledWith(1, 'support-1', '2')
+    expect(transport.markRead).toHaveBeenNthCalledWith(2, 'support-2', '7')
+    client.destroy()
+  })
+
+  it('retries a failed cursor only after a later message refresh', async () => {
+    const sockets: FakeWebSocket[] = []
+    const transport = createTransport()
+    const markRead = vi.fn<(sessionId: string, cursor: string) => Promise<void>>(async () => {})
+    transport.markRead = markRead
+    vi.mocked(transport.listMessages).mockResolvedValue({
+      messages: history,
+      latestSequence: '3',
+      sessionVersion: '1',
+    })
+    markRead.mockRejectedValueOnce(new Error('temporary failure')).mockResolvedValue(undefined)
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+    await client.start()
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+
+    for (let index = 0; index < 5; index += 1) {
+      sockets[0]?.receive({
+        type: 'realtime_event',
+        channel: 'customer_support',
+        event: {
+          type: 'support_event',
+          event_type: 'support_read_state_changed',
+          session_id: 'support-1',
+          payload: {},
+        },
+      })
+    }
+    await Promise.resolve()
+    expect(transport.markRead).toHaveBeenCalledTimes(1)
+
+    sockets[0]?.receive({
+      type: 'realtime_event',
+      channel: 'customer_support',
+      event: {
+        type: 'support_event',
+        event_type: 'support_message_created',
+        session_id: 'support-1',
+        payload: {},
+      },
+    })
+    await vi.waitFor(() => expect(transport.markRead).toHaveBeenCalledTimes(2))
+    expect(transport.markRead).toHaveBeenLastCalledWith('support-1', '3')
+    client.destroy()
+  })
+
+  it('creates the first support session atomically and emits one local message', async () => {
+    const sockets: FakeWebSocket[] = []
+    const transport = createTransport()
+    vi.mocked(transport.listSessions).mockResolvedValue([])
+    vi.mocked(transport.createSession).mockResolvedValue({
+      session,
+      initialMessage: {
+        ...history[0]!,
+        senderType: 'customer',
+        content: '需要人工协助',
+      },
+    })
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      requestIdFactory: () => 'b95e15b8-55df-4d84-9fbe-c00dc45ae3a7',
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+    const received: string[] = []
+    client.on('message', ({ message }) => received.push(message.id))
+    await client.start()
+    const message = await client.sendMessage('需要人工协助')
+
+    expect(transport.createSession).toHaveBeenCalledWith({
+      clientRequestId: 'b95e15b8-55df-4d84-9fbe-c00dc45ae3a7',
+      title: '需要人工协助',
+      initialMessage: '需要人工协助',
+    })
+    expect(message.content).toBe('需要人工协助')
+    expect(received).toEqual(['support-message-1'])
+    client.destroy()
+  })
+
+  it('does not restore an empty waiting session before the customer sends a message', async () => {
+    const emptyWaitingSession: CustomerSupportSession = {
+      ...session,
+      status: 'waiting',
+      statusText: '等待接入',
+      lastMessage: '',
+    }
+    const initialMessage: CustomerSupportMessage = {
+      ...history[0]!,
+      senderType: 'customer',
+      senderName: '',
+      content: '首次咨询',
+    }
+    const transport = createTransport()
+    vi.mocked(transport.listSessions).mockResolvedValue([emptyWaitingSession])
+    vi.mocked(transport.createSession).mockResolvedValue({
+      session: { ...emptyWaitingSession, lastMessage: '首次咨询' },
+      initialMessage,
+    })
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      requestIdFactory: () => 'b95e15b8-55df-4d84-9fbe-c00dc45ae3a7',
+      webSocketFactory: (url) => new FakeWebSocket(url).asWebSocket(),
+    })
+
+    await client.start()
+    expect(client.session).toBeNull()
+    expect(transport.listMessages).not.toHaveBeenCalled()
+    expect(transport.createSession).not.toHaveBeenCalled()
+
+    const message = await client.sendMessage('首次咨询')
+    expect(transport.createSession).toHaveBeenCalledWith({
+      clientRequestId: 'b95e15b8-55df-4d84-9fbe-c00dc45ae3a7',
+      title: '首次咨询',
+      initialMessage: '首次咨询',
+    })
+    expect(message).toEqual(initialMessage)
+    expect(client.session?.status).toBe('waiting')
+    client.destroy()
+  })
+
+  it('refreshes an expired support credential once and then stops retrying', async () => {
+    const sockets: FakeWebSocket[] = []
+    const transport = createTransport()
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      reconnect: { initialDelayMs: 1_000, maximumDelayMs: 1_000, jitter: 0 },
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+    const errors: Array<{ code: string; message: string; recoverable: boolean }> = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+
+    sockets[0]?.open()
+    await Promise.resolve()
+    sockets[0]?.receive({ type: 'authentication_error', code: 'UNAUTHORIZED' })
+    sockets[0]?.serverClose(4401)
+    await vi.advanceTimersByTimeAsync(1_000)
+    sockets[1]?.open()
+    await Promise.resolve()
+    sockets[1]?.receive({ type: 'authentication_error', code: 'UNAUTHORIZED' })
+    sockets[1]?.serverClose(4401)
+
+    expect(sockets).toHaveLength(2)
+    expect(transport.getAccessToken).toHaveBeenCalledTimes(2)
+    expect(client.connectionState).toBe('disconnected')
+    expect(vi.getTimerCount()).toBe(0)
+    expect(errors.at(-1)).toEqual({
+      code: 'AUTHENTICATION_FAILED',
+      message: '人工客服身份验证失败，请重新登录后再试。',
+      recoverable: false,
+    })
+    client.destroy()
+  })
+
+  it('does not label access denial as an expired credential or retry it', async () => {
+    const sockets: FakeWebSocket[] = []
+    const transport = createTransport()
+    const client = new CustomerSupportClient({
+      realtimeUrl: 'wss://kanban.example.com/api/user-realtime/ws',
+      transport,
+      webSocketFactory: (url) => {
+        const socket = new FakeWebSocket(url)
+        sockets.push(socket)
+        return socket.asWebSocket()
+      },
+    })
+    const errors: Array<{ code: string; message: string; recoverable: boolean }> = []
+    client.on('error', (detail) => errors.push(detail))
+    await client.start()
+    sockets[0]?.open()
+    await Promise.resolve()
+    sockets[0]?.receive({ type: 'authentication_error', code: 'ACCESS_DENIED' })
+    sockets[0]?.serverClose(4403)
+
+    expect(client.connectionState).toBe('disconnected')
+    expect(vi.getTimerCount()).toBe(0)
+    expect(errors).toEqual([
+      {
+        code: 'AUTHENTICATION_FAILED',
+        message: '当前身份无权使用人工客服。',
+        recoverable: false,
+      },
+    ])
+    client.destroy()
+  })
+})

package/packages/core/tests/fake-websocket.ts

@@ -0,0 +1,55 @@
+export class FakeWebSocket {
+  readonly url: string
+  readyState = 0
+  sent: string[] = []
+  closeCount = 0
+  onopen: ((event: Event) => void) | null = null
+  onmessage: ((event: MessageEvent) => void) | null = null
+  onerror: ((event: Event) => void) | null = null
+  onclose: ((event: CloseEvent) => void) | null = null
+
+  constructor(url: string) {
+    this.url = url
+  }
+
+  open(): void {
+    this.readyState = 1
+    this.onopen?.(new Event('open'))
+  }
+
+  receive(payload: unknown): void {
+    this.onmessage?.(new MessageEvent('message', { data: JSON.stringify(payload) }))
+  }
+
+  fail(): void {
+    this.onerror?.(new Event('error'))
+  }
+
+  serverClose(code = 1006): void {
+    this.readyState = 3
+    this.onclose?.(createCloseEvent(code))
+  }
+
+  send(payload: string): void {
+    if (this.readyState !== 1) throw new Error('socket is not open')
+    this.sent.push(payload)
+  }
+
+  close(code = 1000): void {
+    if (this.readyState >= 2) return
+    this.closeCount += 1
+    this.readyState = 3
+    this.onclose?.(createCloseEvent(code))
+  }
+
+  asWebSocket(): WebSocket {
+    return this as unknown as WebSocket
+  }
+}
+
+function createCloseEvent(code: number): CloseEvent {
+  if (typeof CloseEvent === 'function') return new CloseEvent('close', { code })
+  const event = new Event('close') as CloseEvent
+  Object.defineProperty(event, 'code', { value: code })
+  return event
+}