@crvouga/ mockingbird-service-paddle (英语)

本地模拟器。 真正的API合同. 部分 嘲笑鸟。 。 。 .

国家模拟器 划板计费 测试套房的API. 顾客,地址,企业, 产品和价格表现为Paddle的行为(验证, invalid_field 错误, include=, (中文(简体) ), 光标平面)。 交易携带 计算总数。订阅创建方式 当一个反复出现价格的交易被支付, 以及模拟者的管理员时, 板块会创建它们 主机检查和计费引擎的路线: 支付交易, 完成 a 一通电话就退房,续约,不付款。每次更改都会生成事件 将发射,在 GET /events 作为《京都议定书》 Paddle-Signature 网络浏览 (原始内容存档于2018-07-21) (英语). Official SDK's paddle.webhooks.unmarshal 验出.

• 行动范围: 支助
• openapi.yaml 由 Paddle 的 API 引用和线条类型生成 @paddle/[email protected]。 。 。 .

安装

npm install -D @crvouga/mockingbird-service-paddle

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

使用量

SDK地图 environment 到一个基础 URL , 否则使用 数值 逐字, 因此将其指向 通过将模拟器的 URL 作为环境传递给模拟器。 给同样的应用 pdl_ntfset_… 保密为 --webhook-secret。 。 。 .

npx mockingbird-paddle serve --port 8795 --fixtures \
  --webhook-url http://127.0.0.1:3000/webhooks/paddle \
  --webhook-secret "$PADDLE_WEBHOOK_SECRET" \
  --payment-link https://pay.example.com/checkout
PADDLE_API_BASE_URL=http://127.0.0.1:8795 node app.js

import { createServer } from "@crvouga/mockingbird-service-paddle/server"
import { type Environment, Paddle } from "@paddle/paddle-node-sdk"

const emulator = await createServer({ paymentLink: "https://pay.example.com/checkout" })
// The app's own Paddle client. Only its environment changes.
const paddle = new Paddle("pdl_sdbx_apikey_test", { environment: emulator.url as Environment })

const product = await paddle.products.create({ name: "Pro plan", taxCategory: "saas" })
const price = await paddle.prices.create({
  productId: product.id,
  description: "Pro monthly",
  unitPrice: { amount: "2900", currencyCode: "USD" },
  billingCycle: { interval: "month", frequency: 1 },
})
const customer = await paddle.customers.create({ email: "[email protected]" })
const address = await paddle.addresses.create(customer.id, { countryCode: "US" })
const transaction = await paddle.transactions.create({
  items: [{ priceId: price.id, quantity: 2 }],
  customerId: customer.id,
  addressId: address.id,
})
// transaction.status === "ready", transaction.details.totals.grandTotal === "5800",
// transaction.checkout.url === "https://pay.example.com/checkout?_ptxn=txn_…"

// The customer pays on the hosted checkout: the emulator's admin route stands in for it.
await fetch(`${emulator.url}/__admin/transactions/${transaction.id}/pay`, { method: "POST" })
const [subscription] = await paddle.subscriptions.list({ customerId: [customer.id] }).next()
// subscription.status === "active", subscription.nextBilledAt one month out
await emulator.close()

与 fixtures: true 该目录已经播种, 并有一个管理员呼叫完成一个检查:

import { createServer } from "@crvouga/mockingbird-service-paddle/server"
import { type Environment, Paddle } from "@paddle/paddle-node-sdk"

const emulator = await createServer({ fixtures: true })
const paddle = new Paddle("pdl_sdbx_apikey_test", { environment: emulator.url as Environment })
const [product] = await paddle.products.list({ include: ["prices"] }).next()

// Test setup: one admin call stands in for a customer completing the hosted checkout.
const completed = await fetch(`${emulator.url}/__admin/checkout`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ email: "[email protected]", items: [{ price_id: product?.prices?.[0]?.id }] }),
})
const checkout = (await completed.json()) as { transaction: { id: string }; subscription: { id: string } }

const transaction = await paddle.transactions.get(checkout.transaction.id)
const subscription = await paddle.subscriptions.get(checkout.subscription.id)
// transaction.status === "completed", subscription.status === "trialing" (the fixture price has a trial)
await emulator.close()

路线

每个回复都是Paddle的信封: {data, meta: {request_id}},列表添加 meta.pagination: {per_page, next, has_more, estimated_total}清单 after=<id> (单位:千美元) 光标进入 next,SDK所遵循的绝对URL as-is,), per_page (违约50,最大200; 交易 30; 超过最大值获得最大值, 如 Paddle 文档)和 order_by=id[ASC]|id[DESC] (默认最新第一). 一个页面显示创建于 after 按此顺序排列的实体,所以将过滤器留在页面之间的光标(存档,例如) 页面打开。 错误是 {error: {type, code, detail, documentation_url, errors?: [{field, message}]}, meta}。 。 。 .

认证是 Authorization: Bearer <key>; 任何关键功能。 没有标题是403 authentication_missing, (中文(简体) ), 非Bearer 信头为 403 authentication_malformed验证失败400次 invalid_field 与 errors: [{field, message}] (单位:千美元)email: required field; 变形的 JSON 尸体是400块 invalid_json; 未知实体为 404 not_found (单位:千美元)Entity ctm_… not found) (中文(简体) ). Ids看起来像Paddle'sctm_01…, (中文(简体) ), pri_01…, (中文(简体) ), txn_01…, (中文(简体) ), sub_01…, (中文(简体) ), evt_01…: 前缀和26 小写字母数),对给定历史具有决定性.

