@csntgao/uni-base 0.6.3 → 0.6.5

package/packages/web-components/src/chat.ts

@@ -1,15 +1,20 @@
 import {
   AiEmployeeClient,
   AiEmployeeClientError,
+  parseAiEmployeeAssistantContent,
   type AiEmployeeClientErrorDetail,
   type AiEmployeeClientOptions,
   type AiEmployeeConnectionState,
   type AiEmployeeMessage,
   type AiEmployeeSessionSummary,
+  type OpenCustomerSupportAssistantAction,
 } from '@uniplat/ai-employee-client'
 import { LitElement, css, html, nothing, type PropertyValues } from 'lit'
 import type { UniplatCustomerSupportChat, CustomerSupportChatConfig } from './customer-support-chat'
-import { createHrSaasCustomerSupportTransport } from './customer-support-transport'
+import {
+  createHrSaasCustomerSupportTransport,
+  HrSaasCustomerSupportTransportError,
+} from './customer-support-transport'
 import { prototypeIcon } from './prototype-icons'
 import { renderSafeMarkdown } from './safe-markdown'
 
@@ -22,6 +27,11 @@ interface LocalReadBoundary {
   updatedAtMs: number
 }
 
+interface CustomerSupportHandoffUiState {
+  status: 'loading' | 'failed' | 'succeeded'
+  message: string
+}
+
 const AI_ADVISOR_TITLE = '企业服务AI顾问'
 
 export interface AiEmployeeChatEventMap {
@@ -50,6 +60,7 @@ export class UniplatAiEmployeeChat extends LitElement {
     switchingSessionId: { state: true },
     creatingSession: { state: true },
     customerSupportOpen: { state: true },
+    customerSupportHandoffStates: { state: true },
   }
 
   static override styles = css`
@@ -635,6 +646,55 @@ export class UniplatAiEmployeeChat extends LitElement {
       text-underline-offset: 2px;
     }
 
+    .assistant-action {
+      display: flex;
+      align-items: flex-start;
+      flex-direction: column;
+      gap: 6px;
+      margin-top: 8px;
+    }
+
+    .assistant-action-button {
+      display: inline-flex;
+      min-height: 36px;
+      align-items: center;
+      justify-content: center;
+      gap: 7px;
+      padding: 7px 13px;
+      border: 1px solid color-mix(in srgb, var(--uniplat-chat-primary), transparent 58%);
+      border-radius: 9px;
+      outline: none;
+      background: #f0f5ff;
+      color: var(--uniplat-chat-primary);
+      cursor: pointer;
+      font: inherit;
+      font-size: 13px;
+      font-weight: 700;
+    }
+
+    .assistant-action-button:hover,
+    .assistant-action-button:focus-visible {
+      border-color: var(--uniplat-chat-primary);
+      background: #e6efff;
+    }
+
+    .assistant-action-button:disabled {
+      cursor: wait;
+      opacity: 0.65;
+    }
+
+    .assistant-action-button svg {
+      width: 16px;
+      height: 16px;
+    }
+
+    .assistant-action-error {
+      max-width: 280px;
+      color: var(--uniplat-chat-error);
+      font-size: 12px;
+      line-height: 1.5;
+    }
+
     .empty,
     .loading {
       display: grid;
@@ -778,6 +838,7 @@ export class UniplatAiEmployeeChat extends LitElement {
   declare private switchingSessionId: string
   declare private creatingSession: boolean
   declare private customerSupportOpen: boolean
+  declare private customerSupportHandoffStates: ReadonlyMap<string, CustomerSupportHandoffUiState>
   private config: AiEmployeeChatConfig | null = null
   private client: AiEmployeeClient | null = null
   private clientUnsubscribers: Array<() => void> = []
@@ -785,7 +846,13 @@ export class UniplatAiEmployeeChat extends LitElement {
   private sessionListGeneration = 0
   private readyDispatched = false
   private readSyncGeneration = 0
+  private customerSupportHandoffGeneration = 0
   private readonly localMessageIds = new Set<string>()
+  /**
+   * 只有来自 HTTP 历史与会话列表的消息 ID 是服务端持久化 ID，实时事件里的
+   * ws_message_id / 合成 ID 不能用于已读同步，服务端会以 INVALID_ARGUMENT 拒绝。
+   */
+  private readonly persistedMessageIds = new Set<string>()
   private readonly locallyReadBoundaries = new Map<string, LocalReadBoundary>()
   private readonly confirmedReadMessageIds = new Map<string, string>()
   private readonly queuedReadMessageIds = new Map<string, string>()
@@ -813,9 +880,11 @@ export class UniplatAiEmployeeChat extends LitElement {
     this.switchingSessionId = ''
     this.creatingSession = false
     this.customerSupportOpen = false
+    this.customerSupportHandoffStates = new Map()
   }
 
   configure(config: AiEmployeeChatConfig): void {
+    this.customerSupportHandoffGeneration += 1
     this.config = config
     this.releaseClient()
     this.resetView()
@@ -838,6 +907,7 @@ export class UniplatAiEmployeeChat extends LitElement {
     if (!this.drawerOpen) return
     this.drawerOpen = false
     this.pendingInitialMessage = ''
+    this.customerSupportHandoffGeneration += 1
     window.removeEventListener('keydown', this.handleWindowKeyDown)
     this.releaseClient()
   }
@@ -848,6 +918,7 @@ export class UniplatAiEmployeeChat extends LitElement {
   }
 
   override disconnectedCallback(): void {
+    this.customerSupportHandoffGeneration += 1
     window.removeEventListener('keydown', this.handleWindowKeyDown)
     this.releaseClient()
     super.disconnectedCallback()
@@ -1039,7 +1110,9 @@ export class UniplatAiEmployeeChat extends LitElement {
           >
             <span class="session-item-icon" aria-hidden="true">${prototypeIcon('robot')}</span>
             <span class="session-item-title">${session.title}</span>
-            <span class="session-item-preview">${session.latestMessage || '暂无消息'}</span>
+            <span class="session-item-preview"
+              >${sessionPreview(session.latestMessage) || '暂无消息'}</span
+            >
             <span class="session-item-side">
               <span>${formatRelativeTime(session.updatedAt)}</span>
               ${
@@ -1089,6 +1162,10 @@ export class UniplatAiEmployeeChat extends LitElement {
         </div>
       `
     }
