# @chift/chift-nodejs 中文文档

规范地址：https://npmcn.com/package/%40chift/chift-nodejs/

版本：1\.0\.35
npm 元数据更新时间：2026-08-31T16:36:05.917Z
中文译文更新时间：2026-11-09T13:01:31.731Z
软件包许可：Apache License 2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40chift/chift-nodejs
原文对照：https://npmcn.com/package/%40chift/chift-nodejs/?lang=original
项目主页：https://github.com/chift-oneapi/chift-nodejs-sdk

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

- 包体积（解压后）：6 MB，93 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2023-09-14T11:42:21.590Z
- 最新版本发布：2026-08-31T16:36:05.688Z
- 近 30 天下载量：89624（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 8 个）

## 中文简介

Chift NodeJS库从以NodeJS语言(Javascript/Typescript)所写的应用程序中为Chift API提供方便访问.

## 安装

```sh
npm install @chift/chift-nodejs
```

也可以使用：`pnpm add @chift/chift-nodejs`、`yarn add @chift/chift-nodejs`、`bun add @chift/chift-nodejs`

## README

# Chift 节点js 图书馆

[![npm version](https://img.shields.io/npm/v/@chift/chift-nodejs)](https://www.npmjs.com/package/@chift/chift-nodejs) [![Build](https://github.com/chift-oneapi/chift-nodejs-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/chift-oneapi/chift-nodejs-sdk/actions/workflows/ci.yml) [![Coverage Status](https://coveralls.io/repos/github/chift-oneapi/chift-nodejs-sdk/badge.svg?branch=main)](https://coveralls.io/github/chift-oneapi/chift-nodejs-sdk?branch=main) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)

Chift 节点JS 库提供方便访问 Chift API 从 用节点JS语言(Javascript/Typescript)编写的应用程序.

## 文档

见 [API 文件](https://docs.chift.eu/docs/chift-api/intro)。 。 。 .

## 所需资源

节点18以上.

## 安装

以 :

```sh
npm install @chift/chift-nodejs
# or
yarn add @chift/chift-nodejs
```

## 示例

```typescript
const chift = require('@chift/chift-nodejs');
const client = new chift.API({
    clientId: process.env.CHIFT_TESTING_CLIENTID,
    clientSecret: process.env.CHIFT_TESTING_CLIENTSECRET,
    accountId: process.env.CHIFT_TESTING_ACCOUNTID,
});
const consumers = await client.Consumers.getConsumers();
// my first consumer has a POS connection
const locations = await consumers[0].pos.getLocations();
```

## 特征

### 客户端申请身份证明是否充分

SDK 支持使用 : `x-chift-client-requestid` 头曰. 这有助于防止重复创造资源。 见 [开发者指南](https://docs.chift.eu/developer-guides/advanced/idempotency#idempotency)

```typescript
// Create a client with idempotency
const client = await consumer.accounting.createClient({ name: 'Acme Corp' }, undefined, {
    clientRequestId: 'unique-request-id-123',
});

// Update a client with idempotency
const updatedClient = await consumer.accounting.updateClient(
    'client-id',
    { name: 'Acme Corporation' },
    undefined,
    { clientRequestId: 'unique-update-id-456' }
);
```

### 原始数据访问

SDK 支持使用 `rawData` 参数 :

```typescript
// Get raw data from invoices
const rawInvoices = await consumer.accounting.getInvoicesByType(
    'customer_invoice',
    {},
    { rawData: true }
);

// Get raw data from orders
const rawOrders = await consumer.ecommerce.getOrders({}, { rawData: true });
```

## 发展

### 重新生成 OpenAPI 计划

```sh
npx openapi-typescript https://api.chift.eu/openapi.json -o src/types/public-api/schema.d.ts
npx prettier --write src/types/public-api/schema.d.ts
```

将结果与已有文件相比较 。 如果没有变化,就停止.

### Schema 同步工作流程

重新生成后 `schema.d.ts`,在编辑模块前对 diff 进行分类:

-   **需要更新模块** 当添加了新的终点时, 现有的终点将被移除或重新命名, 或者在其中引用的策略类型 `src/modules` 编号 : `test/` 变化.
-   **仅更新一个计划就够了** 当修改仅限于类型、enums或没有模块引用的字段,或仅是文档/格式化.

`npm run build` 通过并不证明模块覆盖完成,但也并不意味着模块必须总是改变。 检查 diff 和 现有 模块 覆盖 以决定 .

在添加了新的公用端点后,在SDK中曝光. 当只有非破解的图案改进了土地和模块中没有任何内容引用已改变的符号时,跳过模块编辑.

用补丁版本来完成 `package.json`,一个匹配 `package-lock.json` 更新(`npm install --package-lock-only`页:1 `CHANGELOG.md` 条目( 单独) **模块** 财务报告和审定财务报表 **司马** 和成功的 `npm run build`。 。 。 .

### 模块布局

检查 `src/modules/` 以学习当前结构。 总的来说:

-   垂直 API( E)`accounting`, (中文(简体) ), `banking`, (中文(简体) ), `ecommerce`, (中文(简体) ), `invoicing`, (中文(简体) ), `payment`, (中文(简体) ), `pms`, (中文(简体) ), `pos`, (中文(简体) ), `custom`使用 a `*Factory` 模式并暴露在 `consumer.<api>`。 。 。 .
-   消费者范围管理 API(连接、每个消费者同步、数据显示) `consumer.ts`。 。 。 .
-   同步级别 API 已存在 `syncs.ts`。 。 。 .
-   其他顶级 API 有匹配文件在 `src/modules/`。 。 。 .

新的顶级模块也必须接入 `src/modules/api.ts` (进口、财产和建筑商转让) `client.<api>`。 。 。 .

遵循目标模块中的现有方法. 从方案复制精确路径 `paths` 区域 —— 不要从操作名称中猜测 URL.

### 添加路径

图书馆处理活页. 如果图中的路由参数包含 `page` 财务报告和审定财务报表 `size`,使用时 `AutoPaginatedParams<T>` 用于模块中的路由参数.

如果 `query` 参数在策略中是可选的,声明 `params` 作为模块中的可选选项。 如果需要的话,请 `params` 所需经费.

例如,在 `accounting.ts`,则 `parameters['query']` 页:1 `operations['accounting_get_analytic_plans']` 应替换为 `AutoPaginatedParams<operations['accounting_get_analytic_plans']['parameters']['query']>`。 。 。 .

自兹 `query` 是可选的, `getAnalyticPlans` 应宣布为 `getAnalyticPlans(params?: GetAnalyticPlansParams)`。 。 。 .

#### 返回类型

不要盲目复制 OpenAPI 响应类型 。 SDK运行时的形状取决于方法的接线方式:

-   **工厂方法** (单位:千美元)`*Factory`,打开 `consumer.<api>`(通过) `createApiFor` → `makeRequest`。用于标注 `GET` 列表终点, `makeRequest` 获取每页并返回 a **平面阵列** (b) 与项目有关的其他事项。 键入为 `RequestData<Item[]>` 使用页面图中的元素类型(例如). `ContactItem[]`, (中文(简体) ), **没有** `ChiftPage_ContactItem_`。与同一模块中的兄弟姐妹列表方法相比,例如 `getClients` 或者说 `getPayments`。 。 。 .
-   **直接 `InternalAPI` 方法** (单位:千美元)`consumer.ts`, (中文(简体) ), `syncs.ts`,...) 打电话 `_internalApi` 直接返回原始 API 响应。 输入它们以匹配同一文件中的兄弟姐妹方法.

工厂方法返回 `RequestData<...>` 与 `method`, (中文(简体) ), `url`,可选择 `params`, (中文(简体) ), `body`, (中文(简体) ), `rawData`,或 `clientRequestId`。 。 。 .

当为新操作添加方法时, 在 `src/types/public-api/mappings.ts`。 。 。 .

综合测试 `test/modules/` 取决于现场证书和测试环境数据。 在 schema 中断编译时将类型引用固定在那里,但不作为 schema 同步的一部分添加或运行集成测试——失败测试不是一个阻塞器.

对于之前的策略同步公关实例,请查看最近发生的触摸 `schema.d.ts` 财务报告和审定财务报表 `src/modules/`。 。 。 .

## 常见问题

### @chift/chift-nodejs 是什么？

Chift NodeJS库从以NodeJS语言\(Javascript/Typescript\)所写的应用程序中为Chift API提供方便访问\.

### 如何安装 @chift/chift-nodejs？

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

### @chift/chift-nodejs 支持 TypeScript 吗？

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

### @chift/chift-nodejs 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @chift/chift-nodejs 需要什么版本的 Node\.js？

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

### @chift/chift-nodejs 可以商用吗？

@chift/chift-nodejs 使用 Apache License 2\.0 许可。声明的许可为 Apache License 2\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @chift/chift-nodejs 的下载量有多少？

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

### @chift/chift-nodejs 还在维护吗？

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