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

package/types/index.d.ts

@@ -0,0 +1,269 @@
+import { CloudbaseAdapter, SDKAdapterInterface, ResponseObject } from '@cloudbase/adapter-interface'
+import { ICloudbaseComponent, ICloudbaseHook } from './component'
+import { ICloudbaseRequest } from './request'
+import { ICloudbaseCache } from './cache'
+import { ICloudbaseAuth } from './auth'
+import { ICallFunctionOptions, ICallFunctionResponse } from './functions'
+import {
+  ICloudbaseUploadFileParams,
+  ICloudbaseUploadFileResult,
+  ICloudbaseDeleteFileParams,
+  ICloudbaseDeleteFileResult,
+  ICloudbaseGetTempFileURLParams,
+  ICloudbaseGetTempFileURLResult,
+  ICloudbaseDownloadFileParams,
+  ICloudbaseDownloadFileResult,
+  ICloudbaseCopyFileParams,
+  ICloudbaseCopyFileResult,
+} 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',
+}
+
+export type Persistence = 'local' | 'session' | 'none'
+
+export interface KV<T> {
+  [key: string]: T
+}
+
+export interface KVstring {
+  [key: string]: string
+}
+
+export type EndPointKey = 'CLOUD_API' | 'GATEWAY'
+
+/** 自定义登录凭证信息（从控制台下载的私钥文件） */
+export interface ICredentialsInfo {
+  /** 私钥 ID */
+  private_key_id: string;
+  /** RSA 私钥内容 */
+  private_key: string;
+  /** 所属环境 ID */
+  env_id: string;
+}
+
+export interface ICloudbaseConfig {
+  env: string
+  intl?: boolean,
+  region?: string
+  timeout?: number
+  persistence?: Persistence
+  oauthClient?: any
+  debug?: boolean
+  _fromApp?: ICloudbase
+  clientId?: string
+  oauthInstance?: any
+  wxCloud?: any
+  i18n?: {
+    t: (text: string) => string
+    LANG_HEADER_KEY: string
+    lang: LANGS
+  }
+  accessKey?: string
+  endPointMode?: EndPointKey // auth请求域名模式，默认CLOUD_API
+  useWxCloud?: boolean // 是否使用微信云开发链路
+  auth?: {
+    detectSessionInUrl?: boolean
+    secretId?: string
+    secretKey?: string
+    sessionToken?: string
+    secretType?: 'SESSION_SECRET' | 'SECRET'
+    credentials?: ICredentialsInfo // 自定义登录私钥信息，node端使用
+  }
+  // @cloudbase/functions-framework 函数上下文，只要求部分字段，只在云函数或云托管中有效
+  context?: Readonly<{
+    eventID: string
+    extendedContext?: {
+      envId: string // 环境 ID
+      // uin: string             // 请求的 UIN
+      source: string // 请求来源，如 wx
+      accessToken?: string // 调用请求时的 AccessToken
+      userId?: string // 请求的用户 ID
+      tmpSecret?: {
+        // 临时凭证
+        secretId: string // secretId
+        secretKey: string // secretKey
+        token: string // token
+      }
+    }
+  }>
+}
+// 可更新的配置字段
+export type ICloudbaseUpgradedConfig = Pick<ICloudbaseConfig, 'persistence' | 'region' | 'debug'>
+
+export interface ICloudbaseExtension {
+  name: string
+  invoke: (opts: any, app: ICloudbase) => Promise<any>
+}
+
+declare type MethodType = 'request' | 'post' | 'get' | 'head' | 'patch' | 'delete' | 'put'
+export interface ICloudbaseApis {
+  [apiName: string]: {
+    [method in MethodType]: (callApiOptions: ICallApiOptions, opts?: KV<any>) => Promise<ResponseObject['data']>
+  }
+}
+
+/**
+ * Cloudbase 核心能力（始终存在，与运行时是否注册某个业务组件无关）。
+ *
+ * 这些字段/方法由 SDK 初始化流程直接提供，因此**不是可选的**。
+ * 业务能力（auth / functions / storage / database / ai / models / mysql 等）
+ * 被拆分到独立的 `*Capability` 接口，通过下面的 `ICloudbase` 交叉类型组合。
+ */
+export interface CloudbaseCore {
+  config: ICloudbaseConfig
+  platform: ICloudbasePlatformInfo
+  cache: ICloudbaseCache
+  request: ICloudbaseRequest
+  oauthClient: any
+  localCache: ICloudbaseCache
+  authInstance?: ICloudbaseAuth
+  oauthInstance?: any
+  apis: ICloudbaseApis
+  init: (config: ICloudbaseConfig & { lang?: LANGS }) => cloudbase.app
+  updateConfig: (config: ICloudbaseUpgradedConfig) => void
+  registerExtension: (ext: ICloudbaseExtension) => void
+  invokeExtension: (name: string, opts: any) => Promise<any>
+  useAdapters: (adapters: CloudbaseAdapter | CloudbaseAdapter[], options?: any) => void
+  registerComponent: (component: ICloudbaseComponent) => void
+  registerHook: (hook: ICloudbaseHook) => void
+  registerVersion: (version: string) => void
+  fire?: (...args: any[]) => void
+  updateLang?: (lang: LANGS) => void
+  /**
+   * 检查当前 Cloudbase 实例是否已完成初始化
+   * @returns 是否已初始化
+   */
+  isInitialized?: () => boolean
+  getEndPointWithKey?: (key: EndPointKey) => {
+    BASE_URL: string
+    PROTOCOL: string
+  }
+}
+
+/** 身份鉴权能力（`registerAuth` 注册后可用）。 */
+export interface AuthCapability {
+  auth?: (options?: { persistence: cloudbase.auth.Persistence }) => cloudbase.auth.App
+}
+
+/** 云函数能力（`registerFunctions` 注册后可用）。 */
+export interface FunctionsCapability {
+  /** 调用云函数 */
+  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
+  /** 上传文件 */
+  uploadFile?: (params: ICloudbaseUploadFileParams, callback?: Function) => Promise<ICloudbaseUploadFileResult>
+  /** 下载文件 */
+  downloadFile?: (params: ICloudbaseDownloadFileParams, callback?: Function) => Promise<ICloudbaseDownloadFileResult>
+  /** 删除云端文件 */
+  deleteFile?: (params: ICloudbaseDeleteFileParams, callback?: Function) => Promise<ICloudbaseDeleteFileResult>
+  /** 获取文件临时下载链接 */
+  getTempFileURL?: (params: ICloudbaseGetTempFileURLParams, callback?: Function) => Promise<ICloudbaseGetTempFileURLResult>
+  /** 复制/移动文件 */
+  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 端适配器扩展方法
+ */
+export interface INodeAdapterExtend {
+  /**
+   * 从环境变量中获取腾讯云临时密钥信息
+   * 用于 API 请求签名
+   */
+  getSecretInfo?: (config?: ICloudbaseConfig) => {
+    env: string
+    secretId: string
+    secretKey: string
+    sessionToken: string
+    accessKey: string
+    secretType: string
+    credentials?: string
+  }
+  /**
+   * 初始化 Node.js 端工具方法，挂载到 js-sdk app 实例上
+   * 包含：auth 相关方法、模板消息推送、context 解析
+   */
+  nodeTool?: (
+    /** js-sdk cloudbase 实例 */
+    app: any,
+    /** 配置信息，包含认证凭证和环境 ID */
+    config: ICloudbaseConfig,
+  ) => void
+}
+export interface ICloudbasePlatformInfo {
+  adapter?: SDKAdapterInterface & INodeAdapterExtend
+  runtime?: string
+}
+
+export interface IGenericError<T extends string, P = any> extends Error {
+  type: T
+  payload: P
+  generic: boolean
+}
+
+export interface ICallApiOptions {
+  /** api标识 */
+  name?: string
+  /** 请求的path */
+  path?: string
+  method?: string
+  headers?: KV<any>
+  /** 请求体，根据content-type可以是不同类型 */
+  body?: KV<any> | string
+  token?: string
+}

package/types/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@cloudbase/types",
+  "version": "4.0.1-alpha.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",
+    "auth.d.ts",
+    "component.d.ts",
+    "functions.d.ts",
+    "cloudrun.d.ts",
+    "container.d.ts",
+    "analytics.d.ts",
+    "storage.d.ts",
+    "realtime.d.ts",
+    "database.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TencentCloudBase/cloudbase-js-sdk"
+  },
+  "keywords": [
+    "cloudbase",
+    "Cloudbase",
+    "CloudBase",
+    "tcb",
+    "TCB",
+    "serverless",
+    "Serverless",
+    "javascript",
+    "typescript"
+  ],
+  "author": "",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cloudbase/adapter-interface": "^0.7.1"
+  },
+  "gitHead": "859557576897d4778857c12fb8d7fe8ca1f3a052"
+}

