# @cloudbase/wx-cloud-client-sdk

> wx cloud client sdk

Latest version **1.8.11** (published 2026-10-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cloudbase/wx-cloud-client-sdk
pnpm add @cloudbase/wx-cloud-client-sdk
yarn add @cloudbase/wx-cloud-client-sdk
bun add @cloudbase/wx-cloud-client-sdk
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.8.11 |
| Published | 2026-10-05 |
| First published | 2024-06-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 323.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | starkwang, yhyang, binggg, fengkx, liuyanjie, justan, woodenstone, miusuncle, yuzhen, wedabot, joeyren, byronpiao, yandrewding, areo-joe, coylexie, lukejyhuang |
| Keywords | typescript, javascript |

## Links

- npm: https://www.npmjs.com/package/@cloudbase/wx-cloud-client-sdk
- npm.io page: https://npm.io/package/@cloudbase/wx-cloud-client-sdk

## Dependencies (2)

- [core-js-pure](https://npm.io/package/core-js-pure.md) ^3.45.0
- [@cloudbase/adapter-wx_mp](https://npm.io/package/@cloudbase/adapter-wx_mp.md) ^1.2.1

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.8.11 (latest) — 2026-10-05
- 1.8.6-beta.1 (beta) — 2026-04-08
- 1.8.10 — 2026-07-17
- 1.8.9 — 2026-07-02
- 1.8.8 — 2026-04-27
- 1.8.7 — 2026-04-27
- 1.8.6-beta.0 — 2026-04-08
- 1.8.6 — 2026-03-26
- 1.8.5 — 2026-02-26
- 1.8.4 — 2026-01-28
- 1.8.3 — 2026-01-27
- 1.8.2 — 2026-01-27
- 1.8.1 — 2026-01-26
- 1.8.0 — 2026-01-26
- 1.7.2 — 2025-11-17
- … 15 more at https://npm.io/package/@cloudbase/wx-cloud-client-sdk/versions

## README

# @cloudbase/wx-cloud-client-sdk

微信云开发客户端 SDK，提供数据模型、MySQL/RDB 数据库和用户认证能力。

## 安装

```bash
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', // 可选，当 wx.cloud 为 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, // 获取总数
});

// 更新数据
await client.models.yourModel.update({
  data: { title: 'Updated' },
  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
// 获取 MySQL 客户端（mysql 和 rdb 是别名）, 参数为可选
const mysql = client.mysql({
  database: 'your-database', // 数据库名，默认为环境 ID
  instance: 'default', // 实例名，默认为 'default'
});

// 或使用 rdb 别名, 参数为可选
const rdb = client.rdb({ database: 'your-database' });
```

#### 查询数据

```javascript
// 查询所有字段
const users = await mysql.from('users').select('*');

// 查询指定字段
const users = await mysql.from('users').select('id, name, email');

// 条件查询（支持 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)
  .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: '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
// 更新并返回更新后的数据
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
// 删除并返回删除的数据
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;

// 微信小程序 OpenID 静默登录，用户不存在则注册成外部注册用户
await auth.signInWithOpenId();

// 更新用户信息（昵称、性别等）
const { data, error } = await auth.updateUser({
  nickname: '新昵称',
  gender: 'MALE',
});

// 更新 email 或 phone（需要验证）
const { data, error } = await auth.updateUser({
  email: 'new@example.com',
});

// 调用 verifyOtp 回调验证邮箱/手机
if (data?.verifyOtp) {
  await data.verifyOtp({
    email: 'new@example.com',
    token: '123456',
  });
}

// 获取当前用户信息
const { data, error } = await auth.getUser();

// 获取登录状态
const { data, error } = auth.getSession();

// 刷新登录状态
await auth.refreshSession();

// 登出
await auth.signOut();
```

## API 参考

### 初始化函数

#### `init(cloud, options)`

使用云函数调用初始化 SDK。

| 参数            | 类型                | 必填 | 说明                                                       |
| --------------- | ------------------- | ---- | ---------------------------------------------------------- |
| cloud           | `CloudBaseInstance` | 是   | 微信云开发实例                                             |
| options.envId   | `string`            | 否   | 环境 ID，当 cloud 为 `new wx.cloud.Cloud()` 实例时需要提供 |
| options.adapter | `CloudbaseAdapter`  | 否   | 自定义适配器                                               |

### 数据模型方法

所有数据模型方法都支持 `envType` 参数（可选，默认 `'prod'`），用于指定操作环境（`'prod'` 或 `'pre'`）。

- `create(params)` - 创建单条数据
- `createMany(params)` - 批量创建数据
- `update(params)` - 更新单条数据
- `updateMany(params)` - 批量更新数据
- `upsert(params)` - 创建或更新数据
- `delete(params)` - 删除单条数据
- `deleteMany(params)` - 批量删除数据
- `get(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)

---
_Source: https://npm.io/package/@cloudbase/wx-cloud-client-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
