@cloudbase/js-sdk 4.0.0 → 4.0.1-alpha.0

package/types/analytics.d.ts

@@ -0,0 +1,51 @@
+// report 接口传参结构
+export interface IReportData {
+  report_type: string, // 上报场景  如电商 mall，游戏 game
+  report_data: {
+    action_time?: number, // 非必填  行为发生时，客户端的时间点，单位s
+    action_type: string, // 必填 行为类型 如 访问 visit_store，分享 share，加入购物车 add_to_cart等
+    click_id?: string, // 非必填  广告平台会在URL增加click_id
+    action_param?: { // 非必填
+      value?: number, // 非必填 行为所带的参数，转化行为价值（例如金额）
+      leads_type?: string // 非必填 行为来源，目前支持PHONE（电话直呼），RESERVE（表单预约）
+    },
+    product_param?: { // 非必填
+      product_yun_type?: string, // 非必填  商品 goods ，优惠券 coupon, 搜索词 search_term
+      product_yun_id?: string, // 非必填 商品id
+      product_yun_category?: string, // 非必填 商品类目 自定义
+      product_yun_keywords?: string, // 非必填 商品关键词
+      product_yun_price?: number, // 非必填 商品原价
+      product_yun_value?: number, // 非必填 商品成交价
+      product_yun_name?: string, // 非必填 商品名
+      product_yun_id_ad?: string, // 非必填 广告商品库中商品id
+      product_yun_category_ad?: string // 非必填 广告商品库中商品类目
+    }
+  }
+}
+
+// 上报数据结构
+export interface IAnalyticsDataItem {
+  analytics_scene: string, // 上报场景  如电商 mall，游戏 game
+  analytics_data: { // 场景模板内容，以电商模板举例
+    openid?: string, // 必填  用户openid
+    wechat_mini_program_appid?: string, // 必填小程序appid
+    action_time: number, // 必填  行为发生时，客户端的时间点，单位s
+    action_type: string, // 必填 行为类型 如 访问 visit_store，分享 share，加入购物车 add_to_cart等
+    click_id?: string, // 非必填  广告平台会在URL增加click_id
+    action_param?: { // 非必填
+      value?: number, // 非必填 行为所带的参数，转化行为价值（例如金额）
+      leads_type?: string // 非必填 行为来源，目前支持PHONE（电话直呼），RESERVE（表单预约）
+    },
+    product_param?: { // 非必填
+      product_yun_type?: string, // 非必填  商品 goods ，优惠券 coupon, 搜索词 search_term
+      product_yun_id?: string, // 非必填 商品id
+      product_yun_category?: string, // 非必填 商品类目 自定义
+      product_yun_keywords?: string, // 非必填 商品关键词
+      product_yun_price?: number, // 非必填 商品原价
+      product_yun_value?: number, // 非必填 商品成交价
+      product_yun_name?: string, // 非必填 商品名
+      product_yun_id_ad?: string, // 非必填 广告商品库中商品id
+      product_yun_category_ad?: string // 非必填 广告商品库中商品类目
+    }
+  }
+}

package/types/auth.d.ts

