@cx00123/lunetale-game-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lunetale SDK contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# Lunetale 小游戏 AI / VIP 插件
+
+为 Lunetale 内的网页小游戏提供 AI 对话、真实 VIP/SVIP 查询。**当前原生接入支持 Android；iOS 未接入。** 游戏不需要 App 用户 ID、App 登录 token 或模型 API Key。
+
+## 1. 安装与最小接入
+
+```sh
+npm install @cx00123/lunetale-game-sdk
+```
+
+```js
+import { createGameClient, GameSDKError } from '@cx00123/lunetale-game-sdk'
+
+// Android 内无需填写域名、用户、游戏 ID 或密钥。
+const game = createGameClient()
+const membership = await game.getVIP()
+console.log(membership.isVip, membership.tier, membership.cost)
+
+const input = {
+  requestId: crypto.randomUUID(),
+  messages: [
+    { role: 'system', content: '你是岛上的向导，用简短中文回答。' },
+    { role: 'user', content: '我应该先探索哪里？' },
+  ],
+}
+try {
+  const reply = await game.chat(input)
+  document.querySelector('#reply').textContent = reply.content
+  console.log(reply.charged, reply.balance)
+} catch (error) {
+  if (error instanceof GameSDKError) {
+    // NETWORK / 42001 时保留 input，稍后 game.chat(input)。
+    // 不要为了重试生成新编号，否则可能作为新问题再次收费。
+    console.warn(error.code, error.message, error.requestId)
+  }
+}
+
+// 页面退出时可调用；只清除本页内存/等待，不表示服务端撤销或退款。
+// game.dispose()
+```
+
+无打包工具时，也可以在顶层 HTML 中通过 ESM CDN 导入（建议固定版本并在生产环境自行打包托管）：
+
+```html
+<script type="module">
+  import { createGameClient } from 'https://cdn.jsdelivr.net/npm/@cx00123/lunetale-game-sdk@0.1.0/src/index.js'
+  const game = createGameClient()
+  const vip = await game.getVIP()
+  document.querySelector('#vip').textContent = vip.isVip ? '会员' : '普通用户'
+</script>
+```
+
+SDK 不包含 UI，也不会自动执行模型回复。请用文本绑定或 `textContent` 展示；不要把回复直接写入 `innerHTML`、`eval`。
+
+## 2. 平台管理员准备
+
+1. 发布支持本 SDK 的后端并完成游戏定向迁移；安装新版 Android App。
+2. 「App 管理 → 大模型管理」建立并启用模型组，配置服务端上游密钥。
+3. 「App 管理 → 游戏管理 → 编辑」填写游戏 HTTPS 地址，配置：
+   - `aiEnabled`：AI 开关（老游戏迁移默认关闭）。
+   - `aiGroup`：模型组名称或 ID；网页不能覆盖模型。
+   - `aiCost`：每次成功调用积分，最多 4 位小数，0 表示免费。**积分复用 App 能量余额，不新建钱包。**
+   - `aiMaxTokens`：输出上限，1–8192，默认 1024。
+   - `aiSystemPrompt`：前置服务端系统提示词，不是密钥或安全权限规则。
+   - `vipOnly`：AI 仅限有效 VIP/SVIP；会员也按该游戏配置扣费，不自动免费。
+   - `runtimeOrigin`：最终运行页面的**精确 HTTPS origin**，例如 `https://games.example.com`，不带路径、末尾 `/`、通配符、用户名或密码。空值使用游戏 HTML 地址的 origin；跨域中转到 CDN 时需登记最终 CDN origin。
+4. 游戏要上架。SDK 必须运行在该 origin 的**顶层页面**；iframe、官网连接页和未登记来源没有原生 AI 桥。
+5. 后台「AI / VIP 插件接入」可查看简版说明。普通后台预览没有玩家授权，也不会偷偷消耗管理员或玩家积分。
+
+授权粒度是账号 + 游戏 + origin，不是 CDN 路径。同一 CDN origin 下的页面与脚本处于同一个浏览器信任域；不可信制作者应使用独立 origin。平台只应登记受信任内容，不应在游戏页面加载不可信第三方脚本。
+
+## 3. 授权与续期
+
+### Android（已接入）
+
+`SDK → Android 主框架来源校验 → Flutter 当前账号 → 后端授权码 → SDK 兑换专用凭证`
+
+- Flutter 用自己的 App JWT 调用 `POST /lunetale/game/authorize`；原生桥不接受网页指定 userId、gameId、模型、价格或任意 URL。
+- 授权码随机生成，**60 秒、只能兑换一次**，数据库只存其哈希。
+- Android 通过消息桥交付授权码，不把 App JWT 或授权码追加到游戏 URL。相比 fragment，原生消息桥避免额外跳转并保持已有 hash 路由。
+- SDK 兑换**2 小时**游戏专用签名凭证，只放内存；不会写 localStorage、sessionStorage、Cookie 或云存档。
+- 后端检查专用签名/受众/有效期、绑定账号与游戏、精确 origin、账号状态、游戏上架与 AI/VIP 权限。修改 JSON 中的用户、游戏、价格或模型不能越权（未知字段直接拒绝）。
+- 成功请求完成时，如果凭证**尚未过期且剩余 ≤10 分钟**，响应中携带新的 2 小时凭证，SDK 自动替换。续期失败不把已经完成的扣费请求伪装成失败；下次可重新授权。
+- 已过期：SDK 通过 App 当前登录态重新签发授权码，最多补授权重试一次；App 登录失效则要求用户重新登录。请求取消/账号切换/页面导航后的迟到桥回调不会发送到新页面。
+- App 的正常后端退出登录接口撤销该用户全部小游戏凭证；禁用/注销账号、游戏下架或更换 runtimeOrigin 后请求也会被拒绝。仅断网清除本机登录态无法承诺即时服务端撤销，未撤销凭证仍以服务端有效期为准。
+- Android 的 Runtime HTTP 请求由 Flutter 固定路径代理；网页即使知道当前开发 API 地址，也不能要求代理访问任意 URL。HTTPS 游戏连接本地 HTTP 开发 API 不需要启用 WebView 混合内容。生产仍必须使用 HTTPS API。
+
+### 独立浏览器 / 外部可信登录入口
+
+本 SDK 支持读取 `#lt_code=<60秒授权码>` 并**同步立即从地址栏删除**；保留其它 hash 片段。已有 hash 路由可在末尾追加 `&lt_code=...`。不要用 URL query 传授权码，不要传 App JWT。
+
+```js
+const game = createGameClient({
+  apiBase: 'https://api.example.com', // 如代理有 /api 前缀，请包含此前缀
+  // 可选：过期后由你自己的可信登录入口重新授权，只返回授权码。
+  // authorize: async () => ({ code, origin, expiresAt }),
+})
+const vip = await game.getVIP()
+```
+
+可信入口在自己的已登录环境调用 `/lunetale/game/authorize`（`x-token: App JWT`，body 为 `{gameId}`），校验跳转目标等于返回的 origin，再将授权码放进已登记游戏 URL 的 fragment。该入口必须隔离于第三方游戏，不能让游戏拿到 JWT。
+
+**当前交付未新增独立官网玩家登录系统。** 顶层官网提供文档入口；离开 Android 后如果没有可信授权入口，SDK 返回 `AUTH_REQUIRED`，不会伪造游客身份、VIP 或免费 AI。普通网页刷新后丢失内存凭证，需要新授权码；这是预期行为。可用 `authorize` 回调接入已有可信入口，跨窗口通信须严格校验 origin/source，禁止 `postMessage('*')` 传授权码。
+
+CDN 的 HTML、图片等静态文件仍可公开访问；这些凭证保护的是账号、VIP 与计费接口，**不是静态文件防下载机制**。
+
+## 4. SDK API
+
+| 方法 | 返回 / 行为 |
+| --- | --- |
+| `createGameClient(options?)` | 创建一个顶层页面客户端；调用时同步取走并清除 fragment 授权码 |
+| `ready()` | 完成授权；其它方法也会按需自动授权 |
+| `getVIP()` | `{isVip,tier,expiresAt,balance,aiEnabled,cost,vipOnly}` |
+| `isVIP()` | `boolean`；有效 VIP、SVIP 都是 true，查询失败会抛异常，不伪装为 false |
+| `chat({requestId?,messages})` | `{requestId,content,charged,balance}`；非流式完整回答 |
+| `dispose()` | 清除本页凭证并取消客户端等待，实例不能再次使用；不是退款或服务端撤销 |
+
+`messages`：1–64 条，role 为 `system/user/assistant`，内容非空，UTF-8 内容合计最多 64 KiB，最后一条必须是 user。每轮需要游戏自己提供所需的历史；SDK 不自动管理历史。服务端额外前置管理员系统提示词。
+
+`requestId`：16–64 位字母、数字、`_`、`-`，推荐 `crypto.randomUUID()`。省略时 SDK 自动生成；错误对象携带该编号。推荐显式创建并保存 `input`，保证网络重试不改变编号或历史消息。
+
+### 计费 / 并发 / 重试
+
+- 使用**请求开始时**的游戏价格；上游成功且结果与积分事务一起提交后才收费。余额不足、无权限、模型失败、超时不收费。
+- 同一账号最多一个进行中的小游戏 AI 请求，且新请求间隔至少 2 秒（含免费调用）；这是全后端实例共享的数据库控制。
+- 相同账号 + 游戏 + requestId + 原始 messages 重试返回原成功结果，**不重复调用模型或扣费**。原成功响应中的 balance 是当次历史余额，当前余额请调用 getVIP。
+- 相同 requestId 更换内容会被拒绝。不同的实际问题必须生成新编号。
+- 响应丢失不代表未扣费：`NETWORK` 或 `42001` 请保留原 input，稍后重试。SDK 不会无限自动重试付费请求。
+- 模型最长等待约 2 分钟；记录超过 3 分钟仍 pending 视为未完成终态，不再自动执行该编号。`42002` 确认本编号未提交扣费，可用新编号重试。
+- 成功结果与扣费原子提交；故障遗留的 pending 记录没有扣费。服务端保存成功回复用于幂等恢复，不保存原始 messages，仅保存内容哈希。
+- 页面刷新后 SDK 不保存请求队列。若游戏需要跨刷新恢复，把 requestId 和原始 messages 存在**该游戏自己的待同步记录**中（不包含任何凭证），重新授权后重试。已有 App localStorage 云存档能力独立工作，SDK 不收集账号存储。
+- 页面离开、网络断开和 `dispose()` 只停止客户端等待，不能撤回已在服务端成功提交的生成和扣费。
+
+### 错误码
+
+| code | 含义 / 处理 |
+| --- | --- |
+| `AUTH_REQUIRED` | 专用凭证失效，App 内自动补授权一次后仍失败则要求重新登录/重新打开 |
+| `40201` | 积分不足，引导用户在 App 充值 |
+| `40301` | 需要 VIP/SVIP，由 App 的会员购买流程处理 |
+| `42001` | 原编号仍在处理，稍后用相同 input 重试 |
+| `42002` | 原编号失败且未扣费，可创建新编号 |
+| `42003` | 原编号已绑定不同消息，修复编号复用问题 |
+| `42901` | 有进行中的请求或请求过于频繁，等待后重试 |
+| `7` | 游戏配置/参数/服务不可用，展示 message 并联系平台 |
+| `NETWORK` | 结果未知，保留原 requestId 重试 |
+| `NATIVE / UNSUPPORTED / ORIGIN / CONFIG / VALIDATION / PROTOCOL / DISPOSED / UNKNOWN` | 原生能力、运行环境、来源、参数、协议或生命周期问题 |
+
+不要用客户端 `isVip` 值替代后端权限检查，不要在积分不足时偷偷生成新 requestId 重试。
+
+## 5. HTTP 契约
+
+统一 `{code,data,msg}`。业务失败通常 HTTP 200 + 非零 code，专用凭证无效 HTTP 401。
+
+| 方法 | 路径 | 鉴权 | 请求 |
+| --- | --- | --- | --- |
+| POST | `/lunetale/game/authorize` | App `x-token` | `{gameId}` → `{code,expiresAt,origin}` |
+| POST | `/lunetale/game/revoke` | App `x-token` | `{gameId}`，撤销该账号该游戏全部专用授权 |
+| POST | `/lunetale/game/runtime/exchange` | `Origin` + 一次性 code | `{code}` → `{accessToken,expiresAt,gameId}` |
+| GET | `/lunetale/game/runtime/vip` | `Origin` + `Authorization: Bearer <游戏凭证>` | VIPStatus，可选 credential |
+| POST | `/lunetale/game/runtime/chat` | 同上 | `{requestId,messages}` → ChatResult，可选 credential |
+
+`credential` 是自动续期数据，形状同 exchange；SDK 自动消费并从公开返回对象中去掉。不允许客户端传 gameId/userId/model/cost/maxTokens 给 runtime/chat。Runtime 凭证签名使用用途隔离的密钥，不能用于 App 或后台接口。
+
+浏览器自动发送 Origin，游戏不可自行设置。专用 runtime 三个端点提供无 Cookie 的 HTTPS 跨域预检，实际请求仍严格校验凭证绑定来源；不会扩大普通 App/后台接口 CORS 权限。反向代理不能移除 Origin 或记录 Authorization、授权 body 和对话正文。
+
+## 6. 人工验收建议
+
+由平台和制作者在目标 Android/后端环境验证：普通账号/VIP/SVIP、会员过期、余额不足、0 积分、重复请求不重复扣费、相同 ID 不同消息、上游超时、返回/刷新/快速重进、换账号、游戏下架、错误 origin、iframe 隔离、授权码重复兑换/过期、10 分钟阈值续期及新授权后恢复原请求。
+
+此包的静态语法/类型检查不代表 App、模型调用、真实扣费或会员功能已验收。部署前请完成真实环境人工联调。

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cx00123/lunetale-game-sdk",
+  "version": "0.1.0",
+  "description": "Lunetale HTML game AI chat and VIP runtime SDK for Android WebView and authorized web games",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/index.js",
+    "src/index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "lunetale",
+    "html-game",
+    "ai",
+    "vip",
+    "webview"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "check": "node --check src/index.js && tsc --noEmit --strict --lib es2022,dom src/index.d.ts"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,49 @@
+export type Message = { role: 'system' | 'user' | 'assistant'; content: string }
+export interface AuthorizationGrant {
+  code: string
+  expiresAt?: string
+  origin?: string
+  apiBase?: string
+}
+export interface GameClientOptions {
+  /** HTTPS API base, including any reverse-proxy prefix; unnecessary inside Android. */
+  apiBase?: string
+  /** Trusted external launcher reauthorization. Do not put App JWTs in game code. */
+  authorize?: () => Promise<AuthorizationGrant>
+}
+export interface VIPStatus {
+  isVip: boolean
+  tier: 'normal' | 'vip' | 'svip'
+  expiresAt: string | null
+  balance: number
+  aiEnabled: boolean
+  cost: number
+  vipOnly: boolean
+}
+export interface ChatInput {
+  /** Preserve this ID AND the exact messages for network/pending retries. */
+  requestId?: string
+  messages: Message[]
+}
+export interface ChatResult {
+  requestId: string
+  content: string
+  charged: number
+  /** Balance at the original successful transaction; replay does not refresh it. */
+  balance: number
+}
+export class GameSDKError extends Error {
+  code: string | number
+  requestId?: string
+  constructor(code: string | number, message: string, options?: { requestId?: string; cause?: unknown })
+}
+export interface GameClient {
+  ready(): Promise<void>
+  getVIP(): Promise<VIPStatus>
+  /** Both active VIP and SVIP count as true. */
+  isVIP(): Promise<boolean>
+  chat(input: ChatInput): Promise<ChatResult>
+  /** Clears memory and cancels local waiting, not a server-side revoke/refund. */
+  dispose(): void
+}
+export function createGameClient(options?: GameClientOptions): GameClient

