@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.
- package/CHANGELOG.md +16 -0
- package/MIGRATION.md +14 -0
- package/README.md +7 -1
- package/dist/client/connect/payoutActivationProof.d.ts.map +1 -1
- package/dist/client/connect/payoutActivationProof.js +88 -42
- package/dist/client/connect/payoutActivationProof.js.map +1 -1
- package/dist/client/connect/payoutAdoption.d.ts +3 -0
- package/dist/client/connect/payoutAdoption.d.ts.map +1 -1
- package/dist/client/connect/payoutAdoption.js +218 -183
- package/dist/client/connect/payoutAdoption.js.map +1 -1
- package/dist/client/connect/payoutAdoptionCollection.d.ts +21 -0
- package/dist/client/connect/payoutAdoptionCollection.d.ts.map +1 -0
- package/dist/client/connect/payoutAdoptionCollection.js +44 -0
- package/dist/client/connect/payoutAdoptionCollection.js.map +1 -0
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +54 -14
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutCollectedInput.d.ts +110 -0
- package/dist/client/connect/payoutCollectedInput.d.ts.map +1 -0
- package/dist/client/connect/payoutCollectedInput.js +70 -0
- package/dist/client/connect/payoutCollectedInput.js.map +1 -0
- package/dist/client/connect/payoutExecution.d.ts +1 -0
- package/dist/client/connect/payoutExecution.d.ts.map +1 -1
- package/dist/client/connect/payoutExecution.js +94 -67
- package/dist/client/connect/payoutExecution.js.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +29 -7
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.js +9 -6
- package/dist/client/connect/payoutExecutionTestHelpers.js.map +1 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +3745 -0
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -0
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.js +55 -0
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.js.map +1 -0
- package/dist/client/connect/payoutOutcomeBatches.d.ts +5 -0
- package/dist/client/connect/payoutOutcomeBatches.d.ts.map +1 -0
- package/dist/client/connect/payoutOutcomeBatches.js +21 -0
- package/dist/client/connect/payoutOutcomeBatches.js.map +1 -0
- package/dist/client/connect/payoutPolicyState.d.ts +14 -0
- package/dist/client/connect/payoutPolicyState.d.ts.map +1 -0
- package/dist/client/connect/payoutPolicyState.js +19 -0
- package/dist/client/connect/payoutPolicyState.js.map +1 -0
- package/dist/client/connect/payoutPreview.d.ts +1 -0
- package/dist/client/connect/payoutPreview.d.ts.map +1 -1
- package/dist/client/connect/payoutPreview.js +31 -19
- package/dist/client/connect/payoutPreview.js.map +1 -1
- package/dist/client/connect/payoutQualification.d.ts +7 -1
- package/dist/client/connect/payoutQualification.d.ts.map +1 -1
- package/dist/client/connect/payoutQualification.js +34 -19
- package/dist/client/connect/payoutQualification.js.map +1 -1
- package/dist/client/connect/payoutReconciliation.d.ts +11 -6
- package/dist/client/connect/payoutReconciliation.d.ts.map +1 -1
- package/dist/client/connect/payoutReconciliation.js +62 -16
- package/dist/client/connect/payoutReconciliation.js.map +1 -1
- package/dist/client/connect/payoutResumableProof.d.ts +17 -0
- package/dist/client/connect/payoutResumableProof.d.ts.map +1 -0
- package/dist/client/connect/payoutResumableProof.js +25 -0
- package/dist/client/connect/payoutResumableProof.js.map +1 -0
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +27 -7
- package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutWorker.d.ts.map +1 -1
- package/dist/client/connect/payoutWorker.js +4 -1
- package/dist/client/connect/payoutWorker.js.map +1 -1
- package/dist/client/connect/transferReceipt.d.ts +6 -2
- package/dist/client/connect/transferReceipt.d.ts.map +1 -1
- package/dist/client/connect/transferReceipt.js +3 -3
- package/dist/client/connect/transferReceipt.js.map +1 -1
- package/dist/client/costRecovery.d.ts +5 -0
- package/dist/client/costRecovery.d.ts.map +1 -1
- package/dist/client/costRecovery.js +5 -0
- package/dist/client/costRecovery.js.map +1 -1
- package/dist/client/payoutPolicy.d.ts +4 -0
- package/dist/client/payoutPolicy.d.ts.map +1 -1
- package/dist/client/payoutPolicy.js +24 -14
- package/dist/client/payoutPolicy.js.map +1 -1
- package/dist/component/_generated/component.d.ts +247 -0
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/costRecovery/mutations.js +1 -1
- package/dist/component/costRecovery/queries.d.ts +9 -0
- package/dist/component/costRecovery/queries.d.ts.map +1 -1
- package/dist/component/costRecovery/queries.js +20 -0
- package/dist/component/costRecovery/queries.js.map +1 -1
- package/dist/component/earnings/triggers.d.ts +28 -10
- package/dist/component/earnings/triggers.d.ts.map +1 -1
- package/dist/component/payoutPolicy/adoption.d.ts.map +1 -1
- package/dist/component/payoutPolicy/adoption.js +12 -7
- package/dist/component/payoutPolicy/adoption.js.map +1 -1
- package/dist/component/payoutPolicy/mutations.d.ts +12 -0
- package/dist/component/payoutPolicy/mutations.d.ts.map +1 -1
- package/dist/component/payoutPolicy/queries.d.ts +2 -0
- package/dist/component/payoutPolicy/queries.d.ts.map +1 -1
- package/dist/component/payoutPolicy/schema.d.ts +31 -7
- package/dist/component/payoutPolicy/schema.d.ts.map +1 -1
- package/dist/component/payoutPolicy/schema.js +2 -0
- package/dist/component/payoutPolicy/schema.js.map +1 -1
- package/dist/component/payoutRelease/adoption.d.ts +9 -1
- package/dist/component/payoutRelease/adoption.d.ts.map +1 -1
- package/dist/component/payoutRelease/adoption.js +33 -16
- package/dist/component/payoutRelease/adoption.js.map +1 -1
- package/dist/component/payoutRelease/fees.d.ts.map +1 -1
- package/dist/component/payoutRelease/fees.js +7 -0
- package/dist/component/payoutRelease/fees.js.map +1 -1
- package/dist/component/payoutRelease/helpers.d.ts +4 -1
- package/dist/component/payoutRelease/helpers.d.ts.map +1 -1
- package/dist/component/payoutRelease/helpers.js +17 -10
- package/dist/component/payoutRelease/helpers.js.map +1 -1
- package/dist/component/payoutRelease/mutations.d.ts +79 -0
- package/dist/component/payoutRelease/mutations.d.ts.map +1 -1
- package/dist/component/payoutRelease/mutations.js +38 -81
- package/dist/component/payoutRelease/mutations.js.map +1 -1
- package/dist/component/payoutRelease/outcome.d.ts +69 -0
- package/dist/component/payoutRelease/outcome.d.ts.map +1 -0
- package/dist/component/payoutRelease/outcome.js +94 -0
- package/dist/component/payoutRelease/outcome.js.map +1 -0
- package/dist/component/payoutRelease/planning.d.ts +4 -0
- package/dist/component/payoutRelease/planning.d.ts.map +1 -1
- package/dist/component/payoutRelease/planning.js +8 -3
- package/dist/component/payoutRelease/planning.js.map +1 -1
- package/dist/component/payoutRelease/preview.d.ts +2 -0
- package/dist/component/payoutRelease/preview.d.ts.map +1 -1
- package/dist/component/payoutRelease/preview.js +2 -0
- package/dist/component/payoutRelease/preview.js.map +1 -1
- package/dist/component/payoutRelease/queries.d.ts +13 -2
- package/dist/component/payoutRelease/queries.d.ts.map +1 -1
- package/dist/component/payoutRelease/queries.js +2 -0
- package/dist/component/payoutRelease/queries.js.map +1 -1
- package/dist/component/payoutRelease/schema.d.ts +17 -2
- package/dist/component/payoutRelease/schema.d.ts.map +1 -1
- package/dist/component/payoutRelease/schema.js +3 -0
- package/dist/component/payoutRelease/schema.js.map +1 -1
- package/dist/component/payoutSnapshots/adoption.d.ts +88 -0
- package/dist/component/payoutSnapshots/adoption.d.ts.map +1 -0
- package/dist/component/payoutSnapshots/adoption.js +49 -0
- package/dist/component/payoutSnapshots/adoption.js.map +1 -0
- package/dist/component/payoutSnapshots/financial.d.ts +47 -0
- package/dist/component/payoutSnapshots/financial.d.ts.map +1 -0
- package/dist/component/payoutSnapshots/financial.js +103 -0
- package/dist/component/payoutSnapshots/financial.js.map +1 -0
- package/dist/component/payoutSnapshots/liabilities.d.ts +7 -0
- package/dist/component/payoutSnapshots/liabilities.d.ts.map +1 -0
- package/dist/component/payoutSnapshots/liabilities.js +18 -0
- package/dist/component/payoutSnapshots/liabilities.js.map +1 -0
- package/dist/component/payoutSnapshots/localState.d.ts +22 -16
- package/dist/component/payoutSnapshots/localState.d.ts.map +1 -1
- package/dist/component/payoutSnapshots/localState.js +19 -7
- package/dist/component/payoutSnapshots/localState.js.map +1 -1
- package/dist/component/payoutSnapshots/mutations.d.ts +6 -0
- package/dist/component/payoutSnapshots/mutations.d.ts.map +1 -1
- package/dist/component/payoutSnapshots/mutations.js +3 -1
- package/dist/component/payoutSnapshots/mutations.js.map +1 -1
- package/dist/component/payoutSnapshots/queries.d.ts +133 -0
- package/dist/component/payoutSnapshots/queries.d.ts.map +1 -0
- package/dist/component/payoutSnapshots/queries.js +86 -0
- package/dist/component/payoutSnapshots/queries.js.map +1 -0
- package/dist/component/payoutSnapshots/revisions.d.ts.map +1 -1
- package/dist/component/payoutSnapshots/revisions.js +19 -0
- package/dist/component/payoutSnapshots/revisions.js.map +1 -1
- package/dist/component/payoutSnapshots/schema.d.ts +20 -6
- package/dist/component/payoutSnapshots/schema.d.ts.map +1 -1
- package/dist/component/payoutSnapshots/schema.js +5 -1
- package/dist/component/payoutSnapshots/schema.js.map +1 -1
- package/dist/component/payoutWorker/mutations.d.ts.map +1 -1
- package/dist/component/payoutWorker/mutations.js +3 -1
- package/dist/component/payoutWorker/mutations.js.map +1 -1
- package/dist/component/schema.d.ts +27 -7
- package/dist/react/workflows/payout-attempt-state.d.ts.map +1 -1
- package/dist/react/workflows/payout-attempt-state.js +3 -0
- package/dist/react/workflows/payout-attempt-state.js.map +1 -1
- package/dist/react/workflows/payout-progress-state.d.ts.map +1 -1
- package/dist/react/workflows/payout-progress-state.js +3 -0
- package/dist/react/workflows/payout-progress-state.js.map +1 -1
- package/docs/settlement.md +136 -24
- package/package.json +1 -1
- package/src/client/connect/payoutActivationProof.ts +123 -53
- package/src/client/connect/payoutAdoption.ts +299 -215
- package/src/client/connect/payoutAdoptionCollection.ts +78 -0
- package/src/client/connect/payoutAdoptionConcurrency.test.ts +266 -0
- package/src/client/connect/payoutCacheIdentity.test.ts +93 -0
- package/src/client/connect/payoutCollectedInput.ts +120 -0
- package/src/client/connect/payoutExecution.ts +116 -84
- package/src/client/connect/payoutExecutionTestHelpers.ts +19 -6
- package/src/client/connect/payoutLargeAdoption.test.ts +541 -0
- package/src/client/connect/payoutLargeAdoptionTestHelpers.ts +74 -0
- package/src/client/connect/payoutLargeHistory.test.ts +222 -0
- package/src/client/connect/payoutLiabilityVersion.test.ts +221 -0
- package/src/client/connect/payoutOutcomeBatches.test.ts +40 -0
- package/src/client/connect/payoutOutcomeBatches.ts +24 -0
- package/src/client/connect/payoutPolicyState.ts +36 -0
- package/src/client/connect/payoutPreview.ts +42 -24
- package/src/client/connect/payoutQualification.ts +68 -21
- package/src/client/connect/payoutReconciliation.ts +86 -7
- package/src/client/connect/payoutResumableProof.ts +41 -0
- package/src/client/connect/payoutWorker.ts +4 -1
- package/src/client/connect/transferReceipt.ts +3 -2
- package/src/client/connect/transferReceiptBaseline.test.ts +55 -0
- package/src/client/costRecovery.ts +8 -0
- package/src/client/payoutPolicy.ts +37 -23
- package/src/component/_generated/api.ts +10 -0
- package/src/component/_generated/component.ts +288 -0
- package/src/component/costRecovery/mutations.ts +1 -1
- package/src/component/costRecovery/queries.ts +21 -0
- package/src/component/payout-snapshots.test.ts +45 -1
- package/src/component/payoutPolicy/adoption.ts +20 -7
- package/src/component/payoutPolicy/schema.ts +2 -0
- package/src/component/payoutRelease/adoption.ts +57 -27
- package/src/component/payoutRelease/fees.ts +9 -0
- package/src/component/payoutRelease/helpers.ts +19 -11
- package/src/component/payoutRelease/mutations.ts +43 -96
- package/src/component/payoutRelease/outcome.ts +119 -0
- package/src/component/payoutRelease/planning.ts +11 -2
- package/src/component/payoutRelease/preview.ts +2 -0
- package/src/component/payoutRelease/queries.ts +2 -0
- package/src/component/payoutRelease/schema.ts +3 -0
- package/src/component/payoutSnapshots/adoption.ts +73 -0
- package/src/component/payoutSnapshots/financial.ts +134 -0
- package/src/component/payoutSnapshots/liabilities.ts +25 -0
- package/src/component/payoutSnapshots/localState.ts +24 -6
- package/src/component/payoutSnapshots/mutations.ts +10 -1
- package/src/component/payoutSnapshots/queries.ts +104 -0
- package/src/component/payoutSnapshots/revisions.ts +26 -0
- package/src/component/payoutSnapshots/schema.ts +5 -0
- package/src/component/payoutWorker/mutations.ts +3 -1
- package/src/react/workflows/payout-attempt-state.ts +6 -0
- package/src/react/workflows/payout-progress-state.ts +6 -0
package/docs/settlement.md
CHANGED
|
@@ -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
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
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
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
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.
|
|
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
|
|
586
|
-
|
|
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
|
|
745
|
-
region
|
|
746
|
-
|
|
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.
|
|
758
|
-
|
|
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
|
-
|
|
792
|
-
|
|
793
|
-
|
|
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
|
|
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,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
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
}
|