@fantastic.dev/better-stripe 0.37.1 → 0.39.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 (210) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/MIGRATION.md +9 -0
  3. package/README.md +25 -1
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +506 -2
  5. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +253 -1
  7. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +506 -2
  9. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts +253 -1
  11. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  12. package/dist/client/core/accountCapabilities.d.ts +20 -0
  13. package/dist/client/core/accountCapabilities.d.ts.map +1 -0
  14. package/dist/client/core/accountCapabilities.js +7 -0
  15. package/dist/client/core/accountCapabilities.js.map +1 -0
  16. package/dist/client/core/accountConfigurations.d.ts +46 -0
  17. package/dist/client/core/accountConfigurations.d.ts.map +1 -0
  18. package/dist/client/core/accountConfigurations.js +99 -0
  19. package/dist/client/core/accountConfigurations.js.map +1 -0
  20. package/dist/client/core/accountLinks.d.ts +29 -2
  21. package/dist/client/core/accountLinks.d.ts.map +1 -1
  22. package/dist/client/core/accountLinks.js +56 -4
  23. package/dist/client/core/accountLinks.js.map +1 -1
  24. package/dist/client/core/accounts.d.ts +2 -36
  25. package/dist/client/core/accounts.d.ts.map +1 -1
  26. package/dist/client/core/accounts.js +3 -73
  27. package/dist/client/core/accounts.js.map +1 -1
  28. package/dist/client/core/billingPortalClient.d.ts +14 -0
  29. package/dist/client/core/billingPortalClient.d.ts.map +1 -0
  30. package/dist/client/core/billingPortalClient.js +18 -0
  31. package/dist/client/core/billingPortalClient.js.map +1 -0
  32. package/dist/client/costRecovery-invoices.d.ts +4 -4
  33. package/dist/client/costRecovery.d.ts +19 -1
  34. package/dist/client/costRecovery.d.ts.map +1 -1
  35. package/dist/client/costRecovery.js +4 -0
  36. package/dist/client/costRecovery.js.map +1 -1
  37. package/dist/client/financialOutcomes/adapters.d.ts +18 -0
  38. package/dist/client/financialOutcomes/adapters.d.ts.map +1 -0
  39. package/dist/client/financialOutcomes/adapters.js +60 -0
  40. package/dist/client/financialOutcomes/adapters.js.map +1 -0
  41. package/dist/client/financialOutcomes/contracts.d.ts +42 -0
  42. package/dist/client/financialOutcomes/contracts.d.ts.map +1 -0
  43. package/dist/client/financialOutcomes/contracts.js +39 -0
  44. package/dist/client/financialOutcomes/contracts.js.map +1 -0
  45. package/dist/client/financialOutcomes/errors.d.ts +6 -0
  46. package/dist/client/financialOutcomes/errors.d.ts.map +1 -0
  47. package/dist/client/financialOutcomes/errors.js +22 -0
  48. package/dist/client/financialOutcomes/errors.js.map +1 -0
  49. package/dist/client/financialOutcomes/index.d.ts +6 -0
  50. package/dist/client/financialOutcomes/index.d.ts.map +1 -0
  51. package/dist/client/financialOutcomes/index.js +4 -0
  52. package/dist/client/financialOutcomes/index.js.map +1 -0
  53. package/dist/client/financialOutcomes/retry.d.ts +24 -0
  54. package/dist/client/financialOutcomes/retry.d.ts.map +1 -0
  55. package/dist/client/financialOutcomes/retry.js +31 -0
  56. package/dist/client/financialOutcomes/retry.js.map +1 -0
  57. package/dist/client/index.d.ts +21 -111
  58. package/dist/client/index.d.ts.map +1 -1
  59. package/dist/client/index.js +11 -85
  60. package/dist/client/index.js.map +1 -1
  61. package/dist/client/processingCostDeficit/index.d.ts +27 -0
  62. package/dist/client/processingCostDeficit/index.d.ts.map +1 -0
  63. package/dist/client/processingCostDeficit/index.js +54 -0
  64. package/dist/client/processingCostDeficit/index.js.map +1 -0
  65. package/dist/client/products/catalog.d.ts +26 -0
  66. package/dist/client/products/catalog.d.ts.map +1 -0
  67. package/dist/client/products/catalog.js +140 -0
  68. package/dist/client/products/catalog.js.map +1 -0
  69. package/dist/client/products/catalogClient.d.ts +109 -0
  70. package/dist/client/products/catalogClient.d.ts.map +1 -0
  71. package/dist/client/products/catalogClient.js +84 -0
  72. package/dist/client/products/catalogClient.js.map +1 -0
  73. package/dist/client/products/prices.d.ts +1 -0
  74. package/dist/client/products/prices.d.ts.map +1 -1
  75. package/dist/client/products/prices.js +1 -0
  76. package/dist/client/products/prices.js.map +1 -1
  77. package/dist/client/publicTypes.d.ts +2 -0
  78. package/dist/client/publicTypes.d.ts.map +1 -1
  79. package/dist/component/_generated/api.d.ts +284 -0
  80. package/dist/component/_generated/api.d.ts.map +1 -0
  81. package/dist/component/_generated/api.js +31 -0
  82. package/dist/component/_generated/api.js.map +1 -0
  83. package/dist/component/_generated/component.d.ts +535 -0
  84. package/dist/component/_generated/component.d.ts.map +1 -1
  85. package/dist/component/balanceFunding/helpers.d.ts +86 -0
  86. package/dist/component/balanceFunding/helpers.d.ts.map +1 -0
  87. package/dist/component/balanceFunding/helpers.js +68 -0
  88. package/dist/component/balanceFunding/helpers.js.map +1 -0
  89. package/dist/component/balanceFunding/importHandler.d.ts +13 -0
  90. package/dist/component/balanceFunding/importHandler.d.ts.map +1 -0
  91. package/dist/component/balanceFunding/importHandler.js +130 -0
  92. package/dist/component/balanceFunding/importHandler.js.map +1 -0
  93. package/dist/component/balanceFunding/lifecycleHandlers.d.ts +85 -0
  94. package/dist/component/balanceFunding/lifecycleHandlers.d.ts.map +1 -0
  95. package/dist/component/balanceFunding/lifecycleHandlers.js +60 -0
  96. package/dist/component/balanceFunding/lifecycleHandlers.js.map +1 -0
  97. package/dist/component/balanceFunding/mutationValidators.d.ts +238 -0
  98. package/dist/component/balanceFunding/mutationValidators.d.ts.map +1 -0
  99. package/dist/component/balanceFunding/mutationValidators.js +55 -0
  100. package/dist/component/balanceFunding/mutationValidators.js.map +1 -0
  101. package/dist/component/balanceFunding/mutations.d.ts +335 -0
  102. package/dist/component/balanceFunding/mutations.d.ts.map +1 -0
  103. package/dist/component/balanceFunding/mutations.js +106 -0
  104. package/dist/component/balanceFunding/mutations.js.map +1 -0
  105. package/dist/component/balanceFunding/preparationHandlers.d.ts +55 -0
  106. package/dist/component/balanceFunding/preparationHandlers.d.ts.map +1 -0
  107. package/dist/component/balanceFunding/preparationHandlers.js +165 -0
  108. package/dist/component/balanceFunding/preparationHandlers.js.map +1 -0
  109. package/dist/component/balanceFunding/queries.d.ts +151 -0
  110. package/dist/component/balanceFunding/queries.d.ts.map +1 -0
  111. package/dist/component/balanceFunding/queries.js +180 -0
  112. package/dist/component/balanceFunding/queries.js.map +1 -0
  113. package/dist/component/balanceFunding/schema.d.ts +748 -0
  114. package/dist/component/balanceFunding/schema.d.ts.map +1 -0
  115. package/dist/component/balanceFunding/schema.js +124 -0
  116. package/dist/component/balanceFunding/schema.js.map +1 -0
  117. package/dist/component/balanceFunding/stateHandlers.d.ts +58 -0
  118. package/dist/component/balanceFunding/stateHandlers.d.ts.map +1 -0
  119. package/dist/component/balanceFunding/stateHandlers.js +160 -0
  120. package/dist/component/balanceFunding/stateHandlers.js.map +1 -0
  121. package/dist/component/convex.config.d.ts.map +1 -1
  122. package/dist/component/convex.config.js +2 -0
  123. package/dist/component/convex.config.js.map +1 -1
  124. package/dist/component/costRecovery/completion.d.ts +1 -0
  125. package/dist/component/costRecovery/completion.d.ts.map +1 -1
  126. package/dist/component/costRecovery/helpers.d.ts +1 -0
  127. package/dist/component/costRecovery/helpers.d.ts.map +1 -1
  128. package/dist/component/costRecovery/mutations.d.ts +5 -0
  129. package/dist/component/costRecovery/mutations.d.ts.map +1 -1
  130. package/dist/component/costRecovery/preparation.d.ts +50 -0
  131. package/dist/component/costRecovery/preparation.d.ts.map +1 -0
  132. package/dist/component/costRecovery/preparation.js +108 -0
  133. package/dist/component/costRecovery/preparation.js.map +1 -0
  134. package/dist/component/costRecovery/queries.d.ts +1 -0
  135. package/dist/component/costRecovery/queries.d.ts.map +1 -1
  136. package/dist/component/costRecovery/reservations.d.ts +2 -0
  137. package/dist/component/costRecovery/reservations.d.ts.map +1 -1
  138. package/dist/component/costRecovery/schema.d.ts +7 -2
  139. package/dist/component/costRecovery/schema.d.ts.map +1 -1
  140. package/dist/component/costRecovery/schema.js +1 -0
  141. package/dist/component/costRecovery/schema.js.map +1 -1
  142. package/dist/component/durableExecution/runtime.d.ts +3 -0
  143. package/dist/component/durableExecution/runtime.d.ts.map +1 -0
  144. package/dist/component/durableExecution/runtime.js +12 -0
  145. package/dist/component/durableExecution/runtime.js.map +1 -0
  146. package/dist/component/earnings/triggers.d.ts +242 -2
  147. package/dist/component/earnings/triggers.d.ts.map +1 -1
  148. package/dist/component/products/mutations.d.ts +9 -0
  149. package/dist/component/products/mutations.d.ts.map +1 -1
  150. package/dist/component/products/mutations.js +31 -2
  151. package/dist/component/products/mutations.js.map +1 -1
  152. package/dist/component/schema.d.ts +253 -1
  153. package/dist/component/schema.js +4 -0
  154. package/dist/component/schema.js.map +1 -1
  155. package/docs/read-contracts.md +33 -0
  156. package/package.json +4 -2
  157. package/src/client/core/account-session-client.test.ts +74 -0
  158. package/src/client/core/accountCapabilities.ts +22 -0
  159. package/src/client/core/accountConfigurations.test.ts +183 -0
  160. package/src/client/core/accountConfigurations.ts +161 -0
  161. package/src/client/core/accountLinks.test.ts +6 -2
  162. package/src/client/core/accountLinks.ts +122 -5
  163. package/src/client/core/accounts.ts +8 -115
  164. package/src/client/core/billingPortal.test.ts +247 -0
  165. package/src/client/core/billingPortalClient.ts +35 -0
  166. package/src/client/costRecovery.test.ts +34 -0
  167. package/src/client/costRecovery.ts +21 -0
  168. package/src/client/financialOutcomes/adapters.ts +88 -0
  169. package/src/client/financialOutcomes/contracts.ts +43 -0
  170. package/src/client/financialOutcomes/errors.ts +29 -0
  171. package/src/client/financialOutcomes/index.ts +5 -0
  172. package/src/client/financialOutcomes/outcomes.test.ts +254 -0
  173. package/src/client/financialOutcomes/retry.ts +52 -0
  174. package/src/client/index.test.ts +0 -64
  175. package/src/client/index.ts +35 -185
  176. package/src/client/processingCostDeficit/README.md +35 -0
  177. package/src/client/processingCostDeficit/calculator.test.ts +176 -0
  178. package/src/client/processingCostDeficit/index.ts +91 -0
  179. package/src/client/products/catalog.test.ts +389 -0
  180. package/src/client/products/catalog.ts +225 -0
  181. package/src/client/products/catalogClient.ts +172 -0
  182. package/src/client/products/prices.test.ts +24 -0
  183. package/src/client/products/prices.ts +2 -0
  184. package/src/client/publicTypes.ts +13 -0
  185. package/src/component/_generated/api.ts +27 -1
  186. package/src/component/_generated/component.ts +707 -0
  187. package/src/component/balanceFunding/failure.test.ts +116 -0
  188. package/src/component/balanceFunding/helpers.ts +102 -0
  189. package/src/component/balanceFunding/import.test.ts +221 -0
  190. package/src/component/balanceFunding/importHandler.ts +146 -0
  191. package/src/component/balanceFunding/lifecycleHandlers.ts +90 -0
  192. package/src/component/balanceFunding/lookup.test.ts +113 -0
  193. package/src/component/balanceFunding/mutationValidators.ts +63 -0
  194. package/src/component/balanceFunding/mutations.ts +136 -0
  195. package/src/component/balanceFunding/preparation.test.ts +146 -0
  196. package/src/component/balanceFunding/preparationHandlers.ts +204 -0
  197. package/src/component/balanceFunding/queries.ts +221 -0
  198. package/src/component/balanceFunding/requestLookup.test.ts +160 -0
  199. package/src/component/balanceFunding/schema.ts +169 -0
  200. package/src/component/balanceFunding/state.test.ts +352 -0
  201. package/src/component/balanceFunding/stateHandlers.ts +198 -0
  202. package/src/component/balanceFunding/validation.test.ts +100 -0
  203. package/src/component/convex.config.ts +2 -0
  204. package/src/component/costRecovery/preparation.test.ts +355 -0
  205. package/src/component/costRecovery/preparation.ts +124 -0
  206. package/src/component/costRecovery/schema.ts +1 -0
  207. package/src/component/durableExecution/composition.test.ts +568 -0
  208. package/src/component/durableExecution/runtime.ts +12 -0
  209. package/src/component/products/mutations.ts +39 -2
  210. package/src/component/schema.ts +8 -0
