@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.
Files changed (308) hide show
  1. package/CHANGELOG.md +260 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +664 -2
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +332 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +664 -2
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +332 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/connect/refundCommandEvidence.d.ts +14 -0
  12. package/dist/client/connect/refundCommandEvidence.d.ts.map +1 -0
  13. package/dist/client/connect/refundCommandEvidence.js +20 -0
  14. package/dist/client/connect/refundCommandEvidence.js.map +1 -0
  15. package/dist/client/connect/refundCommandNormalization.d.ts +11 -0
  16. package/dist/client/connect/refundCommandNormalization.d.ts.map +1 -0
  17. package/dist/client/connect/refundCommandNormalization.js +12 -0
  18. package/dist/client/connect/refundCommandNormalization.js.map +1 -0
  19. package/dist/client/financialObservations.d.ts +42 -0
  20. package/dist/client/financialObservations.d.ts.map +1 -0
  21. package/dist/client/financialObservations.js +58 -0
  22. package/dist/client/financialObservations.js.map +1 -0
  23. package/dist/client/financialOwnership.d.ts +52 -0
  24. package/dist/client/financialOwnership.d.ts.map +1 -0
  25. package/dist/client/financialOwnership.js +72 -0
  26. package/dist/client/financialOwnership.js.map +1 -0
  27. package/dist/client/index.d.ts +2 -2
  28. package/dist/client/index.d.ts.map +1 -1
  29. package/dist/client/index.js +2 -2
  30. package/dist/client/index.js.map +1 -1
  31. package/dist/client/observationPagination.d.ts +10 -0
  32. package/dist/client/observationPagination.d.ts.map +1 -0
  33. package/dist/client/observationPagination.js +12 -0
  34. package/dist/client/observationPagination.js.map +1 -0
  35. package/dist/client/operationEvidence.d.ts +37 -0
  36. package/dist/client/operationEvidence.d.ts.map +1 -0
  37. package/dist/client/operationEvidence.js +44 -0
  38. package/dist/client/operationEvidence.js.map +1 -0
  39. package/dist/client/publicTypes.d.ts +6 -0
  40. package/dist/client/publicTypes.d.ts.map +1 -1
  41. package/dist/client/readContracts.d.ts +31 -0
  42. package/dist/client/readContracts.d.ts.map +1 -1
  43. package/dist/client/readContracts.js +14 -0
  44. package/dist/client/readContracts.js.map +1 -1
  45. package/dist/client/transferObservations.d.ts +59 -0
  46. package/dist/client/transferObservations.d.ts.map +1 -0
  47. package/dist/client/transferObservations.js +82 -0
  48. package/dist/client/transferObservations.js.map +1 -0
  49. package/dist/component/_generated/component.d.ts +687 -0
  50. package/dist/component/_generated/component.d.ts.map +1 -1
  51. package/dist/component/affiliateRecovery/mutations.d.ts.map +1 -1
  52. package/dist/component/affiliateRecovery/mutations.js +4 -1
  53. package/dist/component/affiliateRecovery/mutations.js.map +1 -1
  54. package/dist/component/connect/mutations.d.ts.map +1 -1
  55. package/dist/component/connect/mutations.js +18 -2
  56. package/dist/component/connect/mutations.js.map +1 -1
  57. package/dist/component/connect/queries.d.ts +8 -0
  58. package/dist/component/connect/queries.d.ts.map +1 -1
  59. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  60. package/dist/component/connect/reversalClaims.js +7 -1
  61. package/dist/component/connect/reversalClaims.js.map +1 -1
  62. package/dist/component/connect/reversalReceipts.d.ts.map +1 -1
  63. package/dist/component/connect/reversalReceipts.js +2 -0
  64. package/dist/component/connect/reversalReceipts.js.map +1 -1
  65. package/dist/component/connect/schema.d.ts +11 -1
  66. package/dist/component/connect/schema.d.ts.map +1 -1
  67. package/dist/component/connect/schema.js +9 -1
  68. package/dist/component/connect/schema.js.map +1 -1
  69. package/dist/component/connect/validators.d.ts +9 -1
  70. package/dist/component/connect/validators.d.ts.map +1 -1
  71. package/dist/component/connect/validators.js +2 -0
  72. package/dist/component/connect/validators.js.map +1 -1
  73. package/dist/component/earnings/pairedAdjustment.d.ts +12 -0
  74. package/dist/component/earnings/pairedAdjustment.d.ts.map +1 -0
  75. package/dist/component/earnings/pairedAdjustment.js +46 -0
  76. package/dist/component/earnings/pairedAdjustment.js.map +1 -0
  77. package/dist/component/earnings/triggers.d.ts +546 -2
  78. package/dist/component/earnings/triggers.d.ts.map +1 -1
  79. package/dist/component/earnings/triggers.js +17 -3
  80. package/dist/component/earnings/triggers.js.map +1 -1
  81. package/dist/component/financialObservations/continuation.d.ts +7 -0
  82. package/dist/component/financialObservations/continuation.d.ts.map +1 -0
  83. package/dist/component/financialObservations/continuation.js +131 -0
  84. package/dist/component/financialObservations/continuation.js.map +1 -0
  85. package/dist/component/financialObservations/generations.d.ts +6 -0
  86. package/dist/component/financialObservations/generations.d.ts.map +1 -0
  87. package/dist/component/financialObservations/generations.js +46 -0
  88. package/dist/component/financialObservations/generations.js.map +1 -0
  89. package/dist/component/financialObservations/mutations.d.ts +62 -0
  90. package/dist/component/financialObservations/mutations.d.ts.map +1 -0
  91. package/dist/component/financialObservations/mutations.js +69 -0
  92. package/dist/component/financialObservations/mutations.js.map +1 -0
  93. package/dist/component/financialObservations/queries.d.ts +307 -0
  94. package/dist/component/financialObservations/queries.d.ts.map +1 -0
  95. package/dist/component/financialObservations/queries.js +219 -0
  96. package/dist/component/financialObservations/queries.js.map +1 -0
  97. package/dist/component/financialObservations/schema.d.ts +182 -0
  98. package/dist/component/financialObservations/schema.d.ts.map +1 -0
  99. package/dist/component/financialObservations/schema.js +53 -0
  100. package/dist/component/financialObservations/schema.js.map +1 -0
  101. package/dist/component/financialObservations/settlement.d.ts +7 -0
  102. package/dist/component/financialObservations/settlement.d.ts.map +1 -0
  103. package/dist/component/financialObservations/settlement.js +118 -0
  104. package/dist/component/financialObservations/settlement.js.map +1 -0
  105. package/dist/component/financialObservations/settlementHelpers.d.ts +46 -0
  106. package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -0
  107. package/dist/component/financialObservations/settlementHelpers.js +70 -0
  108. package/dist/component/financialObservations/settlementHelpers.js.map +1 -0
  109. package/dist/component/financialObservations/transferBatches.d.ts +12 -0
  110. package/dist/component/financialObservations/transferBatches.d.ts.map +1 -0
  111. package/dist/component/financialObservations/transferBatches.js +76 -0
  112. package/dist/component/financialObservations/transferBatches.js.map +1 -0
  113. package/dist/component/financialObservations/transferContinuation.d.ts +5 -0
  114. package/dist/component/financialObservations/transferContinuation.d.ts.map +1 -0
  115. package/dist/component/financialObservations/transferContinuation.js +35 -0
  116. package/dist/component/financialObservations/transferContinuation.js.map +1 -0
  117. package/dist/component/financialObservations/transferContinuationState.d.ts +8 -0
  118. package/dist/component/financialObservations/transferContinuationState.d.ts.map +1 -0
  119. package/dist/component/financialObservations/transferContinuationState.js +69 -0
  120. package/dist/component/financialObservations/transferContinuationState.js.map +1 -0
  121. package/dist/component/financialObservations/transferContinuationSteps.d.ts +5 -0
  122. package/dist/component/financialObservations/transferContinuationSteps.d.ts.map +1 -0
  123. package/dist/component/financialObservations/transferContinuationSteps.js +174 -0
  124. package/dist/component/financialObservations/transferContinuationSteps.js.map +1 -0
  125. package/dist/component/financialObservations/transferHelpers.d.ts +18 -0
  126. package/dist/component/financialObservations/transferHelpers.d.ts.map +1 -0
  127. package/dist/component/financialObservations/transferHelpers.js +37 -0
  128. package/dist/component/financialObservations/transferHelpers.js.map +1 -0
  129. package/dist/component/financialObservations/transferReferenceSchema.d.ts +56 -0
  130. package/dist/component/financialObservations/transferReferenceSchema.d.ts.map +1 -0
  131. package/dist/component/financialObservations/transferReferenceSchema.js +21 -0
  132. package/dist/component/financialObservations/transferReferenceSchema.js.map +1 -0
  133. package/dist/component/financialObservations/transferSchema.d.ts +237 -0
  134. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -0
  135. package/dist/component/financialObservations/transferSchema.js +65 -0
  136. package/dist/component/financialObservations/transferSchema.js.map +1 -0
  137. package/dist/component/financialObservations/transfers.d.ts +7 -0
  138. package/dist/component/financialObservations/transfers.d.ts.map +1 -0
  139. package/dist/component/financialObservations/transfers.js +79 -0
  140. package/dist/component/financialObservations/transfers.js.map +1 -0
  141. package/dist/component/financialOwnership/helpers.d.ts +37 -0
  142. package/dist/component/financialOwnership/helpers.d.ts.map +1 -0
  143. package/dist/component/financialOwnership/helpers.js +76 -0
  144. package/dist/component/financialOwnership/helpers.js.map +1 -0
  145. package/dist/component/financialOwnership/mutations.d.ts +28 -0
  146. package/dist/component/financialOwnership/mutations.d.ts.map +1 -0
  147. package/dist/component/financialOwnership/mutations.js +74 -0
  148. package/dist/component/financialOwnership/mutations.js.map +1 -0
  149. package/dist/component/financialOwnership/queries.d.ts +57 -0
  150. package/dist/component/financialOwnership/queries.d.ts.map +1 -0
  151. package/dist/component/financialOwnership/queries.js +50 -0
  152. package/dist/component/financialOwnership/queries.js.map +1 -0
  153. package/dist/component/financialOwnership/schema.d.ts +140 -0
  154. package/dist/component/financialOwnership/schema.d.ts.map +1 -0
  155. package/dist/component/financialOwnership/schema.js +35 -0
  156. package/dist/component/financialOwnership/schema.js.map +1 -0
  157. package/dist/component/operationEvidence/canonical.d.ts +4 -0
  158. package/dist/component/operationEvidence/canonical.d.ts.map +1 -0
  159. package/dist/component/operationEvidence/canonical.js +8 -0
  160. package/dist/component/operationEvidence/canonical.js.map +1 -0
  161. package/dist/component/operationEvidence/helpers.d.ts +87 -0
  162. package/dist/component/operationEvidence/helpers.d.ts.map +1 -0
  163. package/dist/component/operationEvidence/helpers.js +49 -0
  164. package/dist/component/operationEvidence/helpers.js.map +1 -0
  165. package/dist/component/operationEvidence/maintenance.d.ts +88 -0
  166. package/dist/component/operationEvidence/maintenance.d.ts.map +1 -0
  167. package/dist/component/operationEvidence/maintenance.js +59 -0
  168. package/dist/component/operationEvidence/maintenance.js.map +1 -0
  169. package/dist/component/operationEvidence/mutations.d.ts +97 -0
  170. package/dist/component/operationEvidence/mutations.d.ts.map +1 -0
  171. package/dist/component/operationEvidence/mutations.js +14 -0
  172. package/dist/component/operationEvidence/mutations.js.map +1 -0
  173. package/dist/component/operationEvidence/queries.d.ts +205 -0
  174. package/dist/component/operationEvidence/queries.d.ts.map +1 -0
  175. package/dist/component/operationEvidence/queries.js +75 -0
  176. package/dist/component/operationEvidence/queries.js.map +1 -0
  177. package/dist/component/operationEvidence/schema.d.ts +536 -0
  178. package/dist/component/operationEvidence/schema.d.ts.map +1 -0
  179. package/dist/component/operationEvidence/schema.js +53 -0
  180. package/dist/component/operationEvidence/schema.js.map +1 -0
  181. package/dist/component/refundHistory/commandBinding.d.ts +17 -0
  182. package/dist/component/refundHistory/commandBinding.d.ts.map +1 -0
  183. package/dist/component/refundHistory/commandBinding.js +41 -0
  184. package/dist/component/refundHistory/commandBinding.js.map +1 -0
  185. package/dist/component/refundHistory/commandEvidence.d.ts +50 -0
  186. package/dist/component/refundHistory/commandEvidence.d.ts.map +1 -0
  187. package/dist/component/refundHistory/commandEvidence.js +58 -0
  188. package/dist/component/refundHistory/commandEvidence.js.map +1 -0
  189. package/dist/component/refundHistory/commandEvidenceValidator.d.ts +89 -0
  190. package/dist/component/refundHistory/commandEvidenceValidator.d.ts.map +1 -0
  191. package/dist/component/refundHistory/commandEvidenceValidator.js +8 -0
  192. package/dist/component/refundHistory/commandEvidenceValidator.js.map +1 -0
  193. package/dist/component/refundHistory/commandFields.d.ts +8 -0
  194. package/dist/component/refundHistory/commandFields.d.ts.map +1 -0
  195. package/dist/component/refundHistory/commandFields.js +9 -0
  196. package/dist/component/refundHistory/commandFields.js.map +1 -0
  197. package/dist/component/refundHistory/mutations.d.ts +8 -0
  198. package/dist/component/refundHistory/mutations.d.ts.map +1 -0
  199. package/dist/component/refundHistory/mutations.js +25 -0
  200. package/dist/component/refundHistory/mutations.js.map +1 -0
  201. package/dist/component/refundHistory/originalSeller.d.ts +5 -0
  202. package/dist/component/refundHistory/originalSeller.d.ts.map +1 -0
  203. package/dist/component/refundHistory/originalSeller.js +35 -0
  204. package/dist/component/refundHistory/originalSeller.js.map +1 -0
  205. package/dist/component/refundHistory/queries.d.ts +51 -0
  206. package/dist/component/refundHistory/queries.d.ts.map +1 -1
  207. package/dist/component/refundHistory/queries.js +14 -0
  208. package/dist/component/refundHistory/queries.js.map +1 -1
  209. package/dist/component/schema.d.ts +332 -1
  210. package/dist/component/schema.js +15 -0
  211. package/dist/component/schema.js.map +1 -1
  212. package/dist/component/settlement/mutations.d.ts.map +1 -1
  213. package/dist/component/settlement/mutations.js +5 -1
  214. package/dist/component/settlement/mutations.js.map +1 -1
  215. package/dist/shared/refundCommandScope.d.ts +10 -0
  216. package/dist/shared/refundCommandScope.d.ts.map +1 -0
  217. package/dist/shared/refundCommandScope.js +9 -0
  218. package/dist/shared/refundCommandScope.js.map +1 -0
  219. package/docs/financial-observations.md +244 -0
  220. package/docs/financial-ownership.md +54 -0
  221. package/docs/refund-command-evidence.md +55 -0
  222. package/package.json +5 -2
  223. package/src/client/connect/refundCommandEvidence.ts +41 -0
  224. package/src/client/connect/refundCommandNormalization.ts +28 -0
  225. package/src/client/financialObservations.test.ts +109 -0
  226. package/src/client/financialObservations.ts +106 -0
  227. package/src/client/financialOwnership.test.ts +80 -0
  228. package/src/client/financialOwnership.ts +116 -0
  229. package/src/client/index.ts +2 -2
  230. package/src/client/observationPagination.ts +11 -0
  231. package/src/client/operationEvidence.test.ts +110 -0
  232. package/src/client/operationEvidence.ts +92 -0
  233. package/src/client/publicTypes.ts +45 -0
  234. package/src/client/readContracts.ts +25 -0
  235. package/src/client/refund-command-evidence.test.ts +68 -0
  236. package/src/client/refund-command-normalization.test.ts +61 -0
  237. package/src/client/transferContinuation.test.ts +94 -0
  238. package/src/client/transferObservations.test.ts +98 -0
  239. package/src/client/transferObservations.ts +180 -0
  240. package/src/component/_generated/api.ts +54 -0
  241. package/src/component/_generated/component.ts +797 -0
  242. package/src/component/affiliateRecovery/mutations.ts +10 -1
  243. package/src/component/connect/mutations.ts +29 -2
  244. package/src/component/connect/reversalClaims.ts +19 -1
  245. package/src/component/connect/reversalReceipts.ts +2 -0
  246. package/src/component/connect/schema.ts +9 -1
  247. package/src/component/connect/validators.ts +2 -0
  248. package/src/component/core/reset.test.ts +8 -1
  249. package/src/component/earnings/earnings-totals.test.ts +14 -10
  250. package/src/component/earnings/paired-adjustment.test.ts +258 -0
  251. package/src/component/earnings/pairedAdjustment.ts +77 -0
  252. package/src/component/earnings/triggers.ts +23 -11
  253. package/src/component/financialObservations/continuation.test.ts +445 -0
  254. package/src/component/financialObservations/continuation.ts +159 -0
  255. package/src/component/financialObservations/generations.ts +53 -0
  256. package/src/component/financialObservations/mutations.ts +75 -0
  257. package/src/component/financialObservations/observation-boundaries.test.ts +466 -0
  258. package/src/component/financialObservations/queries.ts +246 -0
  259. package/src/component/financialObservations/schema.ts +68 -0
  260. package/src/component/financialObservations/settlement-observations.test.ts +86 -0
  261. package/src/component/financialObservations/settlement.ts +142 -0
  262. package/src/component/financialObservations/settlementHelpers.ts +92 -0
  263. package/src/component/financialObservations/transfer-batches.test.ts +61 -0
  264. package/src/component/financialObservations/transfer-boundaries.test.ts +116 -0
  265. package/src/component/financialObservations/transfer-continuation-guards.test.ts +428 -0
  266. package/src/component/financialObservations/transfer-continuation.test.ts +154 -0
  267. package/src/component/financialObservations/transfer-observations.test.ts +212 -0
  268. package/src/component/financialObservations/transfer-overflow.test.ts +181 -0
  269. package/src/component/financialObservations/transfer-writers.test.ts +162 -0
  270. package/src/component/financialObservations/transferBatches.ts +96 -0
  271. package/src/component/financialObservations/transferContinuation.ts +53 -0
  272. package/src/component/financialObservations/transferContinuationState.ts +85 -0
  273. package/src/component/financialObservations/transferContinuationSteps.ts +232 -0
  274. package/src/component/financialObservations/transferHelpers.ts +38 -0
  275. package/src/component/financialObservations/transferReferenceSchema.ts +20 -0
  276. package/src/component/financialObservations/transferSchema.ts +74 -0
  277. package/src/component/financialObservations/transfers.ts +99 -0
  278. package/src/component/financialOwnership/financial-ownership.test.ts +102 -0
  279. package/src/component/financialOwnership/helpers.ts +98 -0
  280. package/src/component/financialOwnership/mutations.ts +83 -0
  281. package/src/component/financialOwnership/ownership-boundaries.test.ts +308 -0
  282. package/src/component/financialOwnership/queries.ts +65 -0
  283. package/src/component/financialOwnership/schema.ts +35 -0
  284. package/src/component/operationEvidence/canonical.ts +10 -0
  285. package/src/component/operationEvidence/helpers.ts +65 -0
  286. package/src/component/operationEvidence/integrity.test.ts +257 -0
  287. package/src/component/operationEvidence/maintenance.test.ts +152 -0
  288. package/src/component/operationEvidence/maintenance.ts +89 -0
  289. package/src/component/operationEvidence/mutations.ts +14 -0
  290. package/src/component/operationEvidence/queries.ts +108 -0
  291. package/src/component/operationEvidence/reads.test.ts +140 -0
  292. package/src/component/operationEvidence/schema.ts +62 -0
  293. package/src/component/refundHistory/command-evidence.test.ts +288 -0
  294. package/src/component/refundHistory/command-normalization-resource.test.ts +77 -0
  295. package/src/component/refundHistory/command-normalization.test.ts +229 -0
  296. package/src/component/refundHistory/command-provenance.test.ts +59 -0
  297. package/src/component/refundHistory/commandBinding.ts +54 -0
  298. package/src/component/refundHistory/commandEvidence.ts +76 -0
  299. package/src/component/refundHistory/commandEvidenceValidator.ts +18 -0
  300. package/src/component/refundHistory/commandFields.ts +9 -0
  301. package/src/component/refundHistory/mutations.ts +33 -0
  302. package/src/component/refundHistory/original-seller-boundaries.test.ts +138 -0
  303. package/src/component/refundHistory/original-seller.test.ts +175 -0
  304. package/src/component/refundHistory/originalSeller.ts +48 -0
  305. package/src/component/refundHistory/queries.ts +15 -0
  306. package/src/component/schema.ts +28 -0
  307. package/src/component/settlement/mutations.ts +5 -1
  308. 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.34.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/personal-account-mapping.md"
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
+ });