@anker-in/campaign-ui 0.3.2 → 0.3.4

package/src/components/LiveChatWidget/hooks/useSession.ts

@@ -0,0 +1,123 @@
+/**
+ * 会话管理 Hook
+ * 负责 sessionId 的持久化和生命周期管理
+ * 基于 specs/livechat-widget/plan.md 的会话管理策略
+ */
+
+import { useState, useCallback, useEffect } from 'react'
+
+const SESSION_KEY = 'livechat_session_id'
+
+export interface UseSessionReturn {
+  /**
+   * 当前会话 ID
+   */
+  sessionId: string | null
+
+  /**
+   * 保存会话 ID 到 localStorage 和状态
+   * @param id 会话 ID (UUID 格式)
+   */
+  saveSession: (id: string) => void
+
+  /**
+   * 清空会话 ID (会话过期或新会话)
+   */
+  clearSession: () => void
+
+  /**
+   * 检查是否有活动会话
+   */
+  hasSession: boolean
+}
+
+/**
+ * 会话管理 Hook
+ *
+ * 会话管理策略：
+ * 1. 首次对话: 不传 session_id,后端从 message_start 事件返回
+ * 2. 存储位置: localStorage.livechat_session_id
+ * 3. 会话恢复: 打开聊天窗口时自动加载历史消息
+ * 4. 会话过期: 监听 status 事件 (type: "session_expired"),清空消息列表和 sessionId
+ * 5. 新会话按钮: 调用 POST /api/chat/new-session,更新 sessionId
+ *
+ * @returns 会话管理工具对象
+ */
+export function useSession(): UseSessionReturn {
+  // 从 localStorage 初始化会话 ID
+  const [sessionId, setSessionId] = useState<string | null>(() => {
+    if (typeof window === 'undefined') return null
+
+    try {
+      return localStorage.getItem(SESSION_KEY)
+    } catch (error) {
+      console.error('[useSession] Failed to read from localStorage:', error)
+      return null
+    }
+  })
+
+  /**
+   * 保存会话 ID
+   * 同时更新状态和 localStorage
+   */
+  const saveSession = useCallback((id: string) => {
+    if (!id || typeof id !== 'string') {
+      console.warn('[useSession] Invalid session ID:', id)
+      return
+    }
+
+    setSessionId(id)
+
+    if (typeof window !== 'undefined') {
+      try {
+        localStorage.setItem(SESSION_KEY, id)
+      } catch (error) {
+        console.error('[useSession] Failed to save to localStorage:', error)
+      }
+    }
+  }, [])
+
+  /**
+   * 清空会话 ID
+   * 用于会话过期或开始新会话
+   */
+  const clearSession = useCallback(() => {
+    setSessionId(null)
+
+    if (typeof window !== 'undefined') {
+      try {
+        localStorage.removeItem(SESSION_KEY)
+      } catch (error) {
+        console.error('[useSession] Failed to remove from localStorage:', error)
+      }
+    }
+  }, [])
+
+  /**
+   * 监听 localStorage 变化（跨标签页同步）
+   * 注意：根据计划文档，多标签页不支持实时同步
+   * 这里仅监听是为了防止同一浏览器多标签页导致的状态不一致
+   */
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+
+    const handleStorageChange = (event: StorageEvent) => {
+      if (event.key === SESSION_KEY) {
+        setSessionId(event.newValue)
+      }
+    }
+
+    window.addEventListener('storage', handleStorageChange)
+
+    return () => {
+      window.removeEventListener('storage', handleStorageChange)
+    }
+  }, [])
+
+  return {
+    sessionId,
+    saveSession,
+    clearSession,
+    hasSession: sessionId !== null,
+  }
+}

package/src/components/LiveChatWidget/index.tsx

@@ -0,0 +1,63 @@
+/**
+ * LiveChatWidget 组件入口
+ */
+
+export { LiveChatWidget } from './LiveChatWidget'
+export type {
+  LiveChatWidgetProps,
+  Message,
+  MessageContent,
+  MessageRole,
+  MessageContentType,
+  MessageMetadata,
+  Product,
+  QuickReply,
+  Session,
+  BubblePosition,
+  MessageRenderer,
+  ProductCardContent,
+  ProductListContent,
+  PolicyContent,
+  QuickRepliesContent,
+  ThinkingContent,
+  ErrorContent,
+  FAQListContent,
+  FAQItem,
+  FAQCategory,
+  PromotionListContent,
+  PromotionItem,
+  CartContent,
+  CartData,
+  CartLine,
+  CartCost,
+  CartAmount,
+  CartDiscountCode,
+  SSEEvent,
+  ChatStreamRequest,
+  ComplianceDialogConfig,
+} from './types'
+
+// 导出 Hook (供高级用户自定义使用)
+export { useChatState } from './hooks/useChatState'
+export { useChatAPI } from './hooks/useChatAPI'
+export { useSession } from './hooks/useSession'
+
+// 导出工具类
+export { MessageRendererRegistry } from './utils/messageRenderers'
+export { getUserId } from './utils/userId'
+export { sanitizeInput, isValidUrl, isValidUUID, isValidMessageContent, escapeHtml } from './utils/validation'
+
+// 导出消息渲染器（供自定义使用）
+export {
+  TextBlock,
+  ProductCard,
+  ProductList,
+  PolicyBlock,
+  QuickReplies,
+  ThinkingBlock,
+  ErrorBlock,
+  FAQList,
+  PromotionList,
+  CartCard,
+  createQuickRepliesRenderer,
+} from './components/MessageContent/index.js'