# Changelog

## @1.0.8 (2026-06-17)

### 新增

- **Track Action（统计事件上报）**: 新增统计事件上报动作类型
  - `ActionType.TRACK` = `'track'`
  - `Track` 数据类：必填字段 `name`(string，事件名)；可选字段 `params`(Record，事件参数)、`options`(Record，事件选项)、`text`
  - `ActionCreator.buildTrack(name)`、`createTrackAction(name)`、`createTrackActionWithData(track)`
  - `ActionBridge.track(name, params?, options?)`、`buildTrack(name)`、`createTrackAction(name)`、`createTrackActionWithData(track)`
  - `bridge.track(name, params, options)` 便捷方法支持传入事件参数和选项

- **GrantBenefits Action（权益下发）**: 新增权益下发动作类型
  - `ActionType.GRANT_BENEFITS` = `'grant_benefits'`
  - `GrantBenefits` 数据类：必填字段 `benefits`(BSBenefit[]，下发权益列表)；可选字段 `title`(弹窗标题)、`message`(弹窗消息)、`okAction`(Action，确认按钮动作)、`closeable`(boolean，是否允许关闭，默认 true)、`duration`(number，自动关闭时间，单位 ms)、`theme`(弹窗主题配置)、`text`
  - `GrantBenefits.Theme` 内部类：`image`(主题图片)、`tintColor`(主题色)、`buttonImage`(按钮图片，可选)、`topInset`(头部高度，默认 196)
  - `ActionCreator.buildGrantBenefits(benefits)`、`createGrantBenefitsAction(benefits)`、`createGrantBenefitsActionWithData(grantBenefits)`
  - `ActionBridge.grantBenefits(benefits, options?)`、`buildGrantBenefits(benefits)`、`createGrantBenefitsAction(benefits)`、`createGrantBenefitsActionWithData(grantBenefits)`
  - `bridge.grantBenefits(benefits, options)` 便捷方法支持传入可选配置对象

### Action 类型完整列表

| 类型 | 字段 | 说明 |
|------|------|------|
| jump | path: string, text?: string | 页面跳转 |
| navigate | screen: string, params?: Record, text?: string | 导航到指定屏幕 |
| replace | screen: string, params?: Record, text?: string | 替换当前页面 |
| goback | text?: string | 返回上一页 |
| enter_room | id?: number, match?: string, callbacks?: Record, useReplace?: boolean, text?: string | 进入房间 |
| live_detect | text?: string | 活体检测 |
| onelink | url: string, share?: boolean, text?: string | 分享链接 |
| agency_invite | id: number, type: string, title?: string, message?: string, agencyInfo?: AgencyInfo, accepted?: boolean, text?: string | 工会邀请 |
| recharge | text?: string | 充值操作 |
| close | text?: string | 关闭 WebView 窗口（addon 附加） |
| config | theme?: 'dark' \| 'light', brandColor?: string, tintColor?: string, title?: string, text?: string | 配置 WebView 主题（addon 附加） |
| track | name: string, params?: Record, options?: Record, text?: string | 统计事件上报 |
| grant_benefits | benefits: any[], title?: string, message?: string, okAction?: Action, closeable?: boolean, duration?: number, theme?: { image, tintColor, buttonImage?, topInset? }, text?: string | 权益下发 |

---

## @1.0.7 (2026-06-10)

### 新增

- **sendAction 单次超时配置**: `ActionBridge.sendAction` 与适配器 `sendAction` 新增 `option?: { timeout?: number }` 参数
  - `timeout` 默认使用全局 `timeout`(适配器构造时传入,默认 30000ms)
  - 仅当 `timeout > 0` 时启用超时检测；传 `0` 或负值可禁用单次超时
  - `ActionBridge.sendAction` 支持以下调用方式（向后兼容）：
    - `sendAction(action)`
    - `sendAction(action, callback)` — 旧的回调风格
    - `sendAction(action, option)` — 第二个参数为对象时识别为 option
    - `sendAction(action, callback, option)`
  - 类型新增：`SendActionOption` 接口由 `@yagolive/event-kit/adapters` 导出
  - `MockAdapter` 的 `MockCall` 新增可选 `option` 字段,便于测试断言

### 使用示例

```javascript
// 自定义单次超时(毫秒)
await bridge.sendAction(action, { timeout: 5000 });

// 禁用单次超时
await bridge.sendAction(action, { timeout: -1 });
```

---

## @1.0.6 (2026-06-09)

### 新增

