@goplus123/core-api 1.1.2 → 1.1.3

package/README.md

@@ -11,6 +11,17 @@
 
 ---
 
+## 目录
+
+- [快速开始](#快速开始)
+- [调用链路概览](#调用链路概览)
+- [Transport 选择规则](#transport-选择规则)
+- [WS 推送与事件](#ws-推送与事件)
+- [错误处理](#错误处理)
+- [API 参考（对外导出）](#api-参考对外导出)
+- [spec 驱动的 Service 列表](#spec-驱动的-service-列表)
+- [开发指南：如何补充 spec 路由](#开发指南如何补充-spec-路由)
+
 ## 设计方案与思路
 
 ### 这是什么
@@ -40,7 +51,7 @@
 ### 关键设计原则（对后续重构/AI 重设计很重要）
 
 - 单一装配点：只允许通过 `initSDK()` 构建/覆盖全局状态，避免“到处 new client”导致的状态分裂
-- 显式路由表：所有“能被 requestApi 路由”的能力必须可在 spec 中静态看到（便于审计、自动化生成、AI 重构）
+- 显式路由表：`requestApi` 优先按 spec 路由；迁移期允许显式 `transport: 'ws'` 走 raw WS 兜底
 - transport 无关的调用链：上层只关心 EndpointSpec 与请求参数；transport 细节由 UnifiedApiClient 分发
 - 横切能力可插拔：拦截器链（interceptors）是统一入口，避免散落在各 transport 内部
 - 向后兼容优先：spec 未命中时允许落到 legacy serviceInstances 或 raw WS 兜底（便于迁移期稳定）
@@ -109,6 +120,36 @@ spec 的职责是提供“可路由的接口清单”，而不是提供具体实
 
 拦截器的设计意图是把“与业务接口无关的能力”统一实现一次，三种 transport 复用同一条链路。
 
+### 内置拦截器如何启用
+
+SDK 默认只开放“配置式启用”内置拦截器（业务侧目前不需要也不支持直接注入自定义 `ApiInterceptor`）。
+
+```ts
+import { initSDK } from '@goplus123/core-api'
+
+initSDK({
+  http: { baseUrl: 'https://api.example.com' },
+  grpc: { baseUrl: 'https://grpc.example.com' },
+  ws: { url: 'wss://ws.example.com' },
+  headerConfig: {
+    version: '1',
+    platformId: 'web',
+    isReload: false,
+    deviceType: 'web',
+    childPlatformId: 'web',
+  },
+  auth: {
+    getToken: () => localStorage.getItem('token'),
+  },
+  logger: console,
+})
+```
+
+启用效果：
+
+- HTTP/gRPC：通过拦截器把 token 注入到请求头
+- WS：token 由 `WsClient` 在连接 URL/query 或消息体中携带（受浏览器限制无法设置自定义 header）
+
 ### token/header 注入策略
 
 `initSDK({ auth })` 提供的 `getToken/getHeaders` 会被注入到：
@@ -132,6 +173,32 @@ spec 的职责是提供“可路由的接口清单”，而不是提供具体实
 - 让上层（UI/日志/监控）用一致结构处理错误，不必分辨来自 HTTP/WS/gRPC
 - 把错误分为三类：`biz / transport / unknown`，用于更合理的告警与重试策略
 
+### 业务侧案例：统一判断 token 失效（401/403）
+
+业务侧推荐用 `apiError.use(...)` 或 `initSDK({ onApiError })` 统一处理鉴权失效，而不是在每个接口单独 try/catch。
+
+```ts
+import { apiError } from '@goplus123/core-api'
+
+apiError.use((error, _ctx, next) => {
+  const isHttpAuthFailed =
+    error.transport === 'http' && (error.status === 401 || error.status === 403)
+
+  const isGrpcAuthFailed =
+    error.transport === 'grpc' &&
+    (error.code === 7 || error.code === 16)
+
+  const isWsAuthFailed =
+    error.transport === 'ws' && (error.status === 401 || error.status === 403 || error.code === 403)
+
+  if (isHttpAuthFailed || isGrpcAuthFailed || isWsAuthFailed) {
+    // 例如：清 token、跳转登录、或触发 refresh token 流程
+  }
+
+  return next()
+})
+```
+
 ---
 
 ## 依赖与技术方案清单
@@ -255,6 +322,7 @@ const sdk = initSDK({
 - `sdk.api`：底层 `RequestApi`（包含 `http/ws/grpc` 三个 client）
 - `sdk.client`：统一路由分发的 `UnifiedApiClient`
 - `sdk.rpc`：对外暴露的 `WsRpcClient`（便于调试 / 订阅）
+- `sdk.wsNotify`：底层 `WsNotifyCenter`（直接订阅 WS 推送事件）
 - `sdk.cms / sdk.admin / sdk.platform`：类型安全的 service client（由 spec 生成）
 - `sdk.apiError / sdk.notify`：全局错误与通知中心（同名导出也可直接使用）
 
@@ -709,6 +777,41 @@ await requestApi({
 
 ## WS 推送与事件
 
+`notify(type)` 返回一个通知通道（channel），用于承接两类事件：
+
+- 服务端 WS 推送：初始化了 `ws` 时，会自动挂载到 `ws.notify`，把推送分发到同名 channel
+- 本地事件分发：可用 `emit` 主动触发（不发给服务端），用于调试/桥接
+
+channel 支持的方法：
+
+- `use(middleware)`：注册中间件（可在内部决定是否继续传递）
+- `subscribe(listener)`：注册订阅者（等价于一个简单的中间件包装）
+- `emit(payload)`：主动触发一次本地分发
+- `destroy()`：销毁该 type 的 channel 与所有监听
+
+### 直接订阅 wsNotify
+
+如果你想绕开 `notify(type)` 的 channel/middleware 机制，直接订阅 WS 推送事件，可以使用 `sdk.wsNotify`：
+
+```ts
+const sdk = initSDK({
+  ws: { url: 'wss://example.com/websocket' },
+  headerConfig: {
+    version: '1.0.0',
+    platformId: '0',
+    isReload: false,
+    deviceType: 1,
+    childPlatformId: '0',
+  },
+} as any)
+
+const off = sdk.wsNotify?.on<{ gameId: string }>('notifyGameInfo', (payload) => {
+  console.log('game info:', payload)
+})
+
+// off?.()
+```
+
 ### 订阅 WS 推送
 
 `notify(type)` 会创建一个 channel，并在初始化了 `ws` 时自动挂载到 `ws.notify`。
@@ -721,6 +824,36 @@ const off = notify<{ gameId: string }>('notifyGameInfo').subscribe((payload) =>
 // off()
 ```
 
+### notify 中间件（use）
+
+`use` 适合做过滤、埋点、转换、桥接等逻辑；签名为 `(payload, ctx, next) => any`，调用 `next()` 才会继续向后传递。
+
+```ts
+import { notify } from '@goplus123/core-api'
+
+notify<{ level: 'info' | 'error'; message: string }>('app:log').use((payload, _ctx, next) => {
+  if (payload.level !== 'error') return
+  console.log('[app:log][error]', payload.message)
+  return next()
+})
+```
+
+### 主动触发 notify（emit）
+
+`notify(type).emit(payload)` 可以主动触发一次本地事件分发（不会发给服务端），常用于调试/本地桥接复用同一套订阅机制。
+
+```ts
+import { notify } from '@goplus123/core-api'
+
+const off = notify<{ type: number }>('wsStatus').subscribe((payload) => {
+  console.log('wsStatus payload:', payload.type)
+})
+
+notify('wsStatus').emit({ type: 2 })
+
+off()
+```
+
 ### 监听 WS 连接状态
 
 SDK 内置了 `ws:status` 通道（初始化时自动绑定到 WS 事件）：
@@ -779,6 +912,9 @@ apiError.use((error, ctx, next) => {
 ### requestApi(args) / callApi(args)
 
 - 作用：统一调用入口（spec 驱动路由；若 spec 未命中，会尝试 legacy serviceInstances，再兜底走 raw WS）
+- 别名：
+  - `callApi`：`requestApi` 的同名别名
+  - `requestApiSpec`：`requestApi` 的同名别名（历史兼容）
 - 入参：
   - `service: string`
   - `functionName: string`
@@ -788,16 +924,33 @@ apiError.use((error, ctx, next) => {
   - `callOptions?: CallOptions`
   - `meta?: Record<string, any>`
 
+### getWsSnapshot()
+
+- 作用：同步获取 WS 连接状态快照（不依赖订阅）
+- 返回：`{ readyState?: number; isConnected: boolean; status?: WsStatusPayload }`
+
 ### notify(type)
 
-- 作用：获取通知通道（可 `use/subscribe/emit/destroy`）
-- 注意：未初始化会返回 dummy channel（不会报错，但会 warn）
+- 作用：获取通知通道（channel）
+- 方法：
+  - `use(middleware)`：注册中间件；返回 `off()` 用于注销当前中间件
+  - `subscribe(listener)`：注册订阅者；返回 `off()` 用于注销当前订阅
+  - `emit(payload)`：主动触发一次本地分发（不发给服务端）
+  - `destroy()`：销毁该 type 的 channel 与所有监听
+- 注意：未初始化时调用 `emit` 为 no-op（会 warn）；`use/subscribe` 可提前注册，初始化后会自动挂载到 WS 推送
 
 ### apiError
 
 - `apiError.use(middleware)`：注册错误中间件
 - `apiError.emit(error, source?)`：手动注入一个归一化后的 `ApiError`
 
+### 类型导出（常用）
+
+- `WsStatusState` / `WsStatusPayload`：WS 状态类型（配合 `ws:status` 与 `getWsSnapshot`）
+- `ApiErrorMiddleware`：`apiError.use(...)` 的中间件签名
+- `NotifyMiddleware`：`notify(type).use(...)` 的中间件签名
+- `KeyValueStorage`：unikey 存储抽象
+
 ### fetchGuid()
 
 - 作用：生成/读取一个稳定的设备唯一标识（unikey），用于跨请求/跨连接的设备识别
@@ -866,17 +1019,34 @@ setUniqueKeyStorage(appStorage)
 
 spec 定义入口：[`spec/index.ts`](./src/spec/index.ts)
 
+说明：
+
+- spec 影响的是 `requestApi` 的路由表（能让 `requestApi({ service, functionName })` 正确选 transport）
+- 当前 `initSDK()` 默认只创建了 `sdk.cms / sdk.admin / sdk.platform` 三个“类型安全的 service client”
+- 其它 spec service 仍然可以通过 `requestApi` 调用（必要时再扩展 sdk 返回值即可）
+
 按 service 拆分的落点文件：
 
-- cms：[`spec/cms.ts`](./src/spec/cms.ts)
 - admin：[`spec/admin.ts`](./src/spec/admin.ts)
+- auth：[`spec/auth.ts`](./src/spec/auth.ts)
+- cms：[`spec/cms.ts`](./src/spec/cms.ts)
+- packet：[`spec/packet.ts`](./src/spec/packet.ts)
+- payment：[`spec/payment.ts`](./src/spec/payment.ts)
+- player：[`spec/player.ts`](./src/spec/player.ts)
 - platform：[`spec/platform.ts`](./src/spec/platform.ts)
+- promotion：[`spec/promotion.ts`](./src/spec/promotion.ts)
+- provider：[`spec/provider.ts`](./src/spec/provider.ts)
+- recommend：[`spec/recommend.ts`](./src/spec/recommend.ts)
+- riskcontrol：[`spec/riskcontrol.ts`](./src/spec/riskcontrol.ts)
+- userEngagement：[`spec/userEngagement.ts`](./src/spec/userEngagement.ts)
 
-### cms（gRPC 为主，部分接口可多协议）
+### cms（gRPC 为主，部分接口可多协议；支持 sdk.cms）
 
 - `getPageResource`
 - `getPageGameList`（multi：grpc + ws）
+- `getPageGameListV2`（multi：grpc + ws）
 - `getJackpotResources`
+- `getJackpotConfig`
 - `readPopup`
 - `readEventPopup`
 - `getAmbassadorConfig`
@@ -887,7 +1057,7 @@ spec 定义入口：[`spec/index.ts`](./src/spec/index.ts)
 - `getSportTodayMatch`
 - `getGameSuggestions`
 
-### admin（gRPC）
+### admin（gRPC；支持 sdk.admin）
 
 - `signIn`
 - `getAdminProfileByJwt`
@@ -902,10 +1072,65 @@ spec 定义入口：[`spec/index.ts`](./src/spec/index.ts)
 - `updateMarketingDepartmentConfig`
 - `deleteMarketingDepartmentConfig`
 
-### platform（WS）
+### platform（WS；支持 sdk.platform）
 
 - `getConfig`
 
+### riskcontrol（gRPC）
+
+- `getPlayerDepositLimitStateOverview`
+- `updatePlayerDepositLimitSwitch`
+- `updatePlayerPeriodDepositLimit`
+
+### userEngagement（gRPC）
+
+- `updatePWASubscriptionStatus`
+
+### provider（gRPC）
+
+- `getRecentPlayedGames`
+- `getLoginURL`
+
+### recommend（gRPC）
+
+- `saveSearchHistory`
+- `getSearchHistories`
+- `deleteSearchHistory`
+- `searchGames`
+
+### packet（gRPC）
+
+- `assignPacket`
+- `getServerTime`
+- `getPacketsInfo`
+- `grabFreeSpin`
+- `getEventGrabProgress`
+- `verifyPlayerPacket`
+- `verifyPlayerFreeSpin`
+- `playerClaimAllRewardsLite`
+
+### payment（gRPC）
+
+- `getCredit`
+- `getBankTypes`
+- `getBindBankCards`
+- `getAvailableDepositMethods`
+- `updatePaymentInfo`
+- `verifyUnionBank`
+- `getUnionBankTopUp`
+- `getPlayerDisbursements`
+- `claimPlayerDisbursement`
+- `getMud`
+- `getPlayerMudTransactions`
+- `getMudTransactionHistory`
+- `getCreditChangeNotifyMsg`
+- `removeCreditChangeNotifyMsg`
+- `getPlatformPlayerFreeSpinListing`
+
+### auth / player / promotion
+
+- 这三个 service 的 spec 方法较多，建议直接查看对应 spec 文件的 `export const <service>Endpoints` 键名。
+
 ---
 
 ## 为接口新增/扩展 transport（spec 写法）
@@ -918,7 +1143,9 @@ spec 的职责是给 `requestApi` 提供“路由表”：
 
 - runtime 上它会被加载进 `apiMap`，并在 `initSDK()` 时构建 registry（见 [`rebuildEndpointRegistry`](./src/routing/router.ts#L84-L132)）
 - 调用方可以通过 `sdk.<service>.<method>()` 或 `requestApi({ service, functionName })` 走到对应 transport
-- 当调用方显式指定 `transport` 时，如果 spec 中没有对应变体，会在路由选择阶段同步抛错
+- 当调用方显式指定 `transport` 时：
+  - `grpc/http`：若 spec 命中但没有对应变体，会在路由选择阶段同步抛错
+  - `ws`：若 spec 命中但没有对应变体，会兜底走 raw WS（需要已初始化 ws）
 
 ### 1) 选择落点文件