FlexPrice 类型脚本 / JavaScript SDK
FlexPrice API的Type-safet TypeScript/JavaScript客户端:为SaaS和基于使用的产品计费,计量,以及订阅管理.
所需资源
- 节点.js 18+(或见 运行时间.md 支持的运行时间)
安装
npm i @flexprice/sdk
用活页、面包或纱线:
pnpm add @flexprice/sdk
bun add @flexprice/sdk
yarn add @flexprice/sdk
该软件包支持共同JS和无害环境管理.
然后在你的代码:
import { FlexPrice } from "@flexprice/sdk";
所有生成的模块 (共享模型,enums,出错,操作类型,SDK类型)从软件包根被再导出,这样你就可以从一个地方导入所有的东西. 运行 npm run build 在公布无害环境管理和共同JS的切入点之前dist/esm/index.js 财务报告和审定财务报表 dist/commonjs/index.js包括这些再出口 import 财务报告和审定财务报表 require("@flexprice/sdk") 两者都从根部暴露出类型/enum.
import {
FlexPrice,
FeatureType,
Status,
FlexpriceError,
CreateCustomerRequest,
createPageIterator,
} from "@flexprice/sdk";
// No need for: .../dist/sdk/models/shared, .../errors, .../operations, .../types
可运行样品在 examples/ 目录.
环境
| 变量 | 需求 | 说明 |
|---|---|---|
FLEXPRICE_API_KEY | 对 | API 密钥 |
FLEXPRICE_API_HOST | 可选 | 完整基础 URL 包括 https:// 财务报告和审定财务报表 /v1 (默认 : https://us.api.flexprice.io/v1) (中文(简体) ). 没有后面的斜线. |
融合测试 内 api/ tests/ts/ test sdk.ts 页面存档备份,存于互联网档案馆 使用不同的嵌入形状;见 api/测试/README.md。 。 。 .
快开始
初始化客户端,然后创建客户端并摄入一个事件:
import { FlexPrice } from "@flexprice/sdk";
const apiKey = process.env.FLEXPRICE_API_KEY ?? "YOUR_API_KEY";
const serverURL =
process.env.FLEXPRICE_API_HOST ?? "https://us.api.flexprice.io/v1";
const flexPrice = new FlexPrice({
serverURL,
apiKeyAuth: apiKey,
});
async function main() {
const externalId = `customer-${Date.now()}`;
const customer = await flexPrice.customers.createCustomer({
externalId,
email: "[email protected]",
name: "Example Customer",
});
console.log(customer);
const eventResult = await flexPrice.events.ingestEvent({
eventName: "Sample Event",
externalCustomerId: externalId,
properties: { source: "ts_sdk", environment: "test" },
source: "ts_sdk",
});
console.log(eventResult);
}
main();
更多实例和所有 API 操作请参见 API 参考 编辑 实例 这回贷.
属性名称( snake case)
对于请求机构,API经常期望 蛇脚( c) 字段名称。 SDK可能接受骆驼Case并序列化为蛇 case;如果看到验证错误,请使用API形状:
- 首选:
event_name, (中文(简体) ),external_customer_id, (中文(简体) ),page_size - 在原始有效载荷中避免只使用骆驼Case,如果API光谱使用蛇 case
检查 API 参考 准确的要求形状.
类型脚本
带有TypeScript定义的包船. 使用全类型安全的客户端 :
import { FlexPrice } from "@flexprice/sdk";
const serverURL =
process.env.FLEXPRICE_API_HOST ?? "https://us.api.flexprice.io/v1";
const flexPrice = new FlexPrice({
serverURL,
apiKeyAuth: process.env.FLEXPRICE_API_KEY!,
});
const result = await flexPrice.events.ingestEvent({
eventName: "usage",
externalCustomerId: "cust_123",
properties: { units: 10 },
source: "backend",
});
认证
SDK支持两个证书. 设一相相相相相相相相相.
| 选项 | 页眉 | 用它来 |
|---|---|---|
apiKeyAuth | x-api-key | 服务器和脚本 |
bearerAuth | Authorization: Bearer <token> | 浏览器应用程序作为签名的 FlexPrice 用户 |
API 键 (服务器侧). 通过 apiKeyAuth。在仪表盘中创建的密钥绑定在一个环境中,因此不需要其他选择.
import { Flexprice } from "@flexprice/sdk";
const flexprice = new Flexprice({ apiKeyAuth: process.env.FLEXPRICE_API_KEY! });
已签名的用户 (浏览器) . 通过用户的 JWT bearerAuth,并通过 environmentId,以 X-Environment-ID。大多数终点被限制在环境中,在没有环境的情况下返回403.
import { Flexprice } from "@flexprice/sdk";
const flexprice = new Flexprice({
serverURL: "https://us.api.flexprice.io/v1",
bearerAuth: async () => getAccessToken(),
environmentId: () => getActiveEnvironmentId(),
});
- 两个选项都取一个字符串或一个函数,所以一个刷新了的令牌或切换的环境应用而不创建新的客户端. SDK不刷新符号本身.
- A 类
bearerAuth函数在每次尝试之前被调用,包括重试。 一个environmentId函数每个 API 调用一次,所以重试从不交换环境. - 如果值或函数结果为空,则不发送该信头.
- 页:1
{ headers: { ... } }) 优先于这些选项,匹配选项的功能不调用. environmentId也与apiKeyAuth。 API 忽略了与环境绑定的密钥.- 设置两者
apiKeyAuth财务报告和审定财务报表bearerAuth每一次通话都失败UnexpectedClientError在发送任何信息之前.
设定 FLEXPRICE_API_HOST 到完整 URL (参见 环境)或依赖默认 https://us.api.flexprice.io/v1。 。 。 .
特征
- API的全覆盖(客户、计划、事件、发票、付款、应享权利等)
- 请求和回复的脚本类型
- 内置重试和错误处理
- 无害环境管理和共同JS支助
解决问题
- 缺少或无效的 API 密钥 : 保证
apiKeyAuth设置和键已激活。 只使用服务器侧 . - 401号与
bearerAuth数字 : 信使丢失或过期 。 检查您的符号函数返回当前 JWT . - 403 与
bearerAuth数字 : 设定environmentId。Dashboard 登录符与环境无关. - "要么是ApiKeyAuth 要么是手持者Auth 而不是两者": 从构造器中删除两个选项中的一个 .
debugLogger数字 : 它打印每个请求头,包括Authorization财务报告和审定财务报表x-api-key。仅用于本地调试.- 错误服务器 URL : 使用完整的 URL, 如
https://us.api.flexprice.io/v1(包括/v1绝不然. - 验证或 4xx 错误 : 确认请求的正文字段名称( snake case vs cameCase) 和需要的字段对齐 API 文件。 。 。 .
- 参数通过 : 将请求对象直接传递给方法(例如:.
ingestEvent({ ... })除非SDK文件另有说明 否则不能用额外钥匙包裹.
处理 Webhooks
Flexprice向您的服务器发送webhook事件, 以获取支付, 发票, 订阅, 钱包等最新消息 .
流量 :
- 在 Flexprice 仪表板上注册您的端点 URL
- 接收
POST与生 JSON 身体 - 读取
event_type到路径 - 使用 SDK 助手分析有效载荷
- 处理商业逻辑
- 返回时
200快点
import {
WebhookEventName,
webhookDtoPaymentWebhookPayloadFromJSON,
webhookDtoSubscriptionWebhookPayloadFromJSON,
webhookDtoInvoiceWebhookPayloadFromJSON,
} from "@flexprice/sdk";
function handleWebhook(rawBody: string): void {
const env = JSON.parse(rawBody) as { event_type: string };
switch (env.event_type as WebhookEventName) {
case WebhookEventName.PaymentSuccess:
case WebhookEventName.PaymentFailed:
case WebhookEventName.PaymentUpdated: {
const result = webhookDtoPaymentWebhookPayloadFromJSON(rawBody);
if (!result.ok) { console.error("parse error", result.error); break; }
const { payment } = result.value;
console.log("payment", payment?.id);
// TODO: update payment record
break;
}
case WebhookEventName.SubscriptionActivated:
case WebhookEventName.SubscriptionCancelled:
case WebhookEventName.SubscriptionUpdated: {
const result = webhookDtoSubscriptionWebhookPayloadFromJSON(rawBody);
if (!result.ok) { console.error("parse error", result.error); break; }
console.log("subscription", result.value.subscription?.id);
break;
}
case WebhookEventName.InvoiceUpdateFinalized:
case WebhookEventName.InvoicePaymentOverdue: {
const result = webhookDtoInvoiceWebhookPayloadFromJSON(rawBody);
if (!result.ok) { console.error("parse error", result.error); break; }
console.log("invoice", result.value.invoice?.id);
break;
}
default:
console.log("unhandled event:", env.event_type);
}
}
场由SDK自动控制:
event_type→eventType, (中文(简体) ),invoice_status→invoiceStatus编辑fromJSON帮助者返回 aSafeParseResult<T>- 总是检查.ok访问前.value。 。 。 .
事件类型
| 类别 | 活动 |
|---|---|
| 付款 | payment.created • 妇女 payment.updated • 妇女 payment.success • 妇女 payment.failed • 妇女 payment.pending |
| 发票 | invoice.create.drafted • 妇女 invoice.update • 妇女 invoice.update.finalized • 妇女 invoice.update.payment • 妇女 invoice.update.voided • 妇女 invoice.payment.overdue • 妇女 invoice.communication.triggered |
| 订阅 | subscription.created • 妇女 subscription.draft.created • 妇女 subscription.activated • 妇女 subscription.updated • 妇女 subscription.paused • 妇女 subscription.resumed • 妇女 subscription.cancelled • 妇女 subscription.renewal.due |
| 订阅阶段 | subscription.phase.created • 妇女 subscription.phase.updated • 妇女 subscription.phase.deleted |
| 客户 | customer.created • 妇女 customer.updated • 妇女 customer.deleted |
| 钱包 | wallet.created • 妇女 wallet.updated • 妇女 wallet.terminated • 妇女 wallet.transaction.created • 妇女 wallet.transaction.updated • 妇女 wallet.credit_balance.dropped • 妇女 wallet.credit_balance.recovered • 妇女 wallet.ongoing_balance.dropped • 妇女 wallet.ongoing_balance.recovered • 妇女 wallet.ongoing_balance.updated |
| 特征/应享权利 | feature.created • 妇女 feature.updated • 妇女 feature.deleted • 妇女 feature.wallet_balance.alert • 妇女 entitlement.created • 妇女 entitlement.updated • 妇女 entitlement.deleted |
| 贷方附注 | credit_note.created • 妇女 credit_note.updated |
生产规则:
- 保持处理器同位素——非-
2xx - 返回时
200用于未知事件类型 — 防止不必要的重试 - 进行重处理 async —— 快速响应, 排队工作
文档
- FlexPrice API 文档
- 类型脚本 SDK 示例 在此重播中
- SDK 集成测试 ——不同
FLEXPRICE_API_HOST用于自动测试的形状