# @abxy/foil-server 中文文档

规范地址：https://npmcn.com/package/%40abxy/foil-server/

版本：0\.4\.0
npm 元数据更新时间：2026-10-27T22:19:44.340Z
中文译文更新时间：2026-11-06T07:24:44.754Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：752 kB，38 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-05-22T22:21:20.710Z
- 最新版本发布：2026-10-27T22:19:43.946Z
- 近 30 天下载量：4188（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

官方 Foil 节点服务器 SDK

## 安装

```sh
npm install @abxy/foil-server
```

也可以使用：`pnpm add @abxy/foil-server`、`yarn add @abxy/foil-server`、`bun add @abxy/foil-server`

## README

# Foil节点库

![Preview](https://img.shields.io/badge/status-preview-111827) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white) ![License: MIT](https://img.shields.io/badge/license-MIT-0f766e.svg)

Foil节点库从在Node.js运行的应用程序中为Foil API提供方便访问. 它包括一个为会话,指印,组织,组织API密钥管理,webhook端点,以及被封号的验证而输入的客户端.

图书馆还提供:

-   使用快速配置路径 `FOIL_SECRET_KEY`
-   基于光标的页形帮助
-   结构化的 API 错误和内置封装符号验证
-   webhook 端点管理、测试发送、事件发送历史和webhook 签名验证

## 文档

见 [Foil 文档](https://usefoil.com/docs) 财务报告和审定财务报表 [API 参考](https://usefoil.com/docs/api-reference/introduction)。 。 。 .

## 安装

除非你想要修改软件包,否则不需要这个源代码. 如果你想使用软件包,请运行:

```bash
npm install @abxy/foil-server
```

## 所需资源

-   节点18+

## 使用量

使用 `FOIL_SECRET_KEY` 或明示 `secretKey`数字 :

```ts
import { Foil } from "@abxy/foil-server";

const client = new Foil({
  secretKey: process.env.FOIL_SECRET_KEY,
});

const page = await client.sessions.list({ verdict: "bot", limit: 25 });
const session = await client.sessions.get("sid_123");
await client.sessions.attachClientUser("sid_123", "user_123");
await client.sessions.clearClientUser("sid_123");
await client.sessions.attachClientApplication("sid_123", "app_123");
await client.sessions.clearClientApplication("sid_123");
const userSessions = await client.sessions.list({ client_user_id: "user_123" });

console.log(page.has_more, page.next_cursor);
console.log(session.decision.risk_score, session.highlights[0]?.summary);
```

### 封存符号验证

```ts
import { safeVerifyFoilToken } from "@abxy/foil-server";

const result = safeVerifyFoilToken(
  sealedToken,
  process.env.FOIL_SECRET_KEY,
);

if (!result.ok) {
  console.error(result.error);
  return;
}

console.log(result.data.decision.verdict, result.data.decision.risk_score);
```

### 倾斜

```ts
for await (const session of client.sessions.iter({ search: "signup" })) {
  console.log(session.id, session.latest_decision.verdict);
}
```

### 指纹

```ts
const page = await client.fingerprints.list({ sort: "seen_count" });
const fingerprint = await client.fingerprints.get("vid_123");

console.log(fingerprint.lifecycle.last_seen_at);
```

### 组织

```ts
const organization = await client.organizations.get("org_123");
const updated = await client.organizations.update("org_123", { name: "New Name" });
```

### 组织 API 密钥

```ts
const created = await client.organizations.apiKeys.create("org_123", {
  name: "Production",
  type: "secret",
  environment: "live",
  scopes: ["sessions:list", "sessions:read"],
});

await client.organizations.apiKeys.revoke("org_123", created.id);
```

### 网络呼号

```ts
const endpoint = await client.webhooks.createEndpoint("org_123", {
  name: "Production alerts",
  url: "https://example.com/foil/webhook",
  event_types: ["session.result.persisted"],
});

const events = await client.webhooks.listEvents("org_123", {
  endpoint_id: endpoint.id,
  type: "session.result.persisted",
});

console.log(events.items[0]?.webhook_deliveries[0]?.status);
```

#### 正在验证webhook交付

每封网络邮递都签有你的端点签名的秘密 校验 `X-Foil-Timestamp` 财务报告和审定财务报表 `X-Foil-Signature` 在信任有效载荷之前,用头指向原始请求体:

```ts
import { parseWebhookEvent, verifyAndParseWebhookEvent, verifyWebhookSignature } from "@abxy/foil-server";

const valid = verifyWebhookSignature({
  secret: process.env.FOIL_WEBHOOK_SECRET!,
  timestamp: request.headers["x-foil-timestamp"],
  rawBody,
  signature: request.headers["x-foil-signature"],
});

// Verify and parse in one step. Throws if the signature is invalid or expired.
const event = verifyAndParseWebhookEvent({
  secret: process.env.FOIL_WEBHOOK_SECRET!,
  timestamp: request.headers["x-foil-timestamp"],
  rawBody,
  signature: request.headers["x-foil-signature"],
});

if (event.type === "session.result.persisted") {
  console.log(event.data);
}

// Parse a payload you have already verified.
const parsed = parseWebhookEvent(rawBody);
```

签署时间超过5分钟的,默认不予签署。 过 `maxAgeSeconds` 以改变宽容.

### 处理错误

```ts
import { FoilApiError } from "@abxy/foil-server";

try {
  await client.sessions.list({ limit: 999 });
} catch (error) {
  if (error instanceof FoilApiError) {
    console.error(error.status, error.code, error.message);
  }
}
```

## 支助

如果您需要帮助整合 Foil, 请从 [使用foil.com/docs](https://usefoil.com/docs)。 。 。 .

## 常见问题

### @abxy/foil-server 是什么？

官方 Foil 节点服务器 SDK

### 如何安装 @abxy/foil-server？

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

### @abxy/foil-server 支持 TypeScript 吗？

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

### @abxy/foil-server 支持 ESM 还是 CommonJS？

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

### @abxy/foil-server 需要什么版本的 Node\.js？

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

### @abxy/foil-server 可以商用吗？

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

### @abxy/foil-server 的下载量有多少？

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

### @abxy/foil-server 还在维护吗？

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