@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/types/modules/cloud/index.d.ts

@@ -1,88 +1,334 @@
 import type { MiniProgramRequester } from '../../core/client';
 export { CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, } from '../../protocol/capabilities';
-/** 排行榜排序方向。 */
+/**
+ * 排行榜排序方向。
+ *
+ * `desc` 将较大的 `score` 排在前面，`asc` 将较小的 `score` 排在前面。
+ * 排序方向由榜单创建时决定，SDK 查询不会临时改变它。
+ */
 export type LeaderboardOrder = 'asc' | 'desc';
-/** 排行榜记录。 */
+/**
+ * 平台托管的排行榜记录。
+ *
+ * 一个用户在一个榜单中最多对应一条记录。`rank` 只有在 `ranked` 为 `true`
+ * 时才是可展示的名次；否则必须把记录视为“已保存但当前没有精确名次”。
+ */
 export interface LeaderboardEntry {
-    /** 排名；未进入展示范围或超出当前用户排名计算上限时为 0。 */
+    /** 排名；未进入展示范围或超出当前用户排名计算上限时为 `0`。 */
     rank: number;
-    /** 是否进入展示范围并位于当前用户排名计算上限内。 */
+    /** 是否同时进入榜单展示范围并位于当前用户排名计算上限内。 */
     ranked: boolean;
-    /** 当前小程序内稳定的用户标识，由平台注入，前端不能传入。 */
+    /** 当前小程序内稳定且隔离的用户标识，由平台注入，前端不能传入或推断。 */
     appUserId: string;
-    /** 分数，排行榜唯一排序字段。 */
+    /** 分数；排行榜唯一排序字段，`extra` 不参与排序。 */
     score: number;
-    /** 展示附加信息，不参与排序和查询。 */
+    /** 展示附加信息；会随列表返回给有权读取该榜单的用户，不参与排序和查询。 */
     extra: Record<string, unknown>;
-    /** 记录创建时间，秒级时间戳。 */
+    /** 服务端返回的记录创建时间戳；当前公开合同不承诺单位或时钟来源。 */
     createdAt: number;
-    /** 记录更新时间，秒级时间戳。 */
+    /** 服务端返回的记录更新时间戳；当前公开合同不承诺单位或时钟来源。 */
     updatedAt: number;
 }
-/** 提交当前用户排行榜分数。 */
+/**
+ * `cloud.leaderboard.submit` 的提交参数。
+ *
+ * @remarks
+ * 同一个小程序、榜单和当前用户最多保留一条记录。该对象只接受 `key`、`score`、`extra`；
+ * 额外字段（包括调用方提供的用户 ID、rank 或 order）会以 `INVALID_PARAMS` 拒绝。当前用户
+ * 与小程序 identity 由 Host 和平台注入。
+ */
 export interface SubmitLeaderboardEntryPayload {
-    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    /**
+     * 排行榜 key；省略时使用当前小程序已创建的 `default` 榜单。
+     *
+     * @remarks
+     * 必须匹配 `/^[A-Za-z0-9_-]{1,64}$/`，即 1 至 64 位 ASCII 字母、数字、下划线或
+     * 连字符。空字符串、空格、中文、点号、路径分隔符或超长 key 会在读取 Host 登录态和
+     * 发起网络请求前以 `INVALID_PARAMS` 拒绝。`default` 榜单也必须预先创建。
+     */
     key?: string;
-    /** 本次提交分数，必须是有限安全数字，范围不超过 JavaScript safe number。 */
+    /**
+     * 本次提交分数；没有默认值。
+     *
+     * @remarks
+     * 必须是有限 `number`，且绝对值不超过 `Number.MAX_SAFE_INTEGER`。负数、`0` 和小数均
+     * 可用；数字字符串、`NaN`、正负 `Infinity` 或超出安全精度范围的值会以
+     * `INVALID_PARAMS` 拒绝。分数是唯一排名字段，`extra` 不参与比较。
+     */
     score: number;
-    /** 展示附加信息，不参与排序和查询；已有记录更新为更优分数时不传则保留旧值，序列化后不超过 2048 字节。 */
+    /**
+     * 随被保留分数一起保存的公开展示附加信息。
+     *
+     * @remarks
+     * 必须是非 `null`、非数组且可 JSON 序列化的对象。完整 JSON（含属性名、引号、转义和
+     * 结构字符）按 UTF-8 计算最多 `2048` bytes；超限、循环引用或 `BigInt` 会以
+     * `INVALID_PARAMS` 拒绝。函数、Symbol 等不能通过 iframe structured clone 的成员可能在
+     * 请求到达 Runtime 前触发 `DataCloneError`。应只传普通 JSON 数据。
+     *
+     * 首次提交省略 `extra` 时平台保存并返回 `{}`。已有记录收到更优分数时，省略此字段会
+     * 保留旧 extra，显式传 `{}` 才会清空；分数同分或更差时，即使传入新 extra 也不会更新。
+     * `extra` 会随 `getList()` 返回给其他读取者，不要放入 token、邮箱、外部账号、设备标识
+     * 或其他非必要敏感信息。
+     */
     extra?: Record<string, unknown>;
 }
