@fantastic.dev/better-stripe 0.28.6 → 0.30.0

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 (222) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/MIGRATION.md +14 -0
  3. package/README.md +7 -1
  4. package/dist/client/connect/payoutActivationProof.d.ts.map +1 -1
  5. package/dist/client/connect/payoutActivationProof.js +88 -42
  6. package/dist/client/connect/payoutActivationProof.js.map +1 -1
  7. package/dist/client/connect/payoutAdoption.d.ts +3 -0
  8. package/dist/client/connect/payoutAdoption.d.ts.map +1 -1
  9. package/dist/client/connect/payoutAdoption.js +218 -183
  10. package/dist/client/connect/payoutAdoption.js.map +1 -1
  11. package/dist/client/connect/payoutAdoptionCollection.d.ts +21 -0
  12. package/dist/client/connect/payoutAdoptionCollection.d.ts.map +1 -0
  13. package/dist/client/connect/payoutAdoptionCollection.js +44 -0
  14. package/dist/client/connect/payoutAdoptionCollection.js.map +1 -0
  15. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +54 -14
  16. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  17. package/dist/client/connect/payoutCollectedInput.d.ts +110 -0
  18. package/dist/client/connect/payoutCollectedInput.d.ts.map +1 -0
  19. package/dist/client/connect/payoutCollectedInput.js +70 -0
  20. package/dist/client/connect/payoutCollectedInput.js.map +1 -0
  21. package/dist/client/connect/payoutExecution.d.ts +1 -0
  22. package/dist/client/connect/payoutExecution.d.ts.map +1 -1
  23. package/dist/client/connect/payoutExecution.js +94 -67
  24. package/dist/client/connect/payoutExecution.js.map +1 -1
  25. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +29 -7
  26. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  27. package/dist/client/connect/payoutExecutionTestHelpers.js +9 -6
  28. package/dist/client/connect/payoutExecutionTestHelpers.js.map +1 -1
  29. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +3745 -0
  30. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -0
  31. package/dist/client/connect/payoutLargeAdoptionTestHelpers.js +55 -0
  32. package/dist/client/connect/payoutLargeAdoptionTestHelpers.js.map +1 -0
  33. package/dist/client/connect/payoutOutcomeBatches.d.ts +5 -0
  34. package/dist/client/connect/payoutOutcomeBatches.d.ts.map +1 -0
  35. package/dist/client/connect/payoutOutcomeBatches.js +21 -0
  36. package/dist/client/connect/payoutOutcomeBatches.js.map +1 -0
  37. package/dist/client/connect/payoutPolicyState.d.ts +14 -0
  38. package/dist/client/connect/payoutPolicyState.d.ts.map +1 -0
  39. package/dist/client/connect/payoutPolicyState.js +19 -0
  40. package/dist/client/connect/payoutPolicyState.js.map +1 -0
  41. package/dist/client/connect/payoutPreview.d.ts +1 -0
  42. package/dist/client/connect/payoutPreview.d.ts.map +1 -1
  43. package/dist/client/connect/payoutPreview.js +31 -19
  44. package/dist/client/connect/payoutPreview.js.map +1 -1
  45. package/dist/client/connect/payoutQualification.d.ts +7 -1
  46. package/dist/client/connect/payoutQualification.d.ts.map +1 -1
  47. package/dist/client/connect/payoutQualification.js +34 -19
  48. package/dist/client/connect/payoutQualification.js.map +1 -1
  49. package/dist/client/connect/payoutReconciliation.d.ts +11 -6
  50. package/dist/client/connect/payoutReconciliation.d.ts.map +1 -1
  51. package/dist/client/connect/payoutReconciliation.js +62 -16
  52. package/dist/client/connect/payoutReconciliation.js.map +1 -1
  53. package/dist/client/connect/payoutResumableProof.d.ts +17 -0
  54. package/dist/client/connect/payoutResumableProof.d.ts.map +1 -0
  55. package/dist/client/connect/payoutResumableProof.js +25 -0
  56. package/dist/client/connect/payoutResumableProof.js.map +1 -0
  57. package/dist/client/connect/payoutSyncTestHelpers.d.ts +27 -7
  58. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  59. package/dist/client/connect/payoutWorker.d.ts.map +1 -1
  60. package/dist/client/connect/payoutWorker.js +4 -1
  61. package/dist/client/connect/payoutWorker.js.map +1 -1
  62. package/dist/client/connect/transferReceipt.d.ts +6 -2
  63. package/dist/client/connect/transferReceipt.d.ts.map +1 -1
  64. package/dist/client/connect/transferReceipt.js +3 -3
  65. package/dist/client/connect/transferReceipt.js.map +1 -1
  66. package/dist/client/costRecovery.d.ts +5 -0
  67. package/dist/client/costRecovery.d.ts.map +1 -1
  68. package/dist/client/costRecovery.js +5 -0
  69. package/dist/client/costRecovery.js.map +1 -1
  70. package/dist/client/payoutPolicy.d.ts +4 -0
  71. package/dist/client/payoutPolicy.d.ts.map +1 -1
  72. package/dist/client/payoutPolicy.js +24 -14
  73. package/dist/client/payoutPolicy.js.map +1 -1
  74. package/dist/component/_generated/component.d.ts +247 -0
  75. package/dist/component/_generated/component.d.ts.map +1 -1
  76. package/dist/component/costRecovery/mutations.js +1 -1
  77. package/dist/component/costRecovery/queries.d.ts +9 -0
  78. package/dist/component/costRecovery/queries.d.ts.map +1 -1
  79. package/dist/component/costRecovery/queries.js +20 -0
  80. package/dist/component/costRecovery/queries.js.map +1 -1
  81. package/dist/component/earnings/triggers.d.ts +28 -10
  82. package/dist/component/earnings/triggers.d.ts.map +1 -1
  83. package/dist/component/payoutPolicy/adoption.d.ts.map +1 -1
  84. package/dist/component/payoutPolicy/adoption.js +12 -7
  85. package/dist/component/payoutPolicy/adoption.js.map +1 -1
  86. package/dist/component/payoutPolicy/mutations.d.ts +12 -0
  87. package/dist/component/payoutPolicy/mutations.d.ts.map +1 -1
  88. package/dist/component/payoutPolicy/queries.d.ts +2 -0
  89. package/dist/component/payoutPolicy/queries.d.ts.map +1 -1
  90. package/dist/component/payoutPolicy/schema.d.ts +31 -7
  91. package/dist/component/payoutPolicy/schema.d.ts.map +1 -1
  92. package/dist/component/payoutPolicy/schema.js +2 -0
  93. package/dist/component/payoutPolicy/schema.js.map +1 -1
  94. package/dist/component/payoutRelease/adoption.d.ts +9 -1
  95. package/dist/component/payoutRelease/adoption.d.ts.map +1 -1
  96. package/dist/component/payoutRelease/adoption.js +33 -16
  97. package/dist/component/payoutRelease/adoption.js.map +1 -1
  98. package/dist/component/payoutRelease/fees.d.ts.map +1 -1
  99. package/dist/component/payoutRelease/fees.js +7 -0
  100. package/dist/component/payoutRelease/fees.js.map +1 -1
  101. package/dist/component/payoutRelease/helpers.d.ts +4 -1
  102. package/dist/component/payoutRelease/helpers.d.ts.map +1 -1
  103. package/dist/component/payoutRelease/helpers.js +17 -10
  104. package/dist/component/payoutRelease/helpers.js.map +1 -1
  105. package/dist/component/payoutRelease/mutations.d.ts +79 -0
  106. package/dist/component/payoutRelease/mutations.d.ts.map +1 -1
  107. package/dist/component/payoutRelease/mutations.js +38 -81
  108. package/dist/component/payoutRelease/mutations.js.map +1 -1
  109. package/dist/component/payoutRelease/outcome.d.ts +69 -0
  110. package/dist/component/payoutRelease/outcome.d.ts.map +1 -0
  111. package/dist/component/payoutRelease/outcome.js +94 -0
  112. package/dist/component/payoutRelease/outcome.js.map +1 -0
  113. package/dist/component/payoutRelease/planning.d.ts +4 -0
  114. package/dist/component/payoutRelease/planning.d.ts.map +1 -1
  115. package/dist/component/payoutRelease/planning.js +8 -3
  116. package/dist/component/payoutRelease/planning.js.map +1 -1
  117. package/dist/component/payoutRelease/preview.d.ts +2 -0
  118. package/dist/component/payoutRelease/preview.d.ts.map +1 -1
  119. package/dist/component/payoutRelease/preview.js +2 -0
  120. package/dist/component/payoutRelease/preview.js.map +1 -1
  121. package/dist/component/payoutRelease/queries.d.ts +13 -2
  122. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  123. package/dist/component/payoutRelease/queries.js +2 -0
  124. package/dist/component/payoutRelease/queries.js.map +1 -1
  125. package/dist/component/payoutRelease/schema.d.ts +17 -2
  126. package/dist/component/payoutRelease/schema.d.ts.map +1 -1
  127. package/dist/component/payoutRelease/schema.js +3 -0
  128. package/dist/component/payoutRelease/schema.js.map +1 -1
  129. package/dist/component/payoutSnapshots/adoption.d.ts +88 -0
  130. package/dist/component/payoutSnapshots/adoption.d.ts.map +1 -0
  131. package/dist/component/payoutSnapshots/adoption.js +49 -0
  132. package/dist/component/payoutSnapshots/adoption.js.map +1 -0
  133. package/dist/component/payoutSnapshots/financial.d.ts +47 -0
  134. package/dist/component/payoutSnapshots/financial.d.ts.map +1 -0
  135. package/dist/component/payoutSnapshots/financial.js +103 -0
  136. package/dist/component/payoutSnapshots/financial.js.map +1 -0
  137. package/dist/component/payoutSnapshots/liabilities.d.ts +7 -0
  138. package/dist/component/payoutSnapshots/liabilities.d.ts.map +1 -0
  139. package/dist/component/payoutSnapshots/liabilities.js +18 -0
  140. package/dist/component/payoutSnapshots/liabilities.js.map +1 -0
  141. package/dist/component/payoutSnapshots/localState.d.ts +22 -16
  142. package/dist/component/payoutSnapshots/localState.d.ts.map +1 -1
  143. package/dist/component/payoutSnapshots/localState.js +19 -7
  144. package/dist/component/payoutSnapshots/localState.js.map +1 -1
  145. package/dist/component/payoutSnapshots/mutations.d.ts +6 -0
  146. package/dist/component/payoutSnapshots/mutations.d.ts.map +1 -1
  147. package/dist/component/payoutSnapshots/mutations.js +3 -1
  148. package/dist/component/payoutSnapshots/mutations.js.map +1 -1
  149. package/dist/component/payoutSnapshots/queries.d.ts +133 -0
  150. package/dist/component/payoutSnapshots/queries.d.ts.map +1 -0
  151. package/dist/component/payoutSnapshots/queries.js +86 -0
  152. package/dist/component/payoutSnapshots/queries.js.map +1 -0
  153. package/dist/component/payoutSnapshots/revisions.d.ts.map +1 -1
  154. package/dist/component/payoutSnapshots/revisions.js +19 -0
  155. package/dist/component/payoutSnapshots/revisions.js.map +1 -1
  156. package/dist/component/payoutSnapshots/schema.d.ts +20 -6
  157. package/dist/component/payoutSnapshots/schema.d.ts.map +1 -1
  158. package/dist/component/payoutSnapshots/schema.js +5 -1
  159. package/dist/component/payoutSnapshots/schema.js.map +1 -1
  160. package/dist/component/payoutWorker/mutations.d.ts.map +1 -1
  161. package/dist/component/payoutWorker/mutations.js +3 -1
  162. package/dist/component/payoutWorker/mutations.js.map +1 -1
  163. package/dist/component/schema.d.ts +27 -7
  164. package/dist/react/workflows/payout-attempt-state.d.ts.map +1 -1
  165. package/dist/react/workflows/payout-attempt-state.js +3 -0
  166. package/dist/react/workflows/payout-attempt-state.js.map +1 -1
  167. package/dist/react/workflows/payout-progress-state.d.ts.map +1 -1
  168. package/dist/react/workflows/payout-progress-state.js +3 -0
  169. package/dist/react/workflows/payout-progress-state.js.map +1 -1
  170. package/docs/settlement.md +136 -24
  171. package/package.json +1 -1
  172. package/src/client/connect/payoutActivationProof.ts +123 -53
  173. package/src/client/connect/payoutAdoption.ts +299 -215
  174. package/src/client/connect/payoutAdoptionCollection.ts +78 -0
  175. package/src/client/connect/payoutAdoptionConcurrency.test.ts +266 -0
  176. package/src/client/connect/payoutCacheIdentity.test.ts +93 -0
  177. package/src/client/connect/payoutCollectedInput.ts +120 -0
  178. package/src/client/connect/payoutExecution.ts +116 -84
  179. package/src/client/connect/payoutExecutionTestHelpers.ts +19 -6
  180. package/src/client/connect/payoutLargeAdoption.test.ts +541 -0
  181. package/src/client/connect/payoutLargeAdoptionTestHelpers.ts +74 -0
  182. package/src/client/connect/payoutLargeHistory.test.ts +222 -0
  183. package/src/client/connect/payoutLiabilityVersion.test.ts +221 -0
  184. package/src/client/connect/payoutOutcomeBatches.test.ts +40 -0
  185. package/src/client/connect/payoutOutcomeBatches.ts +24 -0
  186. package/src/client/connect/payoutPolicyState.ts +36 -0
  187. package/src/client/connect/payoutPreview.ts +42 -24
  188. package/src/client/connect/payoutQualification.ts +68 -21
  189. package/src/client/connect/payoutReconciliation.ts +86 -7
  190. package/src/client/connect/payoutResumableProof.ts +41 -0
  191. package/src/client/connect/payoutWorker.ts +4 -1
  192. package/src/client/connect/transferReceipt.ts +3 -2
  193. package/src/client/connect/transferReceiptBaseline.test.ts +55 -0
  194. package/src/client/costRecovery.ts +8 -0
  195. package/src/client/payoutPolicy.ts +37 -23
  196. package/src/component/_generated/api.ts +10 -0
  197. package/src/component/_generated/component.ts +288 -0
  198. package/src/component/costRecovery/mutations.ts +1 -1
  199. package/src/component/costRecovery/queries.ts +21 -0
  200. package/src/component/payout-snapshots.test.ts +45 -1
  201. package/src/component/payoutPolicy/adoption.ts +20 -7
  202. package/src/component/payoutPolicy/schema.ts +2 -0
  203. package/src/component/payoutRelease/adoption.ts +57 -27
  204. package/src/component/payoutRelease/fees.ts +9 -0
  205. package/src/component/payoutRelease/helpers.ts +19 -11
  206. package/src/component/payoutRelease/mutations.ts +43 -96
  207. package/src/component/payoutRelease/outcome.ts +119 -0
  208. package/src/component/payoutRelease/planning.ts +11 -2
  209. package/src/component/payoutRelease/preview.ts +2 -0
  210. package/src/component/payoutRelease/queries.ts +2 -0
  211. package/src/component/payoutRelease/schema.ts +3 -0
  212. package/src/component/payoutSnapshots/adoption.ts +73 -0
  213. package/src/component/payoutSnapshots/financial.ts +134 -0
  214. package/src/component/payoutSnapshots/liabilities.ts +25 -0
  215. package/src/component/payoutSnapshots/localState.ts +24 -6
  216. package/src/component/payoutSnapshots/mutations.ts +10 -1
  217. package/src/component/payoutSnapshots/queries.ts +104 -0
  218. package/src/component/payoutSnapshots/revisions.ts +26 -0
  219. package/src/component/payoutSnapshots/schema.ts +5 -0
  220. package/src/component/payoutWorker/mutations.ts +3 -1
  221. package/src/react/workflows/payout-attempt-state.ts +6 -0
  222. package/src/react/workflows/payout-progress-state.ts +6 -0