- **Close Action（addon 附加类型）**: 新增关闭 WebView 窗口动作类型
  - `ActionType.CLOSE` = `'close'`
  - `Close` 数据类：仅含 `text` 可选字段（继承自 `Base`）
  - `ActionCreator.buildClose()`、`createCloseAction()`、`createCloseActionWithData()`
  - `ActionBridge.close()`、`buildClose()`、`createCloseAction()`、`createCloseActionWithData()`
  - 来源：`packages/@yagolive/event_kit/addon.ts` 中的 `AddonAction`，由宿主容器扩展

- **Config Action（addon 附加类型）**: 新增配置 WebView 主题/品牌色动作类型
  - `ActionType.CONFIG` = `'config'`
  - `Config` 数据类：可选字段 `theme`（`'dark' | 'light'`）、`brandColor`（string）、`tintColor`（string）、`title`（string，页面标题）、`text`
  - `Config.Theme` 枚举：`DARK = 'dark'`、`LIGHT = 'light'`
  - `ActionCreator.buildConfig()`、`createConfigAction()`、`createConfigActionWithData()`
  - `ActionBridge.config(options?)`、`buildConfig()`、`createConfigAction()`、`createConfigActionWithData()`
  - `bridge.config()` 便捷方法接受 `{ theme?, brandColor?, tintColor?, title? }` 配置对象
  - 来源：`packages/@yagolive/event_kit/addon.ts` 中的 `AddonAction`，由宿主容器扩展

### Action 类型完整列表

| 类型 | 字段 | 说明 |
|------|------|------|
| jump | path: string, text?: string | 页面跳转 |
| navigate | screen: string, params?: Record, text?: string | 导航到指定屏幕 |
| replace | screen: string, params?: Record, text?: string | 替换当前页面 |
| goback | text?: string | 返回上一页 |
| enter_room | id?: number, match?: string, callbacks?: Record, useReplace?: boolean, text?: string | 进入房间 |
| live_detect | text?: string | 活体检测 |
| onelink | url: string, share?: boolean, text?: string | 分享链接 |
| agency_invite | id: number, type: string, title?: string, message?: string, agencyInfo?: AgencyInfo, accepted?: boolean, text?: string | 工会邀请 |
| recharge | text?: string | 充值操作 |
| close | text?: string | 关闭 WebView 窗口（addon 附加） |
| config | theme?: 'dark' \| 'light', brandColor?: string, tintColor?: string, title?: string, text?: string | 配置 WebView 主题（addon 附加） |

---

## @1.0.5 (2026-06-08)

### 新增

- **Recharge Action**: 新增充值操作动作类型
  - `ActionType.RECHARGE` = `'recharge'`
  - `Recharge` 数据类：仅含 `text` 可选字段（继承自 `Base`）
  - `ActionCreator.buildRecharge()`、`createRechargeAction()`、`createRechargeActionWithData()`
  - `ActionBridge.recharge()`、`buildRecharge()`、`createRechargeAction()`、`createRechargeActionWithData()`

### Action 类型完整列表

| 类型 | 字段 | 说明 |
|------|------|------|
| jump | path: string, text?: string | 页面跳转 |
| navigate | screen: string, params?: Record, text?: string | 导航到指定屏幕 |
| replace | screen: string, params?: Record, text?: string | 替换当前页面 |
| goback | text?: string | 返回上一页 |
| enter_room | id?: number, match?: string, callbacks?: Record, useReplace?: boolean, text?: string | 进入房间 |
| live_detect | text?: string | 活体检测 |
| onelink | url: string, share?: boolean, text?: string | 分享链接 |
| agency_invite | id: number, type: string, title?: string, message?: string, agencyInfo?: AgencyInfo, accepted?: boolean, text?: string | 工会邀请 |
| recharge | text?: string | 充值操作 |

---

## @1.0.4 (2026-05-28)

### 修改

- **EnterRoom.match 字段类型规范化**: 明确 `match` 字段类型为 `BSRoomMatchType` 枚举值
  - 支持的匹配类型：`'recommend'`（推荐房间列表）、`'follow'`（关注）、`'agency'`（本公会的公会房）
  - 移除了之前兼容的 `'hot'`、`'top3'` 字符串值
  - JS/d.ts 类型保持 `string | null`，确保向后兼容性
  - 测试页面新增 `testEnterRoomWithMatch()` 函数用于测试匹配模式

### Action 类型完整列表