离职和记账(管理)

Paddle 无法支付交易或创建订阅的 API : 主机检出确实 开具账单的引擎会更新 这些路线对他们来说都是 /__admin, (中文(简体) ), 像其它东西一样空格 :

--fixtures (或 createRuntime({fixtures: true})种子每一个命名空间 在第一次使用,和再次 每次重置后, 使用 : 艾达·洛芙蕾丝(Ada Lovelace)[email protected],美国地址,企业),a 计划 产品为 每月(29美元)、每年(290美元)和一次性入职(99美元) 启动计划 带有 审判14天(每月19美元),每月主动订阅,试订起步器 (葛瑞斯・霍伯, [email protected]),未支付 ready 交易和a billed 手动 发票. seedFixtures() 返回记录; 在电子邮件上种子两次名称空间冲突. 固定事件列出(GET /events但从未作为通知送达: 账户是原有状态,不是活动.

网络呼号

每个事件都会被发布到配置的终点作为Paddle的通知机构:

{"event_id": "evt_01…", "event_type": "subscription.created", "occurred_at": "…",
 "notification_id": "ntf_01…", "data": {"id": "sub_01…", "status": "active", "transaction_id": "txn_01…", "items": [ … ], … }}

类型 : customer|address|business|product|price.created|updated, (中文(简体) ), transaction.created|ready| billed|paid|completed|canceled|payment_failed|past_due|updated, (中文(简体) ), subscription.created| activated|trialing|updated|paused|resumed|canceled|past_due每次交货都携带 Paddle-Signature: ts=<unix seconds>;h1=<hex HMAC-SHA256(secret, "<ts>:<raw body>")> 带有 时钟 ts (即使模拟时钟移动) paddle.webhooks.unmarshal(body, secret, signature) 财务报告和审定财务报表 isSignatureValid 接受 。 非-2xx的答案被重审(立即, 5分5分30分2小时). GET /__admin/webhooks, (中文(简体) ), …/events, (中文(简体) ), …/flush, (中文(简体) ), …/:id/replay 财务报告和审定财务报表 PUT /__admin/webhook-endpoints (每个名称空间接收器, events: ["subscription.*"]- 风格 过滤器是精确的类型或 *)来与合同.

错误预设( E)POST /__admin/faults {"preset": "<name>", "count"?: n}· ; GET /__admin/faults/presets: invalid_token (每起请求403起), rate_limited (429个) too_many_requests 与 retry-after: 2,SDK's(SDK's ApiError.retryAfter, (中文(简体) ), transactions_500 (单位:千美元)POST /transactions 答复 500 internal_error, (中文(简体) ), bad_gateway_html (读取了502 HTML 页面), network_drop (单位:千美元)POST /transactions 放弃连接, webhook_duplicate, (中文(简体) ), webhook_reorder, (中文(简体) ), webhook_drop。 。 。 .

命名空间

new Paddle(key) 无法单独添加命名空间头( 它可以使用 customHeaders),这样 将 API 密钥映射到命名空间 : PUT /__admin/credentials {"credentials": {"<PADDLE_API_KEY>": "<namespace>"}}此外 x-mockingbird-namespace,或一个 /__admin/ns/<name> 基础 URL 前缀 (单位:千美元)meta.pagination.next 留着吧.

故意不模拟

• 税取而取之. 结转共计 tax: "0" 财务报告和审定财务报表 discount: "0" 无论地址或 tax_mode;没有折扣、贴现组或调整(退款、贷项),没有 贷方余额. unit_price_overrides 以地址为国为荣.
• 作礼. 用 a 更改订阅项目 *_immediately 模式账单 变化会增加全额,不计入其去除的内容;下期模式现在不计入. PATCH /subscriptions/{id}/preview 财务报告和审定财务报表 …/charge/preview 没有支持.
• 主机取出,客户端门户页面和Paddle.js. checkout.url, (中文(简体) ), management_urls 和门户网站会话链接是URL,而不是页面; POST /__admin/checkout 财务报告和审定财务报表 …/pay 替换 结账. POST /customers/{id}/portal-sessions 返回临时 https 会话链接.
• 付款方法和付款方法的改变、付款、报告、模拟、发票 订正案、 imported 事件、 API 关键事件和客户端符号.
• 通知目的地 是销售商API(GET|POST /notification-settings, (中文(简体) ), GET|PATCH /notification-settings/{id}) (中文(简体) ). 活动 url 目的地随其 拥有 pdl_ntfset_… 暗号 秘诀只在创建时返回. --webhook-url 财务报告和审定财务报表 PUT /__admin/webhook-endpoints 作为额外接收者,不由供应商名单所取代.
• 时间. 没有东西能靠自己续约: …/renew (或 …/payment-failed当测试时 时钟到达 next_billed_at重试过去到期的订阅时间表不是模拟的.
• 费率限额除通过 rate_limited。遗留(2025年前)API的关键格式是 和其他钥匙一样被接受.

API 密码

部分 嘲笑鸟。 。 。 .