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

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

@@ -1,23 +1,165 @@
 import type { LoginScope as ProtocolLoginScope } from '@heybox/hb-sdk-protocol';
 import type { MiniProgramRequester } from '../../core/client';
 export { AUTH_LOGIN_METHOD } from '../../protocol/capabilities';
-/** 登录 scope 与 Protocol canonical 用户信息 scope 保持同源。 */
+/**
+ * 登录时可请求的用户信息 scope。
+ *
+ * @remarks
+ * - `identity`：允许开发者服务端取得当前用户在当前小程序内稳定、隔离的
+ *   `app_user_id`。它不是黑盒用户 ID，也不能跨小程序关联用户。
+ * - `profile`：允许开发者服务端读取当前用户的昵称和头像。用户可以只同意
+ *   `identity`，因此请求 `profile` 不代表最终一定获得该 scope。
+ *
+ * `identity` 是登录流程的必选 scope：调用方可以不传它，平台仍会把它加入实际授权
+ * 结果。scope 只描述授权码和后续 OpenAPI token 可访问的资料，不是 token、客户端权限
+ * 或 `package.json#heybox.permissions` 中的开发者权限声明。
+ *
+ * @see {@link LoginOptions.scopes}
+ * @see {@link LoginResult.scopes}
+ * @see [用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)
+ */
 export type LoginScope = ProtocolLoginScope;
+/**
+ * `auth.login` 的可选配置。
+ *
+ * @remarks
+ * 整个参数、省略的 `scopes` 和 `scopes: undefined` 都表示只申请平台隐式包含的
+ * `identity`。配置中不接收小程序 ID、用户 ID、手势标记、应用密钥或 token；这些值由
+ * Host 的可信上下文提供，不能由页面覆盖。
+ *
+ * @see {@link LoginScope}
+ * @see [权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)
+ */
 export interface LoginOptions {
+    /**
+     * 要申请的可选资料 scope。
+     *
+     * @remarks
+     * 通常只在需要昵称和头像时传 `['profile']`；`identity` 无需显式填写。空数组不会产生
+     * 匿名授权，成功结果仍包含 `identity`。数组中的值必须属于 {@link LoginScope} 且不能
+     * 重复；JavaScript 调用传入未知值、重复值、`null` 或非数组值时，Promise 以
+     * `HbMiniProgramSDKError.code === 'INVALID_PARAMS'` 拒绝。
+     *
+     * @defaultValue `undefined`，即只申请隐式的 `identity`。
+     * @see {@link LoginResult.scopes}
+     */
     scopes?: LoginScope[];
 }
+/** `auth.login` 的请求载荷；不传配置时为 `undefined`。 */
 export type LoginPayload = LoginOptions | undefined;