| 类型 | 字段 | 说明 |
|------|------|------|
| jump | path: string, text?: string | 页面跳转 |
| navigate | screen: string, params?: Record, text?: string | 导航到指定屏幕 |
| replace | screen: string, params?: Record, text?: string | 替换当前页面 |
| goback | text?: string | 返回上一页 |
| enter_room | id?: number, match?: string, callbacks?: Record, useReplace?: boolean, text?: string | 进入房间 |
| live_detect | text?: string | 活体检测 |
| onelink | url: string, share?: boolean, text?: string | 分享链接 |
| agency_invite | id: number, type: string, title?: string, message?: string, agencyInfo?: AgencyInfo, accepted?: boolean, text?: string | 工会邀请 |

---

## @1.0.3 (2026-05-27)

### 修改

- **AgencyInfo 字段扩展**: 为 `AgencyInvite.AgencyInfo` 内部类新增 `ownerAvatar` 字段
  - 新增 `ownerAvatar?: string`（工会长头像 URL）
  - JS: `AgencyInfo` 类新增 `getOwnerAvatar()` / `setOwnerAvatar(ownerAvatar)` 方法
  - Java: `AgencyInfo` 类新增 `getOwnerAvatar()` / `setOwnerAvatar(String ownerAvatar)` 方法
  - `toMap()` 方法同步新增 `ownerAvatar` 字段处理

### Action 类型完整列表

| 类型 | 字段 | 说明 |
|------|------|------|
| jump | path: string, text?: string | 页面跳转 |
| navigate | screen: string, params?: Record, text?: string | 导航到指定屏幕 |
| replace | screen: string, params?: Record, text?: string | 替换当前页面 |
| goback | text?: string | 返回上一页 |
| enter_room | id?: number, match?: string, callbacks?: Record, useReplace?: boolean, text?: string | 进入房间 |
| live_detect | text?: string | 活体检测 |
| onelink | url: string, share?: boolean, text?: string | 分享链接 |
| agency_invite | id: number, type: string, title?: string, message?: string, agencyInfo?: AgencyInfo, accepted?: boolean, text?: string | 工会邀请 |

### AgencyInfo 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 工会ID |
| name | string | 工会名称 |
| ownerId | string | 工会长用户ID |
| ownerName | string | 工会长名称 |
| ownerAvatar | string | 工会长头像URL |

---

## @1.0.2 (2026-05-26)

### 新增

- **AgencyInvite Action**: 新增工会邀请动作类型
  - `ActionType.AGENCY_INVITE` = `'agency_invite'`
  - `AgencyInvite` 数据类：必填字段 `id`(number)、`type`('to_be_member' | 'to_be_subagency')；可选字段 `title`、`message`、`agencyInfo`(嵌套对象)、`accepted`(boolean)、`text`
  - `AgencyInvite.AgencyInfo` 内部类：`id`、`name`、`ownerId`、`ownerName`
  - `AgencyInvite.AgencyInviteType` 枚举：`TO_BE_MEMBER`、`TO_BE_SUBAGENCY`
  - `ActionCreator.buildAgencyInvite(id, type)`、`createAgencyInviteAction(id, type)`、`createAgencyInviteActionWithData(agencyInvite)`
  - `ActionBridge.agencyInvite(id, type)`、`buildAgencyInvite(id, type)`、`createAgencyInviteAction(id, type)`、`createAgencyInviteActionWithData(agencyInvite)`

### Action 类型完整列表

| 类型 | 字段 | 说明 |
|------|------|------|
| jump | path: string, text?: string | 页面跳转 |
| navigate | screen: string, params?: Record, text?: string | 导航到指定屏幕 |
| replace | screen: string, params?: Record, text?: string | 替换当前页面 |
| goback | text?: string | 返回上一页 |
| enter_room | id?: number, match?: string, callbacks?: Record, useReplace?: boolean, text?: string | 进入房间 |
| live_detect | text?: string | 活体检测 |
| onelink | url: string, share?: boolean, text?: string | 分享链接 |
| agency_invite | id: number, type: string, title?: string, message?: string, agencyInfo?: AgencyInfo, accepted?: boolean, text?: string | 工会邀请 |

---

## @1.0.1 (2026-05-22)

### 新增

- **Goback Action**: 新增返回上一页动作类型
  - `ActionType.GOBACK` = `'goback'`
  - `Goback` 数据类：仅含 `text` 可选字段
  - `ActionCreator.buildGoback()`、`createGobackAction()`、`createGobackActionWithData()`
  - `ActionBridge.goback()`、`buildGoback()`、`createGobackAction()`、`createGobackActionWithData()`

