@yagolive/event-kit 1.0.0

package/README.md

@@ -0,0 +1,651 @@
+# @yagolive/event-kit
+
+YAGO App Action 创建与通信工具库，支持浏览器、React、Vue 等多种环境。
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   应用层 (Frameworks)                │
+├───────────────────┬───────────────────┬─────────────┤
+│  React            │  Vue 3            │  原生 JS     │
+├───────────────────┴───────────────────┴─────────────┤
+│                   桥接层 (Bridge)                     │
+│               ActionBridge (注入适配器)               │
+├─────────────────────────────────────────────────────┤
+│                   适配器层 (Adapters)                 │
+│        RNWebViewAdapter  │  MockAdapter                │
+├─────────────────────────────────────────────────────┤
+│                   核心层 (Core)                       │
+│   ActionCreator  │  ActionType  │  ActionData       │
+└─────────────────────────────────────────────────────┘
+```
+
+## 安装
+
+```bash
+npm install @yagolive/event-kit
+```
+
+## 快速开始
+
+### 浏览器（Script 标签）
+
+```html
+<!-- 引入完整功能包 -->
+<script src="https://unpkg.com/@yagolive/event-kit/build/js/action_bridge.umd.js"></script>
+<script>
+  var { ActionBridge } = window.__action_bridge__;
+
+  // 自动检测环境并创建桥接实例
+  var bridge = ActionBridge.createDefault();
+
+  // 发送导航 Action
+  bridge.navigate('profile', { userId: 123 })
+    .then(function(result) { console.log('导航成功', result); })
+    .catch(function(error) { console.error('导航失败', error); });
+</script>
+```
+
+```html
+<!-- 仅引入核心包（不需要通信功能时） -->
+<script src="https://unpkg.com/@yagolive/event-kit/build/js/action_creator.umd.js"></script>
+<script>
+  var { ActionCreator } = window.__action_creator__;
+
+  var action = ActionCreator.createNavigateAction('home');
+  console.log(action.toJson());
+  // {"type":"navigate","data":{"screen":"home"}}
+</script>
+```
+
+也可使用 [jsdelivr](https://www.jsdelivr.com/package/npm/@yagolive/event-kit)：
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@yagolive/event-kit/build/js/action_bridge.umd.js"></script>
+```
+
+### React
+
+```jsx
+import { ActionBridgeProvider, useActionBridge } from '@yagolive/event-kit/react';
+import { RNWebViewAdapter } from '@yagolive/event-kit/adapters';
+
+// 1. 在根组件配置 Provider
+function App() {
+  return (
+    <ActionBridgeProvider adapter={new RNWebViewAdapter()}>
+      <MyPage />
+    </ActionBridgeProvider>
+  );
+}
+
+// 2. 在子组件中使用 Hook
+function MyPage() {
+  const bridge = useActionBridge();
+
+  const goToProfile = async () => {
+    try {
+      const result = await bridge.navigate('profile', { userId: 123 });
+      console.log('导航成功', result);
+    } catch (error) {
+      console.error('导航失败', error);
+    }
+  };
+
+  return <button onClick={goToProfile}>查看个人资料</button>;
+}
+```
+
+### Vue 3
+
+```javascript
+import { createActionBridgePlugin, useActionBridge } from '@yagolive/event-kit/vue';
+import { RNWebViewAdapter } from '@yagolive/event-kit/adapters';
+
+// 1. 安装插件
+const adapter = new RNWebViewAdapter();
+app.use(createActionBridgePlugin(adapter));
+
+// 2. 在组件中使用 Composition API
+export default {
+  setup() {
+    const bridge = useActionBridge();
+
+    const goToProfile = async () => {
+      try {
+        const result = await bridge.navigate('profile', { userId: 123 });
+        console.log('导航成功', result);
+      } catch (error) {
+        console.error('导航失败', error);
+      }
+    };
+
+    return { goToProfile };
+  }
+}
+
+// 3. 也可通过 $actionBridge 访问（Options API）
+export default {
+  methods: {
+    async goToProfile() {
+      const result = await this.$actionBridge.navigate('profile', { userId: 123 });
+    }
+  }
+}
+```
+
+### ESM / CommonJS
+
+```javascript
+// ESM
+import { ActionBridge, RNWebViewAdapter } from '@yagolive/event-kit';
+const adapter = new RNWebViewAdapter();
+const bridge = new ActionBridge(adapter);
+
+// CommonJS
+const { ActionBridge, RNWebViewAdapter } = require('@yagolive/event-kit');
+const adapter = new RNWebViewAdapter();
+const bridge = new ActionBridge(adapter);
+```
+
+---
+
+## API 参考
+
+### ActionCreator
+
+纯逻辑工厂，无环境依赖。用于创建各种 Action 对象。
+
+```javascript
+import { ActionCreator } from '@yagolive/event-kit';
+```
+
+#### 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `ActionData` | Object | 包含所有数据类型类：Jump, Navigate, Replace, EnterRoom, LiveDetect, Onelink |
+| `ActionType` | Object | Action 类型枚举：JUMP, NAVIGATE, REPLACE, ENTER_ROOM, LIVE_DETECT, ONELINK |
+
+#### 工厂方法
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `buildJump(path?)` | path?: string | Jump | 构建 Jump 对象（链式配置） |
+| `createJumpAction(path)` | path: string | Action | 创建跳转 Action |
+| `createJumpActionWithData(jump)` | jump: Jump | Action | 从 Jump 对象创建 Action |
+| `buildNavigate(screen?, params?)` | screen?: string, params?: Object | Navigate | 构建 Navigate 对象（链式配置） |
+| `createNavigateAction(screen)` | screen: string | Action | 创建导航 Action（无参数） |
+| `createNavigateActionWithParams(screen, params)` | screen: string, params: Object | Action | 创建导航 Action（带参数） |
+| `createNavigateActionWithData(navigate)` | navigate: Navigate | Action | 从 Navigate 对象创建 Action |
+| `buildReplace(screen?, params?)` | screen?: string, params?: Object | Replace | 构建 Replace 对象（链式配置） |
+| `createReplaceAction(screen)` | screen: string | Action | 创建替换导航 Action |
+| `createReplaceActionWithParams(screen, params)` | screen: string, params: Object | Action | 创建替换导航 Action（带参数） |
+| `createReplaceActionWithData(replace)` | replace: Replace | Action | 从 Replace 对象创建 Action |
+| `buildEnterRoom()` | - | EnterRoom | 构建 EnterRoom 对象（链式配置） |
+| `createEnterRoomAction(id)` | id: number | Action | 创建进房 Action |
+| `createEnterRoomActionWithData(enterRoom)` | enterRoom: EnterRoom | Action | 从 EnterRoom 对象创建 Action |
+| `buildLiveDetect()` | - | LiveDetect | 构建 LiveDetect 对象（链式配置） |
+| `createLiveDetectAction()` | - | Action | 创建活体检测 Action |
+| `createLiveDetectActionWithData(liveDetect)` | liveDetect: LiveDetect | Action | 从 LiveDetect 对象创建 Action |
+| `buildOnelink(url?)` | url?: string | Onelink | 构建 Onelink 对象（链式配置） |
+| `createOnelinkAction(url)` | url: string | Action | 创建 Onelink Action |
+| `createOnelinkActionWithData(onelink)` | onelink: Onelink | Action | 从 Onelink 对象创建 Action |
+
+#### 使用示例
+
+```javascript
+// 简单导航
+const action = ActionCreator.createNavigateAction('home');
+// {"type":"navigate","data":{"screen":"home"}}
+
+// 带参数导航
+const action = ActionCreator.createNavigateActionWithParams('profile', { userId: 123 });
+// {"type":"navigate","data":{"screen":"profile","params":{"userId":123}}}
+
+// 进房（带回调配置）
+const enterRoom = ActionCreator.buildEnterRoom()
+  .setId(1001)
+  .setText('我的房间')
+  .addOpenGiftPopupCallback(
+    new ActionCreator.ActionData.EnterRoom.OpenGiftPopupCallback().setId(1)
+  );
+const action = ActionCreator.createEnterRoomActionWithData(enterRoom);
+// {"type":"enter_room","data":{"text":"我的房间","id":1001,"callbacks":{"open_gift_popup":{"id":1}}}}
+
+// Onelink
+const action = ActionCreator.createOnelinkAction('https://yago.app/room/123');
+```
+
+### ActionType
+
+Action 类型枚举。
+
+```javascript
+import { ActionType } from '@yagolive/event-kit';
+
+ActionType.JUMP         // 'jump'
+ActionType.NAVIGATE     // 'navigate'
+ActionType.REPLACE      // 'replace'
+ActionType.ENTER_ROOM   // 'enter_room'
+ActionType.LIVE_DETECT  // 'live_detect'
+ActionType.ONELINK      // 'onelink'
+```
+
+### ActionBridge
+
+统一桥接接口，通过注入适配器实现跨环境通信。
+
+```javascript
+import { ActionBridge, RNWebViewAdapter } from '@yagolive/event-kit';
+
+const adapter = new RNWebViewAdapter();
+const bridge = new ActionBridge(adapter);
+```
+
+#### 构造函数
+
+```javascript
+new ActionBridge(adapter, options?)
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| adapter | Adapter | 是 | 适配器实例，必须实现 `sendAction` 方法 |
+| options | Object | 否 | 配置项（保留） |
+
+#### 属性
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `ActionCreator` | Object | ActionCreator 工厂引用 |
+| `ActionType` | Object | ActionType 枚举引用 |
+
+#### 核心方法
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `sendAction(action, callback?)` | action: Action, callback?: Function | Promise | 发送 Action，支持回调和 Promise 双模式 |
+| `sendActionNoReply(action)` | action: Action | void | 发送 Action 不期待回复 |
+| `destroy()` | - | void | 销毁桥接实例，清理适配器资源 |
+
+#### 便捷方法
+
+每个便捷方法返回 Promise，内部自动创建对应 Action 并发送。
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `jump(path)` | path: string | Promise | 跳转 |
+| `buildJump(path?)` | path?: string | Jump | 构建 Jump 对象（链式配置） |
+| `createJumpActionWithData(jump)` | jump: Jump | Action | 从 Jump 对象创建 Action（不自动发送） |
+| `navigate(screen, params?)` | screen: string, params?: Object | Promise | 导航到指定页面 |
+| `buildNavigate(screen?, params?)` | screen?: string, params?: Object | Navigate | 构建 Navigate 对象（链式配置） |
+| `createNavigateActionWithData(navigate)` | navigate: Navigate | Action | 从 Navigate 对象创建 Action（不自动发送） |
+| `replace(screen, params?)` | screen: string, params?: Object | Promise | 替换当前页面 |
+| `buildReplace(screen?, params?)` | screen?: string, params?: Object | Replace | 构建 Replace 对象（链式配置） |
+| `createReplaceActionWithData(replace)` | replace: Replace | Action | 从 Replace 对象创建 Action（不自动发送） |
+| `enterRoom(id)` | id: number | Promise | 进入房间 |
+| `buildEnterRoom()` | - | EnterRoom | 构建 EnterRoom 对象（链式配置） |
+| `createEnterRoomAction(id)` | id: number | Action | 创建进房 Action（不自动发送） |
+| `createEnterRoomActionWithData(enterRoom)` | enterRoom: EnterRoom | Action | 从 EnterRoom 对象创建 Action（不自动发送） |
+| `liveDetect()` | - | Promise | 触发活体检测 |
+| `buildLiveDetect()` | - | LiveDetect | 构建 LiveDetect 对象（链式配置） |
+| `createLiveDetectActionWithData(liveDetect)` | liveDetect: LiveDetect | Action | 从 LiveDetect 对象创建 Action（不自动发送） |
+| `onelink(url)` | url: string | Promise | 打开 Onelink |
+| `buildOnelink(url?)` | url?: string | Onelink | 构建 Onelink 对象（链式配置） |
+| `createOnelinkActionWithData(onelink)` | onelink: Onelink | Action | 从 Onelink 对象创建 Action（不自动发送） |
+
+#### 静态方法
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `createDefault(options?)` | options?: Object | ActionBridge | 使用 RNWebViewAdapter 创建默认桥接实例 |
+| `createWithMock(options?)` | options?: Object | ActionBridge | 使用 MockAdapter 创建测试用桥接实例 |
+
+#### 使用示例
+
+```javascript
+// Promise 风格（推荐）
+const result = await bridge.navigate('profile', { userId: 123 });
+
+// 回调风格（向后兼容）
+bridge.sendAction(action, function(result, error) {
+  if (error) console.error(error);
+  else console.log(result);
+});
+
+// 复杂进房配置
+const enterRoom = bridge.buildEnterRoom();
+enterRoom.setId(1001).setUseReplace(true);
+enterRoom.addOpenGiftPopupCallback(
+  new bridge.ActionCreator.ActionData.EnterRoom.OpenGiftPopupCallback().setId(1)
+);
+const action = bridge.createEnterRoomActionWithData(enterRoom);
+const result = await bridge.sendAction(action);
+
+// 销毁
+bridge.destroy();
+```
+
+### 适配器
+
+#### RNWebViewAdapter
+
+用于 React Native WebView 环境，通过 `window.ReactNativeWebView.postMessage` 与原生端通信。
+
+```javascript
+import { RNWebViewAdapter } from '@yagolive/event-kit/adapters';
+```
+
+**构造函数选项：**
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `timeout` | number | 30000 | 请求超时时间（毫秒） |
+
+**示例：**
+
+```javascript
+const adapter = new RNWebViewAdapter({ timeout: 15000 });
+const bridge = new ActionBridge(adapter);
+
+// 或使用快捷方法
+const bridge = ActionBridge.createDefault({ timeout: 15000 });
+```
+
+**工作原理：**
+
+1. `init()` 时自动检测 Android/iOS 平台并注册对应的 `message` 事件监听
+2. `sendAction()` 通过 `window.ReactNativeWebView.postMessage()` 发送 JSON 数据
+3. 原生端处理完毕后通过 `postMessage` 回传结果，适配器自动匹配回调/Promise
+4. 超时未收到回复自动 reject Promise
+
+#### MockAdapter
+
+用于测试和开发环境，无需真实 WebView 即可模拟通信。
+
+```javascript
+import { MockAdapter } from '@yagolive/event-kit/adapters';
+```
+
+**构造函数选项：**
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `delay` | number | 0 | 模拟响应延迟（毫秒） |
+
+**方法：**
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `mockResult(actionType, result)` | actionType: string, result: any | Mock 指定 Action 类型的返回值 |
+| `mockError(actionType, error)` | actionType: string, error: any | Mock 指定 Action 类型的错误返回 |
+| `getCalls()` | - | 获取所有调用记录 |
+| `clearCalls()` | - | 清空调用记录 |
+| `clearMocks()` | - | 清空所有 Mock 配置 |
+
+**示例：**
+
+```javascript
+const mock = new MockAdapter({ delay: 100 });
+const bridge = new ActionBridge(mock);
+
+// Mock 返回值
+mock.mockResult('navigate', { success: true, screen: 'profile' });
+
+// Mock 错误
+mock.mockError('enter_room', new Error('房间不存在'));
+
+// 验证调用
+await bridge.navigate('profile');
+const calls = mock.getCalls();
+console.log(calls[0]);
+// { type: 'navigate', data: { screen: 'profile' }, messageId: 'msg_...', timestamp: 1716364800000 }
+
+// 清理
+mock.clearCalls();
+mock.clearMocks();
+```
+
+#### 自定义适配器
+
+实现以下接口即可创建自定义适配器：
+
+```javascript
+class CustomAdapter {
+  // 必须实现
+  sendAction(action) {
+    // action.type - Action 类型
+    // action.data - Action 数据对象（有 toMap() 方法）
+    // action.messageId - 消息 ID
+    // 必须返回 Promise
+    return new Promise((resolve, reject) => {
+      // 发送 action 到目标环境
+      // 收到回复后 resolve(result) 或 reject(error)
+    });
+  }
+
+  sendActionNoReply(action) {
+    // 发送 action 不期待回复
+  }
+
+  // 可选实现
+  init() {
+    // 初始化逻辑（ActionBridge 构造时自动调用）
+  }
+
+  destroy() {
+    // 清理逻辑（bridge.destroy() 时自动调用）
+  }
+}
+
+const bridge = new ActionBridge(new CustomAdapter());
+```
+
+---
+
+## React 集成
+
+```javascript
+import { ActionBridgeProvider, useActionBridge } from '@yagolive/event-kit/react';
+```
+
+### ActionBridgeProvider
+
+Context Provider 组件，为子组件提供 ActionBridge 实例。
+
+**Props：**
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `adapter` | Adapter | 适配器实例（与 `bridge` 二选一） |
+| `bridge` | ActionBridge | 已创建的桥接实例（与 `adapter` 二选一） |
+| `children` | ReactNode | 子组件 |
+
+**行为：**
+- 传入 `adapter` 时，Provider 内部创建 ActionBridge 实例，卸载时自动 destroy
+- 传入 `bridge` 时，Provider 直接使用该实例，卸载时不会 destroy
+- 都不传时，自动使用 `ActionBridge.createDefault()` 创建
+
+### useActionBridge
+
+Hook，获取当前 ActionBridge 实例。必须在 `ActionBridgeProvider` 内使用，否则抛出错误。
+
+**示例：**
+
+```jsx
+function ProfileButton() {
+  const bridge = useActionBridge();
+
+  const handleClick = async () => {
+    await bridge.navigate('profile', { userId: 123 });
+  };
+
+  return <button onClick={handleClick}>查看资料</button>;
+}
+```
+
+---
+
+## Vue 3 集成
+
+```javascript
+import { createActionBridgePlugin, useActionBridge } from '@yagolive/event-kit/vue';
+```
+
+### createActionBridgePlugin
+
+创建 Vue 插件，安装后提供 ActionBridge 实例。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `adapterOrBridge` | Adapter \| ActionBridge | 传入适配器或已创建的桥接实例 |
+
+**安装后提供：**
+- `inject(BRIDGE_KEY)` — 通过依赖注入获取
+- `app.config.globalProperties.$actionBridge` — 全局属性访问
+
+### useActionBridge
+
+Composition API Hook，获取当前 ActionBridge 实例。必须在安装 `createActionBridgePlugin` 后使用。
+
+**示例：**
+
+```javascript
+// Composition API
+export default {
+  setup() {
+    const bridge = useActionBridge();
+
+    const enterRoom = async (roomId) => {
+      await bridge.enterRoom(roomId);
+    };
+
+    return { enterRoom };
+  }
+}
+
+// Options API（通过 $actionBridge）
+export default {
+  methods: {
+    async enterRoom(roomId) {
+      await this.$actionBridge.enterRoom(roomId);
+    }
+  }
+}
+```
+
+---
+
+## 数据类型
+
+### Jump
+
+跳转 Action 数据。
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `constructor(path)` | path: string (必填) | 创建跳转数据 |
+| `setText(text)` | text: string | 设置显示文本，返回 this |
+| `setPath(path)` | path: string (必填) | 设置跳转路径，返回 this |
+
+### Navigate
+
+导航 Action 数据。
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `constructor(screen, params?)` | screen: string (必填), params?: Object | 创建导航数据 |
+| `setText(text)` | text: string | 设置显示文本，返回 this |
+| `setScreen(screen)` | screen: string (必填) | 设置目标页面，返回 this |
+| `setParams(params)` | params: Object | 设置导航参数，返回 this |
+
+### Replace
+
+替换导航 Action 数据，继承自 Navigate，API 相同。
+
+### EnterRoom
+
+进房 Action 数据。
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `constructor()` | - | 创建进房数据 |
+| `setText(text)` | text: string | 设置显示文本，返回 this |
+| `setId(id)` | id: number | 设置房间 ID，返回 this |
+| `setMatch(match)` | match: string | 设置匹配信息，返回 this |
+| `setUseReplace(useReplace)` | useReplace: boolean | 设置是否替换模式，返回 this |
+| `addOpenGiftPopupCallback(cb)` | cb: OpenGiftPopupCallback | 添加打开礼物弹窗回调，返回 this |
+| `addOpenGameCallback(cb)` | cb: OpenGameCallback | 添加打开游戏回调，返回 this |
+| `addOpenActivityCallback(cb)` | cb: OpenActivityCallback | 添加打开活动回调，返回 this |
+| `addSwitchRoomTypeCallback(cb)` | cb: SwitchRoomTypeCallback | 添加切换房间类型回调，返回 this |
+
+**静态属性：**
+
+| 属性 | 说明 |
+|------|------|
+| `EnterRoom.CallbackType` | 回调类型枚举：OPEN_GIFT_POPUP, OPEN_GAME, OPEN_ACTIVITY, SWITCH_ROOM_TYPE |
+| `EnterRoom.OpenGiftPopupCallback` | 礼物弹窗回调类 |
+| `EnterRoom.OpenGameCallback` | 游戏回调类 |
+| `EnterRoom.OpenActivityCallback` | 活动回调类 |
+| `EnterRoom.SwitchRoomTypeCallback` | 切换房间类型回调类 |
+
+### LiveDetect
+
+活体检测 Action 数据。
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `constructor()` | - | 创建活体检测数据 |
+| `setText(text)` | text: string | 设置显示文本，返回 this |
+
+### Onelink
+
+Onelink Action 数据。
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `constructor(url?)` | url?: string | 创建 Onelink 数据 |
+| `setText(text)` | text: string | 设置显示文本，返回 this |
+| `setUrl(url)` | url: string (必填) | 设置链接 URL，返回 this |
+| `setShare(share)` | share: boolean | 设置是否显示分享弹窗，返回 this |
+
+### Action
+
+Action 对象，封装类型和数据。
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `constructor(type, data)` | type: ActionType, data: ActionData | 创建 Action |
+| `setType(type)` | type: ActionType | 设置 Action 类型，返回 this |
+| `setData(data)` | data: ActionData | 设置 Action 数据，返回 this |
+| `setBaseData(text)` | text: string | 设置数据的 text 字段（便捷方法），返回 this |
+| `toJson()` | - | 序列化为 JSON 字符串 |
+
+---
+
+## 构建
+
+```bash
+# 构建所有 UMD 文件
+npm run build
+
+# 仅构建核心包
+npm run build:core
+
+# 仅构建完整包
+npm run build:bridge
+
+# 监听模式（开发时使用）
+npm run build:watch
+```
+
+**产出文件：**
+
+| 文件 | 说明 | 全局变量 |
+|------|------|----------|
+| `build/js/action_creator.umd.js` | 核心包（仅 ActionCreator） | `__action_creator__` |
+| `build/js/action_bridge.umd.js` | 完整包（ActionCreator + Bridge + Adapters） | `__action_bridge__` |