@cloudbase/app 2.26.0 → 2.26.2

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@cloudbase/app",
-  "version": "2.26.0",
+  "version": "2.26.2",
   "description": "cloudbase javascript sdk core",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
+  "exports": {
+    ".": {
+      "node": {
+        "import": "./dist/esm/index.node.js",
+        "require": "./dist/cjs/index.node.js"
+      },
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "tsc": "rm -rf dist/ && tsc -p tsconfig.esm.json && tsc -p tsconfig.json",
     "lint": "eslint --fix \"./src/**/*.ts\"",
@@ -31,8 +43,24 @@
   "dependencies": {
     "@cloudbase/adapter-interface": "^0.7.1",
     "@cloudbase/adapter-wx_mp": "^1.3.1",
-    "@cloudbase/types": "2.26.0",
-    "@cloudbase/utilities": "2.26.0"
+    "@cloudbase/types": "2.26.2",
+    "@cloudbase/utilities": "2.26.2"
+  },
+  "peerDependencies": {
+    "@cloudbase/signature-nodejs": ">=1.0.0",
+    "jsonwebtoken": ">=8.0.0",
+    "ws": "^8.18.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudbase/signature-nodejs": {
+      "optional": true
+    },
+    "jsonwebtoken": {
+      "optional": true
+    },
+    "ws": {
+      "optional": true
+    }
   },
-  "gitHead": "48764fb5aa33114d65b3607ab97cc95be3f558cc"
+  "gitHead": "af397dd45339057868b98ac09c417d352e56a217"
 }

package/src/index.node.ts

@@ -0,0 +1,22 @@
+/**
+ * Node.js 入口
+ * 引用 base 模块的全部导出，并额外加载 Node adapter
+ */
+import cloudbase from './index'
+
+export { getBaseEndPoint } from './constants/common'
+export { LANGS } from './libs/lang'
+export type { Cloudbase } from './index'
+export { cloudbase }
+
+// Node 环境下加载 Node adapter
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+  const nodeAdapter = require('./libs/adapter-node').default
+  cloudbase.useAdapters(nodeAdapter)
+} catch (error) {
+  throw error
+}
+
+// 默认导出实例
+export default cloudbase

package/src/index.ts

@@ -101,24 +101,31 @@ class Cloudbase implements ICloudbase {
     ],
   })
   public init(config: ICloudbaseConfig & { lang?: LANGS }): Cloudbase {
+    config.endPointMode = config.endPointMode || 'CLOUD_API'
+
+    // 初始化时若未兼容平台，则使用默认adapter
+    if (!Platform.adapter) {
+      this.useDefaultAdapter()
+    }
+
+    // 在判断config.env之前，先处理node环境的配置
+    config = this.dealNodeAdapterConfig(config)
+
     if (!config.env) {
       throw new Error(JSON.stringify({
         code: ERRORS.INVALID_PARAMS,
         msg: 'env must not be specified',
       }),)
     }
-    // config.endPointMode = config.endPointMode || 'GATEWAY'
 
-    // 初始化时若未兼容平台，则使用默认adapter
-    if (!Platform.adapter) {
-      this.useDefaultAdapter()
-    }
+    this.isInitialized(config)
 
-    const reqConfig: IRequestConfig = {
-      timeout: config.timeout || 5000,
+    const reqConfig: IRequestConfig & { auth: ICloudbaseConfig['auth'] } = {
+      timeout: config.timeout || 15000,
       timeoutMsg: `[${getSdkName()}][REQUEST TIMEOUT] request had been abort since didn't finished within${
         config.timeout / 1000
       }s`,
+      auth: config.auth,
     }
 
     this.requestClient = new Platform.adapter.reqClass(reqConfig)
@@ -148,12 +155,18 @@ class Cloudbase implements ICloudbase {
       _fromApp: app,
       i18n,
       endPointMode: config.endPointMode,
+      auth: config.auth,
     })
     app.requestClient = this.requestClient
     ;(this as any)?.fire?.('cloudbase_init', app)
 
     this.try2InitAuth(app)
 
+    // node环境可以从adapter获取nodeTool的方法
+    if (Platform.adapter?.nodeTool) {
+      Platform.adapter?.nodeTool(app, this.cloudbaseConfig)
+    }
+
     return app
   }
 