package/types/realtime.d.ts

@@ -0,0 +1,350 @@
+import { DataType, QueueType, ISingleDBEvent } from './database'
+
+export type IRequestMsgType =
+  | 'LOGIN' // 鉴权（环境维度）
+  | 'INIT_WATCH' // 初始化监听
+  | 'REBUILD_WATCH' // 重建监听，1）数据失序时 2）checkLast 不一致时
+  | 'CHECK_LAST' // 检查是否有未收到的消息
+  | 'CLOSE_WATCH' // 取消监听
+  | 'PING' // 心跳 ping
+
+export type IResponseMsgType =
+  | 'LOGIN_RES' // LOGIN 回包
+  | 'INIT_EVENT' // INIT_WATCH 回包
+  | 'NEXT_EVENT' // 服务端主动推变更事件
+  | 'CHECK_EVENT' // CHECK_LAST 回包
+  | 'PONG' // 心跳 PING 回包
+  | 'ERROR' // 错误异常
+
+export interface IRequestMessageBase<W extends boolean = true> {
+  watchId: W extends true ? string : undefined
+  requestId: string
+  msgType: IRequestMsgType
+  msgData: IRequestMessageMsgData
+}
+
+export type IRequestMessageMsgData =
+  | IRequestMessageInitWatchData
+  | IRequestMessageLoginData
+  | IRequestMessageRebuildWatchData
+  | IRequestMessageCheckLastData
+  | IRequestMessageCloseWatchData
+  | IRequestMessagePingData
+
+export type IRequestMessage =
+  | IRequestMessageInitWatchMsg
+  | IRequestMessageLoginMsg
+  | IRequestMessageRebuildWatchMsg
+  | IRequestMessageCheckLastMsg
+  | IRequestMessageCloseWatchMsg
+  | IRequestMessagePingMsg
+
+export interface IRequestMessageLoginData {
+  envId: string
+  accessToken: string
+  referrer: 'web'
+  sdkVersion: string
+  dataVersion: string
+}
+
+export interface IRequestExtraMessageLoginData {
+  runtime: string
+  signStr: string
+  secretVersion: string
+}
+export interface IRequestMessageLoginMsg extends IRequestMessageBase<false> {
+  msgType: 'LOGIN'
+  msgData: IRequestMessageLoginData
+  exMsgData?: IRequestExtraMessageLoginData
+}
+
+export interface IRequestMessageInitWatchData {
+  envId: string
+  collName: string // collection name
+  query: string // query that is stringified
+  limit?: number
+  orderBy?: Record<string, string>
+}
+
+export interface IRequestMessageInitWatchMsg extends IRequestMessageBase {
+  msgType: 'INIT_WATCH'
+  msgData: IRequestMessageInitWatchData
+}
+
+export interface IRequestMessageRebuildWatchData {
+  envId: string
+  collName: string
+  queryID: string
+  eventID: number
+}
+
+export interface IRequestMessageRebuildWatchMsg extends IRequestMessageBase {
+  msgType: 'REBUILD_WATCH'
+  msgData: IRequestMessageRebuildWatchData
+}
+
+export interface IRequestMessageCheckLastData {
+  queryID: string
+  eventID: number
+}
+
+export interface IRequestMessageCheckLastMsg extends IRequestMessageBase {
+  msgType: 'CHECK_LAST'
+  msgData: IRequestMessageCheckLastData
+}
+
+export type IRequestMessageCloseWatchData = null
+
+export interface IRequestMessageCloseWatchMsg extends IRequestMessageBase {
+  msgType: 'CLOSE_WATCH'
+  msgData: IRequestMessageCloseWatchData
+}
+
+export type IRequestMessagePingData = null
+
+export interface IRequestMessagePingMsg extends IRequestMessageBase<false> {
+  msgType: 'PING'
+  msgData: IRequestMessagePingData
+}
+
+// export interface IResponseMessageBase {
+
+export interface IResponseMessageBase<W extends boolean = true> {
+  watchId: W extends true ? string : undefined
+  // watchId: string
+  requestId: string
+  msgType: IResponseMsgType
+  msgData: IResponseMessageMsgData
+}
+
+export type IResponseMessageMsgData =
+  | IResponseMessageLoginResData
+  | IResponseMessageInitEventData
+  | IResponseMessageNextEventData
+  | IResponseMessageCheckEventData
+  | IResponseMessagePongData
+  | IResponseMessageErrorData
+
+export type IResponseMessage =
+  | IResponseMessageLoginResMsg
+  | IResponseMessageInitEventMsg
+  | IResponseMessageNextEventMsg
+  | IResponseMessageCheckEventMsg
+  | IResponseMessagePongMsg
+  | IResponseMessageErrorMsg
+
+export type IResponseMessageLoginResData = {
+  envId: string
+} & Partial<IResponseMessageErrorData>
+
+export interface IResponseMessageLoginResMsg
+  extends IResponseMessageBase<false> {
+  msgType: 'LOGIN_RES'
+  msgData: IResponseMessageLoginResData
+}
+
+export interface IResponseMessageInitEventData {
+  queryID: string
+  currEvent: number
+  events: IDBEvent[]
+}
+
+export interface IResponseMessageInitEventMsg extends IResponseMessageBase {
+  msgType: 'INIT_EVENT'
+  msgData: IResponseMessageInitEventData
+}
+
+export interface IResponseMessageNextEventData {
+  queryID: string
+  currEvent: number
+  events: IDBEvent[]
+}
+
+export interface IResponseMessageNextEventMsg extends IResponseMessageBase {
+  msgType: 'NEXT_EVENT'
+  msgData: IResponseMessageNextEventData
+}
+
+export interface IResponseMessageCheckEventData {
+  queryID: string
+  currEvent: number
+}
+
+export interface IResponseMessageCheckEventMsg extends IResponseMessageBase {
+  msgType: 'CHECK_EVENT'
+  msgData: IResponseMessageCheckEventData
+}
+
+export type IResponseMessagePongData = null
+
+export interface IResponseMessagePongMsg extends IResponseMessageBase {
+  msgType: 'PONG'
+  msgData: IResponseMessagePongData
+}
+
+export type IResponseMessageErrorData = {
+  message: string
+} & (
+  | { code: 'SYS_ERR' } // 服务器系统错误
+  | { code: 'CHECK_LOGIN_FAILED' } // 登陆校验失败
+  | { code: 'SIGN_INVALID_ERROR' } // ws签名无效
+  | { code: 'SIGN_EXPIRED_ERROR' } // 签名过期
+  | { code: 'INVALIID_ENV' } // 环境无效
+  | { code: 'SIGN_PARAM_INVALID' } // cam签名无效
+  | { code: 'COLLECTION_PERMISSION_DENIED' } // 没有集合操作权限
+  | { code: 'QUERYID_INVALID_ERROR' }) // queryID 无效
+
+export interface IResponseMessageErrorMsg extends IResponseMessageBase {
+  msgType: 'ERROR'
+  msgData: IResponseMessageErrorData
+}
+
+export type IDBEvent = IDBInitEvent | IDBNextEvent
+
+export interface IDBEventBase {
+  ID: number // event id
+  DataType: DataType
+  QueueType: QueueType
+  DocID: string
+  Doc: string
+}
+
+export interface IDBInitEvent extends IDBEventBase {
+  DataType: 'init'
+  QueueType: 'init'
+  UpdatedFields?: any
+  removedFields?: any
+}
+
+// <DataType, QueueType>
+// * <update, update>
+// * <update, enqueue>
+// * <update, dequeue>
+// * <add, enqueue>
+// * <remove, dequeue>
+
+// export interface IDBNextEvent extends IDBEventBase {
+//   DocID: string
+//   Doc: string
+//   UpdatedFields?: any
+//   removedFields?: any
+// }
+
+export type IDBNextEvent =
+  | IDBNextEventDataUpdate
+  | IDBNextEventDataReplace
+  | IDBNextEventDataAdd
+  | IDBNextEventDataRemove
+  | IDBNextEventDataLimit
+
+export type IDBNextEventDataUpdate =
+  | IDBNextEventDataUpdateQueueUpdate
+  | IDBNextEventDataUpdateQueueEnqueue
+  | IDBNextEventDataUpdateQueueDequeue
+
+export type IDBNextEventDataReplace =
+  | IDBNextEventDataReplaceQueueUpdate
+  | IDBNextEventDataReplaceQueueEnqueue
+  | IDBNextEventDataReplaceQueueDequeue
+
+export type IDBNextEventDataLimit =
+  | IDBNextEventDataLimitQueueEnqueue
+  | IDBNextEventDataLimitQueueDequeue
+
+export interface IDBNextEventDataUpdateQueueUpdate extends IDBEventBase {
+  DataType: 'update'
+  QueueType: 'update'
+  Doc: ''
+  UpdatedFields: string
+  RemovedFields: string
+}
+
+export interface IDBNextEventDataUpdateQueueEnqueue extends IDBEventBase {
+  DataType: 'update'
+  QueueType: 'enqueue'
+  Doc: string // full doc
+  UpdatedFields: string
+  RemovedFields: string
+}
+
+export interface IDBNextEventDataUpdateQueueDequeue extends IDBEventBase {
+  DataType: 'update'
+  QueueType: 'dequeue'
+  Doc: ''
+  UpdatedFields: string
+  RemovedFields: string
+}
+
+export interface IDBNextEventDataReplaceQueueUpdate extends IDBEventBase {
+  DataType: 'replace'
+  QueueType: 'update'
+  Doc: string
+  UpdatedFields: ''
+  RemovedFields: ''
+}
+
+export interface IDBNextEventDataReplaceQueueEnqueue extends IDBEventBase {
+  DataType: 'replace'
+  QueueType: 'enqueue'
+  Doc: string
+  UpdatedFields: ''
+  RemovedFields: ''
+}
+
+export interface IDBNextEventDataReplaceQueueDequeue extends IDBEventBase {
+  DataType: 'replace'
+  QueueType: 'dequeue'
+  Doc: string
+  UpdatedFields: ''
+  RemovedFields: ''
+}
+
+export interface IDBNextEventDataAdd extends IDBEventBase {
+  DataType: 'add'
+  QueueType: 'enqueue'
+}
+
+export interface IDBNextEventDataRemove extends IDBEventBase {
+  DataType: 'remove'
+  QueueType: 'dequeue'
+  Doc: ''
+}
+
+export interface IDBNextEventDataLimitQueueEnqueue extends IDBEventBase {
+  DataType: 'limit'
+  QueueType: 'enqueue'
+  Doc: string
+  UpdatedFields: ''
+  RemovedFields: ''
+}
+
+export interface IDBNextEventDataLimitQueueDequeue extends IDBEventBase {
+  DataType: 'limit'
+  QueueType: 'dequeue'
+  Doc: ''
+  UpdatedFields: ''
+  RemovedFields: ''
+}
+
+export interface IWatchOptions {
+  // server realtime data init & change event
+  onChange: (snapshot: ISnapshot) => void
+  // error while connecting / listening
+  onError: (error: any) => void
+}
+
+export interface ISnapshot {
+  id: number
+  docChanges: ISingleDBEvent[]
+  docs: Record<string, any>
+  type?: SnapshotType
+}
+
+export interface DBRealtimeListener {
+  // "And Now His Watch Is Ended"
+  close: () => void
+}
+
+export type IRealtimeListenerConstructorOptions = IWatchOptions
+
+export type SnapshotType = 'init'