### 修复

- 修复 Java `ActionData.Base` 接口 `setText()` 返回类型从 `void` 改为 `Base`，解决链式调用编译错误

---

## @1.0.0 (2026-05-22)

### 新增

- **分层架构重构**: 将原有单体文件拆分为 Core / Adapters / Bridge / Integrations 四层架构
  - Core 层: 零环境依赖的 Action 创建逻辑
  - Adapters 层: 可插拔的通信适配器（RNWebViewAdapter、MockAdapter）
  - Bridge 层: 统一的 ActionBridge 接口，注入适配器实现跨环境通信
  - Integrations 层: React / Vue 3 框架集成

- **ActionCreator**:
  - `ActionCreator.ActionData`: 包含 Jump、Navigate、Replace、EnterRoom、LiveDetect、Onelink 数据类型
  - `ActionCreator.ActionType`: Action 类型枚举（JUMP、NAVIGATE、REPLACE、ENTER_ROOM、LIVE_DETECT、ONELINK）
  - 工厂方法: buildJump、createJumpAction、createJumpActionWithData、buildNavigate、createNavigateAction、createNavigateActionWithParams、createNavigateActionWithData、buildReplace、createReplaceAction、createReplaceActionWithParams、createReplaceActionWithData、buildEnterRoom、createEnterRoomAction、createEnterRoomActionWithData、buildLiveDetect、createLiveDetectAction、createLiveDetectActionWithData、buildOnelink、createOnelinkAction、createOnelinkActionWithData

- **ActionBridge**: 统一桥接接口
  - 构造函数注入适配器，支持自定义通信实现
  - Promise + 回调双重支持: `sendAction(action, callback?)` 返回 Promise
  - 便捷方法: jump、navigate、replace、enterRoom、liveDetect、onelink
  - 委托方法: 每种 Action 类型均提供 buildXxx、createXxxAction、createXxxActionWithData
  - 静态工厂: `createDefault()`、`createWithMock()`

- **RNWebViewAdapter**: React Native WebView 通信适配器
  - 自动检测 Android/iOS 平台注册消息监听
  - 超时机制（默认 30 秒）
  - 通过 `window.ReactNativeWebView.postMessage` 发送消息

- **MockAdapter**: 测试用适配器
  - mockResult / mockError 配置预期返回
  - getCalls 记录调用历史
  - 可配置响应延迟

- **React 集成**: `@yagolive/event-kit/react`
  - `ActionBridgeProvider`: Context Provider 组件
  - `useActionBridge`: Hook 获取 Bridge 实例

- **Vue 3 集成**: `@yagolive/event-kit/vue`
  - `createActionBridgePlugin`: Vue 插件
  - `useActionBridge`: Composition API Hook
  - `$actionBridge`: 全局属性访问

- **UMD 打包**: esbuild 自动构建
  - `build/js/action_creator.umd.js`: 核心包（全局变量 `__action_creator__`，访问方式: `window.__action_creator__.ActionCreator`）
  - `build/js/action_bridge.umd.js`: 完整包（全局变量 `__action_bridge__`，访问方式: `window.__action_bridge__.ActionBridge`）
  - 支持 Browser script 标签、CommonJS、AMD

- **子路径导出**: package.json exports 支持 `@yagolive/event-kit`、`@yagolive/event-kit/core`、`@yagolive/event-kit/react`、`@yagolive/event-kit/vue`、`@yagolive/event-kit/bridge`、`@yagolive/event-kit/adapters`
- **TypeScript 类型定义**: 每个子路径均提供 `index.d.ts` 类型声明

### Action 类型详情

| 类型 | 字段 | 说明 |
|------|------|------|
| jump | path: string, text?: string | 页面跳转 |
| navigate | screen: string, params?: Record, text?: string | 导航到指定屏幕 |
| replace | screen: string, params?: Record, text?: string | 替换当前页面 |
| enter_room | id?: number, match?: string, callbacks?: Record, useReplace?: boolean, text?: string | 进入房间 |
| live_detect | text?: string | 活体检测 |
| onelink | url: string, share?: boolean, text?: string | 分享链接 |

### EnterRoom 回调类型

| 回调类型 | 字段 | 说明 |
|----------|------|------|
| open_gift_popup | id?: number, type?: string, count?: number | 打开礼物弹窗 |
| open_game | id: number | 打开游戏 |
| open_activity | id: string | 打开活动页 |
| switch_room_type | type: string | 切换房间类型 |