@heybox/hb-sdk 0.5.10 → 0.5.11

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

@@ -0,0 +1,100 @@
+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';
+/** 排行榜排序方向。 */
+export type LeaderboardOrder = 'asc' | 'desc';
+/** 排行榜记录。 */
+export interface LeaderboardEntry {
+    /** 排名；未进入展示范围或超出当前用户排名计算上限时为 0。 */
+    rank: number;
+    /** 是否进入展示范围并位于当前用户排名计算上限内。 */
+    ranked: boolean;
+    /** 当前记录所属用户 ID，由平台注入，前端不能传入。 */
+    userId: string;
+    /** 分数，排行榜唯一排序字段。 */
+    score: number;
+    /** 展示附加信息，不参与排序和查询。 */
+    extra: Record<string, unknown>;
+    /** 记录创建时间，秒级时间戳。 */
+    createdAt: number;
+    /** 记录更新时间，秒级时间戳。 */
+    updatedAt: number;
+}
+/** 提交当前用户排行榜分数。 */
+export interface SubmitLeaderboardEntryPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+    /** 本次提交分数，必须是有限安全数字，范围不超过 JavaScript safe number。 */
+    score: number;
+    /** 展示附加信息，不参与排序和查询；已有记录更新为更优分数时不传则保留旧值，序列化后不超过 2048 字节。 */
+    extra?: Record<string, unknown>;
+}
+/** 提交排行榜分数后返回的当前用户最终记录。 */
+export type SubmitLeaderboardEntryResult = LeaderboardEntry;
+/** 读取排行榜列表。 */
+export interface GetLeaderboardListPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+    /** 每页数量，默认 20，最大 100。 */
+    limit?: number;
+    /** 服务端返回的不透明分页游标；只能原样传回下一页，不能自行构造或解析。 */
+    cursor?: string;
+}
+/** 读取排行榜列表的分页结果。 */
+export interface GetLeaderboardListResult {
+    /** 当前页排行榜记录。 */
+    entries: LeaderboardEntry[];
+    /** 下一页不透明分页游标；仅当 hasMore 为 true 时可能返回。 */
+    cursor?: string;
+    /** 是否还有下一页。 */
+    hasMore: boolean;
+}
+/** 读取当前用户在排行榜中的记录。 */
+export interface GetCurrentUserLeaderboardEntryPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+}
+/** 当前用户排行榜记录；不存在时返回 undefined。 */
+export type GetCurrentUserLeaderboardEntryResult = LeaderboardEntry | undefined;
+/** 删除当前用户在排行榜中的记录。 */
+export interface DeleteCurrentUserLeaderboardEntryPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+}
+/** 删除当前用户排行榜记录的结果。 */
+export interface DeleteCurrentUserLeaderboardEntryResult {
+    /** 是否实际删除了已有记录。 */
+    deleted: boolean;
+}
+/** 读取排行榜基础信息。 */
+export interface GetLeaderboardInfoPayload {
+    /** 排行榜 key；不传时由服务端使用当前小程序已创建的 default 榜单。 */
+    key?: string;
+}
+/** 排行榜基础配置。 */
+export interface GetLeaderboardInfoResult {
+    /** 排行榜 key。 */
+    key: string;
+    /** 排行榜排序方向。 */
+    order: LeaderboardOrder;
+    /** 列表展示名次上限；0 表示不限制。当前用户记录仍最多精确计算前 5000 名。 */
+    rankLimit: number;
+}
+/** 外部小程序可调用的云端排行榜模块。 */
+export interface MiniProgramCloudLeaderboardModule {
+    /** 提交当前用户分数。 */
+    submit(options: SubmitLeaderboardEntryPayload): Promise<SubmitLeaderboardEntryResult>;
+    /** 读取排行榜列表。 */
+    getList(options?: GetLeaderboardListPayload): Promise<GetLeaderboardListResult>;
+    /** 读取当前用户记录。 */
+    getCurrentUserEntry(options?: GetCurrentUserLeaderboardEntryPayload): Promise<GetCurrentUserLeaderboardEntryResult>;
+    /** 删除当前用户记录。 */
+    deleteCurrentUserEntry(options?: DeleteCurrentUserLeaderboardEntryPayload): Promise<DeleteCurrentUserLeaderboardEntryResult>;
+    /** 读取排行榜基础信息。 */
+    getInfo(options?: GetLeaderboardInfoPayload): Promise<GetLeaderboardInfoResult>;
+}
+/** 外部小程序可调用的云端能力模块。 */
+export interface MiniProgramCloudModule {
+    leaderboard: MiniProgramCloudLeaderboardModule;
+}
+export type { MiniProgramCloudMethod } from '../../protocol/capabilities';
+export declare function createCloudModule(requester: MiniProgramRequester): MiniProgramCloudModule;

