@csntgao/uni-base 0.1.0

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

@@ -0,0 +1,154 @@
+export type NotificationReadStatus = 'unread' | 'read'
+export type NotificationContentType = 'text' | 'markdown'
+
+export interface NotificationSource {
+  type: string
+  code: string
+  id: string
+  name: string
+  avatarUrl: string
+}
+
+export interface NotificationResource {
+  type: string
+  id: string
+  title: string
+  aeCode: string
+}
+
+export interface NotificationAttachment {
+  fileId: string
+  versionId: string
+  name: string
+  sizeBytes: number
+  mimeType: string
+}
+
+export interface NotificationDto {
+  id: string
+  type: string
+  // 后端 notification_type_name 投影；缺省为空串，展示时回退到 type。
+  typeName: string
+  title: string
+  summary: string
+  content: string
+  contentType: NotificationContentType
+  priority: string
+  source: NotificationSource | null
+  resources: readonly NotificationResource[]
+  attachments: readonly NotificationAttachment[]
+  readStatus: NotificationReadStatus
+  readAt: string | null
+  archivedAt: string | null
+  createdAt: string
+  expiresAt: string | null
+}
+
+/** 分类目录条目：稳定 code 加后端字典给出的展示名（可能为空）。 */
+export interface NotificationTypeSummary {
+  type: string
+  name: string
+}
+
+export interface NotificationInboxQuery {
+  pageSize: number
+  beforeId?: string | null
+  // 请求分类目录；后端按收件人可见范围统计，忽略类型筛选与分页游标。
+  includeTypeFacets?: boolean
+  notificationTypes?: readonly string[]
+  readStatus?: 'all' | 'unread' | 'read'
+  includeArchived?: boolean
+  // Empty means the current principal's notifications across all applications.
+  applicationName: string
+}
+
+export interface NotificationInboxResult {
+  items: readonly NotificationDto[]
+  hasMore: boolean
+  nextId: string | null
+  // 仅在 includeTypeFacets 请求且后端支持时出现；缺省时客户端回退为累积已加载分类。
+  types?: readonly NotificationTypeSummary[]
+}
+
+export interface NotificationMarkReadResult {
+  unreadCount: number
+  readAt: string | null
+}
+
+export interface NotificationMarkAllReadResult {
+  markedCount: number
+  unreadCount: number
+}
+
+export type NotificationRealtimeChange =
+  | { kind: 'created'; notification: NotificationDto; unreadCount?: number }
+  | {
+      kind: 'read'
+      notificationIds: readonly string[]
+      unreadCount?: number
+      readAt?: string | null
+    }
+  | { kind: 'archived'; notificationIds: readonly string[]; unreadCount?: number }
+
+export interface NotificationCenterTransport {
+  listInbox(query: NotificationInboxQuery): Promise<NotificationInboxResult>
+  getUnreadCount(params: { applicationName: string }): Promise<{ unreadCount: number }>
+  markRead(params: {
+    notificationId: string
+    applicationName: string
+  }): Promise<NotificationMarkReadResult>
+  markAllRead(params: {
+    beforeId?: string | null
+    notificationTypes?: readonly string[]
+    applicationName: string
+  }): Promise<NotificationMarkAllReadResult>
+  downloadAttachment(params: { fileId: string; name?: string }): Promise<Blob>
+  archive?(params: {
+    notificationId: string
+    applicationName: string
+  }): Promise<{ unreadCount: number }>
+  // Optional: map a raw realtime notification event handed in by the host to a
+  // stable DTO change so the inbox can update in place. When absent — or when the
+  // event cannot be mapped — the client falls back to a full HTTP refresh.
+  parseRealtimeEvent?(event: unknown): NotificationRealtimeChange | null
+}
+
+export interface NotificationCenterClientOptions {
+  transport: NotificationCenterTransport
+  // Empty means the current principal's notifications across all applications.
+  applicationName: string
+  pageSize?: number
+  // Optional inbox projection used by compact consumers such as the unread
+  // notification popover. The full notification center defaults to `all`.
+  readStatus?: 'all' | 'unread' | 'read'
+  // Optional category codes pinned to the front of the tab order when they exist
+  // in the data. Defaults to empty: order then follows the backend catalog, and
+  // the SDK privileges no code of its own.
+  preferredTypeOrder?: readonly string[]
+}
+
+export type NotificationCenterErrorCode =
+  | 'INVALID_CONFIGURATION'
+  | 'INBOX_LOAD_FAILED'
+  | 'MARK_READ_FAILED'
+  | 'DOWNLOAD_FAILED'
+  | 'CLIENT_DESTROYED'
+
+export interface NotificationCenterErrorDetail {
+  code: NotificationCenterErrorCode
+  message: string
+  recoverable: boolean
+}
+
+export interface NotificationCenterClientEventMap {
+  ready: Record<string, never>
+  inbox: NotificationInboxResult
+  'types-change': { types: readonly NotificationTypeSummary[] }
+  'unread-count-change': { unreadCount: number }
+  'notification-read': { notificationId: string }
+  error: NotificationCenterErrorDetail
+}
+
+export type NotificationCenterClientListener<K extends keyof NotificationCenterClientEventMap> = (
+  detail: NotificationCenterClientEventMap[K],
+) => void

