@flexprice/sdk

中文文档
2.1.49发布于 2026/11/16TypeScriptES Module近 30 天下载 1.6万

FlexPrice API的Type-safet TypeScript/JavaScript客户端:为SaaS和基于使用的产品计费,计量,以及订阅管理.

中文使用文档
文档目录12 节
  1. 所需资源
  2. 安装
  3. 环境
  4. 快开始
  5. 属性名称( snake case)
  6. 类型脚本
  7. 认证
  8. 特征
  9. 解决问题
  10. 处理 Webhooks
  11. 事件类型
  12. 文档

FlexPrice 类型脚本 / JavaScript SDK

FlexPrice API的Type-safet TypeScript/JavaScript客户端:为SaaS和基于使用的产品计费,计量,以及订阅管理.

所需资源

安装

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支持两个证书. 设一相相相相相相相相相.

选项页眉用它来
apiKeyAuthx-api-key服务器和脚本
bearerAuthAuthorization: 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 参考 编辑 实例 这回贷.

解决问题

  • 缺少或无效的 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事件, 以获取支付, 发票, 订阅, 钱包等最新消息 .

流量 :

  1. 在 Flexprice 仪表板上注册您的端点 URL
  2. 接收 POST 与生 JSON 身体
  3. 读取 event_type 到路径
  4. 使用 SDK 助手分析有效载荷
  5. 处理商业逻辑
  6. 返回时 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 帮助者返回 a SafeParseResult<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/sdk 共发布 151 个版本,首次发布于 2025/03/30;过去 12 个月发布了 138 个版本。

版本发布日期距今
2.1.49latest2026/11/16今天
2.1.49-dev.44dev2026/11/16今天
2.1.49-dev.432026/11/16今天
2.1.49-dev.422026/11/16今天
2.1.49-dev.412026/11/16今天
2.1.49-dev.402026/11/16今天

关于 @flexprice/sdk 的常见问题

@flexprice/sdk 是什么?

FlexPrice API的Type-safet TypeScript/JavaScript客户端:为SaaS和基于使用的产品计费,计量,以及订阅管理.

如何安装 @flexprice/sdk?

在项目目录运行 npm install @flexprice/sdk,或使用 pnpm add / yarn add / bun add。

@flexprice/sdk 支持 TypeScript 吗?

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

@flexprice/sdk 支持 ESM 还是 CommonJS?

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

@flexprice/sdk 需要什么版本的 Node.js?

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

@flexprice/sdk 可以商用吗?

@flexprice/sdk 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@flexprice/sdk 的下载量有多少?

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

@flexprice/sdk 还在维护吗?

最新版本 2.1.49 发布于 2026/11/16(今天);至今共发布 151 个版本,其中过去 12 个月发布了 138 个;首次发布于 2025/03/30。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。