@cloudbase/js-sdk 3.6.2 → 3.6.3-beta.0

package/types/auth.d.ts

@@ -70,27 +70,94 @@ export interface IUser extends IUserInfo {
 export interface ILoginState {
   user: IUser
 }
-export interface ICloudbaseAuth {
+
+/**
+ * v1 兼容事件回调收到的载荷。
+ *
+ * 运行时实际传入的是 `ILoginState` 与事件元数据（`eventType` 等）的混合对象；
+ * 在某些时机（如未登录、首次立即回调）可能为 `null`。这里用一个开放的载荷类型
+ * 精确表达其形态，取代原先的裸 `Function`，同时保持对既有回调写法的非破坏。
+ */
+export type IAuthEventPayload =
+  | (Partial<ILoginState> & {
+    /** 事件类型标识（如 `SIGN_IN` / `SIGN_OUT` / `CREDENTIALS_ERROR` 等）。 */
+    eventType?: string
+    /** 事件携带的原始数据。 */
+    data?: KV<any>
+    [key: string]: any
+  })
+  | null
+
+/**
+ * v1 兼容事件回调签名。
+ *
+ * @deprecated 推荐改用 `onAuthStateChange((event, session, info) => {})` 监听，
+ * 该回调仅为兼容旧代码保留。
+ */
+export type IAuthEventCallback = (payload: IAuthEventPayload) => void
+
+/**
+ * 认证核心能力：状态字段与核心方法，均为**非可选**（与 `ICloudbase` 拆分同款）。
+ */
+export interface AuthCore {
   config: ICloudbaseConfig
   loginType: string
-  weixinAuthProvider: any
-  anonymousAuthProvider: any
-  customAuthProvider: any
   getAccessToken: () => IAccessTokenInfo
   getLoginState: () => Promise<ILoginState | null>
   hasLoginState: () => Promise<ILoginState | null>
   getUserInfo: () => Promise<UserInfo & IUser>
   getAuthHeader: () => Promise<KV<string>>
-  onLoginStateChanged: (callback: Function) => void
-  onLoginStateExpired: (callback: Function) => void
-  onAccessTokenRefreshed: (callback: Function) => void
-  onAnonymousConverted: (callback: Function) => void
-  onLoginTypeChanged: (callback: Function) => void
-  shouldRefreshAccessToken: (hook: Function) => void
   /** 当前登录用户，未登录时为 null */
   currentUser: IUser | null
 }
 
+/**
+ * 认证事件监听能力（v1 兼容）。
+ *
+ * @deprecated 这些监听器均为兼容旧代码保留，推荐统一改用
+ * `onAuthStateChange((event, session, info) => {})`。回调签名已从裸 `Function`
+ * 收紧为精确类型 {@link IAuthEventCallback}，对既有 `(state) => {}` 写法非破坏。
+ */
+export interface AuthEventCapability {
+  onLoginStateChanged: (callback: IAuthEventCallback) => void
+  onLoginStateExpired: (callback: IAuthEventCallback) => void
+  onAccessTokenRefreshed: (callback: IAuthEventCallback) => void
+  onAnonymousConverted: (callback: IAuthEventCallback) => void
+  onLoginTypeChanged: (callback: IAuthEventCallback) => void
+  /** 决定是否刷新 accessToken 的钩子，返回 `true` 表示需要刷新。 */
+  shouldRefreshAccessToken: (hook: () => boolean) => void
+}
+
+/**
+ * 认证身份源提供方能力。三个 provider 由 `registerProvider` 动态注册，
+ * 类型收敛为 {@link IAuthProvider}（取代原先的 `any`）。
+ */
+export interface AuthProviderCapability {
+  weixinAuthProvider: IAuthProvider
+  anonymousAuthProvider: IAuthProvider
+  customAuthProvider: IAuthProvider
+}
+
+/**
+ * 认证客户端总类型。
+ *
+ * 由 {@link AuthCore} + {@link AuthEventCapability} + {@link AuthProviderCapability}
+ * 交叉组合而成，与原先的单一大接口**结构等价**（字段无增删，仅按能力分层 +
+ * 收紧回调/provider 类型），因此对既有代码非破坏。
+ */
+export type ICloudbaseAuth = AuthCore & AuthEventCapability & AuthProviderCapability
+
+/**
+ * 按需组合的认证客户端泛型。
+ *
+ * 默认等价于完整的 {@link ICloudbaseAuth}；也可只声明需要的能力，例如
+ * `CloudbaseAuthClient<AuthEventCapability>` 只暴露事件监听，为 tree-shaking
+ * 与精确 API 面铺路。
+ */
+export type CloudbaseAuthClient<
+  Caps = AuthEventCapability & AuthProviderCapability,
+> = AuthCore & Caps
+
 type IProvider = new (...args: any[]) => any
 
 export interface ICloudbaseAuthModule {

package/types/error.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cloudbase 统一错误结构契约。
+ *
+ * 这是一个**结构化契约**（structural contract），而非要求所有错误都继承同一个 class。
+ * 各模块的具体错误类（如 auth 的 `AuthError`、storage 的 `StorageError`）只要满足此结构，
+ * 即可作为 `Result<T, E>` / `SafeResult<T, E>` 的错误分支类型 `E`。
+ *
+ * 运行时判别推荐使用各模块的类型守卫（如 `isStorageError`），
+ * 或检查隐藏标记字段（如 `__isStorageError`），而非 `instanceof`
+ * （`instanceof` 在跨 bundle / 跨 realm 场景会失效）。
+ */
+export interface ICloudbaseError extends Error {
+  /** 错误名称，用于二级判别（如 `'StorageApiError'`）。 */
+  name: string
+  /** 人类可读的错误描述。 */
+  message: string
+  /** 便于 `JSON.stringify` 时不丢失关键字段（原生 Error 序列化会丢 name/message）。 */
+  toJSON?: () => Record<string, unknown>
+}
+
+/**
+ * Cloudbase 体系内错误的隐藏标记字段集合。
+ *
+ * 各模块的错误类都携带其中之一（在其构造函数中设为 `true`）：
+ * - `__isAuthError`     —— {@link !AuthError}（`@cloudbase/oauth`）
+ * - `__isStorageError`  —— `StorageError`（`@cloudbase/storage`）
+ *
+ * 之所以用隐藏标记而非 `instanceof`，是因为多个 SDK 副本共存（跨 bundle / 跨 realm）
+ * 时 `instanceof` 会失效，而标记字段始终可靠。
+ */
+export type CloudbaseErrorBrand = '__isAuthError' | '__isStorageError'
+
+/**
+ * 统一的跨模块错误判别类型。
+ *
+ * 任何携带 {@link CloudbaseErrorBrand} 标记之一的对象，都被视为 Cloudbase 体系内的错误，
+ * 满足 {@link ICloudbaseError} 契约。各模块另提供具体的运行时守卫（`isAuthError` /
+ * `isStorageError`），本类型用于在类型层统一表达「这是一个 Cloudbase 错误」。
+ */
+export type CloudbaseErrorLike = ICloudbaseError & Partial<Record<CloudbaseErrorBrand, boolean>>

package/types/functions.d.ts

@@ -13,12 +13,21 @@ export interface ICallFunctionOptions {
   header?: KV<any>
 }
 
-export interface ICallFunctionResponse {
+export interface ICallFunctionResponse<T = any> {
   requestId: string
-  result: any
+  /**
+   * 云函数返回值。
+   *
+   * 默认 `any` 以保持对既有调用方（直接访问 `res.result.xxx`）的**非破坏**兼容；
+   * 推荐通过泛型参数指定精确类型以获得类型安全：`callFunction<{ n: number }>(...)`。
+   */
+  result: T
 }
 
-export type ICallFunction = (options: ICallFunctionOptions, callback?: Function) => Promise<ICallFunctionResponse>
+export type ICallFunction = <T = any>(
+  options: ICallFunctionOptions,
+  callback?: (err: Error | null, res: ICallFunctionResponse<T> | null) => void,
+) => Promise<ICallFunctionResponse<T>>
 
 export interface IRetryOptions {
   retries?: number
@@ -29,7 +38,7 @@ export interface IRetryOptions {
   timeouts?: number[]
   timeoutOps?: {
     timeout: number
-    cb: function
+    cb: (...args: any[]) => void
   }
 }
 

package/types/index.d.ts

@@ -18,6 +18,10 @@ import {
 } from './storage'
 import { cloudbase } from '../cloudbase/index'
 
+// 统一返回判别联合与错误契约（可辨识联合范式）
+export { Result, SafeResult } from './result'
+export { ICloudbaseError, CloudbaseErrorBrand, CloudbaseErrorLike } from './error'
+
 export enum LANGS {
   ZH = 'zh-CN',
   EN = 'en-US',
@@ -106,7 +110,14 @@ export interface ICloudbaseApis {
   }
 }
 
-export interface ICloudbase {
+/**
+ * Cloudbase 核心能力（始终存在，与运行时是否注册某个业务组件无关）。
+ *
+ * 这些字段/方法由 SDK 初始化流程直接提供，因此**不是可选的**。
+ * 业务能力（auth / functions / storage / database / ai / models / mysql 等）
+ * 被拆分到独立的 `*Capability` 接口，通过下面的 `ICloudbase` 交叉类型组合。
+ */
+export interface CloudbaseCore {
   config: ICloudbaseConfig
   platform: ICloudbasePlatformInfo
   cache: ICloudbaseCache
@@ -135,17 +146,30 @@ export interface ICloudbase {
     BASE_URL: string
     PROTOCOL: string
   }
+}
+
+/** 身份鉴权能力（`registerAuth` 注册后可用）。 */
+export interface AuthCapability {
   auth?: (options?: { persistence: cloudbase.auth.Persistence }) => cloudbase.auth.App
+}
 
-  // ---- 云函数 ----
+/** 云函数能力（`registerFunctions` 注册后可用）。 */
+export interface FunctionsCapability {
   /** 调用云函数 */
-  callFunction?: (options: ICallFunctionOptions, callback?: Function) => Promise<ICallFunctionResponse>
+  callFunction?: <T = any>(
+    options: ICallFunctionOptions,
+    callback?: (err: Error | null, res: ICallFunctionResponse<T> | null) => void,
+  ) => Promise<ICallFunctionResponse<T>>
+}
 
-  // ---- 数据库 ----
+/** 数据库能力（`registerDatabase` 注册后可用）。 */
+export interface DatabaseCapability {
   /** 获取数据库实例 */
   database?: (dbConfig?: { instance?: string; database?: string }) => cloudbase.database.App
+}
 
-  // ---- 云存储 ----
+/** 云存储能力（`registerStorage` 注册后可用）。 */
+export interface StorageCapability {
   /** Storage 命名空间实例（from 分流 + Bucket 管理） */
   storage?: cloudbase.storage.StorageClient
   /** 上传文件 */
@@ -160,6 +184,39 @@ export interface ICloudbase {
   copyFile?: (params: ICloudbaseCopyFileParams, callback?: Function) => Promise<ICloudbaseCopyFileResult>
 }
 
+/**
+ * 完整的 Cloudbase 实例类型。
+ *
+ * = 核心能力 `CloudbaseCore` + 各业务能力 `*Capability` 的交叉组合。
+ * 结构上等价于旧的单一大接口，但拆分后可读性更好、可按需组合，
+ * 也为未来 tree-shaking 友好的模块化 client 打基础。
+ *
+ * 如需只声明「用到的能力子集」，可直接使用 {@link CloudbaseClient} 泛型组合，
+ * 例如 `CloudbaseClient<AuthCapability & FunctionsCapability>`。
+ */
+export type ICloudbase = CloudbaseCore
+  & AuthCapability
+  & FunctionsCapability
+  & DatabaseCapability
+  & StorageCapability
+
+/**
+ * 按需组合的 Cloudbase 客户端类型。
+ *
+ * 始终包含核心能力 `CloudbaseCore`，并叠加调用方声明的能力集合 `Caps`。
+ *
+ * @example
+ * ```ts
+ * // 只用到 auth 与云函数能力
+ * type MyClient = CloudbaseClient<AuthCapability & FunctionsCapability>
+ * ```
+ *
+ * @typeParam Caps - 需要叠加的能力集合，默认叠加全部内置能力（等价于 `ICloudbase`）
+ */
+export type CloudbaseClient<
+  Caps = AuthCapability & FunctionsCapability & DatabaseCapability & StorageCapability,
+> = CloudbaseCore & Caps
+
 /**
  * Node.js 端适配器扩展方法
  */

package/types/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@cloudbase/types",
-  "version": "3.6.2",
+  "version": "3.6.3-beta.0",
   "description": "cloudbase javascript sdk types",
   "files": [
     "index.js",
     "index.d.ts",
+    "result.d.ts",
+    "error.d.ts",
     "cache.d.ts",
     "events.d.ts",
     "request.d.ts",
@@ -12,6 +14,8 @@
     "component.d.ts",
     "functions.d.ts",
     "cloudrun.d.ts",
+    "container.d.ts",
+    "analytics.d.ts",
     "storage.d.ts",
     "realtime.d.ts",
     "database.d.ts"

package/types/result.d.ts

@@ -0,0 +1,48 @@
+import { ICloudbaseError } from './error'
+
+/**
+ * `{ data, error }` 统一返回结构（可辨识联合 / Discriminated Union）。
+ *
+ * 判别字段为 `error` 是否为 `null`：
+ * - 成功：`{ data: T; error: null }`
+ * - 失败：`{ data: null; error: E }`
+ *
+ * @example
+ * ```ts
+ * const res = await sdk.callFunction<{ n: number }>({ name: 'foo' })
+ * if (res.error === null) {
+ *   // 此处 res.data 被自动收窄为 { n: number }（非 null）
+ *   console.log(res.data.n)
+ * } else {
+ *   // 此处 res.data 被收窄为 null，res.error 为 E
+ *   console.error(res.error.message)
+ * }
+ * ```
+ *
+ * @typeParam T - 成功时的数据类型
+ * @typeParam E - 失败时的错误类型，默认 `ICloudbaseError`
+ */
+export type Result<T, E extends ICloudbaseError = ICloudbaseError> =
+  | { data: T; error: null }
+  | { data: null; error: E }
+
+/**
+ * 安全解构变体：失败分支的 `data` 不是 `null`，而是把成功 shape 的每个字段映射成 `null`。
+ *
+ * 这样即使不先判空 `error`，也能安全解构成功结构里的字段（值可能为 `null`）：
+ *
+ * @example
+ * ```ts
+ * // 无需先判 res.data === null 即可解构
+ * const { data: { user, session } } = await auth.signInWithPassword({ ... })
+ * ```
+ *
+ * 该类型用于「已有 `{ data: { ... } }` 嵌套结构、需要平滑升级为判别联合」的场景（如 auth）。
+ * 相比 `Result<T>`，它对既有解构代码是**非破坏性**的升级。
+ *
+ * @typeParam T - 成功时的数据结构（必须为对象）
+ * @typeParam E - 失败时的错误类型，默认 `ICloudbaseError`
+ */
+export type SafeResult<T extends object, E extends ICloudbaseError = ICloudbaseError> =
+  | { data: T; error: null }
+  | { data: { [K in keyof T]: null }; error: E }

package/types/storage.d.ts

@@ -1,14 +1,31 @@
 import { KVstring } from '.'
 import { ICustomReqOpts } from './functions'
 
+/**
+ * 上传/下载时的原始文件内容，覆盖浏览器与 Node 两端形态：
+ * - Node 端：`Buffer`（属于 `Uint8Array`）、可读流（含 `size`/`byteLength` 的对象）
+ * - 浏览器端：`Blob` / `File` / `ArrayBuffer` / TypedArray 等 `ArrayBufferView`
+ * - 纯文本内容：`string`
+ *
+ * 末尾的 `{ size?: number; byteLength?: number }` 兼容自定义流对象（实现层据此推算
+ * content-length）。这是一个开放联合：既约束常见形态，又不排除运行时特殊对象。
+ */
+export type FileContent =
+  | Blob
+  | ArrayBuffer
+  | ArrayBufferView
+  | Uint8Array
+  | string
+  | { size?: number; byteLength?: number; [key: string]: any };
+
 export interface ICloudbaseUploadFileParams {
   cloudPath: string;
   filePath: string;
   method?: 'post' | 'put';
   headers?: KVstring;
   onUploadProgress?: Function;
-  // 文件内容 Buffer 或 文件可读流, node端使用
-  fileContent?: any;
+  /** 文件内容：Buffer / 可读流（Node 端）或 Blob / ArrayBuffer（浏览器端） */
+  fileContent?: FileContent;
   customReqOpts?: ICustomReqOpts;
 }
 
@@ -103,7 +120,8 @@ export interface ICloudbaseDownloadFileParams {
 export interface ICloudbaseDownloadFileResult {
   code?: string;
   message?: string;
-  fileContent?: any;
+  /** 下载得到的文件内容：Buffer / 流（Node 端）或 Blob / ArrayBuffer（浏览器端） */
+  fileContent?: FileContent;
   requestId?: string;
 }
 

package/utilities/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/utilities",
-  "version": "3.6.2",
+  "version": "3.6.3-beta.0",
   "description": "cloudbase javascript sdk utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -19,7 +19,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@cloudbase/adapter-interface": "^0.7.1",
-    "@cloudbase/types": "3.6.2",
+    "@cloudbase/types": "3.6.3-beta.0",
     "jwt-decode": "^3.1.2"
   },
   "gitHead": "859557576897d4778857c12fb8d7fe8ca1f3a052"