# @abby-inc/node 中文文档

规范地址：https://npmcn.com/package/%40abby-inc/node/

版本：2\.9\.0
npm 元数据更新时间：2026-11-04T14:42:20.726Z
中文译文更新时间：2026-11-08T01:43:24.333Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：4.3 MB，91 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13\.0
- 运行依赖：1 个
- 首次发布：2025-12-26T23:14:12.358Z
- 最新版本发布：2026-11-04T14:42:20.184Z
- 近 30 天下载量：1932（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

节点Js, Bun, 和 Abby API 的 Deno 库

## 安装

```sh
npm install @abby-inc/node
```

也可以使用：`pnpm add @abby-inc/node`、`yarn add @abby-inc/node`、`bun add @abby-inc/node`

## README

# 艾比·节点js, Bun & Deno SDK

[![npm version](https://img.shields.io/npm/v/@abby-inc/node.svg)](https://www.npmjs.com/package/@abby-inc/node) [![npm downloads](https://img.shields.io/npm/dm/@abby-inc/node.svg)](https://www.npmjs.com/package/@abby-inc/node) [![CI](https://github.com/abby-inc/abby-node/actions/workflows/ci.yml/badge.svg)](https://github.com/abby-inc/abby-node/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/abby-inc/abby-node/branch/master/graph/badge.svg?token=51rRlQV05f)](https://codecov.io/gh/abby-inc/abby-node) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

官方Node.js、Bun和Deno图书馆 [艾比・API](https://abby.fr/)Abby是自由职业者和微型企业的全能企业管理平台.

## 目录

-   [安装](https://npmcn.com/package/%40abby-inc/node/#readme-installation)
-   [所需资源](https://npmcn.com/package/%40abby-inc/node/#readme-requirements)
-   [使用量](https://npmcn.com/package/%40abby-inc/node/#readme-usage)
    -   [初始化](https://npmcn.com/package/%40abby-inc/node/#readme-initialization)
    -   [服务](https://npmcn.com/package/%40abby-inc/node/#readme-services)
    -   [基本示例](https://npmcn.com/package/%40abby-inc/node/#readme-basic-example)
    -   [配置](https://npmcn.com/package/%40abby-inc/node/#readme-configuration)
    -   [自定义获取代理支持( P)](https://npmcn.com/package/%40abby-inc/node/#readme-custom-fetch--proxy-support)
    -   [处理错误](https://npmcn.com/package/%40abby-inc/node/#readme-error-handling)
    -   [活动听众](https://npmcn.com/package/%40abby-inc/node/#readme-event-listeners)
    -   [截取器](https://npmcn.com/package/%40abby-inc/node/#readme-interceptors)
    -   [原始请求](https://npmcn.com/package/%40abby-inc/node/#readme-raw-requests)
-   [验证](https://npmcn.com/package/%40abby-inc/node/#readme-validation)
    -   [自动验证](https://npmcn.com/package/%40abby-inc/node/#readme-automatic-validation)
    -   [使用 Zod Schemas 直接](https://npmcn.com/package/%40abby-inc/node/#readme-using-zod-schemas-directly)
-   [类型脚本支持](https://npmcn.com/package/%40abby-inc/node/#readme-typescript-support)
-   [版本](https://npmcn.com/package/%40abby-inc/node/#readme-versioning)
-   [发展](https://npmcn.com/package/%40abby-inc/node/#readme-development)
-   [支助](https://npmcn.com/package/%40abby-inc/node/#readme-support)
-   [许可证](https://npmcn.com/package/%40abby-inc/node/#readme-license)

## 安装

使用您的首选软件包管理器安装软件包 :

```bash
npm install @abby-inc/node
# or
yarn add @abby-inc/node
# or
pnpm add @abby-inc/node
# or
bun add @abby-inc/node
```

对于 Deno, 您可以直接从 npm 导入 :

```typescript
import Abby from 'npm:@abby-inc/node';
```

## 所需资源

-   节点js 22.13.0或以上(CI:22,24,26),Bun 1.0.0或以上,或Deno 2.0.0或以上
-   一个有API密钥的 Abby 账户

## 使用量

### 初始化

从中获取您的 API 密钥 [艾比设置](https://app.abby.fr/settings/integrations)。 。 。 .

```typescript
import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key');
```

### 服务

SDK提供多项服务与Abby API的不同部分互动:

-   `abby.company`:当前公司信息与偏好.
-   `abby.invoice`: 创建和管理发票.
-   `abby.estimate`: 创建和管理估计数(引文).
-   `abby.contact`: 管理您的联系人( 客户) .
-   `abby.organization`: 管理组织.
-   `abby.billing`: 共享计费公用事业 (PDF,电子邮件).
-   `abby.opportunity`:客户关系管理和机会管理.
-   `abby.asset`: 管理业务资产.
-   `abby.advance`: 管理预付款.
-   `abby.customerPortal`:客户门户支付和计费主题.

### 基本示例

```typescript
import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key');

async function main() {
  // Get current company information
  const { data: me } = await abby.company.getMe();
  console.log(`Welcome back, ${me.user.firstname}!`);

  // List all contacts
  const { data: contacts } = await abby.contact.retrieveContacts({
    query: { limit: 10 },
  });

  console.log(`Found ${contacts.docs.length} contacts.`);
}

main().catch(console.error);
```

### 配置

您可以在初始化 SDK 时通过可选配置设置 :

```typescript
import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key', {
  baseUrl: 'https://api.app-abby.com',
  timeout: 30000,
  headers: {
    'X-Custom-Header': 'value',
  },
});
```

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `baseUrl` | `'https://api.app-abby.com'` | Abby API的基础 URL. |
| `timeout` | `30000` | 请求超时, 以毫秒计 . |
| `headers` | `undefined` | 在每个请求中包含额外的标题 . |
| `fetch` | `globalThis.fetch` | 自定义获取代理、记录或测试的执行 。 见 [自定义获取代理支持( P)](https://npmcn.com/package/%40abby-inc/node/#readme-custom-fetch--proxy-support)。 。 。 . |

### 自定义获取代理支持( P)

SDK 允许您提供自定义 `fetch` 用于高级使用,如代理、自定义记录或测试.

#### 使用代理服务器

与 [未编辑](https://github.com/nodejs/undici) (建议Node.js):

```typescript
import Abby from '@abby-inc/node';
import { fetch as undiciFetch, ProxyAgent } from 'undici';

const proxyAgent = new ProxyAgent('http://proxy.example.com:8080');

const abby = new Abby('your_api_key', {
  fetch: (url, init) =>
    undiciFetch(url, {
      ...init,
      dispatcher: proxyAgent,
    }),
});
```

与 [节点比对](https://github.com/node-fetch/node-fetch) 财务报告和审定财务报表 [https- 代理剂](https://github.com/TooTallNate/proxy-agents)数字 :

```typescript
import Abby from '@abby-inc/node';
import fetch from 'node-fetch';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyAgent = new HttpsProxyAgent('http://proxy.example.com:8080');

const abby = new Abby('your_api_key', {
  fetch: (url, init) =>
    fetch(url, {
      ...init,
      agent: proxyAgent,
    }) as Promise<Response>,
});
```

#### 自定义日志

```typescript
const abby = new Abby('your_api_key', {
  fetch: async (url, init) => {
    console.log(`[Abby SDK] ${init?.method ?? 'GET'} ${url}`);
    const start = Date.now();

    const response = await globalThis.fetch(url, init);

    console.log(`[Abby SDK] ${response.status} in ${Date.now() - start}ms`);
    return response;
  },
});
```

#### 使用 Moc 获取测试

```typescript
import { vi } from 'vitest';

const mockFetch = vi.fn(
  async () =>
    new Response(JSON.stringify({ success: true }), {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    })
);

const abby = new Abby('your_api_key', {
  fetch: mockFetch,
});
```

### 处理错误

SDK 当请求失败时会抛出描述错误 。 您可以抓住这些错误来处理不同的失败情况 :

```typescript
try {
  const { data } = await abby.invoice.getInvoice({
    path: { invoiceId: 'inv_invalid' },
  });
} catch (error) {
  if (error.status === 404) {
    console.error('Invoice not found');
  } else if (error.status === 401) {
    console.error('Invalid API key');
  } else {
    console.error('An unexpected error occurred:', error.message);
  }
}
```

### 活动听众

SDK为全局错误处理和记录提供了事件发报器模式. 这对于与哨兵等出错跟踪服务相融合或集中记录很有用.

#### 正在收听错误

订阅应用程序中的所有 API 错误 :

```typescript
import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key');

// Global error handler - fires on any 4xx/5xx response
abby.on('error', (error) => {
  console.error(`API Error: ${error.status} ${error.statusText}`);
  console.error(`URL: ${error.method} ${error.url}`);
  console.error(`Message: ${error.message}`);
  console.error(`Duration: ${error.duration}ms`);

  // Send to error tracking service
  Sentry.captureException(new Error(error.message), {
    extra: {
      status: error.status,
      url: error.url,
      requestId: error.requestId,
      body: error.body,
    },
  });
});
```

#### 倾听所有回复

订阅所有 API 响应( 无论是成功还是失败) :

```typescript
// Log all API calls for debugging/monitoring
abby.on('response', (response) => {
  console.log(`${response.method} ${response.url} - ${response.status} (${response.duration}ms)`);
});
```

#### 删除收听器

使用 `off()` 删除一个听众 :

```typescript
const errorHandler = (error) => console.error(error);

// Add listener
abby.on('error', errorHandler);

// Remove listener later
abby.off('error', errorHandler);
```

#### 事件类型

| 活动 | 说明 | 有效载荷类型 |
| --- | --- | --- |
| `error` | 4xx/5xxx回应起火 | `AbbyErrorEvent` |
| `response` | 所有反应均起火 | `AbbyResponseEvent` |

**`AbbyErrorEvent` 属性 :**

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `status` | `number` | HTTP 状态代码( 4xx 或 5xx) |
| `statusText` | `string` | HTTP 状态文本 |
| `url` | `string` | 请求 URL |
| `method` | `string` | HTTP 方法( GET, POST等) |
| `duration` | `number` | 请求持续时间以毫秒为单位 |
| `message` | `string?` | 来自响应机构的错误消息, 如果有的话 |
| `body` | `unknown?` | 反应机构(如有) |
| `requestId` | `string?` | X- 请求- Id 页眉, 如果有的话 |

**`AbbyResponseEvent` 属性 :**

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `status` | `number` | HTTP 状态代码 |
| `url` | `string` | 请求 URL |
| `method` | `string` | HTTP 方法( GET, POST等) |
| `duration` | `number` | 请求持续时间以毫秒为单位 |
| `ok` | `boolean` | 答复是否成功( 2xx) |

### 截取器

拦截器允许您连接到请求/响应生命周期:

```typescript
const client = abby.getClient();

// Request Interceptor: Add a custom header to every request
client.interceptors.request.use((request) => {
  request.headers.set('X-Request-ID', crypto.randomUUID());
  return request;
});

// Response Interceptor: Log every response status
client.interceptors.response.use((response) => {
  console.log(`API Response: ${response.status}`);
  return response;
});
```

### 原始请求

如果您需要调用SDK未覆盖的端点,或者更愿意直接指定请求细节,您可以使用基本的HTTP客户端:

```typescript
import Abby from '@abby-inc/node';

const abby = new Abby('your_api_key');
const client = abby.getClient();

// GET request
const { data } = await client.get({
  url: '/v2/some/endpoint',
});

// POST request with body
const { data: result } = await client.post({
  url: '/v2/some/endpoint',
  body: {
    field: 'value',
  },
});

// Other methods available: put, patch, delete, head, options
```

客户端在所有请求中自动包含您的 API 密钥和 SDK 信头 .

## 验证

SDK包括内置 [佐德语Name](https://zod.dev/) 对 API 请求进行验证,在不正确有效载荷离开您的进程前将其抓取.

### 自动验证

所有 SDK 方法自动验证 **请求数据**:在发送前检查参数、查询字符串和请求机构.

**答复未经证实.** 反应计划生成并导出(见下文),但SDK并不运行这些计划——如果Spec/API不匹配,否则一个成功的调用会变成一个抛出的错误. 回复类型仅保留编译时间;分析导出内容 `z*Dto` 如果你需要运行时的保证,请自作主张.

如果请求验证失败, a `ZodError` 以详细信息显示什么是错的:

```typescript
import Abby from '@abby-inc/node';
import { ZodError } from 'zod';

const abby = new Abby('your_api_key');

try {
  // This will fail validation if the request body is invalid
  await abby.contact.createContact({
    body: {
      // Missing required fields will trigger a ZodError
    },
  });
} catch (error) {
  if (error instanceof ZodError) {
    console.error('Validation failed:', error.errors);
  }
}
```

### 使用 Zod Schemas 直接

所有 Zod schemas 均导出并可用于您自己的验证需要 :

```typescript
import Abby, { zCreateContactDto, zReadContactDto } from '@abby-inc/node';

// Validate user input before sending to the API
const userInput = {
  firstname: 'John',
  lastname: 'Doe',
  email: 'john@example.com',
};

// Parse and validate (throws ZodError if invalid)
const validatedContact = zCreateContactDto.parse(userInput);

// Or use safeParse for non-throwing validation
const result = zCreateContactDto.safeParse(userInput);
if (result.success) {
  console.log('Valid:', result.data);
} else {
  console.error('Invalid:', result.error.errors);
}

// Infer TypeScript types from schemas
import { z } from 'zod';
type CreateContactInput = z.infer<typeof zCreateContactDto>;
```

可用的方案模式 :

-   `z{DtoName}` - DTO(例如, `zCreateContactDto`, (中文(简体) ), `zReadInvoiceDto`(中文(简体) )
-   `z{ControllerMethod}Data` - 要求数据计划(例如, `zContactControllerCreateContactData`(中文(简体) )

## 类型脚本支持

SDK被写入TypeScript,为所有API资源和响应提供了完整的类型定义.

```typescript
import Abby, { ReadMeDto } from '@abby-inc/node';

const abby = new Abby('your_api_key');

async function getCompanyData() {
  const { data }: { data: ReadMeDto } = await abby.company.getMe();
  return data;
}
```

也可以直接从Zod schemas推断类型:

```typescript
import { z } from 'zod';
import { zReadContactDto } from '@abby-inc/node';

// Infer the type from the Zod schema
type Contact = z.infer<typeof zReadContactDto>;
```

## 版本

这个 SDK 使用 **独立版本** 从艾比API:

-   **SDK 版本** (单位:千美元)`version` 内 `package.json`: 随行 [铸造](https://semver.org/) sDK 更改( 错误修正、 新特性、 断开更改)
-   **API 版本** (单位:千美元)`apiVersion` 内 `package.json`: Abby API 版本用于生成 SDK 的音轨

```json
{
  "version": "1.2.0", // SDK version
  "apiVersion": "1.5.0" // API spec version used to generate
}
```

这使得SDK能够独立于API更改而接受错误修正和改进.

SDK更新由 API 光谱变化自动打开的PRs,一旦CI通过就会被自动并发. 生成SDK工作流程的人工运行需要人机合并.

## 发展

欢迎捐款! 请看我们的 [贡献准则](https://npmcn.com/package/%40abby-inc/node/CONTRIBUTING.md) 更多信息.

## 支助

如果遇到问题或有问题,请检查以下资源:

-   [正式文件](https://docs.abby.fr/)
-   [API 参考](https://api.app-abby.com/api-docs/public.json)
-   [GitHub 问题](https://github.com/abby-inc/abby-node/issues)
-   [艾比支助](https://abby.fr/contact)

## 许可证

麻省理工学院执照 - 看 [自由主义](https://npmcn.com/package/%40abby-inc/node/LICENSE) 详细情况.

## 常见问题

### @abby-inc/node 是什么？

节点Js, Bun, 和 Abby API 的 Deno 库

### 如何安装 @abby-inc/node？

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

### @abby-inc/node 支持 TypeScript 吗？

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

### @abby-inc/node 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @abby-inc/node 需要什么版本的 Node\.js？

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

### @abby-inc/node 可以商用吗？

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

### @abby-inc/node 的下载量有多少？

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

### @abby-inc/node 还在维护吗？

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