阅读主题
H5 API 参考
适用版本：v0.2.1。以下方法对应 StarlightSDK 当前公开源码；先完成 快速接入。运行时导出 StarlightSDK、ApiError、createPkce。发布包的自包含声明同时导出 LoginInput、SessionStorageAdapter、SessionResponse、Order 等类型，可使用 import type 引入，无需额外安装 contracts 包。
构造与基础方法
ts
new StarlightSDK({
appId: string,
baseUrl?: string,
timeoutMs?: number,
storage?: SessionStorageAdapter,
exchange: (input: { appId: string; code: string; codeVerifier: string })
=> Promise<SessionResponse>
})以上是签名示意，不是直接执行的对象字面量。SessionResponse 包含 token、expiresAt、user、role，可用 import type { SessionResponse } from '@starlight/sdk'，或从 NonNullable<ReturnType<StarlightSDK['getSession']>> 推导。默认 API 请求超时 15 秒；baseUrl 省略时请求当前 origin。
| 方法 | 返回与行为 |
|---|---|
init() | Promise<PlatformConfig>，公开配置请求，不恢复会话 |
getSession() | 会话深拷贝或 null |
restoreSession() | Promise<SessionResponse | null>，显式验证存储候选；网络失败抛错并保留候选 |
login(input: LoginInput) | Promise 会话；执行 PKCE/state/服务端交换，取消后的结果被拒绝 |
cancelLogin() | 使当前登录事务失效，不清现有已登录身份 |
clearSession() | 本地清会话/存储并发事件，不撤销服务端 |
logout() / switchAccount() | Promise；立即本地退出并尝试服务端撤销；切号额外通知宿主打开登录中心 |
LoginInput：{ method:'password'|'sms', account:string, password?:string, challengeId?:string, code?:string, consentVersion:string }。当前服务接受协议版本 2026-09；宿主在玩家同意后提交。
短信、密码和设备
| 方法 | 参数/结果 |
|---|---|
sendSms(phone, purpose = 'login') | purpose 为 login 或 password_reset；返回 challengeId、retryAfterSeconds、本地演示可能有 demoCode |
resetPassword({phone,challengeId,code,newPassword}) | Promise {ok:true}；当前事务成功后清本地会话 |
changePassword(currentPassword, newPassword) | 调用改密接口；错误旧密码不触发退出 |
sessions() | Promise {items: AccountSession[]}；本人跨游戏有效会话 |
revokeSession(id) | Promise {ok:true,current:boolean}；若撤销本设备则清会话 |
revokeOtherSessions() | Promise {ok:true,revoked:number} |
验证码用途不可互换。demoCode 只表明本地模拟发码，当前未接通真实短信供应商。设备 id 不是认证令牌。
中心、权益与消息
| 方法 | 说明 |
|---|---|
center() | Promise 中心数据，含账号/角色/配置/钱包/会员/商品/订单/账本/消息 |
claimGift(id, roleId, requestId?) | 领取礼包，未传入时生成 requestId；角色必须属于当前账号/游戏 |
claimCoupon(id, requestId?) | 领取优惠券，未传入时生成 requestId |
claimDaily(requestId?) | 领取有效月卡每日福利，未传入时生成 requestId |
readMessage(id) | 标记消息已读 |
当前中心、玩家订单及历史响应没有完整数据库级分页接口；不要假造 page/cursor 参数。账号与游戏的单内置角色模型不接受任意外部角色 ID。
订单与重试
| 方法 | 返回/约束 |
|---|---|
orders() / order(id) | Promise {items:Order[]} / Promise Order |
createOrder({productId,roleId,couponId?,paymentMethod,requestId?}) | Promise Order；paymentMethod 仅 demo 或 wallet |
payOrder(id, requestId?) | Promise Order；省略时生成新 requestId；同一动作重试可显式复用原 ID |
closeOrder(id) | Promise Order；只关闭未支付订单并释放占券 |
refundOrder(id, requestId?) | Promise Order；本地资产回收与钱包原桶退款，未传入时生成 requestId |
ts
import { sdk } from './sdk';
export function preparePurchase(productId: string, roleId: string) {
const input = { productId, roleId, paymentMethod: 'wallet' as const,
requestId: crypto.randomUUID() };
// 将返回函数用于同一次创建的重试；不要每次重建 input/requestId。
return () => sdk.createOrder(input);
}
export async function continuePayment(orderId: string) {
const latest = await sdk.order(orderId);
return latest.status === 'pending' ? sdk.payOrder(orderId) : latest;
}订单状态为 pending、paid、fulfilled、refunded、closed。超时不能推断未付款，先查原单。商品价格和角色归属由服务器决定；本地成功只代表演示资产/内部钱包闭环，没有真实微信、支付宝或远程游戏发货。
玩家客服
ts
sdk.tickets({ limit: 50 }); // 返回 items / nextCursor；下一页传 before: nextCursor
sdk.ticket('实际工单ID');
sdk.createTicket({ subject: '订单问题', category: 'payment', content: '请协助核查',
orderId: '实际本人同游戏订单ID', requestId: crypto.randomUUID() });
sdk.replyTicket('实际工单ID', '补充说明', crypto.randomUUID());
sdk.closeTicket('实际工单ID', crypto.randomUUID());这些调用返回工单或工单列表的 Promise。category 为 account | payment | game | other；orderId 可省略。显式传入 requestId 后，同一动作重试复用它。这里是玩家客服，不是开发者技术支持工单。
UI 事件与底层请求
on(event, listener) 返回取消监听函数：session 载荷为会话/null，center 为 {view:string}，floating 为 boolean，error 为 ApiError。openCenter(view='home')、showFloating()、hideFloating() 仅发事件，见 宿主 UI。
request<T>(path, body?, method?, {authenticated?}?) 仅允许当前平台的 /api/ 路径；默认无 body 用 GET、有 body 用 POST，默认携带当前 token，可用 authenticated:false 关闭。不能用它向游戏后端/第三方 URL 转发平台令牌。createPkce() 返回 {verifier,challenge,state}，普通登录已经内部调用，无需手工重复生成。
ApiError 含 code、message、status，网络/超时通常 status 为 0。NETWORK_ERROR、TIMEOUT、INVALID_RESPONSE 应提示重试；SESSION_CHANGED 代表旧结果被丢弃；INVALID_ENDPOINT 是路径错误。自定义 exchange 抛出的错误未必是 ApiError，也不保证触发 SDK error 事件，应始终捕获 login() 的拒绝。会话清理规则见 会话管理。
v0.2.1 新增公共能力
| 方法 | 行为 |
|---|---|
capabilities() | 当前 App ID 实际可用的身份、支付、短信与履约能力 |
realms() / roles() | 当前游戏区服及本人可信角色绑定 |
deletionPreview() | 注销前余额、会员、未结订单检查 |
exportAccount() | 导出本人账号与交易资料 |
deleteAccount(input) | 重新验证本人后注销，成功且会话代际一致才清理本地身份 |
sendSms 新增 account_deletion 用途。deleteAccount 输入见账号生命周期。外部游戏礼包返回持久化赠礼发货状态，不能将创建记录等同于游戏到账。