package/CHANGELOG.md CHANGED
@@ -26,6 +26,59 @@
26
26
  - Remove internal tracker references from public documentation and add a
27
27
  regression check that prevents their reintroduction.
28
28
 
29
+ ## [0.39.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.38.0...v0.39.0) (2026-10-17)
30
+
31
+ ### Features
32
+
33
+ - add nested durable execution runtime ([4e300df](https://github.com/FantasticDevHQ/better-stripe/commit/4e300dfcd12dac3be6a9ee568502766d94b7ac11))
34
+ - add policy-explicit processing cost deficit calculator ([eaab6dc](https://github.com/FantasticDevHQ/better-stripe/commit/eaab6dcaa06554ae7ba3ba7035194758ae0a0926))
35
+ - add policy-explicit processing cost deficit calculator ([ac18f4e](https://github.com/FantasticDevHQ/better-stripe/commit/ac18f4eaab624730cc45b3a31039809c8a8e8f8a))
36
+ - **cost-recovery:** prepare bounded groups atomically ([cad0ec7](https://github.com/FantasticDevHQ/better-stripe/commit/cad0ec729a9b72ad17b09311808e524fd73fa667))
37
+ - **cost-recovery:** prepare bounded recovery groups atomically ([2157234](https://github.com/FantasticDevHQ/better-stripe/commit/215723444c649c341861ec58a030df3331c151b6))
38
+ - persist durable balance funding operations ([11b81d5](https://github.com/FantasticDevHQ/better-stripe/commit/11b81d5a66548f73d131555dd3034eb79629c39e))
39
+ - persist versioned balance funding preparations and operations ([d8943eb](https://github.com/FantasticDevHQ/better-stripe/commit/d8943ebb251df672b435fe7722877bbd3395c498))
40
+ - recover funding preparation by immutable scoped request ([a2c839c](https://github.com/FantasticDevHQ/better-stripe/commit/a2c839c29faddcc04ac52aeac26dfcfa5c5352da))
41
+
42
+ ### Maintenance
43
+
44
+ - ratchet coverage after durable funding state checks ([a2be05d](https://github.com/FantasticDevHQ/better-stripe/commit/a2be05dd60e12abfdff7d4bafad848f408074b75))
45
+ - ratchet funding coverage after calculator integration ([b709c7d](https://github.com/FantasticDevHQ/better-stripe/commit/b709c7d251ff59ca297f7bfbb3dba0599c8cee7f))
46
+ - ratchet funding coverage after catalog integration ([71ac9b6](https://github.com/FantasticDevHQ/better-stripe/commit/71ac9b60ba6fb76fac0055811fe5ce185a92b145))
47
+ - ratchet funding coverage after outcomes integration ([8e8282c](https://github.com/FantasticDevHQ/better-stripe/commit/8e8282ce9d4584943cb69c71e481e0337a6a7bd7))
48
+
49
+ ## [0.38.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.37.1...v0.38.0) (2026-10-17)
50
+
51
+ ### Features
52
+
53
+ - **accounts:** add merchant configuration and transfer readiness ([e9994a9](https://github.com/FantasticDevHQ/better-stripe/commit/e9994a9e49295ebd963cf30ecd3fb6d62d38a409))
54
+ - add typed financial readiness and bounded retry policy ([9dae843](https://github.com/FantasticDevHQ/better-stripe/commit/9dae843d17d1a83fed9f496bb28f10e902b69170))
55
+ - **billing:** add typed portal configuration APIs ([f43f5f6](https://github.com/FantasticDevHQ/better-stripe/commit/f43f5f670a894d48f9bc29ba18f82c0b4ad5e369))
56
+ - **billing:** add typed portal configuration APIs ([8ff5510](https://github.com/FantasticDevHQ/better-stripe/commit/8ff5510ba6e9135bf7a4d48610a3cc85dbe8aff4))
57
+ - **catalog:** ensure lookup-key prices and adopt products ([e3f75fc](https://github.com/FantasticDevHQ/better-stripe/commit/e3f75fce959256dafa3475f67e9a2b65c4faeb71))
58
+ - **catalog:** ensure lookup-key prices and adopt products ([9dcc092](https://github.com/FantasticDevHQ/better-stripe/commit/9dcc0927543f87bb932e24e38811b413a07c97e4))
59
+ - standardize financial readiness and bounded retries ([06ae478](https://github.com/FantasticDevHQ/better-stripe/commit/06ae478ff2ee5c9e89f79d109ae1e92a3f8510b7))
60
+
61
+ ### Bug Fixes
62
+
63
+ - **catalog:** enforce adoption ownership atomically ([afd9909](https://github.com/FantasticDevHQ/better-stripe/commit/afd9909f93973af329abe46858f646d03d1d24d2))
64
+
65
+ ### Documentation
66
+
67
+ - complete durable preparation handoff contracts ([066dda2](https://github.com/FantasticDevHQ/better-stripe/commit/066dda2626f6f713af95bb5cb34bc09ddca2e8b9))
68
+ - define component extraction and durable execution contracts ([c27a215](https://github.com/FantasticDevHQ/better-stripe/commit/c27a21577e9f52ab62f3c45f14f484e584e9d0db))
69
+ - define scoped preparation results and migration pauses ([1d0a07f](https://github.com/FantasticDevHQ/better-stripe/commit/1d0a07f8b634182dc04ade4c36cca7311e2c3773))
70
+ - refresh extraction contract review baseline ([070ba5f](https://github.com/FantasticDevHQ/better-stripe/commit/070ba5f6ec833ee780414d2fae0ca6498699121e))
71
+
72
+ ### Maintenance
73
+
74
+ - ratchet portal coverage after earnings integration ([a179036](https://github.com/FantasticDevHQ/better-stripe/commit/a17903630339e00041c0e86c5da3e223a6a0b084))
75
+ - ratchet portal coverage after merged contracts integration ([5faff9a](https://github.com/FantasticDevHQ/better-stripe/commit/5faff9aa5206bbcadf8086a966162631c5b7ac42))
76
+ - ratchet portal coverage after seller attribution integration ([fdcb303](https://github.com/FantasticDevHQ/better-stripe/commit/fdcb3033df39b43d2d33bb8e41ef7397ad36509d))
77
+
78
+ ### Refactoring
79
+
80
+ - reuse package currency and embedded session APIs ([#247](https://github.com/FantasticDevHQ/better-stripe/issues/247)) ([c4ab43c](https://github.com/FantasticDevHQ/better-stripe/commit/c4ab43cc9bccf631fd5a576131ddc65f489fead5))
81
+
29
82
  ## [0.37.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.37.0...v0.37.1) (2026-10-17)
30
83
 
31
84
  ### Bug Fixes
package/MIGRATION.md CHANGED
@@ -19,6 +19,15 @@ fields as unavailable rather than zero. No table migration is required.
19
19
 
20
20
  ## Package and runtime
21
21
 
22
+ Nested durable execution requires Convex 1.46.0 or newer. The package peer
23
+ minimum changes from `^1.29.3` to `^1.46.0`; upgrade older consumers before
24
+ installing this change. Existing public methods remain available. Workflow
25
+ 0.4.10 and Workpool 0.4.14 are pinned, and Workflow installs its own nested
26
+ Workpool/Batch Worker. Regenerate bindings and deploy the component through your
27
+ normal upgrade process. Existing financial jobs are not migrated automatically.
28
+ See [runtime compatibility and execution boundaries](docs/architecture/durable-execution.md)
29
+ for the version comparison, host credential actions, replay and cancellation.
30
+
22
31
  Payout worker discovery, expiry, local snapshot collection, pending affiliate
23
32
  payouts and seller cost history now use component-compatible pagination. The
24
33
  page result shape is unchanged. Clear cached pagination cursors and reload from
package/README.md CHANGED
@@ -70,7 +70,7 @@ claim execution are completed.
70
70
 
71
71
  ## Status
72
72
 
73
- **Version**: `0.37.1` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
73
+ **Version**: `0.39.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
74
74
 
75
75
  Used in production by its authors. Webhook pipeline is covered by unit tests and a live E2E harness (`npm run e2e:webhooks`) that fires real Stripe-signed events and asserts the ledger.
76
76
 
@@ -382,6 +382,10 @@ shows where the host's authenticated-actor check belongs.
382
382
 
383
383
  ### Product and Price
384
384
 
385
+ `ensurePrice(ctx, { stripeProductId, lookupKey, unitAmount, type, idempotencyKey, currency?, interval?, intervalCount? })` finds a price by its provider lookup key, verifies its immutable terms, and adopts the price and product into the component mirrors. If absent, it creates the price with the supplied idempotency key. A matching provider result repairs a failed mirror write on retry. Inactive prices, different products or pricing terms, and metered or transformed pricing are rejected. Choose a new versioned lookup key when changing price terms; existing subscriptions retain their current price.
386
+
387
+ Scope the idempotency key to one catalog operation and reuse it only with identical creation parameters. Authorize product access in your host action. `getStripePriceByLookupKey(ctx, { lookupKey })` reads Stripe without changing mirrors. `adoptProduct(ctx, { stripeProductId, accountId? })` imports an existing provider product, preserving existing ownership and rejecting reassignment. Adoption does not update provider metadata or statement descriptors. `createPrice` also accepts `lookupKey` for callers handling adoption themselves. Tier names, lookup-key version policy, and entitlement mapping remain in the host app.
388
+
385
389
  | Method | Description |
386
390
  | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
387
391
  | `createProduct(ctx, { name, description?, active?, accountId?, metadata? })` | Create product in Stripe and component DB |
@@ -508,6 +512,26 @@ an optional `reservedAmount` to distinguish reservations from collected money,
508
512
  while preserving the legacy `invoicedAmount` input. See the example README for
509
513
  cutover constraints and the sandbox renewal acceptance procedure.
510
514
 
515
+ ### Atomic recovery preparation
516
+
517
+ Call `stripe.costRecovery.prepareGroup(ctx, { ...groupOptions, limit: 100 })`
518
+ after authorizing the account, scope, currency, source and debit/credit policy.
519
+ Each call reserves at most one batch and seals the completed target in the same
520
+ component mutation. It returns `{ status: "prepared", group, isDone }`. Continue
521
+ with unchanged group options while `isDone` is false; do not run provider effects
522
+ until it is true. Sealed or finished replay returns the saved group without
523
+ another reservation. Batch identities use a persisted sequence, independent of
524
+ pending or completed reservation counts. The optional limit must be 1 through
525
+ 100 and can change between bounded calls.
526
+
527
+ A competing boundary returns `{ status: "conflict", reason: "scope_busy",
528
+ retryable: false }`. Changed group identity or a legacy operation-key collision
529
+ returns `identity_changed`; invalid scope or policy returns `rejected`. These
530
+ outcomes do not reserve anything. Read current state and let host policy decide
531
+ what to do; conflicts are not automatic retries. Existing `reserve`, `seal` and
532
+ `finish` methods remain available. Host reporting and provider execution remain
533
+ separate from preparation.
534
+
511
535
  ### Importing opening recovery balances
512
536
 
513
537
  When moving an existing ledger into the component, your server can call