@anker-in/campaign-ui 0.2.11-beta.3 → 0.2.11-beta.31

package/dist/cjs/components/LiveChatWidget/types.d.ts

@@ -0,0 +1,767 @@
+/**
+ * LiveChat 组件核心类型定义
+ * 基于 specs/livechat-widget/data-model.md
+ */
+export type SessionStatus = 'active' | 'expired';
+export interface Session {
+    sessionId: string;
+    userId: string;
+    site: string;
+    status: SessionStatus;
+    createdAt?: number;
+    lastActivityAt?: number;
+}
+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;
+    }>;
+}
+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;
+        onAddToCart?: (product: Product) => void;
+        productCardRender?: (product: any) => 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;
+    };
+}
+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;
+    };
+}
+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;
+    };
+}
+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[];
+}
+export interface QuickReply {
+    id: string;
+    label: string;
+    value: string;
+    icon?: string;
+}
+export interface Policy {
+    title: string;
+    content: string;
+}
+/**
+ * 购物车金额信息
+ */
+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;
+}
+/**
+ * 后端返回的购物车商品行数据 (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;
+}
+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;
+}
+/**
+ * 流式对话请求参数
+ */
+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;
+}
+/**
+ * 通用文案配置
+ * 用于自定义组件中的按钮文案
+ */
+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;
+}
+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;
+    /**
+     * 欢迎消息
+     * @default "你好！我是 AI 助手，有什么可以帮助你的吗？"
+     */
+    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 回复促销卡片时触发
+     */
+    onPromotionList?: () => void;
+    /**
+     * 商品操作回调
+     */
+    onAddToCart?: (product: Product) => void;
+    /**
+     * 购物车按钮点击回调
+     */
+    onCart?: (cartId: string, checkoutUrl?: string) => void;
+    /**
+     * 是否显示新会话按钮
+     * @default true
+     */
+    showNewSessionButton?: boolean;
+    /**
+     * 通用文案配置
+     * 用于自定义按钮文案
+     */
+    commonText?: CommonText;
+    /**
+     * 自定义产品卡片渲染函数
+     * 用于自定义渲染 product_card 类型的产品卡片
+     * 当提供此函数时，将替代默认的产品卡片渲染逻辑
+     * @param product 原始后端产品数据（未经转换的数据）
+     * @returns React 可渲染的内容
+     * @example
+     * ```tsx
+     * <LiveChatWidget
+     *   productCardRender={(product) => (
+     *     <div>
+     *       <h3>{product.title}</h3>
+     *       <p>{product.price_range?.min}</p>
+     *     </div>
+     *   )}
+     * />
+     * ```
+     */
+    productCardRender?: (product: any) => React.ReactNode;
+}
+export interface MessageRenderer {
+    render: (content: MessageContent, isUser: boolean, isSystem: boolean) => React.ReactNode;
+}
+export interface CustomRendererMap {
+    [type: string]: MessageRenderer;
+}
+export interface PositionStyles {
+    bottom?: string;
+    top?: string;
+    left?: string;
+    right?: string;
+}
+export type BubblePosition = PositionStyles;