@anker-in/campaign-ui 0.3.3 → 0.3.5

package/src/components/LiveChatWidget/utils/cartTransformers.ts

@@ -0,0 +1,72 @@
+/**
+ * 购物车数据转换工具
+ * 将后端返回的 Shopify GraphQL 格式转换为前端标准格式
+ */
+
+import type { BackendCartData, CartData, CartLine } from '../types'
+
+/**
+ * 转换后端购物车数据为前端格式
+ *
+ * @param backendData 后端返回的 Shopify GraphQL 格式数据
+ * @returns 前端标准化的购物车数据
+ *
+ * @example
+ * ```typescript
+ * const backendData = {
+ *   id: "gid://shopify/Cart/xxx",
+ *   lines: { edges: [{ node: {...} }] },
+ *   cost: { totalAmount: {...}, subtotalAmount: {...} },
+ *   ...
+ * }
+ *
+ * const cartData = transformCartData(backendData)
+ * // => { cartId: "gid://shopify/Cart/xxx", lines: [...], ... }
+ * ```
+ */
+export function transformCartData(backendData: BackendCartData): CartData {
+  // 转换商品行数据：从 edges[].node 结构转为扁平数组
+  const lines: CartLine[] = backendData.lines.edges.map(edge => ({
+    id: edge.node.id,
+    quantity: edge.node.quantity,
+    cost: {
+      totalAmount: edge.node.cost.totalAmount,
+      amountPerQuantity: edge.node.cost.amountPerQuantity,
+      subtotalAmount: edge.node.cost.subtotalAmount,
+    },
+    merchandise: {
+      id: edge.node.merchandise.id,
+      title: edge.node.merchandise.title,
+      price: edge.node.merchandise.price,
+      image: edge.node.merchandise.image
+        ? {
+            url: edge.node.merchandise.image.url,
+            altText: edge.node.merchandise.image.altText || undefined,
+          }
+        : undefined,
+      product: {
+        id: edge.node.merchandise.product.id,
+        title: edge.node.merchandise.product.title,
+        handle: edge.node.merchandise.product.handle,
+      },
+    },
+    attributes: edge.node.attributes,
+  }))
+
+  // 返回标准化的购物车数据
+  return {
+    isEmpty: backendData.totalQuantity === 0 || lines.length === 0,
+    cartId: backendData.id,
+    totalQuantity: backendData.totalQuantity,
+    lines,
+    cost: {
+      totalAmount: backendData.cost.totalAmount,
+      subtotalAmount: backendData.cost.subtotalAmount,
+    },
+    discountCodes: backendData.discountCodes?.map((code: any) => ({
+      code: code.code || code,
+      applicable: code.applicable !== false,
+    })),
+    checkoutUrl: backendData.checkoutUrl,
+  }
+}

package/src/components/LiveChatWidget/utils/fetcher.ts