package/src/index.js

@@ -0,0 +1,234 @@
+/** Credentials are private closure state; importing this module performs no I/O. */
+export class GameSDKError extends Error {
+  constructor(code, message, { requestId, cause } = {}) {
+    super(message, { cause })
+    this.name = 'GameSDKError'
+    this.code = code
+    this.requestId = requestId
+  }
+}
+
+const transports = new WeakMap()
+function nativeTransport(bridge) {
+  if (transports.has(bridge)) return transports.get(bridge)
+  const pending = new Map()
+  bridge.onmessage = (event) => {
+    let message
+    try { message = JSON.parse(event.data) } catch { return }
+    const task = pending.get(message.id)
+    if (!task) return
+    pending.delete(message.id)
+    clearTimeout(task.timer)
+    if (message.error) task.reject(new GameSDKError('NATIVE', message.error))
+    else task.resolve(message.data)
+  }
+  const transport = {
+    call(message, owner, timeout) {
+      return new Promise((resolve, reject) => {
+        const id = crypto.randomUUID()
+        const timer = setTimeout(() => {
+          pending.delete(id)
+          reject(new GameSDKError('NETWORK', '请求超时，请保留 requestId 重试'))
+        }, timeout)
+        pending.set(id, { resolve, reject, timer, owner })
+        try { bridge.postMessage(JSON.stringify({ ...message, id })) } catch {
+          pending.delete(id)
+          clearTimeout(timer)
+          reject(new GameSDKError('NATIVE', '无法连接 App 游戏接口'))
+        }
+      })
+    },
+    dispose(owner) {
+      for (const [id, task] of pending) {
+        if (task.owner !== owner) continue
+        clearTimeout(task.timer)
+        task.reject(new GameSDKError('DISPOSED', '游戏客户端已关闭'))
+        pending.delete(id)
+      }
+    },
+  }
+  transports.set(bridge, transport)
+  return transport
+}
+
+// Remove the code synchronously, before any network wait; preserve other hash parameters.
+function takeFragmentCode() {
+  const raw = window.location.hash.slice(1)
+  const parts = raw.split('&')
+  let code
+  const kept = parts.filter((part) => {
+    const at = part.indexOf('=')
+    if (at < 0 || part.slice(0, at) !== 'lt_code') return true
+    try { code = decodeURIComponent(part.slice(at + 1)) } catch { code = '' }
+    return false
+  })
+  if (kept.length !== parts.length) {
+    const url = new URL(window.location.href)
+    url.hash = kept.join('&')
+    window.history.replaceState(window.history.state, '', url)
+  }
+  return code
+}
+
+export function createGameClient(options = {}) {
+  if (typeof window === 'undefined' || window.top !== window.self) {
+    throw new GameSDKError('UNSUPPORTED', 'SDK 只能在游戏顶层浏览器页面使用')
+  }
+  const fragmentCode = takeFragmentCode()
+  const bridge = window.LunetaleGameRuntime
+  const native = bridge && typeof bridge.postMessage === 'function' ? nativeTransport(bridge) : null
+  const owner = {}
+  const controllers = new Set()
+  const timeout = 160000
+  let credential = null
+  let authorizing = null
+  let initialCode = fragmentCode
+  let apiBase = options.apiBase || ''
+  let disposed = false
+
+  function checkOpen() {
+    if (disposed) throw new GameSDKError('DISPOSED', '游戏客户端已关闭')
+  }
+  function acceptCredential(value) {
+    if (!value || typeof value.accessToken !== 'string' || !Number.isFinite(Date.parse(value.expiresAt))) {
+      throw new GameSDKError('PROTOCOL', '游戏授权响应格式错误')
+    }
+    // Concurrent responses must not replace a newer credential with an older one.
+    if (!credential || Date.parse(value.expiresAt) >= Date.parse(credential.expiresAt)) credential = value
+  }
+  async function transport(action, payload, token = '') {
+    checkOpen()
+    let status
+    let body
+    if (native) {
+      const result = await native.call({ method: 'runtime', action, payload, token }, owner, timeout)
+      status = result?.status
+      body = result?.body
+    } else {
+      let base
+      try { base = new URL(apiBase) } catch {
+        throw new GameSDKError('CONFIG', '独立网页必须设置可信后端 apiBase')
+      }
+      if (base.protocol !== 'https:' || base.username || base.password || base.search || base.hash) {
+        throw new GameSDKError('CONFIG', 'apiBase 必须是无凭证、无查询参数的 HTTPS 地址')
+      }
+      const controller = new AbortController()
+      controllers.add(controller)
+      const timer = setTimeout(() => controller.abort(), timeout)
+      try {
+        const response = await fetch(`${base.href.replace(/\/$/, '')}/lunetale/game/runtime/${action}`, {
+          method: action === 'vip' ? 'GET' : 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+          },
+          body: action === 'vip' ? undefined : JSON.stringify(payload),
+          signal: controller.signal,
+          credentials: 'omit',
+          cache: 'no-store',
+          redirect: 'error',
+          referrerPolicy: 'no-referrer',
+        })
+        status = response.status
+        body = await response.json()
+      } catch {
+        throw new GameSDKError('NETWORK', '游戏服务连接失败，请保留 requestId 重试')
+      } finally {
+        clearTimeout(timer)
+        controllers.delete(controller)
+      }
+    }
+    checkOpen()
+    if (status === 401) throw new GameSDKError('AUTH_REQUIRED', '请重新授权游戏')
+    if (status !== 200 || !body || typeof body.code !== 'number') {
+      throw new GameSDKError('PROTOCOL', '游戏服务响应异常')
+    }
+    if (body.code !== 0) throw new GameSDKError(body.code, body.msg || '游戏请求失败')
+    return body.data
+  }
+
+  async function authorize() {
+    checkOpen()
+    if (authorizing) return authorizing
+    const work = (async () => {
+      let grant
+      if (initialCode) {
+        grant = { code: initialCode }
+        initialCode = null
+      } else if (native) {
+        grant = await native.call({ method: 'authorize' }, owner, 30000)
+      } else if (typeof options.authorize === 'function') {
+        // Caller must use a trusted login launcher. Never embed an App JWT in game JS.
+        grant = await options.authorize()
+      } else {
+        throw new GameSDKError('AUTH_REQUIRED', '请从 Lunetale App 打开游戏或重新通过可信入口授权')
+      }
+      checkOpen()
+      if (!grant || !/^[a-f0-9]{64}$/.test(grant.code)) throw new GameSDKError('PROTOCOL', '授权码格式错误')
+      if (grant.origin && grant.origin !== window.location.origin) throw new GameSDKError('ORIGIN', '游戏授权来源不匹配')
+      if (grant.apiBase) apiBase = grant.apiBase
+      acceptCredential(await transport('exchange', { code: grant.code }))
+    })()
+    authorizing = work
+    try { await work } finally { if (authorizing === work) authorizing = null }
+  }
+  async function request(action, payload) {
+    checkOpen()
+    if (!credential || Date.parse(credential.expiresAt) <= Date.now()) await authorize()
+    const used = credential.accessToken
+    let data
+    try {
+      data = await transport(action, payload, used)
+    } catch (error) {
+      if (!(error instanceof GameSDKError) || error.code !== 'AUTH_REQUIRED') throw error
+      // Retry authentication once only. Chat payload/requestId remains identical.
+      if (credential?.accessToken === used) credential = null
+      if (!credential) await authorize()
+      data = await transport(action, payload, credential.accessToken)
+    }
+    if (data?.credential) acceptCredential(data.credential)
+    const { credential: ignored, ...result } = data || {}
+    void ignored
+    return result
+  }
+
+  return Object.freeze({
+    async ready() {
+      checkOpen()
+      if (!credential || Date.parse(credential.expiresAt) <= Date.now()) await authorize()
+    },
+    getVIP() { return request('vip') },
+    async isVIP() { return (await request('vip')).isVip === true },
+    async chat(input) {
+      const requestId = input?.requestId || crypto.randomUUID()
+      try {
+        if (!/^[A-Za-z0-9_-]{16,64}$/.test(requestId) || !Array.isArray(input?.messages) ||
+            input.messages.length < 1 || input.messages.length > 64) {
+          throw new GameSDKError('VALIDATION', '需要1至64条消息和16至64位 requestId')
+        }
+        const messages = input.messages.map(({ role, content }) => {
+          if (!['system', 'user', 'assistant'].includes(role) || typeof content !== 'string' || !content.trim()) {
+            throw new GameSDKError('VALIDATION', '消息角色或内容无效')
+          }
+          return { role, content }
+        })
+        if (messages.at(-1).role !== 'user' ||
+            messages.reduce((size, item) => size + new TextEncoder().encode(item.content).length, 0) > 65536) {
+          throw new GameSDKError('VALIDATION', '最后一条消息必须为user，内容合计不超过64KiB')
+        }
+        return await request('chat', { requestId, messages })
+      } catch (error) {
+        if (error instanceof GameSDKError) { error.requestId = requestId; throw error }
+        throw new GameSDKError('UNKNOWN', '游戏聊天请求失败', { requestId })
+      }
+    },
+    dispose() {
+      disposed = true
+      credential = null
+      initialCode = null
+      native?.dispose(owner)
+      for (const controller of controllers) controller.abort()
+      controllers.clear()
+    },
+  })
+}