@anker-in/campaign-ui 0.2.11-beta.25 → 0.2.11-beta.26

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

@@ -6,7 +6,7 @@
 
 import { useCallback, useRef } from 'react'
 import type { ChatStreamRequest, SSEEvent, NewSessionRequest, NewSessionResponse } from '../types'
-import { sendMessage, createNewSession } from '../api/chat'
+import { sendMessage, createNewSession, type RecaptchaConfig } from '../api/chat'
 
 export interface UseChatAPIOptions {
   /**
@@ -19,6 +19,11 @@ export interface UseChatAPIOptions {
    */
   headers?: Record<string, string>
 
+  /**
+   * reCAPTCHA 配置
+   */
+  recaptchaConfig?: RecaptchaConfig
+
   /**
    * 错误处理回调
    */
@@ -64,7 +69,7 @@ export interface UseChatAPIReturn {
  * @returns API 调用工具对象
  */
 export function useChatAPI(options: UseChatAPIOptions): UseChatAPIReturn {
-  const { apiBaseUrl, headers, onError } = options
+  const { apiBaseUrl, headers, recaptchaConfig, onError } = options
 
   // 用于中断当前请求的 AbortController
   const abortControllerRef = useRef<AbortController | null>(null)
@@ -87,7 +92,7 @@ export function useChatAPI(options: UseChatAPIOptions): UseChatAPIReturn {
       isSendingRef.current = true
 
       try {
-        await sendMessage(apiBaseUrl, request, onEvent, headers)
+        await sendMessage(apiBaseUrl, request, onEvent, headers, recaptchaConfig)
       } catch (error) {
         // 忽略手动中断的错误
         if (error instanceof Error && error.name === 'AbortError') {
@@ -102,7 +107,7 @@ export function useChatAPI(options: UseChatAPIOptions): UseChatAPIReturn {
         abortControllerRef.current = null
       }
     },
-    [apiBaseUrl, headers, onError]
+    [apiBaseUrl, headers, recaptchaConfig, onError]
   )
 
   /**
@@ -111,14 +116,14 @@ export function useChatAPI(options: UseChatAPIOptions): UseChatAPIReturn {
   const createSession = useCallback(
     async (request: NewSessionRequest): Promise<NewSessionResponse> => {
       try {
-        return await createNewSession(apiBaseUrl, request, headers)
+        return await createNewSession(apiBaseUrl, request, headers, recaptchaConfig)
       } catch (error) {
         console.error('[useChatAPI] Create session error:', error)
         onError?.(error as Error)
         throw error
       }
     },
-    [apiBaseUrl, headers, onError]
+    [apiBaseUrl, headers, recaptchaConfig, onError]
   )
 
   /**

package/src/components/LiveChatWidget/types.ts

@@ -705,6 +705,26 @@ export interface LiveChatWidgetProps {
    */
   headers?: Record<string, string>
 
+  /**
+   * 是否启用 reCAPTCHA 验证
+   * @default false
+   */
+  needRecaptcha?: boolean
+
+  /**
+   * reCAPTCHA site key
+   * 当 needRecaptcha=true 时必填
+   * @example "6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14"
+   */
+  recaptchaSitekey?: string
+
+  /**
+   * reCAPTCHA action 前缀
+   * 实际使用时会根据不同接口添加后缀（如 chat_stream, new_session）
+   * @default "livechat"
+   */
+  recaptchaAction?: string
+
   /**
    * Shopify 店铺域名
    * @example "www.eufy.com"

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

@@ -0,0 +1,126 @@
+/**
+ * LiveChat Fetcher
+ * 参照 storefront 的实现，支持 reCAPTCHA
+ */
+
+/**
+ * 执行 Google reCAPTCHA 验证
+ */
+const executeRecaptcha = async (action: string, sitekey: string): Promise<string | false> => {
+  if (typeof window === 'undefined' || !window.grecaptcha?.execute) {
+    console.warn('[LiveChat Fetcher] reCAPTCHA not loaded')
+    return false
+  }
+
+  try {
+    const token = await window.grecaptcha.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 = 'activity',
+  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
+    }
+  }
+}

package/src/stories/LiveChatWidget.stories.tsx

@@ -85,6 +85,27 @@ const customRenderers = {
         defaultValue: { summary: 'undefined' },
       },
     },
+    needRecaptcha: {
+      control: 'boolean',
+      description: '是否启用 Google reCAPTCHA v3 验证',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    recaptchaSitekey: {
+      control: 'text',
+      description: 'Google reCAPTCHA v3 site key',
+      table: {
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    recaptchaAction: {
+      control: 'text',
+      description: 'reCAPTCHA action 名称，用于区分不同的验证场景',
+      table: {
+        defaultValue: { summary: '"activity"' },
+      },
+    },
     site: {
       control: 'text',
       description: 'Shopify 店铺 URL',
@@ -138,10 +159,10 @@ export const Default: Story = {
 
     site: 'beta.eufy.com',
 
-    headers: {
-      'X-Recaptcha-Sitekey': '6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14',
-      recaptcha: '',
-    },
+    // reCAPTCHA 配置（使用组件 props，不是 headers）
+    needRecaptcha: true,
+    recaptchaSitekey: '6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14 999testtest',
+    recaptchaAction: 'chat',
   },
 }
 
@@ -492,3 +513,60 @@ FAQ 列表消息支持：
     },
   },
 }
+
+/**
+ * 带 reCAPTCHA 配置
+ *
+ * 展示如何配置 Google reCAPTCHA v3 验证，保护 API 请求免受滥用。
+ *
+ * reCAPTCHA 会在后台自动验证用户行为，无需用户手动操作。
+ */
+export const WithRecaptcha: Story = {
+  args: {
+    // 启用 reCAPTCHA
+    needRecaptcha: true,
+    // 配置你的 reCAPTCHA site key
+    recaptchaSitekey: '6LfS4J4pAAAAACX1e_WrxutmxxzCK7FU4WzVqL14',
+    // 可选：自定义 action 名称
+    recaptchaAction: 'livechat',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+### reCAPTCHA v3 配置
+
+启用 reCAPTCHA v3 可以保护你的 API 免受机器人和滥用行为的攻击。
+
+**配置步骤：**
+
+1. 在 [Google reCAPTCHA](https://www.google.com/recaptcha/admin) 创建 v3 密钥
+2. 在页面中加载 reCAPTCHA 脚本：
+   \`\`\`html
+   <script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
+   \`\`\`
+3. 配置 LiveChatWidget 组件：
+   \`\`\`tsx
+   <LiveChatWidget
+     needRecaptcha={true}
+     recaptchaSitekey="YOUR_SITE_KEY"
+     recaptchaAction="livechat"
+   />
+   \`\`\`
+
+**工作原理：**
+
+- 每次发送消息或创建会话时，会自动获取 reCAPTCHA token
+- token 会通过 \`X-Recaptcha-Token\` header 发送到后端
+- 后端需要验证 token 的有效性
+
+**注意事项：**
+
+- reCAPTCHA v3 在后台运行，不会打断用户体验
+- 建议为不同的操作使用不同的 \`recaptchaAction\` 以便分析
+- 确保后端正确验证 reCAPTCHA token
+        `,
+      },
+    },
+  },
+}