-/** 小程序服务端用于换取当前用户身份的短期授权码。 */
+/**
+ * 小程序服务端用于换取当前用户身份的短期授权码。
+ *
+ * @remarks
+ * 页面应立即把 `code` 通过 HTTPS 提交给开发者自己的服务端；服务端再使用仅保存在
+ * 服务端的应用凭据换取 OpenAPI token。不要把结果写入 DOM、日志、localStorage 或其他
+ * 持久化存储，也不要把 `code` 当作 `app_user_id` 或业务 session 使用。
+ *
+ * @see {@link LoginOptions}
+ * @see [服务端换票流程](https://docs.xiaoheihe.cn/hb_sdk/guide/auth#后端-openapi)
+ */
 export interface LoginResult {
+    /**
+     * 一次性短期授权码。
+     *
+     * @remarks
+     * 该不透明字符串只属于当前小程序，提交给开发者服务端并成功换票后立即失效。过期、
+     * 重复使用或提交给其他小程序都会换票失败；此时应由新的明确用户操作再次调用
+     * `auth.login()`，不要重试或解析旧 code。
+     */
     code: string;
+    /**
+     * 授权码剩余有效期，单位为秒。
+     *
+     * @remarks
+     * 返回值是正整数；当前服务端通常返回 `300`，但调用方必须以本字段为准并尽快换票，
+     * 不要把 `300` 硬编码为长期契约。该值不是换票后 access token 或业务 session 的有效期。
+     */
     expiresIn: number;
+    /**
+     * 本次授权码实际包含的 scope。
+     *
+     * @remarks
+     * 数组无重复项且始终包含 `identity`。它可能少于 {@link LoginOptions.scopes} 中请求的
+     * scope；只有这里实际包含 `profile` 时，服务端才应读取或依赖昵称、头像字段。
+     */
     scopes: LoginScope[];
 }
 export type { MiniProgramAuthMethod } from '../../protocol/capabilities';
 /** 外部小程序可调用的授权模块。 */
 export interface MiniProgramAuthModule {
     /**
-     * 获取短期授权码；不会向小程序暴露 token、cookie 或黑盒用户资料。
+     * 为当前小程序获取一次性短期授权码，由开发者服务端建立用户会话。
+     *
+     * @param options - 可选的授权配置。不传、传 `{}` 或 `scopes: undefined` 时只申请隐式
+     * `identity`；需要昵称和头像时传 `{ scopes: ['profile'] }`。
+     * @returns Promise 成功时返回 {@link LoginResult}。它只包含一次性 code、code 有效期和
+     * 实际授权 scope，不包含用户资料、`app_user_id`、access token、cookie 或应用密钥。
+     * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`scopes` 不是数组、包含未知值或
+     * 重复值。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`：
+     * 当前版本未声明或不可使用 `userInfo` 权限。
+     * @throws {@link HbMiniProgramSDKError} `USER_GESTURE_REQUIRED`：本次需要展示黑盒登录或
+     * 授权 UI，但调用没有可信用户手势；`AUTHORIZATION_CANCELLED`：用户取消、关闭授权页，
+     * 或没有同意必选的 `identity`。
+     * @throws {@link HbMiniProgramSDKError} `HEYBOX_APP_LOGIN_REQUIRED`：当前黑盒账号未登录或
+     * 登录态已失效；`AUTHORIZATION_CONTEXT_CHANGED`：授权期间发生账号切换、授权撤销等
+     * 上下文变化；`AUTHORIZATION_PRESENTATION_UNAVAILABLE`：Host 无法展示授权界面。
+     * @throws {@link HbMiniProgramSDKError} `REQUEST_FAILED`、`REQUEST_UNSUPPORTED`、
+     * `INVALID_RESPONSE`、`INVALID_STATE`、`METHOD_FORBIDDEN` 或 `RUNTIME_DESTROYED`：Host
+     * 请求、响应、身份上下文、能力支持或 Runtime 生命周期不满足调用要求。
+     * @throws {@link HbMiniProgramSDKError} SDK 握手、bridge 请求超时或 SDK 销毁时，抛出对应
+     * 初始化/transport 错误；业务应根据稳定的 `error.code` 分支，不比较 `message`。
+     *
+     * @remarks
+     * 在项目根 `package.json#heybox.permissions.userInfo.enabled` 中声明 `true` 后才能调用。
+     * `userInfo` 是开发者权限声明，{@link LoginOptions.scopes} 是用户资料授权，两层门禁互不
+     * 替代。
+     *
+     * SDK 会自动等待握手，但可能展示 UI 的调用必须直接发生在登录、绑定账号等明确的用户
+     * 操作回调中。页面应提前用 `getHandshakeState()` 和 `onHandshakeStateChange()` 启用按钮，
+     * 不要在点击后先等待其他异步工作。所需 scope 已授权时，Host 可以不展示 UI，直接签发
+     * 新 code；调用方仍不能假定以后每次都能静默完成。
+     *
+     * 本能力通过 Host 的受信请求完成登录，不要求公开 `network` 权限。页面若用
+     * `network.request()` 把 code 发给自己的服务端，该网络调用仍须另行声明并获得 `network`
+     * 平台批准。页面不能直接访问平台换票接口，也不能持有服务端应用凭据。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * async function loginFromUserAction() {
+     *   try {
+     *     const result = await hbSDK.auth.login({ scopes: ['profile'] })
+     *
+     *     // 这是开发者自己的 HTTPS 接口；服务端负责换票并建立业务 session。
+     *     await hbSDK.network.request({
+     *       url: 'https://api.example.com/session/heybox',
+     *       method: 'POST',
+     *       data: { code: result.code },
+     *     })
+     *
+     *     if (!result.scopes.includes('profile')) {
+     *       renderWithoutProfile()
+     *     }
+     *   } catch (error) {
+     *     if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
+     *       return
+     *     }
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link LoginOptions}
+     * @see {@link LoginResult}
+     * @see [用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)
+     * @see [权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)
+     * @see [错误处理](https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling)
+     * @see [user.getInfo](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/user/getInfo)
+     * @see [user.revokeAuthorization](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/user/revokeAuthorization)
+     * @see [network.request](https://docs.xiaoheihe.cn/hb_sdk/reference/sdk/network/request)
      *
      * @since 0.2.0-alpha.0
      * @hbPlatform android
@@ -33,7 +175,19 @@ export interface MiniProgramAuthModule {
      */
     login(options?: LoginOptions): Promise<LoginResult>;
 }
-/** 获取短期授权码。 */
+/**
+ * 获取短期授权码。
+ *
+ * @param requester - SDK 内部的能力请求器。
+ * @param options - 可选的资料 scope；不传时不附带请求载荷。
+ * @returns 与 {@link MiniProgramAuthModule.login} 相同的授权码结果。
+ * @throws {@link HbMiniProgramSDKError} 当 Host 拒绝请求、用户取消授权或 SDK 状态无效时抛出。
+ */
 export declare function login(requester: MiniProgramRequester, options?: LoginOptions): Promise<LoginResult>;
-/** 创建授权模块。 */
+/**
+ * 创建授权模块。
+ *
+ * @param requester - SDK 内部的能力请求器。
+ * @returns 绑定到该 requester 的授权模块。
+ */
 export declare function createAuthModule(requester: MiniProgramRequester): MiniProgramAuthModule;