@@ -218,6 +231,43 @@ class Cloudbase implements ICloudbase {
     setSdkName(name)
   }
 
+  /**
+   * 检查当前 Cloudbase 实例是否已完成初始化
+   *
+   * @example
+   * ```javascript
+   * import cloudbase from '@cloudbase/js-sdk'
+   *
+   * // 初始化前
+   * console.log(cloudbase.isInitialized()) // false
+   *
+   * const app = cloudbase.init({ env: 'your-env-id' })
+   *
+   * // 初始化后
+   * console.log(app.isInitialized()) // true
+   * ```
+   *
+   * @returns {boolean} 是否已初始化
+   */
+  public isInitialized(config = this.cloudbaseConfig): boolean {
+    // 检测常见占位符 env 值，在开发阶段给出友好提示
+    const PLACEHOLDER_PATTERNS = [
+      'your-env-id', 'your-envid', 'your_env_id',
+      'xxx-yyy', 'xxxx-yyy', 'envId', 'env-id',
+      'your-environment-id', 'REPLACE_ME',
+    ]
+    if (PLACEHOLDER_PATTERNS.some(p => config.env.toLowerCase() === p.toLowerCase())) {
+      printWarn(
+        ERRORS.INVALID_PARAMS,
+        `[CloudBase] 检测到环境 ID "${config.env}" 可能是占位符，请替换为真实的环境 ID。\n`
+        + '  获取方式：登录腾讯云开发平台 → 环境管理 → 环境设置 → 环境 ID\n'
+        + '  建议通过环境变量配置：process.env.CLOUDBASE_ENV 或 import.meta.env.VITE_CLOUDBASE_ENV',
+      )
+    }
+
+    return !!(config?.env)
+  }
+
   /** 设置 tcb api 的 endpoint */
   public registerEndPoint(url: string, protocol?: 'http' | 'https') {
     setEndPointInfo({ baseUrl: url, protocol, env: this.config.env, endPointKey: 'CLOUD_API' })
@@ -273,6 +323,40 @@ class Cloudbase implements ICloudbase {
       console.log('try2InitAuth error:', error)
     }
   }
+
+  /**
+   * 处理 Node 环境下 adapter 的配置信息
+   * 在 Node 环境中，通过 adapter 自动获取密钥、环境ID、accessKey 等配置，
+   * 减少用户手动传入配置的负担
+   * @param config - 云开发初始化配置对象
+   * @returns 补充了 Node adapter 信息后的配置对象
+   */
+  private dealNodeAdapterConfig(config: ICloudbaseConfig) {
+    // node环境可以从adapter获取默认的secretId和secretKey
+    if (typeof process !== 'undefined' && typeof process.env !== 'undefined' && !process.env.IS_BROWSER_BUILD && Platform.adapter?.getSecretInfo) {
+      const secretInfo = Platform.adapter?.getSecretInfo(config)
+      // 将 adapter 提供的密钥信息写入 config.auth
+      config.auth = {
+        ...config.auth,
+        secretId: secretInfo.secretId,
+        secretKey: secretInfo.secretKey,
+        sessionToken: secretInfo.sessionToken,
+        secretType: secretInfo.secretType as any,
+      }
+
+      // node 环境可能可以从上下文获取env，用户未显式指定时自动填充
+      if (!config.env) {
+        config.env = secretInfo.env
+      }
+
+      // node adapter环境能读取到 process.env.CLOUDBASE_APIKEY 时，在没有传入accessKey时，使用 node adapter 提供的 accessKey（process.env.CLOUDBASE_APIKEY）
+      if (!config.accessKey && secretInfo.accessKey) {
+        config.accessKey = secretInfo.accessKey
+      }
+    }
+
+    return config
+  }
 }
 
 // 类型导出

package/src/libs/adapter-node/constants.ts

