@csntgao/uni-base 0.1.0

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

@@ -0,0 +1,123 @@
+import type { AiEmployeeConnectionState, AiEmployeeReconnectOptions } from './types'
+
+export type CustomerSupportSessionStatus = 'waiting' | 'active' | 'closed'
+export type CustomerSupportSenderType = 'customer' | 'agent' | 'system'
+
+export interface CustomerSupportAgent {
+  id: string
+  name: string
+  avatarUrl: string
+  roleName: string
+}
+
+export interface CustomerSupportMessage {
+  id: string
+  sessionId: string
+  sequence: string
+  clientMessageId: string
+  senderType: CustomerSupportSenderType
+  senderName: string
+  content: string
+  createdAt: string
+}
+
+export interface CustomerSupportSession {
+  id: string
+  sessionNo: string
+  title: string
+  status: CustomerSupportSessionStatus
+  statusText: string
+  primaryAgent: CustomerSupportAgent | null
+  lastMessage: string
+  unreadCount: number
+  openedAt: string
+  updatedAt: string
+  version: string
+}
+
+export interface CustomerSupportMessagePage {
+  messages: readonly CustomerSupportMessage[]
+  latestSequence: string
+  sessionVersion: string
+}
+
+export interface CustomerSupportCreateSessionRequest {
+  clientRequestId: string
+  title?: string
+  initialMessage?: string
+}
+
+export interface CustomerSupportCreateSessionResult {
+  session: CustomerSupportSession
+  initialMessage?: CustomerSupportMessage
+}
+
+export interface CustomerSupportTransport {
+  getAccessToken(): Promise<string>
+  listSessions(): Promise<readonly CustomerSupportSession[]>
+  getSession?(sessionId: string): Promise<CustomerSupportSession>
+  createSession(
+    request: CustomerSupportCreateSessionRequest,
+  ): Promise<CustomerSupportCreateSessionResult>
+  listMessages(sessionId: string): Promise<CustomerSupportMessagePage>
+  sendMessage(
+    sessionId: string,
+    clientMessageId: string,
+    content: string,
+  ): Promise<CustomerSupportMessage>
+  markRead?(sessionId: string, lastReadSequence: string): Promise<void>
+}
+
+export interface CustomerSupportClientOptions {
+  realtimeUrl: string
+  transport: CustomerSupportTransport
+  sessionId?: string
+  reconnect?: Partial<AiEmployeeReconnectOptions>
+  webSocketFactory?: (url: string) => WebSocket
+  requestIdFactory?: () => string
+  minimumHeartbeatMs?: number
+}
+
+export type CustomerSupportErrorCode =
+  | 'INVALID_CONFIGURATION'
+  | 'SESSION_UNAVAILABLE'
+  | 'HISTORY_LOAD_FAILED'
+  | 'TOKEN_UNAVAILABLE'
+  | 'WEBSOCKET_UNAVAILABLE'
+  | 'WEBSOCKET_ERROR'
+  | 'AUTHENTICATION_FAILED'
+  | 'ORGANIZATION_CONTEXT_REQUIRED'
+  | 'REALTIME_UNAVAILABLE'
+  | 'CHANNEL_UNAVAILABLE'
+  | 'PROTOCOL_ERROR'
+  | 'SEND_FAILED'
+  | 'SEND_IN_PROGRESS'
+  | 'EMPTY_MESSAGE'
+  | 'CLIENT_DESTROYED'
+
+export interface CustomerSupportErrorDetail {
+  code: CustomerSupportErrorCode
+  message: string
+  recoverable: boolean
+}
+
+export interface CustomerSupportClientEventMap {
+  ready: { sessionId: string | null }
+  sessions: { sessions: readonly CustomerSupportSession[] }
+  session: { session: CustomerSupportSession }
+  history: { sessionId: string; messages: readonly CustomerSupportMessage[] }
+  message: {
+    sessionId: string
+    message: CustomerSupportMessage
+    source: 'local' | 'realtime'
+  }
+  'connection-state-change': {
+    previous: AiEmployeeConnectionState
+    current: AiEmployeeConnectionState
+  }
+  error: CustomerSupportErrorDetail
+}
+
+export type CustomerSupportClientListener<K extends keyof CustomerSupportClientEventMap> = (
+  detail: CustomerSupportClientEventMap[K],
+) => void

