@fantastic.dev/better-stripe 0.63.0 → 0.64.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +21 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +550 -0
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +275 -0
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +582 -32
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +291 -16
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/financialOwnership.d.ts +2 -2
  12. package/dist/client/financialOwnership.d.ts.map +1 -1
  13. package/dist/client/financialOwnership.js +2 -2
  14. package/dist/client/financialOwnership.js.map +1 -1
  15. package/dist/client/payoutRevisionMigration.d.ts +37 -0
  16. package/dist/client/payoutRevisionMigration.d.ts.map +1 -0
  17. package/dist/client/payoutRevisionMigration.js +49 -0
  18. package/dist/client/payoutRevisionMigration.js.map +1 -0
  19. package/dist/client/publicTypes.d.ts +2 -0
  20. package/dist/client/publicTypes.d.ts.map +1 -1
  21. package/dist/client/reversalObservations.d.ts +62 -0
  22. package/dist/client/reversalObservations.d.ts.map +1 -0
  23. package/dist/client/reversalObservations.js +79 -0
  24. package/dist/client/reversalObservations.js.map +1 -0
  25. package/dist/component/_generated/api.d.ts +28 -0
  26. package/dist/component/_generated/api.d.ts.map +1 -1
  27. package/dist/component/_generated/api.js.map +1 -1
  28. package/dist/component/_generated/component.d.ts +354 -0
  29. package/dist/component/_generated/component.d.ts.map +1 -1
  30. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  31. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  32. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  33. package/dist/component/connect/mutations.d.ts.map +1 -1
  34. package/dist/component/connect/mutations.js +2 -0
  35. package/dist/component/connect/mutations.js.map +1 -1
  36. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  37. package/dist/component/connect/reversalClaims.js +10 -1
  38. package/dist/component/connect/reversalClaims.js.map +1 -1
  39. package/dist/component/earnings/triggers.d.ts +408 -16
  40. package/dist/component/earnings/triggers.d.ts.map +1 -1
  41. package/dist/component/financialObservations/transferSchema.d.ts +1 -0
  42. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -1
  43. package/dist/component/financialObservations/transferSchema.js +1 -0
  44. package/dist/component/financialObservations/transferSchema.js.map +1 -1
  45. package/dist/component/payoutRelease/queries.d.ts +2 -2
  46. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  47. package/dist/component/payoutRevisionJournal/mutations.d.ts +15 -0
  48. package/dist/component/payoutRevisionJournal/mutations.d.ts.map +1 -0
  49. package/dist/component/payoutRevisionJournal/mutations.js +11 -0
  50. package/dist/component/payoutRevisionJournal/mutations.js.map +1 -0
  51. package/dist/component/payoutRevisionJournal/schema.d.ts +45 -0
  52. package/dist/component/payoutRevisionJournal/schema.d.ts.map +1 -0
  53. package/dist/component/payoutRevisionJournal/schema.js +22 -0
  54. package/dist/component/payoutRevisionJournal/schema.js.map +1 -0
  55. package/dist/component/payoutRevisionJournal/state.d.ts +36 -0
  56. package/dist/component/payoutRevisionJournal/state.d.ts.map +1 -0
  57. package/dist/component/payoutRevisionJournal/state.js +111 -0
  58. package/dist/component/payoutRevisionJournal/state.js.map +1 -0
  59. package/dist/component/payoutRevisionMigration/mutations.d.ts +36 -0
  60. package/dist/component/payoutRevisionMigration/mutations.d.ts.map +1 -0
  61. package/dist/component/payoutRevisionMigration/mutations.js +126 -0
  62. package/dist/component/payoutRevisionMigration/mutations.js.map +1 -0
  63. package/dist/component/payoutRevisionMigration/queries.d.ts +38 -0
  64. package/dist/component/payoutRevisionMigration/queries.d.ts.map +1 -0
  65. package/dist/component/payoutRevisionMigration/queries.js +39 -0
  66. package/dist/component/payoutRevisionMigration/queries.js.map +1 -0
  67. package/dist/component/payoutRevisionMigration/schema.d.ts +115 -0
  68. package/dist/component/payoutRevisionMigration/schema.d.ts.map +1 -0
  69. package/dist/component/payoutRevisionMigration/schema.js +52 -0
  70. package/dist/component/payoutRevisionMigration/schema.js.map +1 -0
  71. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts +4 -0
  72. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts.map +1 -0
  73. package/dist/component/payoutSnapshots/legacyRevisionWriter.js +33 -0
  74. package/dist/component/payoutSnapshots/legacyRevisionWriter.js.map +1 -0
  75. package/dist/component/payoutSnapshots/revisions.d.ts.map +1 -1
  76. package/dist/component/payoutSnapshots/revisions.js +23 -29
  77. package/dist/component/payoutSnapshots/revisions.js.map +1 -1
  78. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  79. package/dist/component/refundSync/mutations.d.ts +1 -1
  80. package/dist/component/refundSync/mutations.d.ts.map +1 -1
  81. package/dist/component/reversalObservations/capture.d.ts +6 -0
  82. package/dist/component/reversalObservations/capture.d.ts.map +1 -0
  83. package/dist/component/reversalObservations/capture.js +96 -0
  84. package/dist/component/reversalObservations/capture.js.map +1 -0
  85. package/dist/component/reversalObservations/indexSlice.d.ts +29 -0
  86. package/dist/component/reversalObservations/indexSlice.d.ts.map +1 -0
  87. package/dist/component/reversalObservations/indexSlice.js +101 -0
  88. package/dist/component/reversalObservations/indexSlice.js.map +1 -0
  89. package/dist/component/reversalObservations/integrity.d.ts +25 -0
  90. package/dist/component/reversalObservations/integrity.d.ts.map +1 -0
  91. package/dist/component/reversalObservations/integrity.js +19 -0
  92. package/dist/component/reversalObservations/integrity.js.map +1 -0
  93. package/dist/component/reversalObservations/mutations.d.ts +37 -0
  94. package/dist/component/reversalObservations/mutations.d.ts.map +1 -0
  95. package/dist/component/reversalObservations/mutations.js +181 -0
  96. package/dist/component/reversalObservations/mutations.js.map +1 -0
  97. package/dist/component/reversalObservations/pagination.d.ts +34 -0
  98. package/dist/component/reversalObservations/pagination.d.ts.map +1 -0
  99. package/dist/component/reversalObservations/pagination.js +31 -0
  100. package/dist/component/reversalObservations/pagination.js.map +1 -0
  101. package/dist/component/reversalObservations/queries.d.ts +221 -0
  102. package/dist/component/reversalObservations/queries.d.ts.map +1 -0
  103. package/dist/component/reversalObservations/queries.js +114 -0
  104. package/dist/component/reversalObservations/queries.js.map +1 -0
  105. package/dist/component/reversalObservations/references.d.ts +17 -0
  106. package/dist/component/reversalObservations/references.d.ts.map +1 -0
  107. package/dist/component/reversalObservations/references.js +95 -0
  108. package/dist/component/reversalObservations/references.js.map +1 -0
  109. package/dist/component/reversalObservations/schema.d.ts +525 -0
  110. package/dist/component/reversalObservations/schema.d.ts.map +1 -0
  111. package/dist/component/reversalObservations/schema.js +92 -0
  112. package/dist/component/reversalObservations/schema.js.map +1 -0
  113. package/dist/component/reversalObservations/selectors.d.ts +3 -0
  114. package/dist/component/reversalObservations/selectors.d.ts.map +1 -0
  115. package/dist/component/reversalObservations/selectors.js +8 -0
  116. package/dist/component/reversalObservations/selectors.js.map +1 -0
  117. package/dist/component/reversalObservations/state.d.ts +34 -0
  118. package/dist/component/reversalObservations/state.d.ts.map +1 -0
  119. package/dist/component/reversalObservations/state.js +34 -0
  120. package/dist/component/reversalObservations/state.js.map +1 -0
  121. package/dist/component/schema.d.ts +275 -0
  122. package/dist/component/schema.js +10 -0
  123. package/dist/component/schema.js.map +1 -1
  124. package/dist/component/usage/allowance.fixtures.d.ts +291 -16
  125. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  126. package/dist/component/usageCredits/accounting.fixtures.d.ts +275 -0
  127. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  128. package/docs/README.md +4 -1
  129. package/docs/client-api.md +6 -0
  130. package/docs/financial-observations.md +51 -8
  131. package/docs/payout-revision-migration.md +54 -0
  132. package/docs/react-workflows-audit.md +73 -2
  133. package/docs/usage-example.md +4 -0
  134. package/docs/usage-verification.md +117 -0
  135. package/package.json +4 -2
  136. package/src/client/financialOwnership.ts +2 -2
  137. package/src/client/payoutRevisionMigration.test.ts +40 -0
  138. package/src/client/payoutRevisionMigration.ts +96 -0
  139. package/src/client/publicTypes.ts +15 -0
  140. package/src/client/reversalObservations.test.ts +69 -0
  141. package/src/client/reversalObservations.ts +151 -0
  142. package/src/component/_generated/api.ts +28 -0
  143. package/src/component/_generated/component.ts +423 -0
  144. package/src/component/connect/mutations.ts +2 -0
  145. package/src/component/connect/reversalClaims.ts +13 -1
  146. package/src/component/financialObservations/transferSchema.ts +1 -0
  147. package/src/component/payoutRevisionJournal/mutations.ts +11 -0
  148. package/src/component/payoutRevisionJournal/schema.ts +34 -0
  149. package/src/component/payoutRevisionJournal/state.ts +141 -0
  150. package/src/component/payoutRevisionMigration/mutations.ts +135 -0
  151. package/src/component/payoutRevisionMigration/queries.ts +50 -0
  152. package/src/component/payoutRevisionMigration/schema.ts +51 -0
  153. package/src/component/payoutSnapshots/legacy-revisions.test.ts +246 -0
  154. package/src/component/payoutSnapshots/legacyRevisionWriter.ts +39 -0
  155. package/src/component/payoutSnapshots/revision-journal-callbacks.test.ts +160 -0
  156. package/src/component/payoutSnapshots/revision-journal-held.test.ts +94 -0
  157. package/src/component/payoutSnapshots/revision-journal.test.ts +310 -0
  158. package/src/component/payoutSnapshots/revision-migration.test.ts +128 -0
  159. package/src/component/payoutSnapshots/revisions.ts +22 -30
  160. package/src/component/reversalObservations/boundaries.test.ts +62 -0
  161. package/src/component/reversalObservations/capture-integrity.test.ts +119 -0
  162. package/src/component/reversalObservations/capture.ts +129 -0
  163. package/src/component/reversalObservations/continuation.test.ts +131 -0
  164. package/src/component/reversalObservations/indexSlice.ts +124 -0
  165. package/src/component/reversalObservations/integrity.ts +31 -0
  166. package/src/component/reversalObservations/lifecycle.test.ts +81 -0
  167. package/src/component/reversalObservations/mutations.ts +211 -0
  168. package/src/component/reversalObservations/pagination.ts +40 -0
  169. package/src/component/reversalObservations/provenance.test.ts +167 -0
  170. package/src/component/reversalObservations/queries.ts +121 -0
  171. package/src/component/reversalObservations/references.ts +134 -0
  172. package/src/component/reversalObservations/schema.ts +100 -0
  173. package/src/component/reversalObservations/selectors.ts +9 -0
  174. package/src/component/reversalObservations/state.ts +42 -0
  175. package/src/component/schema.ts +18 -0