package/packages/core/src/protocol.ts

@@ -0,0 +1,237 @@
+import type { AiEmployeeMessage, AiEmployeeMessageRole } from './types'
+
+type JsonRecord = Record<string, unknown>
+
+export interface AuthenticateFrame {
+  type: 'authenticate'
+  protocol_version: 1
+  access_token: string
+  requested_channels: ['ai_employee']
+  cursors: Record<string, never>
+}
+
+export interface SessionSubscriptionFrame {
+  action: 'subscribe' | 'unsubscribe'
+  channel: 'ai_employee'
+  resource_type: 'session'
+  resource_id: string
+  replay_history?: boolean
+}
+
+export interface PingFrame {
+  action: 'ping'
+  timestamp: string
+}
+
+export interface ParsedSessionMessage {
+  messages: AiEmployeeMessage[]
+  fallbackResult?: AiEmployeeMessage
+  processing?: boolean
+}
+
+export type ParsedAiEmployeeEvent =
+  | { kind: 'session-message'; sessionId: string; result: ParsedSessionMessage }
+  | { kind: 'session-title'; sessionId: string; title: string }
+  | { kind: 'ignored' }
+
+export function createAuthenticateFrame(accessToken: string): AuthenticateFrame {
+  return {
+    type: 'authenticate',
+    protocol_version: 1,
+    access_token: accessToken,
+    requested_channels: ['ai_employee'],
+    cursors: {},
+  }
+}
+
+export function createSubscriptionFrame(
+  sessionId: string,
+  action: 'subscribe' | 'unsubscribe' = 'subscribe',
+  replayHistory = false,
+): SessionSubscriptionFrame {
+  const frame: SessionSubscriptionFrame = {
+    action,
+    channel: 'ai_employee',
+    resource_type: 'session',
+    resource_id: sessionId,
+  }
+  if (action === 'subscribe') frame.replay_history = replayHistory
+  return frame
+}
+
+export function createPingFrame(now = new Date()): PingFrame {
+  return { action: 'ping', timestamp: now.toISOString() }
+}
+
+export function parseJsonRecord(raw: string): JsonRecord | null {
+  try {
+    return asRecord(JSON.parse(raw))
+  } catch {
+    return null
+  }
+}
+
+export function parseAiEmployeeEvent(raw: unknown): ParsedAiEmployeeEvent {
+  const event = asRecord(raw)
+  const type = stringValue(event.type)
+  const sessionId = stringValue(event.session_id).trim()
+
+  if (type === 'session_title_updated') {
+    const title = stringValue(asRecord(event.payload).title).trim()
+    return sessionId && title ? { kind: 'session-title', sessionId, title } : { kind: 'ignored' }
+  }
+
+  if (type !== 'session_message' || !sessionId) return { kind: 'ignored' }
+  return {
+    kind: 'session-message',
+    sessionId,
+    result: parseSessionPayload(asRecord(event.payload), sessionId),
+  }
+}
+
+function parseSessionPayload(payload: JsonRecord, sessionId: string): ParsedSessionMessage {
+  const messages: AiEmployeeMessage[] = []
+  const patches = Array.isArray(payload.JsonPatch) ? payload.JsonPatch : []
+
+  for (const rawPatch of patches) {
+    const patch = asRecord(rawPatch)
+    const value = asRecord(patch.value)
+    const parsed = messageFromEntry(value, sessionId, patch)
+    if (parsed) messages.push(parsed)
+  }
+
+  const result = stringValue(payload.result).trim()
+  const fallbackResult = result
+    ? createMessage(
+        sessionId,
+        'assistant',
+        result,
+        `result:${sessionId}:${hashText(result)}`,
+        payload,
+      )
+    : undefined
+
+  if (payload.error) {
+    messages.push(
+      createMessage(
+        sessionId,
+        'error',
+        'AI 回复出现异常，请稍后重试。',
+        `error:${sessionId}:${hashText(stableString(payload))}`,
+        payload,
+      ),
+    )
+  }
+
+  let processing: boolean | undefined
+  if (payload.Ready === true) processing = true
+  if (payload.finished === true || payload.stopped === true) processing = false
+  return { messages, fallbackResult, processing }
+}
+
+function messageFromEntry(
+  entry: JsonRecord,
+  sessionId: string,
+  patch: JsonRecord,
+): AiEmployeeMessage | null {
+  const entryTypeValue = entry.entry_type
+  const entryType =
+    typeof entryTypeValue === 'string' ? entryTypeValue : stringValue(asRecord(entryTypeValue).type)
+
+  let role: AiEmployeeMessageRole
+  switch (entryType) {
+    case 'assistant_message':
+    case 'result':
+      role = 'assistant'
+      break
+    case 'user_message':
+      role = 'user'
+      break
+    case 'system_message':
+    case 'system_push':
+      role = 'system'
+      break
+    case 'error':
+    case 'error_message':
+      role = 'error'
+      break
+    default:
+      return null
+  }
+
+  const content = role === 'error' ? 'AI 回复出现异常，请稍后重试。' : extractText(entry.content)
+  if (!content) return null
+
+  const messageId = stringValue(entry.message_id)
+  const webSocketMessageId = stringValue(entry.ws_message_id)
+  const explicitId =
+    role === 'user'
+      ? messageId || webSocketMessageId || stringValue(entry.id)
+      : webSocketMessageId || messageId || stringValue(entry.id)
+  const fingerprint = stableString({ entry, path: patch.path, op: patch.op })
+  const id = explicitId || `realtime:${sessionId}:${hashText(fingerprint)}`
+  return createMessage(sessionId, role, content, id, entry)
+}
+
+function createMessage(
+  sessionId: string,
+  role: AiEmployeeMessageRole,
+  content: string,
+  id: string,
+  source: JsonRecord,
+): AiEmployeeMessage {
+  const createdAt =
+    stringValue(source.timestamp) ||
+    stringValue(source.create_time) ||
+    stringValue(source.created_at) ||
+    new Date().toISOString()
+  return { id, sessionId, role, content, createdAt }
+}
+
+function extractText(raw: unknown): string {
+  if (typeof raw !== 'string') return ''
+  const value = raw.trim()
+  if (!value) return ''
+
+  try {
+    const parsed: unknown = JSON.parse(value)
+    if (typeof parsed === 'string') return parsed.trim()
+    const record = asRecord(parsed)
+    for (const key of ['text', 'result', 'message', 'content']) {
+      const candidate = stringValue(record[key]).trim()
+      if (candidate) return candidate
+    }
+  } catch {
+    // Plain text and the simple user-message XML format are handled below.
+  }
+
+  const messageMatch = value.match(/<message>([\s\S]*?)<\/message>/i)
+  return (messageMatch?.[1] ?? value).trim()
+}
+
+function asRecord(value: unknown): JsonRecord {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as JsonRecord)
+    : {}
+}
+
+function stringValue(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function stableString(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? ''
+  } catch {
+    return ''
+  }
+}
+
+export function hashText(value: string): string {
+  let hash = 2_166_136_261
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index)
+    hash = Math.imul(hash, 16_777_619)
+  }
+  return (hash >>> 0).toString(36)
+}