-/** 提交排行榜分数后返回的当前用户最终记录。 */
+/**
+ * 提交完成后服务端为当前用户保留的最终 {@link LeaderboardEntry}。
+ *
+ * @remarks
+ * 服务端不会另返 `created` 或 `updated` 标记。同分或更差提交成功时，本类型仍返回提交前
+ * 已保存的更优记录，因此 `score`、`extra` 和 `updatedAt` 可能与本次入参不同；调用方应以
+ * 返回值更新 UI，而不是假定入参已经落库。
+ *
+ * 结果固定包含 `rank`、`ranked`、平台注入的 `appUserId`、最终 `score` / `extra`，以及
+ * 服务端时间戳 `createdAt` / `updatedAt`。`ranked: true` 时 `rank` 为正整数；超出榜单
+ * `rankLimit` 或前 5000 名精确排名范围时记录仍存在，但返回 `ranked: false, rank: 0`。
+ */
 export type SubmitLeaderboardEntryResult = LeaderboardEntry;
-/** 读取排行榜列表。 */
+/**
+ * `cloud.leaderboard.getList` 的分页参数。
+ *
+ * @remarks
+ * 只接受 `key`、`limit` 与 `cursor`；额外字段会以 `INVALID_PARAMS` 拒绝。排序方向与列表名次
+ * 范围由榜单创建配置决定，不能通过此对象传入 `order`、`rankLimit` 或用户身份。
+ */
 export interface GetLeaderboardListPayload {
-    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    /**
+     * 排行榜 key；省略 `options` 或此字段时使用当前小程序已创建的 `default` 榜单。
+     *
+     * @remarks
+     * 显式 key 必须匹配 `/^[A-Za-z0-9_-]{1,64}$/`，即 1 至 64 位 ASCII 字母、数字、
+     * 下划线或连字符。空字符串、空格、中文、点号、路径分隔符或超长 key 会在发起 Host
+     * 请求前以 `INVALID_PARAMS` 拒绝。`default` 榜单也必须预先创建。
+     */
     key?: string;
-    /** 每页数量，默认 20，最大 100。 */
+    /**
+     * 本页最多请求的记录数，默认 `20`。
+     *
+     * @remarks
+     * 必须是 `1` 至 `100`（含边界）的有限整数；`0`、负数、小数、`NaN`、`Infinity` 和
+     * 超过 `100` 的值会以 `INVALID_PARAMS` 拒绝。实际 `entries.length` 可能因到达末页或
+     * 榜单 `rankLimit` 展示边界而小于 limit，不能据此推断是否还有下一页。
+     */
     limit?: number;
-    /** 服务端返回的不透明分页游标；只能原样传回下一页，不能自行构造或解析。 */
+    /**
+     * 上一页返回的不透明分页游标；首屏省略。
+     *
+     * @remarks
+     * 传入时必须是字符串。只能把同一榜单上一页返回的值原样传回，不能解析、修改、构造、
+     * 持久化为页码或跨榜单复用；续页时应保持相同的 key 和 limit。
+     */
     cursor?: string;
 }
-/** 读取排行榜列表的分页结果。 */
+/**
+ * 排行榜列表的一页规范化结果。
+ *
+ * @remarks
+ * 记录顺序由榜单 `order` 决定，并受 `rankLimit` 展示范围限制。空 `entries` 是合法页面；
+ * 是否继续只能看 `hasMore`，不能用数组长度或是否有 cursor 单独推断。
+ */
 export interface GetLeaderboardListResult {
-    /** 当前页排行榜记录。 */
+    /**
+     * 当前页排行榜记录，按服务端名次顺序返回。
+     *
+     * 每条 {@link LeaderboardEntry} 包含 `rank`、`ranked`、小程序隔离的 `appUserId`、排序字段
+     * `score`、公开展示 `extra`，以及服务端时间戳 `createdAt` / `updatedAt`。`extra` 不参与
+     * 排序，`appUserId` 不是黑盒用户 ID，也不能用于跨小程序关联用户。
+     */
     entries: LeaderboardEntry[];
-    /** 下一页不透明分页游标；仅当 hasMore 为 true 时可能返回。 */
+    /**
+     * 下一页不透明分页游标；仅当服务端返回非空 cursor 时存在。应在 `hasMore: true` 时原样
+     * 传给同一 key 和 limit 的下一次 `getList()`，不要解析或自行递增。
+     */
     cursor?: string;
-    /** 是否还有下一页。 */
+    /**
+     * 服务端对“是否还有下一页”的权威判断。`false` 表示遍历结束；不要用
+     * `entries.length === limit` 或 cursor 是否存在替代该字段。
+     */
     hasMore: boolean;
 }