@@ -0,0 +1,117 @@
1
+ # Metered usage verification
2
+
3
+ BetterStripe supports pay as you go, included monthly units with overages, and
4
+ paid prepaid credits. This matrix separates actual Stripe sandbox observations
5
+ from deterministic failure tests. It does not certify live-money eligibility or
6
+ production throughput.
7
+
8
+ ## Reproduce the checks
9
+
10
+ From the repository root, with the pinned pnpm dependencies installed:
11
+
12
+ ```sh
13
+ pnpm run build
14
+ pnpm exec vitest run src/client/usage src/component/usage src/react/workflows/Usage example/convex/meteredUsage scripts/usage-contracts-packed.test.mjs scripts/usage-composition-packed.test.mjs scripts/usage-models-packed.test.mjs scripts/verify-usage-evidence.test.mjs
15
+ node scripts/verify-usage-evidence.mjs
16
+ pnpm run check:all
17
+ ```
18
+
19
+ The packed tests extract an actual `pnpm pack` archive into an external temporary
20
+ consumer. Import resolution is asserted against the extracted package. The
21
+ three-model test registers its actual compiled Convex component, invokes public
22
+ reservation and recording APIs, races competing work against the remaining units,
23
+ and renders the resulting balances through the packed React components. No
24
+ provider is called by that deterministic test. Its prepaid setup injects verified
25
+ fixture backing through internal component functions; native payment verification
26
+ is separately exercised through real SDK transports and the sandbox flows below.
27
+
28
+ ## Three-model acceptance matrix
29
+
30
+ | Contract | Pay as you go | Included monthly units and overages | Paid prepaid credits |
31
+ | ----------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
32
+ | Packed public API and actual component | Immutable record and replay; configured hard cap | Reserve, consume, exact free/overage boundary and hard cap | Unpaid purchase cannot reserve; verified backing, reserve, consume and exhaustion |
33
+ | Competing packed work | Exactly one remaining-capacity request commits | Exactly one remaining-capacity request commits | Exactly one last-units request commits |
34
+ | Packed React view | Actual allowance accounting and estimate | Actual included quantity, overage and estimate | Actual available, consumed and exhausted balance |
35
+ | Sandbox local/native effective units | 15 / 15 | 15 / 15, including 10 free units | 10 / 10, funded by the original 10-unit purchase |
36
+ | Original paid native usage invoice, USD minor units | 1500 | 500, with native zero-priced included line plus overage line | 0 due and paid; 1000 rated usage covered by original native credits |
37
+ | Original cash source | InvoicePayment → original PaymentIntent/Charge | InvoicePayment → original PaymentIntent/Charge | Original paid purchase PaymentIntent/Charge, gross 1000 |
38
+ | Actual processing fee, USD minor units | 74 | 45 | 59 on the original purchase |
39
+ | Eligible seller / affiliate transfer, USD minor units | 1080 / 270 | 360 / 90 | No seller redemption transfer; affiliate 180 on the original purchase |
40
+ | Verified renewal observation | New native period retained | New native period retained; controlled-clock test proves local reset | Original paid-grant terms and consumption retained |
41
+
42
+ Each native row has both an issuer-only customer fixture and an eligible seller
43
+ fixture. The values above describe those specific USD sandbox cases, not universal
44
+ Stripe fees or rates. Settlement retries retained the original transfer IDs.
45
+
46
+ The original payment/invoice/settlement proof and UI recording are retained in
47
+ [the example evidence](https://github.com/FantasticDevHQ/better-stripe/tree/main/docs/evidence/usage-example). A subsequent native
48
+ aggregate refresh and complete retained ledger histories for all six fixtures are
49
+ in [the verification evidence](https://github.com/FantasticDevHQ/better-stripe/tree/main/docs/evidence/usage-verification). Financial
50
+ proof records when those invoices and purchases were verified; the refresh does
51
+ not claim a new cash observation or perform another payment or transfer.
52
+
53
+ ## Failure and boundary matrix
54
+
55
+ These tests exercise the real component and real Stripe SDK transports with
56
+ controlled responses. Their fixtures are deterministic, not native charge or
57
+ network-failure recordings.
58
+
59
+ | Invariant | Executable coverage |
60
+ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61
+ | Concurrent duplicates, changed amount/version/time, exact source identity, tenant/mode/realm isolation | `src/component/usage/ledger.test.ts`, `src/client/usage/boundaries.test.ts`, `src/component/usage/historyIsolation.test.ts` |
62
+ | Host authentication boundary before reusable acceptance, guessed IDs and cross-tenant cursors | `src/client/usage/boundaries.test.ts`, `src/component/usage/historyIsolation.test.ts`, `src/component/usageCredits/accounting.test.ts`, `example/convex/meteredUsage/state.test.ts` |
63
+ | Exact quantities beyond safe JS integers, unsupported API/definition versions, retained payload/history quotas | `src/client/usage/contracts.test.ts`, `src/client/usage/deliveryProvider.test.ts`, `src/component/usage/ledger.test.ts`, `src/component/usage/allowanceBounds.test.ts`, `src/component/usageCredits/quotas.test.ts` |
64
+ | Partial batches, rate limits, restarts, lost responses and provider success followed by receipt failure | `src/component/usageDelivery/workflow.test.ts`, `src/client/usage/catalog.test.ts`, `src/client/usage/correctionRecovery.test.ts`, `src/client/usage/creditProvider.test.ts` |
65
+ | Unknown responses beyond the retry window cannot send blindly; native clock/time-window guards | `src/component/usageDelivery/workflow.test.ts`, `src/client/usage/deliveryProvider.test.ts` |
66
+ | Complete summaries, lag, stale observations, scope mismatch and incomplete histories cannot become a successful zero | `src/client/usage/reconciliation.test.ts`, `src/client/usage/providerObservation.test.ts`, `src/component/usageObservations/queries.test.ts`, `src/react/workflows/Usage.test.tsx` |
67
+ | Included-unit reservation, concurrency, hard/soft caps, price changes, half-open periods and new-period reset | `src/component/usage/allowance.test.ts`, `src/client/usage/allowanceTerms.test.ts` |
68
+ | Prepaid payment gating, concurrent last-unit spending, duplicate backing, delayed grants and exhausted balance | `src/component/usageCredits/accounting.test.ts`, `src/client/usage/creditProvider.test.ts`, `scripts/usage-models-packed.test.mjs` |
69
+ | Original grant application, native invoice credits, reservation freshness and bounded complete backing proof | `src/client/usage/creditInvoice.test.ts`, `src/client/usage/creditObservation.test.ts`, `src/client/usage/creditProofBounds.test.ts`, `src/component/usageCredits/freshness.test.ts` |
70
+ | Corrections before/after billing cutoff, native pending cancellation, late credit notes and no invented refund | `src/client/usage/correctionClient.test.ts`, `src/client/usage/correctionRecovery.test.ts`, `src/client/usage/correctionInvoice.test.ts`, `src/component/usageCorrections/corrections.test.ts` |
71
+ | Paid original invoice, actual processing fee, one-time/forever commission and no duplicate transfers after receipt failure | `src/client/usage/invoiceSale.test.ts`, `src/client/usage/settlement.test.ts` |
72
+ | Prepaid refunds, disputes, won reinstatement, consumed backing, affiliate recovery and no second sale on redemption | `src/client/usage/creditSettlementRecovery.test.ts`, `src/component/usageCredits/accounting.test.ts`, `src/client/usage/creditRevenue.test.ts` |
73
+ | Saved success cannot bypass later cash uncertainty or unresolved settlement during cleanup | `example/convex/meteredUsage/revenue.test.ts`, `example/convex/meteredUsage/cleanupRefresh.test.ts` |
74
+
75
+ ## Comparison and hold rules
76
+
77
+ Compare explicit original scope, meter, price/version, subscription item and
78
+ half-open billing period. Native aggregation can lag. A temporary match is an
79
+ observation, not invoice finality. Missing, stale, truncated or unavailable evidence
80
+ stays unavailable or held. The retained native proof uses zero tolerance in scaled
81
+ units after aggregation has settled. Exact decimal rates and scaled integer units
82
+ avoid rounding discrepancies; estimates remain labelled estimates. Only a complete
83
+ finalized original invoice determines the rated amount. A paid zero-dollar prepaid
84
+ invoice cannot create cash revenue.
85
+
86
+ The evidence auditor checks all six native aggregates against complete local
87
+ histories, original invoice lines, exact quantities and original cash/transfer
88
+ identities. It also checks conservation of original gross across actual processing
89
+ fees, retained platform proceeds and executed transfers. Corruption tests reject
90
+ unknown/stale/partial data, changed quantities/prices, foreign cash and duplicate
91
+ transfer identities. It audits retained proof; it cannot replace a fresh provider
92
+ reconciliation before a financial operation.
93
+
94
+ ## Tested limits
95
+
96
+ The sandbox issuer and eligible seller/affiliate recipients support the recorded
97
+ Accounts v2 and Connect flows. A seller without transfer capability retained paid
98
+ cash evidence but remained held for settlement; cleanup refused to erase it.
99
+ Issuer-only customer billing was also exercised on the same platform issuer.
100
+ This does not establish a separate non-Connect customer-only preview account's
101
+ eligibility. Billing under connected-account headers is not supported by the
102
+ current usage adapters. Those cases require their own verified API/account
103
+ configuration. Eligibility remains tied to the original account configuration,
104
+ currency, API access and native capabilities.
105
+
106
+ Native test clocks advanced billing and exposed the next subscription period.
107
+ That future period is outside the real server's current allowance acceptance
108
+ window. Its allowance is explicitly `not_active_yet`, not zero or accepting. A
109
+ controlled-clock component test proves monthly counter reset while retaining the
110
+ old period. The sandbox does not establish a future-period production send before
111
+ its real acceptance window, or a wall-clock month of production operation.
112
+
113
+ No native live dispute was created. Refund/dispute recovery, transport ambiguity,
114
+ worker/DB failures, retained quota limits and API-version refusals use deterministic
115
+ SDK/component tests. No load or sustained throughput certification is claimed.
116
+ These checks authorize neither live billing nor automatic production migration,
117
+ publication or replay of unknown historical provider writes.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.63.0",
3
+ "version": "0.64.1",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -114,7 +114,9 @@
114
114
  "docs/usage-react.md",
115
115
  "docs/evidence/native-metering",
116
116
  "docs/usage-configuration.md",
117
- "docs/usage-example.md"
117
+ "docs/usage-example.md",
118
+ "docs/payout-revision-migration.md",
119
+ "docs/usage-verification.md"
118
120
  ],
119
121
  "scripts": {
120
122
  "build": "tsc --project ./tsconfig.build.json && node scripts/check-public-exports.mjs",
@@ -6,7 +6,7 @@ import {
6
6
  assertSelector,
7
7
  } from "../component/financialOwnership/helpers.js";
8
8
  import type { registrationDoc } from "../component/financialOwnership/schema.js";
9
- import { FinancialObservationsHost } from "./financialObservations.js";
9
+ import { ReversalObservationsHost } from "./reversalObservations.js";
10
10
  import type { Component, RunCtx } from "./helpers.js";
11
11
  import { runMutationOrThrow } from "./helpers.js";
12
12
  import { componentRef } from "./webhooks/helpers.js";
@@ -111,6 +111,6 @@ export class FinancialOwnershipClient {
111
111
  }
112
112
  }
113
113
  /** Extends the existing facade without expanding its frozen entry-file budget. */
114
- export abstract class FinancialOwnershipHost extends FinancialObservationsHost {
114
+ export abstract class FinancialOwnershipHost extends ReversalObservationsHost {
115
115
  readonly financialOwnership = new FinancialOwnershipClient(this.component);
116
116
  }
@@ -0,0 +1,40 @@
1
+ // @vitest-environment edge-runtime
2
+ import { expect, it } from "vitest";
3
+ import schema from "../component/schema.js";
4
+ import { BetterStripe } from "./index.js";
5
+ import type { RunCtx } from "./helpers.js";
6
+ import { components, initConvexTest } from "./setup.test.js";
7
+ const modules = import.meta.glob("../component/**/*.ts");
8
+ it("runs the trusted migration through the public facade without Stripe or financial writes", async () => {
9
+ const t = initConvexTest();
10
+ t.registerComponent("betterStripe", schema, modules);
11
+ const client = new BetterStripe(components.betterStripe);
12
+ const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
13
+ const migration = client.payoutRevisionMigration;
14
+ expect(await migration.activateAccount(ctx, { accountId: "opaque" })).toEqual(
15
+ { accountId: "opaque", status: "activated" },
16
+ );
17
+ let job = await migration.begin(ctx, { operationKey: "public-pass" });
18
+ expect(await migration.get(ctx, { jobId: job._id })).toEqual(job);
19
+ while (job.status !== "finished")
20
+ job = await migration.resume(ctx, {
21
+ jobId: job._id,
22
+ expectedStep: job.step,
23
+ });
24
+ expect(job).toMatchObject({ status: "finished", visited: 0 });
25
+ expect(
26
+ await migration.results(ctx, {
27
+ jobId: job._id,
28
+ paginationOpts: { numItems: 1, cursor: null },
29
+ }),
30
+ ).toMatchObject({ page: [], isDone: true });
31
+ expect(() =>
32
+ migration.resume(ctx, { jobId: job._id, expectedStep: -1 }),
33
+ ).toThrow();
34
+ expect(() =>
35
+ migration.results(ctx, {
36
+ jobId: job._id,
37
+ paginationOpts: { numItems: 101, cursor: null },
38
+ }),
39
+ ).toThrow();
40
+ });
@@ -0,0 +1,96 @@
1
+ import type { PaginationResult } from "convex/server";
2
+ import type { Infer } from "convex/values";
3
+ import { z } from "zod";
4
+ import { FinancialObservationsHost } from "./financialObservations.js";
5
+ import { runMutationOrThrow, type Component, type RunCtx } from "./helpers.js";
6
+ import { componentRef } from "./webhooks/helpers.js";
7
+ import { observationPagination } from "./observationPagination.js";
8
+ import type { activationResult } from "../component/payoutRevisionJournal/schema.js";
9
+ import type {
10
+ jobDoc,
11
+ resultDoc,
12
+ } from "../component/payoutRevisionMigration/schema.js";
13
+ export type PayoutRevisionActivation = Infer<typeof activationResult>;
14
+ export type PayoutRevisionMigrationState = Infer<typeof jobDoc>;
15
+ export type PayoutRevisionMigrationResult = Infer<typeof resultDoc>;
16
+ const jobId = z.string().min(1).max(256);
17
+ /** Trusted host maintenance only. Authorize every call; completion is not financial coverage. */
18
+ export class PayoutRevisionMigrationClient {
19
+ constructor(private component: Component) {}
20
+ activateAccount(
21
+ ctx: RunCtx,
22
+ input: { accountId: string },
23
+ ): Promise<PayoutRevisionActivation> {
24
+ const args = z.object({ accountId: z.string() }).strict().parse(input);
25
+ return runMutationOrThrow(
26
+ ctx,
27
+ componentRef(
28
+ this.component,
29
+ "payoutRevisionJournal/mutations/activateAccount",
30
+ ),
31
+ args,
32
+ );
33
+ }
34
+ begin(
35
+ ctx: RunCtx,
36
+ input: { operationKey: string },
37
+ ): Promise<PayoutRevisionMigrationState> {
38
+ const args = z
39
+ .object({ operationKey: z.string().min(1).max(256) })
40
+ .strict()
41
+ .parse(input);
42
+ return runMutationOrThrow(
43
+ ctx,
44
+ componentRef(this.component, "payoutRevisionMigration/mutations/begin"),
45
+ args,
46
+ );
47
+ }
48
+ resume(
49
+ ctx: RunCtx,
50
+ input: { jobId: string; expectedStep: number },
51
+ ): Promise<PayoutRevisionMigrationState> {
52
+ const args = z
53
+ .object({
54
+ jobId,
55
+ expectedStep: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
56
+ })
57
+ .strict()
58
+ .parse(input);
59
+ return runMutationOrThrow(
60
+ ctx,
61
+ componentRef(this.component, "payoutRevisionMigration/mutations/resume"),
62
+ args,
63
+ );
64
+ }
65
+ get(
66
+ ctx: RunCtx,
67
+ input: { jobId: string },
68
+ ): Promise<PayoutRevisionMigrationState | null> {
69
+ const args = z.object({ jobId }).strict().parse(input);
70
+ return ctx.runQuery(
71
+ componentRef(this.component, "payoutRevisionMigration/queries/get"),
72
+ args,
73
+ );
74
+ }
75
+ results(
76
+ ctx: RunCtx,
77
+ input: {
78
+ jobId: string;
79
+ paginationOpts: z.input<typeof observationPagination>;
80
+ },
81
+ ): Promise<PaginationResult<PayoutRevisionMigrationResult>> {
82
+ const args = z
83
+ .object({ jobId, paginationOpts: observationPagination })
84
+ .strict()
85
+ .parse(input);
86
+ return ctx.runQuery(
87
+ componentRef(this.component, "payoutRevisionMigration/queries/results"),
88
+ args,
89
+ );
90
+ }
91
+ }
92
+ export abstract class PayoutRevisionMigrationHost extends FinancialObservationsHost {
93
+ readonly payoutRevisionMigration = new PayoutRevisionMigrationClient(
94
+ this.component,
95
+ );
96
+ }
@@ -103,3 +103,18 @@ export type {
103
103
  AccountByStripeIdOptions,
104
104
  SubscriptionByStripeIdOptions,
105
105
  } from "./originalIdReadOptions.js";
106
+
107
+ export type {
108
+ PayoutRevisionActivation,
109
+ PayoutRevisionMigrationState,
110
+ PayoutRevisionMigrationResult,
111
+ } from "./payoutRevisionMigration.js";
112
+
113
+ export type {
114
+ ReversalObservation,
115
+ ReversalObservationSlice,
116
+ ReversalObservationPayload,
117
+ ReversalObservationState,
118
+ ReversalObservationResult,
119
+ ReversalObservationPage,
120
+ } from "./reversalObservations.js";
@@ -0,0 +1,69 @@
1
+ // @vitest-environment edge-runtime
2
+ import { expect, it } from "vitest";
3
+ import schema from "../component/schema.js";
4
+ import { BetterStripe } from "./index.js";
5
+ import type { RunCtx } from "./helpers.js";
6
+ import { components, initConvexTest } from "./setup.test.js";
7
+ const modules = import.meta.glob("../component/**/*.ts");
8
+ it("navigates package-owned reversal history through the public facade without Stripe", async () => {
9
+ const t = initConvexTest();
10
+ t.registerComponent("betterStripe", schema, modules);
11
+ const client = new BetterStripe(components.betterStripe);
12
+ const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
13
+ await t.mutation(components.betterStripe.connect.mutations.upsertTransfer, {
14
+ stripeTransferId: "tr_sdk_history",
15
+ sourceChargeId: "ch_sdk_history",
16
+ destinationAccountId: "acct_sdk",
17
+ amount: 10,
18
+ currency: "usd",
19
+ role: "store",
20
+ status: "paid",
21
+ });
22
+ await t.mutation(
23
+ components.betterStripe.connect.mutations.claimReversalSlices,
24
+ {
25
+ operationId: "op_sdk_history",
26
+ sourceChargeId: "ch_sdk_history",
27
+ mode: { kind: "full" },
28
+ },
29
+ );
30
+ const history = await client.reversalObservations.history(ctx, {
31
+ selector: "sourceChargeId",
32
+ value: "ch_sdk_history",
33
+ paginationOpts: { numItems: 1, cursor: null },
34
+ });
35
+ expect(history).toMatchObject({ coverage: "unknown" });
36
+ if (!history.isDone) {
37
+ const end = await client.reversalObservations.history(ctx, {
38
+ selector: "sourceChargeId",
39
+ value: "ch_sdk_history",
40
+ paginationOpts: { numItems: 1, cursor: history.continueCursor },
41
+ });
42
+ expect(end).toMatchObject({ coverage: "unknown", isDone: true, page: [] });
43
+ }
44
+ expect(history.page).toHaveLength(1);
45
+ const operationId = history.page[0].originalOperationId;
46
+ let state = await client.reversalObservations.operation(ctx, { operationId });
47
+ for (let n = 0; n < 4 && state.observation?.status !== "complete"; n++)
48
+ state = await client.reversalObservations.resume(ctx, {
49
+ operationId,
50
+ expectedGeneration: state.observation!.generation,
51
+ batchSize: 1,
52
+ });
53
+ const page = await client.reversalObservations.bucket(ctx, {
54
+ bucketKey: "acct_sdk",
55
+ paginationOpts: { numItems: 1, cursor: null },
56
+ });
57
+ expect(page.page[0]).toMatchObject({
58
+ originalOperationId: operationId,
59
+ sliceIndex: 0,
60
+ });
61
+ const original = await client.reversalObservations.payload(ctx, {
62
+ operationId: page.page[0].originalOperationId,
63
+ version: "original",
64
+ });
65
+ expect(original.payload).toMatchObject({
66
+ operationId: "op_sdk_history",
67
+ sourceChargeId: "ch_sdk_history",
68
+ });
69
+ });
@@ -0,0 +1,151 @@
1
+ import type { PaginationResult } from "convex/server";
2
+ import type { Infer } from "convex/values";
3
+ import { z } from "zod";
4
+ import { PayoutRevisionMigrationHost } from "./payoutRevisionMigration.js";
5
+ import { runMutationOrThrow, type Component, type RunCtx } from "./helpers.js";
6
+ import { componentRef } from "./webhooks/helpers.js";
7
+ import { observationPagination } from "./observationPagination.js";
8
+ import type {
9
+ headerDoc,
10
+ sliceDoc,
11
+ payloadDoc,
12
+ } from "../component/reversalObservations/schema.js";
13
+ export type ReversalObservation = Infer<typeof headerDoc>;
14
+ export type ReversalObservationSlice = Infer<typeof sliceDoc>;
15
+ export type ReversalObservationPayload = Infer<typeof payloadDoc>;
16
+ export type ReversalObservationState = {
17
+ coverage: "unknown";
18
+ generation: number | null;
19
+ transferGeneration: number | null;
20
+ };
21
+ export type ReversalObservationResult = ReversalObservationState & {
22
+ observation: ReversalObservation | null;
23
+ };
24
+ export type ReversalObservationPage<T> = ReversalObservationState &
25
+ PaginationResult<T>;
26
+ type PageOptions = z.input<typeof observationPagination>;
27
+ const operationId = z.string().min(1).max(256);
28
+ /** Trusted host diagnostics only. History and indexed pages never authorize financial actions. */
29
+ export class ReversalObservationsClient {
30
+ constructor(private component: Component) {}
31
+ operation(
32
+ ctx: RunCtx,
33
+ input: { operationId: string },
34
+ ): Promise<ReversalObservationResult> {
35
+ const args = z.object({ operationId }).strict().parse(input);
36
+ return ctx.runQuery(
37
+ componentRef(this.component, "reversalObservations/queries/operation"),
38
+ args,
39
+ );
40
+ }
41
+ resume(
42
+ ctx: RunCtx,
43
+ input: {
44
+ operationId: string;
45
+ expectedGeneration: number;
46
+ batchSize?: number;
47
+ },
48
+ ): Promise<ReversalObservationResult> {
49
+ const args = z
50
+ .object({
51
+ operationId,
52
+ expectedGeneration: z
53
+ .number()
54
+ .int()
55
+ .min(1)
56
+ .max(Number.MAX_SAFE_INTEGER),
57
+ batchSize: z.number().int().min(1).max(20).optional(),
58
+ })
59
+ .strict()
60
+ .parse(input);
61
+ return runMutationOrThrow(
62
+ ctx,
63
+ componentRef(this.component, "reversalObservations/mutations/resume"),
64
+ args,
65
+ );
66
+ }
67
+ slices(
68
+ ctx: RunCtx,
69
+ input: { operationId: string; paginationOpts: PageOptions },
70
+ ): Promise<ReversalObservationPage<ReversalObservationSlice>> {
71
+ const args = z
72
+ .object({ operationId, paginationOpts: observationPagination })
73
+ .strict()
74
+ .parse(input);
75
+ return ctx.runQuery(
76
+ componentRef(this.component, "reversalObservations/queries/slices"),
77
+ args,
78
+ );
79
+ }
80
+ bucket(
81
+ ctx: RunCtx,
82
+ input: { bucketKey: string; paginationOpts: PageOptions },
83
+ ): Promise<ReversalObservationPage<ReversalObservationSlice>> {
84
+ const args = z
85
+ .object({ bucketKey: z.string(), paginationOpts: observationPagination })
86
+ .strict()
87
+ .parse(input);
88
+ return ctx.runQuery(
89
+ componentRef(this.component, "reversalObservations/queries/bucket"),
90
+ args,
91
+ );
92
+ }
93
+ owner(
94
+ ctx: RunCtx,
95
+ input: { userId: string; orgId?: string; paginationOpts: PageOptions },
96
+ ): Promise<ReversalObservationPage<ReversalObservationSlice>> {
97
+ const args = z
98
+ .object({
99
+ userId: z.string().min(1),
100
+ orgId: z.string().min(1).optional(),
101
+ paginationOpts: observationPagination,
102
+ })
103
+ .strict()
104
+ .parse(input);
105
+ return ctx.runQuery(
106
+ componentRef(this.component, "reversalObservations/queries/owner"),
107
+ args,
108
+ );
109
+ }
110
+ history(
111
+ ctx: RunCtx,
112
+ input: {
113
+ selector: "operationId" | "sourceChargeId";
114
+ value: string;
115
+ paginationOpts: PageOptions;
116
+ },
117
+ ): Promise<ReversalObservationPage<ReversalObservation>> {
118
+ const args = z
119
+ .object({
120
+ selector: z.enum(["operationId", "sourceChargeId"]),
121
+ value: z.string(),
122
+ paginationOpts: observationPagination,
123
+ })
124
+ .strict()
125
+ .parse(input);
126
+ return ctx.runQuery(
127
+ componentRef(this.component, "reversalObservations/queries/history"),
128
+ args,
129
+ );
130
+ }
131
+ payload(
132
+ ctx: RunCtx,
133
+ input: { operationId: string; version: "original" | "latest" },
134
+ ): Promise<
135
+ ReversalObservationState & { payload: ReversalObservationPayload | null }
136
+ > {
137
+ const args = z
138
+ .object({ operationId, version: z.enum(["original", "latest"]) })
139
+ .strict()
140
+ .parse(input);
141
+ return ctx.runQuery(
142
+ componentRef(this.component, "reversalObservations/queries/payload"),
143
+ args,
144
+ );
145
+ }
146
+ }
147
+ export abstract class ReversalObservationsHost extends PayoutRevisionMigrationHost {
148
+ readonly reversalObservations = new ReversalObservationsClient(
149
+ this.component,
150
+ );
151
+ }
@@ -113,8 +113,13 @@ import type * as payoutRelease_planning from "../payoutRelease/planning.js";
113
113
  import type * as payoutRelease_preview from "../payoutRelease/preview.js";
114
114
  import type * as payoutRelease_progress from "../payoutRelease/progress.js";
115
115
  import type * as payoutRelease_queries from "../payoutRelease/queries.js";
116
+ import type * as payoutRevisionJournal_mutations from "../payoutRevisionJournal/mutations.js";
117
+ import type * as payoutRevisionJournal_state from "../payoutRevisionJournal/state.js";
118
+ import type * as payoutRevisionMigration_mutations from "../payoutRevisionMigration/mutations.js";
119
+ import type * as payoutRevisionMigration_queries from "../payoutRevisionMigration/queries.js";
116
120
  import type * as payoutSnapshots_adoption from "../payoutSnapshots/adoption.js";
117
121
  import type * as payoutSnapshots_financial from "../payoutSnapshots/financial.js";
122
+ import type * as payoutSnapshots_legacyRevisionWriter from "../payoutSnapshots/legacyRevisionWriter.js";
118
123
  import type * as payoutSnapshots_liabilities from "../payoutSnapshots/liabilities.js";
119
124
  import type * as payoutSnapshots_localState from "../payoutSnapshots/localState.js";
120
125
  import type * as payoutSnapshots_mutations from "../payoutSnapshots/mutations.js";
@@ -158,6 +163,15 @@ import type * as refundSync_mutations from "../refundSync/mutations.js";
158
163
  import type * as refundSync_queries from "../refundSync/queries.js";
159
164
  import type * as refundSync_routing from "../refundSync/routing.js";
160
165
  import type * as refundSync_validators from "../refundSync/validators.js";
166
+ import type * as reversalObservations_capture from "../reversalObservations/capture.js";
167
+ import type * as reversalObservations_indexSlice from "../reversalObservations/indexSlice.js";
168
+ import type * as reversalObservations_integrity from "../reversalObservations/integrity.js";
169
+ import type * as reversalObservations_mutations from "../reversalObservations/mutations.js";
170
+ import type * as reversalObservations_pagination from "../reversalObservations/pagination.js";
171
+ import type * as reversalObservations_queries from "../reversalObservations/queries.js";
172
+ import type * as reversalObservations_references from "../reversalObservations/references.js";
173
+ import type * as reversalObservations_selectors from "../reversalObservations/selectors.js";
174
+ import type * as reversalObservations_state from "../reversalObservations/state.js";
161
175
  import type * as settlement_clawbackSchema from "../settlement/clawbackSchema.js";
162
176
  import type * as settlement_clawbacks from "../settlement/clawbacks.js";
163
177
  import type * as settlement_mutations from "../settlement/mutations.js";
@@ -317,8 +331,13 @@ const fullApi: ApiFromModules<{
317
331
  "payoutRelease/preview": typeof payoutRelease_preview;
318
332
  "payoutRelease/progress": typeof payoutRelease_progress;
319
333
  "payoutRelease/queries": typeof payoutRelease_queries;
334
+ "payoutRevisionJournal/mutations": typeof payoutRevisionJournal_mutations;
335
+ "payoutRevisionJournal/state": typeof payoutRevisionJournal_state;
336
+ "payoutRevisionMigration/mutations": typeof payoutRevisionMigration_mutations;
337
+ "payoutRevisionMigration/queries": typeof payoutRevisionMigration_queries;
320
338
  "payoutSnapshots/adoption": typeof payoutSnapshots_adoption;
321
339
  "payoutSnapshots/financial": typeof payoutSnapshots_financial;
340
+ "payoutSnapshots/legacyRevisionWriter": typeof payoutSnapshots_legacyRevisionWriter;
322
341
  "payoutSnapshots/liabilities": typeof payoutSnapshots_liabilities;
323
342
  "payoutSnapshots/localState": typeof payoutSnapshots_localState;
324
343
  "payoutSnapshots/mutations": typeof payoutSnapshots_mutations;
@@ -362,6 +381,15 @@ const fullApi: ApiFromModules<{
362
381
  "refundSync/queries": typeof refundSync_queries;
363
382
  "refundSync/routing": typeof refundSync_routing;
364
383
  "refundSync/validators": typeof refundSync_validators;
384
+ "reversalObservations/capture": typeof reversalObservations_capture;
385
+ "reversalObservations/indexSlice": typeof reversalObservations_indexSlice;
386
+ "reversalObservations/integrity": typeof reversalObservations_integrity;
387
+ "reversalObservations/mutations": typeof reversalObservations_mutations;
388
+ "reversalObservations/pagination": typeof reversalObservations_pagination;
389
+ "reversalObservations/queries": typeof reversalObservations_queries;
390
+ "reversalObservations/references": typeof reversalObservations_references;
391
+ "reversalObservations/selectors": typeof reversalObservations_selectors;
392
+ "reversalObservations/state": typeof reversalObservations_state;
365
393
  "settlement/clawbackSchema": typeof settlement_clawbackSchema;
366
394
  "settlement/clawbacks": typeof settlement_clawbacks;
367
395
  "settlement/mutations": typeof settlement_mutations;