@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,588 @@
1
+ import { decodeSubjectReference } from "../../data/subject.js";
2
+ import { PaymentsVerificationFailedError } from "../../error/errors.js";
3
+ import { pauseResumesAt } from "../../data/pause.js";
4
+ import { z } from "zod";
5
+ //#region src/rails/paddle/objects.ts
6
+ /**
7
+ * Paddle's objects, and the mapping from what its events say to what this package stores.
8
+ *
9
+ * ## Two rows per subscription, exactly as Lemon Squeezy has
10
+ *
11
+ * Paddle splits money from state at the source. A `transaction.*` event carries a **transaction**: one
12
+ * billing period's charge, its totals, its status. A `subscription.*` event carries a **subscription**: a
13
+ * status, a billing period, a scheduled change, and no money. So there is a **state row** keyed on
14
+ * `sub_…` and a **money row** per `txn_…`, distinguished by `PurchaseRole`, and each is monotonic on
15
+ * exactly one provider clock.
16
+ *
17
+ * Paddle's ids are globally prefixed and distinct — `txn_`, `sub_`, `adj_`, `ctm_` — so unlike Lemon
18
+ * Squeezy nothing needs namespacing before it can be a row's identity.
19
+ *
20
+ * **A subscription transaction is born `expired`, not `active`, and this is a departure from the issue's
21
+ * event table stated out loud.** The issue maps `transaction.completed` to `active`. On a one-off that is
22
+ * right and this module does it. On a subscription it would be a row with no expiry saying "paid and
23
+ * current" forever — and a never-expiring `active` row outranks the subscription's own state row, so a
24
+ * canceled subscriber would keep their entitlement for good. The paid period is real and it has closed:
25
+ * `expired` grants nothing and still credits a `grants` clause, which is what makes two renewals credit
26
+ * twice. This is the trap `lemonSqueezy/objects.ts` documents at length; Paddle has it identically.
27
+ *
28
+ * ## The environment is the account, not a field on the payload
29
+ *
30
+ * The issue says `data.mode` is `sandbox` or `live`. It is not. Verified against a live sandbox: `mode`
31
+ * appears on a **discount**, where its values are `standard` and `custom`, and it is absent from customers
32
+ * and transactions entirely. Paddle Billing partitions sandbox from live by *account* — a separate host,
33
+ * a separate API key, a separate set of notification destinations — so the environment a purchase belongs
34
+ * to is the environment this deployment's credentials point at, and nothing in a payload can contradict
35
+ * it. That is the same arrangement Stripe has, and the opposite of Lemon Squeezy's single namespace.
36
+ *
37
+ * ## The environment fence, and why `custom_data` alone cannot be one
38
+ *
39
+ * `dev` is not publicly routable, so a dev checkout's webhooks land at `staging` — both point at one
40
+ * Paddle sandbox, and a sandbox has one set of notification destinations. So a delivery stamped for
41
+ * another environment is the normal case here, not an anomaly, and it projects nothing and returns 200.
42
+ *
43
+ * The issue argues the stamp needs no proof, because "`Paddle.Checkout.open` refuses `customData`
44
+ * alongside `transactionId`, and the server always creates the transaction." **That constraint does not
45
+ * exist.** Two things were measured against the live sandbox on 2026-08-13, both from a page holding
46
+ * nothing but the publishable client token this rail ships to every browser that loads a paywall:
47
+ *
48
+ * - `Paddle.Checkout.open({ items: [{ priceId, quantity }], customData: {…} })` opens and completes with
49
+ * no server involved at all, and Paddle stores the page's `custom_data` verbatim.
50
+ * - `Paddle.Checkout.open({ transactionId, customData: {…} })` does not throw, is not refused, and
51
+ * **replaces** the `custom_data` the server wrote when the transaction was created. Same transaction id,
52
+ * `origin` still `"api"`, owner now whoever the page said.
53
+ *
54
+ * Both recordings are in `fixtures/browserForged.ts` and `objects.test.ts` gates on them. So
55
+ * `custom_data.pithy_user` is a string a browser can write on either form of the call, and binding
56
+ * ownership on it would let anyone attach a purchase to any account, permanently, because
57
+ * `linkProviderAccount` never rebinds and the first pairing wins.
58
+ *
59
+ * The Lemon Squeezy rail met the same problem and answered it with a MAC. So does this one: see
60
+ * {@link accountReferenceProof}. Without the proof the two stamped values are worth nothing, and with it
61
+ * they are worth exactly what a value only this deployment's server could have produced is worth.
62
+ */
63
+ /**
64
+ * The `custom_data` key carrying the subject reference. Literal snake_case, as the issue specifies.
65
+ *
66
+ * **The name says `user` and the value no longer has to be one, and that mismatch is deliberate.** What
67
+ * travels here is now `encodeSubjectReference`'s output — `user:ada`, `organization:acme` — because a
68
+ * purchase can be held by an organization. The obvious tidy-up is to rename the key to match. It is the one
69
+ * thing that must not happen: this string is a wire contract with Paddle, not an identifier of ours. A
70
+ * checkout stamped `pithy_user` today is a transaction sitting open in somebody's browser, a subscription
71
+ * renewing next month, and a `custom_data` object Paddle stores verbatim for the life of the customer. A
72
+ * renamed key reads nothing on any of them — every in-flight purchase comes back naming nobody, permanently,
73
+ * with a `linkProviderAccount` that never rebinds behind it. The name is frozen; the meaning moved.
74
+ */
75
+ const PADDLE_CUSTOM_ACCOUNT = "pithy_user";
76
+ /** The `custom_data` key carrying this deployment's environment — the shared-sandbox fence. */
77
+ const PADDLE_CUSTOM_ENV = "pithy_env";
78
+ /**
79
+ * The `custom_data` key carrying the proof that **this deployment's server** wrote the two above.
80
+ *
81
+ * Without it the other two prove nothing: `Paddle.Checkout.open` accepts `customData` with only the
82
+ * publishable client token — beside an `items[]` array *and* beside a `transactionId`, where it overwrites
83
+ * what the server wrote — both key names are exported constants in an open-source package, and the
84
+ * environment value is one of three. Requiring them asks an attacker to guess nothing.
85
+ *
86
+ * A MAC is the only part a stranger cannot produce.
87
+ */
88
+ const PADDLE_CUSTOM_PROOF = "pithy_ref_proof";
89
+ /**
90
+ * Paddle stores `custom_data` verbatim — it does not normalize keys the way Lemon Squeezy snake_cases
91
+ * them. The `pithy_` prefix is still load-bearing: this object is shared with whatever an adopter puts in
92
+ * it, and a prefix is what stops a collision being silent rather than being a wrong owner.
93
+ */
94
+ const CustomData = z.record(z.string(), z.unknown()).describe("Arbitrary key/value data stored verbatim by Paddle, shared with whatever the adopter puts there.");
95
+ /** The envelope every webhook delivery and every swept event arrives in. */
96
+ const PaddleEvent = z.object({
97
+ event_id: z.string().min(1).describe("Paddle's own id for this event — `evt_…`. The dedup key, and the one the webhook path and the events sweep share, because the stream carries no notification_id."),
98
+ event_type: z.string().min(1).describe("Which event this is — `transaction.completed`, `subscription.canceled`."),
99
+ occurred_at: z.string().min(1).describe("When the event happened, from the envelope. This is `providerEventAt`, never the entity's `updated_at`: a transaction's clock lives in the transaction's domain, and stamping it onto a subscription's watermark discards the `subscription.activated` that follows."),
100
+ data: z.record(z.string(), z.unknown()).describe("The entity the event is about.")
101
+ }).loose().describe("One Paddle event, as a webhook delivers it and as the events stream returns it.");
102
+ /** One transaction line item, narrowed to the price it names. */
103
+ const PaddleTransactionItem = z.object({
104
+ price: z.object({ id: z.string().optional().describe("The price sold — this rail's SKU.") }).loose().optional().describe("The price object, which is where a transaction carries its SKU."),
105
+ price_id: z.string().optional().describe("The price id, on the shapes that carry it flat.")
106
+ }).loose().describe("One line of a transaction. Single-product checkouts have exactly one.");
107
+ /** An adjustment's fields — a refund, a credit, or a chargeback, which on this rail can arrive unsolicited. */
108
+ const PaddleAdjustment = z.object({
109
+ id: z.string().min(1).describe("The adjustment — `adj_…`."),
110
+ action: z.string().min(1).describe("What it does — `refund`, `credit`, `chargeback`, `chargeback_reverse`, `chargeback_warning`, `chargeback_warning_reverse`, `credit_reverse`."),
111
+ status: z.string().nullish().describe("`pending_approval`, `approved`, `rejected`, or `reversed`."),
112
+ transaction_id: z.string().min(1).describe("The transaction adjusted. The only key that names a row of ours."),
113
+ subscription_id: z.string().nullish().describe("The subscription behind it, when there is one."),
114
+ customer_id: z.string().nullish().describe("The customer adjusted."),
115
+ currency_code: z.string().nullish().describe("The currency the totals are in."),
116
+ totals: z.object({ total: z.string().nullish().describe("How much was adjusted, in the currency's lowest denomination.") }).loose().nullish().describe("What the adjustment came to. Summed with every other approved adjustment against the transaction, and that sum is what tells a full refund from a partial one."),
117
+ created_at: z.string().nullish().describe("When Paddle raised the adjustment."),
118
+ updated_at: z.string().nullish().describe("The adjustment's own clock. Deliberately not used as a watermark.")
119
+ }).loose().describe("A Paddle adjustment. As merchant of record Paddle issues these on its own, with no local write first.");
120
+ /** A transaction's fields, as an event and the API both present them. */
121
+ const PaddleTransaction = z.object({
122
+ id: z.string().min(1).describe("The transaction — `txn_…`. This row's identity forever."),
123
+ status: z.string().min(1).describe("Paddle's own status vocabulary, normalized by `transactionStatus`."),
124
+ customer_id: z.string().nullish().describe("The Paddle customer charged — this rail's `providerAccountId`."),
125
+ subscription_id: z.string().nullish().describe("The subscription this transaction bills, or null for a one-off. The family key."),
126
+ discount_id: z.string().nullish().describe("The discount applied, when one was."),
127
+ origin: z.string().nullish().describe("How the transaction came to exist — `web`, `subscription_recurring`, `api`. Recorded rather than acted on: it is undocumented enough that a fence on it would be a guess."),
128
+ items: z.array(PaddleTransactionItem).optional().describe("The lines sold. The first carries this rail's SKU."),
129
+ details: z.object({ totals: z.object({
130
+ grand_total: z.string().optional().describe("What was charged, in the currency's lowest denomination, as a string."),
131
+ currency_code: z.string().optional().describe("The currency, uppercase ISO 4217.")
132
+ }).loose().optional().describe("The money, as Paddle computed it.") }).loose().optional().describe("The computed totals. Paddle is the authority on every figure here; nothing recomputes one."),
133
+ billing_period: z.object({
134
+ starts_at: z.string().nullish().describe("When the period this transaction bills began."),
135
+ ends_at: z.string().nullish().describe("When it ends.")
136
+ }).loose().nullish().describe("The billing period a subscription transaction covers. Absent on a one-off."),
137
+ currency_code: z.string().nullish().describe("The transaction's currency, when it carries one flat."),
138
+ custom_data: CustomData.nullish().describe("What this deployment's server stamped at checkout, echoed back."),
139
+ checkout: z.object({ url: z.string().nullish().describe("The hosted checkout page, when the account has a payment link.") }).loose().nullish().describe("Where a hosted checkout lives. Null unless the account has a default payment link set."),
140
+ adjustments: z.array(PaddleAdjustment).optional().describe("Every adjustment raised against this transaction, returned when the read asks `include=adjustments`. The whole reason it is asked for: a full refund delivered as two partial adjustments is only full when they are summed."),
141
+ created_at: z.string().min(1).describe("When Paddle recorded the transaction."),
142
+ updated_at: z.string().nullish().describe("The transaction's own clock. Deliberately not used as a watermark.")
143
+ }).loose().describe("A Paddle transaction — one billing period's charge, or a one-off purchase.");
144
+ /**
145
+ * A change Paddle will apply later, exactly as it sits on a subscription.
146
+ *
147
+ * Lifted out of {@link PaddleSubscription}, where it was inline, because two readers now ask it questions
148
+ * and a second inline copy is how the two field lists drift apart: {@link subscriptionResumesAt} asks when
149
+ * a paused subscription comes back, and {@link subscriptionPendingChange} asks what is pending at all. One
150
+ * declaration, one parse, both readers.
151
+ *
152
+ * **`items` is declared because Paddle sends it.** It arrived `null` on every change recorded so far —
153
+ * the pause and resume of 2026-08-15, the cancel of 2026-08-28 — and nothing reads it. Declaring a field
154
+ * the payload carries costs a line; discovering it later inside a `.loose()` passthrough that nobody wrote
155
+ * down costs an afternoon.
156
+ */
157
+ const PaddleScheduledChange = z.object({
158
+ action: z.string().optional().describe("`cancel`, `pause`, or `resume`."),
159
+ effective_at: z.string().nullish().describe("When it takes effect. On a `resume` action against a paused subscription this is the resume date itself — verified live, see `subscriptionResumesAt`. On a `cancel` it is when access ends, and it is the only place that date exists: `next_billed_at` is null on a subscription with a cancellation scheduled, recorded 2026-08-28."),
160
+ resume_at: z.string().nullish().describe("When a paused subscription should resume. Paddle documents it as set only on a `pause` action, and a subscription carrying one is still `active` — so it is read for completeness rather than as the field a paused row is filled from."),
161
+ items: z.array(z.unknown()).nullish().describe("The items the change applies to. Null on every change recorded so far; carried, not read.")
162
+ }).loose().describe("A change Paddle will apply later — the shape both readers of `scheduled_change` parse through, so neither can drift from the other.");
163
+ /** A subscription's fields, as an event and the API both present them. */
164
+ const PaddleSubscription = z.object({
165
+ id: z.string().min(1).describe("The subscription — `sub_…`. The state row's identity, and the family key."),
166
+ status: z.string().min(1).describe("Paddle's own status vocabulary, normalized by `subscriptionStatus`."),
167
+ customer_id: z.string().nullish().describe("The Paddle customer — this rail's `providerAccountId`."),
168
+ items: z.array(z.object({
169
+ price: z.object({ id: z.string().optional().describe("The price — `pri_…`. This rail's SKU.") }).loose().optional().describe("The price this item is billed at."),
170
+ status: z.string().optional().describe("The item's own status, which can differ from the subscription's.")
171
+ }).loose().describe("One priced item on the subscription.")).optional().describe("The priced items. The first carries this rail's SKU."),
172
+ current_billing_period: z.object({
173
+ starts_at: z.string().nullish().describe("When the current period began."),
174
+ ends_at: z.string().nullish().describe("When it ends — what a cancellation's `expiresAt` becomes.")
175
+ }).loose().nullish().describe("The period currently paid for. Null while a subscription is trialing or paused."),
176
+ scheduled_change: PaddleScheduledChange.nullish().describe("A change Paddle will apply later. A subscription with a scheduled cancel is still `active` today — the distinction between `canceled` and a scheduled change is the whole difference between access now and access until the period ends."),
177
+ trial_dates: z.object({
178
+ starts_at: z.string().nullish().describe("When the trial began."),
179
+ ends_at: z.string().nullish().describe("When the trial ends — a trialing subscription's `expiresAt`.")
180
+ }).loose().nullish().describe("The trial window, when this subscription has one. Its end is a trialing subscription's expiry."),
181
+ next_billed_at: z.string().nullish().describe("When the next charge falls due, when one is going to."),
182
+ canceled_at: z.string().nullish().describe("When it was canceled, if it was."),
183
+ paused_at: z.string().nullish().describe("When it was paused, if it was."),
184
+ discount: z.object({
185
+ id: z.string().optional().describe("The discount in force."),
186
+ starts_at: z.string().nullish().describe("When the discount started applying."),
187
+ ends_at: z.string().nullish().describe("When the discount stops applying, or null for one that runs forever.")
188
+ }).loose().nullish().describe("The discount in force, when one is. Carries an id and no code, so a screen names the date rather than the code."),
189
+ custom_data: CustomData.nullish().describe("What Paddle copied from the transaction that created this subscription. The stamp, on every later event."),
190
+ created_at: z.string().min(1).describe("When the subscription began."),
191
+ updated_at: z.string().nullish().describe("The subscription's own clock. Deliberately not used as a watermark.")
192
+ }).loose().describe("A Paddle subscription — the standing of a recurring purchase, carrying no charge.");
193
+ /**
194
+ * A money figure Paddle quotes, as it sends one: a **string**, in the currency's lowest denomination, and
195
+ * **signed**.
196
+ *
197
+ * The sign is the part a schema gets wrong, and it gets it wrong in the direction that throws in front of a
198
+ * customer. Recorded against the sandbox on 2026-08-28: previewing an upgrade returns
199
+ * `credit: { amount: "-380" }`, and previewing a downgrade returns a whole totals block below zero. A
200
+ * `.nonnegative()` anywhere on this path would refuse every real plan change while reading, in the source,
201
+ * like ordinary care. {@link minorAmount} already accepts a leading `-`; nothing else here needs to know.
202
+ *
203
+ * `amount` is required where `PaddleTransaction`'s totals are optional, and the difference is deliberate: a
204
+ * transaction's totals are a block this package reads one figure out of, while a quoted money object with no
205
+ * amount is not a partial reading — it is a shape change, and it should be loud.
206
+ */
207
+ const PaddleMoney = z.object({
208
+ amount: z.string().describe("How much, as an integer string in the currency's lowest denomination, signed. `-380` is a credit of $3.80."),
209
+ currency_code: z.string().nullish().describe("The currency, uppercase ISO 4217, as Paddle sends it.")
210
+ }).loose().describe("One money figure Paddle quoted. Never recomputed here — Paddle is the authority on every amount.");
211
+ /**
212
+ * One block of Paddle's computed totals, on a preview.
213
+ *
214
+ * **`grand_total` is not the headline, and on a downgrade it is actively misleading.** Recorded 2026-08-28:
215
+ * previewing Team → Solo answers `grand_total: "0"` while the customer is owed 6581, which is sitting in
216
+ * `credit_to_balance`. A screen wired to the totals says "You will be charged $0.00" — true, and it never
217
+ * mentions the money. What renders is `update_summary.result`; see {@link PaddleUpdateSummary}.
218
+ *
219
+ * Every field is optional because Paddle's blocks differ by mode and by direction, and every one may be
220
+ * negative because a downgrade's are: `subtotal: "-6045"`, `tax: "-536"`, `total: "-6581"`. `fee` and
221
+ * `earnings` arrive **null** on a preview — the money has not moved, so there is nothing to have earned —
222
+ * and they are declared rather than left to `.loose()` so a later reader finds null in the type instead of
223
+ * inferring absence.
224
+ *
225
+ * **Deliberately not shared with {@link PaddleTransaction}'s own `details.totals`.** Unifying them would
226
+ * widen that shape's public type — `string | undefined` becomes `string | null | undefined` on fields four
227
+ * modules already read — in the same commit that adds a preview, which is precisely the regression
228
+ * `objects.test.ts` guards against. The *treatment* is identical and that is what matters here: strings,
229
+ * unscaled, `.loose()`, no constraint on sign. One type in both places is the job of the step that needs
230
+ * one type in both places.
231
+ */
232
+ const PaddleTotals = z.object({
233
+ subtotal: z.string().nullish().describe("Before tax. Negative when the change is a credit."),
234
+ tax: z.string().nullish().describe("The tax on it, which is negative alongside a negative subtotal."),
235
+ discount: z.string().nullish().describe("What a discount took off, when one applies."),
236
+ total: z.string().nullish().describe("Subtotal plus tax, still signed."),
237
+ grand_total: z.string().nullish().describe("What Paddle will actually take today — and `\"0\"` on a downgrade, where the money owed is in `credit_to_balance` instead. Not the figure a screen quotes."),
238
+ grand_total_tax: z.string().nullish().describe("The tax within the grand total."),
239
+ credit: z.string().nullish().describe("Credit consumed by this transaction."),
240
+ credit_to_balance: z.string().nullish().describe("What lands on the customer's balance rather than on a card — where a downgrade's whole refund sits while `grand_total` reads zero."),
241
+ balance: z.string().nullish().describe("What is left outstanding after credit is applied."),
242
+ fee: z.string().nullish().describe("Paddle's fee. Null on a preview: nothing has been charged to take one from."),
243
+ earnings: z.string().nullish().describe("The seller's share. Null on a preview, for the same reason."),
244
+ currency_code: z.string().nullish().describe("The currency every figure in this block is in."),
245
+ exchange_rate: z.string().nullish().describe("The rate Paddle used, `\"1\"` when the currency is the account's own. Recorded, never applied here.")
246
+ }).loose().describe("One block of totals as Paddle computed it. Strings, signed, in the currency's lowest denomination.");
247
+ /**
248
+ * What the change comes to, and **the only part of a preview a screen should quote**.
249
+ *
250
+ * `credit` is the unused remainder of the old plan and arrives negative; `charge` is what the new plan costs
251
+ * for the rest of the period; `result` is Paddle's own reconciliation of the two, and it carries the word as
252
+ * well as the number — `{ action: "charge", amount: "6582" }` on the recorded upgrade,
253
+ * `{ action: "credit", amount: "6581" }` on the recorded downgrade.
254
+ *
255
+ * The alternative — reading `immediate_transaction.details.totals.grand_total` — is right on an upgrade and
256
+ * silently wrong on a downgrade, where it is `"0"`. That is why `result` is required here while the two
257
+ * halves it reconciles are not: a summary with no result is a summary nothing can be said from.
258
+ *
259
+ * `action` stays a plain string rather than an enum for the reason `status` does: an unknown value is
260
+ * refused by the reader that has to act on it, with a message naming what arrived, rather than by a parse
261
+ * failure that discards the rest of a valid response.
262
+ */
263
+ const PaddleUpdateSummary = z.object({
264
+ credit: PaddleMoney.nullish().describe("What the unused part of the current plan is worth back. Negative — it is money coming off."),
265
+ charge: PaddleMoney.nullish().describe("What the new plan costs for the remainder of the period, before credit."),
266
+ result: PaddleMoney.extend({ action: z.string().describe("What happens on balance — `charge` or `credit`. The verb a screen uses.") }).describe("The reconciliation of credit against charge: what happens, and how much. The renderable headline.")
267
+ }).loose().describe("Paddle's own summary of what a plan change costs. The one place a downgrade's credit is stated plainly.");
268
+ /**
269
+ * A preview of a subscription change — what Paddle answers before anything is committed.
270
+ *
271
+ * **`immediate_transaction` is nullable, and the adopter's own downgrade policy is the case that makes it
272
+ * null.** Under `proration_billing_mode: "prorated_next_billing_period"` nothing settles today, so there is
273
+ * no transaction to describe and Paddle sends none; the whole answer is `update_summary` plus the recurring
274
+ * block. A shape requiring it would fail on every downgrade this package is designed to perform.
275
+ *
276
+ * **Only the preview's own keys are declared.** The response is a subscription entity *with* these three
277
+ * fields on it — the recordings are excerpts of exactly those fields, and this shape claims no more than was
278
+ * measured. `.loose()` carries the rest through, and a caller wanting the entity parses the same body a
279
+ * second time through {@link PaddleSubscription}, which is the shape that knows what an entity requires.
280
+ */
281
+ const PaddleSubscriptionPreview = z.object({
282
+ update_summary: PaddleUpdateSummary.nullish().describe("What the change costs, reconciled. The headline, and the only figure a downgrade states honestly."),
283
+ immediate_transaction: z.object({
284
+ details: z.object({ totals: PaddleTotals.nullish().describe("What today's charge comes to, if there is one.") }).loose().nullish().describe("The computed detail of the transaction that would settle now."),
285
+ billing_period: z.object({
286
+ starts_at: z.string().nullish().describe("When the prorated period being charged for begins — now."),
287
+ ends_at: z.string().nullish().describe("When it ends, which is where the existing paid period ends.")
288
+ }).loose().nullish().describe("The period today's charge covers. The remainder of the period already running.")
289
+ }).loose().nullish().describe("The transaction that would be raised immediately — **null whenever nothing settles today**, which is every change made under `prorated_next_billing_period`."),
290
+ recurring_transaction_details: z.object({ totals: PaddleTotals.nullish().describe("What each subsequent period will come to.") }).loose().nullish().describe("What the subscription costs from the next renewal onward — the 'then' half of a quote.")
291
+ }).loose().describe("Paddle's preview of a subscription change: what settles now, what recurs after, and what the change comes to on balance.");
292
+ /** A Paddle timestamp, or a refusal. Its API emits RFC-3339 throughout. */
293
+ function at(value, what) {
294
+ const parsed = new Date(value);
295
+ if (Number.isNaN(parsed.getTime())) throw new PaymentsVerificationFailedError({ detail: `Paddle: ${what} is not a readable timestamp.` });
296
+ return parsed;
297
+ }
298
+ /** The same, tolerating an absent value. */
299
+ function maybeAt(value, what) {
300
+ return value === null || value === void 0 || value === "" ? null : at(value, what);
301
+ }
302
+ /**
303
+ * A subscription's status, normalized.
304
+ *
305
+ * `trialing` grants, with `expiresAt` at the trial's end. That hands an entitlement to somebody who has
306
+ * paid nothing, which is what a trial *is* — and it is bounded, because the trial's end date is on the
307
+ * row. The issue asked for this to be an explicit decision rather than a table row, so: it is deliberate,
308
+ * and the bound is what makes it safe.
309
+ *
310
+ * An unknown status refuses rather than guessing, which is every other rail's rule too: a status this
311
+ * package has never seen is a shape change worth failing loudly on.
312
+ */
313
+ function subscriptionStatus(status) {
314
+ switch (status) {
315
+ case "active":
316
+ case "trialing": return "active";
317
+ case "past_due": return "in_grace";
318
+ case "paused": return "paused";
319
+ case "canceled": return "canceled";
320
+ default: throw new PaymentsVerificationFailedError({ detail: `Paddle: subscription status "${status}" is not one this build maps.` });
321
+ }
322
+ }
323
+ /**
324
+ * A transaction's status, normalized — and it depends on whether the transaction bills a subscription.
325
+ *
326
+ * **A one-off is money and state at once**, so a completed one is `active` with no expiry: that is a
327
+ * non-consumable bought and owned.
328
+ *
329
+ * **A subscription transaction is one closed billing period**, so a completed one is `expired`. It
330
+ * credits a `grants` clause — which is what makes N renewals credit exactly N times — and grants no
331
+ * access, because access is the state row's job. See the module doc for why `active` here would outlive
332
+ * a cancellation.
333
+ */
334
+ function transactionStatus(status, subscription) {
335
+ switch (status) {
336
+ case "paid":
337
+ case "completed": return subscription ? "expired" : "active";
338
+ case "past_due": return "in_grace";
339
+ case "canceled": return "never_paid";
340
+ case "billed": return "on_hold";
341
+ case "draft":
342
+ case "ready": return "on_hold";
343
+ default: throw new PaymentsVerificationFailedError({ detail: `Paddle: transaction status "${status}" is not one this build maps.` });
344
+ }
345
+ }
346
+ /** The price id a transaction sold. Paddle carries it under `items[].price.id`; some shapes flatten it. */
347
+ function transactionPriceId(transaction) {
348
+ const first = transaction.items?.[0];
349
+ return first?.price?.id ?? first?.price_id ?? "";
350
+ }
351
+ /** The price id a subscription is for. */
352
+ function subscriptionPriceId(subscription) {
353
+ return subscription.items?.[0]?.price?.id ?? "";
354
+ }
355
+ /**
356
+ * An amount Paddle reported, as an integer in the currency's lowest denomination.
357
+ *
358
+ * Paddle sends amounts as **strings** and always in the lowest denomination, including for the
359
+ * zero-decimal currencies — ¥725 arrives as `"725"`, not `"72500"`, confirmed live. So this parses and
360
+ * never scales: a multiplication here would be this package computing money, which it does not do.
361
+ *
362
+ * Anything that is not a plain integer string is `null` rather than a guess. `Number.parseInt` on
363
+ * `"0.105"` answers `0`, which is a wrong amount rather than a missing one.
364
+ */
365
+ function minorAmount(value) {
366
+ if (typeof value !== "string" || !/^-?\d+$/.test(value)) return null;
367
+ const parsed = Number(value);
368
+ return Number.isSafeInteger(parsed) ? parsed : null;
369
+ }
370
+ /** A currency as this package stores it. Paddle sends uppercase; every other rail here is lowercase. */
371
+ function currencyOf(value) {
372
+ return typeof value === "string" && value !== "" ? value.toLowerCase() : null;
373
+ }
374
+ /**
375
+ * The money row a transaction implies.
376
+ *
377
+ * `providerEventAt` comes from the caller — the **envelope's** `occurred_at`, never `updated_at` — for
378
+ * the reason the envelope schema states at the field.
379
+ */
380
+ function transactionEvent(transaction, occurredAt, environment) {
381
+ const subscriptionId = transaction.subscription_id ?? null;
382
+ const status = transactionStatus(transaction.status, subscriptionId !== null);
383
+ const purchased = at(transaction.created_at, "a transaction's created_at");
384
+ return {
385
+ rail: "paddle",
386
+ providerTransactionId: transaction.id,
387
+ originalTransactionId: subscriptionId,
388
+ providerProductId: transactionPriceId(transaction),
389
+ role: "charge",
390
+ status,
391
+ environment,
392
+ purchasedAt: purchased,
393
+ expiresAt: subscriptionId === null ? null : purchased,
394
+ revokedAt: null,
395
+ amountMinor: minorAmount(transaction.details?.totals?.grand_total),
396
+ currency: currencyOf(transaction.details?.totals?.currency_code ?? transaction.currency_code),
397
+ providerEventAt: occurredAt,
398
+ payload: { ...transaction }
399
+ };
400
+ }
401
+ /**
402
+ * What Paddle says a paused subscription resumes at, verbatim — or nothing, for an open-ended pause.
403
+ *
404
+ * **The date is not in the field named after it**, which is the trap this function exists to hold. Recorded
405
+ * against a live sandbox on 2026-08-15: pausing immediately with `resume_at: "2026-10-01T00:00:00Z"` leaves
406
+ * `scheduled_change: { action: "resume", effective_at: "2026-10-01T00:00:00Z", resume_at: null }`. Paddle
407
+ * turns the request's `resume_at` into a scheduled *resume* whose `effective_at` is the date, and blanks
408
+ * `resume_at` — that field is populated only while a `pause` is scheduled and the subscription is still
409
+ * `active`, which is not a paused subscription. Pausing with no resume date leaves `scheduled_change: null`.
410
+ *
411
+ * So both spellings are read and the one that means resumption wins. `effective_at` is taken only from a
412
+ * `resume` action: on a `cancel` it is when access ends, and on a `pause` it is when the pause begins —
413
+ * writing either into a resume date would be a wrong date in front of a paying customer.
414
+ */
415
+ function subscriptionResumesAt(subscription) {
416
+ const change = subscription.scheduled_change;
417
+ if (change === null || change === void 0) return null;
418
+ if (typeof change.resume_at === "string" && change.resume_at !== "") return change.resume_at;
419
+ return change.action === "resume" ? change.effective_at ?? null : null;
420
+ }
421
+ /**
422
+ * What is pending on a subscription, or nothing.
423
+ *
424
+ * **The field a screen reaches for first is empty exactly when this one fills.** Recorded against the
425
+ * sandbox on 2026-08-28: `cancel({ effective_from: "next_billing_period" })` leaves `status: "active"`,
426
+ * `canceled_at: null` and — the part that surprises — **`next_billed_at: null`**, with the date living only
427
+ * on `scheduled_change.effective_at`. So "Renews on {next_billed_at}" goes blank on precisely the
428
+ * subscription whose end date the customer most needs to see, while the row still says `active`.
429
+ * `update(subscription, { scheduled_change: null })` withdraws the cancellation and puts the date back.
430
+ *
431
+ * An action this build does not map refuses rather than being read as one of the three. That is
432
+ * {@link subscriptionStatus}'s rule and it is the same argument: a new Paddle action quietly normalized into
433
+ * `cancel` is a wrong date, or a wrong sentence, in front of a paying customer — and a `scheduled_change`
434
+ * with no action at all is a shape change, not an absence, because Paddle sends the object or sends null.
435
+ *
436
+ * **This deliberately does not change what {@link subscriptionResumesAt} answers.** That function reads
437
+ * `effective_at` only on a `resume`, which is why a scheduled *cancel* is invisible to the projection today.
438
+ * The two now parse one declared shape — {@link PaddleScheduledChange} — so whichever step decides what the
439
+ * projection should carry about a pending cancellation reconciles them in one place, with both readings in
440
+ * front of it.
441
+ */
442
+ function subscriptionPendingChange(subscription) {
443
+ const change = subscription.scheduled_change;
444
+ if (change === null || change === void 0) return null;
445
+ const action = change.action;
446
+ if (action !== "cancel" && action !== "pause" && action !== "resume") throw new PaymentsVerificationFailedError({ detail: `Paddle: scheduled change action "${action ?? ""}" is not one this build maps.` });
447
+ return {
448
+ action,
449
+ effectiveAt: change.effective_at ?? null,
450
+ resumeAt: change.resume_at ?? null
451
+ };
452
+ }
453
+ /**
454
+ * The state row a subscription implies. Carries no amount — a subscription is not a charge.
455
+ *
456
+ * `expiresAt` is the end of what has been paid for, and which field that is depends on the standing: a
457
+ * trial ends at its own date, everything else at the current billing period's end. A cancellation keeps
458
+ * the period already bought rather than taking it away, which is what `canceled` means in this package's
459
+ * status set.
460
+ */
461
+ function subscriptionEvent(subscription, occurredAt, environment) {
462
+ const status = subscriptionStatus(subscription.status);
463
+ const ends = subscription.status === "trialing" ? subscription.trial_dates?.ends_at ?? subscription.current_billing_period?.ends_at ?? null : subscription.current_billing_period?.ends_at ?? subscription.next_billed_at ?? null;
464
+ return {
465
+ rail: "paddle",
466
+ providerTransactionId: subscription.id,
467
+ originalTransactionId: subscription.id,
468
+ providerProductId: subscriptionPriceId(subscription),
469
+ role: "state",
470
+ status,
471
+ environment,
472
+ purchasedAt: at(subscription.created_at, "a subscription's created_at"),
473
+ expiresAt: maybeAt(ends, "a subscription's period end"),
474
+ revokedAt: null,
475
+ resumesAt: pauseResumesAt({
476
+ rail: "paddle",
477
+ status,
478
+ reported: subscriptionResumesAt(subscription)
479
+ }),
480
+ amountMinor: null,
481
+ currency: null,
482
+ providerEventAt: occurredAt,
483
+ payload: { ...subscription }
484
+ };
485
+ }
486
+ /**
487
+ * Whether this delivery belongs to another deployment sharing the same Paddle sandbox.
488
+ *
489
+ * True only when both sides named an environment and they differ. An unstamped delivery is not fenced —
490
+ * a transaction created in the Paddle dashboard carries no `custom_data`, and fencing on absence would
491
+ * silently drop real sales — and a deployment that does not know its own `ENVIRONMENT` fences nothing,
492
+ * which is precisely how the other rails behave.
493
+ *
494
+ * **This is a fence, not an authorization.** It is read off unauthenticated `custom_data` on purpose: its
495
+ * job is to stop this deployment acting on another deployment's traffic, and the direction it can be
496
+ * abused in is a forger declining to be projected — which they achieve by not sending anything. Deciding
497
+ * *who owns* a purchase is {@link accountReferenceOf}'s job, and that one demands a MAC.
498
+ */
499
+ function fencedOut(custom, deployment) {
500
+ const stamped = custom?.[PADDLE_CUSTOM_ENV];
501
+ if (typeof stamped !== "string" || stamped === "" || deployment === void 0) return false;
502
+ return stamped !== deployment;
503
+ }
504
+ /**
505
+ * The account reference this deployment stamped into the checkout, or null.
506
+ *
507
+ * **Honored only when a MAC this deployment could have produced is beside it**, and that condition is the
508
+ * whole security of the field. `accountReference`'s contract says it is "a value this deployment's own
509
+ * server wrote and the store returned unchanged" — the route writes the provider-account link from it, and
510
+ * `linkProviderAccount` never rebinds, so the first pairing is permanent.
511
+ *
512
+ * `Paddle.Checkout.open` accepts `customData` with nothing but the publishable client token, and it does
513
+ * so on both forms of the call — beside an `items[]` array of price ids, and beside a `transactionId`,
514
+ * where the page's object replaces the one the server wrote. So `custom_data` on its own is **not**
515
+ * evidence our server wrote anything, and it is not evidence even when our server did: a stranger can put
516
+ * any string in it and permanently bind their Paddle customer to an account they chose. The env stamp does
517
+ * not save it either — the key names are exported constants in an open-source package and the value is one
518
+ * of three.
519
+ *
520
+ * A deployment that does not know its own `ENVIRONMENT` trusts no reference at all. That is the safe
521
+ * direction: the cost is a purchase that lands unbound and is repairable from the trail, where the other
522
+ * way round is an unauthenticated write into the account map that nothing ever undoes.
523
+ *
524
+ * **And the value must be the subject encoding, which the MAC alone does not make it.** A stamp can be
525
+ * authentic and still name nobody: a bare id is what this rail wrote before subjects existed, and reading
526
+ * one as a user would hand a purchase to whoever else holds that id. So the reference is put through
527
+ * `decodeSubjectReference` — the one decoder, never a split written here — and anything that is not exactly
528
+ * the encoding is refused in the same direction as everything else above. The string is returned rather than
529
+ * the pair because a rail reports `accountReference` as a string; the route decodes it again through the same
530
+ * function, and gets the same answer.
531
+ */
532
+ async function accountReferenceOf(custom, deployment, secret) {
533
+ if (deployment === void 0) return null;
534
+ const reference = custom?.[PADDLE_CUSTOM_ACCOUNT];
535
+ const stampedEnv = custom?.[PADDLE_CUSTOM_ENV];
536
+ const proof = custom?.[PADDLE_CUSTOM_PROOF];
537
+ if (typeof reference !== "string" || reference === "") return null;
538
+ if (typeof stampedEnv !== "string" || typeof proof !== "string") return null;
539
+ if (decodeSubjectReference(reference) === void 0) return null;
540
+ if (stampedEnv !== deployment) return null;
541
+ return await proofMatches(reference, deployment, secret, proof) ? reference : null;
542
+ }
543
+ /**
544
+ * The proof this deployment stamps beside an account reference, and the only reason the reference is
545
+ * worth anything.
546
+ *
547
+ * An HMAC over the environment and the user id, keyed with a secret a stranger does not have. The message
548
+ * is domain-separated by a fixed prefix so this MAC can never be confused with the webhook-body signature
549
+ * that shares its key: the two answer different questions, and a value satisfying both would be a
550
+ * cross-protocol attack waiting to be found.
551
+ *
552
+ * The key is the notification destination's signing secret because it is already per-environment, already
553
+ * rotated with the rail, and already known only to this deployment and to Paddle — and Paddle is not the
554
+ * attacker here. The attacker is anyone who can load the paywall, which is everyone.
555
+ */
556
+ async function accountReferenceProof(reference, deployment, secret) {
557
+ const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
558
+ name: "HMAC",
559
+ hash: "SHA-256"
560
+ }, false, ["sign"]);
561
+ const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message(reference, deployment)));
562
+ return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
563
+ }
564
+ /** Domain separation, so this MAC and the webhook body signature can never be mistaken for one another. */
565
+ const ACCOUNT_REFERENCE_DOMAIN = "pithy:paddle:account-reference:v1:";
566
+ /** What the MAC covers: the domain, the environment, and the subject — in that order, and never one of them. */
567
+ function message(reference, deployment) {
568
+ return `${ACCOUNT_REFERENCE_DOMAIN}${deployment}:${reference}`;
569
+ }
570
+ /** Whether a stamped proof matches, compared in constant time by the runtime rather than by `===`. */
571
+ async function proofMatches(reference, deployment, secret, candidate) {
572
+ const bytes = hexToBytes(candidate);
573
+ if (bytes === void 0) return false;
574
+ const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
575
+ name: "HMAC",
576
+ hash: "SHA-256"
577
+ }, false, ["verify"]);
578
+ return await crypto.subtle.verify("HMAC", key, bytes, new TextEncoder().encode(message(reference, deployment)));
579
+ }
580
+ /** Decode hex, or undefined when it is not hex. */
581
+ function hexToBytes(value) {
582
+ if (value.length === 0 || value.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(value)) return void 0;
583
+ const bytes = new Uint8Array(value.length / 2);
584
+ for (let index = 0; index < bytes.length; index += 1) bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
585
+ return bytes;
586
+ }
587
+ //#endregion
588
+ export { PADDLE_CUSTOM_ACCOUNT, PADDLE_CUSTOM_ENV, PADDLE_CUSTOM_PROOF, PaddleAdjustment, PaddleEvent, PaddleScheduledChange, PaddleSubscription, PaddleSubscriptionPreview, PaddleTotals, PaddleTransaction, PaddleUpdateSummary, accountReferenceOf, accountReferenceProof, at, currencyOf, fencedOut, minorAmount, subscriptionEvent, subscriptionPendingChange, subscriptionPriceId, subscriptionResumesAt, subscriptionStatus, transactionEvent, transactionPriceId, transactionStatus };
@@ -0,0 +1,45 @@
1
+ import type { PaymentsPaddleCredentials } from "../../secret/registry";
2
+ import type { PortalHandoff, PortalSessionInput } from "../contract";
3
+ import { type PaddleEnvironment, type PaddleHttpFetch } from "./api";
4
+ /**
5
+ * The customer portal — where a Paddle subscriber changes a card or cancels, under Paddle's own rules.
6
+ *
7
+ * ## The links are 24-hour bearer credentials, not the single-use tokens the issue describes
8
+ *
9
+ * `POST /customers/{ctm_…}/portal-sessions` returns `urls.general.overview` plus, per subscription,
10
+ * `cancel_subscription` and `update_subscription_payment_method`. The issue calls those "single-use,
11
+ * short-lived". Live, the overview URL carries `token=pga_<JWT>` whose `iat` and `exp` are 86400 seconds
12
+ * apart, with scopes including `customer.subscription.update`, `customer.customer.update` and
13
+ * `customer.transaction.create`. It is a day of control over that customer's billing.
14
+ *
15
+ * So "never cached or persisted" has to mean more than not writing them to a table: never logged, never
16
+ * in an audit payload, and never a redirect target something downstream could read out of a `Referer`.
17
+ * Nothing in this module returns them anywhere but to the caller, and the route emits an audit row naming
18
+ * the customer and not one URL.
19
+ *
20
+ * ## The caller never names the customer, and never names a subscription
21
+ *
22
+ * `providerAccountId` comes from the provider-account map, keyed on the authenticated caller.
23
+ * `subscriptionIds` comes from that caller's own purchase rows. The `/portal` route takes no body at all,
24
+ * which is the request contract that makes this safe: either field there would let anyone mint
25
+ * authenticated cancel links against somebody else's subscription.
26
+ *
27
+ * ## There is no return URL, and config refuses one
28
+ *
29
+ * Paddle's portal takes no return parameter. {@link PortalSessionInput.returnUrl} is optional precisely so
30
+ * a rail can decline it in the type rather than accept one and silently drop it, and `paddle.portalReturnUrl`
31
+ * is refused by config rather than accepted and ignored — a URL an adopter wrote that nothing reads is a
32
+ * lie in a file they trust.
33
+ */
34
+ /** What creating a portal session needs: the credentials, the account, and the transport. */
35
+ export interface PaddlePortalOptions {
36
+ /** The rail's credentials. Only `apiKey` is used here, and it needs `customer_portal_session.write`. */
37
+ credentials: PaymentsPaddleCredentials;
38
+ /** Which Paddle account to reach. */
39
+ environment: PaddleEnvironment;
40
+ /** The HTTP seam. Defaults to the runtime's `fetch`. */
41
+ transport?: PaddleHttpFetch;
42
+ }
43
+ /** Create a portal session for one customer, and return where they manage their billing. */
44
+ export declare function createPaddlePortalSession(input: PortalSessionInput, options: PaddlePortalOptions): Promise<PortalHandoff>;
45
+ //# sourceMappingURL=portal.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../../src/rails/paddle/portal.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAA2B,MAAM,aAAa,CAAC;AAC9F,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA+B,MAAM,OAAO,CAAC;AAElG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,wGAAwG;IACxG,WAAW,EAAE,yBAAyB,CAAC;IACvC,qCAAqC;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAuCD,4FAA4F;AAC5F,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAsCxB"}