@heybox/hb-sdk 0.1.2

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

@@ -0,0 +1,18 @@
+import type { MiniProgramRequester } from '../../core/client';
+import { SHARE_SCREENSHOT_METHOD, type ScreenshotResult } from './screenshot';
+import { SHARE_SHOW_SHARE_MENU_METHOD, type ShowShareMenuPayload, type ShowShareMenuResult } from './show-share-menu';
+import type { MiniProgramScreenshotOptions } from './types';
+export * from './screenshot';
+export * from './show-share-menu';
+export * from './types';
+/** 分享模块开放的方法名。 */
+export type MiniProgramShareMethod = typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
+/** 外部小程序可调用的分享模块。 */
+export interface MiniProgramShareModule {
+    /** 展示基础分享面板。 */
+    showShareMenu(options: ShowShareMenuPayload): Promise<ShowShareMenuResult>;
+    /** 截图并唤起分享。 */
+    screenshot(options?: MiniProgramScreenshotOptions): Promise<ScreenshotResult>;
+}
+/** 创建分享模块。 */
+export declare function createShareModule(requester: MiniProgramRequester): MiniProgramShareModule;

package/types/modules/share/screenshot.d.ts

@@ -0,0 +1,10 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { MiniProgramScreenshotOptions } from './types';
+/** 截图分享能力方法名。 */
+export declare const SHARE_SCREENSHOT_METHOD: "share.screenshot";
+/** `share.screenshot` 入参。 */
+export type ScreenshotPayload = MiniProgramScreenshotOptions | undefined;
+/** `share.screenshot` 返回值由客户端协议决定。 */
+export type ScreenshotResult = unknown;
+/** 截图并唤起分享。 */
+export declare function screenshot(requester: MiniProgramRequester, options?: MiniProgramScreenshotOptions): Promise<ScreenshotResult>;

package/types/modules/share/show-share-menu.d.ts

@@ -0,0 +1,10 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { MiniProgramShowShareMenuOptions } from './types';
+/** 展示分享面板能力方法名。 */
+export declare const SHARE_SHOW_SHARE_MENU_METHOD: "share.showShareMenu";
+/** `share.showShareMenu` 入参。 */
+export type ShowShareMenuPayload = MiniProgramShowShareMenuOptions;
+/** `share.showShareMenu` 返回值由客户端协议决定。 */
+export type ShowShareMenuResult = unknown;
+/** 展示基础分享面板。 */
+export declare function showShareMenu(requester: MiniProgramRequester, options: ShowShareMenuPayload): Promise<ShowShareMenuResult>;

package/types/modules/share/types.d.ts

@@ -0,0 +1,35 @@
+/** 小程序可选分享渠道。 */
+export type MiniProgramShareChannel = 'wechatSession' | 'wechatTimeline' | 'qqFriend' | 'qzone' | 'weibo';
+/** 展示基础分享面板的配置。 */
+export interface MiniProgramShowShareMenuOptions {
+    /** 分享标题。 */
+    title: string;
+    /** 分享描述。 */
+    desc: string;
+    /** 分享落地页 URL。 */
+    url: string;
+    /** 分享缩略图 URL。 */
+    imageUrl?: string;
+    /** 指定分享渠道；不传则由客户端展示默认分享面板。 */
+    channel?: MiniProgramShareChannel;
+}
+/** 截图区域。 */
+export interface MiniProgramScreenshotRect {
+    /** 截图区域左边距。 */
+    left: number;
+    /** 截图区域上边距。 */
+    top: number;
+    /** 截图区域宽度。 */
+    width: number;
+    /** 截图区域高度。 */
+    height: number;
+}
+/** 截图分享配置。 */
+export interface MiniProgramScreenshotOptions {
+    /** 指定截图区域；不传则默认截当前可见窗口。 */
+    rect?: MiniProgramScreenshotRect;
+    /** 截图延迟，单位毫秒。 */
+    delay?: number;
+    /** 是否展示保存到相册能力。 */
+    saveToAlbum?: boolean;
+}

package/types/modules/system/get-storage.d.ts