@@ -0,0 +1,131 @@
+/**
+ * LiveChat Fetcher
+ * 参照 storefront 的实现，支持 reCAPTCHA
+ */
+
+/**
+ * 执行 Google reCAPTCHA 验证
+ */
+const executeRecaptcha = async (action: string, sitekey: string): Promise<string | false> => {
+  if (typeof window === 'undefined' || !window.grecaptcha?.enterprise?.execute) {
+    console.warn('[LiveChat Fetcher] reCAPTCHA not loaded')
+    return false
+  }
+
+  try {
+    const token = await window.grecaptcha.enterprise.execute(sitekey, { action })
+    return token
+  } catch (error) {
+    console.error('[LiveChat Fetcher] reCAPTCHA execution failed:', error)
+    return false
+  }
+}
+
+/**
+ * 获取 reCAPTCHA headers
+ */
+async function getRecaptchaHeaders(
+  action: string,
+  sitekey: string,
+  headerKey = 'X-Recaptcha-Token'
+): Promise<Record<string, string>> {
+  const recaptchaToken = await executeRecaptcha(action, sitekey)
+  if (!recaptchaToken) {
+    return {}
+  }
+  return {
+    [headerKey]: recaptchaToken,
+  }
+}
+
+/**
+ * Fetcher 参数
+ */
+export interface FetcherOptions {
+  url: string
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+  headers?: Record<string, string>
+  body?: any
+  timeout?: number
+  needRecaptcha?: boolean
+  recaptchaSitekey?: string
+  recaptchaAction?: string
+  recaptchaHeaderKey?: string
+}
+
+/**
+ * Fetcher 函数
+ * 支持 reCAPTCHA 和自定义 headers
+ */
+export const fetcher = async ({
+  url,
+  method = 'POST',
+  headers = {},
+  body,
+  timeout = 90000,
+  needRecaptcha = false,
+  recaptchaSitekey,
+  recaptchaAction = '',
+  recaptchaHeaderKey = 'X-Recaptcha-Token',
+}: FetcherOptions): Promise<Response> => {
+  // 获取 reCAPTCHA headers（如果需要）
+  let recaptchaHeaders: Record<string, string> = {}
+  if (needRecaptcha) {
+    if (!recaptchaSitekey) {
+      console.warn('[LiveChat Fetcher] needRecaptcha=true but recaptchaSitekey is missing')
+    } else {
+      recaptchaHeaders = await getRecaptchaHeaders(recaptchaAction, recaptchaSitekey, recaptchaHeaderKey)
+    }
+  }
+
+  // 准备请求体
+  const bodyData = body ? JSON.stringify(body) : undefined
+
+  const controller = new AbortController()
+  let timeoutTimer: NodeJS.Timeout | undefined
+  if (timeout) {
+    timeoutTimer = setTimeout(() => controller.abort(), timeout)
+  }
+
+  try {
+    const response = await fetch(url, {
+      method,
+      mode: 'cors',
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+        ...recaptchaHeaders,
+      },
+      signal: controller.signal,
+      ...(method !== 'GET' && bodyData && { body: bodyData }),
+    })
+
+    if (timeoutTimer) {
+      clearTimeout(timeoutTimer)
+    }
+
+    return response
+  } catch (error) {
+    if (timeoutTimer) {
+      clearTimeout(timeoutTimer)
+    }
+    throw error
+  }
+}
+
+/**
+ * 扩展 Window 接口以支持 grecaptcha
+ */
+  declare global {
+    interface Window {
+      grecaptcha?: {
+        execute: (sitekey: string, options: { action: string }) => Promise<string>
+        ready: (callback: () => void) => void
+        enterprise?: {
+          execute: (sitekey: string, options: { action: string }) =>
+  Promise<string>
+          ready: (callback: () => void) => void
+        }
+      }
+    }
+  }

package/src/components/LiveChatWidget/utils/messageRenderers.ts

@@ -0,0 +1,120 @@
+/**
+ * 消息渲染器注册表
+ * 支持自定义消息类型的扩展机制
+ * 基于 specs/livechat-widget/plan.md 的扩展机制设计
+ */
+
+import type { MessageContent, MessageRenderer } from '../types'
+
+/**
+ * 消息渲染器注册表
+ * 允许注册自定义的消息类型渲染器
+ */
+export class MessageRendererRegistry {
+  private renderers = new Map<string, MessageRenderer>()
+
+  /**
+   * 注册自定义渲染器
+   * @param type 消息内容类型
+   * @param renderer 渲染器实现
+   */
+  register(type: string, renderer: MessageRenderer): void {
+    if (!type || typeof type !== 'string') {
+      throw new Error('Message type must be a non-empty string')
+    }
+
+    if (!renderer) {
+      throw new Error('Renderer is required')
+    }
+
+    // 检查 renderer 是否有 render 属性
+    if (!('render' in renderer) || typeof renderer.render !== 'function') {
+      throw new Error('Renderer must have a render function')
+    }
+
+    this.renderers.set(type, renderer)
+  }
+
+  /**
+   * 批量注册渲染器
+   * @param renderers 渲染器映射表
+   */
+  registerMany(renderers: Record<string, MessageRenderer>): void {
+    Object.entries(renderers).forEach(([type, renderer]) => {
+      this.register(type, renderer)
+    })
+  }
+
+  /**
+   * 获取指定类型的渲染器
+   * @param type 消息内容类型
+   * @returns 渲染器实现，如果未注册则返回 undefined
+   */
+  get(type: string): MessageRenderer | undefined {
+    return this.renderers.get(type)
+  }
+
+  /**
+   * 检查是否已注册指定类型的渲染器
+   * @param type 消息内容类型
+   * @returns 是否已注册
+   */
+  has(type: string): boolean {
+    return this.renderers.has(type)
+  }
+
+  /**
+   * 移除指定类型的渲染器
+   * @param type 消息内容类型
+   * @returns 是否成功移除
+   */
+  unregister(type: string): boolean {
+    return this.renderers.delete(type)
+  }
+
+  /**
+   * 清空所有已注册的渲染器
+   */
+  clear(): void {
+    this.renderers.clear()
+  }
+
+  /**
+   * 渲染消息内容
+   * @param content 消息内容
+   * @param isUser 是否为用户消息
+   * @param isSystem 是否为系统消息
+   * @returns 渲染结果，如果未找到对应渲染器则返回 null
+   */
+  render(content: MessageContent, isUser: boolean, isSystem: boolean): React.ReactNode {
+    const renderer = this.renderers.get(content.type)
+
+    if (!renderer) {
+      console.warn(`[MessageRendererRegistry] No renderer found for type: ${content.type}`)
+      return null
+    }
+
+    try {
+      return renderer.render(content, isUser, isSystem)
+    } catch (error) {
+      console.error(`[MessageRendererRegistry] Error rendering ${content.type}:`, error)
+      return null
+    }
+  }
+
+  /**
+   * 获取所有已注册的消息类型
+   * @returns 消息类型数组
+   */
+  getRegisteredTypes(): string[] {
+    return Array.from(this.renderers.keys())
+  }
+}
+
+/**
+ * 创建默认的渲染器注册表实例
+ * @returns 新的注册表实例
+ */
+export function createRendererRegistry(): MessageRendererRegistry {
+  return new MessageRendererRegistry()
+}

