@cloudbase/wx-cloud-client-sdk 1.8.3 → 1.8.4

package/README.md

@@ -12,31 +12,70 @@ npm install @cloudbase/wx-cloud-client-sdk
 
 ### 初始化
 
+SDK 提供两种初始化方式：
+
+#### 1. 微信云开发中使用（默认）
+
 ```javascript
 import { init } from '@cloudbase/wx-cloud-client-sdk';
 
 // 使用微信云开发实例初始化
 const client = init(wx.cloud, {
-  envId: 'your-env-id',
+  envId: 'your-env-id', // 可选，当 cloud 为 new wx.cloud.Cloud() 实例时需要提供
+});
+```
+
+#### 2. NodeJs 服务端使用
+
+```javascript
+const adapter = require('@cloudbase/adapter-node');
+const cloudbase = require('@cloudbase/js-sdk'); // 内置 @cloudbase/wx-cloud-client-sdk
+cloudbase.useAdapters(adapter);
+
+const client = cloudbase.init({
+  env,
 });
 ```
 
+初始化后，`client` 将拥有以下属性：
+
+- `client.models` - 数据模型操作接口
+- `client.mysql()` / `client.rdb()` - MySQL/RDB 数据库客户端
+- `client.auth` - 用户认证接口
+
 ### 数据模型操作
 
+数据模型提供完整的 CRUD 操作，支持生产环境 (`envType: 'prod'`) 和预发环境 (`envType: 'pre'`)。
+
 ```javascript
 // 创建数据
 const { data } = await client.models.yourModel.create({
   data: { title: 'Hello', content: 'World' },
+  envType: 'prod', // 可选，默认 'prod'
+});
+
+// 批量创建
+const { data } = await client.models.yourModel.createMany({
+  data: [
+    { title: 'Post 1', content: 'Content 1' },
+    { title: 'Post 2', content: 'Content 2' },
+  ],
 });
 
-// 查询列表
+// 查询单条数据
+const { data } = await client.models.yourModel.get({
+  filter: { where: { _id: { $eq: 'record-id' } } },
+  select: { $master: true }, // 默认包含主模型字段
+});
+
+// 查询列表（支持分页、总数）
 const {
   data: { records, total },
 } = await client.models.yourModel.list({
   filter: { where: { title: { $eq: 'Hello' } } },
   pageSize: 10,
   pageNumber: 1,
-  getCount: true,
+  getCount: true, // 获取总数
 });
 
 // 更新数据
@@ -45,18 +84,49 @@ await client.models.yourModel.update({
   filter: { where: { _id: { $eq: 'record-id' } } },
 });
 
+// 批量更新
+await client.models.yourModel.updateMany({
+  data: { status: 'published' },
+  filter: { where: { status: { $eq: 'draft' } } },
+});
+
+// 创建或更新（upsert）
+await client.models.yourModel.upsert({
+  data: { title: 'New or Updated' },
+  filter: { where: { _id: { $eq: 'record-id' } } },
+});
+
 // 删除数据
 await client.models.yourModel.delete({
   filter: { where: { _id: { $eq: 'record-id' } } },
 });
+
+// 批量删除
+await client.models.yourModel.deleteMany({
+  filter: { where: { status: { $eq: 'deleted' } } },
+});
+
+// 执行 SQL 模板
+const { data } = await client.models.yourModel.runSQLTemplate({
+  templateId: 'your-template-id',
+  parameters: { param1: 'value1' },
+});
 ```
 
 ### MySQL/RDB 数据库
 
+MySQL/RDB 客户端基于 PostgREST 风格，提供链式查询构建器。
+
+#### 获取数据库客户端
+
 ```javascript
-// 获取数据库客户端
-const mysql = client.mysql({ database: 'your-database' });
-// 或使用别名
+// 获取 MySQL 客户端（mysql 和 rdb 是别名）, 参数为可选
+const mysql = client.mysql({
+  database: 'your-database', // 数据库名，默认为环境 ID
+  instance: 'default', // 实例名，默认为 'default'
+});
+
+// 或使用 rdb 别名, 参数为可选
 const rdb = client.rdb({ database: 'your-database' });
 ```
 
@@ -69,46 +139,74 @@ const users = await mysql.from('users').select('*');
 // 查询指定字段
 const users = await mysql.from('users').select('id, name, email');
 
-// 条件查询
-const activeUsers = await mysql.from('users').select('*').eq('status', 'active');
+// 条件查询（支持 eq、neq、gt、gte、lt、lte、in、like 等）
+const activeUsers = await mysql
+  .from('users')
+  .select('*')
+  .eq('status', 'active')
+  .neq('role', 'admin')
+  .gt('age', 18)
+  .lt('age', 65)
+  .like('name', '%John%')
+  .in('id', [1, 2, 3]);
 
-// 多条件查询
+// 排序和分页
 const result = await mysql
   .from('users')
   .select('*')
   .eq('status', 'active')
   .gte('age', 18)
   .order('created_at', { ascending: false })
