# @capawesome/cloud-sdk 中文文档

规范地址：https://npmcn.com/package/%40capawesome/cloud-sdk/

版本：0\.1\.7
npm 元数据更新时间：2026-10-04T14:57:29.861Z
中文译文更新时间：2026-11-09T05:38:16.717Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/cloud-sdk
原文对照：https://npmcn.com/package/%40capawesome/cloud-sdk/?lang=original
项目主页：https://github.com/capawesome-team/cloud-node#readme
源码仓库：https://github.com/capawesome-team/cloud-node

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：241 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：0 个
- 首次发布：2026-06-02T07:21:42.959Z
- 最新版本发布：2026-10-04T14:57:29.533Z
- 近 30 天下载量：6336（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

节点js SDK 为Capawesome Cloud API.

## 安装

```sh
npm install @capawesome/cloud-sdk
```

也可以使用：`pnpm add @capawesome/cloud-sdk`、`yarn add @capawesome/cloud-sdk`、`bun add @capawesome/cloud-sdk`

## README

# @ capawesome/ cloud- sdk

[![npm version](https://img.shields.io/npm/v/@capawesome/cloud-sdk)](https://www.npmjs.com/package/@capawesome/cloud-sdk) [![npm downloads](https://img.shields.io/npm/dm/@capawesome/cloud-sdk)](https://www.npmjs.com/package/@capawesome/cloud-sdk) [![license](https://img.shields.io/npm/l/@capawesome/cloud-sdk)](https://github.com/capawesome-team/cloud-node/blob/main/LICENSE)

节点.js SDK [云雾](https://capawesome.io/cloud/) API (英语).

它为管理组织、应用软件、现场更新频道和部署、本土建筑、应用商店目的地等提供了一个完全打入的、基于承诺的界面.

> **说明:** Capawesome Cloud API仍在开发中,可能会不经通知而改变. 反应类型故意只暴露最相关的属性来尽量减少断裂变化.

## SDKs 软件

卡帕韦斯克云API的官方SDKs:

| 语言 | 软件包 | 仓库 |
| --- | --- | --- |
| 节点.js | [`@capawesome/cloud-sdk`](https://www.npmjs.com/package/@capawesome/cloud-sdk) | [云节点](https://github.com/capawesome-team/cloud-node) |
| 蟒 | [`capawesome-cloud`](https://pypi.org/project/capawesome-cloud/) | [云鹏](https://github.com/capawesome-team/cloud-python) |

## 安装

```bash
npm install @capawesome/cloud-sdk
```

**所需经费:** 节点.js 20.19 或后. 该软件包仅作为无害环境管理发布,但也可通过CommonJS加载 `require()`。 。 。 .

## 开始

在其中创建 API 令牌 [彩云控制台](https://console.cloud.capawesome.io/settings/tokens) 并传递给客户:

```ts
import { CapawesomeCloud } from '@capawesome/cloud-sdk';

const client = new CapawesomeCloud({
  token: process.env.CAPAWESOME_TOKEN!,
});

const apps = await client.apps.list({ organizationId: process.env.CAPAWESOME_ORGANIZATION_ID! });
console.log(apps);
```

### 配置

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `token` | `string` | —— 说 | API 令牌用于认证. |
| `baseUrl` | `string` | `https://api.cloud.capawesome.io` | API的基础URL(用于自宿/测试). |
| `timeout` | `number` | `60000` | 请求超时, 以毫秒计 。 不适用于流媒体下载. |
| `maxRetries` | `number` | `3` | 暂时性故障(网络、, `429`, (中文(简体) ), `5xx`) 依一能所请. |
| `fetch` | `typeof fetch` | `globalThis.fetch` | 这个 `fetch` 用于所有请求的执行. |

## 使用量

所有方法都取出一个单一的选项对象并返回一个打出的承诺. 大多数操作都通过 `appId`。 。 。 .

### 组织

```ts
const organizations = await client.organizations.list();
const organization = await client.organizations.get({ organizationId });
const members = await client.organizations.members.list({ organizationId });

// Invite a new member
await client.organizations.invitations.create({
  organizationId,
  email: 'jane@example.com',
  role: 'member',
});

// Group apps and members in a team
const team = await client.organizations.teams.create({ organizationId, name: 'Mobile' });
await client.organizations.teams.apps.create({ organizationId, teamId: team.id, appId });
```

### 应用程序

```ts
const apps = await client.apps.list({ organizationId });
const app = await client.apps.get({ appId });
const created = await client.apps.create({ name: 'My App', type: 'capacitor' });
await client.apps.update({ appId, name: 'Renamed App' });
await client.apps.delete({ appId });
```

### 实时更新

```ts
// Create a channel
const channel = await client.apps.channels.create({ appId, name: 'production' });

// Pause / resume a channel
await client.apps.channels.pause({ appId, channelId: channel.id });
await client.apps.channels.resume({ appId, channelId: channel.id });
```

### 部署

促进一个构建到一个频道(实时更新)或一个目的地(应用程序商店发布):

```ts
// Roll out a live update to half of the devices on a channel
await client.apps.deployments.create({
  appId,
  appBuildId,
  appChannelName: 'production',
  rolloutPercentage: 0.5,
});

// Publish a native build to an app store with localized release notes
await client.apps.deployments.create({
  appId,
  appBuildId,
  appDestinationName: 'Google Play',
  releaseNotes: {
    default: 'Bug fixes and performance improvements.',
    'de-DE': 'Fehlerbehebungen und Leistungsverbesserungen.',
  },
});
```

### Git 仓库

原生建筑由寄存器创建,一个应用程序链接到:

```ts
const [connection] = await client.organizations.gitConnections.list({ organizationId });
const repositories = await client.organizations.gitConnections.listRepositories({
  organizationId,
  gitConnectionId: connection.id,
});

await client.apps.repository.set({
  appId,
  gitConnectionId: connection.id,
  path: repositories[0].path,
});
```

### 原始建筑

```ts
const build = await client.apps.builds.create({
  appId,
  platform: 'ios',
  gitRef: 'main',
});

// Poll the job that processes the build
let job = await client.jobs.get({ jobId: build.jobId! });
while (job.status === 'queued' || job.status === 'pending' || job.status === 'in_progress') {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  job = await client.jobs.get({ jobId: job.id });
}

const logs = await client.jobs.getLogs({ jobId: job.id });

// Explain a failure
if (job.status === 'failed') {
  const { summary } = await client.jobs.getFailureSummary({ jobId: job.id });
  console.error(summary);
}
```

#### 建造文物

二进制下载返回 a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) 所以大文件可以被流到磁盘中而不缓冲内存中的所有内容:

```ts
import { Writable } from 'node:stream';
import { createWriteStream } from 'node:fs';

const stream = await client.apps.builds.artifacts.download({ appId, buildId, artifactId });
await stream.pipeTo(Writable.toWeb(createWriteStream('artifact.ipa')));
```

您也可以获得一个签名的,有时间限制的下载 URL :

```ts
const { url, expiresAt } = await client.apps.builds.artifacts.getSignedDownloadUrl({
  appId,
  buildId,
  artifactId,
});
```

#### 证书

```ts
import { readFile } from 'node:fs/promises';

const certificate = await client.apps.certificates.create({
  appId,
  name: 'Distribution Certificate',
  platform: 'ios',
  type: 'production',
  file: await readFile('distribution.p12'),
  fileName: 'distribution.p12',
  password: process.env.CERT_PASSWORD,
});
```

#### 环境、 秘密和变量

```ts
const environment = await client.apps.environments.create({ appId, name: 'production' });

await client.apps.environments.secrets.create({
  appId,
  environmentId: environment.id,
  key: 'API_KEY',
  value: process.env.API_KEY!,
});

await client.apps.environments.variables.create({
  appId,
  environmentId: environment.id,
  key: 'API_URL',
  value: 'https://api.example.com',
});
```

## 现有资源

资源映射API的路径等级. 应用范围的资源被嵌入 `client.apps.*`资源 `client.organizations.*`;顶级资源直接被曝光在客户端上.

| 资源 | 说明 |
| --- | --- |
| `client.apps` | 创建,读取,更新,删除并传输应用程序. |
| `client.apps.channels` | 管理实时更新频道(包括暂停/重播). |
| `client.apps.deployments` | 向渠道或目的地推广. |
| `client.apps.builds` | 触发并管理本土建筑. |
| `client.apps.builds.artifacts` | 列出并下载建设文物. |
| `client.apps.buildSources` | 注册和下载本地建筑源. |
| `client.apps.certificates` | 管理签名证书 . |
| `client.apps.destinations` | 管理应用商店出版目的地. |
| `client.apps.environments` | 管理环境,秘密和变量. |
| `client.apps.automations` | 管理构建自动化. |
| `client.apps.devices` | 管理已注册的设备 . |
| `client.apps.webhooks` | 管理 app webhoks . |
| `client.apps.configurations` | 管理本地应用程序配置 . |
| `client.apps.repository` | 链接一个应用程序到 Git 仓库 . |
| `client.organizations` | 创建、阅读和更新组织. |
| `client.organizations.members` | 管理组织成员. |
| `client.organizations.invitations` | 请用户到一个组织. |
| `client.organizations.teams` | 管理团队及其应用程序和成员. |
| `client.organizations.licenseKeys` | 管理内幕软件包的许可证密钥 . |
| `client.organizations.gitConnections` | 管理 Git 连接并浏览仓库 . |
| `client.jobs` | 检查背景工作及其日志. |
| `client.users` | 访问认证用户 . |

## 处理错误

任何非-2xx响应都被抛出 `CapawesomeCloudError`数字 :

```ts
import { CapawesomeCloudError } from '@capawesome/cloud-sdk';

try {
  await client.apps.get({ appId: 'unknown' });
} catch (error) {
  if (error instanceof CapawesomeCloudError) {
    console.error(error.status); // 404
    console.error(error.message); // "App not found."
    console.error(error.body); // { message: "App not found." }
  }
}
```

## 发展

### 设置

清除寄存器并安装依赖性 :

```bash
npm install
```

这也设置了 Git 钩子(通过 [胡斯基](https://typicode.github.io/husky)),它运行在每一次承诺之前的已上演的文件上. 开发过程中的常见脚本 :

| 脚本 | 说明 |
| --- | --- |
| `npm run build` | 将软件包构建为 `dist/` 与tsdown。 与tsdown. |
| `npm run dev` | 改变时重建( 监视模式) . |
| `npm run typecheck` | 在不排放输出的情况下检查类型 . |
| `npm run lint` | 检查格式和线条 . |
| `npm run fmt` | 自动固定格式化和插件问题. |

### 测试

测试用 [维特](https://vitest.dev/) 并生活在一个 `test/` 目录 :

```bash
npm test          # run the suite once
npm run test:watch # re-run on change
```

### 出版

释放是自动的 [释放请](https://github.com/googleapis/release-please),从中生成下一个版本和更改日志条目 [常规武器委员会](https://www.conventionalcommits.org/)。 。 。 .

每一次推进 `main`,则 [发布工作流程](https://npmcn.com/package/%40capawesome/cloud-sdk/.github/workflows/release.yml) 创建或更新使版本与更新相撞的释放拉出请求 `CHANGELOG.md`。将拉出请求合并后创建了 git 标记和 GitHub 发布,并将软件包发布到 npm .

## 许可证

见 [自由主义](https://npmcn.com/package/%40capawesome/cloud-sdk/LICENSE)。 。 。 .

## 常见问题

### @capawesome/cloud-sdk 是什么？

节点js SDK 为Capawesome Cloud API\.

### 如何安装 @capawesome/cloud-sdk？

在项目目录运行 npm install @capawesome/cloud-sdk，或使用 pnpm add / yarn add / bun add。

### @capawesome/cloud-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capawesome/cloud-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @capawesome/cloud-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @capawesome/cloud-sdk 可以商用吗？

@capawesome/cloud-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/cloud-sdk 的下载量有多少？

根据 npm 官方下载统计，@capawesome/cloud-sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 6,336 次，日均约 211 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capawesome/cloud-sdk 还在维护吗？

最新版本 0\.1\.7 发布于 2026/10/04（1 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/06/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。