@@ -0,0 +1,15 @@
+import type { MiniProgramRequester } from '../../core/client';
+/** 获取小程序隔离 storage 能力方法名。 */
+export declare const SYSTEM_GET_STORAGE_METHOD: "system.getStorage";
+/** `system.getStorage` 入参。 */
+export interface GetStoragePayload {
+    /** storage key。 */
+    key: string;
+}
+/** `system.getStorage` 返回值。 */
+export interface GetStorageResult<T = unknown> {
+    /** key 对应的数据；不存在时为 undefined。 */
+    data: T | undefined;
+}
+/** 获取小程序隔离 storage。 */
+export declare function getStorage<T = unknown>(requester: MiniProgramRequester, options: GetStoragePayload): Promise<GetStorageResult<T>>;

package/types/modules/system/get-window-info.d.ts

@@ -0,0 +1,16 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { MiniProgramWindowInfoResult } from './types';
+/** 系统窗口信息能力方法名。 */
+export declare const SYSTEM_GET_WINDOW_INFO_METHOD: "system.getWindowInfo";
+/**
+ * `system.getWindowInfo` 不需要入参。
+ */
+export type GetWindowInfoPayload = void;
+/**
+ * `system.getWindowInfo` 返回当前小程序可用窗口信息。
+ */
+export type GetWindowInfoResult = MiniProgramWindowInfoResult;
+/**
+ * 获取当前小程序窗口信息。
+ */
+export declare function getWindowInfo(requester: MiniProgramRequester): Promise<GetWindowInfoResult>;

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

@@ -0,0 +1,23 @@
+import type { MiniProgramRequester } from '../../core/client';
+import { SYSTEM_GET_WINDOW_INFO_METHOD, type GetWindowInfoResult } from './get-window-info';
+import { SYSTEM_GET_STORAGE_METHOD, type GetStoragePayload, type GetStorageResult } from './get-storage';
+import { SYSTEM_SET_STORAGE_METHOD, type SetStoragePayload } from './set-storage';
+export * from './get-window-info';
+export * from './get-storage';
+export * from './set-storage';
+export * from './types';
+/** 系统模块开放的方法名。 */
+export type MiniProgramSystemMethod = typeof SYSTEM_GET_WINDOW_INFO_METHOD | typeof SYSTEM_GET_STORAGE_METHOD | typeof SYSTEM_SET_STORAGE_METHOD;
+/** 外部小程序可调用的系统模块。 */
+export interface MiniProgramSystemModule {
+    /**
+     * 获取当前小程序窗口信息。
+     */
+    getWindowInfo(): Promise<GetWindowInfoResult>;
+    /** 获取小程序隔离 storage。 */
+    getStorage<T = unknown>(options: GetStoragePayload): Promise<GetStorageResult<T>>;
+    /** 写入小程序隔离 storage。 */
+    setStorage(options: SetStoragePayload): Promise<void>;
+}
+/** 创建系统模块。 */
+export declare function createSystemModule(requester: MiniProgramRequester): MiniProgramSystemModule;

package/types/modules/system/set-storage.d.ts

@@ -0,0 +1,12 @@
+import type { MiniProgramRequester } from '../../core/client';
+/** 写入小程序隔离 storage 能力方法名。 */
+export declare const SYSTEM_SET_STORAGE_METHOD: "system.setStorage";
+/** `system.setStorage` 入参。 */
+export interface SetStoragePayload {
+    /** storage key。 */
+    key: string;
+    /** 需要写入的数据。 */
+    data: unknown;
+}
+/** 写入小程序隔离 storage。 */
+export declare function setStorage(requester: MiniProgramRequester, options: SetStoragePayload): Promise<void>;

package/types/modules/system/types.d.ts

@@ -0,0 +1,34 @@
+/** 小程序安全区域信息。 */
+export interface MiniProgramSafeArea {
+    /** 安全区域左上角横坐标。 */
+    left: number;
+    /** 安全区域右下角横坐标。 */
+    right: number;
+    /** 安全区域左上角纵坐标。 */
+    top: number;
+    /** 安全区域右下角纵坐标。 */
+    bottom: number;
+    /** 安全区域宽度，单位 px。 */
+    width: number;
+    /** 安全区域高度，单位 px。 */
+    height: number;
+}
+/** 小程序窗口信息。 */
+export interface MiniProgramWindowInfoResult {
+    /** 设备像素比。 */
+    pixelRatio: number;
+    /** 屏幕宽度，单位 px。 */
+    screenWidth: number;
+    /** 屏幕高度，单位 px。 */
+    screenHeight: number;
+    /** 可使用窗口宽度，单位 px。 */
+    windowWidth: number;
+    /** 可使用窗口高度，单位 px。 */
+    windowHeight: number;
+    /** 状态栏高度；黑盒环境按顶部可用偏移兼容。 */
+    statusBarHeight: number;
+    /** 安全区域。 */
+    safeArea: MiniProgramSafeArea;
+    /** 窗口上边缘的 y 值。 */
+    screenTop: number;
+}