@@ -303,11 +303,14 @@ release an unaccepted claim within a conservative 23-hour window. It requires
303
303
  its own unique Stripe request receipt; ambiguous errors and older attempts stay
304
304
  held. This window stays below Stripe's [24-hour v1 idempotency retention minimum](https://docs.stripe.com/api/idempotent_requests).
305
305
 
306
- Current atomic snapshots support 100 account transfers, 100 historical claims and
307
- 1,000 receipt IDs per source. Larger/incomplete histories hold the whole operation
308
- without partial totals. Resumable larger-account collection, other provider-debit
309
- allocation and recurring/UI integration remain required. The package does not
310
- claim that component tests alone demonstrate a Stripe bank payout.
306
+ The legacy direct snapshot supports 100 account transfers and historical claims.
307
+ Public release, preview and historical-adoption flows switch to complete paginated
308
+ collections beyond that boundary. The per-source observation guard still permits
309
+ at most 1,000 receipt IDs; incomplete provider history never supplies partial
310
+ financial totals. Native platform limits still apply to the atomic boundary.
311
+ Hosts install the scheduled runner and authenticated UI adapters. Unknown provider
312
+ debits need explicit accounting before qualification. Verify actual Stripe payout
313
+ receipts rather than treating component-only tests as proof of bank payment.
311
314
 
