@pithy-sh/payments 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (402) hide show
  1. package/dist/admin/coverage.d.ts +35 -0
  2. package/dist/admin/coverage.d.ts.map +1 -0
  3. package/dist/admin/coverage.js +56 -0
  4. package/dist/admin/read.d.ts +222 -0
  5. package/dist/admin/read.d.ts.map +1 -0
  6. package/dist/admin/read.js +159 -0
  7. package/dist/audit/actions.d.ts +211 -0
  8. package/dist/audit/actions.d.ts.map +1 -0
  9. package/dist/audit/actions.js +211 -0
  10. package/dist/capability.d.ts +72 -0
  11. package/dist/capability.d.ts.map +1 -0
  12. package/dist/capability.js +228 -0
  13. package/dist/client/api.d.ts +435 -0
  14. package/dist/client/api.d.ts.map +1 -0
  15. package/dist/client/api.js +415 -0
  16. package/dist/client/checkout.d.ts +144 -0
  17. package/dist/client/checkout.d.ts.map +1 -0
  18. package/dist/client/checkout.js +173 -0
  19. package/dist/client/fixtures/price-preview-de.js +89 -0
  20. package/dist/client/fixtures/price-preview-gb.js +89 -0
  21. package/dist/client/fixtures/price-preview-jp-yen.js +89 -0
  22. package/dist/client/fixtures/price-preview-us-country-only.js +89 -0
  23. package/dist/client/fixtures/price-preview-us-new-york.js +89 -0
  24. package/dist/client/fixtures/pricePreview.d.ts +54 -0
  25. package/dist/client/fixtures/pricePreview.d.ts.map +1 -0
  26. package/dist/client/fixtures/pricePreview.js +61 -0
  27. package/dist/client/hooks.d.ts +235 -0
  28. package/dist/client/hooks.d.ts.map +1 -0
  29. package/dist/client/hooks.js +428 -0
  30. package/dist/client/paddle.d.ts +433 -0
  31. package/dist/client/paddle.d.ts.map +1 -0
  32. package/dist/client/paddle.js +391 -0
  33. package/dist/client/paddleCache.d.ts +123 -0
  34. package/dist/client/paddleCache.d.ts.map +1 -0
  35. package/dist/client/paddleCache.js +159 -0
  36. package/dist/client/paddlePrices.d.ts +94 -0
  37. package/dist/client/paddlePrices.d.ts.map +1 -0
  38. package/dist/client/paddlePrices.js +55 -0
  39. package/dist/client/paddlePricesTag.d.ts +127 -0
  40. package/dist/client/paddlePricesTag.d.ts.map +1 -0
  41. package/dist/client/paddlePricesTag.js +207 -0
  42. package/dist/client/projection.d.ts +128 -0
  43. package/dist/client/projection.d.ts.map +1 -0
  44. package/dist/client/projection.js +0 -0
  45. package/dist/client/test-utils/cacheStore.d.ts +18 -0
  46. package/dist/client/test-utils/cacheStore.d.ts.map +1 -0
  47. package/dist/client/test-utils/cacheStore.js +42 -0
  48. package/dist/client/wholeUnits.d.ts +18 -0
  49. package/dist/client/wholeUnits.d.ts.map +1 -0
  50. package/dist/client/wholeUnits.js +120 -0
  51. package/dist/config/config.d.ts +238 -0
  52. package/dist/config/config.d.ts.map +1 -0
  53. package/dist/config/config.js +249 -0
  54. package/dist/data/discount.d.ts +127 -0
  55. package/dist/data/discount.d.ts.map +1 -0
  56. package/dist/data/discount.js +91 -0
  57. package/dist/data/entitlement.d.ts +43 -0
  58. package/dist/data/entitlement.d.ts.map +1 -0
  59. package/dist/data/entitlement.js +43 -0
  60. package/dist/data/money.d.ts +15 -0
  61. package/dist/data/money.d.ts.map +1 -0
  62. package/dist/data/money.js +76 -0
  63. package/dist/data/pause.d.ts +133 -0
  64. package/dist/data/pause.d.ts.map +1 -0
  65. package/dist/data/pause.js +63 -0
  66. package/dist/data/providerAccount.d.ts +40 -0
  67. package/dist/data/providerAccount.d.ts.map +1 -0
  68. package/dist/data/providerAccount.js +34 -0
  69. package/dist/data/purchase.d.ts +107 -0
  70. package/dist/data/purchase.d.ts.map +1 -0
  71. package/dist/data/purchase.js +77 -0
  72. package/dist/data/rail.d.ts +74 -0
  73. package/dist/data/rail.d.ts.map +1 -0
  74. package/dist/data/rail.js +74 -0
  75. package/dist/data/reconcileRun.d.ts +120 -0
  76. package/dist/data/reconcileRun.d.ts.map +1 -0
  77. package/dist/data/reconcileRun.js +120 -0
  78. package/dist/data/renderMoney.d.ts +85 -0
  79. package/dist/data/renderMoney.d.ts.map +1 -0
  80. package/dist/data/renderMoney.js +146 -0
  81. package/dist/data/status.d.ts +58 -0
  82. package/dist/data/status.d.ts.map +1 -0
  83. package/dist/data/status.js +68 -0
  84. package/dist/data/subject.d.ts +111 -0
  85. package/dist/data/subject.d.ts.map +1 -0
  86. package/dist/data/subject.js +125 -0
  87. package/dist/data/subscription.d.ts +624 -0
  88. package/dist/data/subscription.d.ts.map +1 -0
  89. package/dist/data/subscription.js +497 -0
  90. package/dist/data/syncCursor.d.ts +33 -0
  91. package/dist/data/syncCursor.d.ts.map +1 -0
  92. package/dist/data/syncCursor.js +29 -0
  93. package/dist/data/tables.d.ts +37 -0
  94. package/dist/data/tables.d.ts.map +1 -0
  95. package/dist/data/tables.js +44 -0
  96. package/dist/data/webhookEvent.d.ts +134 -0
  97. package/dist/data/webhookEvent.d.ts.map +1 -0
  98. package/dist/data/webhookEvent.js +128 -0
  99. package/dist/entitlement/manual.d.ts +101 -0
  100. package/dist/entitlement/manual.d.ts.map +1 -0
  101. package/dist/entitlement/manual.js +84 -0
  102. package/dist/entitlement/resolver.d.ts +60 -0
  103. package/dist/entitlement/resolver.d.ts.map +1 -0
  104. package/dist/entitlement/resolver.js +101 -0
  105. package/dist/entitlement/subjectSeam.d.ts +102 -0
  106. package/dist/entitlement/subjectSeam.d.ts.map +1 -0
  107. package/dist/entitlement/subjectSeam.js +85 -0
  108. package/dist/error/errors.d.ts +247 -0
  109. package/dist/error/errors.d.ts.map +1 -0
  110. package/dist/error/errors.js +326 -0
  111. package/dist/grants/apply.d.ts +74 -0
  112. package/dist/grants/apply.d.ts.map +1 -0
  113. package/dist/grants/apply.js +148 -0
  114. package/dist/grants/clawback.d.ts +43 -0
  115. package/dist/grants/clawback.d.ts.map +1 -0
  116. package/dist/grants/clawback.js +71 -0
  117. package/dist/grants/ledgerSeam.d.ts +89 -0
  118. package/dist/grants/ledgerSeam.d.ts.map +1 -0
  119. package/dist/grants/ledgerSeam.js +66 -0
  120. package/dist/http/dispatch.d.ts +35 -0
  121. package/dist/http/dispatch.d.ts.map +1 -0
  122. package/dist/http/dispatch.js +40 -0
  123. package/dist/http/guards.d.ts +43 -0
  124. package/dist/http/guards.d.ts.map +1 -0
  125. package/dist/http/guards.js +52 -0
  126. package/dist/http/manifestConfig.d.ts +38 -0
  127. package/dist/http/manifestConfig.d.ts.map +1 -0
  128. package/dist/http/manifestConfig.js +49 -0
  129. package/dist/http/responses.d.ts +1455 -0
  130. package/dist/http/responses.d.ts.map +1 -0
  131. package/dist/http/responses.js +728 -0
  132. package/dist/http/routes.d.ts +315 -0
  133. package/dist/http/routes.d.ts.map +1 -0
  134. package/dist/http/routes.js +1966 -0
  135. package/dist/http/schemas.d.ts +404 -0
  136. package/dist/http/schemas.d.ts.map +1 -0
  137. package/dist/http/schemas.js +359 -0
  138. package/dist/http/scopes.d.ts +160 -0
  139. package/dist/http/scopes.d.ts.map +1 -0
  140. package/dist/http/scopes.js +240 -0
  141. package/dist/http/view.d.ts +96 -0
  142. package/dist/http/view.d.ts.map +1 -0
  143. package/dist/http/view.js +170 -0
  144. package/dist/http/webhookGuard.d.ts +109 -0
  145. package/dist/http/webhookGuard.d.ts.map +1 -0
  146. package/dist/http/webhookGuard.js +206 -0
  147. package/dist/index.d.ts +64 -0
  148. package/dist/index.d.ts.map +1 -0
  149. package/dist/index.js +43 -0
  150. package/dist/migrations/0001_purchases.d.ts +35 -0
  151. package/dist/migrations/0001_purchases.d.ts.map +1 -0
  152. package/dist/migrations/0001_purchases.js +80 -0
  153. package/dist/pricing/location.d.ts +138 -0
  154. package/dist/pricing/location.d.ts.map +1 -0
  155. package/dist/pricing/location.js +81 -0
  156. package/dist/pricing/visitor.d.ts +56 -0
  157. package/dist/pricing/visitor.d.ts.map +1 -0
  158. package/dist/pricing/visitor.js +35 -0
  159. package/dist/projection/event.d.ts +66 -0
  160. package/dist/projection/event.d.ts.map +1 -0
  161. package/dist/projection/event.js +45 -0
  162. package/dist/projection/orphans.d.ts +114 -0
  163. package/dist/projection/orphans.d.ts.map +1 -0
  164. package/dist/projection/orphans.js +162 -0
  165. package/dist/projection/owner.d.ts +121 -0
  166. package/dist/projection/owner.d.ts.map +1 -0
  167. package/dist/projection/owner.js +114 -0
  168. package/dist/projection/resolve.d.ts +30 -0
  169. package/dist/projection/resolve.d.ts.map +1 -0
  170. package/dist/projection/resolve.js +42 -0
  171. package/dist/projection/writer.d.ts +103 -0
  172. package/dist/projection/writer.d.ts.map +1 -0
  173. package/dist/projection/writer.js +280 -0
  174. package/dist/provision/resolvePaymentsConfig.d.ts +48 -0
  175. package/dist/provision/resolvePaymentsConfig.d.ts.map +1 -0
  176. package/dist/provision/resolvePaymentsConfig.js +41 -0
  177. package/dist/rails/apple/certs.d.ts +7 -0
  178. package/dist/rails/apple/certs.d.ts.map +1 -0
  179. package/dist/rails/apple/certs.js +8 -0
  180. package/dist/rails/apple/der.d.ts +107 -0
  181. package/dist/rails/apple/der.d.ts.map +1 -0
  182. package/dist/rails/apple/der.js +217 -0
  183. package/dist/rails/apple/fixtures/chain.d.ts +117 -0
  184. package/dist/rails/apple/fixtures/chain.d.ts.map +1 -0
  185. package/dist/rails/apple/fixtures/chain.js +289 -0
  186. package/dist/rails/apple/http.d.ts +74 -0
  187. package/dist/rails/apple/http.d.ts.map +1 -0
  188. package/dist/rails/apple/http.js +32 -0
  189. package/dist/rails/apple/jws.d.ts +17 -0
  190. package/dist/rails/apple/jws.d.ts.map +1 -0
  191. package/dist/rails/apple/jws.js +75 -0
  192. package/dist/rails/apple/notification.d.ts +116 -0
  193. package/dist/rails/apple/notification.d.ts.map +1 -0
  194. package/dist/rails/apple/notification.js +199 -0
  195. package/dist/rails/apple/rail.d.ts +25 -0
  196. package/dist/rails/apple/rail.d.ts.map +1 -0
  197. package/dist/rails/apple/rail.js +68 -0
  198. package/dist/rails/apple/serverApi.d.ts +120 -0
  199. package/dist/rails/apple/serverApi.d.ts.map +1 -0
  200. package/dist/rails/apple/serverApi.js +244 -0
  201. package/dist/rails/apple/verify.d.ts +36 -0
  202. package/dist/rails/apple/verify.d.ts.map +1 -0
  203. package/dist/rails/apple/verify.js +46 -0
  204. package/dist/rails/apple/x509.d.ts +85 -0
  205. package/dist/rails/apple/x509.d.ts.map +1 -0
  206. package/dist/rails/apple/x509.js +273 -0
  207. package/dist/rails/contract.d.ts +871 -0
  208. package/dist/rails/contract.d.ts.map +1 -0
  209. package/dist/rails/contract.js +60 -0
  210. package/dist/rails/google/fixtures/push.d.ts +71 -0
  211. package/dist/rails/google/fixtures/push.d.ts.map +1 -0
  212. package/dist/rails/google/fixtures/push.js +107 -0
  213. package/dist/rails/google/http.d.ts +77 -0
  214. package/dist/rails/google/http.d.ts.map +1 -0
  215. package/dist/rails/google/http.js +39 -0
  216. package/dist/rails/google/jwt.d.ts +53 -0
  217. package/dist/rails/google/jwt.d.ts.map +1 -0
  218. package/dist/rails/google/jwt.js +94 -0
  219. package/dist/rails/google/oidc.d.ts +112 -0
  220. package/dist/rails/google/oidc.d.ts.map +1 -0
  221. package/dist/rails/google/oidc.js +179 -0
  222. package/dist/rails/google/playApi.d.ts +188 -0
  223. package/dist/rails/google/playApi.d.ts.map +1 -0
  224. package/dist/rails/google/playApi.js +350 -0
  225. package/dist/rails/google/rail.d.ts +57 -0
  226. package/dist/rails/google/rail.d.ts.map +1 -0
  227. package/dist/rails/google/rail.js +70 -0
  228. package/dist/rails/google/rtdn.d.ts +105 -0
  229. package/dist/rails/google/rtdn.d.ts.map +1 -0
  230. package/dist/rails/google/rtdn.js +179 -0
  231. package/dist/rails/google/verify.d.ts +20 -0
  232. package/dist/rails/google/verify.d.ts.map +1 -0
  233. package/dist/rails/google/verify.js +76 -0
  234. package/dist/rails/lemonSqueezy/api.d.ts +92 -0
  235. package/dist/rails/lemonSqueezy/api.d.ts.map +1 -0
  236. package/dist/rails/lemonSqueezy/api.js +121 -0
  237. package/dist/rails/lemonSqueezy/checkout.d.ts +52 -0
  238. package/dist/rails/lemonSqueezy/checkout.d.ts.map +1 -0
  239. package/dist/rails/lemonSqueezy/checkout.js +84 -0
  240. package/dist/rails/lemonSqueezy/discounts.d.ts +50 -0
  241. package/dist/rails/lemonSqueezy/discounts.d.ts.map +1 -0
  242. package/dist/rails/lemonSqueezy/discounts.js +75 -0
  243. package/dist/rails/lemonSqueezy/fixtures/events.d.ts +56 -0
  244. package/dist/rails/lemonSqueezy/fixtures/events.d.ts.map +1 -0
  245. package/dist/rails/lemonSqueezy/fixtures/events.js +144 -0
  246. package/dist/rails/lemonSqueezy/objects.d.ts +229 -0
  247. package/dist/rails/lemonSqueezy/objects.d.ts.map +1 -0
  248. package/dist/rails/lemonSqueezy/objects.js +379 -0
  249. package/dist/rails/lemonSqueezy/portal.d.ts +35 -0
  250. package/dist/rails/lemonSqueezy/portal.d.ts.map +1 -0
  251. package/dist/rails/lemonSqueezy/portal.js +18 -0
  252. package/dist/rails/lemonSqueezy/pricing.d.ts +25 -0
  253. package/dist/rails/lemonSqueezy/pricing.d.ts.map +1 -0
  254. package/dist/rails/lemonSqueezy/pricing.js +54 -0
  255. package/dist/rails/lemonSqueezy/rail.d.ts +41 -0
  256. package/dist/rails/lemonSqueezy/rail.d.ts.map +1 -0
  257. package/dist/rails/lemonSqueezy/rail.js +67 -0
  258. package/dist/rails/lemonSqueezy/read.d.ts +28 -0
  259. package/dist/rails/lemonSqueezy/read.d.ts.map +1 -0
  260. package/dist/rails/lemonSqueezy/read.js +37 -0
  261. package/dist/rails/lemonSqueezy/refresh.d.ts +42 -0
  262. package/dist/rails/lemonSqueezy/refresh.d.ts.map +1 -0
  263. package/dist/rails/lemonSqueezy/refresh.js +40 -0
  264. package/dist/rails/lemonSqueezy/signature.d.ts +56 -0
  265. package/dist/rails/lemonSqueezy/signature.d.ts.map +1 -0
  266. package/dist/rails/lemonSqueezy/signature.js +92 -0
  267. package/dist/rails/lemonSqueezy/verify.d.ts +33 -0
  268. package/dist/rails/lemonSqueezy/verify.d.ts.map +1 -0
  269. package/dist/rails/lemonSqueezy/verify.js +41 -0
  270. package/dist/rails/lemonSqueezy/webhook.d.ts +53 -0
  271. package/dist/rails/lemonSqueezy/webhook.d.ts.map +1 -0
  272. package/dist/rails/lemonSqueezy/webhook.js +179 -0
  273. package/dist/rails/paddle/adjustments.d.ts +60 -0
  274. package/dist/rails/paddle/adjustments.d.ts.map +1 -0
  275. package/dist/rails/paddle/adjustments.js +66 -0
  276. package/dist/rails/paddle/api.d.ts +138 -0
  277. package/dist/rails/paddle/api.d.ts.map +1 -0
  278. package/dist/rails/paddle/api.js +152 -0
  279. package/dist/rails/paddle/checkout.d.ts +69 -0
  280. package/dist/rails/paddle/checkout.d.ts.map +1 -0
  281. package/dist/rails/paddle/checkout.js +100 -0
  282. package/dist/rails/paddle/discounts.d.ts +67 -0
  283. package/dist/rails/paddle/discounts.d.ts.map +1 -0
  284. package/dist/rails/paddle/discounts.js +73 -0
  285. package/dist/rails/paddle/events.d.ts +140 -0
  286. package/dist/rails/paddle/events.d.ts.map +1 -0
  287. package/dist/rails/paddle/events.js +183 -0
  288. package/dist/rails/paddle/fixtures/browserForged.d.ts +42 -0
  289. package/dist/rails/paddle/fixtures/browserForged.d.ts.map +1 -0
  290. package/dist/rails/paddle/fixtures/browserForged.js +52 -0
  291. package/dist/rails/paddle/fixtures/pausedSubscription.d.ts +78 -0
  292. package/dist/rails/paddle/fixtures/pausedSubscription.d.ts.map +1 -0
  293. package/dist/rails/paddle/fixtures/pausedSubscription.js +76 -0
  294. package/dist/rails/paddle/objects.d.ts +519 -0
  295. package/dist/rails/paddle/objects.d.ts.map +1 -0
  296. package/dist/rails/paddle/objects.js +588 -0
  297. package/dist/rails/paddle/portal.d.ts +45 -0
  298. package/dist/rails/paddle/portal.d.ts.map +1 -0
  299. package/dist/rails/paddle/portal.js +42 -0
  300. package/dist/rails/paddle/rail.d.ts +55 -0
  301. package/dist/rails/paddle/rail.d.ts.map +1 -0
  302. package/dist/rails/paddle/rail.js +117 -0
  303. package/dist/rails/paddle/read.d.ts +53 -0
  304. package/dist/rails/paddle/read.d.ts.map +1 -0
  305. package/dist/rails/paddle/read.js +66 -0
  306. package/dist/rails/paddle/recorded.d.ts +49 -0
  307. package/dist/rails/paddle/recorded.d.ts.map +1 -0
  308. package/dist/rails/paddle/recorded.js +79 -0
  309. package/dist/rails/paddle/refresh.d.ts +54 -0
  310. package/dist/rails/paddle/refresh.d.ts.map +1 -0
  311. package/dist/rails/paddle/refresh.js +94 -0
  312. package/dist/rails/paddle/refund.d.ts +82 -0
  313. package/dist/rails/paddle/refund.d.ts.map +1 -0
  314. package/dist/rails/paddle/refund.js +175 -0
  315. package/dist/rails/paddle/signature.d.ts +83 -0
  316. package/dist/rails/paddle/signature.d.ts.map +1 -0
  317. package/dist/rails/paddle/signature.js +163 -0
  318. package/dist/rails/paddle/subscription.d.ts +137 -0
  319. package/dist/rails/paddle/subscription.d.ts.map +1 -0
  320. package/dist/rails/paddle/subscription.js +538 -0
  321. package/dist/rails/paddle/verify.d.ts +46 -0
  322. package/dist/rails/paddle/verify.d.ts.map +1 -0
  323. package/dist/rails/paddle/verify.js +43 -0
  324. package/dist/rails/paddle/webhook.d.ts +98 -0
  325. package/dist/rails/paddle/webhook.d.ts.map +1 -0
  326. package/dist/rails/paddle/webhook.js +181 -0
  327. package/dist/rails/providers.d.ts +73 -0
  328. package/dist/rails/providers.d.ts.map +1 -0
  329. package/dist/rails/providers.js +62 -0
  330. package/dist/rails/stripe/api.d.ts +118 -0
  331. package/dist/rails/stripe/api.d.ts.map +1 -0
  332. package/dist/rails/stripe/api.js +153 -0
  333. package/dist/rails/stripe/checkout.d.ts +60 -0
  334. package/dist/rails/stripe/checkout.d.ts.map +1 -0
  335. package/dist/rails/stripe/checkout.js +86 -0
  336. package/dist/rails/stripe/discounts.d.ts +50 -0
  337. package/dist/rails/stripe/discounts.d.ts.map +1 -0
  338. package/dist/rails/stripe/discounts.js +87 -0
  339. package/dist/rails/stripe/fixtures/events.d.ts +64 -0
  340. package/dist/rails/stripe/fixtures/events.d.ts.map +1 -0
  341. package/dist/rails/stripe/fixtures/events.js +67 -0
  342. package/dist/rails/stripe/objects.d.ts +237 -0
  343. package/dist/rails/stripe/objects.d.ts.map +1 -0
  344. package/dist/rails/stripe/objects.js +389 -0
  345. package/dist/rails/stripe/portal.d.ts +29 -0
  346. package/dist/rails/stripe/portal.d.ts.map +1 -0
  347. package/dist/rails/stripe/portal.js +41 -0
  348. package/dist/rails/stripe/pricing.d.ts +25 -0
  349. package/dist/rails/stripe/pricing.d.ts.map +1 -0
  350. package/dist/rails/stripe/pricing.js +68 -0
  351. package/dist/rails/stripe/rail.d.ts +28 -0
  352. package/dist/rails/stripe/rail.d.ts.map +1 -0
  353. package/dist/rails/stripe/rail.js +81 -0
  354. package/dist/rails/stripe/refresh.d.ts +33 -0
  355. package/dist/rails/stripe/refresh.d.ts.map +1 -0
  356. package/dist/rails/stripe/refresh.js +21 -0
  357. package/dist/rails/stripe/signature.d.ts +71 -0
  358. package/dist/rails/stripe/signature.d.ts.map +1 -0
  359. package/dist/rails/stripe/signature.js +92 -0
  360. package/dist/rails/stripe/verify.d.ts +15 -0
  361. package/dist/rails/stripe/verify.d.ts.map +1 -0
  362. package/dist/rails/stripe/verify.js +63 -0
  363. package/dist/rails/stripe/webhook.d.ts +26 -0
  364. package/dist/rails/stripe/webhook.d.ts.map +1 -0
  365. package/dist/rails/stripe/webhook.js +31 -0
  366. package/dist/secret/registry.d.ts +192 -0
  367. package/dist/secret/registry.d.ts.map +1 -0
  368. package/dist/secret/registry.js +154 -0
  369. package/dist/seeds/example.d.ts +3 -0
  370. package/dist/seeds/example.d.ts.map +1 -0
  371. package/dist/seeds/example.js +171 -0
  372. package/dist/version.generated.d.ts +5 -0
  373. package/dist/version.generated.d.ts.map +1 -0
  374. package/dist/version.generated.js +7 -0
  375. package/dist/workflows/paddleSweep.d.ts +175 -0
  376. package/dist/workflows/paddleSweep.d.ts.map +1 -0
  377. package/dist/workflows/paddleSweep.js +433 -0
  378. package/dist/workflows/railAccess.d.ts +48 -0
  379. package/dist/workflows/railAccess.d.ts.map +1 -0
  380. package/dist/workflows/railAccess.js +36 -0
  381. package/dist/workflows/reconcile.d.ts +161 -0
  382. package/dist/workflows/reconcile.d.ts.map +1 -0
  383. package/dist/workflows/reconcile.js +352 -0
  384. package/dist/workflows/report.d.ts +28 -0
  385. package/dist/workflows/report.d.ts.map +1 -0
  386. package/dist/workflows/report.js +54 -0
  387. package/dist/workflows/retryPolicy.d.ts +29 -0
  388. package/dist/workflows/retryPolicy.d.ts.map +1 -0
  389. package/dist/workflows/retryPolicy.js +37 -0
  390. package/dist/workflows/specs.d.ts +102 -0
  391. package/dist/workflows/specs.d.ts.map +1 -0
  392. package/dist/workflows/specs.js +84 -0
  393. package/dist/workflows/worker.d.ts +62 -0
  394. package/dist/workflows/worker.d.ts.map +1 -0
  395. package/dist/workflows/worker.js +92 -0
  396. package/dist/workflows/workerConfig.d.ts +46 -0
  397. package/dist/workflows/workerConfig.d.ts.map +1 -0
  398. package/dist/workflows/workerConfig.js +38 -0
  399. package/package.json +22 -13
  400. package/pithy.manifest.json +19 -13
  401. package/src/version.generated.ts +1 -1
  402. package/src/client/paddlePrices.iife.ts +0 -43