package/packages/core/src/types.ts

@@ -0,0 +1,170 @@
+export type AiEmployeeMessageRole = 'user' | 'assistant' | 'system' | 'error'
+
+export interface AiEmployeeMessage {
+  id: string
+  sessionId: string
+  role: AiEmployeeMessageRole
+  content: string
+  createdAt: string
+}
+
+export interface AiEmployeeSessionSummary {
+  sessionId: string
+  title: string
+  latestMessage: string
+  latestMessageId?: string
+  updatedAt: string
+  unreadCount: number
+}
+
+export interface AiEmployeeAttachmentReference {
+  transactionId: string
+  fspath: string
+}
+
+export interface AiEmployeeFirstMessageOptions {
+  attachments?: readonly AiEmployeeAttachmentReference[]
+  trustedContext?: Readonly<Record<string, unknown>> | null
+}
+
+export interface AiEmployeeFirstMessageRequest {
+  requestId: string
+  aeCode: string
+  agentCode: string
+  content: string
+  attachments: readonly AiEmployeeAttachmentReference[]
+  trustedContext: Readonly<Record<string, unknown>> | null
+}
+
+export interface AiEmployeeFirstMessageResult {
+  sessionId: string
+  messageId: string
+  executionId: string
+  status: 'running' | 'queued'
+  startedAt: string
+  aeCode: string
+  agentCode: string
+  conversationType: string
+  title?: string
+  createdAt?: string
+}
+
+export interface AiEmployeeFirstMessageRequestState {
+  fingerprint: string
+  requestId: string
+}
+
+export interface AiEmployeeFirstMessageRequestStore {
+  load(
+    scope: string,
+  ): AiEmployeeFirstMessageRequestState | null | Promise<AiEmployeeFirstMessageRequestState | null>
+  save(scope: string, state: AiEmployeeFirstMessageRequestState): void | Promise<void>
+  clear(scope: string): void | Promise<void>
+}
+
+export interface AiEmployeeTransport {
+  createSessionWithFirstMessage(
+    request: AiEmployeeFirstMessageRequest,
+  ): Promise<AiEmployeeFirstMessageResult>
+  listSessions?(): Promise<AiEmployeeSessionSummary[]>
+  markSessionRead?(sessionId: string, latestMessageId: string): Promise<void>
+  listMessages(sessionId: string): Promise<AiEmployeeMessage[]>
+  sendMessage(sessionId: string, content: string): Promise<void>
+  getAccessToken(): Promise<string>
+}
+
+export type AiEmployeeTransportErrorCode =
+  | 'UNAUTHORIZED'
+  | 'ACCESS_DENIED'
+  | 'AI_EMPLOYEE_NOT_AVAILABLE'
+  | 'APPLICATION_NOT_SUPPORTED'
+  | 'ORGANIZATION_CONTEXT_REQUIRED'
+  | 'INVALID_ARGUMENT'
+  | 'IDEMPOTENCY_CONFLICT'
+  | 'REALTIME_UNAVAILABLE'
+  | 'TOO_MANY_REQUESTS'
+
+export type AiEmployeeConnectionState =
+  | 'idle'
+  | 'connecting'
+  | 'authenticating'
+  | 'subscribing'
+  | 'connected'
+  | 'reconnecting'
+  | 'disconnected'
+  | 'destroyed'
+
+export type AiEmployeeErrorCode =
+  | 'INVALID_CONFIGURATION'
+  | 'SESSION_UNAVAILABLE'
+  | 'HISTORY_LOAD_FAILED'
+  | 'TOKEN_UNAVAILABLE'
+  | 'WEBSOCKET_UNAVAILABLE'
+  | 'WEBSOCKET_ERROR'
+  | 'AUTHENTICATION_FAILED'
+  | 'ORGANIZATION_CONTEXT_REQUIRED'
+  | 'REALTIME_UNAVAILABLE'
+  | 'CHANNEL_UNAVAILABLE'
+  | 'SESSION_NOT_FOUND'
+  | 'PROTOCOL_ERROR'
+  | 'SEND_FAILED'
+  | 'FIRST_MESSAGE_CONFLICT'
+  | 'RATE_LIMITED'
+  | 'SEND_IN_PROGRESS'
+  | 'EMPTY_MESSAGE'
+  | 'CLIENT_DESTROYED'
+
+export interface AiEmployeeClientErrorDetail {
+  code: AiEmployeeErrorCode
+  message: string
+  recoverable: boolean
+}
+
+export interface AiEmployeeClientEventMap {
+  ready: { sessionId: string }
+  history: { sessionId: string; messages: readonly AiEmployeeMessage[] }
+  message: {
+    sessionId: string
+    message: AiEmployeeMessage
+    source: 'local' | 'realtime'
+  }
+  title: { sessionId: string; title: string }
+  'connection-state-change': {
+    previous: AiEmployeeConnectionState
+    current: AiEmployeeConnectionState
+  }
+  'processing-state-change': { processing: boolean }
+  error: AiEmployeeClientErrorDetail
+}
+
+export interface AiEmployeeReconnectOptions {
+  initialDelayMs: number
+  maximumDelayMs: number
+  factor: number
+  jitter: number
+}
+
+export type AiEmployeeWebSocketFactory = (url: string) => WebSocket
+
+export interface AiEmployeeClientOptions {
+  realtimeUrl: string
+  aeCode: string
+  agentCode: string
+  transport: AiEmployeeTransport
+  sessionId?: string
+  reconnect?: Partial<AiEmployeeReconnectOptions>
+  webSocketFactory?: AiEmployeeWebSocketFactory
+  requestIdFactory?: () => string
+  firstMessageRequestStore?: AiEmployeeFirstMessageRequestStore | null
+  /** Primarily useful for deterministic tests. Production heartbeats are never faster than 5s. */
+  minimumHeartbeatMs?: number
+}
+
+export interface AiEmployeeClientStartResult {
+  sessionId: string | null
+  messages: readonly AiEmployeeMessage[]
+}
+
+export type AiEmployeeClientListener<K extends keyof AiEmployeeClientEventMap> = (
+  detail: AiEmployeeClientEventMap[K],
+) => void