312
315
  ## Verified recipient funding receipts
313
316
 
@@ -479,13 +482,13 @@ is canceled on replay, and a new scheduled operation can collect fresh receipts.
479
482
  Below-threshold money remains owed. The numeric provider floor remains `null`
480
483
  unless a supported provider contract exposes it.
481
484
 
482
- Current atomic collection accepts up to 100 account transfers and 100 historical
483
- claims. Larger accounts return `held/snapshot_limit`, without paying a partial
484
- page. Provider history uses a 1–100 page budget, default 10; exhaustion stays held.
485
- Use the historical import and funded activation flow below for known old funds.
486
- Resumable larger-account collection, independent provider-debit allocation,
487
- recurring example jobs and React controls remain integration work. Unknown funds
488
- and unsupported accounts keep explicit migration holds.
485
+ The direct component snapshot remains bounded at 100 source/claim rows. The SDK
486
+ switches to a complete paginated manifest above that boundary and binds its
487
+ verified membership to the financial claim. It never pays from a partial page.
488
+ Provider history uses a 1–100 page budget, default 10; exhaustion stays held.
489
+ Use the separate historical import and funded activation contract below for known
490
+ old funds; a local manifest is not historical-adoption proof. Unknown funds and
491
+ unsupported accounts keep explicit migration holds.
489
492
 