package/types/request.d.ts

@@ -0,0 +1,30 @@
+import {
+  IFetchOptions,
+  IRequestOptions, IUploadRequestOptions, ResponseObject,
+} from '@cloudbase/adapter-interface'
+
+import { ICloudbaseConfig, KV } from '.'
+
+export interface IGetAccessTokenResult {
+  accessToken: string;
+  accessTokenExpire: number;
+}
+
+export type ICloudbaseRequestConfig = Pick<ICloudbaseConfig, 'env' | 'region' | 'timeout' | 'oauthClient' | '_fromApp' | 'i18n' | 'endPointMode' | 'auth'>;
+
+export interface IAppendedRequestInfo {
+  data: KV<any>;
+  headers: KV<string>;
+}
+export type IRequestBeforeHook = (...args: any[]) => IAppendedRequestInfo;
+export interface ICloudbaseRequest {
+  // fetch: (urlOrPath: string, init?: RequestInit) => Promise<Response>;
+  post: (options: IRequestOptions) => Promise<ResponseObject>;
+  upload: (options: IUploadRequestOptions) => Promise<ResponseObject>;
+  download: (options: IRequestOptions) => Promise<ResponseObject>;
+  // refreshAccessToken: () => Promise<IGetAccessTokenResult>;
+  // getAccessToken: () => Promise<IGetAccessTokenResult>;
+  request: (action: string, params: KV<any>, options?: KV<any>) => Promise<ResponseObject>;
+  send: (action: string, data: KV<any>) => Promise<any>;
+  fetch: (options: IFetchOptions) => Promise<ResponseObject>;
+}