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

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

版本：3\.10\.7
npm 元数据更新时间：2026-11-03T00:53:31.547Z
中文译文更新时间：2026-11-11T08:53:32.797Z
软件包许可：MIT

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

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

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

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

## 中文简介

Klaviyo事件的状态仿真器 API:JSON:API事件创建(命令出产,被放出命令出产),事件读取,独有 id dedupe,JSON:API出错和一个发包.

## 安装

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

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

## README

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

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

国家模拟器 **克拉维约** 测试套件的 API: JSON: API 创建- 事件结束点 我们的后端帖子 `Ordered Product` 财务报告和审定财务报表 `Placed Order` ,然后读取 一间套房装着 错误出现在 Klaviyo 的 JSON: API `errors[]` 形状,所以文本 我们的客户端抛出(和日志)是真实的API将生成的文本.

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/klaviyo/SUPPORT.md)
-   合同`openapi.yaml`校对:Portnoy `2024-02-15`, (中文(简体) ), 我们的后端针) 给消费者送来的东西.

## 安装

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

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

## 使用量

点 `KLAVIYO_URL` (Joi- required, 完全压倒性) 在模拟器的事件终点; 任意 `KLAVIYO_API_KEY` 工作时.

```bash
npx mockingbird-klaviyo serve --port 8811
# KLAVIYO_URL=http://127.0.0.1:8811/api/events/
```

```ts
import { ApiKeySession, EventEnum, EventsApi, MetricEnum, ProfileEnum } from "klaviyo-api"
import { createServer } from "@crvouga/mockingbird-service-klaviyo/server"

const klaviyo = await createServer()

// The application's Klaviyo client. Only basePath changes.
const events = new EventsApi(new ApiKeySession("any-key"))
events.basePath = klaviyo.url
await events.createEvent({
  data: {
    type: EventEnum.Event,
    attributes: {
      properties: { OrderId: "1001" },
      value: 29,
      uniqueId: "order-1001",
      metric: { data: { type: MetricEnum.Metric, attributes: { name: "Placed Order" } } },
      profile: { data: { type: ProfileEnum.Profile, attributes: { email: "ada@example.com" } } },
    },
  },
})

// Test assertion: the outbox holds what the emulator accepted.
const response = await fetch(`${klaviyo.url}/__admin/outbox?to=ada@example.com&metric=Placed%20Order`)
const { messages } = (await response.json()) as { messages: { metric: string; value: number }[] }
// messages → [{ metric: "Placed Order", value: 29, … }]

await klaviyo.close()
```

### 路线

| 路线 | 行为 |
| --- | --- |
| `POST /api/events/` | 亚庇: `{data: {type: "event", attributes: {properties, time?, value?, value_currency?, unique_id?, metric: {data: {type: "metric", attributes: {name}}}, profile: {data: {type: "profile", id?, attributes: {email?, phone_number?, external_id?}}}}}}` → **202,没有尸体**。配置文件与 id、 email、 电话或外部 id 相匹配( else 创建); 度量符是首先使用的。 重复 度量 + 剖面 + `unique_id` 被接受但不储存两次(BullMQ重试不会使收入增加一倍)。 无效输入为 400 `{errors: [{id, status, code: "invalid", title, detail, source: {pointer}}]}`;一个不是E.164的电话号码被用克拉维约的措辞拒绝. |
| `GET /api/events/` | `{data: [event], links: {self, next: null, prev: null}}`,最古老的第一。 每次活动都带 `attributes.{timestamp, event_properties (properties + $value + $event_id), datetime, uuid}` 财务报告和审定财务报表 `relationships.{profile, metric}`。 。 。 . |
| `GET /api/events/{id}/` | 一个事件,或404 `not_found`。 。 。 . |

每个电话都需要 `Authorization: Klaviyo-API-Key <key>` (原为401) `not_authenticated`)和a 数据 `revision: YYYY-MM-DD` 头(等为400). 路径以末端的斜线来回答.

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

| 路线 | 效果 |
| --- | --- |
| `GET /__admin/outbox?to=&since=&metric=&unique_id=` | 接受呼号命名空间事件,最古老的`to` 匹配配置文件的电子邮件、电话或id. `GET /__admin/outbox/:id` 一个. |
| `GET /__admin/profiles` | 创建或匹配的配置文件 . |

错误预设( E)`POST /__admin/faults {"preset": "<name>", "count"?: n}`· ; `GET /__admin/faults/presets`: `throttled` (429个+) `Retry-After: 1`, (中文(简体) ), `invalid_api_key` (401个), `server_error` (500个), `service_unavailable` (503个), `connection_drop` (套接字关闭;没有存储).

### 命名空间

`x-mockingbird-namespace`页:1 `/__admin/ns/<name>` 前缀在 `KLAVIYO_URL`,或用私钥: `PUT /__admin/credentials {"credentials": {"<KLAVIYO_API_KEY>": "<namespace>"}}`。 。 。 .

### 故意不模拟

-   流量, 列表, 片段和运动: 事件永远不会触发电子邮件( 使用发件箱) .
-   Profile-id 验证: Klaviyo profile ids 是 Klaviyo 生成的; 我们的后端发送用户 符号为 `profile.data.id`而不是拒绝. 真实的 API 是否接受未知的 id 未经验证( 没有 sandbox 证书) .
-   倾斜( P)`page[cursor]`, (中文(简体) ), `filter`, (中文(简体) ), `fields[…]` 财务报告和审定财务报表 `include` 读取.
-   费率限额,但 `throttled` 预设.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `KlaviyoAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `events()`, (中文(简体) ), `state`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `baseUrl`。 。 。 . |
| `createRuntime` | 函数 | 全面服务合同的仿真器(保健、管理、命名空间、证书、预设、发包)。 选项 : `baseUrl`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`, (中文(简体) ), `sqlite`。 。 。 . |
| `KLAVIYO_PRESETS` | 对象 | 每个命名的断层预设. |
| `KLAVIYO_NAMESPACE` | 字符串 | 服务名称, `"klaviyo"`。 。 。 . |
| `KLAVIYO_REVISION` | 字符串 | API版本 我们的后端发送, `"2024-02-15"`。 。 。 . |
| `klaviyoApiKey` | 函数 | 键入 `Authorization: Klaviyo-API-Key <key>` (如何将证书映射到命名空间). |
| `klaviyoError` | 函数 | 构建 JSON: API `{errors: [...]}` 躯体. |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | 销售商为OpenAPI合同及其业务代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`; 数据 `serve` CLI目标; 第8811口. |

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

## 常见问题

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

Klaviyo事件的状态仿真器 API:JSON:API事件创建\(命令出产,被放出命令出产\),事件读取,独有 id dedupe,JSON:API出错和一个发包\.

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

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

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

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

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

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

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

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

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

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

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

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