@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,871 @@
1
+ import type { CreatedDiscount, DiscountTerms, SubscriptionPricing } from "../data/discount";
2
+ import type { PaymentsPurchase } from "../data/purchase";
3
+ import type { PaymentsRail } from "../data/rail";
4
+ import type { PaymentsSubject } from "../data/subject";
5
+ import type { RefundRequest, SubscriptionCancelTiming, SubscriptionChangeQuote, SubscriptionStanding } from "../data/subscription";
6
+ import type { ProviderEventInput } from "../projection/event";
7
+ /**
8
+ * The one contract every rail implements, and the one it deliberately does not.
9
+ *
10
+ * A rail does three things: it verifies a receipt a client submitted, it parses a notification the store
11
+ * pushed, and it re-reads the current state of a purchase already projected. All three produce the same
12
+ * normalized event, so the projection writer never learns which store it came from — that is what lets one
13
+ * idempotent writer serve three stores and one entitlement resolve across them.
14
+ *
15
+ * ## Why `refresh` is on the shared contract and `createCheckoutSession` is not
16
+ *
17
+ * Every store can be asked what a purchase looks like now, and every store's answer is worth having: webhooks
18
+ * are dropped, push subscriptions are misconfigured, signing keys rotate, and a subscription can lapse with no
19
+ * notification arriving at all. So `refresh` is not a Stripe-shaped method the other two would stub — it is the
20
+ * question the reconciliation Workflow exists to ask, and all three rails answer it for real. A rail that
21
+ * cannot answer for one *particular* purchase returns `undefined`, which is a fact about that purchase rather
22
+ * than a hole in the rail.
23
+ *
24
+ * ## Why Stripe's session creation is a separate interface
25
+ *
26
+ * Stripe additionally creates the purchase. That asymmetry is real, and this contract does not paper over
27
+ * it. An Apple or Google purchase has **already happened inside the store SDK** by the time the server hears
28
+ * of it: the app presented the sheet, the user paid, and the server's job begins at a receipt. A Stripe
29
+ * purchase is one Pithy initiates, by creating a hosted Checkout Session and sending the browser to it.
30
+ *
31
+ * A single abstraction covering both would force Apple and Google to declare a `createCheckoutSession` with
32
+ * no meaning for them, and every such method is a lie a future maintainer has to read past — worse, one
33
+ * somebody eventually calls. So {@link CheckoutRail} is its own interface, and a rail that initiates
34
+ * purchases implements both. Nothing needs to widen when a fourth rail arrives on either side.
35
+ *
36
+ * ## Why managing a subscription is a third interface, and what changed to allow it
37
+ *
38
+ * {@link SubscriptionRail} is the same split for the same reason: a StoreKit or Play subscription is changed
39
+ * inside the store's own UI, on the customer's device, and a rail that had to declare `changePlan` to satisfy
40
+ * the shared contract would declare a method that cannot be written.
41
+ *
42
+ * It is also **the amendment of 2026-08-28 to #79's locked decision 2**, and the distinction is narrow enough
43
+ * to be worth stating precisely, because the docs it corrects said the wider thing. The kit may *invoke* a
44
+ * plan change and pass the provider's own figures through unmodified. It still never *computes* proration,
45
+ * tax, or SCA: no amount in {@link SubscriptionChangeQuote} is derived from another amount, nothing multiplies
46
+ * a price by a fraction of a period, and nothing checks the provider's arithmetic. The line is between asking
47
+ * a store what a change costs and answering that question ourselves — the second is a number a customer holds
48
+ * against their statement, and the statement is the one they will believe.
49
+ *
50
+ * ## Why a rail cannot name an owner
51
+ *
52
+ * Everything a rail returns is an {@link UnboundProviderEvent} — a provider event with **neither half** of the
53
+ * subject pair. That is a type-level fact, not a convention: a webhook arrives carrying the store's own
54
+ * identifier and nothing else, so a rail that could fill an owner in could be talked into filling in the wrong
55
+ * one. Binding happens in exactly one place, the route, from the authenticated caller through the configured
56
+ * subject seam or from the provider-account map.
57
+ *
58
+ * Omitting *both* halves is what makes the guarantee hold. A rail that could name a `subjectId` and leave the
59
+ * kind to be supplied from config would be pairing an id from a store with a type from somewhere else — and
60
+ * nothing keeps an organization id from equalling some user's, so the two together would grant one holder's
61
+ * subscription to the other. A subject is read and written whole. See `data/subject.ts`.
62
+ *
63
+ * The one thing a rail may report about ownership is an {@link VerifiedNotification.accountReference} — the
64
+ * encoded subject reference *this deployment's own server* attached when it created the purchase, echoed back
65
+ * by the store. That is a claim about the purchase rather than a rail's verdict on who holds it, and it is
66
+ * what a rail with no client-submission path needs: a Stripe purchase is only ever heard about through a
67
+ * webhook, so the pairing of `cus_…` with a subject has to arrive with the notification or never at all.
68
+ */
69
+ /**
70
+ * A normalized provider event with its owner left out — **both halves of it**. The rail knows everything about
71
+ * the transaction and nothing about who it belongs to, and the shape says so.
72
+ *
73
+ * Derived by omission rather than declared beside {@link ProviderEventInput}, so a field added to the event is
74
+ * a field every rail may report, and the only fields a rail may never report are the two named here.
75
+ */
76
+ export type UnboundProviderEvent = Omit<ProviderEventInput, "subjectType" | "subjectId">;
77
+ /** What a rail needs from the request it is serving. The clock, and which deployment is asking. */
78
+ export interface RailRequestContext {
79
+ /** The clock, for certificate validity and freshness windows. Injected so verification is deterministic. */
80
+ now: Date;
81
+ /**
82
+ * This deployment's `ENVIRONMENT` var, verbatim — `dev`, `staging`, `prod` — or undefined.
83
+ *
84
+ * For a rail whose store is **one namespace across every environment**, which is the case for Lemon
85
+ * Squeezy: test mode is a flag on an object, not a separate store, so a `dev` deployment and a `staging`
86
+ * deployment pointed at one store both hear everything the other's buyers do. Such a rail stamps this
87
+ * value into the checkout it creates and reads it back off the webhook, and an event stamped for another
88
+ * deployment projects nothing.
89
+ *
90
+ * Deliberately the raw var and not `deploymentEnvironment`'s two-valued answer: that returns `sandbox`
91
+ * for `dev` and `staging` alike, so fencing on it would not separate the two environments this exists to
92
+ * separate. Optional because the other three stores partition by credential and have nothing to fence.
93
+ */
94
+ deployment?: string;
95
+ /**
96
+ * The locale a figure in the answer is rendered for — `Translator.formattingLocale`, region and all.
97
+ *
98
+ * **One method reads it: {@link SubscriptionRail.previewChange}**, whose answer carries `rendered` on
99
+ * every amount, and it is here rather than on {@link SubscriptionChangeInput} because a locale is a fact
100
+ * about the reader of a response, not about the subscription being changed. Every other call on this
101
+ * context — a webhook, a verification, a refresh — answers a machine, and a machine has no locale.
102
+ *
103
+ * **Never a request field, and never `Accept-Language` read directly.** A locale a client can name in a
104
+ * body is a locale a client sets, and the header is only one of four inputs the kit's own negotiation
105
+ * weighs — reading it here would render the money in a language the rest of the same response is not
106
+ * written in. The route resolves it from the translator seam, which is what `@pithy-sh/email` does per
107
+ * recipient and what `@pithy-sh/i18n` fills in per request.
108
+ *
109
+ * Optional, and its absence is not an error: `data/renderMoney.ts` states the fallback rather than
110
+ * guessing one, because a quote in the wrong language is recoverable and a quote with no figure is not.
111
+ */
112
+ locale?: string;
113
+ }
114
+ /**
115
+ * One inbound notification, as bytes and headers rather than as a `Request`.
116
+ *
117
+ * Bytes because every rail's authenticity check covers the **exact received body** — Apple signs it, Stripe
118
+ * HMACs it — and re-serializing a parsed object would change what was signed. Headers because two of the
119
+ * three rails put their proof in one.
120
+ *
121
+ * Deliberately not a `Request`: a request body is a stream that can be read once, and a rail reading it
122
+ * would leave the route's own validator with nothing. The guard reads it once through Hono's body cache and
123
+ * hands the same string here, so the signature and the handler see the identical bytes.
124
+ */
125
+ export interface WebhookDelivery {
126
+ /** The exact received body, decoded as UTF-8. */
127
+ body: string;
128
+ /** The delivery's headers — where Google's OIDC token and Stripe's signature live. */
129
+ headers: Headers;
130
+ }
131
+ /** A verified client submission: what was bought, and the store-account identifier to link it by. */
132
+ export interface VerifiedPurchase {
133
+ /** The transaction, normalized. The route binds the authenticated caller onto it. */
134
+ event: UnboundProviderEvent;
135
+ /**
136
+ * The store's own account identifier — Apple's `appAccountToken`, Google's `obfuscatedAccountId`, Stripe's
137
+ * customer id — or null when the purchase carried none. This is what a later webhook resolves a user
138
+ * through, so a submission that carries one is what stops that webhook arriving orphaned.
139
+ */
140
+ providerAccountId: string | null;
141
+ /**
142
+ * The **encoded subject reference** this deployment's own server attached when it created the purchase,
143
+ * echoed back by the store — Stripe's `client_reference_id`, which the `/checkout` route sets from the
144
+ * caller's resolved subject. `user:ada`, `organization:acme`: the pair, as `encodeSubjectReference` in
145
+ * `data/subject.ts` writes it, and read back only by `decodeSubjectReference`. Never split by hand — one
146
+ * encoding with one decoder is what keeps a value stamped by one code path readable by another.
147
+ *
148
+ * Set only by a rail whose purchases Pithy initiates. Apple's `appAccountToken` and Google's
149
+ * `obfuscatedAccountId` deliberately do **not** go here: those are set by the *app*, which may put anything
150
+ * in them, so treating one as an owner would make a client's choice of value decide who a purchase belongs
151
+ * to. This is the value a server wrote and a store returned unchanged.
152
+ *
153
+ * A string all the same, and untrusted all the same: it comes back as bytes from a store. **It decodes or
154
+ * it names nobody** — a bare id, the shape every pre-subject client sent, is not a user, and a kind this
155
+ * build does not know is not a kind. The route uses it to refuse a submission whose own reference names
156
+ * somebody else, before projecting it.
157
+ */
158
+ accountReference?: string | null;
159
+ }
160
+ /** A verified notification: authentic, recorded, and sometimes carrying no state change at all. */
161
+ export interface VerifiedNotification {
162
+ /**
163
+ * The rail's own event id — Apple's `notificationUUID`, Stripe's event id. `UNIQUE (rail,
164
+ * providerEventId)` is what makes a redelivery recognized rather than reprocessed, and all three providers
165
+ * deliver at-least-once.
166
+ */
167
+ providerEventId: string;
168
+ /** The notification as received, stored whole. What makes "why didn't this renew" answerable. */
169
+ payload: Record<string, unknown>;
170
+ /**
171
+ * The transaction the notification reports, or **null when it reports no transaction state**. Null is a
172
+ * successful outcome, not a failure: a test notification, a consumption request, a declined refund, and a
173
+ * type the store shipped after this package did are all authentic and all change nothing. The row is still
174
+ * recorded, so the reconciliation pass can see what arrived.
175
+ */
176
+ event: UnboundProviderEvent | null;
177
+ /** The store account identifier the notification carried, or null. */
178
+ providerAccountId: string | null;
179
+ /**
180
+ * A refund the rail reported by **order id alone**, with no state attached — or null.
181
+ *
182
+ * Google's voided-purchase notification is the only one shaped this way. It names an order and says it was
183
+ * refunded, and Play offers no lookup that turns it back into a purchase: the one-time endpoint takes the
184
+ * product id as a path segment, and the notification does not carry one. So the rail cannot produce an
185
+ * `event`, and for a while this was recorded and dropped — leaving a refunded non-consumable granting its
186
+ * entitlement forever.
187
+ *
188
+ * The missing product was never in Play, though. It is in **our** row: an order id is exactly what a Google
189
+ * purchase's `providerTransactionId` is. So the rail reports the order and the route, which owns the
190
+ * database, resolves it — the same division as everywhere else, where a rail knows the store and the route
191
+ * knows the projection. An authentic void is itself the refund record, in the same way Apple's `REFUND`
192
+ * notification is; nothing needs to re-ask the store what it already said.
193
+ */
194
+ voidedOrderId?: string | null;
195
+ /**
196
+ * The encoded subject reference this deployment attached when it created the purchase, echoed back — see
197
+ * {@link VerifiedPurchase.accountReference} for the encoding, and for why this is not the same as a rail
198
+ * naming an owner.
199
+ *
200
+ * On a rail with no client-submission path this is the **only** way the account map is ever populated: a
201
+ * Stripe webhook arrives carrying `cus_…`, and the pairing with a subject exists nowhere else. The route
202
+ * decodes it, writes the link from it, and `linkProviderAccount` never rebinds, so the first pairing wins.
203
+ *
204
+ * **It is ranked last in the owner trust order, and it fails closed.** Last because everything above it in
205
+ * `projection/owner.ts` is a fact this server established about a purchase it already projected, and this is
206
+ * a string that made a round trip through somebody else's system — Paddle's is stamped with a MAC precisely
207
+ * because a browser can overwrite it. Closed because `decodeSubjectReference` returns `undefined` for
208
+ * anything that is not exactly the encoding, and `undefined` means the event is recorded as an **orphan**,
209
+ * replayable when an account links, granting nothing. A decode miss is never read as a bare user id: that
210
+ * guess would attribute one customer's renewal to whoever happens to hold the id they sent.
211
+ */
212
+ accountReference?: string | null;
213
+ /**
214
+ * A second event the same notification implies, describing the **subscription's standing** where `event`
215
+ * describes a **charge** — or null, which is the case on every rail but one.
216
+ *
217
+ * Exists because one store reports the two separately and neither message names the other's key. A Lemon
218
+ * Squeezy `subscription_payment_*` webhook carries an invoice: the money, and nothing about whether the
219
+ * subscription is still live. Its `subscription_*` webhooks carry the standing and no money. So that rail
220
+ * writes two rows — see {@link PurchaseRole} — and a notification that changes both has to say both.
221
+ *
222
+ * The case that forces it is a refund. Lemon Squeezy is a merchant of record and issues refunds on its own,
223
+ * for a chargeback or a tax dispute, with no local write preceding it; the invoice row must go `refunded` so
224
+ * the ledger claws back, *and* the subscription must stop granting, because the buyer has their money back.
225
+ * One event could do one or the other, and doing only the first leaves a refunded subscriber with the
226
+ * feature.
227
+ *
228
+ * The route projects it with the same owner as `event` and after it. It is never fulfilled for credit — a
229
+ * `state` row is not a charge, so `purchaseIsPaid` and the clawback both refuse it by role.
230
+ */
231
+ stateEvent?: UnboundProviderEvent | null;
232
+ /**
233
+ * Why an authentic notification produced no event, when that is worth recording — written to the webhook row's
234
+ * `error` column so it is queryable and the reconciliation pass can act on it.
235
+ *
236
+ * Null when there is nothing to say, which is the common case: a test notification is exactly what it looks
237
+ * like. It earns its place on the rails that *can* be authentically told about a purchase they cannot resolve
238
+ * — Play's voided-purchase notification names no product, so the delivery is real, the refund is real, and
239
+ * neither is projectable without a lookup only the Workflow can make. A row recording that with its reason is
240
+ * the difference between a repairable gap and a silent drop.
241
+ *
242
+ * **Which of the two it is decides whether the row is finished** — see {@link NotificationNote}.
243
+ */
244
+ note?: NotificationNote | null;
245
+ }
246
+ /**
247
+ * Why there is no event, and **where that answer came from**. Two cases, because there are two.
248
+ *
249
+ * `{ stated }` — the delivered bytes say it. A partial refund that takes nothing away, a notification type
250
+ * this build does not act on, an order Play reports voided. The same bytes get the same answer from the same
251
+ * build for ever, so the row is **finished** and a redelivery is answered `duplicate`.
252
+ *
253
+ * `{ read }` — a call to the provider came back empty and this note is that answer. Play has no purchase
254
+ * under the token, Lemon Squeezy no longer knows the subscription, Paddle will not show the transaction an
255
+ * adjustment names. **Repairable**, and this is #341: three rails derived a note this way and it finished the
256
+ * row. A read that answers "no such thing" can be a race — an RTDN outrunning Play's own read-after-write, a
257
+ * key rotated mid-flight, a shared sandbox — so the second answer differs from the first, and the delivery
258
+ * that would have carried it was already being told it was a duplicate.
259
+ *
260
+ * **A note is safe as terminal only when it comes from a source that cannot have failed.** The delivered
261
+ * bytes are such a source; a read is not. So the provenance travels with the text rather than being inferred
262
+ * at the far end, and the two are one field so no rail can claim both.
263
+ *
264
+ * The same rule applies wherever a note finishes a row: the webhook handler and the Paddle events sweep both
265
+ * read this, and both treat `read` as a repairable failure rather than a completion.
266
+ */
267
+ export type NotificationNote = {
268
+ /** What the delivered bytes say. Terminal. */
269
+ readonly stated: string;
270
+ } | {
271
+ /** What a provider read answered, and could answer differently next time. Repairable. */
272
+ readonly read: string;
273
+ };
274
+ /** The note's text, whichever kind it is. An operator reads the two the same way; the row does not. */
275
+ export declare function noteText(note: NotificationNote | null | undefined): string | undefined;
276
+ /** Whether this note leaves the delivery repairable — true only for one a read produced. */
277
+ export declare function noteIsRepairable(note: NotificationNote | null | undefined): boolean;
278
+ /** Every rail. Verification of a client submission, parsing of a pushed notification, and a state re-read. */
279
+ export interface PaymentsRailProvider {
280
+ /** Which store this provider speaks for. */
281
+ readonly rail: PaymentsRail;
282
+ /**
283
+ * Verify a receipt or signed transaction a client submitted, exactly as the store SDK returned it. Throws
284
+ * `payments/invalid_receipt` when it cannot be read and `payments/verification_failed` when the store does
285
+ * not vouch for it.
286
+ */
287
+ verify(receipt: string, context: RailRequestContext): Promise<VerifiedPurchase>;
288
+ /**
289
+ * Verify and parse a pushed notification. Takes the delivery's bytes and headers rather than a parsed
290
+ * object, because authenticity lives in different places per rail — Apple signs the body, Google puts an
291
+ * OIDC token in a header, Stripe puts an HMAC in one — and every one of those covers the exact received
292
+ * bytes. Throws when authenticity cannot be established; the guard maps that to
293
+ * `payments/webhook_unverified`.
294
+ */
295
+ parseNotification(delivery: WebhookDelivery, context: RailRequestContext): Promise<VerifiedNotification>;
296
+ /**
297
+ * Re-read the current state of a purchase this deployment already projected — the reconciliation path.
298
+ *
299
+ * Takes the stored row rather than a handful of ids, because what identifies a purchase at its store differs
300
+ * per rail and some of it survives only in the payload: Apple keys a subscription family on
301
+ * `originalTransactionId`, Play keys one on the purchase token, and Stripe on `sub_…`. Handing the whole row
302
+ * over means adding a rail never widens this signature.
303
+ *
304
+ * **The returned event's `providerEventAt` is the clock, not a store timestamp**, and that is deliberate. A
305
+ * refresh is a read of the state *now*, so it is the freshest fact anyone has — dating it earlier would let
306
+ * the monotonic write rule discard the very repair the run exists to make.
307
+ *
308
+ * `undefined` means the store has nothing to say about this purchase: the rail cannot address it (a one-time
309
+ * purchase whose store offers no lookup), or the store no longer knows it. That is a normal answer and leaves
310
+ * the row exactly as it stood. A store that cannot be *reached* throws `payments/provider_unavailable`
311
+ * instead, which is what tells the Workflow to fail the step and retry rather than record a repair that
312
+ * never happened.
313
+ */
314
+ refresh(purchase: PaymentsPurchase, context: RailRequestContext): Promise<UnboundProviderEvent | undefined>;
315
+ /**
316
+ * Re-read a notification body this package already recorded, **without re-establishing authenticity**.
317
+ *
318
+ * The row it comes from was written by a delivery that verified, or by a sweep reading the store's own
319
+ * event stream over an authenticated connection, so the bytes are already vouched for. Re-verifying is not
320
+ * merely redundant — it is impossible: a signature covers headers this table never stored, and a JWS has a
321
+ * validity window that expired long ago.
322
+ *
323
+ * It exists for one caller: the repair that runs when an account links. An orphan is a purchase with
324
+ * nobody to project it against, and the only thing that changes is a `provider_accounts` row appearing
325
+ * later. Nothing about the event changes, so the payload is where the purchase is — which is precisely
326
+ * what {@link VerifiedNotification.payload} is stored whole for.
327
+ *
328
+ * **Optional, and a rail that cannot do it says so by not implementing it.** Apple and Google store a
329
+ * signed blob whose claims this build reads only through a verifier, and Lemon Squeezy's parse needs a live
330
+ * subscription read; a stub returning a half-read event would be worse than the absence. Those rails'
331
+ * orphans are repaired by the store's own redelivery, as they were.
332
+ *
333
+ * `undefined` means the payload is not one this rail can replay — a shape from an older build, an event
334
+ * type since dropped. That is a fact about the row, not a failure, and the repair leaves it exactly as it
335
+ * stood.
336
+ */
337
+ replay?(payload: Record<string, unknown>, context: RailRequestContext): Promise<VerifiedNotification | undefined>;
338
+ }
339
+ /** What a hosted checkout session needs. The catalog product is resolved before this is called. */
340
+ export interface CheckoutSessionInput {
341
+ /** The rail's own price identifier for the product being bought. */
342
+ providerProductId: string;
343
+ /** Whether this buys a recurring subscription or a one-off. Decides the hosted flow the store presents. */
344
+ subscription: boolean;
345
+ /**
346
+ * The subject the purchase is for — the authenticated caller, or the organization the project bills on
347
+ * their behalf, as the configured subject seam resolved it.
348
+ *
349
+ * Passed as the pair rather than an id so the rail stamps `encodeSubjectReference(input.subject)` into the
350
+ * checkout it creates, and the webhook that follows arrives already naming a holder this server chose. A
351
+ * rail that received an id alone would have to pair it with a kind from config to build that reference,
352
+ * which is the one pairing `data/subject.ts` forbids.
353
+ */
354
+ subject: PaymentsSubject;
355
+ /**
356
+ * The store account this caller already has, from the provider-account map, or null on a first purchase.
357
+ *
358
+ * Passing it is what keeps one buyer to one store account. Without it every checkout creates a fresh
359
+ * customer, and a user's second purchase would be invisible from the billing portal their first one made.
360
+ */
361
+ providerAccountId?: string | null;
362
+ /** Where the store sends the browser after a completed purchase. */
363
+ successUrl: string;
364
+ /**
365
+ * Where the store sends the browser if the purchase is abandoned, or undefined for a store that offers
366
+ * nowhere to abandon *to*.
367
+ *
368
+ * Optional for the same reason {@link PortalSessionInput.returnUrl} is: Lemon Squeezy's hosted checkout
369
+ * has no cancel destination — a buyer who backs out closes the tab — and a required field there would
370
+ * mean asking an adopter for a URL the rail then silently discarded.
371
+ */
372
+ cancelUrl?: string;
373
+ /**
374
+ * A discount code to apply, passed to the store **unchanged**, or undefined.
375
+ *
376
+ * The store calculates the price. Pithy never computes a discounted amount and never checks a code against
377
+ * anything of its own: the provider is the authority on what is owed, and a second calculation here would
378
+ * be a second answer to the one question a customer will check against their card statement.
379
+ *
380
+ * An invalid or expired code therefore fails at the store, and the rail turns that into
381
+ * `payments/discount_invalid` naming the code — distinctly from a payment failure, because a customer told
382
+ * "something went wrong" at checkout concludes their card was declined.
383
+ */
384
+ discountCode?: string;
385
+ }
386
+ /** What a billing-portal session needs: the store account whose subscription is being managed. */
387
+ export interface PortalSessionInput {
388
+ /** The store's own account identifier for the caller, resolved from the provider-account map. */
389
+ providerAccountId: string;
390
+ /**
391
+ * Where the store sends the browser when the user is done, or undefined for a store that offers nowhere
392
+ * to return to.
393
+ *
394
+ * Optional because one store genuinely is shaped that way, and saying so in the type is better than the
395
+ * alternative. Lemon Squeezy's customer portal is a signed, expiring link read off the customer object;
396
+ * it takes no return parameter, and the subscriber closes the tab. A required field there would leave
397
+ * the rail silently discarding a URL an adopter configured and believed in — the failure would be a
398
+ * button that goes nowhere rather than a type error. So the contract admits the gap, and a project
399
+ * running that rail alone is never asked for a URL nothing will use.
400
+ */
401
+ returnUrl?: string;
402
+ /**
403
+ * The store's own subscription ids this caller owns, for a store that mints per-subscription deep links.
404
+ *
405
+ * **Resolved by the route from the caller's own purchase rows, never from a request body.** `/portal`
406
+ * takes no body at all, and that is the request contract that makes the whole surface safe: a field here
407
+ * naming a subscription would let any signed-in caller ask for authenticated cancel links to somebody
408
+ * else's — the exact vulnerability {@link providerAccountId} coming from the account map exists to close.
409
+ *
410
+ * Undefined for the rails whose portal is one page for the whole account.
411
+ */
412
+ subscriptionIds?: readonly string[];
413
+ }
414
+ /**
415
+ * How a browser is handed to a store's payment page. Pithy never owns payment UI, SCA, or tax, and never
416
+ * *computes* proration.
417
+ *
418
+ * **"Never computes" is narrower than what this line used to say, and the narrowing is deliberate** (#79's
419
+ * locked decision 2, amended 2026-08-28). A checkout still names no amount and no quantity: the price is the
420
+ * price, and a checkout that could carry a figure is a checkout a client could put a figure on. What the kit
421
+ * may now do is *invoke* a plan change on an existing subscription and pass the provider's own preview through
422
+ * unmodified — see {@link SubscriptionRail}, which is a separate interface reached by a separate route, and
423
+ * which produces no figure of its own either.
424
+ *
425
+ * **A union, because one store has no URL to give.** Stripe and Lemon Squeezy both mint a hosted page and
426
+ * answer with its address, and for eleven months that was the whole shape — `{ url }`. Paddle's overlay and
427
+ * inline modes never leave the adopter's page: the server creates a transaction, and the browser opens it
428
+ * with Paddle.js against a publishable client token. There is no address to send anyone to, so a `{ url }`
429
+ * return could only be filled with a lie or with an empty string.
430
+ *
431
+ * `redirect` is what the two older rails return, unchanged in every field. The widening costs them nothing,
432
+ * and a screen that only ever handled a redirect keeps working by narrowing on `kind` — which is a compile
433
+ * error where it is missing rather than a runtime surprise.
434
+ */
435
+ export type CheckoutHandoff = {
436
+ /** A hosted page the browser is sent to. */
437
+ kind: "redirect";
438
+ /** The absolute URL to send the browser to. */
439
+ url: string;
440
+ } | {
441
+ /** A transaction the browser opens with Paddle.js, over the adopter's own page. */
442
+ kind: "paddle";
443
+ /** The transaction the server created — `txn_…`. What `Paddle.Checkout.open` is given. */
444
+ transactionId: string;
445
+ /**
446
+ * The publishable client token Paddle.js initializes with — `live_…` or `test_…`.
447
+ *
448
+ * Publishable by design, exactly as a Stripe price id is: it is what a browser needs to open a
449
+ * checkout, and nothing about verification depends on its secrecy. The API key and the webhook
450
+ * signing secret are secrets and never appear here.
451
+ */
452
+ clientToken: string;
453
+ /** Which Paddle environment the token belongs to. `Paddle.Environment.set` takes it verbatim. */
454
+ environment: "sandbox" | "production";
455
+ /** Whether the checkout opens over the page or inside a container the screen provides. */
456
+ displayMode: "overlay" | "inline";
457
+ /**
458
+ * Where a buyer who paid is sent, from `config.paddle.successUrl`.
459
+ *
460
+ * On the handoff because Paddle.js takes it as `settings.successUrl` at the moment the checkout is
461
+ * opened, and that moment is in the browser. It still comes from config and never from a request:
462
+ * a client that could name a return URL could send a paying customer to a page it controls.
463
+ */
464
+ successUrl: string;
465
+ };
466
+ /** One subscription's authenticated portal deep links, as a store hands them back. */
467
+ export interface PortalSubscriptionLinks {
468
+ /** The store's own subscription id — `sub_…`. */
469
+ subscriptionId: string;
470
+ /** Where this subscription is canceled. */
471
+ cancel: string;
472
+ /** Where this subscription's payment method is changed. */
473
+ updatePaymentMethod: string;
474
+ }
475
+ /**
476
+ * A billing portal, as a store returns it.
477
+ *
478
+ * `url` is the overview page every rail has. `subscriptions` is the part only Paddle offers: authenticated
479
+ * deep links straight to one subscription's cancel and update-payment-method screens, so a subscription
480
+ * screen can render per-subscription actions rather than one "Manage billing" button.
481
+ *
482
+ * **Every URL here is a bearer credential for that customer's billing, and Paddle's is good for 24 hours.**
483
+ * Its overview link carries a `pga_` JWT whose `iat` and `exp` are 86400 seconds apart, with scopes
484
+ * covering `customer.subscription.update`, `customer.customer.update` and `customer.transaction.create` —
485
+ * verified against a live sandbox session, and materially different from the "single-use, short-lived" the
486
+ * issue described. So: never cached, never persisted, never logged, and never a redirect target something
487
+ * else could read out of a `Referer`.
488
+ */
489
+ export interface PortalHandoff {
490
+ /** The portal's overview page for this customer. */
491
+ url: string;
492
+ /** Per-subscription deep links, when the store offers them. Absent on the rails that do not. */
493
+ subscriptions?: readonly PortalSubscriptionLinks[];
494
+ }
495
+ /**
496
+ * The rails that *initiate* a purchase rather than merely hearing about one — Stripe, Lemon Squeezy, Paddle.
497
+ *
498
+ * Deliberately separate from {@link PaymentsRailProvider}: see the module doc. A rail implements both
499
+ * interfaces or only the first, and the route that needs a checkout session narrows to this one.
500
+ */
501
+ export interface CheckoutRail {
502
+ /** Create a checkout for one product, and say how the browser reaches it. */
503
+ createCheckoutSession(input: CheckoutSessionInput, context: RailRequestContext): Promise<CheckoutHandoff>;
504
+ /** Create a billing-portal session, where a subscriber manages or cancels. */
505
+ createPortalSession(input: PortalSessionInput, context: RailRequestContext): Promise<PortalHandoff>;
506
+ }
507
+ /** Whether a rail provider also initiates purchases. The one narrowing `/checkout` and `/portal` need. */
508
+ export declare function isCheckoutRail(provider: PaymentsRailProvider): provider is PaymentsRailProvider & CheckoutRail;
509
+ /**
510
+ * A rail that can *mint* a discount, as distinct from one that can merely apply one.
511
+ *
512
+ * **Its own interface, and the separation is load-bearing rather than tidy.** Applying a code must work with
513
+ * creation unimplemented — an adopter whose codes are minted by hand in a provider dashboard is fully served
514
+ * by the apply half, and making that half depend on this one would hold it hostage to a surface they never
515
+ * asked for. So `discountCode` rides on {@link CheckoutSessionInput}, which every checkout rail already
516
+ * takes, and this is a separate question asked separately.
517
+ *
518
+ * It is also the more dangerous half. It writes money-affecting objects into a payment provider through one
519
+ * shape over two APIs that agree on the concept and disagree on nearly every field, and the failures are
520
+ * quiet ones that surface on a customer's statement — see `data/discount.ts` for the three that were
521
+ * designed against. Minting a discount is an administrative act with a cost attached, which is why the route
522
+ * behind it carries its own scope and its own audit event rather than riding on an existing one.
523
+ */
524
+ export interface DiscountRail {
525
+ /**
526
+ * Create a discount at the store and return what it made.
527
+ *
528
+ * Throws `payments/discount_invalid` when the store refuses the terms, with the store's own reason in
529
+ * `detail`. Nothing here validates the terms a second time — `DiscountTerms` has already refused the
530
+ * combinations that are wrong on their face, and the store owns the rest.
531
+ */
532
+ createDiscount(terms: DiscountTerms, context: RailRequestContext): Promise<CreatedDiscount>;
533
+ /**
534
+ * The discount codes this store holds, newest first.
535
+ *
536
+ * A management client that can mint a code must be able to see what it minted — otherwise a pane over
537
+ * them computes *absent* rather than blocked, which no grant repairs (#247). Read from the store rather
538
+ * than from a table of ours: the store is where a code actually exists, and a local mirror would be a
539
+ * second answer that drifts the first time somebody uses the dashboard.
540
+ *
541
+ * Never reaches a browser. The set of codes an adopter has issued is a commercial fact, and the client
542
+ * projection draws the same line here it draws for SKUs and the `grants` block.
543
+ */
544
+ listDiscounts(context: RailRequestContext): Promise<readonly ListedDiscount[]>;
545
+ }
546
+ /** One discount as a store lists it. Deliberately less than {@link CreatedDiscount} — a list is not a receipt. */
547
+ export interface ListedDiscount {
548
+ /** The code a customer enters. */
549
+ code: string;
550
+ /** The store's own id. */
551
+ providerDiscountId: string;
552
+ /** How much comes off, rendered for a person — `20%`, `500 usd`. The store's own figures. */
553
+ amount: string;
554
+ /** How many times it has been claimed, when the store reports it. */
555
+ redemptions: number | null;
556
+ }
557
+ /**
558
+ * A rail that can say what a subscription pays now, what it becomes, and when.
559
+ *
560
+ * Separate from {@link DiscountRail} because they are separate abilities: a rail that can apply a code an
561
+ * adopter minted by hand must be able to report the resulting rate, whether or not it can mint one. Separate
562
+ * from the shared contract because Apple and Google have no equivalent — a store SDK subscription's price
563
+ * changes are the store's business and it does not publish a "what this becomes" figure.
564
+ *
565
+ * **This is the half that stops a bill changing unannounced.** A capability that can apply a discount but
566
+ * cannot report its end date has shipped the half that creates the surprise: from a customer's seat, a rate
567
+ * that silently lapses is indistinguishable from a billing error.
568
+ */
569
+ export interface PricingRail {
570
+ /**
571
+ * What this subscription pays now, what it will pay, and when that changes — or `undefined` when the store
572
+ * has nothing to say about it, which is the same answer `refresh` gives for the same reason.
573
+ *
574
+ * Every figure comes from the store. Nothing multiplies a price by a percentage here or anywhere else.
575
+ */
576
+ readPricing(purchase: PaymentsPurchase, context: RailRequestContext): Promise<SubscriptionPricing | undefined>;
577
+ }
578
+ /** Whether a rail reports pricing. Structural, like the others. */
579
+ export declare function isPricingRail(provider: PaymentsRailProvider): provider is PaymentsRailProvider & PricingRail;
580
+ /**
581
+ * Whether a rail can mint **and** list discounts. Structural, so a rail gains the ability without an edit here.
582
+ *
583
+ * **It ANDs both methods, and until #465 it did not.** {@link DiscountRail} declares two, and a guard probing
584
+ * `createDiscount` alone narrowed a rail that could mint and not list into a type promising both — so
585
+ * `GET {base}/admin/discounts` passed its own guard and then called a method that was not there. That is a
586
+ * `TypeError` inside a handler, which reaches a management pane as a 500, where a rail that plainly cannot
587
+ * mint gets `rail_not_configured` and a pane that can say so. No rail ever hit it: all three hosted rails
588
+ * declare both. It was a defect waiting for the fourth, and it is the one every other guard here is written
589
+ * against by name.
590
+ */
591
+ export declare function isDiscountRail(provider: PaymentsRailProvider): provider is PaymentsRailProvider & DiscountRail;
592
+ /**
593
+ * Which subscription is being changed, and what it becomes. One row, one price, and nothing else.
594
+ *
595
+ * **There is no field naming a subscription, and that absence is the security boundary.** The subscription
596
+ * arrives as a {@link PaymentsPurchase} — a decoded row only this deployment's own database produces, already
597
+ * carrying the subject that owns it — exactly as {@link PaymentsRailProvider.refresh} and
598
+ * {@link PricingRail.readPricing} take one. A `subscriptionId` here would be a value a caller supplies, and a
599
+ * value a caller supplies is one they can point at somebody else's subscription. This capability holds no
600
+ * members table and no ownership graph of its own, so there is nothing it could check that claim against: the
601
+ * refusal has to be structural. It is the same rule {@link PortalSessionInput.subscriptionIds} states for
602
+ * reads, applied where the verb writes.
603
+ *
604
+ * The route's own job follows from that: resolve the row from the authenticated caller's purchases, never
605
+ * from a request body.
606
+ */
607
+ export interface SubscriptionChangeInput {
608
+ /**
609
+ * The stored purchase whose subscription is being changed — the projection's own row, already owned.
610
+ *
611
+ * The whole row rather than the ids off it, for {@link PaymentsRailProvider.refresh}'s reason: what
612
+ * identifies a subscription at its store differs per rail and some of it survives only in the payload. A
613
+ * rail added later never widens this signature.
614
+ */
615
+ purchase: PaymentsPurchase;
616
+ /**
617
+ * The rail's own price identifier for the plan being moved to — **exactly one, never a list**.
618
+ *
619
+ * Paddle's subscription update *replaces* the items array: an item omitted from the request is removed from
620
+ * the subscription. So a `readonly string[]` here would be a delete verb wearing an update verb's name, and
621
+ * the shape of the mistake is a caller passing the one price they are moving to and silently dropping every
622
+ * add-on beside it. **Building the complete item list the provider is sent is the rail's obligation**, from
623
+ * the subscription it re-read, and it is the rail's because that is where the provider's replace semantics
624
+ * are known.
625
+ *
626
+ * Named as {@link CheckoutSessionInput.providerProductId} is, and meaning what it means there: the store's
627
+ * own SKU or price id, resolved from the catalog before this is called. One vocabulary, so a reader does not
628
+ * have to work out whether two spellings are two things.
629
+ */
630
+ providerProductId: string;
631
+ }
632
+ /** Which subscription is being canceled, and when the customer stops. */
633
+ export interface SubscriptionCancelInput {
634
+ /** The stored purchase whose subscription is being canceled. See {@link SubscriptionChangeInput.purchase}. */
635
+ purchase: PaymentsPurchase;
636
+ /**
637
+ * When it takes effect, in the customer's terms — `at_period_end` under the settled policy.
638
+ *
639
+ * The rail translates into the store's spelling; Paddle's own `next_billing_period` does not parse here, so a
640
+ * rail that stopped translating fails loudly rather than sending a string Paddle happens to accept. See
641
+ * `data/subscription.ts` for why the customer's word is the one modeled.
642
+ */
643
+ timing: SubscriptionCancelTiming;
644
+ }
645
+ /**
646
+ * A rail whose subscriptions can be *changed* from the server: read, quoted, moved, ended, and un-ended.
647
+ *
648
+ * Separate from {@link CheckoutRail} because selling and managing are separate abilities — and separate from
649
+ * the shared contract for the reason the module doc gives: an Apple or Google subscription is changed inside
650
+ * the store's own UI, on the device, and no server call exists to do it.
651
+ *
652
+ * ## Five methods, and the guard demands all five
653
+ *
654
+ * {@link isSubscriptionRail} ANDs every one of them. That is the rule {@link isCheckoutRail} sets and
655
+ * {@link isDiscountRail} broke: it probed a single method of two and narrowed a half-implemented rail into a
656
+ * type that promised the other, which is a `TypeError` inside a handler rather than a refusal at its edge.
657
+ * That guard was fixed with this interface's arrival, and the shape is named here so nothing is written to
658
+ * match it again. The floor it sets is a rule about what may ship together:
659
+ *
660
+ * - **No destructive verb without the read that makes it legible.** A rail that could cancel and not report
661
+ * the cancellation ships the half that creates the support ticket: Paddle leaves `status` at `active` and
662
+ * blanks `next_billed_at` when a cancellation is scheduled (recorded 2026-08-28, #465), so a customer who
663
+ * canceled is told they will be billed again by every screen that reads the status.
664
+ * - **No change without the quote that makes it consented to.** A confirmation screen with no figure on it is
665
+ * a customer agreeing to an amount they were never shown, and the amount is real: the recorded upgrade
666
+ * charges 6582 immediately.
667
+ *
668
+ * ## What is deliberately absent from every method here
669
+ *
670
+ * **A proration mode, and any other billing enum.** The rail picks the mode from the *direction* of the
671
+ * change — an upgrade prorates immediately and charges now, a downgrade prorates into the next billing period
672
+ * — and `on_payment_failure` is always `prevent_change`. Neither is a parameter, because a parameter is a
673
+ * thing a client eventually sets, and the value a client would eventually set is Paddle's `do_not_bill`: a
674
+ * free upgrade. It is unreachable because there is nowhere to write it.
675
+ *
676
+ * ## The no-op is a success, not a refusal
677
+ *
678
+ * A change to the plan already held, and a cancellation of a subscription that is already scheduled to
679
+ * cancel, both answer the current standing **without calling the provider at all**. That is the retry answer:
680
+ * these verbs sit behind a network, callers retry, and a second delivery of the same intent must not become a
681
+ * second proration. A 409 for the state the caller asked for is also simply wrong — the subscription is how
682
+ * they wanted it.
683
+ */
684
+ export interface SubscriptionRail {
685
+ /**
686
+ * Where this subscription stands now — status, dates, and whatever is scheduled to happen to it — or
687
+ * `undefined` when the store has nothing to say about this purchase.
688
+ *
689
+ * `undefined` for {@link PaymentsRailProvider.refresh}'s reason and with its meaning: the rail cannot
690
+ * address this purchase, or the store no longer knows it. A store that cannot be *reached* throws
691
+ * `payments/provider_unavailable` instead, so a screen distinguishes "there is nothing to show" from "we
692
+ * could not look".
693
+ *
694
+ * Read live, never from a projected row. The one fact this exists to report — a scheduled cancellation —
695
+ * is precisely the one a purchase row does not carry, and a webhook announcing it can be dropped.
696
+ */
697
+ readStanding(purchase: PaymentsPurchase, context: RailRequestContext): Promise<SubscriptionStanding | undefined>;
698
+ /**
699
+ * What moving to this price would cost, as the provider previews it — the figures a customer confirms.
700
+ *
701
+ * Every amount comes from the store and none is derived here. See `data/subscription.ts` for what the
702
+ * recordings established about reading them, and in particular for why the answer has three parts.
703
+ *
704
+ * **A read, so the no-op rule does not apply to it.** A preview takes and gives nothing, a second one is
705
+ * free, and asking the provider what the plan already held would cost is a question with an honest answer.
706
+ * The no-op exists to stop a retried *write* from prorating twice; borrowing it here would mean inventing a
707
+ * recurring figure to fill the quote with, which is the one thing this package will not do.
708
+ *
709
+ * Throws rather than answering `undefined`. A quote that could be absent is a confirm button rendered
710
+ * beside nothing, and `payments/provider_unavailable` is what tells a screen to say so.
711
+ */
712
+ previewChange(input: SubscriptionChangeInput, context: RailRequestContext): Promise<SubscriptionChangeQuote>;
713
+ /**
714
+ * Move the subscription to a different plan, and answer where it now stands.
715
+ *
716
+ * **The rail chooses the proration mode from the direction of the change** — up charges immediately, down
717
+ * defers the credit to the next billing period — and nothing the caller sends influences it.
718
+ *
719
+ * Answers the resulting {@link SubscriptionStanding} rather than nothing, so the screen that just wrote can
720
+ * render what it wrote from the provider's own answer instead of predicting it. A prediction is how a
721
+ * customer sees a plan they are not on.
722
+ *
723
+ * A change to the plan already held is the no-op: the current standing, and no provider call. Anything the
724
+ * store refuses — a subscription that is paused, canceled, or past due — throws
725
+ * `payments/subscription_change_refused` (409) with the store's own reason in `detail`.
726
+ */
727
+ changePlan(input: SubscriptionChangeInput, context: RailRequestContext): Promise<SubscriptionStanding>;
728
+ /**
729
+ * Stop the subscription renewing, and answer where it now stands.
730
+ *
731
+ * `at_period_end` is the settled policy and the tier holds until the paid period runs out; `now` exists
732
+ * because support occasionally has to end one today, and because a policy with no legitimate exit gets
733
+ * departed from by a direct provider call nothing audits.
734
+ *
735
+ * A cancellation on a subscription already scheduled to cancel is the no-op: the current standing, and no
736
+ * provider call. A subscription the store will not cancel throws `payments/subscription_change_refused`.
737
+ */
738
+ cancelSubscription(input: SubscriptionCancelInput, context: RailRequestContext): Promise<SubscriptionStanding>;
739
+ /**
740
+ * Withdraw a scheduled cancellation, so the subscription renews after all.
741
+ *
742
+ * **It withdraws a cancellation, and only a cancellation.** Paddle offers no verb for that: the update
743
+ * clears `scheduled_change` *wholesale*, by setting it to null, and the field also holds a scheduled pause
744
+ * and a scheduled resume. So a rail that simply sent the clear would silently un-pause a paused subscription
745
+ * — the customer's account restarts billing, on a request that said nothing about pausing. The rail must
746
+ * **re-read the subscription first and refuse unless the pending action is `cancel`**, with
747
+ * `payments/subscription_change_refused` (409) naming what was actually scheduled. The check cannot move to
748
+ * the route: the route holds a projected row, and the pending action lives only at the store.
749
+ *
750
+ * A subscription with nothing scheduled is the no-op rather than a refusal: it already renews, which is what
751
+ * the caller asked for, and a retry after a successful withdrawal is exactly that request arriving twice.
752
+ *
753
+ * Its own method rather than `changePlan` to the same price, because the two are separate acts by possibly
754
+ * separate actors and the audit trail records them separately — a withdrawal folded into a plan change
755
+ * leaves a trail that asserts a cancellation and holds nothing saying it was taken back.
756
+ */
757
+ keepSubscription(purchase: PaymentsPurchase, context: RailRequestContext): Promise<SubscriptionStanding>;
758
+ }
759
+ /**
760
+ * Whether a rail can manage a subscription from the server. Structural, like the others — and **it ANDs all
761
+ * five methods**, which the others do not all do.
762
+ *
763
+ * Every guard in this file ANDs its whole interface now, which was not true when this one was written — see
764
+ * {@link isDiscountRail} for the shape and what it cost. A guard that probes one method narrows a
765
+ * partially-implemented rail into a type promising the rest, and the first thing anybody learns about the gap
766
+ * is a `TypeError` thrown mid-cancellation, on a route that has already written an audit row. Here a rail
767
+ * missing any one verb is simply not a subscription rail, and the route answers `rail_not_configured` — which
768
+ * is true, and which is a refusal rather than a half-applied change.
769
+ */
770
+ export declare function isSubscriptionRail(provider: PaymentsRailProvider): provider is PaymentsRailProvider & SubscriptionRail;
771
+ /**
772
+ * Which payments are being refunded, and why — one set, no amount, and no identifier a caller could have
773
+ * written.
774
+ *
775
+ * **There is no transaction id here, and that absence is the security boundary**, exactly as
776
+ * {@link SubscriptionChangeInput} states it for a subscription. The payments arrive as
777
+ * {@link PaymentsPurchase} rows — decoded rows only this deployment's own database produces, each already
778
+ * carrying the subject that owns it — because a `txn_…` a caller supplies is a `txn_…` they can point at a
779
+ * stranger's money. This capability holds no ownership graph to check such a claim against, so the refusal
780
+ * has to be structural: the route resolves the rows from the authenticated caller's own purchases and there
781
+ * is nowhere in this shape to write anything else.
782
+ *
783
+ * **And there is no amount.** Every refund raised through this seam is for a transaction's whole total. A
784
+ * partial one is a different feature — it needs the store's own line-item ids, which nothing here holds —
785
+ * and an amount on a bearer route is a self-service withdrawal.
786
+ */
787
+ export interface RefundRequestInput {
788
+ /**
789
+ * The payments to refund — the caller's own purchase rows, one adjustment each.
790
+ *
791
+ * A set rather than one, because refunds attach to transactions and a subscription is a family of them:
792
+ * a customer who upgraded mid-period has paid twice and is owed both. The rail raises one refund per row
793
+ * and reports one outcome per row.
794
+ *
795
+ * **Order is the caller's and the report keeps it**, so a partial report is reproducible rather than
796
+ * whatever the store answered first.
797
+ */
798
+ purchases: readonly PaymentsPurchase[];
799
+ /**
800
+ * Why, in the operator's words — composed by the route, and **never read from a request body.**
801
+ *
802
+ * Every store requires one and shows it to a human in the merchant's own console. That is the argument
803
+ * for not taking it from the caller: a bearer request writing free text into an adopter's back office is
804
+ * a stranger writing into somebody's operational record, and there is nothing a customer could say there
805
+ * that the audit row and the store's own history do not already hold. An adopter who wants the
806
+ * customer's own words collects them on their own screen, where they belong to the adopter.
807
+ */
808
+ reason: string;
809
+ }
810
+ /**
811
+ * A rail that can ask its store to give a customer's money back.
812
+ *
813
+ * ## Its own interface, and not a sixth method on {@link SubscriptionRail}
814
+ *
815
+ * **The two abilities are independent in both directions, which is the whole argument.** Google Play has a
816
+ * server-side refund call and no server-side plan change — a subscription's plan is changed inside the
817
+ * store, on the device — so that rail could implement this and never implement {@link SubscriptionRail}.
818
+ * Apple is the other corner: refunds are Apple's own decision and the only server endpoint is a *lookup*,
819
+ * so a rail may be able to manage a subscription and have nothing to put here. An interface that demanded
820
+ * both would be one neither of them can satisfy.
821
+ *
822
+ * **And widening a guard that ANDs its methods is retroactive.** {@link isSubscriptionRail} requires all
823
+ * five verbs; a sixth would silently de-narrow every rail that already satisfies the five, and the first
824
+ * anybody would hear of it is `rail_not_configured` on a cancellation, from a release that changed nothing
825
+ * about canceling. A new interface costs one guard and breaks nothing that exists.
826
+ *
827
+ * **The floors differ too.** `SubscriptionRail`'s floor is *no destructive verb without the read that makes
828
+ * it legible* — the read being a standing. A refund's legibility read is a different one: the transactions
829
+ * and whatever adjustments already stand on them. Folding refunds in would make the ability to change a
830
+ * plan carry the power to move money back, which is a much larger power granted for a much smaller job.
831
+ *
832
+ * ## What a rail implementing this must guarantee
833
+ *
834
+ * - **It never claims money moved.** The answer is {@link RefundRequest}, whose every outcome is a request
835
+ * and whose statuses say so. Most live refunds sit at the store awaiting a human.
836
+ * - **It revokes nothing.** No entitlement, no purchase row, no projection. An approved refund arrives as a
837
+ * webhook and the projection acts on it — revoking on the *request* takes access from a customer whose
838
+ * refund the store then rejects, leaving them with neither the money nor the product.
839
+ * - **It refuses before it writes, and reports after.** Everything knowable in advance refuses the whole
840
+ * request with `payments/subscription_change_refused` and sends nothing; once one adjustment exists,
841
+ * every remaining failure is an outcome in the report. {@link RefundRequest} holds the long form.
842
+ * - **It bounds the set.** A set it cannot issue inside one request is refused before the first write, not
843
+ * discovered half way through.
844
+ *
845
+ * ## What is deliberately absent
846
+ *
847
+ * **An amount, a currency, a transaction id, and a window.** The first three are {@link RefundRequestInput}'s
848
+ * argument. The window is the *adopter's*: how many days a customer has to ask for their money back is a
849
+ * commercial policy with a company behind it, and a kit that hard-coded fourteen days would be wrong for the
850
+ * second adopter. The kit makes the refund possible; the adopter's screen decides which button exists.
851
+ */
852
+ export interface RefundRail {
853
+ /**
854
+ * Ask the store to refund these payments in full, and report what became of each.
855
+ *
856
+ * Throws `payments/subscription_change_refused` (409) when the request is refused before anything is
857
+ * sent, and `payments/provider_unavailable` (503) when the store could not be reached or answered in a
858
+ * shape this build cannot read — both only while nothing has been raised. After the first adjustment
859
+ * exists it answers, whatever else happened.
860
+ */
861
+ requestRefunds(input: RefundRequestInput, context: RailRequestContext): Promise<RefundRequest>;
862
+ }
863
+ /**
864
+ * Whether a rail can refund at its store. Structural, like the others.
865
+ *
866
+ * One method, so probing it *is* ANDing all of them — {@link isSubscriptionRail}'s rule, satisfied by
867
+ * arithmetic rather than by care. Stated because that stops being true the moment a second method is added
868
+ * here, and a guard left probing one of two is what {@link isDiscountRail} did until #465.
869
+ */
870
+ export declare function isRefundRail(provider: PaymentsRailProvider): provider is PaymentsRailProvider & RefundRail;
871
+ //# sourceMappingURL=contract.d.ts.map