-/** 读取当前用户在排行榜中的记录。 */
+/**
+ * `cloud.leaderboard.getCurrentUserEntry` 的可选参数。
+ *
+ * @remarks
+ * 该对象只能选择榜单，不能携带 `appUserId`、黑盒用户 ID 或其他目标用户字段；额外字段会
+ * 以 `INVALID_PARAMS` 拒绝。被读取的用户始终由 Host 当前登录态和受信服务端会话确定。
+ */
 export interface GetCurrentUserLeaderboardEntryPayload {
-    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    /**
+     * 排行榜 key；省略 `options` 或此字段时使用当前小程序已创建的 `default` 榜单。
+     *
+     * @remarks
+     * 显式 key 必须匹配 `/^[A-Za-z0-9_-]{1,64}$/`，即 1 至 64 位 ASCII 字母、数字、
+     * 下划线或连字符。空字符串、空格、中文、点号、路径分隔符或超长 key 会在读取 Host
+     * 登录态和发起网络请求前以 `INVALID_PARAMS` 拒绝。`default` 榜单也必须预先创建。
+     */
     key?: string;
 }
-/** 当前用户排行榜记录；不存在时返回 undefined。 */
+/**
+ * 当前用户排行榜记录，或表示“没有记录”的 `undefined`。
+ *
+ * @remarks
+ * `undefined` 是成功的正常空结果，不会抛出“记录不存在”错误。它与返回一条
+ * `{ ranked: false, rank: 0, ... }` 的记录不同：后者表示分数仍已保存，只是超出榜单展示
+ * 范围或当前前 5000 名精确排名范围。
+ *
+ * 非空 {@link LeaderboardEntry} 固定包含：平台注入且仅在当前小程序内有意义的
+ * `appUserId`；用于排序的 `score`；不参与排序的公开展示 `extra`；服务端
+ * `createdAt` / `updatedAt`；以及必须成对解释的 `ranked` / `rank`。`ranked: true` 时
+ * `rank` 是正整数名次；`ranked: false` 时 `rank` 固定为 `0`，不能展示为“第 0 名”。
+ */
 export type GetCurrentUserLeaderboardEntryResult = LeaderboardEntry | undefined;
-/** 删除当前用户在排行榜中的记录。 */
+/**
+ * `cloud.leaderboard.deleteCurrentUserEntry` 的可选参数。
+ *
+ * @remarks
+ * 该对象只能选择榜单，不能携带 `appUserId`、黑盒用户 ID 或其他目标用户字段；额外字段会
+ * 以 `INVALID_PARAMS` 拒绝。被删除的用户始终由 Host 登录态和受信服务端会话确定。
+ */
 export interface DeleteCurrentUserLeaderboardEntryPayload {
-    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    /**
+     * 排行榜 key；省略 `options` 或此字段时使用当前小程序已创建的 `default` 榜单。
+     *
+     * @remarks
+     * 显式 key 必须匹配 `/^[A-Za-z0-9_-]{1,64}$/`，即 1 至 64 位 ASCII 字母、数字、
+     * 下划线或连字符。空字符串、空格、中文、点号、路径分隔符或超长 key 会在发起 Host
+     * 请求前以 `INVALID_PARAMS` 拒绝。`default` 也必须预先创建，不是临时生成的本地榜单。
+     */
     key?: string;
 }
-/** 删除当前用户排行榜记录的结果。 */
+/**
+ * 删除当前用户排行榜记录的结果。
+ *
+ * @remarks
+ * 结果只包含是否实际删除记录，不返回被删除的分数、名次、`extra` 或用户身份。删除不存在
+ * 的记录以及对同一记录重复删除都会成功返回 `{ deleted: false }`，适合按幂等操作处理。
+ */
 export interface DeleteCurrentUserLeaderboardEntryResult {
-    /** 是否实际删除了已有记录。 */
+    /**
+     * `true` 表示本次请求实际删除了一条已有记录；`false` 表示请求成功，但调用时已无记录。
+     * `false` 是正常空结果，不应作为异常、权限失败或需要重试的信号。
+     */
     deleted: boolean;
 }