+    const parsed =
+      message.role === 'assistant'
+        ? parseAiEmployeeAssistantContent(message.content)
+        : { content: message.content, actions: [] }
     return html`
       <div class="message-row ${message.role}">
         <div class="assistant-message">
@@ -1097,19 +1174,60 @@ export class UniplatAiEmployeeChat extends LitElement {
             <span class="assistant-label"
               >${message.role === 'error' ? '系统提示' : '在线顾问'}</span
             >
-            <div
-              class="message ${message.role} ${message.role === 'assistant' ? 'markdown' : ''}"
-              part="message message-${message.role}"
-              data-message-id=${message.id}
-            >
-              ${message.role === 'assistant' ? renderSafeMarkdown(message.content) : message.content}
-            </div>
+            ${
+              parsed.content
+                ? html`<div
+                    class="message ${message.role} ${
+                      message.role === 'assistant' ? 'markdown' : ''
+                    }"
+                    part="message message-${message.role}"
+                    data-message-id=${message.id}
+                  >
+                    ${
+                      message.role === 'assistant'
+                        ? renderSafeMarkdown(parsed.content)
+                        : parsed.content
+                    }
+                  </div>`
+                : nothing
+            }
+            ${
+              message.role === 'assistant'
+                ? parsed.actions.map((action) => this.renderAssistantAction(message, action))
+                : nothing
+            }
           </div>
         </div>
       </div>
     `
   }
 
