# @crvouga/mockingbird-service-easypost 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-easypost/

版本：3\.11\.0
npm 元数据更新时间：2026-11-11T02:07:19.391Z
中文译文更新时间：2026-11-11T05:50:49.476Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-easypost
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-easypost/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/easypost#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.3 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-09-22T23:53:34.754Z
- 最新版本发布：2026-11-11T02:07:19.005Z
- 近 30 天下载量：3107（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

EasyPost trackers API的状态仿真器:创建/再使用 trackers,EasyPost的测试跟踪代码,管理状态过渡和EasyPost的错误信封.

## 安装

```sh
npm install @crvouga/mockingbird-service-easypost
```

也可以使用：`pnpm add @crvouga/mockingbird-service-easypost`、`yarn add @crvouga/mockingbird-service-easypost`、`bun add @crvouga/mockingbird-service-easypost`

## README

# @crvouga/ mockingbird-service-easypost (英语)

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

国家模拟器 **网易邮箱** 测试套件的 API : `POST /v2/trackers` (创建或 重新使用跟踪码, `GET /v2/trackers/{id}` 财务报告和审定财务报表 `GET /v2/trackers`网易邮报 记录的测试跟踪代码解答其固定状态,任何其他代码都通过 管理员过渡,所以基因组管理员的航运腿状态可以被驱动决定.

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/easypost/SUPPORT.md)
-   合同`openapi.yaml`从EasyPost发表的关于我们 跟踪搜索( e)`packages/lib/src/shipment-tracking-status/easypost-client.ts`(电话).

## 安装

```bash
npm install -D @crvouga/mockingbird-service-easypost
```

仅限无害环境管理。 节点 22或 Bun 1.2. 无土生属地. 给它服务 `npx mockingbird-easypost serve`, (中文(简体) ), `createServer` 从 `./server` (节点),或 `createRuntime` 与 任何获取服务器.

## 使用量

应用程序硬码 `https://api.easypost.com/v2/trackers` (接缝) **G-Y1级**: 向 `easypost-client.ts`) (中文(简体) ). 将基准 URL 指向模拟器; `EASYPOST_API_KEY` 可以是任意值 (单位:千美元)`--api-key` 限制它).

```bash
npx mockingbird-easypost serve --port 8818
```

```ts
import EasyPostClient from "@easypost/api"
import { createServer } from "@crvouga/mockingbird-service-easypost/server"

const server = await createServer()

// Test setup: seed a status before the app looks the code up (or move an existing tracker).
await fetch(`${server.url}/__admin/trackers/1Z999AA10123456784/transition`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ status: "out_for_delivery" }),
})

// The EasyPost SDK your application already uses. Only its base URL changes.
// @ts-ignore @easypost/api 8.9.0 types its ESM default export as CommonJS (NodeNext only).
const easypost = new EasyPostClient("EZTK_test", { baseUrl: `${server.url}/v2/` })
const tracker = await easypost.Tracker.create({ tracking_code: "1Z999AA10123456784", carrier: "UPS" })
console.log(tracker.id, tracker.status, tracker.carrier) // trk_… out_for_delivery UPS

await server.close()
```

### 路线