490
493
  Sources: [payout creation and source balance selection](https://docs.stripe.com/api/payouts/create),
491
494
  [complete balance history and automatic-only payout filtering](https://docs.stripe.com/api/balance_transactions/list).
@@ -539,13 +542,63 @@ not-yet-mature bank returns cannot fund an earlier payout. Terminal paid and
539
542
  verified returned payouts are supported; pending or ambiguous outcomes stay
540
543
  held. Unknown credits, debits, fees or unallocated payouts require further
541
544
  reconciliation. All unknown historical payouts import as one component
542
- transaction, including fees and source allocations. Changed mappings and stale
545
+ transaction, including fees and source allocations. Each new historical claim
546
+ retains immutable observations for every allocated source. Unrelated source
547
+ proofs are still checked in the complete batch, but are not copied onto every
548
+ claim. Existing claim evidence is not rewritten. Changed mappings and stale
543
549
  competing snapshots reject without mixing their writes. Replays never create a
544
550
  payout. Historical paid principal remains paid after later refunds, so debt
545
551
  reduces later qualifying funds rather than making the old commission payable
546
552
  again. An adopted payout can reconcile a subsequent bank failure without
547
553
  requiring a package marker that was absent from its original Stripe object.
548
554
 
555
+ Historical receipt reads are bounded to five concurrent requests. Known outcomes
556
+ reconcile in atomic batches of at most 25, splitting repeated allocation work
557
+ above 1,000 allocations while retaining a large individual outcome as its own
558
+ transaction. Native per-transaction limits still apply. Batches use the same receipt, ownership, fee,
559
+ uniqueness and return validation as individual reconciliation. An invalid row
560
+ rolls back its entire batch; earlier verified batches remain safely retryable.
561
+ Disposable source caches retain optional primary document IDs to avoid repeated
562
+ indexed lookups. Older caches fall back to indexed reads, and every primary-ID
563
+ lookup still checks live identity and financial state. Already-read transfer
564
+ baselines never replace the final live ledger check.
565
+
566
+ Identical activation callers can complete while another caller is verifying a
567
+ proof or waiting to mark its attempt. These retry boundaries re-read the same
568
+ owned durable operation. Attempted, completed or canceled operations resume
569
+ through their canonical state; an unattempted proof failure still rejects.
570
+ A committed attempt is not marked again after its response is lost. Original
571
+ provider request identity and schedule-restoration records remain unchanged.
572
+
573
+ Public adoption and funded activation use complete cursor-paginated collections
574
+ when local sources, existing claims or proposed imports exceed the small direct
575
+ snapshot path. There is no lifetime 100-row cutoff in these public flows. The
576
+ collection checks complete membership, paid/reserved rollups, owner, policy and
577
+ financial revision again inside the atomic import or activation transaction.
578
+ Unlike a later release, adoption rejects deferred positive funding as well as
579
+ risk changes; collect a new current baseline before changing account controls.
580
+
581
+ `collection_pending` preserves bounded local work. Repeat the same authorized
582
+ account/currency/policy request with enough `maxPages` to complete the provider
583
+ history. The internal collection key also includes the policy operation, so a
584
+ new policy operation cannot reuse an obsolete baseline. Invalidated and consumed
585
+ read-only caches are discarded; financial claims and schedule restoration records
586
+ remain intact. No partial import or cache state authorizes a bank payout.
587
+
588
+ Source receipts run in groups of at most five. After reconciliation, a complete
589
+ matching currency history renews its observations. Funded activation verifies
590
+ every discovered currency, then rechecks the account-wide balance and history
591
+ head after collecting the local baseline. It renews the complete proof only if
592
+ that provider snapshot remained unchanged. These checks retain freshness limits
593
+ rather than accepting old observations because a scan took longer.
594
+
595
+ Native platform limits still apply to the atomic boundary, including document,
596
+ argument, return-value and transaction sizes, array lengths and execution time.
597
+ An oversized workload requires a separately designed import/migration; it must
598
+ not be split into unverified partial activation or silently truncated. See the
599
+ [Convex limits](https://docs.convex.dev/production/state/limits). Provider page
600
+ budgets and unsupported payout rails remain explicit holds.
601
+
549
602
  After successful import, explicitly request funded-account adoption during
550
603
  preparation, using the latest owned policy revision:
551
604
 
@@ -582,8 +635,8 @@ Preparation cannot restart an expired holding period, and later checks can only
582
635
  shorten the pending operation's deadline. `migration_required.adoptionReason`
583
636
  explains unknown history or an expired holding period. This flow does not enable
584
637
  Dashboard accounts with withdrawal bypasses, Global Payouts, unsupported source
585
- rails, unknown numeric provider floors or accounts beyond the current atomic
586
- snapshot bounds. Activation itself does not install a host cron or UI.
638
+ rails, unknown numeric provider floors or workloads beyond native atomic
639
+ platform limits. Activation itself does not install a host cron or UI.
587
640
 
588
641
  ## Automatic recipient worker
589
642
 
@@ -741,9 +794,10 @@ attempt. Bank arrival dates remain separate provider data from
741
794
  `getPayoutSnapshot`.
742
795
 
743
796
  Stripe-managed recipients keep Stripe's default automatic schedule. This preview
744
- requires a ready custom policy and preserves the current source/history limits,
745
- region restrictions and supported payout rail. It does not remove the need for
746
- provider-history continuation on larger accounts.
797
+ requires a ready custom policy, verified complete provider history, the supported
798
+ region/control capabilities and payout rail. The SDK automatically collects a
799
+ paginated local manifest when the small direct snapshot exceeds 100 rows; a
800
+ partial collection never supplies an eligibility amount.
747
801
 
748
802
  ## Resumable local collections
749
803
 
@@ -754,8 +808,8 @@ components. The public page shape remains `page`, `continueCursor` and `isDone`.
754
808
  Treat cursors as opaque and restart cached pages at a null cursor when upgrading
755
809
  these readers. Use the package's discard operation for an obsolete read-only
756
810
  collection; never erase financially bound or unresolved payout state to restart
757
- a scan. This change preserves the existing source/history limits and does not
758
- make larger provider-history qualification complete.
811
+ a scan. The automatic SDK qualification path uses these pages when a direct
812
+ snapshot exceeds 100 lifetime source or claim rows.
759
813
 
760
814
  An authorized host worker can collect the local recipient ledger in bounded
761
815
  steps, retaining its cursor and step number across restarts:
@@ -788,15 +842,31 @@ stop collection with an explicit reason.
788
842
 
789
843
  `local_ready` describes a read-only local manifest. Complete provider receipts,
790
844
  provider history and monetary claim binding are still required before a payout.
791
- These local APIs do not remove the current bounded release/adoption limits by
792
- themselves. Provider-history continuation and scalable claim execution remain
793
- under implementation.
845
+ The SDK verifies every source against Stripe, fetching at most five source
846
+ receipts concurrently, and checks the complete selected-currency provider history.
847
+ The monetary transaction then checks the collection's owner, policy, full source
848
+ membership, allocation rollups and current risk revision. A qualifying collection
849
+ is bound to the immutable payout claim, including that claim's own reservation
850
+ writes. The risk revision is checked again before the provider attempt. A later
851
+ reversal, fee or competing claim cannot silently change the request.
852
+
853
+ `collection_pending` retains the recurring worker operation and resumes its local
854
+ cursor on a subsequent scheduled check. `collection_invalidated` requires a new
855
+ assessment. Preview/qualification on a query-only context returns
856
+ `collection_requires_action` for larger histories; use an authorized server action.
857
+ A bank payout is not created by collecting or previewing. Complete provider history
858
+ still has the caller's `maxPages` budget, and claims must fit Convex's argument,
859
+ transaction and document limits. Budget errors never erase financial records or
860
+ qualify a partial manifest; use operator recovery for an unsupported workload.
794
861
 
795
862
  After a read-only collection is no longer needed, repeatedly call
796
863
  `discardSnapshot(ctx, { accountId, ownerKey, operationKey: collectionKey })` until
797
864
  it returns `null`. Cleanup removes only collection caches. Read-only collection
798
865
  leases last 24 hours. Financially bound collections reject read-only cleanup and
799
- expiry; payout claims and their source reservations keep their own lifecycle.
866
+ expiry. Once an attempt is durably marked or an unattempted claim is canceled,
867
+ its cache becomes discardable; the claim retains its own immutable observations
868
+ and reservations. An unknown provider outcome keeps those reservations, even
869
+ when the disposable cache has been removed.
800
870
 
801
871
  ### Development reset safeguards
802
872
 
@@ -825,3 +895,45 @@ entitlement. Refunds/reversals still reduce qualifying funds. Provider floors
825
895
  remain provider-enforced and numerically unknown when not exposed. Reassess fresh
826
896
  receipts and balances on the next scheduled attempt rather than manually
827
897
  recreating uncertain requests.
898
+
899
+ ### Versioned recovery liabilities
900
+
901
+ Resolve seller refund/dispute costs and their account version in one component query:
902
+
903
+ ```ts
904
+ const quote = await stripe.costRecovery.payoutQuote(ctx, {
905
+ accountId,
906
+ scopeKey: authorizedRecoveryScope,
907
+ currency,
908
+ });
909
+ await stripe.payoutPolicy.worker.run(ctx, {
910
+ accountId,
911
+ ownerKey,
912
+ currency,
913
+ ...quote,
914
+ });
915
+ ```
916
+
917
+ Use the same quote with `preview` or `release`. The amount is
918
+ `max(0, amountDue - collectedAmount)` for that authorized recovery scope;
919
+ invoice reservations remain owed until collection is verified. Provider-collected
920
+ costs are not deducted again. Keep the amount and `liabilityRevision` together,
921
+ for the same account, scope and currency. Use an authorized user-level scope
922
+ when costs span communities; the host remains responsible for including all
923
+ other authorized debts/reserves and for versioning state outside this component.
924
+ The package's revision does not version an external host database.
925
+
926
+ Recovery amount changes enter the payout risk journal. The financial boundary
927
+ rejects an old quote, and a bound claim checks the current risk revision again
928
+ before its attempt. Its own reservation writes are included in the binding.
929
+ A source/fee/recovery change requires a new assessment; unattempted reservations
930
+ are canceled exactly on replay. An attempted or unknown payout still reconciles
931
+ its immutable request. New claims retain the approved `independentLiabilities`
932
+ and `liabilityRevision` for audit.
933
+
934
+ Legacy unversioned calls remain valid for accounts without recovery balance
935
+ records. Once such records exist, obtain a quote; missing versions fail safely.
936
+ The example's worker and preview adapters do this automatically. Old unattempted
937
+ claims are canceled on replay, rather than retroactively supplied with a guessed
938
+ quote. Restart obsolete read-only collections after upgrading their fingerprint
939
+ format; never clear unresolved financial claims to bypass validation.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.28.6",
3
+ "version": "0.30.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -1,3 +1,12 @@
1
+ import {
2
+ collectLargePayoutInput,
3
+ discardQualificationInput,
4
+ type CollectionRef,
5
+ } from "./payoutCollectedInput.js";
6
+ import {
7
+ adoptionCollectionKey,
8
+ discardAdoptionProof,
9
+ } from "./payoutAdoptionCollection.js";
1
10
  import type Stripe from "stripe";
2
11
  import type { Infer } from "convex/values";
3
12
  import type { Component, RunCtx } from "../helpers.js";
@@ -44,58 +53,119 @@ export async function collectAdoptionProof(
44
53
  | { status: "verified"; proof: Infer<typeof adoptionProof> }
45
54
  | { status: "held"; reason: string }
46
55
  > {
47
- const request = { stripeAccount: scope.accountId };
48
- const initial = await stripe.balance.retrieve(undefined, request);
49
- const first = await stripe.balanceTransactions.list({ limit: 1 }, request);
50
- const queue = new Set([
51
- ...configuredCurrencies,
52
- ...initial.available.map((t) => t.currency),
53
- ...initial.pending.map((t) => t.currency),
54
- ...(first.data[0] ? [first.data[0].currency] : []),
55
- ]);
56
- const completed = new Set<string>();
57
- let observations: Infer<typeof adoptionProof>["observations"] = [],
58
- oldestHeldAt: number | undefined;
59
- for (const currency of queue) {
60
- if (completed.size >= 50)
61
- return { status: "held", reason: "currency_history_incomplete" };
62
- const result = await adoptRecipientPayouts(
63
- stripe,
64
- component,
65
- ctx,
66
- { ...scope, currency, expectedRevision, payouts: [] },
67
- true,
68
- );
69
- if (result.status !== "adopted") return result;
70
- completed.add(currency);
71
- for (const c of result.historyCurrencies) queue.add(c);
72
- observations = result.observations;
73
- if (result.oldestHeldAt !== undefined)
74
- oldestHeldAt = Math.min(oldestHeldAt ?? Infinity, result.oldestHeldAt);
56
+ let retained: CollectionRef | undefined;
57
+ let collection:
58
+ | {
59
+ snapshotId: Infer<typeof adoptionProof>["snapshotId"];
60
+ collectionKey: string;
61
+ }
62
+ | undefined;
63
+ let handedOff = false,
64
+ keepPending = false;
65
+ try {
66
+ const request = { stripeAccount: scope.accountId };
67
+ const initial = await stripe.balance.retrieve(undefined, request);
68
+ const first = await stripe.balanceTransactions.list({ limit: 1 }, request);
69
+ const queue = new Set([
70
+ ...configuredCurrencies,
71
+ ...initial.available.map((t) => t.currency),
72
+ ...initial.pending.map((t) => t.currency),
73
+ ...(first.data[0] ? [first.data[0].currency] : []),
74
+ ]);
75
+ const completed = new Set<string>();
76
+ let observations: Infer<typeof adoptionProof>["observations"] = [],
77
+ oldestHeldAt: number | undefined;
78
+ for (const currency of queue) {
79
+ if (completed.size >= 50)
80
+ return { status: "held", reason: "currency_history_incomplete" };
81
+ const result = await adoptRecipientPayouts(
82
+ stripe,
83
+ component,
84
+ ctx,
85
+ { ...scope, currency, expectedRevision, payouts: [] },
86
+ true,
87
+ );
88
+ if (result.status !== "adopted") return result;
89
+ if (result.collection) {
90
+ if (
91
+ retained &&
92
+ retained.operationKey !== result.collection.operationKey
93
+ )
94
+ await discardQualificationInput(component, ctx, retained);
95
+ retained = result.collection;
96
+ }
97
+ completed.add(currency);
98
+ for (const c of result.historyCurrencies) queue.add(c);
99
+ observations = result.observations;
100
+ if (result.oldestHeldAt !== undefined)
101
+ oldestHeldAt = Math.min(oldestHeldAt ?? Infinity, result.oldestHeldAt);
102
+ }
103
+ let snapshot = (await ctx.runQuery(
104
+ componentRef(component, "payoutRelease/queries/snapshot"),
105
+ { accountId: scope.accountId, ownerKey: scope.ownerKey },
106
+ )) as
107
+ | { status: "ready"; claims: Infer<typeof claimDoc>[] }
108
+ | { status: "held"; reason: string };
109
+ if (snapshot.status !== "ready" || retained) {
110
+ const policy = (await ctx.runQuery(
111
+ componentRef(component, "payoutPolicy/queries/get"),
112
+ { accountId: scope.accountId, ownerKey: scope.ownerKey },
113
+ )) as { operationKey: string };
114
+ const key =
115
+ retained?.operationKey ??
116
+ (await adoptionCollectionKey(scope, policy.operationKey, "activation"));
117
+ const large = await collectLargePayoutInput(
118
+ component,
119
+ ctx,
120
+ { ...scope, operationKey: key },
121
+ 10,
122
+ );
123
+ if (large.status !== "ready") {
124
+ keepPending = large.reason === "collection_pending";
125
+ if (large.reason !== "collection_pending" && large.collection)
126
+ await discardAdoptionProof(component, ctx, scope, {
127
+ snapshotId: large.collection.snapshotId,
128
+ collectionKey: key,
129
+ });
130
+ return { status: "held", reason: large.reason };
131
+ }
132
+ collection = {
133
+ snapshotId: large.collection.snapshotId,
134
+ collectionKey: key,
135
+ };
136
+ snapshot = large;
137
+ }
138
+ const balance = await stripe.balance.retrieve(undefined, request);
139
+ const latest = await stripe.balanceTransactions.list({ limit: 1 }, request);
140
+ if (
141
+ balanceIdentity(initial) !== balanceIdentity(balance) ||
142
+ transactionIdentity(first.data[0]) !== transactionIdentity(latest.data[0])
143
+ ) {
144
+ await discardAdoptionProof(component, ctx, scope, collection);
145
+ return { status: "held", reason: "provider_changed" };
146
+ }
147
+ handedOff = true;
148
+ return {
149
+ status: "verified",
150
+ proof: {
151
+ // All discovered currencies completed verification. The final provider
152
+ // head and balances still match the initial account snapshot after local collection.
153
+ observations: observations.map((o) => ({
154
+ ...o,
155
+ observedAt: Date.now(),
156
+ })),
157
+ ...collection,
158
+ claims: snapshot.claims.map((c) => ({
159
+ operationKey: c.operationKey,
160
+ fingerprint: payoutClaimFingerprint(c),
161
+ })),
162
+ ...(oldestHeldAt !== undefined ? { oldestHeldAt } : {}),
163
+ },
164
+ };
165
+ } finally {
166
+ if (!handedOff && !keepPending) {
167
+ await discardQualificationInput(component, ctx, retained);
168
+ await discardAdoptionProof(component, ctx, scope, collection);
169
+ }
75
170
  }
76
- const balance = await stripe.balance.retrieve(undefined, request);
77
- const latest = await stripe.balanceTransactions.list({ limit: 1 }, request);
78
- if (
79
- balanceIdentity(initial) !== balanceIdentity(balance) ||
80
- transactionIdentity(first.data[0]) !== transactionIdentity(latest.data[0])
81
- )
82
- return { status: "held", reason: "provider_changed" };
83
- const snapshot = (await ctx.runQuery(
84
- componentRef(component, "payoutRelease/queries/snapshot"),
85
- { accountId: scope.accountId, ownerKey: scope.ownerKey },
86
- )) as
87
- | { status: "ready"; claims: Infer<typeof claimDoc>[] }
88
- | { status: "held"; reason: string };
89
- if (snapshot.status !== "ready") return snapshot;
90
- return {
91
- status: "verified",
92
- proof: {
93
- observations,
94
- claims: snapshot.claims.map((c) => ({
95
- operationKey: c.operationKey,
96
- fingerprint: payoutClaimFingerprint(c),
97
- })),
98
- ...(oldestHeldAt !== undefined ? { oldestHeldAt } : {}),
99
- },
100
- };
101
171
  }