package/src/components/LiveChatWidget/utils/productTransformers.ts

@@ -0,0 +1,149 @@
+/**
+ * 产品数据转换工具函数
+ * 将后端返回的产品数据转换为前端使用的格式
+ */
+
+import type { Product, Variant } from '../types'
+
+/**
+ * 转换单个变体数据
+ */
+function transformVariant(variant: any): Variant {
+  return {
+    id: variant.shopify_variant_id || variant.id,
+    title: variant.title || variant.option1,
+    sku: variant.sku,
+    price: variant.price
+      ? {
+          amount: variant.price,
+          currency: variant.currency || 'USD',
+        }
+      : undefined,
+    availableForSale: variant.available,
+    discount: variant.discount
+      ? {
+          has_discount: variant.discount.has_discount,
+          discount_price: variant.discount.discount_price,
+          discount_code: variant.discount.discount_code,
+          discount_percentage: variant.discount.discount_percentage,
+          discount_type: variant.discount.discount_type,
+          discount_value: variant.discount.discount_value,
+        }
+      : undefined,
+    memberPrice: variant.member_price
+      ? {
+          has_member_price: variant.member_price.has_member_price,
+          price: variant.member_price.price,
+        }
+      : undefined,
+    inventoryQuantity: variant.inventory_quantity,
+    option1: variant.option1,
+    option2: variant.option2,
+    option3: variant.option3,
+  }
+}
+
+/**
+ * 转换产品数据
+ * 将后端返回的产品对象转换为前端使用的 Product 类型
+ *
+ * @param product - 后端返回的产品数据
+ * @param site - 站点域名，用于构建产品 URL（可选，默认为空字符串）
+ * @returns 转换后的 Product 对象
+ *
+ * @example
+ * ```ts
+ * const backendProduct = {
+ *   shopify_product_id: "gid://shopify/Product/123",
+ *   handle: "product-handle",
+ *   title: "Product Title",
+ *   price_range: { min: 99.99, max: 149.99, currency: "USD" },
+ *   // ... 其他字段
+ * }
+ *
+ * const product = transformProduct(backendProduct, "www.example.com")
+ * // product.shopifyId === "gid://shopify/Product/123"
+ * // product.productUrl === "https://www.example.com/products/product-handle"
+ * ```
+ */
+export function transformProduct(product: any, site: string = ''): Product {
+  return {
+    // 基本信息
+    shopifyId: product.shopify_product_id || product.id,
+    sku: product.variants?.[0]?.sku || '',
+    handle: product.handle,
+    title: product.title,
+    description: product.description,
+    vendor: product.vendor,
+
+    // 价格信息
+    price: {
+      amount: product.price_range?.min || product.variants?.[0]?.price || 0,
+      currency: product.price_range?.currency || product.variants?.[0]?.currency || 'USD',
+    },
+    priceRange: product.price_range
+      ? {
+          min: product.price_range.min,
+          max: product.price_range.max,
+          currency: product.price_range.currency,
+        }
+      : undefined,
+    memberPriceRange: product.member_price_range
+      ? {
+          min: product.member_price_range.min,
+          max: product.member_price_range.max,
+          currency: product.member_price_range.currency,
+        }
+      : undefined,
+
+    // 媒体和链接
+    imageUrl: product.featured_image || '',
+    productUrl: site ? `https://${site}/products/${product.handle}` : `/products/${product.handle}`,
+
+    // 库存和状态
+    stockStatus: product.variants?.[0]?.available ? 'in_stock' : 'out_of_stock',
+
+    // 评分和热度
+    hotScore: product.popularity_score,
+    averageRating: product.average_rating,
+    reviewCount: product.review_count,
+
+    // 变体信息
+    variantCount: product.variant_count,
+    availableCount: product.available_count,
+    variants: product.variants?.map(transformVariant),
+
+    // 特性和标签
+    features: product.features
+      ? {
+          is_new: product.features.is_new,
+          has_rental: product.features.has_rental,
+          has_presale: product.features.has_presale,
+          has_member_price: product.features.has_member_price,
+          has_discount: product.features.has_discount,
+        }
+      : undefined,
+    tags: product.tags,
+  }
+}
+
+/**
+ * 批量转换产品列表
+ *
+ * @param products - 后端返回的产品数组
+ * @param site - 站点域名（可选）
+ * @returns 转换后的 Product 数组
+ *
+ * @example
+ * ```ts
+ * const backendProducts = [product1, product2, product3]
+ * const products = transformProducts(backendProducts, "www.example.com")
+ * ```
+ */
+export function transformProducts(products: any[], site?: string): Product[] {
+  if (!Array.isArray(products)) {
+    return []
+  }
+
+  return products.map(product => transformProduct(product, site))
+}