-  .limit(10);
+  .limit(10)
+  .range(0, 9); // 范围查询
+
+// 计数查询
+const { count } = await mysql.from('users').select('*', { count: 'exact', head: true }).eq('status', 'active');
 ```
 
 #### 插入数据
 
 ```javascript
 // 插入单条
-await mysql.from('users').insert({ name: 'test', email: 'test@example.com' });
+await mysql.from('users').insert({
+  name: 'test',
+  email: 'test@example.com',
+});
 
 // 插入多条
 await mysql.from('users').insert([
   { name: 'user1', email: 'user1@example.com' },
   { name: 'user2', email: 'user2@example.com' },
 ]);
+
+// 插入并返回数据
+const { data } = await mysql.from('users').insert({ name: 'test', email: 'test@example.com' }).select();
 ```
 
 #### 更新数据
 
 ```javascript
-await mysql.from('users').update({ status: 'inactive' }).eq('id', 1);
+// 更新并返回更新后的数据
+const { data } = await mysql.from('users').update({ status: 'inactive' }).eq('id', 1).select();
+
+// 批量更新
+await mysql.from('users').update({ status: 'inactive' }).in('id', [1, 2, 3]);
 ```
 
 #### 删除数据
 
 ```javascript
-await mysql.from('users').delete().eq('id', 1);
+// 删除并返回删除的数据
+const { data } = await mysql.from('users').delete().eq('id', 1).select();
+
+// 批量删除
+await mysql.from('users').delete().in('id', [1, 2, 3]);
 ```
 
 ### 用户认证
 
+认证模块提供微信小程序 OpenID 静默登录和用户信息管理。在 NodeJs 端提供更多的登录方式，参考[JS SDK 文档](https://docs.cloudbase.net/api-reference/webv3/authentication)。
+
 ```javascript
 // 获取 auth 实例
 const auth = client.auth;
@@ -116,19 +214,24 @@ const auth = client.auth;
 // 微信小程序 OpenID 静默登录，用户不存在则注册成外部注册用户
 await auth.signInWithOpenId();
 
-// 更新用户信息
+// 更新用户信息（昵称、性别等）
 const { data, error } = await auth.updateUser({
   nickname: '新昵称',
   gender: 'MALE',
 });
 
 // 更新 email 或 phone（需要验证）