@@ -0,0 +1,82 @@
1
+ import { RefundRequest } from "../../data/subscription";
2
+ import type { PaymentsPaddleCredentials } from "../../secret/registry";
3
+ import type { RefundRequestInput } from "../contract";
4
+ import { type PaddleEnvironment, type PaddleHttpFetch } from "./api";
5
+ /**
6
+ * Asking Paddle to give a subscriber's payments back — the fourth verb of #465.
7
+ *
8
+ * ## Three facts about Paddle shaped every line of this
9
+ *
10
+ * **1. It is a request, not a completion.** `POST /adjustments` creates an adjustment, and on a live
11
+ * account Paddle holds most refunds at `pending_approval` until a person there reviews them; the sandbox
12
+ * approves on its own, roughly ten minutes later. So nothing here says the money moved, nothing revokes an
13
+ * entitlement, and nothing writes a purchase row. An approved refund arrives as a webhook, and
14
+ * `adjustments.ts` and the projection writer already act on it — they are the only things that do.
15
+ * Revoking on the *request* would take access from a customer whose refund Paddle then rejects, leaving
16
+ * them with neither the money nor the product.
17
+ *
18
+ * **2. Refunds attach to a transaction, not to a subscription.** There is no endpoint that refunds a
19
+ * subscription, so this raises one adjustment per transaction and reports one outcome per transaction.
20
+ * The case is ordinary: a customer who joined on Solo at 6.00, upgraded to Team on day 10 for a 65.82
21
+ * proration and cancels on day 13 has paid twice, and a refund policy owes them both.
22
+ *
23
+ * **3. They do not stack.** Paddle: *"You can't create an adjustment for a transaction that has a refund
24
+ * that's pending approval."* Learning that from Paddle, mid-set, after other adjustments have already been
25
+ * raised, is the worst possible place to learn it — so it is decided here, from the transaction's own
26
+ * `include=adjustments`, before anything is sent.
27
+ *
28
+ * ## The guarantee, and the line it is split at
29
+ *
30
+ * All-or-nothing across the whole set **cannot be built**: Paddle offers no batch adjustment and no delete,
31
+ * so once the first one is at `pending_approval` nothing un-raises it. The guarantee is therefore split at
32
+ * the only line that is real — whether this call has written anything yet:
33
+ *
34
+ * - **Before the first write**, every transaction is read and checked, and anything that makes one
35
+ * unrefundable refuses the *whole request* with `payments/subscription_change_refused` having sent
36
+ * nothing. {@link MAX_PADDLE_REFUND_TRANSACTIONS} is enforced first, for the same reason.
37
+ * - **After the first write**, nothing throws. Every remaining failure becomes a `failed` outcome, because
38
+ * an error raised over a state where money is already moving is precisely the silent partial this module
39
+ * is designed against.
40
+ *
41
+ * A refund that is already standing is neither: it is reported as `already_requested` and no call is made.
42
+ * That is the per-payment form of the no-op rule the other four verbs follow — a retried write must not
43
+ * become a second refund, and a 409 for the state the caller asked for is simply wrong.
44
+ *
45
+ * ## The window is not here
46
+ *
47
+ * How long a customer has to ask for their money back is the **adopter's** policy, with a company's
48
+ * commercial decisions behind it. This module refunds what it is handed and hard-codes no window; the
49
+ * adopter's screen decides which button exists.
50
+ */
51
+ /** What every call here needs: the credentials, which Paddle account, and the transport. */
52
+ export interface PaddleRefundOptions {
53
+ /** The rail's credentials. The API key is read at the point of need and never cached. */
54
+ credentials: PaymentsPaddleCredentials;
55
+ /** Which Paddle account to reach. */
56
+ environment: PaddleEnvironment;
57
+ /** The HTTP seam. Defaults to the runtime's `fetch`. */
58
+ transport?: PaddleHttpFetch;
59
+ }
60
+ /**
61
+ * The most transactions one request will refund.
62
+ *
63
+ * **A bound on subrequests, not a policy.** Each transaction costs two calls — a read and a create — and a
64
+ * Worker's subrequest budget is finite. A call that runs out of it half way through is a partial by
65
+ * another name, and the one thing this module will not produce. So the size is checked before anything is
66
+ * read, and a set that is too large is refused whole.
67
+ *
68
+ * Twelve, and the two ends of the range are what pick it. Any refund window an adopter would set holds one
69
+ * or two transactions on a monthly plan — the recorded upgrade case is two — so nothing legitimate comes
70
+ * near it. And twenty-four calls sits well inside the budget with room for everything else a request does.
71
+ * An adopter reversing a whole subscription history is doing something else, and the Paddle dashboard is
72
+ * the tool for it.
73
+ */
74
+ export declare const MAX_PADDLE_REFUND_TRANSACTIONS = 12;
75
+ /**
76
+ * Ask Paddle to refund these payments in full, and report what became of each.
77
+ *
78
+ * The report is **total** over the input — one outcome per purchase, in the order given — because a report
79
+ * shorter than the set is what a silent partial looks like. See {@link RefundRequest}.
80
+ */
81
+ export declare function requestPaddleRefunds(input: RefundRequestInput, options: PaddleRefundOptions): Promise<RefundRequest>;
82
+ //# sourceMappingURL=refund.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/refund.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAuD,MAAM,yBAAyB,CAAC;AAE7G,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAoD,MAAM,OAAO,CAAC;AAIvH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAoGjD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAyFxB"}
@@ -0,0 +1,175 @@
1
+ import { PaymentsProviderUnavailableError, PaymentsSubscriptionChangeRefusedError } from "../../error/errors.js";
2
+ import { RefundRequest } from "../../data/subscription.js";
3
+ import { paddleHttpFetch, paddleJson, redactPaddleSecrets } from "./api.js";
4
+ import { PaddleAdjustment } from "./objects.js";
5
+ import { PADDLE_ADJUSTMENTS_INCLUDE, readTransaction } from "./read.js";
6
+ import { REVOKING_ACTIONS } from "./adjustments.js";
7
+ //#region src/rails/paddle/refund.ts
8
+ /**
9
+ * The most transactions one request will refund.
10
+ *
11
+ * **A bound on subrequests, not a policy.** Each transaction costs two calls — a read and a create — and a
12
+ * Worker's subrequest budget is finite. A call that runs out of it half way through is a partial by
13
+ * another name, and the one thing this module will not produce. So the size is checked before anything is
14
+ * read, and a set that is too large is refused whole.
15
+ *
16
+ * Twelve, and the two ends of the range are what pick it. Any refund window an adopter would set holds one
17
+ * or two transactions on a monthly plan — the recorded upgrade case is two — so nothing legitimate comes
18
+ * near it. And twenty-four calls sits well inside the budget with room for everything else a request does.
19
+ * An adopter reversing a whole subscription history is doing something else, and the Paddle dashboard is
20
+ * the tool for it.
21
+ */
22
+ const MAX_PADDLE_REFUND_TRANSACTIONS = 12;
23
+ /** What Paddle sends and what this module states. Anything else is `unknown` — see the enum's own doc. */
24
+ const REFUND_STATUS = {
25
+ pending_approval: "awaiting_review",
26
+ approved: "approved",
27
+ rejected: "rejected",
28
+ reversed: "reversed"
29
+ };
30
+ /** The request cannot be honored, and nothing has been sent. 409, with the reason in `detail`. */
31
+ function refuse(detail) {
32
+ throw new PaymentsSubscriptionChangeRefusedError({
33
+ message: "That refund cannot be requested.",
34
+ action: "Re-read the subscription and the payments on it, then ask for a refund the present state allows.",
35
+ detail
36
+ });
37
+ }
38
+ /** The transaction this purchase row names, or null when it names none. */
39
+ function transactionIdOf(purchase) {
40
+ const id = purchase.providerTransactionId;
41
+ return id.startsWith("txn_") ? id : null;
42
+ }
43
+ /**
44
+ * The adjustment already standing against this transaction, or undefined.
45
+ *
46
+ * **Two cases block, and one deliberately does not.** A `refund` awaiting review blocks because Paddle
47
+ * refuses a second one outright. An *approved* revoking adjustment — {@link REVOKING_ACTIONS}, so a
48
+ * chargeback counts — blocks because the money is already back and a second refund would send it twice.
49
+ *
50
+ * A **rejected** refund does not block. A reviewer at Paddle turning one down is not a permanent bar, and
51
+ * treating it as one would make somebody else's decision final over money the adopter has chosen to give
52
+ * back. Neither does a `credit` against a balance, which is not a revocation — the same line
53
+ * `adjustments.ts` draws, read from its set rather than restated here.
54
+ */
55
+ function standingRefund(transaction) {
56
+ return (transaction.adjustments ?? []).find((one) => {
57
+ if (one.status === "pending_approval") return one.action === "refund";
58
+ return one.status === "approved" && REVOKING_ACTIONS.has(one.action);
59
+ });
60
+ }
61
+ /**
62
+ * Read and check every payment, or refuse the whole request. **No write happens inside this.**
63
+ *
64
+ * A transaction Paddle does not know, or one it will not refund, refuses the request rather than becoming
65
+ * an outcome: it is knowable in advance, and everything knowable in advance is decided while refusing is
66
+ * still free. A store that cannot be *reached* raises `payments/provider_unavailable` from `paddleJson`
67
+ * and is left to propagate, because nothing about the subscription is wrong and telling a customer their
68
+ * refund was refused over a timeout is a true sentence about the wrong thing.
69
+ */
70
+ async function check(purchases, options) {
71
+ const read = {
72
+ credentials: options.credentials,
73
+ environment: options.environment,
74
+ transport: options.transport ?? paddleHttpFetch
75
+ };
76
+ const checked = [];
77
+ for (const purchase of purchases) {
78
+ const transactionId = transactionIdOf(purchase);
79
+ if (transactionId === null) refuse(`Purchase ${purchase.id} names ${JSON.stringify(purchase.providerTransactionId)}, which is not a Paddle transaction. A refund attaches to a transaction, and a subscription is not one.`);
80
+ const transaction = await readTransaction(transactionId, read, PADDLE_ADJUSTMENTS_INCLUDE);
81
+ if (transaction === void 0) refuse(`Paddle has no transaction ${transactionId}, so there is nothing on it to refund.`);
82
+ if (transaction.status !== "completed") refuse(`Paddle reports transaction ${transactionId} as ${JSON.stringify(transaction.status)}, and only a completed transaction can be refunded. Nothing in this set was raised.`);
83
+ checked.push({
84
+ purchase,
85
+ transactionId,
86
+ standing: standingRefund(transaction)
87
+ });
88
+ }
89
+ return checked;
90
+ }
91
+ /** Paddle's status, as this package states it. An unmapped one is `unknown` — never a throw. */
92
+ function statusOf(stated) {
93
+ return (typeof stated === "string" ? REFUND_STATUS[stated] : void 0) ?? "unknown";
94
+ }
95
+ /**
96
+ * Ask Paddle to refund these payments in full, and report what became of each.
97
+ *
98
+ * The report is **total** over the input — one outcome per purchase, in the order given — because a report
99
+ * shorter than the set is what a silent partial looks like. See {@link RefundRequest}.
100
+ */
101
+ async function requestPaddleRefunds(input, options) {
102
+ const { purchases, reason } = input;
103
+ if (purchases.length === 0) refuse("No payment was named, so there is nothing to refund.");
104
+ if (purchases.length > 12) refuse(`${purchases.length} payments were named and one request refunds at most 12. A call that runs out of budget half way through is a partial refund nobody asked for, so the whole set is refused before anything is read.`);
105
+ const checked = await check(purchases, options);
106
+ const transport = options.transport ?? paddleHttpFetch;
107
+ const outcomes = [];
108
+ let raised = 0;
109
+ for (const one of checked) {
110
+ if (one.standing !== void 0) {
111
+ outcomes.push({
112
+ outcome: "already_requested",
113
+ purchaseId: one.purchase.id,
114
+ adjustmentId: one.standing.id,
115
+ status: statusOf(one.standing.status)
116
+ });
117
+ continue;
118
+ }
119
+ let answer;
120
+ try {
121
+ answer = (await paddleJson(transport, "/adjustments", {
122
+ what: `a refund on transaction ${one.transactionId} (this key needs the adjustment.write permission)`,
123
+ apiKey: options.credentials.apiKey,
124
+ environment: options.environment,
125
+ method: "POST",
126
+ body: {
127
+ action: "refund",
128
+ type: "full",
129
+ transaction_id: one.transactionId,
130
+ reason
131
+ }
132
+ }))?.data;
133
+ } catch (error) {
134
+ if (raised === 0) throw error;
135
+ outcomes.push({
136
+ outcome: "failed",
137
+ purchaseId: one.purchase.id,
138
+ reason: said(error, one.transactionId)
139
+ });
140
+ continue;
141
+ }
142
+ const parsed = PaddleAdjustment.safeParse(answer);
143
+ if (!parsed.success) {
144
+ if (raised === 0) throw new PaymentsProviderUnavailableError({ detail: `Paddle answered the refund of transaction ${one.transactionId} in a shape this build cannot read.` });
145
+ outcomes.push({
146
+ outcome: "failed",
147
+ purchaseId: one.purchase.id,
148
+ reason: `Paddle answered the refund of transaction ${one.transactionId} in a shape this build cannot read, so whether one was raised is unknown. Check the transaction's adjustments at Paddle.`
149
+ });
150
+ continue;
151
+ }
152
+ raised += 1;
153
+ outcomes.push({
154
+ outcome: "requested",
155
+ purchaseId: one.purchase.id,
156
+ adjustmentId: parsed.data.id,
157
+ status: statusOf(parsed.data.status)
158
+ });
159
+ }
160
+ return RefundRequest.parse({ outcomes });
161
+ }
162
+ /**
163
+ * What went wrong, in an operator's words, with anything key-shaped blanked.
164
+ *
165
+ * A reported reason lands in an audit trail and in a log, and the API key is in every request this module
166
+ * makes. `paddleJson` has already put Paddle's own sentence in `detail` and redacted it once; this redacts
167
+ * again rather than trusting that, because the cost of the second pass is nothing and the cost of the
168
+ * assumption being wrong is a credential in a long-lived queryable table.
169
+ */
170
+ function said(error, transactionId) {
171
+ const detail = error?.payload?.detail;
172
+ return `Paddle would not refund transaction ${transactionId}.${typeof detail === "string" && detail !== "" ? ` ${redactPaddleSecrets(detail)}` : ""}`;
173
+ }
174
+ //#endregion
175
+ export { MAX_PADDLE_REFUND_TRANSACTIONS, requestPaddleRefunds };
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Paddle's authenticity proof: a timestamp and one or more HMACs, in one header.
3
+ *
4
+ * `Paddle-Signature: ts=1770000000;h1=5257a8…` — elements split on `;`, key and value split on `=`, and
5
+ * the signed payload is the timestamp, **a colon**, and the exact received body. HMAC-SHA256, hex,
6
+ * keyed with the notification destination's `pdl_ntfset_…` secret.
7
+ *
8
+ * ## Why this is a second verifier and not a widened core primitive
9
+ *
10
+ * The issue that scoped this work said Paddle "fits the existing timestamped shape of
11
+ * `requireSignedWebhook` with no new scheme." It does not, and the difference is two characters that
12
+ * decide whether anything is verified at all. `packages/core/src/http/signedWebhook.ts` splits the header
13
+ * on `,` and builds its signed payload as `` `${timestamp}.${body}` `` — Stripe's format. Paddle uses `;`
14
+ * and `:`. Neither is a parameter, and the module doc there argues *deliberately* that the signed payload
15
+ * must never become a caller-supplied template, because a payload a caller can shape is a payload a caller
16
+ * can shape into one that matches.
17
+ *
18
+ * So there were two options, and this is the one taken out loud: generalize the core primitive — editing a
19
+ * package this issue does not scope, against its own written reasoning — or write the scheme here, as the
20
+ * Lemon Squeezy rail already did for its own. This is the sibling precedent, and it keeps the change inside
21
+ * `@pithy-sh/payments`.
22
+ *
23
+ * The cost is real and worth naming: two modules now know how to check an HMAC. What they do not share is
24
+ * a *format*, which is the part that would have had to become configurable, and a configurable format is
25
+ * how #125 shipped a `requireSignedWebhook("lemonSqueezy", …)` that structurally could not verify the
26
+ * signatures it claimed to.
27
+ *
28
+ * ## The freshness window, and why it is 300 seconds and not 5
29
+ *
30
+ * Paddle's own SDKs default to five seconds. This defaults to three hundred, and the reason is what
31
+ * replay protection actually rests on here: `UNIQUE (rail, providerEventId)` over `evt_…`, in the webhook
32
+ * guard, which is absolute. A captured delivery replayed a year later is refused because its event id is
33
+ * already recorded — no window is doing that work. What a five-second window *does* do is convert ordinary
34
+ * clock skew between a Cloudflare edge and Paddle into a dropped renewal.
35
+ *
36
+ * The window still earns its place, in both directions. It bounds how long a captured-but-never-delivered
37
+ * signature stays usable, and it refuses a far-future timestamp — either a broken clock or somebody trying
38
+ * to mint a delivery that never goes stale. Configurable, so an adopter who wants Paddle's number can set
39
+ * it.
40
+ *
41
+ * Paddle re-signs each retry attempt with a fresh `ts`, which is the only way a three-day retry window and
42
+ * a five-second SDK tolerance could both be coherent — so the window does not silently reject retries.
43
+ *
44
+ * ## What a refusal says
45
+ *
46
+ * `payments/verification_failed`, with the reason in `detail` and nothing the delivery carried — not the
47
+ * body, not the candidate signature, never the secret. The webhook guard maps this to
48
+ * `payments/webhook_unverified` (401) before anything reaches the sender, so a forger learns only that it
49
+ * failed.
50
+ */
51
+ /** The header Paddle puts its proof in. Lower case, because that is how Hono presents a header name. */
52
+ export declare const PADDLE_SIGNATURE_HEADER = "paddle-signature";
53
+ /** How long a delivery stays acceptable, by default. See the module doc for why this is not Paddle's 5. */
54
+ export declare const PADDLE_DEFAULT_FRESHNESS_SECONDS = 300;
55
+ /** What the verifier needs beyond the bytes: the secret, the clock, and the window. */
56
+ export interface VerifyPaddleSignatureOptions {
57
+ /** The notification destination's signing secret — `pdl_ntfset_…`. Never logged. */
58
+ secret: string;
59
+ /** The clock, for the freshness window. Injected so verification is deterministic. */
60
+ now: Date;
61
+ /** How many seconds either side of `now` a delivery may be dated. Undefined uses the default. */
62
+ toleranceSeconds?: number;
63
+ }
64
+ /**
65
+ * The signature Paddle would send for these bytes at this second — lower-case hex.
66
+ *
67
+ * Exported for the tests and the fixtures, which mint their own so verification is exercised for real
68
+ * rather than stubbed. Nothing in the request path signs anything: this rail only ever verifies.
69
+ */
70
+ export declare function signPaddleBody(timestamp: number, body: string, secret: string): Promise<string>;
71
+ /**
72
+ * Verify one delivery's `Paddle-Signature`. Resolves when Paddle signed these exact bytes at a moment
73
+ * inside the window, and throws `payments/verification_failed` otherwise.
74
+ *
75
+ * The comparison is `crypto.subtle.verify`, never `===` on the hex and never a hand-written loop: the
76
+ * runtime's own compare is constant-time, and a string equality on a MAC leaks how many leading bytes an
77
+ * attacker got right.
78
+ *
79
+ * The freshness check runs **before** the MACs. A stale delivery is refused whatever it carries, and
80
+ * refusing it first means an expired capture does not buy an attacker even one HMAC of work.
81
+ */
82
+ export declare function verifyPaddleSignature(body: string, header: string | null, options: VerifyPaddleSignatureOptions): Promise<void>;
83
+ //# sourceMappingURL=signature.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/signature.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,wGAAwG;AACxG,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,2GAA2G;AAC3G,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAkBpD,uFAAuF;AACvF,MAAM,WAAW,4BAA4B;IAC3C,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,GAAG,EAAE,IAAI,CAAC;IACV,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA+BD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CASrG;AA2CD;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAgBf"}
@@ -0,0 +1,163 @@
1
+ import { PaymentsVerificationFailedError } from "../../error/errors.js";
2
+ //#region src/rails/paddle/signature.ts
3
+ /**
4
+ * Paddle's authenticity proof: a timestamp and one or more HMACs, in one header.
5
+ *
6
+ * `Paddle-Signature: ts=1770000000;h1=5257a8…` — elements split on `;`, key and value split on `=`, and
7
+ * the signed payload is the timestamp, **a colon**, and the exact received body. HMAC-SHA256, hex,
8
+ * keyed with the notification destination's `pdl_ntfset_…` secret.
9
+ *
10
+ * ## Why this is a second verifier and not a widened core primitive
11
+ *
12
+ * The issue that scoped this work said Paddle "fits the existing timestamped shape of
13
+ * `requireSignedWebhook` with no new scheme." It does not, and the difference is two characters that
14
+ * decide whether anything is verified at all. `packages/core/src/http/signedWebhook.ts` splits the header
15
+ * on `,` and builds its signed payload as `` `${timestamp}.${body}` `` — Stripe's format. Paddle uses `;`
16
+ * and `:`. Neither is a parameter, and the module doc there argues *deliberately* that the signed payload
17
+ * must never become a caller-supplied template, because a payload a caller can shape is a payload a caller
18
+ * can shape into one that matches.
19
+ *
20
+ * So there were two options, and this is the one taken out loud: generalize the core primitive — editing a
21
+ * package this issue does not scope, against its own written reasoning — or write the scheme here, as the
22
+ * Lemon Squeezy rail already did for its own. This is the sibling precedent, and it keeps the change inside
23
+ * `@pithy-sh/payments`.
24
+ *
25
+ * The cost is real and worth naming: two modules now know how to check an HMAC. What they do not share is
26
+ * a *format*, which is the part that would have had to become configurable, and a configurable format is
27
+ * how #125 shipped a `requireSignedWebhook("lemonSqueezy", …)` that structurally could not verify the
28
+ * signatures it claimed to.
29
+ *
30
+ * ## The freshness window, and why it is 300 seconds and not 5
31
+ *
32
+ * Paddle's own SDKs default to five seconds. This defaults to three hundred, and the reason is what
33
+ * replay protection actually rests on here: `UNIQUE (rail, providerEventId)` over `evt_…`, in the webhook
34
+ * guard, which is absolute. A captured delivery replayed a year later is refused because its event id is
35
+ * already recorded — no window is doing that work. What a five-second window *does* do is convert ordinary
36
+ * clock skew between a Cloudflare edge and Paddle into a dropped renewal.
37
+ *
38
+ * The window still earns its place, in both directions. It bounds how long a captured-but-never-delivered
39
+ * signature stays usable, and it refuses a far-future timestamp — either a broken clock or somebody trying
40
+ * to mint a delivery that never goes stale. Configurable, so an adopter who wants Paddle's number can set
41
+ * it.
42
+ *
43
+ * Paddle re-signs each retry attempt with a fresh `ts`, which is the only way a three-day retry window and
44
+ * a five-second SDK tolerance could both be coherent — so the window does not silently reject retries.
45
+ *
46
+ * ## What a refusal says
47
+ *
48
+ * `payments/verification_failed`, with the reason in `detail` and nothing the delivery carried — not the
49
+ * body, not the candidate signature, never the secret. The webhook guard maps this to
50
+ * `payments/webhook_unverified` (401) before anything reaches the sender, so a forger learns only that it
51
+ * failed.
52
+ */
53
+ /** The header Paddle puts its proof in. Lower case, because that is how Hono presents a header name. */
54
+ const PADDLE_SIGNATURE_HEADER = "paddle-signature";
55
+ /** How long a delivery stays acceptable, by default. See the module doc for why this is not Paddle's 5. */
56
+ const PADDLE_DEFAULT_FRESHNESS_SECONDS = 300;
57
+ /** How many bytes an HMAC-SHA256 is. A candidate of any other length cannot be one, whatever it decodes to. */
58
+ const HMAC_SHA256_BYTES = 32;
59
+ /**
60
+ * How many `h1` values a header may list.
61
+ *
62
+ * Paddle lists more than one only while a destination's secret is being rotated, which pairs the old and
63
+ * the new — so two is the real number and this is generous. It is bounded at all because each listed
64
+ * candidate costs an HMAC: unbounded, the header would be a free way to make this Worker do arbitrary
65
+ * work. Core's primitive caps its own list for the same reason.
66
+ */
67
+ const MAX_SIGNATURES = 5;
68
+ /** Decode lower- or upper-case hex, or `undefined` when it is not hex at all. */
69
+ function hexBytes(value) {
70
+ if (value.length === 0 || value.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(value)) return void 0;
71
+ const bytes = new Uint8Array(value.length / 2);
72
+ for (let index = 0; index < bytes.length; index += 1) bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
73
+ return bytes;
74
+ }
75
+ /** Import a signing secret for HMAC-SHA256. */
76
+ async function signingKey(secret, usage) {
77
+ return await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
78
+ name: "HMAC",
79
+ hash: "SHA-256"
80
+ }, false, [usage]);
81
+ }
82
+ /**
83
+ * The signature Paddle would send for these bytes at this second — lower-case hex.
84
+ *
85
+ * Exported for the tests and the fixtures, which mint their own so verification is exercised for real
86
+ * rather than stubbed. Nothing in the request path signs anything: this rail only ever verifies.
87
+ */
88
+ async function signPaddleBody(timestamp, body, secret) {
89
+ const mac = await crypto.subtle.sign("HMAC", await signingKey(secret, "sign"), new TextEncoder().encode(`${timestamp}:${body}`));
90
+ return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
91
+ }
92
+ /**
93
+ * Parse the header into a timestamp and its candidate MACs, or `undefined` when it is not one.
94
+ *
95
+ * Strict about shape on purpose. Everything here is attacker-controlled text, and a lenient parse is how
96
+ * a verifier ends up comparing an empty candidate against an empty expectation and returning happily.
97
+ */
98
+ function parse(header) {
99
+ let timestamp;
100
+ const candidates = [];
101
+ for (const element of header.split(";")) {
102
+ const at = element.indexOf("=");
103
+ if (at <= 0) continue;
104
+ const key = element.slice(0, at).trim();
105
+ const value = element.slice(at + 1).trim();
106
+ if (value === "") continue;
107
+ if (key === "ts") {
108
+ if (timestamp !== void 0) return void 0;
109
+ if (!/^\d+$/.test(value)) return void 0;
110
+ timestamp = Number.parseInt(value, 10);
111
+ if (!Number.isSafeInteger(timestamp)) return void 0;
112
+ continue;
113
+ }
114
+ if (key === "h1") {
115
+ if (candidates.length >= MAX_SIGNATURES) return void 0;
116
+ const bytes = hexBytes(value);
117
+ if (bytes === void 0 || bytes.length !== HMAC_SHA256_BYTES) return void 0;
118
+ candidates.push(bytes);
119
+ }
120
+ }
121
+ if (timestamp === void 0 || candidates.length === 0) return void 0;
122
+ return {
123
+ timestamp,
124
+ candidates
125
+ };
126
+ }
127
+ /**
128
+ * Verify one delivery's `Paddle-Signature`. Resolves when Paddle signed these exact bytes at a moment
129
+ * inside the window, and throws `payments/verification_failed` otherwise.
130
+ *
131
+ * The comparison is `crypto.subtle.verify`, never `===` on the hex and never a hand-written loop: the
132
+ * runtime's own compare is constant-time, and a string equality on a MAC leaks how many leading bytes an
133
+ * attacker got right.
134
+ *
135
+ * The freshness check runs **before** the MACs. A stale delivery is refused whatever it carries, and
136
+ * refusing it first means an expired capture does not buy an attacker even one HMAC of work.
137
+ */
138
+ async function verifyPaddleSignature(body, header, options) {
139
+ const parsed = header === null ? void 0 : parse(header.trim());
140
+ if (parsed === void 0) throw new PaymentsVerificationFailedError({ detail: refusal("unreadable") });
141
+ const tolerance = options.toleranceSeconds ?? 300;
142
+ if (Math.abs(Math.floor(options.now.getTime() / 1e3) - parsed.timestamp) > tolerance) throw new PaymentsVerificationFailedError({ detail: refusal("stale") });
143
+ const key = await signingKey(options.secret, "verify");
144
+ const message = new TextEncoder().encode(`${parsed.timestamp}:${body}`);
145
+ for (const candidate of parsed.candidates) if (await crypto.subtle.verify("HMAC", key, candidate, message)) return;
146
+ throw new PaymentsVerificationFailedError({ detail: refusal("unmatched") });
147
+ }
148
+ /**
149
+ * This rail's wording for its three refusals.
150
+ *
151
+ * Prefixed `Paddle:` because a payments Worker composes several rails and `detail` is what an operator
152
+ * reads to find out which one refused. The strings say what failed and what to check, and nothing the
153
+ * delivery carried — `detail` reaches a log, and a forger must not be able to write into one.
154
+ */
155
+ function refusal(reason) {
156
+ switch (reason) {
157
+ case "unreadable": return "Paddle: the delivery carries no Paddle-Signature header of the form ts=<seconds>;h1=<64 hex chars>.";
158
+ case "stale": return "Paddle: the delivery's ts is outside the freshness window. Check this Worker's clock, or widen `paddle.webhookFreshnessSeconds`.";
159
+ case "unmatched": return "Paddle: no h1 matches an HMAC-SHA256 of `ts:body` under the configured signing secret. Check that the secret belongs to this notification destination and this environment.";
160
+ }
161
+ }
162
+ //#endregion
163
+ export { PADDLE_DEFAULT_FRESHNESS_SECONDS, PADDLE_SIGNATURE_HEADER, signPaddleBody, verifyPaddleSignature };
@@ -0,0 +1,137 @@
1
+ import type { PaymentsPurchase } from "../../data/purchase";
2
+ import { SubscriptionChangeQuote, SubscriptionStanding } from "../../data/subscription";
3
+ import type { PaymentsPaddleCredentials } from "../../secret/registry";
4
+ import type { SubscriptionCancelInput, SubscriptionChangeInput } from "../contract";
5
+ import { type PaddleEnvironment, type PaddleHttpFetch } from "./api";
6
+ /**
7
+ * Changing a Paddle subscription from the server: read it, quote a move, make one, end it, un-end it.
8
+ *
9
+ * Written against real sandbox responses recorded on 2026-08-28 (#465), not against the documentation.
10
+ * Four of the rules below exist because a recording contradicted a design written from the docs, and each
11
+ * is stated where it is enforced rather than in a changelog.
12
+ *
13
+ * ## The three verbs Paddle needs, one of which this rail had never sent
14
+ *
15
+ * | What | Paddle |
16
+ * | --- | --- |
17
+ * | Read | `GET /subscriptions/{id}` |
18
+ * | Quote a change | `PATCH /subscriptions/{id}/preview` |
19
+ * | Make one, or withdraw a schedule | `PATCH /subscriptions/{id}` |
20
+ * | Cancel | `POST /subscriptions/{id}/cancel` |
21
+ *
22
+ * **Nothing in this rail had ever issued a PATCH.** Every call before #465 was a GET or a POST, and
23
+ * `paddleJson` defaults a request carrying a body to POST — so a preview built the obvious way is sent as
24
+ * `POST /subscriptions/{id}/preview`, which Paddle does not route. The failure arrives as an ordinary 4xx,
25
+ * which this rail maps to `payments/rail_not_configured`, and an operator is sent to check an API key that
26
+ * is perfectly fine. `method` is passed explicitly on every call here for that reason, and the tests assert
27
+ * the verb rather than the outcome.
28
+ *
29
+ * ## What this module will not do
30
+ *
31
+ * **It computes no money.** Every figure in a quote is a string Paddle sent, parsed by {@link minorAmount}
32
+ * and never scaled, summed, or checked. `data/subscription.ts` holds the longer argument; the short one is
33
+ * that a second answer to "what will this cost" is a second number for a customer to hold against their
34
+ * statement, and the statement is the one they will believe.
35
+ *
36
+ * **It does render one, and that is a different verb** (#465, 2026-08-28). Paddle's `subscriptions.preview`
37
+ * returns no formatted total at any depth — `formatted_totals` exists only on the pricing-preview endpoint,
38
+ * "for convenience" — so a quote leaves here as minor units or as nothing a screen can print. Every amount
39
+ * therefore carries `rendered` beside it, placed by `data/renderMoney.ts` in the locale the route resolved.
40
+ * The integer is Paddle's and is untouched; only its spelling is decided here.
41
+ *
42
+ * **It returns nothing projectable.** Every method answers a `SubscriptionStanding` or a
43
+ * `SubscriptionChangeQuote` and never an `UnboundProviderEvent`. The webhook owns `pithy_payments_purchases`;
44
+ * a rail that handed a route an event to write would be a second producer of a row the projection already
45
+ * owns, and the two would race on `providerEventAt` — the exact ordering defect that field exists to prevent.
46
+ *
47
+ * **It reads no client-supplied billing enum, because there is none to read.** The proration mode is chosen
48
+ * from the direction of the change (see {@link prorationModeFor}) and `on_payment_failure` is always
49
+ * `prevent_change`. Paddle's `do_not_bill` is a free upgrade, and it is unreachable here because there is
50
+ * nowhere for a caller to write it.
51
+ */
52
+ /** What every call here needs: the credentials, which Paddle account, and the transport. */
53
+ export interface PaddleSubscriptionOptions {
54
+ /** The rail's credentials. The API key is read at the point of need and never cached. */
55
+ credentials: PaymentsPaddleCredentials;
56
+ /** Which Paddle account to reach. */
57
+ environment: PaddleEnvironment;
58
+ /** The HTTP seam. Defaults to the runtime's `fetch`. */
59
+ transport?: PaddleHttpFetch;
60
+ }
61
+ /**
62
+ * Where this subscription stands now, or `undefined` when Paddle has nothing to say about this purchase.
63
+ *
64
+ * Read live, because the one fact it exists to report is the one a projected row does not carry: with a
65
+ * cancellation scheduled Paddle answers `status: "active"`, `canceled_at: null` and `next_billed_at: null`
66
+ * (recorded 2026-08-28). Two of those say the subscription is fine and the third says nothing, so the end
67
+ * date lives only on `scheduled_change.effective_at` — and a webhook announcing it can be dropped.
68
+ */
69
+ export declare function readPaddleStanding(purchase: PaymentsPurchase, options: PaddleSubscriptionOptions): Promise<SubscriptionStanding | undefined>;
70
+ /**
71
+ * What moving to this price would cost, as Paddle previews it.
72
+ *
73
+ * **A read, so the no-op rule does not apply.** Previewing the plan already held is a question with an honest
74
+ * answer and asking it takes nothing; skipping the call would mean inventing a recurring figure to fill the
75
+ * quote with, which is the one thing this package will not do.
76
+ *
77
+ * The item refusals *do* apply, because the preview body is the update body: a preview built from a rewritten
78
+ * items array quotes a change that is not the one the update would make.
79
+ *
80
+ * A subscription with a change already scheduled is not refused here. Refusing a read on the grounds of state
81
+ * would hide the figures from the screen that has to explain why the move cannot be made yet, and `changePlan`
82
+ * is where the write is stopped.
83
+ *
84
+ * `locale` is the reader the figures are rendered for, and it is a parameter of this method alone: the other
85
+ * four verbs answer a standing, which carries no amount. Absent, the rendering falls back to the kit's own
86
+ * locale rather than failing — see `data/renderMoney.ts`.
87
+ */
88
+ export declare function previewPaddleChange(input: SubscriptionChangeInput, options: PaddleSubscriptionOptions, locale?: string): Promise<SubscriptionChangeQuote>;
89
+ /**
90
+ * Move the subscription to a different plan, and answer where it now stands.
91
+ *
92
+ * The answer is Paddle's, not a prediction: the screen that just wrote renders what the store says rather than
93
+ * what the request asked for, and the recorded responses are why — a cancel leaves `status` at `active`, and
94
+ * an update's response is the only place the resulting standing exists.
95
+ *
96
+ * **The plan already held is a success and writes nothing.** These verbs sit behind a network, callers retry,
97
+ * and a second delivery of the same instruction must not become a second proration. A 409 for the state the
98
+ * caller asked for would also simply be wrong — the subscription is how they wanted it. The subscription is
99
+ * still re-read, because the standing that comes back has to be the store's; the rule is about not *writing*
100
+ * twice, and a read takes and gives nothing.
101
+ *
102
+ * **A subscription with a change already scheduled is refused.** Honoring the move means discarding the
103
+ * pending action, and Paddle's own refusal for it arrives as an ordinary 4xx that this rail maps to
104
+ * `rail_not_configured` — a refusal naming the wrong thing. Withdraw the schedule first; that is what
105
+ * {@link keepPaddleSubscription} is for, and it is a separate act the audit trail records separately.
106
+ */
107
+ export declare function changePaddlePlan(input: SubscriptionChangeInput, options: PaddleSubscriptionOptions): Promise<SubscriptionStanding>;
108
+ /**
109
+ * Stop the subscription renewing, and answer where it now stands.
110
+ *
111
+ * `at_period_end` is Paddle's `next_billing_period` and the settled policy: the tier holds until the paid
112
+ * period runs out. `now` is `immediately`, and it exists because support occasionally has to end one today —
113
+ * and because a policy with no legitimate exit gets departed from by a direct provider call nothing audits.
114
+ *
115
+ * **The no-op is per timing, not per verb.** A subscription scheduled to end on the 15th is not a subscription
116
+ * that ended today, so `now` against a scheduled cancel is a real request and reaches Paddle. What is already
117
+ * true is what is skipped: a period-end cancel on one already scheduled, and an immediate cancel on one the
118
+ * store has already ended.
119
+ */
120
+ export declare function cancelPaddleSubscription(input: SubscriptionCancelInput, options: PaddleSubscriptionOptions): Promise<SubscriptionStanding>;
121
+ /**
122
+ * Withdraw a scheduled cancellation, so the subscription renews after all.
123
+ *
124
+ * **It withdraws a cancellation, and only a cancellation.** Paddle has no verb for that: the update clears
125
+ * `scheduled_change` *wholesale*, and that field also holds a scheduled pause and a scheduled resume. A rail
126
+ * that simply sent the clear would silently un-pause a paused subscription — the customer's account restarts
127
+ * billing, on a request that said nothing about pausing. So the subscription is re-read and anything but a
128
+ * pending `cancel` is refused, with what was actually scheduled named in `detail`.
129
+ *
130
+ * The check cannot move to the route: the route holds a projected row, and the pending action lives only at
131
+ * the store.
132
+ *
133
+ * **Nothing scheduled is the no-op, not a refusal.** The subscription already renews, which is what the caller
134
+ * asked for, and a retry after a successful withdrawal is exactly that request arriving twice.
135
+ */
136
+ export declare function keepPaddleSubscription(purchase: PaymentsPurchase, options: PaddleSubscriptionOptions): Promise<SubscriptionStanding>;
137
+ //# sourceMappingURL=subscription.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/subscription.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAIL,uBAAuB,EAGvB,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA+B,MAAM,OAAO,CAAC;AAYlG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,yBAAyB;IACxC,yFAAyF;IACzF,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AA2fD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAK3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,EAClC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,uBAAuB,CAAC,CAuBlC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CA0B/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAsB/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAsB/B"}