@@ -0,0 +1,166 @@
+import { ICloudbaseConfig, KV, ICloudbase } from '.'
+import { authModels, UserInfo } from '@cloudbase/oauth'
+import { ICloudbaseEventEmitter } from './events'
+
+export type ICloudbaseAuthConfig = Pick<
+ICloudbaseConfig,
+| 'env'
+| 'clientId'
+| 'region'
+| 'persistence'
+| 'debug'
+| '_fromApp'
+| 'oauthInstance'
+| 'wxCloud'
+| 'i18n'
+| 'accessKey'
+| 'useWxCloud'
+| 'auth'
+> &
+ICloudbaseConfig['auth']
+& {eventBus?: ICloudbaseEventEmitter}
+
+export interface IAccessTokenInfo {
+  accessToken: string
+  env: string
+}
+export interface ICredential {
+  // refreshToken: string;
+  accessToken?: string
+  accessTokenExpire?: string
+}
+export interface IAuthProvider {
+  signInWithRedirect: () => any
+}
+export interface IUserInfo {
+  uid?: string
+  loginType?: string
+  openid?: string
+  wxOpenId?: string
+  wxPublicId?: string
+  unionId?: string
+  qqMiniOpenId?: string
+  customUserId?: string
+  name?: string
+  displayName?: string
+  gender?: string
+  email?: string
+  username?: string
+  hasPassword?: boolean
+  location?: {
+    country?: string
+    province?: string
+    city?: string
+  }
+  country?: string
+  province?: string
+  city?: string
+}
+export interface IUser extends IUserInfo {
+  checkLocalInfo: () => void
+  checkLocalInfoAsync: () => Promise<void>
+  linkWithTicket?: (ticket: string) => Promise<void>
+  linkWithRedirect?: (provider: IAuthProvider) => void
+  getLinkedUidList?: () => Promise<{ hasPrimaryUid: boolean; users: IUserInfo[] }>
+  setPrimaryUid?: (uid: string) => Promise<void>
+  unlink?: (loginType: 'CUSTOM' | 'WECHAT-OPEN' | 'WECHAT-PUBLIC' | 'WECHAT-UNION') => Promise<void>
+  update: (userinfo: authModels.UserProfile) => Promise<void>
+  refresh: (params?: { version?: string }) => Promise<authModels.UserInfo>
+}
+export interface ILoginState {
+  user: IUser
+}
+
+/**
+ * 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
+  getAccessToken: () => IAccessTokenInfo
+  getLoginState: () => Promise<ILoginState | null>
+  hasLoginState: () => Promise<ILoginState | null>
+  getUserInfo: () => Promise<UserInfo & IUser>
+  getAuthHeader: () => Promise<KV<string>>
+  /** 当前登录用户，未登录时为 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 {
+  registerAuth: (app: ICloudbase) => void
+  registerProvider: (name: string, provider: IProvider) => void
+}

package/types/cache.d.ts

@@ -0,0 +1,26 @@
+import { ICloudbasePlatformInfo, KV, ICloudbaseConfig } from '.'
+
+export type ICacheConfig = Pick < ICloudbaseConfig, 'debug' | 'persistence' > & {
+  platformInfo?: ICloudbasePlatformInfo;
+  keys?: KV<string>;
+  alwaysLocalKeys?: string[];
+};
+
+export interface ICloudbaseCache {
+  keys: KV<string>;
+  mode: 'async' | 'sync';
+
+  setStore: (key: string, value: any, version?: string) => void;
+  setStoreAsync: (key: string, value: any, version?: string) => Promise<void>;
+
+  getStore: (key: string, version?: string) => any;
+  getStoreAsync: (key: string, version?: string) => Promise<any>;
+
+  removeStore: (key: string) => void;
+  removeStoreAsync: (key: string) => Promise<void>;
+
+  updatePersistence?: (persistence: string) => void;
+  updatePersistenceAsync?: (persistence: string) => Promise<void>;
+
+  clear?: () => void;
+}

package/types/cloudrun.d.ts

@@ -0,0 +1,9 @@
+import { KV } from '.'
+
+export interface ICallContainerOptions {
+  name: string
+  data?: KV<any>
+  method?: string
+  path?: string
+  header?: KV<any>
+}

package/types/component.d.ts

@@ -0,0 +1,17 @@
+import { ICloudbaseEventEmitter } from './events'
+
+export interface ICloudbaseComponent {
+  name: string;
+  entity: any;
+  namespace?: string;
+  injectEvents?: {
+    bus: ICloudbaseEventEmitter,
+    events: string[];
+  };
+  IIFE?: boolean
+}
+
+export interface ICloudbaseHook {
+  entity: any;
+  target: string;
+}

package/types/container.d.ts

@@ -0,0 +1,93 @@
+import { ICloudbaseConfig } from '.'
+
+export interface IContianerConfig {
+  /**
+   * wasm sdk 地址
+   */
+  wasmUrl?: string;
+  /**
+   * js sdk 地址
+   */
+  jsUrl?:
+  | string
+  | {
+    vender?: string;
+    vm?: string;
+  };
+  /**
+   * 账号ID
+   */
+  uin: string;
+  /**
+   * 网关id
+   */
+  gatewayId: string;
+  /**
+   * 网关请求 host port
+   */
+  host: string;
+  port: string;
+  /**
+   * 是否上报数据
+   */
+  report?: boolean | object;
+  /**
+   * public key
+   */
+  publicKey?: string;
+  i18n?: ICloudbaseConfig['i18n'];
+}
+
+export interface ICallContainerOptions {
+  /**
+   * 填入业务自定义url和参数
+   * 根目录，就是 /
+   */
+  url: string;
+  /**
+   * 请求网关api子路由
+   */
+  pathname?: string;
+  /**
+   * 按照自己的业务开发，选择对应的方法
+   * @default GET
+   */
+  method?: string;
+  /**
+   * 设置请求的 header，header 中不能设置 Referer
+   */
+  header?: Record<string, string>;
+  /**
+   * 请求参数
+   */
+  data?: Object;
+  /**
+   * 超时时间，单位毫秒，默认60000
+   */
+  timeout?: number;
+  /**
+   * 超时提示细腻系
+   */
+  timeoutMsg?: string;
+
+  /**
+   * 响应 parse 类型
+   */
+  dataType?: 'json' | string;
+  /**
+   * 响应类型
+   */
+  responseType?: 'text' | 'arrayBuffer';
+  /**
+   * 是否上报数据
+   */
+  report?: boolean;
+  /**
+   * 请求 withCredentials
+   */
+  withCredentials?: boolean;
+  /**
+   * 请求是否为透明模式
+   */
+  transparent?: boolean;
+}