package/src/components/LiveChatWidget/utils/userId.ts

@@ -0,0 +1,140 @@
+/**
+ * userId 生成和管理工具
+ * 基于 specs/livechat-widget/research.md 的决策
+ *
+ * 策略：
+ * 1. 优先从 localStorage 读取
+ * 2. 尝试获取 Google Analytics ID (GAID)
+ * 3. 兜底：时间戳 + 随机数哈希
+ */
+
+const STORAGE_KEY = 'livechat_user_id'
+
+/**
+ * 获取用户唯一标识符（异步版本）
+ * @returns userId (GAID 或哈希值)
+ */
+export async function getUserId(): Promise<string> {
+  // 1. 尝试从 localStorage 读取
+  if (typeof window !== 'undefined') {
+    const stored = localStorage.getItem(STORAGE_KEY)
+    if (stored) return stored
+  }
+
+  // 2. 尝试获取 GAID
+  const gaid = getGAID()
+  if (gaid) {
+    if (typeof window !== 'undefined') {
+      localStorage.setItem(STORAGE_KEY, gaid)
+    }
+    return gaid
+  }
+
+  // 3. 兜底：使用 SHA-256 生成哈希
+  try {
+    const fallback = await generateHashedUserId()
+    if (typeof window !== 'undefined') {
+      localStorage.setItem(STORAGE_KEY, fallback)
+    }
+    return fallback
+  } catch (error) {
+    // 如果 SHA-256 失败，使用同步兜底方案
+    console.warn('[LiveChat userId] SHA-256 failed, using sync fallback:', error)
+    const fallback = generateHashedUserIdSync()
+    if (typeof window !== 'undefined') {
+      localStorage.setItem(STORAGE_KEY, fallback)
+    }
+    return fallback
+  }
+}
+
+/**
+ * 从 Google Analytics 获取 Client ID (GAID)
+ * @returns GAID 或 null
+ */
+function getGAID(): string | null {
+  if (typeof window === 'undefined') return null
+
+  // 检查 gtag 是否可用
+  if (typeof (window as any).gtag !== 'function') {
+    console.warn('[LiveChat userId] Google Analytics gtag is not available')
+    return null
+  }
+
+  try {
+    // Google Analytics 4 方法
+    // 注意：gtag 的 'get' 命令是异步的，这里使用同步 fallback
+    // 在实际项目中，如果 GA 已初始化，可以从 dataLayer 读取
+    const dataLayer = (window as any).dataLayer || []
+
+    // 尝试从 dataLayer 中查找已存在的 client_id
+    for (const item of dataLayer) {
+      if (item && item[1] && typeof item[1] === 'object') {
+        const clientId = item[1].client_id || item[1].clientId
+        if (clientId && typeof clientId === 'string') {
+          return `G-${clientId}`
+        }
+      }
+    }
+
+    // 如果没有找到，返回 null，使用兜底方案
+    return null
+  } catch (error) {
+    console.error('[LiveChat userId] Failed to get GAID:', error)
+    return null
+  }
+}
+
+/**
+ * 生成哈希用户 ID（兜底方案）
+ * @returns 格式为 user-{hash} 的用户 ID，hash 由 timestamp + random 通过 SHA-256 生成
+ */
+async function generateHashedUserId(): Promise<string> {
+  const timestamp = Date.now()
+  const random = Math.random().toString(36).substring(2, 15) // 生成随机字符串
+
+  // 将 timestamp 和 random 组合成字符串
+  const rawString = `${timestamp}${random}`
+
+  // 使用 Web Crypto API 生成 SHA-256 哈希
+  const encoder = new TextEncoder()
+  const data = encoder.encode(rawString)
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+
+  // 将 ArrayBuffer 转换为 16 进制字符串
+  const hashArray = Array.from(new Uint8Array(hashBuffer))
+  const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
+
+  // 取前 16 位作为用户 ID（保持简洁）
+  return `user-${hashHex.substring(0, 16)}`
+}
+
+/**
+ * 同步版本的哈希用户 ID 生成（兜底的兜底）
+ * 当 Web Crypto API 不可用时使用
+ */
+function generateHashedUserIdSync(): string {
+  const timestamp = Date.now()
+  const random = Math.random().toString(36).substring(2, 15)
+  const rawString = `${timestamp}${random}`
+
+  // 使用简单的哈希算法作为兜底
+  let hash = 0
+  for (let i = 0; i < rawString.length; i++) {
+    const char = rawString.charCodeAt(i)
+    hash = (hash << 5) - hash + char
+    hash = hash & hash
+  }
+
+  const hashString = Math.abs(hash).toString(16).padStart(8, '0')
+  return `user-${hashString}`
+}
+
+/**
+ * 清除保存的 userId（用于测试或重置）
+ */
+export function clearUserId(): void {
+  if (typeof window !== 'undefined') {
+    localStorage.removeItem(STORAGE_KEY)
+  }
+}

