@anker-in/campaign-ui 0.3.3 → 0.3.5

package/src/components/LiveChatWidget/types.ts

@@ -0,0 +1,1012 @@
+/**
+ * LiveChat 组件核心类型定义
+ * 基于 specs/livechat-widget/data-model.md
+ */
+
+// ============================================================================
+// Session Types (会话)
+// ============================================================================
+
+export type SessionStatus = 'active' | 'expired'
+
+export interface Session {
+  sessionId: string
+  userId: string
+  site: string
+  status: SessionStatus
+  createdAt?: number
+  lastActivityAt?: number
+}
+
+// ============================================================================
+// Message Types (消息)
+// ============================================================================
+
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool'
+
+export interface MessageMetadata {
+  tokenUsage?: {
+    inputTokens: number
+    outputTokens: number
+  }
+  toolCalls?: Array<{
+    id: string
+    type: string
+    name: string
+  }>
+}
+
+export interface Message {
+  id: string
+  sessionId?: string
+  role: MessageRole
+  content: MessageContent[]
+  timestamp: number
+  metadata?: MessageMetadata
+  structured_content?: Array<{
+    type: string
+    data: any
+  }>
+}
+
+// ============================================================================
+// Message Content Types (消息内容)
+// ============================================================================
+
+export type MessageContentType =
+  | 'text'
+  | 'product_card'
+  | 'product_list'
+  | 'product_comparison'
+  | 'policy'
+  | 'quick_replies'
+  | 'thinking'
+  | 'error'
+  | 'faq_list'
+  | 'cart'
+
+export type MessageContent =
+  | TextContent
+  | ProductCardContent
+  | ProductListContent
+  | ProductComparisonContent
+  | PolicyContent
+  | QuickRepliesContent
+  | ThinkingContent
+  | ErrorContent
+  | FAQListContent
+  | PromotionListContent
+  | CartContent
+
+export interface TextContent {
+  type: 'text'
+  text: string
+}
+
+export interface ProductCardContent {
+  type: 'product_card'
+  data: {
+    product?: Product
+    rawProduct?: any // Raw backend product data (for custom render)
+    productHandle: string // Product ID from placeholder {{product:ID}}, for app-level product lookup
+    onAddToCart?: (product: Product) => void
+    productCardRender?: (product: any, productHandle: string) => React.ReactNode
+  }
+}
+
+export interface ProductListContent {
+  type: 'product_list'
+  data: {
+    products: Product[]
+    title?: string
+    onAddToCart?: (product: Product) => void
+    commonText?: CommonText
+  }
+}
+
+export interface ProductComparisonContent {
+  type: 'product_comparison'
+  data: {
+    products: Product[]
+    dimensions: {
+      price?: {
+        label: string
+        values: Array<{
+          product_id: string
+          min: number
+          max: number
+          currency: string
+          has_discount: boolean
+        }>
+      }
+      variants?: {
+        label: string
+        values: Array<{
+          product_id: string
+          count: number
+        }>
+      }
+      member_price?: {
+        label: string
+        values: Array<{
+          product_id: string
+          available: boolean
+          min: number
+          max: number
+          currency: string
+        }>
+      }
+      discount?: {
+        label: string
+        values: Array<{
+          product_id: string
+          has_discount: boolean
+        }>
+      }
+      [key: string]: any
+    }
+    onAddToCart?: (product: Product) => void
+    commonText?: CommonText
+  }
+}
+
+export interface PolicyContent {
+  type: 'policy'
+  data: {
+    title: string
+    content: string
+  }
+}
+
+export interface QuickRepliesContent {
+  type: 'quick_replies'
+  data: {
+    replies: QuickReply[]
+  }
+}
+
+export interface ThinkingContent {
+  type: 'thinking'
+  data: {
+    status: string
+  }
+}
+
+export interface ErrorContent {
+  type: 'error'
+  data: {
+    message: string
+    code?: string
+  }
+}
+
+export interface FAQListContent {
+  type: 'faq_list'
+  data: {
+    found: boolean
+    count: number
+    total?: number
+    results: FAQItem[]
+  }
+}
+
+export interface PromotionListContent {
+  type: 'promotion_list'
+  data: {
+    found: boolean
+    count: number
+    total?: number
+    results: PromotionItem[]
+    commonText?: CommonText
+  }
+}
+
+// ============================================================================
+// FAQ Types (常见问题)
+// ============================================================================
+
+export type FAQCategory = 'shipping' | 'return' | 'product' | 'payment' | 'general'
+
+export interface FAQItem {
+  id: string
+  question: string
+  answer: string
+  category: FAQCategory
+  keywords?: string[]
+  relatedQuestions?: string[]
+  metadata?: {
+    language?: string
+    priority?: number
+    lastUpdated?: string
+  }
+}
+
+// ============================================================================
+// Promotion Types (促销活动)
+// ============================================================================
+
+export interface PromotionItem {
+  id: string
+  title: string
+  subtitle?: string
+  description?: string
+  banner_url?: string
+  url?: string
+  time_range: {
+    start: string
+    end?: string | null
+    is_active: boolean
+  }
+  priority?: number
+  product_count?: number
+  metadata?: {
+    display_order?: number
+    target_audience?: string
+  }
+}
+
+// ============================================================================
+// Product Types (商品)
+// ============================================================================
+
+export type StockStatus = 'in_stock' | 'low_stock' | 'out_of_stock'
+
+export interface Price {
+  amount: number
+  currency: string
+}
+
+export interface PriceRange {
+  min: number
+  max: number
+  currency: string
+}
+
+export interface VariantDiscount {
+  has_discount: boolean
+  discount_price?: number
+  discount_code?: string
+  discount_percentage?: number
+  /** 折扣类型：fixed_amount 固定金额折扣，percentage 百分比折扣 */
+  discount_type?: 'fixed_amount' | 'percentage'
+  /** 折扣数值（可能是字符串或数字） */
+  discount_value?: string | number
+}
+
+export interface VariantMemberPrice {
+  has_member_price: boolean
+  price?: number
+}
+
+export interface ProductFeatures {
+  is_new?: boolean
+  has_rental?: boolean
+  has_presale?: boolean
+  has_member_price?: boolean
+  has_discount?: boolean
+}
+
+export interface Variant {
+  id: string
+  title: string
+  sku?: string
+  price?: Price
+  availableForSale: boolean
+  color?: string
+  discount?: VariantDiscount
+  memberPrice?: VariantMemberPrice
+  inventoryQuantity?: number
+  option1?: string
+  option2?: string
+  option3?: string
+}
+
+export interface Product {
+  shopifyId: string
+  sku?: string
+  handle: string
+  title: string
+  description?: string
+  vendor?: string
+  price: Price
+  priceRange?: PriceRange
+  memberPriceRange?: PriceRange
+  imageUrl: string
+  productUrl: string
+  stockStatus: StockStatus
+  hotScore?: number
+  averageRating?: number
+  reviewCount?: number
+  variants?: Variant[]
+  variantCount?: number
+  availableCount?: number
+  features?: ProductFeatures
+  tags?: string[]
+}
+
+// ============================================================================
+// Quick Reply Types (快捷回复)
+// ============================================================================
+
+export interface QuickReply {
+  id: string
+  label: string
+  value: string
+  icon?: string
+}
+
+// ============================================================================
+// Policy Types (政策)
+// ============================================================================
+
+export interface Policy {
+  title: string
+  content: string
+}
+
+// ============================================================================
+// Cart Types (购物车)
+// ============================================================================
+
+/**
+ * 购物车金额信息
+ */
+export interface CartAmount {
+  /** 金额字符串（如 "99.99"） */
+  amount: string
+  /** 货币代码（如 "USD"） */
+  currencyCode: string
+}
+
+/**
+ * 购物车价格汇总
+ */
+export interface CartCost {
+  /** 应付总价（已应用折扣） */
+  totalAmount: CartAmount
+  /** 原价小计（未应用折扣） */
+  subtotalAmount: CartAmount
+}
+
+/**
+ * 购物车商品变体信息
+ */
+export interface CartMerchandise {
+  /** 变体 ID (Shopify ProductVariant GID) */
+  id: string
+  /** 变体标题（如 "Black", "Large" 等） */
+  title: string
+  /** 单价 */
+  price: CartAmount
+  /** 商品图片 URL */
+  image?: {
+    url: string
+    altText?: string
+  }
+  /** 关联的商品信息 */
+  product: {
+    /** 商品 ID */
+    id: string
+    /** 商品标题 */
+    title: string
+    /** 商品 handle */
+    handle: string
+  }
+}
+
+/**
+ * 购物车商品行
+ */
+export interface CartLine {
+  /** 购物车行 ID (用于更新/删除操作) */
+  id: string
+  /** 商品数量 */
+  quantity: number
+  /** 价格信息 */
+  cost: {
+    /** 行总价（单价 × 数量，已应用折扣） */
+    totalAmount: CartAmount
+    /** 单价 */
+    amountPerQuantity: CartAmount
+    /** 行小计（单价 × 数量，未应用折扣） */
+    subtotalAmount: CartAmount
+  }
+  /** 商品变体信息 */
+  merchandise: CartMerchandise
+  /** 自定义属性（可选） */
+  attributes?: Array<{
+    key: string
+    value: string
+  }>
+}
+
+/**
+ * 购物车折扣码
+ */
+export interface CartDiscountCode {
+  /** 折扣码 */
+  code: string
+  /** 是否有效/适用 */
+  applicable: boolean
+}
+
+/**
+ * 购物车数据
+ */
+export interface CartData {
+  /** 购物车是否为空 */
+  isEmpty: boolean
+  /** 购物车 ID (Shopify Cart GID) */
+  cartId: string
+  /** 商品总数量 */
+  totalQuantity: number
+  /** 商品列表 */
+  lines: CartLine[]
+  /** 价格汇总 */
+  cost: CartCost
+  /** 折扣码列表 */
+  discountCodes?: CartDiscountCode[]
+  /** 结账页面 URL */
+  checkoutUrl?: string
+  /** 购物车按钮回调函数 */
+  onCart?: (cartId: string, checkoutUrl?: string) => void
+  /** 通用文案配置 */
+  commonText?: CommonText
+}
+
+/**
+ * 购物车内容块
+ */
+export interface CartContent {
+  type: 'cart'
+  data: CartData
+}
+
+// ============================================================================
+// Backend Cart Types (后端购物车数据格式 - Shopify GraphQL)
+// ============================================================================
+
+/**
+ * 后端返回的购物车商品行数据 (Shopify GraphQL 格式)
+ */
+export interface BackendCartLineNode {
+  id: string
+  quantity: number
+  cost: {
+    totalAmount: CartAmount
+    amountPerQuantity: CartAmount
+    compareAtAmountPerQuantity?: CartAmount | null
+    subtotalAmount: CartAmount
+  }
+  discountAllocations: any[]
+  merchandise: {
+    id: string
+    title: string
+    availableForSale: boolean
+    quantityAvailable?: number
+    price: CartAmount
+    compareAtPrice?: CartAmount | null
+    image?: {
+      url: string
+      altText?: string | null
+      width?: number
+      height?: number
+    } | null
+    product: {
+      id: string
+      title: string
+      handle: string
+      vendor?: string
+      featuredImage?: {
+        url: string
+        altText?: string | null
+        width?: number
+        height?: number
+      } | null
+      tags?: string[]
+    }
+  }
+  attributes?: Array<{
+    key: string
+    value: string
+  }>
+}
+
+/**
+ * 后端返回的购物车数据 (Shopify GraphQL 格式)
+ */
+export interface BackendCartData {
+  id: string
+  checkoutUrl?: string
+  totalQuantity: number
+  lines: {
+    edges: Array<{
+      node: BackendCartLineNode
+    }>
+  }
+  cost: {
+    totalAmount: CartAmount
+    subtotalAmount: CartAmount
+    checkoutChargeAmount?: CartAmount
+    totalAmountEstimated?: boolean
+    subtotalAmountEstimated?: boolean
+    totalTaxAmount?: CartAmount | null
+    totalDutyAmount?: CartAmount | null
+  }
+  discountAllocations?: any[]
+  buyerIdentity?: any
+  attributes?: Array<{
+    key: string
+    value: string
+  }>
+  discountCodes?: any[]
+  createdAt?: string
+  updatedAt?: string
+}
+
+// ============================================================================
+// SSE Event Types (SSE 事件)
+// ============================================================================
+
+export type SSEEventType =
+  | 'message_start'
+  | 'content_delta'
+  | 'content_block'
+  | 'message_end'
+  | 'tool_start'
+  | 'tool_end'
+  | 'status'
+  | 'error'
+  | 'done'
+
+export interface SSEEvent<T = any> {
+  event: SSEEventType | null
+  data: T
+}
+
+// 具体事件数据类型
+export interface MessageStartData {
+  sessionId: string
+}
+
+export interface ContentDeltaData {
+  text: string
+}
+
+export interface ContentBlockData {
+  type: string
+  data: any
+}
+
+export interface MessageEndData {
+  usage: {
+    inputTokens: number
+    outputTokens: number
+  }
+}
+
+export interface ToolStartData {
+  id: string
+  type: string
+  name: string
+}
+
+export interface ToolEndData {
+  id: string
+}
+
+export interface StatusData {
+  type: string
+  message?: string
+}
+
+export interface ErrorData {
+  message: string
+  code?: string
+  type?: string
+}
+
+// ============================================================================
+// API Request/Response Types (API 请求响应)
+// ============================================================================
+
+/**
+ * 流式对话请求参数
+ */
+export interface ChatStreamRequest {
+  /** 用户的消息文本 */
+  message: string
+  /** 用户标识符 */
+  user_id: string
+  /** 来自 new-session 端点的会话 ID */
+  session_id: string
+  /** 可选的上下文信息 */
+  context?: {
+    /** 用于购物车操作的 Shopify 购物车 ID */
+    cartId?: string
+    /** Storefront API 访问令牌 */
+    accessToken?: string
+    /** 已登录用户的 ID */
+    real_user_id?: string
+  }
+}
+
+export interface NewSessionRequest {
+  user_id: string
+  session_id?: string
+  site?: string
+  channel_code?: string
+  real_user_id?: string
+}
+
+export interface NewSessionResponse {
+  success: boolean
+  sessionId: string
+  message: string
+  resumed?: boolean
+  messages?: Message[]
+  welcomeMessage?: string
+  quickQuestions?: string[]
+  brand?: string
+}
+
+export interface ErrorResponse {
+  success: boolean
+  error: string
+  code?: string
+  details?: any
+}
+
+// ============================================================================
+// Common Text Types (通用文案)
+// ============================================================================
+
+/**
+ * 通用文案配置
+ * 用于自定义组件中的按钮文案
+ */
+export interface CommonText {
+  /**
+   * 产品列表展开按钮文案
+   * @default "Learn More"
+   */
+  learnMore?: string
+
+  /**
+   * 产品列表收起按钮文案
+   * @default "Show Less"
+   */
+  showLess?: string
+
+  /**
+   * 添加到购物车按钮文案
+   * @default "Add to Cart"
+   */
+  addToCart?: string
+
+  /**
+   * 查看购物车/更多按钮文案
+   * @default "View More"
+   */
+  viewMore?: string
+
+  /**
+   * 折扣标签后缀文案（如 "20% OFF" 中的 "OFF"）
+   * @default "OFF"
+   */
+  off?: string
+
+  /**
+   * 购物车总计文案
+   * @default "Total"
+   */
+  total?: string
+}
+
+// ============================================================================
+// Compliance Dialog Types (法规协议弹窗)
+// ============================================================================
+
+/**
+ * 法规协议弹窗配置
+ */
+export interface ComplianceDialogConfig {
+  /**
+   * 弹窗标题
+   * @example "Hi! I'm your eufy AI assistant."
+   */
+  title: string
+
+  /**
+   * 弹窗内容文本（支持 HTML）
+   * @example "AI-generated responses can be inaccurate. Please verify important info. Do not input sensitive personal data"
+   */
+  content: string
+
+  /**
+   * 勾选框文本（支持完整 HTML，包括链接）
+   * 可以直接包含 <a> 标签等 HTML 元素
+   * @example "By starting to use \"Live Chat\", you agree to Anker's <a href=\"https://www.anker.com/privacy\" target=\"_blank\">LIVE CHAT PRIVACY NOTICE</a>."
+   */
+  checkboxText: string
+
+  /**
+   * 同意按钮文本
+   * @default "Agree"
+   */
+  agreeButtonText?: string
+
+  /**
+   * Cookie 名称，用于记录用户同意状态
+   * Cookie 有效期为 365 天
+   * @default "livechat_compliance_agreed"
+   */
+  cookieName?: string
+}
+
+// ============================================================================
+// Component Props Types (组件 Props)
+// ============================================================================
+
+export interface LiveChatWidgetProps {
+  /**
+   * API 基础 URL
+   * @example "https://beta-api-livechat.anker.com"
+   */
+  apiBaseUrl: string
+
+  /**
+   * 自定义请求头
+   * 将在所有 API 请求中添加这些请求头
+   * @example { "Authorization": "Bearer token", "X-Custom-Header": "value" }
+   */
+  headers?: Record<string, string>
+
+  /**
+   * reCAPTCHA site key
+   * 提供此参数将自动启用 reCAPTCHA v3 验证
+   * @example "6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14"
+   */
+  recaptchaSitekey?: string
+
+  /**
+   * reCAPTCHA action 前缀
+   * 实际使用时会根据不同接口添加后缀（如 chat_stream, new_session）
+   * @default "livechat"
+   */
+  recaptchaAction?: string
+
+  /**
+   * Shopify 店铺域名
+   * @example "www.eufy.com"
+   */
+  site?: string
+
+  /**
+   * 渠道编码
+   * 用于标识来源渠道
+   * @example "web_homepage"
+   */
+  channelCode?: string
+
+  /**
+   * 已登录用户的 ID（可选）
+   * 如果提供，将在 API 请求中传递
+   */
+  loginUserId?: string
+
+  /**
+   * Shopify 购物车 ID（可选）
+   * 用于购物车操作，将在 stream 接口的 context 中传递
+   * @example "gid://shopify/Cart/Z2NwLXVzLWVhc3QxOjAxSkZH..."
+   */
+  cartId?: string
+
+  /**
+   * Storefront API 访问令牌（可选）
+   * 用于购物车操作，将在 stream 接口的 context 中传递
+   */
+  accessToken?: string
+
+  /**
+   * 气泡按钮位置
+   * 自定义位置对象：{ top?: string, bottom?: string, left?: string, right?: string }
+   * @default { bottom: "1.5rem", right: "1.5rem" }
+   * @example
+   * // 自定义位置
+   * position={{ bottom: "20px", right: "30px" }}
+   * position={{ top: "100px", left: "50px" }}
+   */
+  position?: BubblePosition
+
+  /**
+   * 欢迎消息
+   */
+  welcomeMessage?: string
+
+  /**
+   * 初始快捷回复按钮
+   */
+  quickReplies?: QuickReply[]
+
+  /**
+   * 自定义消息渲染器
+   */
+  customRenderers?: Record<string, MessageRenderer>
+
+  /**
+   * Logo URL
+   */
+  logoUrl?: string
+
+  /**
+   * 聊天窗口标题
+   * @default "AI 助手"
+   */
+  title?: string
+
+  /**
+   * 聊天气泡按钮图标（图片 URL）
+   * 如果提供，将使用图片替代默认的 SVG 图标
+   */
+  chatBubbleIcon?: string
+
+  /**
+   * 受控模式：是否打开聊天窗口
+   * 提供此参数时，组件将处于受控模式
+   * @example
+   * ```tsx
+   * const [isOpen, setIsOpen] = useState(false)
+   * <LiveChatWidget open={isOpen} onOpenChange={setIsOpen} />
+   * ```
+   */
+  open?: boolean
+
+  /**
+   * 受控模式：打开/关闭状态变化回调
+   * 【必需】配合 `open` 使用，用于同步状态到父组件
+   * 当用户点击打开或关闭按钮时触发
+   * @example
+   * ```tsx
+   * <LiveChatWidget
+   *   open={isOpen}
+   *   onOpenChange={setIsOpen}  // 必需：同步状态
+   * />
+   * ```
+   */
+  onOpenChange?: (open: boolean) => void
+
+  /**
+   * 【可选】窗口打开事件监听
+   * 用于埋点、日志等副作用，不影响状态控制
+   * 在 onOpenChange 之后触发
+   * @example
+   * ```tsx
+   * <LiveChatWidget
+   *   open={isOpen}
+   *   onOpenChange={setIsOpen}
+   *   onOpen={() => trackEvent('chat_opened')}  // 可选：埋点
+   * />
+   * ```
+   */
+  onOpen?: () => void
+
+  /**
+   * 【可选】窗口关闭事件监听
+   * 用于埋点、日志等副作用，不影响状态控制
+   * 在 onOpenChange 之后触发
+   * @example
+   * ```tsx
+   * <LiveChatWidget
+   *   open={isOpen}
+   *   onOpenChange={setIsOpen}
+   *   onClose={() => trackEvent('chat_closed')}  // 可选：埋点
+   * />
+   * ```
+   */
+  onClose?: () => void
+  onMessageSend?: (message: string) => void
+  onError?: (error: Error) => void
+
+  /**
+   * AI 消息回调
+   */
+  /**
+   * AI 回复文本消息时触发
+   */
+  onTextMessage?: () => void
+
+  /**
+   * AI 回复商品列表卡片时触发
+   */
+  onProductList?: () => void
+
+  /**
+   * AI 回复促销卡片时触发
+   * @param promotions 促销活动数组数据
+   */
+  onPromotionList?: (promotions: PromotionItem[]) => void
+
+  /**
+   * 商品操作回调
+   */
+  onAddToCart?: (product: Product) => void
+
+  /**
+   * 购物车按钮点击回调
+   */
+  onCart?: (cartId: string, checkoutUrl?: string) => void
+
+  /**
+   * 是否显示新会话按钮
+   * @default true
+   */
+  showNewSessionButton?: boolean
+
+  /**
+   * 通用文案配置
+   * 用于自定义按钮文案
+   */
+  commonText?: CommonText
+
+  /**
+   * 自定义产品卡片渲染函数
+   * 用于自定义渲染 product_card 类型的产品卡片
+   * 当提供此函数时，将替代默认的产品卡片渲染逻辑
+   * @param product 原始后端产品数据（未经转换的数据），如果在 product_list 中找不到则为 undefined
+   * @param productHandle 文本占位符中的产品 ID（如 {{product:ID}} 中的 ID），可用于应用层查询产品数据
+   * @returns React 可渲染的内容
+   * @example
+   * ```tsx
+   * <LiveChatWidget
+   *   productCardRender={(product, productHandle) => {
+   *     // product 可能为 undefined，此时可用 productHandle 查询产品
+   *     if (!product) {
+   *       return <ProductCardByHandle handle={productHandle} />
+   *     }
+   *     return (
+   *       <div>
+   *         <h3>{product.title}</h3>
+   *         <p>{product.price_range?.min}</p>
+   *       </div>
+   *     )
+   *   }}
+   * />
+   * ```
+   */
+  productCardRender?: (product: any, productHandle: string) => React.ReactNode
+
+  /**
+   * 输入框底部提示文本
+   * 不传入则不显示
+   */
+  bottomTips?: string
+
+  /**
+   * 法规协议弹窗配置
+   * 提供此参数将在用户首次点击聊天气泡时显示法规协议弹窗
+   * 用户同意后才会打开聊天窗口
+   */
+  complianceConfig?: ComplianceDialogConfig
+}
+
+export interface MessageRenderer {
+  render: (content: MessageContent, isUser: boolean, isSystem: boolean) => React.ReactNode
+}
+
+export interface CustomRendererMap {
+  [type: string]: MessageRenderer
+}
+
+// ============================================================================
+// Utility Types (工具类型)
+// ============================================================================
+
+export interface PositionStyles {
+  bottom?: string
+  top?: string
+  left?: string
+  right?: string
+}
+
+export type BubblePosition = PositionStyles