@@ -0,0 +1,42 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+/** 统一错误码定义 */
+export const ERROR = {
+  INVALID_PARAM: {
+    code: 'INVALID_PARAM',
+    message: 'invalid param',
+  },
+  SYS_ERR: {
+    code: 'SYS_ERR',
+    message: 'system error',
+  },
+  STORAGE_REQUEST_FAIL: {
+    code: 'STORAGE_REQUEST_FAIL',
+    message: 'storage request fail',
+  },
+  STORAGE_FILE_NONEXIST: {
+    code: 'STORAGE_FILE_NONEXIST',
+    message: 'storage file not exist',
+  },
+  TCB_CLS_UNOPEN: {
+    code: 'TCB_CLS_UNOPEN',
+    message: '需要先开通日志检索功能',
+  },
+  INVALID_CONTEXT: {
+    code: 'INVALID_CONTEXT',
+    message: '无效的context对象，请使用 云函数入口的context参数',
+  },
+}
+
+/** 管理端 API 路径，用于替换 /web 路径（需要密钥签名时） */
+export const ADMIN_PATH = '/admin'
+
+/** 管理端获取客户端凭证 access_token，为管理员权限 */
+export const CLIENT_AUTH_PATH = '/auth/v1/token/clientCredential'
+
+/** 自定义用户 ID 校验规则：4~32 位，允许字母、数字及部分特殊字符 */
+export const checkCustomUserIdRegex = /^[a-zA-Z0-9_\-#@~=*(){}[\]:.,<>+]{4,32}$/
+
+export enum SECRET_TYPE {
+  'SECRET' = 'SECRET',
+  'SESSION_SECRET' = 'SESSION_SECRET',
+}

package/src/libs/adapter-node/context.ts

@@ -0,0 +1,238 @@
+/* eslint-disable import/no-mutable-exports */
+/* eslint-disable @typescript-eslint/naming-convention */
+/* eslint-disable no-restricted-syntax */
+import { ERROR, SECRET_TYPE } from './constants'
+import { checkIsInScf, getEnv } from './utils'
+import type { IContextParam, ICompleteCloudbaseContext } from './types'
+import { ICloudbaseConfig } from '@cloudbase/types'
+
+/**
+ * 解析并校验云函数入口的 Context 参数
+ * 将下划线命名的字段转为驼峰格式，并解析环境变量
+ *
+ * @param context - 云函数入口传入的 context 对象
+ * @returns 解析后的上下文对象，包含 environment（新架构）或 environ（老架构）
+ * @throws INVALID_CONTEXT - context 不是对象或解析失败时
+ */
+export function parseContext(context: IContextParam) {
+  if (typeof context !== 'object') {
+    throw { ...ERROR.INVALID_CONTEXT, message: 'context 必须为对象类型' }
+  }
+
+  const parseResult: any = {}
+
+  const {
+    memory_limit_in_mb,
+    time_limit_in_ms,
+    request_id,
+    function_version,
+    namespace,
+    function_name,
+
+    environ,
+    environment,
+  } = context
+
+  try {
+    parseResult.memoryLimitInMb = memory_limit_in_mb
+    parseResult.timeLimitIns = time_limit_in_ms
+    parseResult.requestId = request_id
+    parseResult.functionVersion = function_version
+    parseResult.namespace = namespace
+    parseResult.functionName = function_name
+
+    if (environment) {
+      // 新架构：environment 为 JSON 字符串，直接解析
+      parseResult.environment = JSON.parse(environment)
+    } else {
+      // TODO: 考虑移除老架构的兼容逻辑
+      // 老架构：environ 为分号分隔的 key=value 字符串
+      // 存在 bug：value 含特殊字符时可能影响解析
+      const parseEnviron: any = environ?.split(';')
+      const parseEnvironObj: any = {}
+
+      // eslint-disable-next-line @typescript-eslint/no-for-in-array
+      for (const i in parseEnviron) {
+        if (parseEnviron[i].includes('=')) {
+          // 只按第一个 = 切割，保留 value 中的 =
+          const equalIndex = parseEnviron[i].indexOf('=')
+          const key = parseEnviron[i].slice(0, equalIndex)
+          let value: any = parseEnviron[i].slice(equalIndex + 1)
+
+          // value 含逗号时视为数组
+          if (value.indexOf(',') >= 0) {
+            value = value.split(',')
+          }
+          parseEnvironObj[key] = value
+        }
+      }
+
+      parseResult.environ = parseEnvironObj
+    }
+  } catch (_err: any) {
+    throw { ...ERROR.INVALID_CONTEXT }
+  }
+
+  return parseResult
+}
+
+/**
+ * 获取当前云函数内的所有环境变量
+ * 统一从 process.env 和 context 两个来源合并取值
+ *
+ * 取值优先级：context > process.env
+ * 通过 TCB_CONTEXT_KEYS / WX_CONTEXT_KEYS 动态扩展需要读取的环境变量列表
+ *
+ * @param context - 可选，云函数入口的 context 参数
+ * @returns 合并后的完整环境变量上下文
+ */
+export const getCloudbaseContext = (context?: IContextParam): ICompleteCloudbaseContext => {
+  // 云函数环境下校验必要环境变量
+  if (checkIsInScf()) {
+    if (!getEnv('TENCENTCLOUD_REGION')) {
+      console.error('[TCB][ERROR] missing `TENCENTCLOUD_REGION` environment')
+    }
+    if (!getEnv('SCF_NAMESPACE')) {
+      console.error('[TCB][ERROR] missing `SCF_NAMESPACE` environment')
+    }
+  }
+
+  // 第一步：从 process.env 读取基础环境变量
+  const envObj = getEnv()
+  const envFromProcessEnv: any = {
+    TRIGGER_SRC: envObj.TRIGGER_SRC,
+    _SCF_TCB_LOG: envObj._SCF_TCB_LOG,
+    SCF_NAMESPACE: envObj.SCF_NAMESPACE,
+    TENCENTCLOUD_RUNENV: envObj.TENCENTCLOUD_RUNENV,
+    TENCENTCLOUD_SECRETID: envObj.TENCENTCLOUD_SECRETID,
+    TENCENTCLOUD_SECRETKEY: envObj.TENCENTCLOUD_SECRETKEY,
+    TENCENTCLOUD_SESSIONTOKEN: envObj.TENCENTCLOUD_SESSIONTOKEN,
+    WX_CONTEXT_KEYS: envObj.WX_CONTEXT_KEYS,
+    WX_TRIGGER_API_TOKEN_V0: envObj.WX_TRIGGER_API_TOKEN_V0,
+    WX_CLIENTIP: envObj.WX_CLIENTIP,
+    WX_CLIENTIPV6: envObj.WX_CLIENTIPV6,
+    TCB_CONTEXT_KEYS: envObj.TCB_CONTEXT_KEYS,
+    TCB_CONTEXT_CNFG: envObj.TCB_CONTEXT_CNFG,
+    LOGINTYPE: envObj.LOGINTYPE,
+  }
+
+  // 第二步：从 context 中解析环境变量
+  let envFromContext: any = {}
+  if (context) {
+    const { environment, environ } = parseContext(context)
+    envFromContext = environment || environ || {}
+  }
+
+  // 第三步：根据 CONTEXT_KEYS 动态扩展变量列表（优先取 context 中的值）
+  const tcbContextKeys = envFromContext.TCB_CONTEXT_KEYS || envObj.TCB_CONTEXT_KEYS
+  const wxContextKeys = envFromContext.WX_CONTEXT_KEYS || envObj.WX_CONTEXT_KEYS
+
+  if (tcbContextKeys) {
+    try {
+      const tcbKeysList = tcbContextKeys.split(',')
+      for (const item of tcbKeysList) {
+        envFromProcessEnv[item] = envFromContext[item] || getEnv(item)
+      }
+    } catch (_e) {
+      //
+    }
+  }
+
+  if (wxContextKeys) {
+    try {
+      const wxKeysList = wxContextKeys.split(',')
+      for (const item of wxKeysList) {
+        envFromProcessEnv[item] = envFromContext[item] || getEnv(item)
+      }
+    } catch (_e) {
+      //
+    }
+  }
+
+  // 第四步：合并所有来源，context 的值覆盖 process.env，过滤 undefined
+  const allContext = { ...envFromProcessEnv, ...envFromContext }
+
+  const finalContext: any = {}
+  for (const key in allContext) {
+    if (allContext[key] !== undefined) {
+      finalContext[key] = allContext[key]
+    }
+  }
+
+  return finalContext
+}
+
+/** 缓存 extendedContext，供其他模块读取（如 tool.ts 中获取 userId） */
+export let INIT_CONFIG: ICloudbaseConfig = {} as unknown as ICloudbaseConfig
+
+/**
+ * 从环境变量中获取腾讯云临时密钥信息
+ * 用于 API 请求签名
+ */
+export const getSecretInfo = (config?: ICloudbaseConfig) => {
+  INIT_CONFIG = JSON.parse(JSON.stringify(config || {}))
+
+  const { TCB_ENV, SCF_NAMESPACE } = getCloudbaseContext()
+
+  let env = config?.env || TCB_ENV || SCF_NAMESPACE || ''
+  const defaultInfo = {
+    env,
+    secretId: '',
+    secretKey: '',
+    sessionToken: '',
+    accessKey: '',
+    secretType: '',
+  }
+
+  if (config?.accessKey) {
+    return defaultInfo
+  }
+
+  if (config?.auth?.secretId && config?.auth?.secretKey) {
+    return {
+      ...defaultInfo,
+      secretId: config.auth.secretId,
+      secretKey: config.auth.secretKey,
+      secretType: SECRET_TYPE.SECRET,
+    }
+  }
+
+  const secretEnv = getEnv()
+  const { TENCENTCLOUD_SECRETID } = secretEnv
+  const { TENCENTCLOUD_SECRETKEY } = secretEnv
+  const { TENCENTCLOUD_SESSIONTOKEN } = secretEnv
+  const { CLOUDBASE_APIKEY } = secretEnv
+
+  if (CLOUDBASE_APIKEY) {
+    return {
+      ...defaultInfo,
+      accessKey: CLOUDBASE_APIKEY,
+    }
+  }
+
+  if (TENCENTCLOUD_SECRETID && TENCENTCLOUD_SECRETKEY) {
+    return {
+      ...defaultInfo,
+      secretId: TENCENTCLOUD_SECRETID,
+      secretKey: TENCENTCLOUD_SECRETKEY,
+      sessionToken: TENCENTCLOUD_SESSIONTOKEN || '',
+      secretType: SECRET_TYPE.SESSION_SECRET,
+    }
+  }
+
+  if (config?.context?.extendedContext) {
+    const { extendedContext } = config.context
+    if (!env) {
+      env = extendedContext.envId || ''
+    }
+
+    return {
+      ...defaultInfo,
+      secretId: extendedContext?.tmpSecret?.secretId || '',
+      secretKey: extendedContext?.tmpSecret?.secretKey || '',
+      sessionToken: extendedContext?.tmpSecret?.token || '',
+    }
+  }
+
+  return { ...defaultInfo }
+}

package/src/libs/adapter-node/index.ts

@@ -0,0 +1,166 @@
+/* eslint-disable prefer-destructuring */
+/* eslint-disable @typescript-eslint/naming-convention */
+import {
+  SDKAdapterInterface,
+  StorageInterface,
+  StorageType,
+  WebSocketContructor as WebSocketConstructor,
+} from '@cloudbase/adapter-interface'
+
+import { NodeRequest } from './request'
+import { nodeTool } from './tool'
+import { getSecretInfo } from './context'
+import { parseQueryString } from './utils'
+import { ICloudbaseConfig } from '@cloudbase/types'
+
+// ws 延迟加载，避免非 Node 环境打包时引入
+let _WS: any = null
+function getWS() {
+  if (!_WS) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+      _WS = require('ws')
+    } catch (e) {
+      throw new Error('缺少依赖 ws，请执行以下命令安装：\n\n'
+        + '  npm install ws\n\n'
+        + '该依赖用于 Node 环境下的 WebSocket 连接。',)
+    }
+  }
+  return _WS
+}
+
+// Re-export for external consumers
+export { NodeRequest } from './request'
+export { parseQueryString, createWebStreamFromNodeReadableStream } from './utils'
+export type {
+  ICreateTicketOpts,
+  IGetUserInfoResult,
+  IGetEndUserInfoResult,
+  IUserInfoQuery,
+  IContextParam,
+  ICompleteCloudbaseContext,
+} from './types'
+
+/**
+ * 环境匹配检测：判断当前运行环境是否为 Node.js
+ * SDK 通过此方法决定是否使用当前 adapter
+ */
+function isMatch(): boolean {
+  // eslint-disable-next-line eqeqeq
+  return typeof process !== 'undefined' && process.versions != null && process.versions.node != null
+}
+
+/**
+ * 基于 Map 的内存存储实现
+ * Node.js 环境下无浏览器 Storage API，使用内存 Map 模拟
+ */
+const storage: StorageInterface = (() => {
+  const db = new Map()
+  return {
+    mode: 'sync',
+    setItem(key, value) {
+      db.set(key, value)
+    },
+    getItem(key) {
+      return db.get(key)
+    },
+    removeItem(key) {
+      db.delete(key)
+    },
+    clear() {
+      db.clear()
+    },
+  }
+})()
+
+/**
+ * 生成 Node.js 环境的 SDK Adapter
+ * 组装请求类、存储、WebSocket、认证等能力
+ *
+ * @param options - 配置项，包含 EventBus（用于验证码回调）
+ * @returns SDK Adapter 实例
+ */
+function genAdapter(options: any) {
+  const adapter: SDKAdapterInterface & {
+    getSecretInfo: (config?: ICloudbaseConfig) => {
+      env: string
+      secretId: string
+      secretKey: string
+      sessionToken: string
+      accessKey: string
+      secretType: string
+    }
+    nodeTool: (app: any, config: ICloudbaseConfig) => void
+  } = {
+    nodeTool,
+    getSecretInfo,
+    root: { globalThis: {} },
+    reqClass: NodeRequest,
+    wsClass: getWS() as WebSocketConstructor,
+    sessionStorage: storage,
+    localStorage: storage,
+    primaryStorage: StorageType.session,
+    captchaOptions: {
+      /**
+       * 验证码处理回调
+       * 解析 data: URI 中的验证码参数，通过 EventBus 通知业务层
+       * 等待业务层返回验证结果后 resolve
+       */
+      openURIWithCallback: (_url: string) => {
+        const { EventBus } = options
+        let queryObj: Record<string, string | string[]> = {}
+        let url = _url
+
+        // 从 data: URI 中提取查询参数
+        const matched = _url.match(/^(data:.*?)(\?[^#\s]*)?$/)
+        if (matched) {
+          url = matched[1]
+          const search = matched[2]
+          if (search) {
+            queryObj = parseQueryString(search)
+          }
+        }
+
+        const { token, ...restQueryObj } = queryObj
+
+        // data: 协议但无 token，视为无效验证码数据
+        if (/^data:/.test(url) && !token) {
+          return Promise.reject({
+            error: 'invalid_argument',
+            error_description: `invalie captcha data: ${_url}`,
+          })
+        }
+        if (!token) {
+          return Promise.reject({
+            error: 'unimplemented',
+            error_description: 'need to impl captcha data',
+          })
+        }
+
+        return new Promise((resolve) => {
+          // 通知业务层展示验证码
+          EventBus.$emit('CAPTCHA_DATA_CHANGE', {
+            ...restQueryObj,
+            token,
+            url,
+          })
+
+          // 等待业务层返回验证结果
+          EventBus.$once('RESOLVE_CAPTCHA_DATA', (res: { captcha_token: string; expires_in: number }) => {
+            resolve(res)
+          })
+        })
+      },
+    },
+  }
+  return adapter
+}
+
+/** Node.js Adapter 入口导出 */
+const adapter = {
+  genAdapter,
+  isMatch,
+  runtime: 'node-adapter',
+}
+
+export default adapter