package/packages/core/src/index.ts

@@ -0,0 +1,79 @@
+export { AiEmployeeClient, AiEmployeeClientError, AiEmployeeTransportError } from './client'
+export { CustomerSupportClient, CustomerSupportClientError } from './customer-support-client'
+export {
+  NotificationCenterClient,
+  NotificationCenterClientError,
+} from './notification-center-client'
+export {
+  createAuthenticateFrame,
+  createPingFrame,
+  createSubscriptionFrame,
+  hashText,
+  parseAiEmployeeEvent,
+  parseJsonRecord,
+} from './protocol'
+export type {
+  AuthenticateFrame,
+  ParsedAiEmployeeEvent,
+  ParsedSessionMessage,
+  PingFrame,
+  SessionSubscriptionFrame,
+} from './protocol'
+export type {
+  AiEmployeeClientErrorDetail,
+  AiEmployeeClientEventMap,
+  AiEmployeeClientListener,
+  AiEmployeeClientOptions,
+  AiEmployeeClientStartResult,
+  AiEmployeeAttachmentReference,
+  AiEmployeeConnectionState,
+  AiEmployeeErrorCode,
+  AiEmployeeFirstMessageOptions,
+  AiEmployeeFirstMessageRequest,
+  AiEmployeeFirstMessageRequestState,
+  AiEmployeeFirstMessageRequestStore,
+  AiEmployeeFirstMessageResult,
+  AiEmployeeMessage,
+  AiEmployeeMessageRole,
+  AiEmployeeReconnectOptions,
+  AiEmployeeSessionSummary,
+  AiEmployeeTransport,
+  AiEmployeeTransportErrorCode,
+  AiEmployeeWebSocketFactory,
+} from './types'
+export type {
+  CustomerSupportAgent,
+  CustomerSupportClientEventMap,
+  CustomerSupportClientListener,
+  CustomerSupportClientOptions,
+  CustomerSupportCreateSessionRequest,
+  CustomerSupportCreateSessionResult,
+  CustomerSupportErrorCode,
+  CustomerSupportErrorDetail,
+  CustomerSupportMessage,
+  CustomerSupportMessagePage,
+  CustomerSupportSenderType,
+  CustomerSupportSession,
+  CustomerSupportSessionStatus,
+  CustomerSupportTransport,
+} from './customer-support-types'
+export type {
+  NotificationAttachment,
+  NotificationCenterClientEventMap,
+  NotificationCenterClientListener,
+  NotificationCenterClientOptions,
+  NotificationCenterErrorCode,
+  NotificationCenterErrorDetail,
+  NotificationCenterTransport,
+  NotificationContentType,
+  NotificationDto,
+  NotificationInboxQuery,
+  NotificationInboxResult,
+  NotificationMarkAllReadResult,
+  NotificationMarkReadResult,
+  NotificationReadStatus,
+  NotificationRealtimeChange,
+  NotificationResource,
+  NotificationSource,
+  NotificationTypeSummary,
+} from './notification-center-types'

package/packages/core/src/notification-center-client.ts