| 路线 | 行为 |
| --- | --- |
| `POST /v2/trackers` | 表单( E)`tracker[tracking_code]`, (中文(简体) ), `tracker[carrier]`)或JSON(英语:`{tracker: {…}}`, (中文(简体) ), `Authorization: Basic base64(key:)`与跟踪器对201的答复(`id`, (中文(简体) ), `object`, (中文(简体) ), `mode`, (中文(简体) ), `tracking_code`, (中文(简体) ), `status`, (中文(简体) ), `status_detail`, (中文(简体) ), `carrier`, (中文(简体) ), `tracking_details`, (中文(简体) ), `public_url`, (中文(简体) ), `signed_by`, (中文(简体) ), `est_delivery_date`(中文(简体) ). 同样的代码和载体像EasyPost一样重新使用已存在的跟踪器. 承运人:给定的(`DHL` 正态化为 `DHLExpress`),其他从代码形状检测出,否则 `USPS`。空白代码为422 `PARAMETER.REQUIRED`; 坏载体 422 `PARAMETER.INVALID`。 。 。 . |
| `GET /v2/trackers/{id}` | 追踪器,或404 `NOT_FOUND`。 。 。 . |
| `GET /v2/trackers` | `?tracking_code=&carrier=&page_size=` → `{trackers, has_more}`,最新的第一. |

每一个错误都是 EasyPost 的信封 `{error: {code, message, errors}}`;我们的客户端读 `error.message`。缺失的密钥为 401 `APIKEY.REQUIRED`,外部键 `apiKeys` 401 (中文(简体) ) `APIKEY.INACTIVE`键开始 `EZAK` 生产模式(测试代码不特殊); 其他的都是测试模式.

**测试跟踪代码** (试验模式,载体) `USPS`: `EZ1000000001` 传输前( t), `EZ2000000002` 中转, `EZ3000000003` 运出( f), `EZ4000000004` 交付, `EZ5000000005` 返回到发件人( s), `EZ6000000006` 失败, `EZ7000000007` 不详。 任何其他代码 开始 `unknown` 编号 : `unknown`。 。 。 .

### 管理员(超过标准合同)

| 路线 | 效果 |
| --- | --- |
| `POST /__admin/trackers/:idOrCode/transition` | `{status, status_detail?, message?, signed_by?, carrier?}`。移动跟踪器(通过ID或跟踪代码)并附加跟踪细节。 还没有那个代码的追踪器, 请先登记一个, 所以应用程序的下一个查询会看到状态. `status` 这是其中之一 `unknown`, (中文(简体) ), `pre_transit`, (中文(简体) ), `in_transit`, (中文(简体) ), `out_for_delivery`, (中文(简体) ), `delivered`, (中文(简体) ), `available_for_pickup`, (中文(简体) ), `return_to_sender`, (中文(简体) ), `failure`, (中文(简体) ), `cancelled`, (中文(简体) ), `error`。 。 。 . |
| `GET /__admin/trackers` | 名字空间的追踪器. |
| `GET/PUT /__admin/settings` | `{apiKeys?: string[]}`: 只接受这些密钥( 默认: 任何) . |

错误预设( E)`POST /__admin/faults {"preset": "<name>", "count"?: n}`: `rate_limited` (429个), `server_error` (500个), `invalid_api_key` (401个), `gateway_html` (502 HTML,我们的客户掉头了) 改为 `EasyPost tracker request failed (502)`, (中文(简体) ), `connection_drop` (拒绝;我们的批量检查) 记录 `unknown` 你应当警告, `slow` (5s) (英语).

### 命名空间

`x-mockingbird-namespace`页:1 `/__admin/ns/<name>` 前缀在基址上,或用 API 键: `PUT /__admin/credentials {"credentials": {"<EASYPOST_API_KEY>": "<namespace>"}}`。 。 。 .

### 故意不模拟

-   追踪器 Webhooks (`tracker.updated`, (中文(简体) ), `X-Hmac-Signature`我们的应用程序没有接收器.
-   载体外观: 真实形状的代码从不自行移动; 状态来自管理员 过渡.
-   运输、费率、标签、地址、批发和所有其他的EasyPost资源.
-   相位光标( P)`before_id` 编号 : `after_id`名单中: `page_size` 财务报告和审定财务报表 `has_more` 只有这个.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `EasyPostAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `transition(idOrCode, {status, …}, carrier?)`, (中文(简体) ), `trackers()`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `settings`。 。 。 . |
| `createRuntime` | 函数 | 全面服务合同的仿真器(保健、管理员、命名空间、证书、预设)。 选项 : `settings`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`, (中文(简体) ), `sqlite`。 。 。 . |
| `EASYPOST_PRESETS` | 对象 | 每个命名的断层预设. |
| `EASYPOST_NAMESPACE` | 字符串 | 服务名称, `"easypost"`。 。 。 . |
| `TEST_TRACKING_CODES` | 对象 | EasyPost的测试代码和状态 / 详细每个答案. |
| `TRACKER_STATUSES` | 数组 | 每个跟踪器 `status`。 。 。 . |
| `apiKeyCredential` | 函数 | API 密钥来自 `Basic base64(key:)` (如何将证书映射到命名空间). |
| `detectCarrier` | 函数 | 仿真器的载体会指定一个没有给与载体的代码. |
| `easyPostError` | 函数 | 构建一个 EasyPost 错误响应 `{error: {code, message, errors}}`。 。 。 . |
| `isTrackerStatus` | 函数 | 值是否为 Tracker 状态 . |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | 销售商为OpenAPI合同及其业务代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`; 数据 `serve` CLI目标;出港8818. |

部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

## 常见问题

### @crvouga/mockingbird-service-easypost 是什么？

EasyPost trackers API的状态仿真器:创建/再使用 trackers,EasyPost的测试跟踪代码,管理状态过渡和EasyPost的错误信封\.

### 如何安装 @crvouga/mockingbird-service-easypost？

在项目目录运行 npm install @crvouga/mockingbird-service-easypost，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-easypost，可以用 npx mockingbird-easypost 直接运行。

### @crvouga/mockingbird-service-easypost 支持 TypeScript 吗？

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

### @crvouga/mockingbird-service-easypost 支持 ESM 还是 CommonJS？

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

### @crvouga/mockingbird-service-easypost 可以商用吗？

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

### @crvouga/mockingbird-service-easypost 的下载量有多少？

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

### @crvouga/mockingbird-service-easypost 还在维护吗？

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