+  private renderAssistantAction(
+    message: AiEmployeeMessage,
+    action: OpenCustomerSupportAssistantAction,
+  ) {
+    const state = this.customerSupportHandoffStates.get(action.transactionId)
+    const loading = state?.status === 'loading'
+    const succeeded = state?.status === 'succeeded'
+    return html`<div class="assistant-action" part="assistant-action">
+      <button
+        class="assistant-action-button"
+        part="assistant-action-button"
+        type="button"
+        ?disabled=${loading || succeeded}
+        @click=${() => void this.handleCustomerSupportHandoff(message, action)}
+      >
+        ${prototypeIcon(succeeded ? 'circle-check-filled' : 'headset')}
+        ${loading ? '正在发起人工客服…' : succeeded ? '已发起人工客服' : '发起人工客服'}
+      </button>
+      ${
+        state?.status === 'failed'
+          ? html`<span class="assistant-action-error" role="status">${state.message}</span>`
+          : nothing
+      }
+    </div>`
+  }
+
   private async startClient(): Promise<void> {
     const config = this.config
     if (!config || this.client || !this.isConnected) return
@@ -1159,6 +1277,7 @@ export class UniplatAiEmployeeChat extends LitElement {
       client.on('history', ({ sessionId, messages }) => {
         if (this.client !== client) return
         this.messages = messages
+        for (const message of messages) this.persistedMessageIds.add(message.id)
         if (this.isCurrentConversationVisible(sessionId)) void this.markCurrentSessionRead()
       }),
       client.on('message', ({ sessionId, message, source }) => {
@@ -1180,7 +1299,14 @@ export class UniplatAiEmployeeChat extends LitElement {
         this.dispatchPublicEvent('connection-state-change', { state: current })
       }),
       client.on('processing-state-change', ({ processing }) => {
-        if (this.client === client) this.processing = processing
+        if (this.client !== client) return
+        const finished = this.processing && !processing
+        this.processing = processing
+        // 实时事件只带 ws_message_id；本轮结束后重新取一次历史，
+        // 才能用持久化 ID 同步已读。
+        if (finished && this.isCurrentConversationVisible(client.sessionId ?? '')) {
+          void client.refreshMessages().catch(() => undefined)
+        }
       }),
       client.on('title', ({ sessionId, title }) => {
         if (this.client !== client) return
@@ -1252,6 +1378,9 @@ export class UniplatAiEmployeeChat extends LitElement {
     try {
       const sessions = normalizeSessionSummaries(await listSessions.call(transport))
       if (!this.isCurrentSessionList(generation)) return
+      for (const session of sessions) {
+        if (session.latestMessageId) this.persistedMessageIds.add(session.latestMessageId)
+      }
       const mergedSessions = mergeCurrentSession(sessions, this.currentSessionSummary())
       this.sessions = this.applyLocallyReadState(mergedSessions)
       const currentSession = mergedSessions.find(
@@ -1390,11 +1519,14 @@ export class UniplatAiEmployeeChat extends LitElement {
     const summary: AiEmployeeSessionSummary = {
       sessionId: message.sessionId,
       title: existing?.title || this.chatTitle || '新对话',
-      latestMessage: message.content,
+      latestMessage: messagePreview(message),
       updatedAt: message.createdAt,
       unreadCount: visible ? 0 : Math.max(0, (existing?.unreadCount ?? 0) + unreadIncrement),
     }
-    const latestMessageId = source === 'local' ? existing?.latestMessageId : message.id
+    // 实时消息 ID 不是持久化 ID，不能当作已读游标。
+    const latestMessageId = this.persistedMessageIds.has(message.id)
+      ? message.id
+      : existing?.latestMessageId
     if (latestMessageId) summary.latestMessageId = latestMessageId
     this.sessions = [
       summary,
@@ -1410,7 +1542,7 @@ export class UniplatAiEmployeeChat extends LitElement {
     let latestServerMessage: AiEmployeeMessage | undefined
     for (let index = this.messages.length - 1; index >= 0; index -= 1) {
       const candidate = this.messages[index]
-      if (candidate && !this.localMessageIds.has(candidate.id)) {
+      if (candidate && this.persistedMessageIds.has(candidate.id)) {
         latestServerMessage = candidate
         break
       }
@@ -1418,7 +1550,7 @@ export class UniplatAiEmployeeChat extends LitElement {
     const summary: AiEmployeeSessionSummary = {
       sessionId,
       title: this.chatTitle || '新对话',
-      latestMessage: latestMessage?.content ?? '',
+      latestMessage: latestMessage ? messagePreview(latestMessage) : '',
       updatedAt: latestMessage?.createdAt ?? new Date().toISOString(),
       unreadCount: 0,
     }
@@ -1495,6 +1627,48 @@ export class UniplatAiEmployeeChat extends LitElement {
       })
       return
     }
+    this.openCustomerSupport(customerSupport)
+  }
+
+  private async handleCustomerSupportHandoff(
+    message: AiEmployeeMessage,
+    action: OpenCustomerSupportAssistantAction,
+  ): Promise<void> {
+    const key = action.transactionId
+    const currentState = this.customerSupportHandoffStates.get(key)
+    if (currentState?.status === 'loading' || currentState?.status === 'succeeded') return
+    const customerSupport = this.resolveCustomerSupportConfig()
+    const createHandoffSession = customerSupport?.transport.createHandoffSession
+    if (!customerSupport || !createHandoffSession) {
+      const detail: AiEmployeeClientErrorDetail = {
+        code: 'CUSTOMER_SUPPORT_UNAVAILABLE',
+        message: '人工客服转接暂未配置。',
+        recoverable: false,
+      }
+      this.setCustomerSupportHandoffState(key, { status: 'failed', message: detail.message })
+      this.dispatchPublicEvent('error', detail)
+      return
+    }
+
+    const generation = this.customerSupportHandoffGeneration
+    this.setCustomerSupportHandoffState(key, { status: 'loading', message: '' })
+    try {
+      const result = await createHandoffSession.call(customerSupport.transport, {
+        sourceSessionId: message.sessionId,
+        actionTransactionId: action.transactionId,
+      })
+      if (!this.isCurrentCustomerSupportHandoff(generation, message.sessionId)) return
+      this.setCustomerSupportHandoffState(key, { status: 'succeeded', message: '' })
+      this.openCustomerSupport({ ...customerSupport, sessionId: result.session.id })
+    } catch (error) {
+      if (!this.isCurrentCustomerSupportHandoff(generation, message.sessionId)) return
+      const detail = customerSupportHandoffError(error)
+      this.setCustomerSupportHandoffState(key, { status: 'failed', message: detail.message })
+      this.dispatchPublicEvent('error', detail)
+    }
+  }
+
+  private openCustomerSupport(customerSupport: CustomerSupportChatConfig): void {
     this.releaseClient()
     this.customerSupportOpen = true
     void this.updateComplete.then(() => {
@@ -1507,6 +1681,20 @@ export class UniplatAiEmployeeChat extends LitElement {
     })
   }
 
+  private setCustomerSupportHandoffState(key: string, state: CustomerSupportHandoffUiState): void {
+    const next = new Map(this.customerSupportHandoffStates)
+    next.set(key, state)
+    this.customerSupportHandoffStates = next
+  }
+
+  private isCurrentCustomerSupportHandoff(generation: number, sessionId: string): boolean {
+    return (
+      generation === this.customerSupportHandoffGeneration &&
+      this.drawerOpen &&
+      this.client?.sessionId === sessionId
+    )
+  }
+
   private resolveCustomerSupportConfig(): CustomerSupportChatConfig | null {
     const config = this.config
     if (!config) return null
@@ -1603,6 +1791,7 @@ export class UniplatAiEmployeeChat extends LitElement {
   private resetView(): void {
     this.readSyncGeneration += 1
     this.localMessageIds.clear()
+    this.persistedMessageIds.clear()
     this.locallyReadBoundaries.clear()
     this.confirmedReadMessageIds.clear()
     this.queuedReadMessageIds.clear()
@@ -1619,9 +1808,72 @@ export class UniplatAiEmployeeChat extends LitElement {
     this.switchingSessionId = ''
     this.creatingSession = false
     this.connectionState = 'idle'
+    this.customerSupportHandoffStates = new Map()
   }
 }
 
+function customerSupportHandoffError(error: unknown): AiEmployeeClientErrorDetail {
+  if (error instanceof HrSaasCustomerSupportTransportError) {
+    if (error.code === 'SOURCE_SESSION_NOT_FOUND') {
+      return {
+        code: 'SOURCE_SESSION_NOT_FOUND',
+        message: '来源会话不存在，请刷新后重试。',
+        recoverable: false,
+      }
+    }
+    if (error.code === 'SOURCE_SESSION_ACCESS_DENIED') {
+      return {
+        code: 'SOURCE_SESSION_ACCESS_DENIED',
+        message: '当前身份无权转接此会话。',
+        recoverable: false,
+      }
+    }
+    if (error.code === 'HANDOFF_ACTION_NOT_FOUND') {
+      return {
+        code: 'HANDOFF_ACTION_NOT_FOUND',
+        message: '该人工客服入口已失效，请刷新会话后重试。',
+        recoverable: false,
+      }
+    }
+    if (error.code === 'HANDOFF_ACTION_MISMATCH') {
+      return {
+        code: 'HANDOFF_ACTION_MISMATCH',
+        message: '转接状态已变化，请刷新会话后重试。',
+        recoverable: true,
+      }
+    }
+    if (error.code === 'AUTH_REQUIRED' || error.code === 'UNAUTHORIZED') {
+      return {
+        code: 'AUTHENTICATION_FAILED',
+        message: '登录状态已失效，请重新登录后再试。',
+        recoverable: true,
+      }
+    }
+    if (error.code === 'CUSTOMER_SUPPORT_UNAVAILABLE' || error.code === 'REQUEST_FAILED') {
+      return {
+        code: 'CUSTOMER_SUPPORT_UNAVAILABLE',
+        message: '人工客服暂时不可用，请稍后重试。',
+        recoverable: true,
+      }
+    }
+  }
+  return {
+    code: 'CUSTOMER_SUPPORT_HANDOFF_FAILED',
+    message: '人工客服转接失败，请稍后重试。',
+    recoverable: true,
+  }
+}
+
+function messagePreview(message: AiEmployeeMessage): string {
+  return message.role === 'assistant' ? sessionPreview(message.content) : message.content
+}
+
+function sessionPreview(content: string): string {
+  const parsed = parseAiEmployeeAssistantContent(content)
+  if (parsed.actions.length === 0) return content
+  return parsed.content || '可发起人工客服'
+}
+
 function formatMessageTime(value: string): string {
   const date = new Date(value)
   if (Number.isNaN(date.getTime())) return ''

package/packages/web-components/src/customer-support-transport.ts

@@ -1,6 +1,7 @@
 import type {
   CustomerSupportAgent,
   CustomerSupportCreateSessionResult,
+  CustomerSupportHandoffResult,
   CustomerSupportMessage,
   CustomerSupportMessagePage,
   CustomerSupportSenderType,
@@ -8,6 +9,7 @@ import type {
   CustomerSupportSessionStatus,
   CustomerSupportTransport,
 } from '@uniplat/ai-employee-client'
+import { isUuidV4 } from '@uniplat/ai-employee-client'
 
 export interface HrSaasCustomerSupportTransportOptions {
   serviceBaseUrl: string
@@ -15,8 +17,30 @@ export interface HrSaasCustomerSupportTransportOptions {
   fetch?: typeof fetch
 }
 
+export type HrSaasCustomerSupportTransportErrorCode =
+  | 'AUTH_REQUIRED'
+  | 'SOURCE_SESSION_NOT_FOUND'
+  | 'SOURCE_SESSION_ACCESS_DENIED'
+  | 'HANDOFF_ACTION_NOT_FOUND'
+  | 'HANDOFF_ACTION_MISMATCH'
+  | 'UNAUTHORIZED'
+  | 'CUSTOMER_SUPPORT_UNAVAILABLE'
+  | 'REQUEST_FAILED'
+  | 'INVALID_RESPONSE'
+
+export class HrSaasCustomerSupportTransportError extends Error {
+  readonly code: HrSaasCustomerSupportTransportErrorCode
+
+  constructor(code: HrSaasCustomerSupportTransportErrorCode) {
+    super('Customer support request failed')
+    this.name = 'HrSaasCustomerSupportTransportError'
+    this.code = code
+  }
+}
+
 const SESSION_PAGE_ACTION = 'user_session_page'
 const SESSION_CREATE_ACTION = 'user_session_create'
+const SESSION_HANDOFF_CREATE_ACTION = 'user_session_handoff_create'
 const SESSION_DETAIL_ACTION = 'user_session_detail'
 const MESSAGE_PAGE_ACTION = 'user_message_page'
 const MESSAGE_SEND_ACTION = 'user_message_send'
@@ -63,6 +87,37 @@ export function createHrSaasCustomerSupportTransport(
       if (parsedInitialMessage) result.initialMessage = parsedInitialMessage
       return result
     },
+    async createHandoffSession(handoffRequest) {
+      const sourceSessionId = requiredText(handoffRequest.sourceSessionId, 128)
+      const actionTransactionId = requiredText(handoffRequest.actionTransactionId, 36)
+      if (!isUuidV4(actionTransactionId)) {
+        throw new HrSaasCustomerSupportTransportError('INVALID_RESPONSE')
+      }
+      const data = record(
+        await request(SESSION_HANDOFF_CREATE_ACTION, {
+          source_session_id: sourceSessionId,
+          action_transaction_id: actionTransactionId,
+        }),
+      )
+      const session = parseSession(data.session)
+      const initialMessage = parseMessage(data.initial_message)
+      if (
+        !session ||
+        !initialMessage ||
+        initialMessage.sessionId !== session.id ||
+        typeof data.created !== 'boolean' ||
+        typeof data.repaired !== 'boolean'
+      ) {
+        throw new HrSaasCustomerSupportTransportError('INVALID_RESPONSE')
+      }
+      const result: CustomerSupportHandoffResult = {
+        session,
+        initialMessage,
+        created: data.created,
+        repaired: data.repaired,
+      }
+      return result
+    },
     async getSession(sessionId) {
       const data = await request(SESSION_DETAIL_ACTION, {
         session_id: requiredText(sessionId, 128),
@@ -169,27 +224,74 @@ async function requestData(
   accessToken: string,
   body: Record<string, unknown>,
 ): Promise<unknown> {
-  if (!fetchImplementation) throw new Error('Fetch is unavailable')
-  const response = await fetchImplementation(endpoint, {
-    method: 'POST',
-    credentials: 'include',
-    headers: {
-      accept: 'application/json',
-      authorization: `Bearer ${accessToken}`,
-      'content-type': 'application/json',
-    },
-    body: JSON.stringify(body),
-  })
-  if (!response.ok) throw new Error('Customer support request failed')
-  const payload: unknown = await response.json()
+  if (!fetchImplementation) throw new HrSaasCustomerSupportTransportError('REQUEST_FAILED')
+  let response: Response
+  try {
+    response = await fetchImplementation(endpoint, {
+      method: 'POST',
+      credentials: 'include',
+      headers: {
+        accept: 'application/json',
+        authorization: `Bearer ${accessToken}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+  } catch {
+    throw new HrSaasCustomerSupportTransportError('REQUEST_FAILED')
+  }
+  let payload: unknown = null
+  try {
+    payload = await response.json()
+  } catch {
+    if (!response.ok) throw transportResponseError({}, response.status)
+    throw new HrSaasCustomerSupportTransportError('INVALID_RESPONSE')
+  }
   const envelope = record(payload)
+  if (!response.ok) throw transportResponseError(envelope, response.status)
   if ('rescode' in envelope) {
-    if (Number(envelope.rescode) !== 0) throw new Error('Customer support request failed')
+    if (Number(envelope.rescode) !== 0) {
+      throw transportResponseError(envelope, response.status)
+    }
     return envelope.data
   }
   return payload
 }
 
+function transportResponseError(
+  envelope: Record<string, unknown>,
+  status: number,
+): HrSaasCustomerSupportTransportError {
+  const detail = record(envelope.data)
+  const error = record(envelope.error)
+  const candidate = [
+    envelope.error_code,
+    envelope.code,
+    detail.error_code,
+    detail.code,
+    error.error_code,
+    error.code,
+  ].find((value) => typeof value === 'string' && value.trim())
+  const code = typeof candidate === 'string' ? candidate.trim().toUpperCase() : ''
+  if (isTransportErrorCode(code)) return new HrSaasCustomerSupportTransportError(code)
+  if (status === 401) return new HrSaasCustomerSupportTransportError('UNAUTHORIZED')
+  if (status === 503) {
+    return new HrSaasCustomerSupportTransportError('CUSTOMER_SUPPORT_UNAVAILABLE')
+  }
+  return new HrSaasCustomerSupportTransportError('REQUEST_FAILED')
+}
+
+function isTransportErrorCode(value: string): value is HrSaasCustomerSupportTransportErrorCode {
+  return [
+    'SOURCE_SESSION_NOT_FOUND',
+    'SOURCE_SESSION_ACCESS_DENIED',
+    'HANDOFF_ACTION_NOT_FOUND',
+    'HANDOFF_ACTION_MISMATCH',
+    'UNAUTHORIZED',
+    'CUSTOMER_SUPPORT_UNAVAILABLE',
+  ].includes(value)
+}
+
 function validateServiceBaseUrl(value: string): string {
   const raw = typeof value === 'string' ? value.trim() : ''
   if (!raw) throw new TypeError('Customer support serviceBaseUrl is required')
@@ -216,7 +318,7 @@ async function resolveAccessToken(provider: () => string | Promise<string>): Pro
   } catch {
     // Provider details may contain credentials and are intentionally discarded.
   }
-  if (!value) throw new Error('Access token is unavailable')
+  if (!value) throw new HrSaasCustomerSupportTransportError('AUTH_REQUIRED')
   return value
 }
 

package/packages/web-components/src/index.ts

@@ -77,8 +77,20 @@ export type {
   CustomerSupportChatConfig,
   CustomerSupportChatEventMap,
 } from './customer-support-chat'
-export { createHrSaasCustomerSupportTransport } from './customer-support-transport'
-export type { HrSaasCustomerSupportTransportOptions } from './customer-support-transport'
+export {
+  createHrSaasCustomerSupportTransport,
+  HrSaasCustomerSupportTransportError,
+} from './customer-support-transport'
+export type {
+  HrSaasCustomerSupportTransportErrorCode,
+  HrSaasCustomerSupportTransportOptions,
+} from './customer-support-transport'
+export { isUuidV4, parseAiEmployeeAssistantContent } from '@uniplat/ai-employee-client'
+export type {
+  AiEmployeeAssistantAction,
+  OpenCustomerSupportAssistantAction,
+  ParsedAiEmployeeAssistantContent,
+} from '@uniplat/ai-employee-client'
 export type {
   NotificationCenterConfig,
   NotificationCenterEventMap,