@fantastic.dev/better-stripe 0.34.0 → 0.37.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 +260 -0
- package/README.md +1 -1
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +664 -2
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +332 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +664 -2
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +332 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/refundCommandEvidence.d.ts +14 -0
- package/dist/client/connect/refundCommandEvidence.d.ts.map +1 -0
- package/dist/client/connect/refundCommandEvidence.js +20 -0
- package/dist/client/connect/refundCommandEvidence.js.map +1 -0
- package/dist/client/connect/refundCommandNormalization.d.ts +11 -0
- package/dist/client/connect/refundCommandNormalization.d.ts.map +1 -0
- package/dist/client/connect/refundCommandNormalization.js +12 -0
- package/dist/client/connect/refundCommandNormalization.js.map +1 -0
- package/dist/client/financialObservations.d.ts +42 -0
- package/dist/client/financialObservations.d.ts.map +1 -0
- package/dist/client/financialObservations.js +58 -0
- package/dist/client/financialObservations.js.map +1 -0
- package/dist/client/financialOwnership.d.ts +52 -0
- package/dist/client/financialOwnership.d.ts.map +1 -0
- package/dist/client/financialOwnership.js +72 -0
- package/dist/client/financialOwnership.js.map +1 -0
- package/dist/client/index.d.ts +2 -2
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +2 -2
- package/dist/client/index.js.map +1 -1
- package/dist/client/observationPagination.d.ts +10 -0
- package/dist/client/observationPagination.d.ts.map +1 -0
- package/dist/client/observationPagination.js +12 -0
- package/dist/client/observationPagination.js.map +1 -0
- package/dist/client/operationEvidence.d.ts +37 -0
- package/dist/client/operationEvidence.d.ts.map +1 -0
- package/dist/client/operationEvidence.js +44 -0
- package/dist/client/operationEvidence.js.map +1 -0
- package/dist/client/publicTypes.d.ts +6 -0
- package/dist/client/publicTypes.d.ts.map +1 -1
- package/dist/client/readContracts.d.ts +31 -0
- package/dist/client/readContracts.d.ts.map +1 -1
- package/dist/client/readContracts.js +14 -0
- package/dist/client/readContracts.js.map +1 -1
- package/dist/client/transferObservations.d.ts +59 -0
- package/dist/client/transferObservations.d.ts.map +1 -0
- package/dist/client/transferObservations.js +82 -0
- package/dist/client/transferObservations.js.map +1 -0
- package/dist/component/_generated/component.d.ts +687 -0
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/affiliateRecovery/mutations.d.ts.map +1 -1
- package/dist/component/affiliateRecovery/mutations.js +4 -1
- package/dist/component/affiliateRecovery/mutations.js.map +1 -1
- package/dist/component/connect/mutations.d.ts.map +1 -1
- package/dist/component/connect/mutations.js +18 -2
- package/dist/component/connect/mutations.js.map +1 -1
- package/dist/component/connect/queries.d.ts +8 -0
- package/dist/component/connect/queries.d.ts.map +1 -1
- package/dist/component/connect/reversalClaims.d.ts.map +1 -1
- package/dist/component/connect/reversalClaims.js +7 -1
- package/dist/component/connect/reversalClaims.js.map +1 -1
- package/dist/component/connect/reversalReceipts.d.ts.map +1 -1
- package/dist/component/connect/reversalReceipts.js +2 -0
- package/dist/component/connect/reversalReceipts.js.map +1 -1
- package/dist/component/connect/schema.d.ts +11 -1
- package/dist/component/connect/schema.d.ts.map +1 -1
- package/dist/component/connect/schema.js +9 -1
- package/dist/component/connect/schema.js.map +1 -1
- package/dist/component/connect/validators.d.ts +9 -1
- package/dist/component/connect/validators.d.ts.map +1 -1
- package/dist/component/connect/validators.js +2 -0
- package/dist/component/connect/validators.js.map +1 -1
- package/dist/component/earnings/pairedAdjustment.d.ts +12 -0
- package/dist/component/earnings/pairedAdjustment.d.ts.map +1 -0
- package/dist/component/earnings/pairedAdjustment.js +46 -0
- package/dist/component/earnings/pairedAdjustment.js.map +1 -0
- package/dist/component/earnings/triggers.d.ts +546 -2
- package/dist/component/earnings/triggers.d.ts.map +1 -1
- package/dist/component/earnings/triggers.js +17 -3
- package/dist/component/earnings/triggers.js.map +1 -1
- package/dist/component/financialObservations/continuation.d.ts +7 -0
- package/dist/component/financialObservations/continuation.d.ts.map +1 -0
- package/dist/component/financialObservations/continuation.js +131 -0
- package/dist/component/financialObservations/continuation.js.map +1 -0
- package/dist/component/financialObservations/generations.d.ts +6 -0
- package/dist/component/financialObservations/generations.d.ts.map +1 -0
- package/dist/component/financialObservations/generations.js +46 -0
- package/dist/component/financialObservations/generations.js.map +1 -0
- package/dist/component/financialObservations/mutations.d.ts +62 -0
- package/dist/component/financialObservations/mutations.d.ts.map +1 -0
- package/dist/component/financialObservations/mutations.js +69 -0
- package/dist/component/financialObservations/mutations.js.map +1 -0
- package/dist/component/financialObservations/queries.d.ts +307 -0
- package/dist/component/financialObservations/queries.d.ts.map +1 -0
- package/dist/component/financialObservations/queries.js +219 -0
- package/dist/component/financialObservations/queries.js.map +1 -0
- package/dist/component/financialObservations/schema.d.ts +182 -0
- package/dist/component/financialObservations/schema.d.ts.map +1 -0
- package/dist/component/financialObservations/schema.js +53 -0
- package/dist/component/financialObservations/schema.js.map +1 -0
- package/dist/component/financialObservations/settlement.d.ts +7 -0
- package/dist/component/financialObservations/settlement.d.ts.map +1 -0
- package/dist/component/financialObservations/settlement.js +118 -0
- package/dist/component/financialObservations/settlement.js.map +1 -0
- package/dist/component/financialObservations/settlementHelpers.d.ts +46 -0
- package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -0
- package/dist/component/financialObservations/settlementHelpers.js +70 -0
- package/dist/component/financialObservations/settlementHelpers.js.map +1 -0
- package/dist/component/financialObservations/transferBatches.d.ts +12 -0
- package/dist/component/financialObservations/transferBatches.d.ts.map +1 -0
- package/dist/component/financialObservations/transferBatches.js +76 -0
- package/dist/component/financialObservations/transferBatches.js.map +1 -0
- package/dist/component/financialObservations/transferContinuation.d.ts +5 -0
- package/dist/component/financialObservations/transferContinuation.d.ts.map +1 -0
- package/dist/component/financialObservations/transferContinuation.js +35 -0
- package/dist/component/financialObservations/transferContinuation.js.map +1 -0
- package/dist/component/financialObservations/transferContinuationState.d.ts +8 -0
- package/dist/component/financialObservations/transferContinuationState.d.ts.map +1 -0
- package/dist/component/financialObservations/transferContinuationState.js +69 -0
- package/dist/component/financialObservations/transferContinuationState.js.map +1 -0
- package/dist/component/financialObservations/transferContinuationSteps.d.ts +5 -0
- package/dist/component/financialObservations/transferContinuationSteps.d.ts.map +1 -0
- package/dist/component/financialObservations/transferContinuationSteps.js +174 -0
- package/dist/component/financialObservations/transferContinuationSteps.js.map +1 -0
- package/dist/component/financialObservations/transferHelpers.d.ts +18 -0
- package/dist/component/financialObservations/transferHelpers.d.ts.map +1 -0
- package/dist/component/financialObservations/transferHelpers.js +37 -0
- package/dist/component/financialObservations/transferHelpers.js.map +1 -0
- package/dist/component/financialObservations/transferReferenceSchema.d.ts +56 -0
- package/dist/component/financialObservations/transferReferenceSchema.d.ts.map +1 -0
- package/dist/component/financialObservations/transferReferenceSchema.js +21 -0
- package/dist/component/financialObservations/transferReferenceSchema.js.map +1 -0
- package/dist/component/financialObservations/transferSchema.d.ts +237 -0
- package/dist/component/financialObservations/transferSchema.d.ts.map +1 -0
- package/dist/component/financialObservations/transferSchema.js +65 -0
- package/dist/component/financialObservations/transferSchema.js.map +1 -0
- package/dist/component/financialObservations/transfers.d.ts +7 -0
- package/dist/component/financialObservations/transfers.d.ts.map +1 -0
- package/dist/component/financialObservations/transfers.js +79 -0
- package/dist/component/financialObservations/transfers.js.map +1 -0
- package/dist/component/financialOwnership/helpers.d.ts +37 -0
- package/dist/component/financialOwnership/helpers.d.ts.map +1 -0
- package/dist/component/financialOwnership/helpers.js +76 -0
- package/dist/component/financialOwnership/helpers.js.map +1 -0
- package/dist/component/financialOwnership/mutations.d.ts +28 -0
- package/dist/component/financialOwnership/mutations.d.ts.map +1 -0
- package/dist/component/financialOwnership/mutations.js +74 -0
- package/dist/component/financialOwnership/mutations.js.map +1 -0
- package/dist/component/financialOwnership/queries.d.ts +57 -0
- package/dist/component/financialOwnership/queries.d.ts.map +1 -0
- package/dist/component/financialOwnership/queries.js +50 -0
- package/dist/component/financialOwnership/queries.js.map +1 -0
- package/dist/component/financialOwnership/schema.d.ts +140 -0
- package/dist/component/financialOwnership/schema.d.ts.map +1 -0
- package/dist/component/financialOwnership/schema.js +35 -0
- package/dist/component/financialOwnership/schema.js.map +1 -0
- package/dist/component/operationEvidence/canonical.d.ts +4 -0
- package/dist/component/operationEvidence/canonical.d.ts.map +1 -0
- package/dist/component/operationEvidence/canonical.js +8 -0
- package/dist/component/operationEvidence/canonical.js.map +1 -0
- package/dist/component/operationEvidence/helpers.d.ts +87 -0
- package/dist/component/operationEvidence/helpers.d.ts.map +1 -0
- package/dist/component/operationEvidence/helpers.js +49 -0
- package/dist/component/operationEvidence/helpers.js.map +1 -0
- package/dist/component/operationEvidence/maintenance.d.ts +88 -0
- package/dist/component/operationEvidence/maintenance.d.ts.map +1 -0
- package/dist/component/operationEvidence/maintenance.js +59 -0
- package/dist/component/operationEvidence/maintenance.js.map +1 -0
- package/dist/component/operationEvidence/mutations.d.ts +97 -0
- package/dist/component/operationEvidence/mutations.d.ts.map +1 -0
- package/dist/component/operationEvidence/mutations.js +14 -0
- package/dist/component/operationEvidence/mutations.js.map +1 -0
- package/dist/component/operationEvidence/queries.d.ts +205 -0
- package/dist/component/operationEvidence/queries.d.ts.map +1 -0
- package/dist/component/operationEvidence/queries.js +75 -0
- package/dist/component/operationEvidence/queries.js.map +1 -0
- package/dist/component/operationEvidence/schema.d.ts +536 -0
- package/dist/component/operationEvidence/schema.d.ts.map +1 -0
- package/dist/component/operationEvidence/schema.js +53 -0
- package/dist/component/operationEvidence/schema.js.map +1 -0
- package/dist/component/refundHistory/commandBinding.d.ts +17 -0
- package/dist/component/refundHistory/commandBinding.d.ts.map +1 -0
- package/dist/component/refundHistory/commandBinding.js +41 -0
- package/dist/component/refundHistory/commandBinding.js.map +1 -0
- package/dist/component/refundHistory/commandEvidence.d.ts +50 -0
- package/dist/component/refundHistory/commandEvidence.d.ts.map +1 -0
- package/dist/component/refundHistory/commandEvidence.js +58 -0
- package/dist/component/refundHistory/commandEvidence.js.map +1 -0
- package/dist/component/refundHistory/commandEvidenceValidator.d.ts +89 -0
- package/dist/component/refundHistory/commandEvidenceValidator.d.ts.map +1 -0
- package/dist/component/refundHistory/commandEvidenceValidator.js +8 -0
- package/dist/component/refundHistory/commandEvidenceValidator.js.map +1 -0
- package/dist/component/refundHistory/commandFields.d.ts +8 -0
- package/dist/component/refundHistory/commandFields.d.ts.map +1 -0
- package/dist/component/refundHistory/commandFields.js +9 -0
- package/dist/component/refundHistory/commandFields.js.map +1 -0
- package/dist/component/refundHistory/mutations.d.ts +8 -0
- package/dist/component/refundHistory/mutations.d.ts.map +1 -0
- package/dist/component/refundHistory/mutations.js +25 -0
- package/dist/component/refundHistory/mutations.js.map +1 -0
- package/dist/component/refundHistory/originalSeller.d.ts +5 -0
- package/dist/component/refundHistory/originalSeller.d.ts.map +1 -0
- package/dist/component/refundHistory/originalSeller.js +35 -0
- package/dist/component/refundHistory/originalSeller.js.map +1 -0
- package/dist/component/refundHistory/queries.d.ts +51 -0
- package/dist/component/refundHistory/queries.d.ts.map +1 -1
- package/dist/component/refundHistory/queries.js +14 -0
- package/dist/component/refundHistory/queries.js.map +1 -1
- package/dist/component/schema.d.ts +332 -1
- package/dist/component/schema.js +15 -0
- package/dist/component/schema.js.map +1 -1
- package/dist/component/settlement/mutations.d.ts.map +1 -1
- package/dist/component/settlement/mutations.js +5 -1
- package/dist/component/settlement/mutations.js.map +1 -1
- package/dist/shared/refundCommandScope.d.ts +10 -0
- package/dist/shared/refundCommandScope.d.ts.map +1 -0
- package/dist/shared/refundCommandScope.js +9 -0
- package/dist/shared/refundCommandScope.js.map +1 -0
- package/docs/financial-observations.md +244 -0
- package/docs/financial-ownership.md +54 -0
- package/docs/refund-command-evidence.md +55 -0
- package/package.json +5 -2
- package/src/client/connect/refundCommandEvidence.ts +41 -0
- package/src/client/connect/refundCommandNormalization.ts +28 -0
- package/src/client/financialObservations.test.ts +109 -0
- package/src/client/financialObservations.ts +106 -0
- package/src/client/financialOwnership.test.ts +80 -0
- package/src/client/financialOwnership.ts +116 -0
- package/src/client/index.ts +2 -2
- package/src/client/observationPagination.ts +11 -0
- package/src/client/operationEvidence.test.ts +110 -0
- package/src/client/operationEvidence.ts +92 -0
- package/src/client/publicTypes.ts +45 -0
- package/src/client/readContracts.ts +25 -0
- package/src/client/refund-command-evidence.test.ts +68 -0
- package/src/client/refund-command-normalization.test.ts +61 -0
- package/src/client/transferContinuation.test.ts +94 -0
- package/src/client/transferObservations.test.ts +98 -0
- package/src/client/transferObservations.ts +180 -0
- package/src/component/_generated/api.ts +54 -0
- package/src/component/_generated/component.ts +797 -0
- package/src/component/affiliateRecovery/mutations.ts +10 -1
- package/src/component/connect/mutations.ts +29 -2
- package/src/component/connect/reversalClaims.ts +19 -1
- package/src/component/connect/reversalReceipts.ts +2 -0
- package/src/component/connect/schema.ts +9 -1
- package/src/component/connect/validators.ts +2 -0
- package/src/component/core/reset.test.ts +8 -1
- package/src/component/earnings/earnings-totals.test.ts +14 -10
- package/src/component/earnings/paired-adjustment.test.ts +258 -0
- package/src/component/earnings/pairedAdjustment.ts +77 -0
- package/src/component/earnings/triggers.ts +23 -11
- package/src/component/financialObservations/continuation.test.ts +445 -0
- package/src/component/financialObservations/continuation.ts +159 -0
- package/src/component/financialObservations/generations.ts +53 -0
- package/src/component/financialObservations/mutations.ts +75 -0
- package/src/component/financialObservations/observation-boundaries.test.ts +466 -0
- package/src/component/financialObservations/queries.ts +246 -0
- package/src/component/financialObservations/schema.ts +68 -0
- package/src/component/financialObservations/settlement-observations.test.ts +86 -0
- package/src/component/financialObservations/settlement.ts +142 -0
- package/src/component/financialObservations/settlementHelpers.ts +92 -0
- package/src/component/financialObservations/transfer-batches.test.ts +61 -0
- package/src/component/financialObservations/transfer-boundaries.test.ts +116 -0
- package/src/component/financialObservations/transfer-continuation-guards.test.ts +428 -0
- package/src/component/financialObservations/transfer-continuation.test.ts +154 -0
- package/src/component/financialObservations/transfer-observations.test.ts +212 -0
- package/src/component/financialObservations/transfer-overflow.test.ts +181 -0
- package/src/component/financialObservations/transfer-writers.test.ts +162 -0
- package/src/component/financialObservations/transferBatches.ts +96 -0
- package/src/component/financialObservations/transferContinuation.ts +53 -0
- package/src/component/financialObservations/transferContinuationState.ts +85 -0
- package/src/component/financialObservations/transferContinuationSteps.ts +232 -0
- package/src/component/financialObservations/transferHelpers.ts +38 -0
- package/src/component/financialObservations/transferReferenceSchema.ts +20 -0
- package/src/component/financialObservations/transferSchema.ts +74 -0
- package/src/component/financialObservations/transfers.ts +99 -0
- package/src/component/financialOwnership/financial-ownership.test.ts +102 -0
- package/src/component/financialOwnership/helpers.ts +98 -0
- package/src/component/financialOwnership/mutations.ts +83 -0
- package/src/component/financialOwnership/ownership-boundaries.test.ts +308 -0
- package/src/component/financialOwnership/queries.ts +65 -0
- package/src/component/financialOwnership/schema.ts +35 -0
- package/src/component/operationEvidence/canonical.ts +10 -0
- package/src/component/operationEvidence/helpers.ts +65 -0
- package/src/component/operationEvidence/integrity.test.ts +257 -0
- package/src/component/operationEvidence/maintenance.test.ts +152 -0
- package/src/component/operationEvidence/maintenance.ts +89 -0
- package/src/component/operationEvidence/mutations.ts +14 -0
- package/src/component/operationEvidence/queries.ts +108 -0
- package/src/component/operationEvidence/reads.test.ts +140 -0
- package/src/component/operationEvidence/schema.ts +62 -0
- package/src/component/refundHistory/command-evidence.test.ts +288 -0
- package/src/component/refundHistory/command-normalization-resource.test.ts +77 -0
- package/src/component/refundHistory/command-normalization.test.ts +229 -0
- package/src/component/refundHistory/command-provenance.test.ts +59 -0
- package/src/component/refundHistory/commandBinding.ts +54 -0
- package/src/component/refundHistory/commandEvidence.ts +76 -0
- package/src/component/refundHistory/commandEvidenceValidator.ts +18 -0
- package/src/component/refundHistory/commandFields.ts +9 -0
- package/src/component/refundHistory/mutations.ts +33 -0
- package/src/component/refundHistory/original-seller-boundaries.test.ts +138 -0
- package/src/component/refundHistory/original-seller.test.ts +175 -0
- package/src/component/refundHistory/originalSeller.ts +48 -0
- package/src/component/refundHistory/queries.ts +15 -0
- package/src/component/schema.ts +28 -0
- package/src/component/settlement/mutations.ts +5 -1
- package/src/shared/refundCommandScope.ts +19 -0
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# Settlement source observations
|
|
2
|
+
|
|
3
|
+
`betterStripe.financialObservations` exposes trusted host diagnostics for original settlement allocation sources and destinations. It records references and fingerprints, not a second financial ledger. Every response reports `coverage: "unknown"`; a registered owner, indexed destination or exhausted page never proves the absence of outstanding work or authorizes account closure.
|
|
4
|
+
|
|
5
|
+
## Observed producer and bounds
|
|
6
|
+
|
|
7
|
+
The version 1 producer is the actual raw-context `reserveSettlementAllocation` mutation. Its transaction records the original allocation ID, charge identity, immutable source fingerprint and diagnostic generation. Matching reservation replay observes the original persisted allocation, preserving existing financial behavior when caller amounts differ. No source row, amount, balance, claim or provider request is rewritten by observation.
|
|
8
|
+
|
|
9
|
+
At most **100 destination legs** are indexed synchronously. Within that bound, each leg retains its original allocation ID, leg index, destination key and role. An allocation with more than 100 legs remains financially valid and records a durable `isOverflow: true` source marker with UNKNOWN coverage and no synchronous destination rows. The marker retains the original allocation reference and total leg count. The trusted host can explicitly resume oversized traversal in bounded transactions. No capped list is described as complete. An allocation with no legs records an empty source marker without inventing a recipient.
|
|
10
|
+
|
|
11
|
+
Existing allocations have no automatic legacy backfill. A missing source observation remains unknown until an actual reservation replay observes it. Transfer fact writers, claimed reversal slices, affiliate/seller-cost/payout producers, legacy backfill, attempt admission and whole-V2 host purchase/configuration/consent guards require separate accepted integrations. This feature does not make account closure safe or activate a close control.
|
|
12
|
+
|
|
13
|
+
## Ownership and late facts
|
|
14
|
+
|
|
15
|
+
Leg ownership comes only from the exact immutable financial ownership registry binding. No user is inferred from destination spelling, provider mapping, account creation time or a caller-supplied alias. An unregistered bucket is indexed with `ownershipStatus: "unknown"`, without an owner. For synchronous allocations, a later legitimate first registration becomes visible when the actual source writer replays. Pending oversized continuation can observe it when validation reaches that slot. A completed traversal remains historical; none of these observations certifies complete coverage.
|
|
16
|
+
|
|
17
|
+
Once observed, a registered leg keeps its original owner pin through registry absence, ambiguity or contradictory replacement. Historical destination rows never redirect to a replacement owner. Missing registration yields unknown ownership, duplicate registration yields ambiguous ownership, and changed ownership yields contradictory ownership. Source identity conflicts, duplicate charge sources and changed original financial source content retain an explicit contradictory source marker. Missing previously indexed slots, duplicate slots and malformed observation slots are held before selecting any leg: index, original destination, role and source-charge identity must agree. Ambiguous observation rows are retained unchanged, with a contradictory source marker rather than a silent repair. Contradictions are held rather than repaired by rewriting financial facts.
|
|
18
|
+
|
|
19
|
+
Source generations advance when source or ownership observations change. Matching replay remains stable, including repeated contradictory facts. Exact-bucket and owner diagnostic generations advance for affected indexed scopes; they are diagnostic invalidation tokens, not certified financial coverage. A missing scope starts at generation zero; an ambiguous or invalid generation is returned as null. Overflow destinations that have not been indexed cannot be discovered through those scope indexes, which is why UNKNOWN must be preserved until and after those destinations are indexed.
|
|
20
|
+
|
|
21
|
+
## Server integration
|
|
22
|
+
|
|
23
|
+
Authenticate the current host actor and derive the allowed owner/bucket scope before calling these readers. They are trusted component/server APIs: a bucket key, allocation ID, user identifier or cursor is not end-user authorization. Keep organization scope explicit rather than inheriting organization history into personal queries.
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
const diagnostic = await betterStripe.financialObservations.source(ctx, {
|
|
27
|
+
allocationId: originalAllocationId,
|
|
28
|
+
});
|
|
29
|
+
const destinations = await betterStripe.financialObservations.bucket(ctx, {
|
|
30
|
+
bucketKey: authorizedBucketKey,
|
|
31
|
+
paginationOpts: { numItems: 25, cursor: previousCursor },
|
|
32
|
+
});
|
|
33
|
+
const ownerSources = await betterStripe.financialObservations.owner(ctx, {
|
|
34
|
+
userId: authenticatedOwnerId,
|
|
35
|
+
paginationOpts: { numItems: 25, cursor: previousCursor },
|
|
36
|
+
});
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Bucket/owner readers use exact indexed pagination, request sizes 1–100, fixed 200-row/1 MB read bounds and native continuation/split metadata. Preserve `continueCursor`, `isDone` and native pagination identity. A full final page may require an empty continuation. Cursors are scoped to the authorized query and do not establish an immutable snapshot. All pages, including empty/exhausted pages, remain UNKNOWN; there is no caller complete flag or closure-readiness API.
|
|
40
|
+
|
|
41
|
+
## Explicit oversized continuation
|
|
42
|
+
|
|
43
|
+
After observing an oversized allocation, call `financialObservations.resume` with its current diagnostic generation. Each transaction indexes at most 100 original destination slots, then advances a durable cursor atomically with those rows. Once every original slot is indexed, subsequent calls advance validation by at most 100 stored slots per transaction, with one indexed lookahead row. Only an actual end-of-source validation marks `continuation.state` as `"complete"`. `isOverflow` remains true because the original allocation exceeded the synchronous bound.
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
const result = await betterStripe.financialObservations.resume(ctx, {
|
|
47
|
+
allocationId: authorizedOriginalAllocationId,
|
|
48
|
+
expectedGeneration: diagnostic.observation.generation,
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The host must authorize the allocation and explicitly drain both phases, persisting or rereading the returned generation between calls. There is no implicit scheduler, automatic legacy discovery or fixed lifetime batch limit. A lost acknowledgement can replay the same generation safely: it returns the current diagnostic without advancing another batch. A transaction failure commits neither destination rows nor cursor progress. The source reader supplies durable progress after a host restart.
|
|
53
|
+
|
|
54
|
+
A missing or duplicate marker returns a null UNKNOWN observation. Changed original financial content, ambiguous charge identity and structurally inconsistent cursors hold the traversal with `isContradictory: true`. The validation pass holds when its current indexed page contains missing, duplicate or malformed slots. Existing ambiguous rows are preserved; continuation never repairs them by recreating an owner pin. Previously observed owners remain pinned through registry absence or replacement. Validation can update their diagnostic ownership status without redirecting historical rows.
|
|
55
|
+
|
|
56
|
+
The integrity boundary is the package-owned writers. They append destination slots and patch diagnostic ownership, advancing the source generation in the same transaction. They never selectively delete slots or change a committed slot's identity. Validation advances over that stable prefix in separate transactions. A privileged database edit that deletes an already validated prefix or forges an otherwise consistent completed marker bypasses this writer/generation contract; this API does not certify arbitrary database-tamper integrity or rescan the entire prefix on every call.
|
|
57
|
+
|
|
58
|
+
Completion describes a historical validated traversal of this one original allocation, not a fresh ownership snapshot. A first ownership registration arriving after its slot was validated, or after completion, does not automatically rewrite that historical observation. Neither completion nor its ownership statuses certify current ownership or current liabilities. It does not prove complete financial ownership, absence of liabilities, complete producer coverage or completed legacy backfill. The host must stop on held/null results and handle recovery explicitly. Every response, including a completed traversal, still reports `coverage: "unknown"`. Source allocations, destination amounts and provider operations remain untouched.
|
|
59
|
+
|
|
60
|
+
## Verification boundary
|
|
61
|
+
|
|
62
|
+
Real-schema tests exercise raw-context reservation, persisted-original replay, late observations, source/owner contradictions, organization isolation, more than one page, empty allocations and allocations over the synchronous bound. Public SDK tests dispatch into the actual component without Stripe credentials. Native evidence uses an isolated local component. These tests perform no provider financial operations, closure, payout, settlement transfer or admission fencing.
|
|
63
|
+
|
|
64
|
+
## Transfer facts and deferred batches
|
|
65
|
+
|
|
66
|
+
`stripe.financialObservations.transfer(ctx, { transferId })` reads one exact
|
|
67
|
+
component transfer document reference. `transferBucket` and `transferOwner`
|
|
68
|
+
paginate the original destination and trusted registered owner. Personal and
|
|
69
|
+
organization scopes stay separate. `transferBatches` paginates one exact
|
|
70
|
+
operation identifier. All four readers always return `coverage: "unknown"`.
|
|
71
|
+
The host must authorize each selector before exposing these server APIs.
|
|
72
|
+
|
|
73
|
+
The package records transfer observations atomically with Connect upserts,
|
|
74
|
+
confirmed reversal receipts, affiliate recovery/restoration, claim-frontier
|
|
75
|
+
updates and releases. Derived earnings backfill also observes its stored fact.
|
|
76
|
+
Original transfer, source, destination and first registered owner references stay
|
|
77
|
+
pinned. Matching observations replay without advancing their generation; later
|
|
78
|
+
financial facts advance it. Missing or ambiguous ownership stays unknown.
|
|
79
|
+
Contradictory original identity remains diagnostic and never repairs a monetary
|
|
80
|
+
row. Only the derived `totalsRecorded` flag is excluded from the financial
|
|
81
|
+
fingerprint. Metadata and other persisted financial fields are included.
|
|
82
|
+
|
|
83
|
+
Claim and release batches synchronously observe at most 100 affected transfers.
|
|
84
|
+
Larger financial operations still process their complete existing slices. In the
|
|
85
|
+
same transaction they retain a pending batch with the original operation document
|
|
86
|
+
reference, source charge, producer/version, fingerprint/generation and every
|
|
87
|
+
compact original transfer document reference. The two producer kinds are
|
|
88
|
+
`transfer_frontier_claim` and `transfer_frontier_release`. A release can delete its
|
|
89
|
+
original operation while its reference and deferred transfer references survive.
|
|
90
|
+
These records contain provenance, not another monetary ledger. Trusted hosts
|
|
91
|
+
explicitly drain them through the bounded continuation API below.
|
|
92
|
+
|
|
93
|
+
Every transfer reader includes `producerGeneration` and `hasDeferredWork`.
|
|
94
|
+
Pending batches invalidate any inference that an older owner or destination page
|
|
95
|
+
reflects the latest batch. Exhausting a page does not clear pending work or prove
|
|
96
|
+
complete financial history. Missing legacy observations and producer versions
|
|
97
|
+
remain unknown. A completed historical observation never certifies current
|
|
98
|
+
ownership, current liabilities or account-closure eligibility. Initial ownership
|
|
99
|
+
registration after an observation does not automatically refresh it.
|
|
100
|
+
|
|
101
|
+
Native checks preserve the previously supported 1,000-transfer claim across four
|
|
102
|
+
shared destination buckets, with registered personal/organization and unknown
|
|
103
|
+
ownership, and the 100-transfer synchronous boundary. Historical public claims
|
|
104
|
+
with 1,001 transfers can still be released without per-row observation work.
|
|
105
|
+
The accepted baseline separately exceeds native read limits for a claim with
|
|
106
|
+
1,000 distinct destinations because of existing earnings-summary work; this
|
|
107
|
+
observation contract does not fix or claim support for that shape.
|
|
108
|
+
|
|
109
|
+
Observations rely on package-owned append/patch writers and their transactional
|
|
110
|
+
generation changes. They do not certify arbitrary privileged database edits,
|
|
111
|
+
selective deletion of historical observations or forged diagnostic markers.
|
|
112
|
+
No provider operation, financial-attempt admission or positive closure clearance
|
|
113
|
+
is part of this contract.
|
|
114
|
+
|
|
115
|
+
## Resume every retained transfer reference
|
|
116
|
+
|
|
117
|
+
Use `stripe.financialObservations.transferBatch(ctx, { batchId })` to read an
|
|
118
|
+
exact marker, then call `resumeTransferBatch(ctx, { batchId, expectedGeneration })`
|
|
119
|
+
with its returned generation. One transaction indexes at most 50 original
|
|
120
|
+
transfer document references or validates at most 50 committed reference receipts.
|
|
121
|
+
Repeat until the marker reports historical completion or a held cursor. Callers
|
|
122
|
+
never supply cursor state or a complete flag. A stale acknowledgement returns the
|
|
123
|
+
current marker without advancing twice. There is no fixed lifetime reference cap.
|
|
124
|
+
The original financial operation and every retained reference stay intact.
|
|
125
|
+
|
|
126
|
+
`transferReferences(ctx, { batchId, paginationOpts })` exposes compact provenance
|
|
127
|
+
receipts through exact indexed pagination, up to 100 rows per page. Preserve native
|
|
128
|
+
cursor, split and page-status metadata. Receipts hold original transfer and
|
|
129
|
+
observation references, position, generation and fingerprints. They contain no
|
|
130
|
+
duplicated amounts. A successful final pass checks every retained slot and its
|
|
131
|
+
actual source/observation before the marker leaves pending state. Missing or
|
|
132
|
+
duplicate sources, ambiguous provenance, contradictory identities, cursor drift
|
|
133
|
+
and supersession hold the marker with UNKNOWN coverage rather than recreate or
|
|
134
|
+
repin history. Both claim and release markers use this same protocol, including
|
|
135
|
+
releases whose original operation document was deleted.
|
|
136
|
+
|
|
137
|
+
Each active cursor binds immutable marker source/version/fingerprint and the
|
|
138
|
+
global transfer-producer generation. Its own indexing writes and checkpoint
|
|
139
|
+
commit atomically. A financial write between commits holds the cursor without
|
|
140
|
+
resetting or silently accepting a previously validated prefix. This conservative
|
|
141
|
+
global fence can also hold traversal after an unrelated transfer changes; it is
|
|
142
|
+
not an availability guarantee under continuous writes. Held references remain
|
|
143
|
+
pending, with no automatic restart or closure permission.
|
|
144
|
+
|
|
145
|
+
Existing registered owner pins and explicitly unregistered ownership snapshots
|
|
146
|
+
survive traversal. A late first registration does not repin an already unknown
|
|
147
|
+
observation. A legacy transfer's first observation may bind its current trusted
|
|
148
|
+
registration, but that is not proof of who historically owned the original sale.
|
|
149
|
+
Completed traversals remain historical after later financial or ownership facts.
|
|
150
|
+
They never certify fresh ownership, current liabilities, complete financial
|
|
151
|
+
coverage or safe account closure. Aggregate coverage always remains UNKNOWN.
|
|
152
|
+
|
|
153
|
+
The final pass relies on supported package-owned append/patch writers and atomic
|
|
154
|
+
generation invalidation. It does not certify arbitrary privileged marker forgery
|
|
155
|
+
or deletion of an already validated prefix. The native capacity proof drains every
|
|
156
|
+
reference from an actual old-public 1,001-transfer claim/release and a current
|
|
157
|
+
1,000-transfer mixed-owner claim across separate committed calls, while retaining
|
|
158
|
+
all financial rows and amounts. No provider operation or financial-attempt
|
|
159
|
+
admission is part of this continuation API.
|
|
160
|
+
|
|
161
|
+
## Lossless operation evidence maintenance
|
|
162
|
+
|
|
163
|
+
`stripe.operationEvidence` is explicit trusted-host maintenance for actual
|
|
164
|
+
persisted reversal-operation documents. Authenticate the host actor and derive
|
|
165
|
+
the authorized source document before calling it. A source ID, selector, digest
|
|
166
|
+
or cursor is not end-user authorization. The host selects an existing document;
|
|
167
|
+
it cannot supply invented financial bytes.
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
const observed = await stripe.operationEvidence.capture(ctx, {
|
|
171
|
+
sourceId: authorizedPersistedOperation._id,
|
|
172
|
+
});
|
|
173
|
+
const page = await stripe.operationEvidence.headers(ctx, {
|
|
174
|
+
paginationOpts: { numItems: 25, cursor: previousCursor },
|
|
175
|
+
});
|
|
176
|
+
if (observed.header) {
|
|
177
|
+
const original = await stripe.operationEvidence.original(ctx, {
|
|
178
|
+
headerId: observed.header._id,
|
|
179
|
+
});
|
|
180
|
+
const latestObserved = await stripe.operationEvidence.latest(ctx, {
|
|
181
|
+
headerId: observed.header._id,
|
|
182
|
+
});
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Original means the first trusted observation, not provider creation or
|
|
187
|
+
historical owner proof. Separate headerless documents retain the exact admitted
|
|
188
|
+
source fields for original and latest observed data. Compact headers retain the
|
|
189
|
+
original source reference, first-observed provenance, fingerprints and
|
|
190
|
+
generation. Payload documents add no annotation or duplicated exposure envelope:
|
|
191
|
+
a legal source can already be exactly the native 1 MiB document limit. Canonical
|
|
192
|
+
Convex encoding preserves special floats, optional presence and array order
|
|
193
|
+
while normalizing recursive object-key order.
|
|
194
|
+
|
|
195
|
+
Stable maintenance replay changes no evidence generation. Changed source data
|
|
196
|
+
updates the latest observed payload and global operation generation atomically;
|
|
197
|
+
original data and identity never redirect. Contradictory original identity stays
|
|
198
|
+
explicit, with actual latest bytes retained. Deletion after observation does not
|
|
199
|
+
erase the retained payloads. A source missing before observation creates no
|
|
200
|
+
evidence. Missing or damaged evidence is not silently recreated.
|
|
201
|
+
|
|
202
|
+
Header pages contain compact references only, up to 100 per request with fixed
|
|
203
|
+
read bounds. They never fan out to payloads. Original and latest hydration are
|
|
204
|
+
separate one-payload reads. `resolve(ctx, { selector, value })` accepts either
|
|
205
|
+
`operationId` or `sourceChargeId`, without narrowing admitted financial strings.
|
|
206
|
+
It reads at most two compact digest candidates and hydrates only one unique
|
|
207
|
+
original payload to verify raw selector equality. Missing, reused, colliding or
|
|
208
|
+
otherwise ambiguous selectors return a null header and UNKNOWN. A source charge
|
|
209
|
+
with multiple observed operations is ambiguous for this unique resolver; it is
|
|
210
|
+
not an exact-scope page. There is no full-payload fallback scan or repin.
|
|
211
|
+
|
|
212
|
+
Every response reports `coverage: "unknown"` and the current maintenance
|
|
213
|
+
`evidenceGeneration`. This is the current maintenance-evidence generation only.
|
|
214
|
+
Latest means latest **observed** data. Financial claim,
|
|
215
|
+
release and exposure writers do not invoke this maintenance automatically.
|
|
216
|
+
Changes that have not been explicitly captured therefore need not change its
|
|
217
|
+
generation. No drained-page or source-generation token certifies complete
|
|
218
|
+
history, current financial state, liabilities, ownership or closure readiness.
|
|
219
|
+
|
|
220
|
+
Maintenance is atomic and can abort at native aggregate read/write or rate
|
|
221
|
+
limits. It does not change financial source rows, swallow a resource abort as
|
|
222
|
+
success, or promise unlimited backlog capacity. Per-document lossless storage
|
|
223
|
+
does not prove that adding future hooks preserves aggregate financial
|
|
224
|
+
transaction capacity. That requires separate baseline-versus-hook measurement
|
|
225
|
+
before lifecycle integration. No financial writer hooks, destination/owner slice
|
|
226
|
+
index, provider operations, admission fence or automatic backfill is included.
|
|
227
|
+
Lifecycle/frontier integrations need separate raw-writer hooks and both financial
|
|
228
|
+
fact and evidence invalidators before claiming destination or owner coverage.
|
|
229
|
+
|
|
230
|
+
## Same-bucket earnings summary updates
|
|
231
|
+
|
|
232
|
+
When a transfer stays in the same destination and currency, its derived earnings
|
|
233
|
+
update reads the unique summary once. It still validates subtraction, zero-count
|
|
234
|
+
reset/reapplication and safe integer/net arithmetic before deciding whether to
|
|
235
|
+
persist the result. Only an exactly unchanged existing nonzero summary can avoid
|
|
236
|
+
a final patch; zero-count deletion and malformed-summary errors remain required.
|
|
237
|
+
Moved buckets, unrecorded transfers, payout summaries and financial/risk callbacks
|
|
238
|
+
retain their existing behavior.
|
|
239
|
+
|
|
240
|
+
This is a private derived-summary optimization. Accepted and earnings-only
|
|
241
|
+
candidates still exceed the native read limit for 1,000 distinct destinations.
|
|
242
|
+
It does not lower the admitted financial maximum, establish complete observation
|
|
243
|
+
coverage or prove aggregate financial-hook capacity. Distinct-destination source
|
|
244
|
+
read reuse and complete capacity verification remain separate work.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Financial bucket ownership provenance
|
|
2
|
+
|
|
3
|
+
`betterStripe.financialOwnership` records immutable host ownership of a financial bucket. It supports physical Stripe account keys and opaque logical keys, including affiliate earnings that have no provider account yet. This is provenance, not a second money ledger. Registration does not rewrite source keys, amounts, balances, transfers or payout history.
|
|
4
|
+
|
|
5
|
+
All registration, lookup and discovery responses report `coverage: "unknown"`. Exhausting discovery means only that the registered ownership rows for that exact scope were enumerated. It does not establish complete financial history, absence of outstanding work, current provider usability or permission to close an account. No API accepts a `complete` flag. Source observations, legacy backfill, financial attempt admission and host business-policy guards require separate accepted integrations.
|
|
6
|
+
|
|
7
|
+
## Trusted host boundary
|
|
8
|
+
|
|
9
|
+
Call this API only from an authorized server adapter. Authenticate the current host actor and derive its allowed owner scope before supplying `userId` and optional `orgId`. Neither a bucket key, cursor nor a claimed user identifier is authorization. Component lookup intentionally returns provenance for a trusted host; do not expose it as an unrestricted browser query.
|
|
10
|
+
|
|
11
|
+
For a new physical registration, the component verifies exact current reciprocal mapping through the unique personal resolver or bounded organization-scope proof. A historical registration requires one exact closed-account owner record. Duplicate mappings, duplicate closure records, foreign ownership, unresolved closure, ownerless history and malformed provider keys refuse registration. Pending capability/KYC is unrelated to ownership and is not interpreted as readiness.
|
|
12
|
+
|
|
13
|
+
Logical ownership is a host-domain fact. Before registering it, the host must verify the actual immutable source record and its owner, then supply its stable integration and record identity. Arbitrary key spelling such as `user:123` or `acct_example` never implies ownership. A proof reference records the host's verified source; it alone does not establish coverage. Unverified legacy keys remain unknown. An absent host migration/integration cannot be replaced with a guessed alias list or account timestamp.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
// Server only, after current-actor authorization and actual source-owner verification.
|
|
17
|
+
await betterStripe.financialOwnership.register(ctx, {
|
|
18
|
+
bucketKey: source.financialBucketKey,
|
|
19
|
+
kind: "logical",
|
|
20
|
+
userId: source.verifiedOwnerUserId,
|
|
21
|
+
source: {
|
|
22
|
+
integration: "host-affiliate-registration-v1",
|
|
23
|
+
recordId: source.id,
|
|
24
|
+
},
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
// Server-derived personal account selector; physical proof is component-owned.
|
|
28
|
+
await betterStripe.financialOwnership.register(ctx, {
|
|
29
|
+
bucketKey: verifiedAccountId,
|
|
30
|
+
kind: "stripe_account",
|
|
31
|
+
userId: authenticatedOwnerId,
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Immutable receipts and bounded discovery
|
|
36
|
+
|
|
37
|
+
Exact-key lookup returns `status: "unknown"` for an unregistered bucket or `status: "registered"` with its immutable registration. Matching registration retries reuse the same receipt. Changing its owner, kind or logical source identity rejects atomically. A previously verified physical receipt survives closure and active mapping removal; replay returns original ownership provenance, not a fresh current-account or readiness assertion.
|
|
38
|
+
|
|
39
|
+
Owner scope is the exact `userId` and optional `orgId` tuple. Organization-owned registrations never appear in a personal discovery query, even when they retain the same user identifier. Hosts must authorize both selectors and retain historical organization context rather than inheriting it into personal ownership.
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
const page = await betterStripe.financialOwnership.discover(ctx, {
|
|
43
|
+
userId: authenticatedOwnerId,
|
|
44
|
+
paginationOpts: { numItems: 25, cursor: previousCursor },
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Pages use the component-compatible indexed paginator, at most 100 requested rows with fixed 200-row/1 MB read bounds. Preserve `continueCursor`, `isDone`, optional split metadata and native pagination identity. A full last page can require an empty continuation before `isDone` becomes true. Keep cursors scoped to the authorized owner query; a cursor is not an immutable snapshot.
|
|
49
|
+
|
|
50
|
+
The returned generation advances only when a new bucket is registered in that owner scope. Matching replay does not advance it. It is a registration provenance generation, not a financial revision. Registration itself has no financial writer observers. The separate [settlement source observations](./financial-observations.md) integration observes bounded raw allocation destinations only and has its own diagnostic generations; it does not establish complete financial coverage. Newly written or unmapped records outside that producer are still unobserved. No completeness claim is available at all.
|
|
51
|
+
|
|
52
|
+
## Verification boundary
|
|
53
|
+
|
|
54
|
+
Real-schema tests exercise current and closed ownership, explicit logical provenance, ambiguity/refusal, replay/conflict, organization isolation, pagination beyond 100 rows and unchanged financial records. Public SDK tests dispatch through the actual component without a Stripe secret. Native verification must use an isolated component runtime. These tests establish registration/discovery behavior only; they perform no provider closure, bank payout, settlement or live financial acceptance.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Refund-command evidence
|
|
2
|
+
|
|
3
|
+
The package provides a bounded component reader for an opaque host refund-command key. It observes synchronized refund records; it does not contact Stripe, prove provider absence, authorize a retry or certify completed money. Public artifact verification and host adoption are separate from source acceptance.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
const evidence = await stripe.getRefundCommandEvidence(ctx, {
|
|
7
|
+
commandKey: originalCommand.providerIdempotencyKey,
|
|
8
|
+
stripeAccountId: originalCommand.originalMerchantAccount,
|
|
9
|
+
stripePaymentIntentId: originalCommand.stripePaymentIntentId,
|
|
10
|
+
stripeChargeId: originalCommand.stripeChargeId,
|
|
11
|
+
currency: originalCommand.currency,
|
|
12
|
+
});
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Authenticate and authorize the host caller before this call. Derive every selector from the original immutable command and verified payment routing. Current community owners or replacement accounts must not remap old payments. The server-only [Vite reference](../example/convex/connect/refundCommandEvidence.ts) verifies a reciprocal unique personal mapping against the original account; demo personas are not authentication. The host still qualifies the original command fingerprint, buyer, invoice allocation, amount/reason, permission and lifecycle.
|
|
16
|
+
|
|
17
|
+
## Result and bounds
|
|
18
|
+
|
|
19
|
+
The result is either `observed` with the refund document or `unavailable` with a reason: `missing`, `normalization_incomplete`, `ambiguous`, `correlation_conflict`, `scope_mismatch` or `invalid_receipt`.
|
|
20
|
+
|
|
21
|
+
The reader first checks one indexed legacy normalization row, then reads at most two rows for the exact global command key and at most two for the candidate provider refund ID. Command-key duplicate detection precedes account/PI/charge/currency qualification; a foreign duplicate cannot be filtered into apparent uniqueness. Duplicated provider refund IDs under different command keys also remain ambiguous. A unique observed row must match the original scope and retain positive safe integer original units and a canonical refund ID. Pending, failed and succeeded states remain distinct. Currency shape validation does not establish supported currency or input precision; the host uses the public currency helpers and original-charge contract.
|
|
22
|
+
|
|
23
|
+
For a receipt whose persisted `accountId` is absent, the reader additionally reads at most two settlement allocations by the exact original charge. Exactly one allocation must have the original payment-intent ID and currency, exactly one store and canonical unique recipient accounts with safe nonnegative integer transfer amounts. Multiple allocations or stores, affiliate-only routing, missing original PI and malformed or duplicate destinations stay unavailable. The existing public allocation reservation inserts the original transfer routing once and returns it unchanged on compatible replay; changed PI, currency or invoice identity rejects. Current mutable payment routing never establishes original merchant provenance. A normal same-PI payment update to another store cannot remap the allocation's original store.
|
|
24
|
+
|
|
25
|
+
An explicitly persisted refund account is never replaced by this fallback, including an empty or foreign value. Existing persisted-account destination receipts retain their prior semantics. Payment-only ownerless legacy receipts and ownerless destination history without an immutable allocation remain unavailable: current routing cannot reconstruct unknown original merchant identity. There is no migration, first-read ownership pin or metadata-based ownership guess.
|
|
26
|
+
|
|
27
|
+
The fallback returns a qualified account only in the observed result; it does not patch the refund, allocation or payment, change historical account indexes, select current user/community account mappings or backfill old records. Original PI, charge, currency and command selectors still match the receipt and allocation. The host must retain verified original provider-charge, immutable merchant/command/fingerprint and authorization contracts. Existing ingestion seller heuristics and the bounded 100-row late owner backfill are unchanged. Ownerless records can therefore remain absent from account-filtered history while this exact reader qualifies their immutable original allocation. Bounds are on documents rather than routing bytes; a rejected native read never establishes observed evidence or retry authority.
|
|
28
|
+
|
|
29
|
+
`missing` is unknown synchronized evidence, never permission to create another refund. `observed` is also not financial completion or an assertion that every provider receipt has arrived. Reobserve when relevant data changes; the exact index discovers later inserts and metadata enrichment independently of a previously exhausted history cursor. Existing `paginateRefunds` retains its history semantics, including pinned cursors; a ten-page budget is per invocation, not a lifetime absence proof.
|
|
30
|
+
|
|
31
|
+
## Immutable correlation convention
|
|
32
|
+
|
|
33
|
+
Before the first provider execution, the host may put its existing stable opaque identity into `metadata.betterStripeRefundCommand` and its immutable fingerprint into a separate metadata field. For example, Dojo's already prepared identity `dojo-refund:<commandId>:v1` and original fingerprint can be reused without generating a replacement command or idempotency key. The package does not inject metadata or change `createRefund` parameters. Do not add this convention to an already prepared or executed provider payload if that would change parameters of a same-key replay; hold or reconcile such an older request under its actual original contract.
|
|
34
|
+
|
|
35
|
+
Command keys are 16–200 canonical ASCII letters, digits, colons, underscores or hyphens. They are correlation selectors, not credentials or authorization. Keep private data out of provider metadata. The host independently verifies the fingerprint and original terms; the reader does not equate matching metadata with permission.
|
|
36
|
+
|
|
37
|
+
Every current refund upsert normalizes existing metadata before applying incoming metadata. The first known key remains indexed. An omitted metadata field on a partial upsert adds no contradictory fact and preserves the binding. Explicitly present missing, invalid or different correlation metadata after a known binding latches a conflict, even if a later event restores the former raw metadata. Original raw provider fields are retained; correlation is a projection on the existing refund row, not another financial ledger.
|
|
38
|
+
|
|
39
|
+
`refundCommandObservedAt` is the time the normalizer first observed that binding. Neither it nor the row's insertion time proves original provider creation time. A legacy row's key is first-known component metadata, not a claim about what the original Stripe request contained. Unknown original request provenance remains the host's held reconciliation case.
|
|
40
|
+
|
|
41
|
+
## Legacy rollout hold
|
|
42
|
+
|
|
43
|
+
Any row without normalization version 1 keeps the reader unavailable globally. Otherwise an unindexed old metadata key plus an indexed newer duplicate could appear falsely unique. The indexed coverage hold is bounded and deliberately conservative, even for an unrelated legacy row.
|
|
44
|
+
|
|
45
|
+
Trusted host maintenance can drain the pending version index through `normalizeRefundCommandBindings(ctx, { limit })`, with an explicit integer limit from 1 to 100. Each transaction reads at most that many pending rows, patches only the reviewed correlation projection/version fields, then checks at most one remaining pending row. The result `{ normalized, hasMore }` reports this batch and current pending coverage. Processed rows leave the pending index, so repeat while `hasMore` is true without a full-history scan, cursor rewind or lifetime cap. Concurrent calls use Convex transactional conflict handling; a repeated call after drainage is an idempotent empty batch.
|
|
46
|
+
|
|
47
|
+
This global maintenance operation requires a trusted platform operator or internal deployment task. Never expose it to community sellers, demo personas or an unauthenticated browser. The [Vite maintenance reference](../example/convex/connect/refundCommandNormalization.ts) is deliberately an unregistered server helper. Host authentication and platform authorization must happen before calling it. Raw metadata, original account/PI/charge/currency/amount/status and financial fields remain unchanged; the same first-known-binding/conflict normalizer used by ingestion is reused. Rows without correlation become normalized unbound records; invalid reserved metadata latches a conflict. An old valid key plus an existing newer match becomes ambiguous after normalization, not falsely unique.
|
|
48
|
+
|
|
49
|
+
`hasMore: false` observes only the current trusted-writer component backlog at the transaction snapshot. It does not prove provider history is complete, prevent later legacy ingestion or authorize any refund request. A later pending row reactivates the reader’s global hold until another bounded drain. Current upserts can reobserve individual legacy rows with the same normalizer. Until all pending rows are normalized, this reader cannot report an observed unique match. Normalization coverage means only the current records written through the trusted component contract have been normalized. It does not establish complete historical Stripe ingestion, discover refunds never delivered to the component or authorize a provider retry.
|
|
50
|
+
|
|
51
|
+
## Native resource limits
|
|
52
|
+
|
|
53
|
+
The per-call limit bounds rows, not bytes. Large raw metadata can make a batch exceed native transaction read/write budgets even within the 100-row limit. Adding projection fields to an individual legacy document near the native document ceiling can also fail. This primitive does not promise capacity for every schema-legal legacy backlog.
|
|
54
|
+
|
|
55
|
+
A native failure rejects the mutation atomically: no partial normalization is committed and no completion result is returned. The unnormalized rows remain pending, so the exact reader stays held. A smaller limit can reduce batch bytes, but cannot solve an individual document ceiling. Keep that case held for investigation; do not skip/delete rows or rewrite raw metadata to manufacture completion. An empty native-dispatch check is not large-backlog capacity evidence.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fantastic.dev/better-stripe",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.37.0",
|
|
4
4
|
"description": "A Convex component for Stripe V2 Accounts API integration.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"stripe",
|
|
@@ -68,7 +68,10 @@
|
|
|
68
68
|
"docs/invoice-payment-pages.md",
|
|
69
69
|
"docs/checkout-session-pages.md",
|
|
70
70
|
"docs/refund-context.md",
|
|
71
|
-
"docs/
|
|
71
|
+
"docs/refund-command-evidence.md",
|
|
72
|
+
"docs/personal-account-mapping.md",
|
|
73
|
+
"docs/financial-ownership.md",
|
|
74
|
+
"docs/financial-observations.md"
|
|
72
75
|
],
|
|
73
76
|
"scripts": {
|
|
74
77
|
"build": "tsc --project ./tsconfig.build.json",
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { Infer } from "convex/values";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { assertRefundCommandScope } from "../../shared/refundCommandScope.js";
|
|
4
|
+
import type { refundCommandEvidenceValidator } from "../../component/refundHistory/commandEvidenceValidator.js";
|
|
5
|
+
import type { Component, RunCtx } from "../helpers.js";
|
|
6
|
+
import { componentRef } from "../webhooks/helpers.js";
|
|
7
|
+
|
|
8
|
+
export type RefundCommandEvidence = Infer<
|
|
9
|
+
typeof refundCommandEvidenceValidator
|
|
10
|
+
>;
|
|
11
|
+
export type RefundCommandEvidenceOptions = {
|
|
12
|
+
commandKey: string;
|
|
13
|
+
stripeAccountId: string;
|
|
14
|
+
stripePaymentIntentId: string;
|
|
15
|
+
stripeChargeId: string;
|
|
16
|
+
currency: string;
|
|
17
|
+
};
|
|
18
|
+
const optionsSchema = z
|
|
19
|
+
.object({
|
|
20
|
+
commandKey: z.string(),
|
|
21
|
+
stripeAccountId: z.string(),
|
|
22
|
+
stripePaymentIntentId: z.string(),
|
|
23
|
+
stripeChargeId: z.string(),
|
|
24
|
+
currency: z.string(),
|
|
25
|
+
})
|
|
26
|
+
.strict();
|
|
27
|
+
|
|
28
|
+
/** Host authorization and original command qualification are required before this observation. */
|
|
29
|
+
export async function getRefundCommandEvidence(
|
|
30
|
+
component: Component,
|
|
31
|
+
ctx: RunCtx,
|
|
32
|
+
input: RefundCommandEvidenceOptions,
|
|
33
|
+
): Promise<RefundCommandEvidence> {
|
|
34
|
+
const { stripeAccountId, ...options } = optionsSchema.parse(input);
|
|
35
|
+
const scope = { ...options, accountId: stripeAccountId };
|
|
36
|
+
assertRefundCommandScope(scope);
|
|
37
|
+
return ctx.runQuery(
|
|
38
|
+
componentRef(component, "refundHistory/queries/getRefundCommandEvidence"),
|
|
39
|
+
scope,
|
|
40
|
+
);
|
|
41
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { runMutationOrThrow, type RunCtx, type Component } from "../helpers.js";
|
|
3
|
+
import { componentRef } from "../webhooks/helpers.js";
|
|
4
|
+
export type RefundCommandNormalizationOptions = { limit: number };
|
|
5
|
+
export type RefundCommandNormalizationResult = {
|
|
6
|
+
normalized: number;
|
|
7
|
+
hasMore: boolean;
|
|
8
|
+
};
|
|
9
|
+
const optionsSchema = z
|
|
10
|
+
.object({ limit: z.number().int().min(1).max(100) })
|
|
11
|
+
.strict();
|
|
12
|
+
|
|
13
|
+
/** Trusted-host projection maintenance; a drained component backlog is not complete provider history. */
|
|
14
|
+
export async function normalizeRefundCommandBindings(
|
|
15
|
+
component: Component,
|
|
16
|
+
ctx: RunCtx,
|
|
17
|
+
opts: RefundCommandNormalizationOptions,
|
|
18
|
+
): Promise<RefundCommandNormalizationResult> {
|
|
19
|
+
const args = optionsSchema.parse(opts);
|
|
20
|
+
return runMutationOrThrow(
|
|
21
|
+
ctx,
|
|
22
|
+
componentRef(
|
|
23
|
+
component,
|
|
24
|
+
"refundHistory/mutations/normalizeRefundCommandBindings",
|
|
25
|
+
),
|
|
26
|
+
args,
|
|
27
|
+
);
|
|
28
|
+
}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
// @vitest-environment edge-runtime
|
|
2
|
+
import { componentRef } from "./webhooks/helpers.js";
|
|
3
|
+
import { expect, it, vi } from "vitest";
|
|
4
|
+
import schema from "../component/schema.js";
|
|
5
|
+
import { BetterStripe } from "./index.js";
|
|
6
|
+
import type { RunCtx } from "./helpers.js";
|
|
7
|
+
import { components, initConvexTest } from "./setup.test.js";
|
|
8
|
+
|
|
9
|
+
it("exposes UNKNOWN source and owner diagnostics through the actual component without Stripe credentials", async () => {
|
|
10
|
+
const t = initConvexTest();
|
|
11
|
+
t.registerComponent(
|
|
12
|
+
"betterStripe",
|
|
13
|
+
schema,
|
|
14
|
+
import.meta.glob("../component/**/*.ts"),
|
|
15
|
+
);
|
|
16
|
+
const client = new BetterStripe(components.betterStripe);
|
|
17
|
+
const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
|
|
18
|
+
await client.financialOwnership.register(ctx, {
|
|
19
|
+
bucketKey: "opaque",
|
|
20
|
+
kind: "logical",
|
|
21
|
+
userId: "user",
|
|
22
|
+
source: { integration: "host", recordId: "fact" },
|
|
23
|
+
});
|
|
24
|
+
const row = await t.mutation(
|
|
25
|
+
componentRef(
|
|
26
|
+
components.betterStripe,
|
|
27
|
+
"settlement/mutations/reserveSettlementAllocation",
|
|
28
|
+
),
|
|
29
|
+
{
|
|
30
|
+
sourceChargeId: "ch_sdk",
|
|
31
|
+
gross: 3,
|
|
32
|
+
currency: "usd",
|
|
33
|
+
processingFee: 1,
|
|
34
|
+
platformNet: 1,
|
|
35
|
+
transfers: [{ destinationAccountId: "opaque", role: "store", amount: 1 }],
|
|
36
|
+
},
|
|
37
|
+
);
|
|
38
|
+
expect(
|
|
39
|
+
await client.financialObservations.source(ctx, { allocationId: row._id }),
|
|
40
|
+
).toMatchObject({ coverage: "unknown", observation: { generation: 1 } });
|
|
41
|
+
const paginationOpts = { numItems: 25, cursor: null, id: 7 };
|
|
42
|
+
expect(
|
|
43
|
+
await client.financialObservations.owner(ctx, {
|
|
44
|
+
userId: "user",
|
|
45
|
+
paginationOpts,
|
|
46
|
+
}),
|
|
47
|
+
).toMatchObject({
|
|
48
|
+
coverage: "unknown",
|
|
49
|
+
generation: 1,
|
|
50
|
+
page: [expect.objectContaining({ bucketKey: "opaque", userId: "user" })],
|
|
51
|
+
});
|
|
52
|
+
});
|
|
53
|
+
it.each([0, 101])(
|
|
54
|
+
"refuses page size %i before trusted dispatch",
|
|
55
|
+
async (numItems) => {
|
|
56
|
+
const client = new BetterStripe(components.betterStripe);
|
|
57
|
+
const ctx = { runQuery: vi.fn(), runMutation: vi.fn() };
|
|
58
|
+
await expect(
|
|
59
|
+
client.financialObservations.bucket(ctx, {
|
|
60
|
+
bucketKey: "opaque",
|
|
61
|
+
paginationOpts: { numItems, cursor: null },
|
|
62
|
+
}),
|
|
63
|
+
).rejects.toThrow();
|
|
64
|
+
expect(ctx.runQuery).not.toHaveBeenCalled();
|
|
65
|
+
},
|
|
66
|
+
);
|
|
67
|
+
it("drains oversized raw reservations through the installed public client", async () => {
|
|
68
|
+
const t = initConvexTest();
|
|
69
|
+
t.registerComponent(
|
|
70
|
+
"betterStripe",
|
|
71
|
+
schema,
|
|
72
|
+
import.meta.glob("../component/**/*.ts"),
|
|
73
|
+
);
|
|
74
|
+
const client = new BetterStripe(components.betterStripe);
|
|
75
|
+
const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
|
|
76
|
+
const row = await t.mutation(
|
|
77
|
+
componentRef(
|
|
78
|
+
components.betterStripe,
|
|
79
|
+
"settlement/mutations/reserveSettlementAllocation",
|
|
80
|
+
),
|
|
81
|
+
{
|
|
82
|
+
sourceChargeId: "ch_sdk_continue",
|
|
83
|
+
gross: 303,
|
|
84
|
+
currency: "usd",
|
|
85
|
+
processingFee: 1,
|
|
86
|
+
platformNet: 1,
|
|
87
|
+
transfers: Array.from({ length: 301 }, (_, i) => ({
|
|
88
|
+
destinationAccountId: `logical_${i}`,
|
|
89
|
+
role: "store",
|
|
90
|
+
amount: 1,
|
|
91
|
+
})),
|
|
92
|
+
},
|
|
93
|
+
);
|
|
94
|
+
let result = await client.financialObservations.source(ctx, {
|
|
95
|
+
allocationId: row._id,
|
|
96
|
+
});
|
|
97
|
+
while (result.observation?.continuation?.state !== "complete")
|
|
98
|
+
result = await client.financialObservations.resume(ctx, {
|
|
99
|
+
allocationId: row._id,
|
|
100
|
+
expectedGeneration: result.observation!.generation,
|
|
101
|
+
});
|
|
102
|
+
expect(result).toMatchObject({
|
|
103
|
+
coverage: "unknown",
|
|
104
|
+
observation: {
|
|
105
|
+
indexedLegCount: 301,
|
|
106
|
+
continuation: { state: "complete", validatedLegs: 301 },
|
|
107
|
+
},
|
|
108
|
+
});
|
|
109
|
+
});
|