@anker-in/campaign-ui 0.3.4 → 0.3.6

package/dist/index.d.ts

@@ -590,6 +590,10 @@ interface Message {
     content: MessageContent[];
     timestamp: number;
     metadata?: MessageMetadata;
+    structured_content?: Array<{
+        type: string;
+        data: any;
+    }>;
 }
 type MessageContentType = 'text' | 'product_card' | 'product_list' | 'product_comparison' | 'policy' | 'quick_replies' | 'thinking' | 'error' | 'faq_list' | 'cart';
 type MessageContent = TextContent | ProductCardContent | ProductListContent | ProductComparisonContent | PolicyContent | QuickRepliesContent | ThinkingContent | ErrorContent | FAQListContent | PromotionListContent | CartContent;
@@ -600,7 +604,11 @@ interface TextContent {
 interface ProductCardContent {
     type: 'product_card';
     data: {
-        product: Product;
+        product?: Product;
+        rawProduct?: any;
+        productHandle: string;
+        onAddToCart?: (product: Product) => void;
+        productCardRender?: (product: any, productHandle: string) => React.ReactNode;
     };
 }
 interface ProductListContent {
@@ -970,6 +978,43 @@ interface CommonText {
      * @default "OFF"
      */
     off?: string;
+    /**
+     * 购物车总计文案
+     * @default "Total"
+     */
+    total?: string;
+}
+/**
+ * 法规协议弹窗配置
+ */
+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;
 }
 interface LiveChatWidgetProps {
     /**
@@ -983,14 +1028,9 @@ interface LiveChatWidgetProps {
      * @example { "Authorization": "Bearer token", "X-Custom-Header": "value" }
      */
     headers?: Record<string, string>;
-    /**
-     * 是否启用 reCAPTCHA 验证
-     * @default false
-     */
-    needRecaptcha?: boolean;
     /**
      * reCAPTCHA site key
-     * 当 needRecaptcha=true 时必填
+     * 提供此参数将自动启用 reCAPTCHA v3 验证
      * @example "6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14"
      */
     recaptchaSitekey?: string;
@@ -1005,6 +1045,12 @@ interface LiveChatWidgetProps {
      * @example "www.eufy.com"
      */
     site?: string;
+    /**
+     * 渠道编码
+     * 用于标识来源渠道
+     * @example "web_homepage"
+     */
+    channelCode?: string;
     /**
      * 已登录用户的 ID（可选）
      * 如果提供，将在 API 请求中传递
@@ -1033,7 +1079,6 @@ interface LiveChatWidgetProps {
     position?: BubblePosition;
     /**
      * 欢迎消息
-     * @default "你好！我是 AI 助手，有什么可以帮助你的吗？"
      */
     welcomeMessage?: string;
     /**
@@ -1059,9 +1104,55 @@ interface LiveChatWidgetProps {
      */
     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;
@@ -1078,8 +1169,9 @@ interface LiveChatWidgetProps {
     onProductList?: () => void;
     /**
      * AI 回复促销卡片时触发
+     * @param promotions 促销活动数组数据
      */
-    onPromotionList?: () => void;
+    onPromotionList?: (promotions: PromotionItem[]) => void;
     /**
      * 商品操作回调
      */
@@ -1098,6 +1190,43 @@ interface LiveChatWidgetProps {
      * 用于自定义按钮文案
      */
     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;
 }
 interface MessageRenderer {
     render: (content: MessageContent, isUser: boolean, isSystem: boolean) => React.ReactNode;
@@ -1151,11 +1280,10 @@ type BubblePosition = PositionStyles;
  *   onMessageSend={(msg) => console.log('Sent:', msg)}
  * />
  *
- * // 启用 reCAPTCHA v3 安全防护
+ * // 启用 reCAPTCHA v3 安全防护（提供 sitekey 即自动启用）
  * <LiveChatWidget
  *   apiBaseUrl="https://beta-api-livechat.anker.com"
  *   site="www.eufy.com"
- *   needRecaptcha={true}
  *   recaptchaSitekey="6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14"
  *   recaptchaAction="livechat"
  * />
@@ -1168,7 +1296,6 @@ type BubblePosition = PositionStyles;
  *     "Authorization": "Bearer your-token",
  *     "X-Custom-Header": "value"
  *   }}
- *   needRecaptcha={true}
  *   recaptchaSitekey="your-site-key"
  * />
  * ```