@csntgao/uni-base 0.1.0

package/packages/core/src/customer-support-client.ts

@@ -0,0 +1,825 @@
+import { createPingFrame, parseJsonRecord } from './protocol'
+import type {
+  CustomerSupportClientEventMap,
+  CustomerSupportClientListener,
+  CustomerSupportClientOptions,
+  CustomerSupportErrorCode,
+  CustomerSupportErrorDetail,
+  CustomerSupportMessage,
+  CustomerSupportSession,
+} from './customer-support-types'
+import type { AiEmployeeConnectionState, AiEmployeeReconnectOptions } from './types'
+
+type UntypedListener = (detail: unknown) => void
+type JsonRecord = Record<string, unknown>
+
+const DEFAULT_RECONNECT: AiEmployeeReconnectOptions = {
+  initialDelayMs: 1_000,
+  maximumDelayMs: 30_000,
+  factor: 2,
+  jitter: 0.2,
+}
+const MAX_TOKEN_RECONNECTS = 1
+const MAX_AVAILABILITY_RECONNECTS = 3
+
+type AuthenticationRetryMode = 'token' | 'availability' | 'never'
+
+interface SocketAuthenticationFailure {
+  generation: number
+  retryMode: AuthenticationRetryMode
+}
+
+interface CustomerSupportReadCursorState {
+  acknowledged: string
+  inFlight: string | null
+  pending: string | null
+  generation: number
+}
+
+interface CustomerSupportHistoryRefresh {
+  sessionId: string
+  promise: Promise<void>
+}
+
+interface CustomerSupportSessionsRefresh {
+  promise: Promise<readonly CustomerSupportSession[]>
+}
+
+export class CustomerSupportClientError extends Error {
+  readonly code: CustomerSupportErrorCode
+
+  constructor(code: CustomerSupportErrorCode, message: string) {
+    super(message)
+    this.name = 'CustomerSupportClientError'
+    this.code = code
+  }
+}
+
+export class CustomerSupportClient {
+  private readonly realtimeUrl: string
+  private readonly transport: CustomerSupportClientOptions['transport']
+  private readonly webSocketFactory: (url: string) => WebSocket
+  private readonly requestIdFactory: () => string
+  private readonly reconnectOptions: AiEmployeeReconnectOptions
+  private readonly minimumHeartbeatMs: number
+  private readonly listeners = new Map<keyof CustomerSupportClientEventMap, Set<UntypedListener>>()
+
+  private currentSession: CustomerSupportSession | null = null
+  private currentSessions: CustomerSupportSession[] = []
+  private currentMessages: CustomerSupportMessage[] = []
+  private currentState: AiEmployeeConnectionState = 'idle'
+  private socket: WebSocket | null = null
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private reconnectAttempt = 0
+  private tokenReconnectAttempt = 0
+  private availabilityReconnectAttempt = 0
+  private socketGeneration = 0
+  private socketAuthenticationFailure: SocketAuthenticationFailure | null = null
+  private destroyed = false
+  private shouldReconnect = false
+  private sending = false
+  private historyRefresh: CustomerSupportHistoryRefresh | null = null
+  private sessionsRefresh: CustomerSupportSessionsRefresh | null = null
+  private readonly readCursorStates = new Map<string, CustomerSupportReadCursorState>()
+  private readLifecycleGeneration = 0
+  private requestedSessionId: string | null
+
+  constructor(options: CustomerSupportClientOptions) {
+    this.realtimeUrl = validateRealtimeUrl(options.realtimeUrl)
+    if (!options.transport) {
+      throw new CustomerSupportClientError('INVALID_CONFIGURATION', '缺少客服 transport 配置。')
+    }
+    this.transport = options.transport
+    this.requestedSessionId = normalizedText(options.sessionId) || null
+    this.requestIdFactory = options.requestIdFactory ?? createRequestId
+    this.reconnectOptions = normalizeReconnect(options.reconnect)
+    this.minimumHeartbeatMs = Math.max(1, options.minimumHeartbeatMs ?? 5_000)
+    this.webSocketFactory =
+      options.webSocketFactory ??
+      ((url) => {
+        if (typeof WebSocket === 'undefined') {
+          throw new CustomerSupportClientError(
+            'WEBSOCKET_UNAVAILABLE',
+            '当前运行环境不支持 WebSocket。',
+          )
+        }
+        return new WebSocket(url)
+      })
+  }
+
+  get session(): CustomerSupportSession | null {
+    return this.currentSession
+  }
+
+  get messages(): readonly CustomerSupportMessage[] {
+    return [...this.currentMessages]
+  }
+
+  get connectionState(): AiEmployeeConnectionState {
+    return this.currentState
+  }
+
+  on<K extends keyof CustomerSupportClientEventMap>(
+    type: K,
+    listener: CustomerSupportClientListener<K>,
+  ): () => void {
+    this.assertUsable()
+    const listeners = this.listeners.get(type) ?? new Set<UntypedListener>()
+    const untyped = listener as UntypedListener
+    listeners.add(untyped)
+    this.listeners.set(type, listeners)
+    return () => listeners.delete(untyped)
+  }
+
+  async start(): Promise<void> {
+    this.assertUsable()
+    try {
+      const sessions = await this.transport.listSessions()
+      this.assertUsable()
+      this.replaceSessions(sessions)
+      const requested = this.requestedSessionId
+      this.currentSession = requested
+        ? (sessions.find((session) => session.id === requested) ?? null)
+        : (sessions.find(
+            (session) => session.status !== 'closed' && hasCustomerSupportMessages(session),
+          ) ??
+          sessions.find(hasCustomerSupportMessages) ??
+          null)
+      if (this.currentSession) {
+        this.emit('session', { session: this.currentSession })
+        await this.refreshHistory()
+      }
+    } catch {
+      this.emitError('HISTORY_LOAD_FAILED', '客服会话加载失败，实时连接仍会继续。', true)
+    }
+    this.shouldReconnect = true
+    this.openSocket(false)
+    this.emit('ready', { sessionId: this.currentSession?.id ?? null })
+  }
+
+  prepareNewConversation(): void {
+    this.assertUsable()
+    this.currentSession = null
+    this.requestedSessionId = null
+    this.currentMessages = []
+  }
+
+  async bindSession(sessionId: string): Promise<void> {
+    this.assertUsable()
+    const normalized = requiredText(sessionId, 'sessionId')
+    const sessions = await this.transport.listSessions()
+    this.replaceSessions(sessions)
+    const session = sessions.find((candidate) => candidate.id === normalized)
+    if (!session) {
+      throw new CustomerSupportClientError('SESSION_UNAVAILABLE', '客服会话不存在。')
+    }
+    this.currentSession = session
+    this.requestedSessionId = session.id
+    this.emit('session', { session })
+    await this.refreshHistory()
+  }
+
+  async sendMessage(content: string): Promise<CustomerSupportMessage> {
+    this.assertUsable()
+    const normalized = content.trim()
+    if (!normalized) throw new CustomerSupportClientError('EMPTY_MESSAGE', '消息内容不能为空。')
+    if (this.sending) {
+      throw new CustomerSupportClientError('SEND_IN_PROGRESS', '上一条消息仍在发送中。')
+    }
+    this.sending = true
+    try {
+      if (!this.currentSession) {
+        const result = await this.transport.createSession({
+          clientRequestId: requiredRequestId(this.requestIdFactory()),
+          title: normalized.slice(0, 30),
+          initialMessage: normalized,
+        })
+        this.assertUsable()
+        this.currentSession = result.session
+        this.upsertSession(result.session)
+        this.requestedSessionId = result.session.id
+        this.emit('session', { session: result.session })
+        let message = result.initialMessage
+        if (!message) {
+          const page = await this.transport.listMessages(result.session.id)
+          message = [...page.messages]
+            .reverse()
+            .find(
+              (candidate) =>
+                candidate.senderType === 'customer' && candidate.content.trim() === normalized,
+            )
+          this.currentMessages = page.messages.filter((candidate) => candidate.id !== message?.id)
+        }
+        if (!message) throw new Error('Missing initial message')
+        this.appendMessage(message, 'local')
+        return message
+      }
+      const message = await this.transport.sendMessage(
+        this.currentSession.id,
+        requiredRequestId(this.requestIdFactory()),
+        normalized,
+      )
+      this.assertUsable()
+      this.appendMessage(message, 'local')
+      return message
+    } catch (error) {
+      if (error instanceof CustomerSupportClientError) throw error
+      const detail = this.emitError('SEND_FAILED', '消息发送失败，请稍后重试。', true)
+      throw new CustomerSupportClientError(detail.code, detail.message)
+    } finally {
+      this.sending = false
+    }
+  }
+
+  async listSessions(): Promise<readonly CustomerSupportSession[]> {
+    this.assertUsable()
+    return this.refreshSessions()
+  }
+
+  destroy(): void {
+    if (this.destroyed) return
+    this.destroyed = true
+    this.shouldReconnect = false
+    this.clearTimers()
+    this.socketGeneration += 1
+    this.socket?.close()
+    this.socket = null
+    this.setState('destroyed')
+    this.listeners.clear()
+    this.currentMessages = []
+    this.currentSessions = []
+    this.historyRefresh = null
+    this.sessionsRefresh = null
+    this.readLifecycleGeneration += 1
+    this.readCursorStates.clear()
+  }
+
+  private async refreshHistory(realtime = false): Promise<void> {
+    const session = this.currentSession
+    if (!session) return
+    if (this.historyRefresh?.sessionId === session.id) return this.historyRefresh.promise
+    const pending = (async () => {
+      try {
+        const page = await this.transport.listMessages(session.id)
+        if (this.destroyed || this.currentSession?.id !== session.id) return
+        const unique = new Map<string, CustomerSupportMessage>()
+        for (const message of page.messages) {
+          if (message.sessionId === session.id && message.id) unique.set(message.id, message)
+        }
+        const previousIds = new Set(this.currentMessages.map((message) => message.id))
+        this.currentMessages = [...unique.values()].sort(compareMessages)
+        this.emit('history', { sessionId: session.id, messages: this.messages })
+        if (realtime) {
+          for (const message of this.currentMessages) {
+            if (!previousIds.has(message.id)) {
+              this.emit('message', { sessionId: session.id, message, source: 'realtime' })
+            }
+          }
+        }
+        this.markReadIfNeeded(session.id, page.latestSequence)
+      } catch {
+        this.emitError('HISTORY_LOAD_FAILED', '历史消息加载失败，实时连接仍会继续。', true)
+      }
+    })()
+    const refresh = { sessionId: session.id, promise: pending }
+    this.historyRefresh = refresh
+    await pending.finally(() => {
+      if (this.historyRefresh === refresh) this.historyRefresh = null
+    })
+  }
+
+  private markReadIfNeeded(sessionId: string, latestSequence: string): void {
+    const markRead = this.transport.markRead
+    const cursor = normalizeReadCursor(latestSequence)
+    if (!markRead || !cursor || compareReadCursors(cursor, '0') <= 0 || this.destroyed) return
+    const state = this.readCursorState(sessionId)
+    if (compareReadCursors(cursor, state.acknowledged) <= 0) return
+    if (state.inFlight) {
+      if (compareReadCursors(cursor, state.inFlight) > 0) {
+        state.pending = maxReadCursor(state.pending, cursor)
+      }
+      return
+    }
+    this.submitReadCursor(sessionId, cursor, state, markRead)
+  }
+
+  private submitReadCursor(
+    sessionId: string,
+    cursor: string,
+    state: CustomerSupportReadCursorState,
+    markRead: NonNullable<CustomerSupportClientOptions['transport']['markRead']>,
+  ): void {
+    const lifecycleGeneration = this.readLifecycleGeneration
+    const requestGeneration = ++state.generation
+    state.inFlight = cursor
+    let request: Promise<void>
+    try {
+      request = markRead.call(this.transport, sessionId, cursor)
+    } catch {
+      state.inFlight = null
+      state.pending = null
+      return
+    }
+    void request
+      .then(() => {
+        if (!this.isCurrentReadRequest(state, lifecycleGeneration, requestGeneration, cursor))
+          return
+        state.acknowledged = maxReadCursor(state.acknowledged, cursor)
+        const next = state.pending
+        state.pending = null
+        state.inFlight = null
+        if (next && compareReadCursors(next, state.acknowledged) > 0) {
+          this.submitReadCursor(sessionId, next, state, markRead)
+        }
+      })
+      .catch(() => {
+        if (!this.isCurrentReadRequest(state, lifecycleGeneration, requestGeneration, cursor))
+          return
+        state.inFlight = null
+        state.pending = null
+      })
+  }
+
+  private readCursorState(sessionId: string): CustomerSupportReadCursorState {
+    const current = this.readCursorStates.get(sessionId)
+    if (current) return current
+    const created: CustomerSupportReadCursorState = {
+      acknowledged: '0',
+      inFlight: null,
+      pending: null,
+      generation: 0,
+    }
+    this.readCursorStates.set(sessionId, created)
+    return created
+  }
+
+  private isCurrentReadRequest(
+    state: CustomerSupportReadCursorState,
+    lifecycleGeneration: number,
+    requestGeneration: number,
+    cursor: string,
+  ): boolean {
+    return (
+      !this.destroyed &&
+      this.readLifecycleGeneration === lifecycleGeneration &&
+      state.generation === requestGeneration &&
+      state.inFlight === cursor
+    )
+  }
+
+  private openSocket(reconnecting: boolean): void {
+    if (this.destroyed || !this.shouldReconnect) return
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.socket?.close()
+    this.setState(reconnecting ? 'reconnecting' : 'connecting')
+    let socket: WebSocket
+    try {
+      socket = this.webSocketFactory(this.realtimeUrl)
+    } catch {
+      this.emitError('WEBSOCKET_UNAVAILABLE', '无法建立客服实时连接。', true)
+      this.scheduleReconnect()
+      return
+    }
+    const generation = ++this.socketGeneration
+    this.socket = socket
+    socket.onopen = () => void this.authenticate(socket, generation)
+    socket.onmessage = (event) => void this.handleSocketData(event.data, socket, generation)
+    socket.onerror = () => {
+      if (this.isCurrentSocket(socket, generation)) {
+        this.emitError('WEBSOCKET_ERROR', '客服实时连接发生异常。', true)
+      }
+    }
+    socket.onclose = (event) => this.handleSocketClose(socket, generation, event.code)
+  }
+
+  private async authenticate(socket: WebSocket, generation: number): Promise<void> {
+    if (!this.isCurrentSocket(socket, generation)) return
+    this.setState('authenticating')
+    let accessToken = ''
+    try {
+      accessToken = (await this.transport.getAccessToken()).trim()
+    } catch {
+      // Provider errors may contain credentials and are intentionally discarded.
+    }
+    if (!this.isCurrentSocket(socket, generation)) return
+    if (!accessToken) {
+      this.emitError('TOKEN_UNAVAILABLE', '无法获取客服实时连接凭证。', true)
+      socket.close()
+      return
+    }
+    socket.send(
+      JSON.stringify({
+        type: 'authenticate',
+        protocol_version: 1,
+        access_token: accessToken,
+        requested_channels: ['customer_support'],
+        cursors: {},
+      }),
+    )
+    accessToken = ''
+  }
+
+  private async handleSocketData(
+    data: unknown,
+    socket: WebSocket,
+    generation: number,
+  ): Promise<void> {
+    if (!this.isCurrentSocket(socket, generation)) return
+    let raw = ''
+    if (typeof data === 'string') raw = data
+    else if (data instanceof Blob) raw = await data.text()
+    else if (data instanceof ArrayBuffer) raw = new TextDecoder().decode(data)
+    const message = raw ? parseJsonRecord(raw) : null
+    if (!message) {
+      this.emitError('PROTOCOL_ERROR', '收到无法解析的客服实时消息。', true)
+      return
+    }
+    this.handleServerMessage(message, socket, generation)
+  }
+
+  private handleServerMessage(message: JsonRecord, socket: WebSocket, generation: number): void {
+    const type = normalizedText(message.type)
+    if (type === 'realtime_ready') {
+      const channels = record(message.channels)
+      if (record(channels.customer_support).available !== true) {
+        this.shouldReconnect = false
+        this.emitError('CHANNEL_UNAVAILABLE', '人工客服实时通道不可用。', false)
+        socket.close()
+        return
+      }
+      this.reconnectAttempt = 0
+      this.tokenReconnectAttempt = 0
+      this.availabilityReconnectAttempt = 0
+      this.startHeartbeat(numberValue(message.heartbeat_interval_seconds), socket, generation)
+      this.setState('connected')
+      return
+    }
+    if (type === 'realtime_event' && message.channel === 'customer_support') {
+      const event = record(message.event)
+      this.handleCustomerSupportEvent(event)
+      return
+    }
+    if (type === 'channel_resync_required' && message.channel === 'customer_support') {
+      void this.refreshFromRealtime()
+      return
+    }
+    if (type === 'authentication_error') {
+      const failure = authenticationFailure(normalizedText(message.code))
+      this.socketAuthenticationFailure = { generation, retryMode: failure.retryMode }
+      this.emitError(failure.code, failure.message, failure.retryMode !== 'never')
+    }
+  }
+
+  private handleCustomerSupportEvent(event: JsonRecord): void {
+    const eventType = normalizedText(event.event_type)
+    const sessionId = normalizedText(event.session_id)
+    if (!eventType || !sessionId) return
+    this.refreshSessionsFromRealtime()
+    if (sessionId !== this.currentSession?.id) return
+    if (eventType === 'support_read_state_changed') return
+    if (eventType === 'support_message_created') {
+      void this.refreshHistory(true)
+      return
+    }
+    void this.refreshSessionFromRealtime()
+  }
+
+  private async refreshFromRealtime(): Promise<void> {
+    await this.refreshSessions().catch(() => [...this.currentSessions])
+    await this.refreshSessionFromRealtime()
+    await this.refreshHistory(true)
+  }
+
+  private async refreshSessions(): Promise<readonly CustomerSupportSession[]> {
+    if (this.sessionsRefresh) return this.sessionsRefresh.promise
+    const pending = (async () => {
+      const sessions = await this.transport.listSessions()
+      if (!this.destroyed) this.replaceSessions(sessions)
+      return [...this.currentSessions]
+    })()
+    const refresh = { promise: pending }
+    this.sessionsRefresh = refresh
+    return pending.finally(() => {
+      if (this.sessionsRefresh === refresh) this.sessionsRefresh = null
+    })
+  }
+
+  private refreshSessionsFromRealtime(): void {
+    void this.refreshSessions().catch(() => {
+      // A later realtime event, panel refresh or resync can recover the list projection.
+    })
+  }
+
+  private replaceSessions(sessions: readonly CustomerSupportSession[]): void {
+    this.currentSessions = [...sessions]
+    this.emit('sessions', { sessions: [...this.currentSessions] })
+  }
+
+  private upsertSession(session: CustomerSupportSession): void {
+    const currentIndex = this.currentSessions.findIndex((candidate) => candidate.id === session.id)
+    if (currentIndex < 0) this.currentSessions = [session, ...this.currentSessions]
+    else {
+      this.currentSessions = this.currentSessions.map((candidate, index) =>
+        index === currentIndex ? session : candidate,
+      )
+    }
+    this.emit('sessions', { sessions: [...this.currentSessions] })
+  }
+
+  private async refreshSessionFromRealtime(): Promise<void> {
+    const sessionId = this.currentSession?.id
+    const getSession = this.transport.getSession
+    if (!sessionId || !getSession) return
+    try {
+      const session = await getSession.call(this.transport, sessionId)
+      if (!this.destroyed && this.currentSession?.id === sessionId) {
+        this.currentSession = session
+        this.emit('session', { session })
+      }
+    } catch {
+      // A later realtime event or resync can recover the optional session projection.
+    }
+  }
+
+  private appendMessage(message: CustomerSupportMessage, source: 'local' | 'realtime'): void {
+    if (this.currentMessages.some((candidate) => candidate.id === message.id)) return
+    this.currentMessages = [...this.currentMessages, message].sort(compareMessages)
+    this.emit('message', { sessionId: message.sessionId, message, source })
+  }
+
+  private startHeartbeat(intervalSeconds: number, socket: WebSocket, generation: number): void {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+    const requested = intervalSeconds > 0 ? intervalSeconds * 1_000 : 25_000
+    this.heartbeatTimer = setInterval(
+      () => {
+        if (this.isCurrentSocket(socket, generation) && socket.readyState === 1) {
+          socket.send(JSON.stringify(createPingFrame()))
+        }
+      },
+      Math.max(this.minimumHeartbeatMs, requested),
+    )
+  }
+
+  private handleSocketClose(socket: WebSocket, generation: number, code: number): void {
+    if (!this.isCurrentSocket(socket, generation)) return
+    this.socket = null
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+    this.heartbeatTimer = null
+    const authenticationFailure =
+      this.socketAuthenticationFailure?.generation === generation
+        ? this.socketAuthenticationFailure
+        : null
+    this.socketAuthenticationFailure = null
+    if (!this.shouldReconnect || this.destroyed) {
+      if (!this.destroyed) this.setState('disconnected')
+      return
+    }
+    if (authenticationFailure?.retryMode === 'never') {
+      this.shouldReconnect = false
+      this.setState('disconnected')
+      return
+    }
+    if (code === 4400 || code === 4403) {
+      this.shouldReconnect = false
+      if (!authenticationFailure) {
+        this.emitError(
+          code === 4400 ? 'PROTOCOL_ERROR' : 'AUTHENTICATION_FAILED',
+          code === 4400 ? '客服实时连接协议不受支持。' : '当前身份无权使用人工客服。',
+          false,
+        )
+      }
+      this.setState('disconnected')
+      return
+    }
+    if (authenticationFailure?.retryMode === 'availability' || code === 1013) {
+      if (!authenticationFailure) {
+        this.emitError('REALTIME_UNAVAILABLE', '客服实时鉴权服务暂不可用，正在重试。', true)
+      }
+      this.scheduleAvailabilityReconnect()
+      return
+    }
+    if (authenticationFailure?.retryMode === 'token' || code === 4401) {
+      if (!authenticationFailure) {
+        this.emitError('AUTHENTICATION_FAILED', '客服连接凭证已失效，正在重新连接。', true)
+      }
+      if (this.tokenReconnectAttempt >= MAX_TOKEN_RECONNECTS) {
+        this.shouldReconnect = false
+        this.emitError('AUTHENTICATION_FAILED', '人工客服身份验证失败，请重新登录后再试。', false)
+        this.setState('disconnected')
+        return
+      }
+      this.tokenReconnectAttempt += 1
+    }
+    this.scheduleReconnect()
+  }
+
+  private scheduleAvailabilityReconnect(): void {
+    if (this.availabilityReconnectAttempt >= MAX_AVAILABILITY_RECONNECTS) {
+      this.shouldReconnect = false
+      this.emitError('REALTIME_UNAVAILABLE', '客服实时鉴权服务持续不可用，请稍后重试。', false)
+      this.setState('disconnected')
+      return
+    }
+    this.availabilityReconnectAttempt += 1
+    this.scheduleReconnect()
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.shouldReconnect || this.destroyed || this.reconnectTimer) return
+    const base = Math.min(
+      this.reconnectOptions.maximumDelayMs,
+      this.reconnectOptions.initialDelayMs *
+        this.reconnectOptions.factor ** this.reconnectAttempt++,
+    )
+    const jitter = base * this.reconnectOptions.jitter * (Math.random() * 2 - 1)
+    this.reconnectTimer = setTimeout(
+      () => {
+        this.reconnectTimer = null
+        this.openSocket(true)
+      },
+      Math.max(0, base + jitter),
+    )
+  }
+
+  private clearTimers(): void {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.heartbeatTimer = null
+    this.reconnectTimer = null
+  }
+
+  private isCurrentSocket(socket: WebSocket, generation: number): boolean {
+    return !this.destroyed && this.socket === socket && this.socketGeneration === generation
+  }
+
+  private setState(current: AiEmployeeConnectionState): void {
+    if (this.currentState === current) return
+    const previous = this.currentState
+    this.currentState = current
+    this.emit('connection-state-change', { previous, current })
+  }
+
+  private emitError(
+    code: CustomerSupportErrorCode,
+    message: string,
+    recoverable: boolean,
+  ): CustomerSupportErrorDetail {
+    const detail = { code, message, recoverable }
+    this.emit('error', detail)
+    return detail
+  }
+
+  private emit<K extends keyof CustomerSupportClientEventMap>(
+    type: K,
+    detail: CustomerSupportClientEventMap[K],
+  ): void {
+    for (const listener of this.listeners.get(type) ?? []) listener(detail)
+  }
+
+  private assertUsable(): void {
+    if (this.destroyed) {
+      throw new CustomerSupportClientError('CLIENT_DESTROYED', '客服客户端已经销毁。')
+    }
+  }
+}
+
+function validateRealtimeUrl(value: string): string {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    throw new CustomerSupportClientError('INVALID_CONFIGURATION', '客服实时地址无效。')
+  }
+  if (!['ws:', 'wss:'].includes(url.protocol) || url.search || url.hash || url.username) {
+    throw new CustomerSupportClientError('INVALID_CONFIGURATION', '客服实时地址不安全。')
+  }
+  return url.href
+}
+
+function normalizeReconnect(
+  value?: Partial<AiEmployeeReconnectOptions>,
+): AiEmployeeReconnectOptions {
+  return {
+    initialDelayMs: Math.max(0, value?.initialDelayMs ?? DEFAULT_RECONNECT.initialDelayMs),
+    maximumDelayMs: Math.max(1, value?.maximumDelayMs ?? DEFAULT_RECONNECT.maximumDelayMs),
+    factor: Math.max(1, value?.factor ?? DEFAULT_RECONNECT.factor),
+    jitter: Math.min(1, Math.max(0, value?.jitter ?? DEFAULT_RECONNECT.jitter)),
+  }
+}
+
+function compareMessages(left: CustomerSupportMessage, right: CustomerSupportMessage): number {
+  const leftSequence = Number(left.sequence)
+  const rightSequence = Number(right.sequence)
+  if (Number.isFinite(leftSequence) && Number.isFinite(rightSequence)) {
+    return leftSequence - rightSequence
+  }
+  return left.createdAt.localeCompare(right.createdAt)
+}
+
+function normalizeReadCursor(value: unknown): string | null {
+  const cursor = normalizedText(value)
+  if (!/^\d+$/.test(cursor)) return null
+  return cursor.replace(/^0+(?=\d)/, '')
+}
+
+function compareReadCursors(left: string, right: string): number {
+  if (left.length !== right.length) return left.length < right.length ? -1 : 1
+  if (left === right) return 0
+  return left < right ? -1 : 1
+}
+
+function maxReadCursor(left: string | null, right: string): string {
+  return left && compareReadCursors(left, right) >= 0 ? left : right
+}
+
+function hasCustomerSupportMessages(session: CustomerSupportSession): boolean {
+  return session.lastMessage.trim().length > 0
+}
+
+function requiredText(value: unknown, field: string): string {
+  const normalized = normalizedText(value)
+  if (!normalized) {
+    throw new CustomerSupportClientError('INVALID_CONFIGURATION', `${field} 不能为空。`)
+  }
+  return normalized
+}
+
+function requiredRequestId(value: string): string {
+  return requiredText(value, 'requestId')
+}
+
+function normalizedText(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function record(value: unknown): JsonRecord {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as JsonRecord)
+    : {}
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+function createRequestId(): string {
+  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `request-${Date.now()}-${Math.random().toString(16).slice(2)}`
+}
+
+function authenticationFailure(code: string): {
+  code: CustomerSupportErrorCode
+  message: string
+  retryMode: AuthenticationRetryMode
+} {
+  if (code === 'UNAUTHORIZED') {
+    return {
+      code: 'AUTHENTICATION_FAILED',
+      message: '客服连接凭证已失效，正在重新连接。',
+      retryMode: 'token',
+    }
+  }
+  if (code === 'ORGANIZATION_CONTEXT_REQUIRED') {
+    return {
+      code: 'ORGANIZATION_CONTEXT_REQUIRED',
+      message: '请选择企业/团队后再联系人工客服。',
+      retryMode: 'never',
+    }
+  }
+  if (code === 'INVALID_ARGUMENT') {
+    return {
+      code: 'PROTOCOL_ERROR',
+      message: '客服实时连接协议不受支持。',
+      retryMode: 'never',
+    }
+  }
+  if (
+    code === 'REALTIME_UNAVAILABLE' ||
+    code === 'KANBAN_AUTH_FAILED' ||
+    code.startsWith('SERVICE_')
+  ) {
+    return {
+      code: 'REALTIME_UNAVAILABLE',
+      message: '客服实时鉴权服务暂不可用，正在重试。',
+      retryMode: 'availability',
+    }
+  }
+  if (
+    code === 'ACCESS_DENIED' ||
+    code === 'ORIGIN_NOT_ALLOWED' ||
+    code === 'CHANNEL_ACCESS_DENIED'
+  ) {
+    return {
+      code: 'AUTHENTICATION_FAILED',
+      message: '当前身份无权使用人工客服。',
+      retryMode: 'never',
+    }
+  }
+  return {
+    code: 'AUTHENTICATION_FAILED',
+    message: '人工客服实时连接认证失败。',
+    retryMode: 'never',
+  }
+}