@@ -0,0 +1,462 @@
+import type {
+  NotificationCenterClientEventMap,
+  NotificationCenterClientListener,
+  NotificationCenterClientOptions,
+  NotificationCenterErrorCode,
+  NotificationCenterErrorDetail,
+  NotificationCenterTransport,
+  NotificationDto,
+  NotificationRealtimeChange,
+  NotificationTypeSummary,
+} from './notification-center-types'
+
+type UntypedListener = (detail: unknown) => void
+
+const DEFAULT_PAGE_SIZE = 20
+
+export class NotificationCenterClientError extends Error {
+  readonly code: NotificationCenterErrorCode
+
+  constructor(code: NotificationCenterErrorCode, message: string) {
+    super(message)
+    this.name = 'NotificationCenterClientError'
+    this.code = code
+  }
+}
+
+/**
+ * Inbox store and HTTP orchestration for the notification center.
+ *
+ * The client owns no realtime connection. The host keeps the single
+ * `/api/user-realtime/ws` socket it already maintains for its other channels and
+ * hands notification events in through {@link applyRealtimeEvent}; cursors,
+ * heartbeats, authentication and reconnect stay on the host side.
+ */
+export class NotificationCenterClient {
+  private readonly transport: NotificationCenterTransport
+  private readonly applicationName: string
+  private readonly pageSize: number
+  private readonly readStatus: 'all' | 'unread' | 'read'
+  private readonly preferredTypeOrder: readonly string[]
+  private readonly listeners = new Map<
+    keyof NotificationCenterClientEventMap,
+    Set<UntypedListener>
+  >()
+
+  private items: NotificationDto[] = []
+  private hasMore = false
+  private nextId: string | null = null
+  private unreadCount = 0
+  private notificationTypes: string[] = []
+  private availableTypes: NotificationTypeSummary[] = []
+  private typeCatalogFromBackend = false
+  private inboxGeneration = 0
+  private destroyed = false
+  private loadingInbox = false
+  private pendingResync = false
+
+  constructor(options: NotificationCenterClientOptions) {
+    if (!options?.transport) {
+      throw new NotificationCenterClientError(
+        'INVALID_CONFIGURATION',
+        '缺少通知中心 transport 配置。',
+      )
+    }
+    this.transport = options.transport
+    this.applicationName = normalizedText(options.applicationName)
+    this.pageSize = Math.max(1, Math.floor(options.pageSize ?? DEFAULT_PAGE_SIZE))
+    this.readStatus = ['all', 'unread', 'read'].includes(options.readStatus ?? '')
+      ? (options.readStatus as 'all' | 'unread' | 'read')
+      : 'all'
+    this.preferredTypeOrder = (options.preferredTypeOrder ?? [])
+      .map((value) => normalizedText(value))
+      .filter(Boolean)
+  }
+
+  get notifications(): readonly NotificationDto[] {
+    return [...this.items]
+  }
+
+  get unread(): number {
+    return this.unreadCount
+  }
+
+  /** 数据中实际存在的通知分类，供 UI 渲染页签；不是写死的枚举。 */
+  get types(): readonly NotificationTypeSummary[] {
+    return this.availableTypes.map((entry) => ({ ...entry }))
+  }
+
+  on<K extends keyof NotificationCenterClientEventMap>(
+    type: K,
+    listener: NotificationCenterClientListener<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()
+    await Promise.all([this.reloadInbox(), this.refreshUnreadCount()])
+    this.emit('ready', {})
+  }
+
+  async setTypeFilter(types: readonly string[]): Promise<void> {
+    this.assertUsable()
+    this.notificationTypes = [...types].map((value) => normalizedText(value)).filter(Boolean)
+    await this.reloadInbox()
+  }
+
+  getTypeFilter(): readonly string[] {
+    return [...this.notificationTypes]
+  }
+
+  async loadMore(): Promise<void> {
+    this.assertUsable()
+    if (!this.hasMore || this.loadingInbox || !this.nextId) return
+    const generation = this.inboxGeneration
+    this.loadingInbox = true
+    try {
+      const result = await this.transport.listInbox({
+        pageSize: this.pageSize,
+        beforeId: this.nextId,
+        notificationTypes: this.notificationTypes,
+        readStatus: this.readStatus,
+        applicationName: this.applicationName,
+      })
+      if (this.destroyed || generation !== this.inboxGeneration) return
+      const existing = new Set(this.items.map((item) => item.id))
+      const merged = [...this.items]
+      for (const item of result.items) {
+        if (!existing.has(item.id)) {
+          existing.add(item.id)
+          merged.push(item)
+        }
+      }
+      this.items = merged
+      this.hasMore = result.hasMore
+      this.nextId = result.nextId
+      this.rememberTypes(result.items)
+      this.emitInbox()
+    } catch {
+      this.emitError('INBOX_LOAD_FAILED', '通知加载失败，请稍后重试。', true)
+    } finally {
+      if (generation === this.inboxGeneration) this.finishInboxLoad()
+    }
+  }
+
+  async refresh(): Promise<void> {
+    this.assertUsable()
+    await Promise.all([this.reloadInbox(), this.refreshUnreadCount()])
+  }
+
+  /**
+   * Consume a notification realtime event captured by the host socket.
+   *
+   * The raw event is mapped through the transport so the DTO contract stays in
+   * this SDK; anything that cannot be mapped degrades to a full refresh. Events
+   * that arrive while an inbox request is in flight are replaced by a resync so a
+   * late server page cannot drop them.
+   */
+  applyRealtimeEvent(event: unknown): void {
+    if (this.destroyed) return
+    if (this.loadingInbox) {
+      this.pendingResync = true
+      return
+    }
+    const parse = this.transport.parseRealtimeEvent
+    let change: NotificationRealtimeChange | null = null
+    if (parse) {
+      try {
+        change = parse.call(this.transport, event)
+      } catch {
+        change = null
+      }
+    }
+    if (!change) {
+      void this.refreshFromRealtime()
+      return
+    }
+    this.applyRealtimeChange(change)
+  }
+
+  async markRead(notificationId: string): Promise<void> {
+    this.assertUsable()
+    const id = requiredText(notificationId, 'notificationId')
+    const target = this.items.find((item) => item.id === id)
+    if (target && target.readStatus === 'read') return
+    try {
+      const result = await this.transport.markRead({
+        notificationId: id,
+        applicationName: this.applicationName,
+      })
+      if (this.destroyed) return
+      this.applyRead([id], result.readAt)
+      this.setUnreadCount(result.unreadCount)
+      this.emit('notification-read', { notificationId: id })
+    } catch {
+      this.emitError('MARK_READ_FAILED', '通知标记已读失败，请稍后重试。', true)
+    }
+  }
+
+  async markAllRead(): Promise<void> {
+    this.assertUsable()
+    try {
+      const result = await this.transport.markAllRead({
+        applicationName: this.applicationName,
+      })
+      if (this.destroyed) return
+      const readAt = new Date().toISOString()
+      this.items = this.items.map((item) =>
+        item.readStatus === 'read' ? item : { ...item, readStatus: 'read', readAt },
+      )
+      this.emitInbox()
+      this.setUnreadCount(result.unreadCount)
+    } catch {
+      this.emitError('MARK_READ_FAILED', '通知标记已读失败，请稍后重试。', true)
+    }
+  }
+
+  async downloadAttachment(fileId: string, name?: string): Promise<Blob> {
+    this.assertUsable()
+    const id = requiredText(fileId, 'fileId')
+    try {
+      return await this.transport.downloadAttachment({ fileId: id, name })
+    } catch {
+      const detail = this.emitError('DOWNLOAD_FAILED', '附件下载失败，请稍后重试。', true)
+      throw new NotificationCenterClientError(detail.code, detail.message)
+    }
+  }
+
+  destroy(): void {
+    if (this.destroyed) return
+    this.destroyed = true
+    this.pendingResync = false
+    this.inboxGeneration += 1
+    this.listeners.clear()
+    this.items = []
+  }
+
+  private async reloadInbox(): Promise<void> {
+    const generation = ++this.inboxGeneration
+    this.loadingInbox = true
+    try {
+      const result = await this.transport.listInbox({
+        pageSize: this.pageSize,
+        beforeId: null,
+        // 分类目录随首屏/刷新/切换页签的请求一并取回，不额外发请求。
+        includeTypeFacets: true,
+        notificationTypes: this.notificationTypes,
+        readStatus: this.readStatus,
+        applicationName: this.applicationName,
+      })
+      if (this.destroyed || generation !== this.inboxGeneration) return
+      const unique = new Map<string, NotificationDto>()
+      for (const item of result.items) {
+        if (item.id) unique.set(item.id, item)
+      }
+      this.items = [...unique.values()]
+      this.hasMore = result.hasMore
+      this.nextId = result.nextId
+      this.applyTypeCatalog(result.types)
+      this.rememberTypes(result.items)
+      this.emitInbox()
+    } catch {
+      if (generation === this.inboxGeneration) {
+        this.emitError('INBOX_LOAD_FAILED', '通知加载失败，请稍后重试。', true)
+      }
+    } finally {
+      if (generation === this.inboxGeneration) this.finishInboxLoad()
+    }
+  }
+
+  private finishInboxLoad(): void {
+    this.loadingInbox = false
+    if (!this.pendingResync || this.destroyed) return
+    this.pendingResync = false
+    void this.refreshFromRealtime()
+  }
+
+  /**
+   * 分类页签的数据来源。
+   *
+   * `notification_type` 是后端自由文本列，展示名来自后端字典（`notification_type_name`），
+   * 前端不维护 code 到中文名的映射。权威目录是 `inbox` 在 `includeTypeFacets` 下返回的
+   * `types`（后端按收件人可见范围统计，忽略类型筛选与分页）；后端未提供时退回累积已加载
+   * 页面里出现过的分类——这在分页深处才出现的分类上会暂时缺页签，属已知取舍。
+   */
+  private applyTypeCatalog(types: readonly NotificationTypeSummary[] | undefined): void {
+    if (!Array.isArray(types)) return
+    const normalized = types
+      .map((entry) => ({
+        type: normalizedText(entry?.type),
+        name: normalizedText(entry?.name),
+      }))
+      .filter((entry) => entry.type)
+    this.typeCatalogFromBackend = true
+    this.setAvailableTypes(normalized, true)
+  }
+
+  private rememberTypes(items: readonly NotificationDto[]): void {
+    const discovered = items
+      .map((item) => ({ type: normalizedText(item.type), name: normalizedText(item.typeName) }))
+      .filter((entry) => entry.type)
+    if (!discovered.length) return
+    // 后端目录已给出分类集合时只补展示名，不新增或重排分类。
+    this.setAvailableTypes(discovered, false, this.typeCatalogFromBackend)
+  }
+
+  private setAvailableTypes(
+    candidates: readonly NotificationTypeSummary[],
+    replace: boolean,
+    namesOnly = false,
+  ): void {
+    const merged = new Map<string, string>()
+    if (!replace) {
+      for (const entry of this.availableTypes) merged.set(entry.type, entry.name)
+    }
+    for (const entry of candidates) {
+      if (namesOnly && !merged.has(entry.type)) continue
+      // 已有展示名优先保留：后端字典是权威，条目里的名字只用于填空。
+      const existing = merged.get(entry.type)
+      merged.set(entry.type, existing || entry.name)
+    }
+    const codes = [...merged.keys()]
+    const preferred = this.preferredTypeOrder.filter((value) => merged.has(value))
+    const ordered = [...preferred, ...codes.filter((value) => !preferred.includes(value))].map(
+      (type) => ({ type, name: merged.get(type) ?? '' }),
+    )
+    if (
+      ordered.length === this.availableTypes.length &&
+      ordered.every(
+        (entry, index) =>
+          entry.type === this.availableTypes[index]?.type &&
+          entry.name === this.availableTypes[index]?.name,
+      )
+    ) {
+      return
+    }
+    this.availableTypes = ordered
+    this.emit('types-change', { types: this.types })
+  }
+
+  private async refreshUnreadCount(): Promise<void> {
+    try {
+      const result = await this.transport.getUnreadCount({ applicationName: this.applicationName })
+      if (this.destroyed) return
+      this.setUnreadCount(result.unreadCount)
+    } catch {
+      // A later inbox reload or realtime event can recover the unread projection.
+    }
+  }
+
+  private applyRealtimeChange(change: NotificationRealtimeChange): void {
+    if (change.kind === 'created') {
+      const incoming = change.notification
+      if (!incoming.id) return
+      if (!this.items.some((item) => item.id === incoming.id)) {
+        this.items = [incoming, ...this.items]
+        this.rememberTypes([incoming])
+        this.emitInbox()
+      }
+      this.syncRealtimeUnreadCount(change.unreadCount)
+      return
+    }
+    if (change.kind === 'read') {
+      this.applyRead(change.notificationIds, change.readAt ?? null)
+      this.syncRealtimeUnreadCount(change.unreadCount)
+      return
+    }
+    const removed = new Set(change.notificationIds)
+    if (removed.size) {
+      const next = this.items.filter((item) => !removed.has(item.id))
+      if (next.length !== this.items.length) {
+        this.items = next
+        this.emitInbox()
+      }
+    }
+    this.syncRealtimeUnreadCount(change.unreadCount)
+  }
+
+  private syncRealtimeUnreadCount(value: number | undefined): void {
+    // Existing realtime events carry an application-scoped unread count. In the
+    // all-applications projection only the aggregate HTTP count is authoritative.
+    if (this.applicationName && typeof value === 'number') this.setUnreadCount(value)
+    else void this.refreshUnreadCount()
+  }
+
+  private applyRead(ids: readonly string[], readAt: string | null): void {
+    const target = new Set(ids)
+    if (!target.size) return
+    let changed = false
+    const next = this.items.map((item) => {
+      if (target.has(item.id) && item.readStatus !== 'read') {
+        changed = true
+        return { ...item, readStatus: 'read' as const, readAt: readAt ?? item.readAt }
+      }
+      return item
+    })
+    if (changed) {
+      this.items = next
+      this.emitInbox()
+    }
+  }
+
+  private async refreshFromRealtime(): Promise<void> {
+    await this.reloadInbox()
+    await this.refreshUnreadCount()
+  }
+
+  private emitInbox(): void {
+    this.emit('inbox', {
+      items: [...this.items],
+      hasMore: this.hasMore,
+      nextId: this.nextId,
+    })
+  }
+
+  private setUnreadCount(value: number): void {
+    const normalized = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0
+    if (normalized === this.unreadCount) return
+    this.unreadCount = normalized
+    this.emit('unread-count-change', { unreadCount: normalized })
+  }
+
+  private emitError(
+    code: NotificationCenterErrorCode,
+    message: string,
+    recoverable: boolean,
+  ): NotificationCenterErrorDetail {
+    const detail = { code, message, recoverable }
+    this.emit('error', detail)
+    return detail
+  }
+
+  private emit<K extends keyof NotificationCenterClientEventMap>(
+    type: K,
+    detail: NotificationCenterClientEventMap[K],
+  ): void {
+    for (const listener of this.listeners.get(type) ?? []) listener(detail)
+  }
+
+  private assertUsable(): void {
+    if (this.destroyed) {
+      throw new NotificationCenterClientError('CLIENT_DESTROYED', '通知中心客户端已经销毁。')
+    }
+  }
+}
+
+function requiredText(value: unknown, field: string): string {
+  const normalized = normalizedText(value)
+  if (!normalized) {
+    throw new NotificationCenterClientError('INVALID_CONFIGURATION', `${field} 不能为空。`)
+  }
+  return normalized
+}
+
+function normalizedText(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}