package/types/modules/user/get-info.d.ts

@@ -0,0 +1,19 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { MiniProgramUserInfoResult } from './types';
+/** 用户信息能力方法名。 */
+export declare const USER_GET_INFO_METHOD: "user.getInfo";
+/**
+ * `user.getInfo` 不需要入参。
+ */
+export type GetUserInfoPayload = void;
+/**
+ * `user.getInfo` 返回当前用户登录态与公开基础资料。
+ */
+export type GetUserInfoResult = MiniProgramUserInfoResult;
+/**
+ * 获取当前访问小程序用户的公开基础资料。
+ *
+ * 该能力只返回 `heybox_id`、`nickname`、`avatar` 三个公开字段。
+ * 未登录时不会触发登录流程，直接返回 `{ isLogin: false, userInfo: null }`。
+ */
+export declare function getInfo(requester: MiniProgramRequester): Promise<GetUserInfoResult>;

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

@@ -0,0 +1,21 @@
+import type { MiniProgramRequester } from '../../core/client';
+import { USER_GET_INFO_METHOD, type GetUserInfoResult } from './get-info';
+import { USER_LOGIN_METHOD, type LoginResult } from './login';
+export * from './get-info';
+export * from './login';
+export * from './types';
+/** 用户模块开放的方法名。 */
+export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_LOGIN_METHOD;
+/** 外部小程序可调用的用户模块。 */
+export interface MiniProgramUserModule {
+    /**
+     * 获取当前用户登录态与公开基础资料。
+     */
+    getInfo(): Promise<GetUserInfoResult>;
+    /**
+     * 唤起登录，并返回登录后的最新用户信息。
+     */
+    login(): Promise<LoginResult>;
+}
+/** 创建用户模块。 */
+export declare function createUserModule(requester: MiniProgramRequester): MiniProgramUserModule;

package/types/modules/user/login.d.ts

@@ -0,0 +1,18 @@
+import type { MiniProgramRequester } from '../../core/client';
+import type { MiniProgramUserInfoResult } from './types';
+/** 用户登录能力方法名。 */
+export declare const USER_LOGIN_METHOD: "user.login";
+/**
+ * `user.login` 不需要入参。
+ */
+export type LoginPayload = void;
+/**
+ * `user.login` 返回登录流程结束后的最新用户登录态与公开基础资料。
+ */
+export type LoginResult = MiniProgramUserInfoResult;
+/**
+ * 唤起黑盒登录流程，并在流程返回后刷新用户公开基础资料。
+ *
+ * 该能力不会向小程序暴露 token、cookie 或任何登录凭据。
+ */
+export declare function login(requester: MiniProgramRequester): Promise<LoginResult>;

package/types/modules/user/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 小程序用户公开基础资料。
+ *
+ * 这里只包含允许暴露给外部小程序的公开字段，不包含 token、手机号、
+ * cookie 或任何可用于直接调用主站私有接口的凭据。
+ */
+export interface MiniProgramUserInfo {
+    /** 黑盒用户 ID。 */
+    heybox_id: string;
+    /** 用户昵称。 */
+    nickname: string;
+    /** 用户头像 URL。 */
+    avatar: string;
+}
+/**
+ * 用户能力统一返回结构。
+ *
+ * 未登录时 `isLogin` 为 `false`，且 `userInfo` 固定为 `null`。
+ * 已登录时 `isLogin` 为 `true`，`userInfo` 为公开基础资料。
+ */
+export interface MiniProgramUserInfoResult {
+    /** 当前访问小程序的用户是否已登录黑盒账号。 */
+    isLogin: boolean;
+    /** 当前用户公开基础资料；未登录时为 `null`。 */
+    userInfo: MiniProgramUserInfo | null;
+}

package/types/protocol/constants.d.ts