package/src/components/LiveChatWidget/utils/validation.ts

@@ -0,0 +1,99 @@
+/**
+ * 输入验证工具
+ * 基于 specs/livechat-widget/research.md 的 XSS 防护策略
+ */
+
+/**
+ * 清理用户输入
+ * - 移除控制字符
+ * - 限制长度
+ * @param input 用户输入的字符串
+ * @param maxLength 最大长度
+ * @returns 清理后的字符串
+ */
+export function sanitizeInput(input: string, maxLength: number = 5000): string {
+  if (!input || typeof input !== 'string') {
+    return ''
+  }
+
+  // 移除控制字符（ASCII 0-31 和 127）
+  let sanitized = input.replace(/[\x00-\x1F\x7F]/g, '')
+
+  // 限制长度
+  if (sanitized.length > maxLength) {
+    sanitized = sanitized.substring(0, maxLength)
+  }
+
+  // 去除首尾空白
+  return sanitized.trim()
+}
+
+/**
+ * 验证 URL 是否安全
+ * @param url URL 字符串
+ * @returns 是否为安全的 URL
+ */
+export function isValidUrl(url: string): boolean {
+  if (!url || typeof url !== 'string') {
+    return false
+  }
+
+  try {
+    const parsed = new URL(url)
+    // 只允许 http 和 https 协议
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 验证 sessionId 是否为有效的 UUID
+ * @param sessionId 会话 ID
+ * @returns 是否为有效的 UUID
+ */
+export function isValidUUID(sessionId: string): boolean {
+  if (!sessionId || typeof sessionId !== 'string') {
+    return false
+  }
+
+  // UUID v4 格式：xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+  return uuidRegex.test(sessionId)
+}
+
+/**
+ * 验证消息内容是否有效
+ * @param content 消息内容
+ * @returns 是否有效
+ */
+export function isValidMessageContent(content: string): boolean {
+  if (!content || typeof content !== 'string') {
+    return false
+  }
+
+  // 去除空白后不能为空
+  const trimmed = content.trim()
+  return trimmed.length > 0 && trimmed.length <= 5000
+}
+
+/**
+ * 转义 HTML 特殊字符
+ * @param text 原始文本
+ * @returns 转义后的文本
+ */
+export function escapeHtml(text: string): string {
+  if (!text || typeof text !== 'string') {
+    return ''
+  }
+
+  const map: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+  }
+
+  return text.replace(/[&<>"']/g, char => map[char] || char)
+}