Foil节点库

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

图书馆还提供:

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

文档

见 Foil 文档 财务报告和审定财务报表 API 参考。 。 。 .

安装

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

npm install @abxy/foil-server

所需资源

• 节点18+

使用量

使用 FOIL_SECRET_KEY 或明示 secretKey数字 :

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);

封存符号验证

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);

倾斜

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

指纹

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

console.log(fingerprint.lifecycle.last_seen_at);

组织

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

组织 API 密钥

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);

网络呼号

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 在信任有效载荷之前,用头指向原始请求体:

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 以改变宽容.

处理错误

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。 。 。 .