-/** 读取排行榜基础信息。 */
+/**
+ * `cloud.leaderboard.getInfo` 的可选参数。
+ *
+ * @remarks
+ * 该对象只用于选择当前小程序所属的榜单；额外字段会以 `INVALID_PARAMS` 拒绝。查询不会
+ * 接受用户身份、排序方向、名次上限或分页参数，也不会临时覆盖榜单创建时的配置。
+ */
 export interface GetLeaderboardInfoPayload {
-    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    /**
+     * 排行榜 key；省略 `options` 或此字段时使用当前小程序已创建的 `default` 榜单。
+     *
+     * @remarks
+     * 显式 key 必须匹配 `/^[A-Za-z0-9_-]{1,64}$/`，即 1 至 64 位 ASCII 字母、数字、
+     * 下划线或连字符。空字符串、空格、中文、点号、路径分隔符或超长 key 会在发起 Host
+     * 请求前以 `INVALID_PARAMS` 拒绝。`default` 榜单也必须预先创建。
+     */
     key?: string;
 }
-/** 排行榜基础配置。 */
+/**
+ * 排行榜创建时确定的基础配置。
+ *
+ * @remarks
+ * 该结果不包含记录、当前用户、记录总数、分页游标或可修改配置。`order` 与 `rankLimit`
+ * 只能通过平台管理流程配置，不能在运行时查询参数中覆盖。
+ */
 export interface GetLeaderboardInfoResult {
-    /** 排行榜 key。 */
+    /**
+     * 服务端实际解析的榜单 key。省略请求 key 时通常为 `default`；显式请求时必须与请求值
+     * 一致，否则 Runtime 以 `INVALID_RESPONSE` 拒绝响应。
+     */
     key: string;
-    /** 排行榜排序方向。 */
+    /**
+     * 排行榜排序与“更优分数”的方向：`desc` 表示分数越大名次越靠前，`submit()` 只用更高
+     * 分更新记录；`asc` 表示分数越小越靠前，`submit()` 只用更低分更新记录。
+     */
     order: LeaderboardOrder;
-    /** 列表展示名次上限；0 表示不限制。当前用户记录仍最多精确计算前 5000 名。 */
+    /**
+     * `getList()` 可展示的名次上限，必须是非负整数；`0` 表示列表不设置名次上限。
+     *
+     * @remarks
+     * 它不是记录数量上限、分页大小或清理策略：超出范围的记录仍保存，`getList({ limit })`
+     * 的 `limit` 只控制单页数量，不能突破非零 `rankLimit`。当前用户记录的 `ranked` 还同时
+     * 受前 5000 名精确排名上限约束；因此 `rankLimit: 0` 时仍可能得到
+     * `ranked: false, rank: 0`。
+     */
     rankLimit: number;
 }
 /** 外部小程序可调用的云端排行榜模块。 */
 export interface MiniProgramCloudLeaderboardModule {
     /**
-     * 提交当前用户分数。
+     * 为当前登录用户创建记录，或仅在分数更优时更新已有记录。
+     *
+     * @param options - 必填分数、可选榜单 key 和公开展示 extra；必须符合
+     * {@link SubmitLeaderboardEntryPayload} 的字段、数值与序列化约束。
+     * @returns 服务端保存的当前用户最终 {@link LeaderboardEntry}。首次提交返回新记录；同分
+     * 或更差时调用仍成功，但返回原有记录，不代表本次 score / extra 已更新。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含未知字段，
+     * key 不合法，score 缺失/非有限数字/超出安全范围，或 extra 不是对象、不可 JSON 序列化、
+     * 超过 2048 UTF-8 bytes。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
+     * 版本未声明或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
+     * 请求期间登录账号发生变化。
+     * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
+     * 小程序未创建 `default` 榜单；`LEADERBOARD_SUBMIT_LOCKED`：同一用户记录正在被另一提交
+     * 更新，可在稍后重新提交。命名榜单不存在或后端拒绝时保留服务端错误码。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_STATE`：canonical 小程序身份未就绪；
+     * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需账号或受信网络能力；
+     * `REQUEST_FAILED`：平台请求失败；`INVALID_RESPONSE`：返回记录字段不符合公开合同。
+     * 其他 bridge 超时与 SDK 状态错误会保留对应错误码。
+     * @throws `DOMException` extra 含函数、Symbol 等不可 structured-clone 的内容时，浏览器可能
+     * 在请求发送前抛出 `DataCloneError`。
+     *
+     * @remarks
+     * 当前用户不来自参数。Runtime 先向 Host 读取当前登录状态，再用 Host 持有的受信会话和
+     * canonical 小程序 identity 调用平台；页面不能指定 `appUserId` 或提交其他用户的成绩。
+     * 不要先调用用户资料 API 探测登录，直接处理 `UNAUTHORIZED`。该 API 需要声明
+     * `leaderboard`，但不需要公开 `network` 权限或可信用户手势。
+     *
+     * “更优”由榜单创建时的 `order` 决定，可通过
+     * {@link MiniProgramCloudLeaderboardModule.getInfo | getInfo} 查询：`desc` 只用更高分更新，
+     * `asc` 只用更低分更新。首次合法分数创建记录；同分和更差分数不更新 score、extra 或
+     * updatedAt。同分记录按更早达到当前分数的 updatedAt 优先，再以 appUserId 稳定排序。
+     *
+     * extra 跟随最终保留的分数记录：首次省略时为 `{}`；更优更新省略时保留旧值，传 `{}`
+     * 才清空；同分或更差时传入的新值被忽略。由于 extra 会出现在
+     * {@link MiniProgramCloudLeaderboardModule.getList | getList} 中，只能保存公开展示数据。
+     *
+     * 每次成功响应（包括同分/更差而未更新）都会失效同一小程序、同一榜单的全部列表页和
+     * {@link MiniProgramCloudLeaderboardModule.getCurrentUserEntry | getCurrentUserEntry} 五分钟
+     * 读缓存；下一次读取重新请求远端。`getInfo` 配置缓存和其他榜单缓存不受影响；提交前已
+     * 在途的旧读取可能仍返回给原调用方，但不会回填已失效的缓存。需要移除记录时使用
+     * {@link MiniProgramCloudLeaderboardModule.deleteCurrentUserEntry | deleteCurrentUserEntry}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const submittedScore = 1200
+     * const entry = await hbSDK.cloud.leaderboard.submit({
+     *   key: 'weekly',
+     *   score: submittedScore,
+     *   extra: { level: 8 },
+     * })
+     *
+     * if (entry.score !== submittedScore) {
+     *   console.log('已有成绩更优，本次未覆盖', entry.score)
+     * } else if (entry.ranked) {
+     *   console.log(`成绩已保存，当前排名 ${entry.rank}`)
+     * } else {
+     *   console.log('成绩已保存，暂未获得精确名次')
+     * }
+     * ```
+     *
+     * @see {@link MiniProgramCloudLeaderboardModule.getInfo | cloud.leaderboard.getInfo}
+     * @see {@link MiniProgramCloudLeaderboardModule.getList | cloud.leaderboard.getList}
+     * @see {@link MiniProgramCloudLeaderboardModule.getCurrentUserEntry | cloud.leaderboard.getCurrentUserEntry}
+     * @see {@link MiniProgramCloudLeaderboardModule.deleteCurrentUserEntry | cloud.leaderboard.deleteCurrentUserEntry}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/cloud-leaderboard | 云端排行榜指南}
      *
      * @since 0.5.11
      * @hbPlatform android
@@ -98,7 +344,69 @@ export interface MiniProgramCloudLeaderboardModule {
      */
     submit(options: SubmitLeaderboardEntryPayload): Promise<SubmitLeaderboardEntryResult>;
     /**
-     * 读取排行榜列表。
+     * 按服务端排名顺序读取排行榜的一页记录。
+     *
+     * @param options - 可选榜单 key、页大小和上一页 cursor；全部省略时读取 `default` 榜单
+     * 首屏并使用 `limit: 20`。各字段必须符合 {@link GetLeaderboardListPayload} 的约束。
+     * @returns 当前页 {@link LeaderboardEntry} 数组、可选下一页 cursor 和权威 `hasMore` 标记。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含未知字段，
+     * key 不符合 1 至 64 位 `[A-Za-z0-9_-]`，limit 不是 1 至 100 的整数，或 cursor 不是字符串。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
+     * 版本未声明或未启用 `leaderboard` 权限。
+     * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
+     * 小程序未创建 `default` 榜单。命名榜单不存在、cursor 失效或后端拒绝时保留服务端错误码。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_STATE`：canonical 小程序身份未就绪；
+     * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需受信网络能力；
+     * `REQUEST_FAILED`：平台请求失败；`INVALID_RESPONSE`：entries、cursor、hasMore 或任一记录
+     * 字段不符合公开合同。其他 bridge 超时与 SDK 状态错误会保留对应错误码。
+     *
+     * @remarks
+     * 该查询不要求 Host 登录、用户授权或可信用户手势。它需要声明 `leaderboard`，但不需要
+     * 公开 `network` 权限；Runtime 使用 Host 的受信网络端口读取 canonical 小程序所属榜单。
+     * 页面不能通过参数查询其他小程序，也不能指定用户过滤列表。
+     *
+     * 榜单创建时的 `order` 决定返回顺序：`desc` 高分优先，`asc` 低分优先。非零
+     * `rankLimit` 限制可展示到的最大名次，`0` 表示不设置列表名次上限；本方法的 `limit`
+     * 只控制单页最多返回数量，不能修改 order 或突破 rankLimit。可通过
+     * {@link MiniProgramCloudLeaderboardModule.getInfo | getInfo} 读取这两项配置。
+     *
+     * cursor 是服务端分页状态，不是 offset 或页码。首次请求省略 cursor；当 `hasMore` 为
+     * `true` 且返回 cursor 时，下一页必须把它原样传回同一 key，并保持相同 limit。
+     * `hasMore: false` 才表示本次遍历结束，不能仅凭页面不足 limit 条记录提前停止。
+     *
+     * 当前 Runtime 最多为 3 个活跃“小程序 + 榜单 key” bucket 缓存每一页五分钟；超过该上限的
+     * 榜单读取不进入缓存。无论是否缓存，同参数的并发读取都会合并为一个远端请求；不同页、
+     * 不同 limit 或不同榜单互不命中。其他用户成绩变化在缓存期内可能暂时不可见。成功的
+     * {@link MiniProgramCloudLeaderboardModule.submit | submit}
+     * 或 {@link MiniProgramCloudLeaderboardModule.deleteCurrentUserEntry | deleteCurrentUserEntry}
+     * 会失效同榜单的全部列表页与当前用户缓存，下一次读取重新请求；`getInfo` 配置缓存和其他
+     * 榜单缓存不受影响。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * let cursor: string | undefined
+     * do {
+     *   const page = await hbSDK.cloud.leaderboard.getList({
+     *     key: 'weekly',
+     *     limit: 20,
+     *     ...(cursor ? { cursor } : {}),
+     *   })
+     *
+     *   for (const entry of page.entries) {
+     *     console.log(entry.rank, entry.score, entry.extra)
+     *   }
+     *
+     *   if (!page.hasMore || !page.cursor) break
+     *   cursor = page.cursor
+     * } while (true)
+     * ```
+     *
+     * @see {@link MiniProgramCloudLeaderboardModule.getInfo | cloud.leaderboard.getInfo}
+     * @see {@link MiniProgramCloudLeaderboardModule.submit | cloud.leaderboard.submit}
+     * @see {@link MiniProgramCloudLeaderboardModule.deleteCurrentUserEntry | cloud.leaderboard.deleteCurrentUserEntry}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/cloud-leaderboard | 云端排行榜指南}
      *
      * @since 0.5.11
      * @hbPlatform android
@@ -114,7 +422,72 @@ export interface MiniProgramCloudLeaderboardModule {
      */
     getList(options?: GetLeaderboardListPayload): Promise<GetLeaderboardListResult>;
     /**
-     * 读取当前用户记录。
+     * 读取当前登录用户在指定排行榜中的记录。
+     *
+     * @param options - 可选榜单选择参数；省略时读取 `default` 榜单。显式 `options.key` 必须
+     * 符合 {@link GetCurrentUserLeaderboardEntryPayload.key} 的格式约束。
+     * @returns 当前用户的完整 {@link LeaderboardEntry}；没有记录时 resolve `undefined`，这是
+     * 正常空结果。返回记录但 `ranked: false` 时记录仍存在，`rank` 固定为 `0`。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含 `key` 以外
+     * 的字段，或 key 不符合 1 至 64 位 `[A-Za-z0-9_-]` 规则。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
+     * 版本未声明或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
+     * 请求期间登录账号发生变化。
+     * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
+     * 小程序未创建 `default` 榜单。命名榜单不存在或后端拒绝时保留服务端错误码。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_STATE`：canonical 小程序身份未就绪；
+     * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需账号或受信网络能力；
+     * 其他网络失败、响应字段不合法和 bridge 超时分别保留对应 `REQUEST_FAILED`、
+     * `INVALID_RESPONSE` 或 SDK 错误码。
+     *
+     * @remarks
+     * 当前用户不来自参数。Runtime 每次调用都会先向 Host 校验当前登录账号，再用 Host 持有的
+     * 受信会话读取平台为该账号和 canonical 小程序身份关联的记录。页面不能指定或猜测其他
+     * 用户，也不应先调用用户资料 API 探测登录；直接处理本方法的 `UNAUTHORIZED` 即可。
+     * 该 API 需要声明 `leaderboard`，但不需要公开 `network` 权限或可信用户手势。
+     *
+     * 返回的 `appUserId` 是当前用户在当前小程序内的隔离标识，不是黑盒用户 ID、登录凭据或
+     * 可跨小程序关联的账号字段。`extra` 会随
+     * {@link MiniProgramCloudLeaderboardModule.getList | getList} 返回给该榜单的其他读取者，
+     * 调用方应把它当作公开展示数据。
+     *
+     * `ranked` 同时受榜单 `rankLimit` 和当前用户前 5000 名精确排名上限约束：两项均满足时
+     * `ranked: true` 且 `rank` 为正整数；任一不满足时记录仍返回，但固定为
+     * `ranked: false, rank: 0`。即使 `rankLimit` 为 `0`（列表不限制），前 5000 名计算上限
+     * 仍然存在。不要用 `rank === 0` 判断“没有记录”，应先判断整个返回值是否为 `undefined`。
+     *
+     * 当前 Runtime 最多为 3 个活跃榜单 bucket 缓存结果（包括 `undefined`）五分钟；超过上限的
+     * 榜单读取不进入缓存。同一时刻的重复读取仍会合并为一个远端请求。账号变化会清空全部榜单缓存，并使旧账号的
+     * 在途响应以 `UNAUTHORIZED` 结束；成功的
+     * {@link MiniProgramCloudLeaderboardModule.submit | submit} 或
+     * {@link MiniProgramCloudLeaderboardModule.deleteCurrentUserEntry | deleteCurrentUserEntry}
+     * 会使同榜单的当前用户与列表缓存立即失效，下一次读取重新请求远端。
+     *
+     * `getCurrentUserEntry()` 可以返回仍存在但未进入列表展示范围的记录；分页
+     * `getList()` 中没有当前用户，不等于当前用户没有记录。需要创建或更新记录时调用
+     * `submit()`，需要删除时调用 `deleteCurrentUserEntry()`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const entry = await hbSDK.cloud.leaderboard.getCurrentUserEntry({
+     *   key: 'weekly',
+     * })
+     *
+     * if (!entry) {
+     *   console.log('还没有成绩')
+     * } else if (entry.ranked) {
+     *   console.log(`当前成绩 ${entry.score}，排名 ${entry.rank}`)
+     * } else {
+     *   console.log(`成绩 ${entry.score} 已保存，暂未获得精确名次`)
+     * }
+     * ```
+     *
+     * @see {@link MiniProgramCloudLeaderboardModule.submit | cloud.leaderboard.submit}
+     * @see {@link MiniProgramCloudLeaderboardModule.deleteCurrentUserEntry | cloud.leaderboard.deleteCurrentUserEntry}
+     * @see {@link MiniProgramCloudLeaderboardModule.getList | cloud.leaderboard.getList}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/cloud-leaderboard | 云端排行榜指南}
      *
      * @since 0.5.11
      * @hbPlatform android
@@ -130,7 +503,59 @@ export interface MiniProgramCloudLeaderboardModule {
      */
     getCurrentUserEntry(options?: GetCurrentUserLeaderboardEntryPayload): Promise<GetCurrentUserLeaderboardEntryResult>;
     /**
-     * 删除当前用户记录。
+     * 删除当前登录用户在指定排行榜中的记录。
+     *
+     * @param options - 可选榜单选择参数；省略时删除 `default` 榜单中的当前用户记录。显式
+     * `options.key` 必须符合 {@link DeleteCurrentUserLeaderboardEntryPayload.key} 的格式约束。
+     * @returns 远端删除完成且同榜单可变读缓存失效后的结果。`deleted: true` 表示实际删除；
+     * `deleted: false` 表示调用成功但已无记录，是幂等空结果。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含 `key` 以外
+     * 的字段，或 key 不符合 1 至 64 位 `[A-Za-z0-9_-]` 规则。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
+     * 版本未声明或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
+     * 请求期间登录账号发生变化。
+     * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
+     * 小程序未创建 `default` 榜单。命名榜单不存在或后端拒绝时保留服务端错误码。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_STATE`：canonical 小程序身份未就绪；
+     * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需账号或受信网络能力；
+     * 其他网络失败、响应不合法和 bridge 超时分别保留对应 `REQUEST_FAILED`、
+     * `INVALID_RESPONSE` 或 SDK 错误码。
+     *
+     * @remarks
+     * 当前用户不来自参数。Runtime 先向 Host 读取当前登录状态，再用 Host 持有的受信会话调用
+     * 平台接口；页面不能指定、猜测或删除其他用户的记录。不要先调用用户资料 API 探测登录，
+     * 直接处理本方法的 `UNAUTHORIZED` 即可。该 API 需要声明 `leaderboard`，但不需要公开
+     * `network` 权限或可信用户手势；产品仍应只在明确的用户操作和二次确认后执行删除。
+     *
+     * 成功响应（包括 `deleted: false`）会使当前 Runtime 中同一小程序、同一榜单的
+     * {@link MiniProgramCloudLeaderboardModule.getList | getList} 与
+     * {@link MiniProgramCloudLeaderboardModule.getCurrentUserEntry | getCurrentUserEntry} 五分钟读
+     * 缓存失效；下一次读取会重新请求远端，不会由删除调用主动预取。该榜单的 `getInfo`
+     * 配置缓存和其他榜单缓存不受影响；删除前已在途的旧读取可能仍向原调用方返回，但不会
+     * 回填已失效的缓存。
+     *
+     * 删除后，`getCurrentUserEntry()` 应返回 `undefined`，`getList()` 不再包含该条记录；之后
+     * 调用 {@link MiniProgramCloudLeaderboardModule.submit | submit} 可以重新建立当前用户记录，
+     * 并重新参与服务端排序。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * async function deleteMyScore() {
+     *   if (!window.confirm('确定删除自己的榜单成绩吗？')) return
+     *
+     *   const { deleted } = await hbSDK.cloud.leaderboard.deleteCurrentUserEntry({
+     *     key: 'weekly',
+     *   })
+     *   console.log(deleted ? '已删除成绩' : '当前没有成绩')
+     * }
+     * ```
+     *
+     * @see {@link MiniProgramCloudLeaderboardModule.getCurrentUserEntry | cloud.leaderboard.getCurrentUserEntry}
+     * @see {@link MiniProgramCloudLeaderboardModule.submit | cloud.leaderboard.submit}
+     * @see {@link MiniProgramCloudLeaderboardModule.getList | cloud.leaderboard.getList}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/cloud-leaderboard | 云端排行榜指南}
      *
      * @since 0.5.11
      * @hbPlatform android
@@ -146,7 +571,56 @@ export interface MiniProgramCloudLeaderboardModule {
      */
     deleteCurrentUserEntry(options?: DeleteCurrentUserLeaderboardEntryPayload): Promise<DeleteCurrentUserLeaderboardEntryResult>;
     /**
-     * 读取排行榜基础信息。
+     * 读取指定排行榜创建时确定的排序与展示配置。
+     *
+     * @param options - 可选榜单选择参数；省略时读取 `default` 榜单。显式 `options.key` 必须
+     * 符合 {@link GetLeaderboardInfoPayload.key} 的格式约束。
+     * @returns 规范化的 {@link GetLeaderboardInfoResult}：实际榜单 `key`、排序方向 `order`
+     * 和列表展示上限 `rankLimit`。不返回榜单记录或当前用户数据。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含 `key` 以外
+     * 的字段，或 key 不符合 1 至 64 位 `[A-Za-z0-9_-]` 规则。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
+     * 版本未声明或未启用 `leaderboard` 权限。
+     * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
+     * 小程序未创建 `default` 榜单。命名榜单不存在或后端拒绝时保留服务端错误码。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_STATE`：canonical 小程序身份未就绪；
+     * `METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需受信网络能力；
+     * `REQUEST_FAILED`：平台请求失败；`INVALID_RESPONSE`：返回 key、order 或 rankLimit
+     * 不符合公开合同。其他 bridge 超时与 SDK 状态错误会保留对应错误码。
+     *
+     * @remarks
+     * 该查询不读取当前用户，也不要求 Host 登录、用户授权或可信用户手势。它需要声明
+     * `leaderboard`，但不需要公开 `network` 权限；Runtime 使用 Host 的受信网络端口读取当前
+     * canonical 小程序所属榜单的配置。页面不能通过参数查询其他小程序的榜单。
+     *
+     * `order` 是创建榜单时固定的服务端规则：`desc` 让高分优先，`asc` 让低分优先。调用
+     * {@link MiniProgramCloudLeaderboardModule.submit | submit} 时无需也不能再次传入 order；
+     * 服务端按这里返回的方向决定新分数是否优于已有记录。
+     *
+     * `rankLimit` 控制 {@link MiniProgramCloudLeaderboardModule.getList | getList} 的列表展示
+     * 名次范围，`0` 表示不设该范围上限。它与 `getList` 的每页 `limit` 相互独立，也不会删除
+     * 范围外记录；当前用户的 `ranked` 还受前 5000 名精确排名上限限制。
+     *
+     * 当前 Runtime 最多为 3 个活跃榜单 bucket 缓存结果五分钟；超过上限的榜单读取不进入缓存。
+     * 同时发起的相同查询仍会合并为一个远端请求。`submit()` 和 `deleteCurrentUserEntry()` 只失效同榜单的列表/当前用户缓存，
+     * 不会失效 `getInfo` 配置缓存；其他榜单也使用独立缓存。Host 账号变化或 Runtime 销毁会
+     * 清空缓存与在途合并状态。SDK 没有强制刷新参数，缓存过期或新 Runtime 才会重新读取。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const info = await hbSDK.cloud.leaderboard.getInfo({ key: 'weekly' })
+     * const page = await hbSDK.cloud.leaderboard.getList({ key: info.key, limit: 20 })
+     *
+     * const direction = info.order === 'desc' ? '高分优先' : '低分优先'
+     * const range = info.rankLimit === 0 ? '不限制展示名次' : `仅展示前 ${info.rankLimit} 名`
+     * console.log(direction, range, page.entries)
+     * ```
+     *
+     * @see {@link MiniProgramCloudLeaderboardModule.getList | cloud.leaderboard.getList}
+     * @see {@link MiniProgramCloudLeaderboardModule.submit | cloud.leaderboard.submit}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/cloud-leaderboard | 云端排行榜指南}
      *
      * @since 0.5.11
      * @hbPlatform android