package/types/protocol/capabilities.d.ts

@@ -1,4 +1,5 @@
 import type { LoginPayload, LoginResult } from '../modules/auth';
+import type { DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult } from '../modules/cloud';
 import type { SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult } from '../modules/device';
 import type { ClosePayload, CloseResult, OpenAppPagePayload, OpenAppPageResult, ReloadPayload, ReloadResult } from '../modules/navigation';
 import type { NetworkRequestPayload, NetworkResponsePayload } from '../modules/network';
@@ -96,6 +97,16 @@ export declare const NAVIGATION_CLOSE_METHOD: "navigation.close";
 export declare const NAVIGATION_RELOAD_METHOD: "navigation.reload";
 /** 打开黑盒 App 页面能力方法名。 */
 export declare const NAVIGATION_OPEN_APP_PAGE_METHOD: "navigation.openAppPage";
+/** 提交当前用户排行榜分数能力方法名。 */
+export declare const CLOUD_LEADERBOARD_SUBMIT_METHOD: "cloud.leaderboard.submit";
+/** 读取排行榜列表能力方法名。 */
+export declare const CLOUD_LEADERBOARD_GET_LIST_METHOD: "cloud.leaderboard.getList";
+/** 读取当前用户排行榜记录能力方法名。 */
+export declare const CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD: "cloud.leaderboard.getCurrentUserEntry";
+/** 删除当前用户排行榜记录能力方法名。 */
+export declare const CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD: "cloud.leaderboard.deleteCurrentUserEntry";
+/** 读取排行榜基础信息能力方法名。 */
+export declare const CLOUD_LEADERBOARD_GET_INFO_METHOD: "cloud.leaderboard.getInfo";
 /** 授权模块开放的方法名。 */
 export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 /** 用户模块开放的方法名。 */
@@ -114,10 +125,12 @@ export type MiniProgramUiMethod = typeof UI_SHOW_TOAST_METHOD | typeof UI_SHOW_L
 export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD;
 /** Navigation 模块开放的方法名。 */
 export type MiniProgramNavigationMethod = typeof NAVIGATION_CLOSE_METHOD | typeof NAVIGATION_RELOAD_METHOD | typeof NAVIGATION_OPEN_APP_PAGE_METHOD;
+/** Cloud 模块开放的方法名。 */
+export type MiniProgramCloudMethod = typeof CLOUD_LEADERBOARD_SUBMIT_METHOD | typeof CLOUD_LEADERBOARD_GET_LIST_METHOD | typeof CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD | typeof CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD | typeof CLOUD_LEADERBOARD_GET_INFO_METHOD;
 /** 父容器开放给小程序调用的 bridge method。 */
-export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod;
+export type MiniProgramBridgeMethod = MiniProgramAuthMethod | MiniProgramUserMethod | MiniProgramShareMethod | MiniProgramViewportMethod | MiniProgramStorageMethod | MiniProgramNetworkMethod | MiniProgramUiMethod | MiniProgramDeviceMethod | MiniProgramNavigationMethod | MiniProgramCloudMethod;
 /** 小程序开放能力所属模块。 */