@@ -0,0 +1,8 @@
+/** 小程序沙盒通信命名空间，父容器与 iframe 内 SDK 必须保持一致。 */
+export declare const MINI_PROGRAM_MESSAGE_NAMESPACE: "heybox:miniprogram";
+/** 小程序沙盒通信协议版本。 */
+export declare const MINI_PROGRAM_MESSAGE_VERSION: 1;
+/** 父容器注入到小程序 URL 上的通信 nonce 参数名。 */
+export declare const MINI_PROGRAM_BRIDGE_NONCE_PARAM: "hb_mini_bridge_nonce";
+/** SDK 初始化时发给父容器的握手方法名。 */
+export declare const SDK_HANDSHAKE_METHOD: "sdk.handshake";

package/types/protocol/guards.d.ts

@@ -0,0 +1,3 @@
+import type { MiniProgramBridgeMessage } from './types';
+/** 判断未知数据是否符合小程序 bridge 消息信封。 */
+export declare function isMiniProgramBridgeMessage(value: unknown): value is MiniProgramBridgeMessage;

package/types/protocol/types.d.ts

@@ -0,0 +1,87 @@
+import type { MiniProgramUserInfoResult } from '../modules/user/types';
+import type { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION } from './constants';
+/** 小程序沙盒消息类型。 */
+export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event';
+/** 首版开放给外部小程序监听的生命周期与业务事件名。 */
+export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'authChange';
+/**
+ * bridge 错误结构。
+ *
+ * 所有请求失败都会被规范化成该结构，SDK 侧再包装为 `HbMiniProgramSDKError`。
+ */
+export interface MiniProgramBridgeError {
+    /** 稳定错误码，便于业务侧分支处理。 */
+    code: string;
+    /** 面向开发者的中文错误说明。 */
+    message: string;
+    /** 可选调试数据，不保证结构稳定。 */
+    data?: unknown;
+}
+/**
+ * SDK 与沙盒之间统一的 postMessage 信封。
+ *
+ * 由于 iframe sandbox 不启用 `allow-same-origin`，协议不依赖 origin 校验，
+ * 而是由父容器校验 `event.source === iframe.contentWindow` 与实例 nonce。
+ */
+export interface MiniProgramBridgeMessage<TPayload = unknown> {
+    /** 固定命名空间，用于过滤非小程序消息。 */
+    namespace: typeof MINI_PROGRAM_MESSAGE_NAMESPACE;
+    /** 协议版本号。 */
+    version: typeof MINI_PROGRAM_MESSAGE_VERSION;
+    /** 当前 iframe 实例的通信随机串。 */
+    nonce: string;
+    /** 消息类型。 */
+    type: MiniProgramBridgeMessageType;
+    /** 请求/响应关联 ID。 */
+    id?: string;
+    /** 请求方法名或事件名。 */
+    method?: string;
+    /** 消息载荷。 */
+    payload?: TPayload;
+    /** 失败响应的错误信息。 */
+    error?: MiniProgramBridgeError;
+}
+/**
+ * 小程序事件载荷映射。
+ *
+ * `on/off` 会基于该映射推导 handler 参数类型。
+ */
+export interface MiniProgramEventPayloadMap {
+    /** 小程序首次完成握手并启动。 */
+    launch: {
+        /** 事件时间戳。 */
+        timestamp: number;
+        /** 父容器最终加载到 iframe 的 URL。 */
+        url?: string;
+    };
+    /** SDK 已可安全调用开放能力。 */
+    ready: {
+        /** 事件时间戳。 */
+        timestamp: number;
+    };
+    /** 小程序页面展示。 */
+    show: {
+        /** 事件时间戳。 */
+        timestamp: number;
+        /** 触发展示的父容器来源。 */
+        source?: string;
+    };
+    /** 小程序页面隐藏。 */
+    hide: {
+        /** 事件时间戳。 */
+        timestamp: number;
+        /** 触发隐藏的父容器来源。 */
+        source?: string;
+    };
+    /** 小程序页面即将卸载。 */
+    unload: {
+        /** 事件时间戳。 */
+        timestamp: number;
+    };
+    /** 父容器或开放能力运行异常。 */
+    error: MiniProgramBridgeError;
+    /** 登录状态发生变化后的最新用户信息。 */
+    authChange: MiniProgramUserInfoResult;
+}
+/** 小程序事件监听函数。 */
+export type MiniProgramEventHandler<T extends MiniProgramEventName = MiniProgramEventName> = (payload: MiniProgramEventPayloadMap[T]) => void;