# @dugjason/front-node 中文文档

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

版本：0\.6\.0
npm 元数据更新时间：2026-11-10T15:02:16.477Z
中文译文更新时间：2026-11-13T01:53:08.592Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.8 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-07-01T20:25:57.187Z
- 最新版本发布：2026-11-10T15:02:16.114Z
- 近 30 天下载量：2530（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 10 个）

## 中文简介

Front.com API 的现代打字机 SDK

## 安装

```sh
npm install @dugjason/front-node
```

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

## README

# 前节点

现代类型SDK [前线](https://front.com/) API (英语).

## 安装

```bash
npm install @dugjason/front-node
```

## 使用量

```ts
import { Front } from "@dugjason/front-node";

const front = new Front({ apiKey: process.env.FRONT_API_TOKEN });

const teammates = await front.teammates.list();

// ID-scoped operations do not require fetching the resource first.
await front.channels.createMessage("cha_123", {
  body: "Hello from Front",
  options: { archive: true },
  to: ["customer@example.com"],
});
await front.conversations.addTag("cnv_123", { tag_ids: ["tag_123"] });
await front.messages.markSeen("msg_123");
```

全权证书为专用:通过 `{ apiKey }` **或者说** `{ accessToken, refreshToken }`从来没有两者。 自动刷新默认 OAuth 到 `false`。要手动刷新,请打电话 `refreshOAuthToken`数字 :

```ts
const front = new Front({
  accessToken,
  refreshToken,
  onTokenRefresh: async (tokens) => {
    await persistTokens(tokens.access_token, tokens.refresh_token);
  },
});

const tokens = await front.refreshOAuthToken({
  clientId: process.env.FRONT_CLIENT_ID,
  clientSecret: process.env.FRONT_CLIENT_SECRET,
});
```

`refreshOAuthToken()` 等着 `onTokenRefresh` 在更新客户端的证书并归还信使之前。 回电也一样 `access_token` 财务报告和审定财务报表 `refresh_token` 字段作为返回值。 如果持久性失败, 刷新拒绝和客户端保留其先前的证书 。 Front可能已经旋转了刷新符号,因此在尝试再刷新之前恢复了持久性失败.

要自动刷新,请提供 OAuth 应用程序的 `clientId` 财务报告和审定财务报表 `clientSecret` 在构造器中:

```ts
const front = new Front({
  accessToken,
  refreshToken,
  autoRefresh: true,
  clientId,
  clientSecret,
  onTokenRefresh: async (tokens) => {
    await persistTokens(tokens.access_token, tokens.refresh_token);
  },
});
```

与 `autoRefresh: true`,一个API 401触发器 `refreshOAuthToken()`客户端等待 `onTokenRefresh`,通过新的符号,并重复一次原始请求。 401个投球 `FrontApiError` 没有另一个新鲜。 其他 HTTP 状态不会触发刷新 。 这些规则适用于JSON请求和原始回复,包括附件下载.

同时期的401s共享一款令牌交换并保存每个客户端的回调. 如果另一个请求已经替换了失败请求的代号, 则该请求会用当前代号重试 。 这种协调不延及客户,也不涉及人工启动的刷新电话.

隐藏交换失败被传播为 `FrontApiError` 上面写着标志性的终点 标题 和解析的正文 譬如说, `body.error === "invalid_grant"` 识别一个已拒绝的刷新令牌; 5xx响应保留了提供者的失败。 网络出错并保存回调出错, 宣传不变 。 两次失败都没有被原API 401所取代,也没有引起请求重试. 一个失败的保存让客户端的证书保持不变,尽管Front可能已经旋转了刷新符.

API- key客户端不自动刷新. OAuth 客户端 `autoRefresh` 省略或设置为 `false` 保持手动行为.

## 发展

```bash
bun install
bun test
bun run check
```

## 释放

发行由Termets管理. 添加一个用于修改用户的更改器 :

```bash
bun run changeset
```

合并为 `main` 打开或更新版本 PR。 合并出版的PR版本 到 npm 时为 `@dugjason/front-node` 通过 npm 信任的出版.

## 费率限额

HTTP 429 答复默认情况下重试两次,等待 `Retry-After` 秒加0-999 ms的焦急。 如果缺席, 重复使用 `X-RateLimit-Reset`。超过60秒的无效延迟或延迟使用60秒。 这包括原始答复和OAuth令牌请求.

当应用程序处理时, 禁用 SDK 重试 :

```ts
const front = new Front({ apiKey: "...", rateLimitRetry: false });
```

已禁用或已耗尽的回推 `FrontRateLimitError`,扩展 `FrontApiError` 与 `retryAfterMs` 在紧张之前 使用 `error instanceof FrontRateLimitError` (d) 最后答复元数据.

## 自定义 `fetch`

您可以使用自定义的获取库, 兼容 `node:fetch`。 。 。 . 举例来说,可以采用内置跟踪或自定义遥测法进行检索;

```ts
import { Front } from "@dugjason/front-node";

const loggingFetch: typeof fetch = async (input, init) => {
  const t0 = performance.now();
  const response = await globalThis.fetch(input, init);
  console.log(
    `${init?.method ?? "GET"} ${input} ${response.status} ${Math.round(performance.now() - t0)}ms`,
  );
  return response;
};
const front = new Front({ fetch: loggingFetch });
```

## 常见问题

### @dugjason/front-node 是什么？

Front\.com API 的现代打字机 SDK

### 如何安装 @dugjason/front-node？

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

### @dugjason/front-node 支持 TypeScript 吗？

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

### @dugjason/front-node 支持 ESM 还是 CommonJS？

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

### @dugjason/front-node 可以商用吗？

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

### @dugjason/front-node 的下载量有多少？

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

### @dugjason/front-node 还在维护吗？

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