-export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'ui' | 'device' | 'navigation';
+export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'ui' | 'device' | 'navigation' | 'cloud';
 /** 小程序开放能力风险级别，用于权限、审计和灰度策略。 */
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 /**
@@ -277,6 +290,36 @@ export declare const MINI_PROGRAM_PROTOCOL_CAPABILITIES: readonly [{
     readonly capability: "navigation.openAppPage";
     readonly permission: "navigation.openAppPage";
     readonly risk: "medium";
+}, {
+    readonly method: "cloud.leaderboard.submit";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.submit";
+    readonly permission: "cloud.leaderboard.write";
+    readonly risk: "medium";
+}, {
+    readonly method: "cloud.leaderboard.getList";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.getList";
+    readonly permission: "cloud.leaderboard.read";
+    readonly risk: "low";
+}, {
+    readonly method: "cloud.leaderboard.getCurrentUserEntry";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.getCurrentUserEntry";
+    readonly permission: "cloud.leaderboard.currentUserEntry.read";
+    readonly risk: "medium";
+}, {
+    readonly method: "cloud.leaderboard.deleteCurrentUserEntry";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.deleteCurrentUserEntry";
+    readonly permission: "cloud.leaderboard.currentUserEntry.delete";
+    readonly risk: "medium";
+}, {
+    readonly method: "cloud.leaderboard.getInfo";
+    readonly module: "cloud";
+    readonly capability: "cloud.leaderboard.getInfo";
+    readonly permission: "cloud.leaderboard.info.read";
+    readonly risk: "low";
 }];
 /** bridge method 到请求 payload 的映射。 */
 export interface MiniProgramCapabilityPayloadMap {
@@ -302,6 +345,11 @@ export interface MiniProgramCapabilityPayloadMap {
     [NAVIGATION_CLOSE_METHOD]: ClosePayload;
     [NAVIGATION_RELOAD_METHOD]: ReloadPayload;
     [NAVIGATION_OPEN_APP_PAGE_METHOD]: OpenAppPagePayload;
+    [CLOUD_LEADERBOARD_SUBMIT_METHOD]: SubmitLeaderboardEntryPayload;
+    [CLOUD_LEADERBOARD_GET_LIST_METHOD]: GetLeaderboardListPayload | undefined;
+    [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryPayload | undefined;
+    [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryPayload | undefined;
+    [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoPayload | undefined;
 }
 /** bridge method 到标准化响应 payload 的映射。 */
 export interface MiniProgramCapabilityResultMap {
@@ -327,6 +375,11 @@ export interface MiniProgramCapabilityResultMap {
     [NAVIGATION_CLOSE_METHOD]: CloseResult;
     [NAVIGATION_RELOAD_METHOD]: ReloadResult;
     [NAVIGATION_OPEN_APP_PAGE_METHOD]: OpenAppPageResult;
+    [CLOUD_LEADERBOARD_SUBMIT_METHOD]: SubmitLeaderboardEntryResult;
+    [CLOUD_LEADERBOARD_GET_LIST_METHOD]: GetLeaderboardListResult;
+    [CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD]: GetCurrentUserLeaderboardEntryResult;
+    [CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD]: DeleteCurrentUserLeaderboardEntryResult;
+    [CLOUD_LEADERBOARD_GET_INFO_METHOD]: GetLeaderboardInfoResult;
 }
 /** 指定 bridge method 的请求 payload。 */
 export type MiniProgramCapabilityPayload<T extends MiniProgramBridgeMethod> = MiniProgramCapabilityPayloadMap[T];

package/types/protocol.d.ts

@@ -1,9 +1,10 @@
 export { MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, SDK_HANDSHAKE_METHOD, } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
 export type { MiniProgramBridgeError, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramEventHandler, MiniProgramEventName, MiniProgramEventPayloadMap, } from './protocol/types';
-export { AUTH_LOGIN_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, } from './protocol/capabilities';
-export type { MiniProgramDeviceMethod, MiniProgramAuthMethod, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramNavigationMethod, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUiMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from './protocol/capabilities';
+export { AUTH_LOGIN_METHOD, 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, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, } from './protocol/capabilities';
+export type { MiniProgramDeviceMethod, MiniProgramAuthMethod, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramNavigationMethod, MiniProgramNetworkMethod, MiniProgramShareMethod, MiniProgramStorageMethod, MiniProgramUiMethod, MiniProgramUserMethod, MiniProgramViewportMethod, } from './protocol/capabilities';
 export type { LoginPayload, LoginResult } from './modules/auth';
+export type { DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, LeaderboardEntry, LeaderboardOrder, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, } from './modules/cloud';
 export type { GetCurrentUserDetailPayload, GetCurrentUserDetailResult, GetCurrentUserProfilePayload, GetCurrentUserProfileResult, GetPlatformAccountInfoPayload, GetPlatformAccountInfoResult, GetPlatformAccountOverviewPayload, GetPlatformAccountOverviewResult, GetSteamGameListOptions, GetSteamGameListPayload, GetSteamGameListResult, GetUserInfoPayload, GetUserInfoResult, MiniProgramUserInfo, MiniProgramUserInfoResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, } from './modules/user';
 export type { ScreenshotPayload, ScreenshotResult } from './modules/share/screenshot';
 export type { ShowShareMenuPayload, ShowShareMenuResult } from './modules/share/show-share-menu';