-const { data, error } = await app.auth.updateUser({
+const { data, error } = await auth.updateUser({
   email: 'new@example.com',
 });
 
-// 调用 verifyOtp 回调验证
-await data.verifyOtp({ email: 'new@example.com', token: '123456' });
+// 调用 verifyOtp 回调验证邮箱/手机
+if (data?.verifyOtp) {
+  await data.verifyOtp({
+    email: 'new@example.com',
+    token: '123456',
+  });
+}
 
 // 获取当前用户信息
 const { data, error } = await auth.getUser();
@@ -136,35 +239,31 @@ const { data, error } = await auth.getUser();
 // 获取登录状态
 const { data, error } = auth.getSession();
 
-// 登出
-await auth.signOut();
-
 // 刷新登录状态
 await auth.refreshSession();
+
+// 登出
+await auth.signOut();
 ```
 
-## API
+## API 参考
 
-### init(cloud, options)
+### 初始化函数
 
-初始化 SDK（使用云函数调用）。
+#### `init(cloud, options)`
 
-| 参数          | 类型              | 必填 | 说明           |
-| ------------- | ----------------- | ---- | -------------- |
-| cloud         | CloudBaseInstance | 是   | 微信云开发实例 |
-| options.envId | string            | 否   | 环境 ID        |
+使用云函数调用初始化 SDK。
 
-### 认证方法
-
-- `signInWithOpenId()` - 微信小程序 OpenID 静默登录，用户不存在则注册成外部注册用户
-- `updateUser(params)` - 更新用户信息
-- `getUser()` - 获取当前用户信息
-- `getSession()` - 获取登录状态
-- `refreshSession()` - 刷新登录状态
-- `signOut()` - 登出
+| 参数            | 类型                | 必填 | 说明                                                       |
+| --------------- | ------------------- | ---- | ---------------------------------------------------------- |
+| cloud           | `CloudBaseInstance` | 是   | 微信云开发实例                                             |
+| options.envId   | `string`            | 否   | 环境 ID，当 cloud 为 `new wx.cloud.Cloud()` 实例时需要提供 |
+| options.adapter | `CloudbaseAdapter`  | 否   | 自定义适配器                                               |
 
 ### 数据模型方法
 
+所有数据模型方法都支持 `envType` 参数（可选，默认 `'prod'`），用于指定操作环境（`'prod'` 或 `'pre'`）。
+
 - `create(params)` - 创建单条数据
 - `createMany(params)` - 批量创建数据
 - `update(params)` - 更新单条数据
@@ -173,10 +272,82 @@ await auth.refreshSession();
 - `delete(params)` - 删除单条数据
 - `deleteMany(params)` - 批量删除数据
 - `get(params)` - 获取单条数据
-- `list(params)` - 获取数据列表
+- `list(params)` - 获取数据列表（支持分页、过滤、排序）
 - `runSQLTemplate(params)` - 执行 SQL 模板
 
+### MySQL/RDB 方法
+
+#### 查询构建器方法
+
+- `from(tableName)` - 指定表名
+- `select(columns, options)` - 选择字段（支持 `count: 'exact'` 等选项）
+- `eq(column, value)` - 等于
+- `neq(column, value)` - 不等于
+- `gt(column, value)` - 大于
+- `gte(column, value)` - 大于等于
+- `lt(column, value)` - 小于
+- `lte(column, value)` - 小于等于
+- `like(column, pattern)` - LIKE 匹配
+- `ilike(column, pattern)` - ILIKE 不区分大小写匹配
+- `in(column, values)` - IN 查询
+- `is(column, value)` - IS 查询（如 `is('deleted_at', null)`）
+- `or(filters)` - OR 条件
+- `not(filter)` - NOT 条件
+- `order(column, options)` - 排序（`{ ascending: boolean }`）
+- `limit(count)` - 限制返回条数
+- `range(start, end)` - 范围查询
+- `insert(data)` - 插入数据
+- `update(data)` - 更新数据
+- `delete()` - 删除数据
+
+### 认证方法
+
+- `signInWithOpenId()` - 微信小程序 OpenID 静默登录，用户不存在则注册成外部注册用户
+- `updateUser(params)` - 更新用户信息（返回可能包含 `verifyOtp` 回调）
+- `getUser()` - 获取当前用户信息
+- `getSession()` - 获取登录状态
+- `refreshSession()` - 刷新登录状态
+- `signOut()` - 登出
+
+## 类型声明
+
+SDK 提供完整的 TypeScript 类型定义。使用时可以导入相关类型：
+
+```typescript
+import type {
+  CloudBaseInstance,
+  ExtendedCloudBaseInstance,
+  OrmClient,
+  Auth,
+  IMySqlOptions,
+} from '@cloudbase/wx-cloud-client-sdk';
+```
+
+## 错误处理
+
+SDK 使用统一的错误类型 `WxCloudSDKError`，包含错误码、请求 ID 和原始错误信息。
+
+```javascript
+try {
+  await client.models.yourModel.create({ data: {} });
+} catch (error) {
+  if (error.code === 'NotSupported') {
+    // 处理不支持的操作
+  }
+  console.error('Request ID:', error.requestId);
+  console.error('Original error:', error.originError);
+}
+```
+
+## 环境支持
+
+- **生产环境** (`envType: 'prod'`) - 默认环境，操作生产数据
+- **预发环境** (`envType: 'pre'`) - 用于测试，操作预发数据
+
+可以在每个数据模型操作中通过 `envType` 参数指定环境。
+
 ## 参考文档
 
 - [初始化 SDK](https://docs.cloudbase.net/model/init-sdk)
 - [类型声明](https://docs.cloudbase.net/model/sdk-reference/globals)
+- [微信云开发文档](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/getting-started.html)

package/lib/auth/index.d.ts

@@ -1,4 +1,6 @@
 import { CloudBaseInstance, Auth } from '../types';
+import type { CloudbaseAdapter } from '@cloudbase/adapter-interface';
 export declare const generateAuthClient: (cloud: CloudBaseInstance, options?: {
     envId?: string;
-}) => Auth;
+    adapter?: CloudbaseAdapter;
+}) => Auth | null;

package/lib/index.d.ts

@@ -2,6 +2,7 @@ import { CloudBaseInstance, ExtendedCloudBaseInstance, IMySqlOptions, OrmClient
 import { generateHTTPClient } from './orm/http-orm-client';
 import { MySqlClient } from './db/mysql';
 import { Fetch } from './db/postgrest/types';
+import type { CloudbaseAdapter } from '@cloudbase/adapter-interface';
 export { getAccessToken } from './utils';
 export declare function initHTTPOverCallFunction(cloud: CloudBaseInstance, options?: {
     envId?: string;
@@ -11,6 +12,7 @@ export declare function initHTTPOverCallFunction(cloud: CloudBaseInstance, optio
 }): ExtendedCloudBaseInstance;
 export declare function init(cloud: CloudBaseInstance, options?: {
     envId?: string;
+    adapter?: CloudbaseAdapter;
 }): ExtendedCloudBaseInstance;
 declare function generateMySQLClient(cloud: CloudBaseInstance, options?: {
     envId?: string;

package/lib/types/index.d.ts

@@ -714,7 +714,7 @@ export interface RunMysqlCommandParams {
  */
 export type CloudBaseInstance = {
     callFunction: CallFunction;
-    auth: Auth;
+    auth: Auth | null;
 };
 export type IMySqlClient = (options?: IMySqlOptions) => MySqlClient;
 export interface Auth {
@@ -733,7 +733,7 @@ export interface ExtendedCloudBaseInstance extends CloudBaseInstance {
     models: OrmClient & OrmRawQueryClient;
     mysql: IMySqlClient;
     rdb: IMySqlClient;
-    auth: Auth;
+    auth: Auth | null;
 }
 /**
  * 云函数调用方法定义。