package/types/database.d.ts

@@ -0,0 +1,31 @@
+export type DataType = 'init' | 'update' | 'add' | 'remove' | 'replace' | 'limit'
+export type QueueType = 'init' | 'enqueue' | 'dequeue' | 'update'
+
+export interface ISingleDBEvent {
+  id: number
+  dataType: DataType
+  queueType: QueueType
+  docId: string
+  doc: Record<string, any>
+  updatedFields?: any
+  removedFields?: any
+}
+
+export interface IDatabaseServiceContext extends IServiceContext {
+  appConfig: IAppConfig
+  ws?: any
+}
+
+export interface IAppConfig {
+  docSizeLimit: number
+  realtimePingInterval: number
+  realtimePongWaitTimeout: number
+  request: any
+}
+
+export interface IServiceContext {
+  // name: string
+  // identifiers: IRuntimeIdentifiers
+  // debug: boolean
+  env?: string
+}

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/events.d.ts

@@ -0,0 +1,13 @@
+export interface Listeners {
+  [key: string]: Function[];
+}
+export interface ICloudbaseEvent {
+  name: string;
+  target: any;
+  data: any;
+}
+export interface ICloudbaseEventEmitter {
+  on(name: string, listener: Function): this;
+  off(name: string, listener: Function): this;
+  fire(event: string | ICloudbaseEvent, data?: any): this;
+}

package/types/functions.d.ts

@@ -0,0 +1,49 @@
+import { KV } from '.'
+
+export interface ICallFunctionOptions {
+  name: string
+  data?: KV<any>
+  query?: KV<any>
+  search?: string
+  parse?: boolean
+  // Used for 云函数2.0 CallContainer
+  type?: string
+  method?: string
+  path?: string
+  header?: KV<any>
+}
+
+export interface ICallFunctionResponse<T = any> {
+  requestId: string
+  /**
+   * 云函数返回值。
+   *
+   * 默认 `any` 以保持对既有调用方（直接访问 `res.result.xxx`）的**非破坏**兼容；
+   * 推荐通过泛型参数指定精确类型以获得类型安全：`callFunction<{ n: number }>(...)`。
+   */
+  result: T
+}
+
+export type ICallFunction = <T = any>(
+  options: ICallFunctionOptions,
+  callback?: (err: Error | null, res: ICallFunctionResponse<T> | null) => void,
+) => Promise<ICallFunctionResponse<T>>
+
+export interface IRetryOptions {
+  retries?: number
+  factor?: number
+  minTimeout?: number
+  maxTimeout?: number
+  randomize?: boolean
+  timeouts?: number[]
+  timeoutOps?: {
+    timeout: number
+    cb: (...args: any[]) => void
+  }
+}
+
+export interface ICustomReqOpts {
+  timeout?: number
+  retryOptions?: IRetryOptions
+  from?: 'node-sdk'
+}