@fantastic.dev/better-stripe 0.33.0 → 0.35.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 (314) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/README.md +30 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +522 -2
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +261 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +522 -2
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +261 -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/core/accountClosures.d.ts +15 -0
  20. package/dist/client/core/accountClosures.d.ts.map +1 -0
  21. package/dist/client/core/accountClosures.js +10 -0
  22. package/dist/client/core/accountClosures.js.map +1 -0
  23. package/dist/client/core/accounts.d.ts.map +1 -1
  24. package/dist/client/core/accounts.js +15 -23
  25. package/dist/client/core/accounts.js.map +1 -1
  26. package/dist/client/core/personalAccountMapping.d.ts +8 -0
  27. package/dist/client/core/personalAccountMapping.d.ts.map +1 -0
  28. package/dist/client/core/personalAccountMapping.js +11 -0
  29. package/dist/client/core/personalAccountMapping.js.map +1 -0
  30. package/dist/client/financialObservations.d.ts +42 -0
  31. package/dist/client/financialObservations.d.ts.map +1 -0
  32. package/dist/client/financialObservations.js +58 -0
  33. package/dist/client/financialObservations.js.map +1 -0
  34. package/dist/client/financialOwnership.d.ts +52 -0
  35. package/dist/client/financialOwnership.d.ts.map +1 -0
  36. package/dist/client/financialOwnership.js +72 -0
  37. package/dist/client/financialOwnership.js.map +1 -0
  38. package/dist/client/index.d.ts +57 -4
  39. package/dist/client/index.d.ts.map +1 -1
  40. package/dist/client/index.js +15 -2
  41. package/dist/client/index.js.map +1 -1
  42. package/dist/client/observationPagination.d.ts +10 -0
  43. package/dist/client/observationPagination.d.ts.map +1 -0
  44. package/dist/client/observationPagination.js +12 -0
  45. package/dist/client/observationPagination.js.map +1 -0
  46. package/dist/client/publicTypes.d.ts +10 -0
  47. package/dist/client/publicTypes.d.ts.map +1 -0
  48. package/dist/client/publicTypes.js +2 -0
  49. package/dist/client/publicTypes.js.map +1 -0
  50. package/dist/client/readContracts.d.ts +29 -0
  51. package/dist/client/readContracts.d.ts.map +1 -1
  52. package/dist/client/readContracts.js +10 -0
  53. package/dist/client/readContracts.js.map +1 -1
  54. package/dist/client/transferObservations.d.ts +59 -0
  55. package/dist/client/transferObservations.d.ts.map +1 -0
  56. package/dist/client/transferObservations.js +82 -0
  57. package/dist/client/transferObservations.js.map +1 -0
  58. package/dist/component/_generated/component.d.ts +594 -0
  59. package/dist/component/_generated/component.d.ts.map +1 -1
  60. package/dist/component/accountClosure/helpers.d.ts +18 -0
  61. package/dist/component/accountClosure/helpers.d.ts.map +1 -0
  62. package/dist/component/accountClosure/helpers.js +18 -0
  63. package/dist/component/accountClosure/helpers.js.map +1 -0
  64. package/dist/component/accountClosure/mutations.d.ts +20 -0
  65. package/dist/component/accountClosure/mutations.d.ts.map +1 -0
  66. package/dist/component/accountClosure/mutations.js +55 -0
  67. package/dist/component/accountClosure/mutations.js.map +1 -0
  68. package/dist/component/accountClosure/queries.d.ts +34 -0
  69. package/dist/component/accountClosure/queries.d.ts.map +1 -0
  70. package/dist/component/accountClosure/queries.js +36 -0
  71. package/dist/component/accountClosure/queries.js.map +1 -0
  72. package/dist/component/accountClosure/schema.d.ts +46 -0
  73. package/dist/component/accountClosure/schema.d.ts.map +1 -0
  74. package/dist/component/accountClosure/schema.js +20 -0
  75. package/dist/component/accountClosure/schema.js.map +1 -0
  76. package/dist/component/affiliateRecovery/mutations.d.ts.map +1 -1
  77. package/dist/component/affiliateRecovery/mutations.js +4 -1
  78. package/dist/component/affiliateRecovery/mutations.js.map +1 -1
  79. package/dist/component/connect/mutations.d.ts.map +1 -1
  80. package/dist/component/connect/mutations.js +18 -2
  81. package/dist/component/connect/mutations.js.map +1 -1
  82. package/dist/component/connect/queries.d.ts +8 -0
  83. package/dist/component/connect/queries.d.ts.map +1 -1
  84. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  85. package/dist/component/connect/reversalClaims.js +7 -1
  86. package/dist/component/connect/reversalClaims.js.map +1 -1
  87. package/dist/component/connect/reversalReceipts.d.ts.map +1 -1
  88. package/dist/component/connect/reversalReceipts.js +2 -0
  89. package/dist/component/connect/reversalReceipts.js.map +1 -1
  90. package/dist/component/connect/schema.d.ts +11 -1
  91. package/dist/component/connect/schema.d.ts.map +1 -1
  92. package/dist/component/connect/schema.js +9 -1
  93. package/dist/component/connect/schema.js.map +1 -1
  94. package/dist/component/connect/validators.d.ts +9 -1
  95. package/dist/component/connect/validators.d.ts.map +1 -1
  96. package/dist/component/connect/validators.js +2 -0
  97. package/dist/component/connect/validators.js.map +1 -1
  98. package/dist/component/core/mutations.d.ts.map +1 -1
  99. package/dist/component/core/mutations.js +5 -0
  100. package/dist/component/core/mutations.js.map +1 -1
  101. package/dist/component/core/personalAccountMapping.d.ts +95 -0
  102. package/dist/component/core/personalAccountMapping.d.ts.map +1 -0
  103. package/dist/component/core/personalAccountMapping.js +54 -0
  104. package/dist/component/core/personalAccountMapping.js.map +1 -0
  105. package/dist/component/core/queries.d.ts +27 -0
  106. package/dist/component/core/queries.d.ts.map +1 -1
  107. package/dist/component/core/queries.js +7 -0
  108. package/dist/component/core/queries.js.map +1 -1
  109. package/dist/component/earnings/triggers.d.ts +468 -2
  110. package/dist/component/earnings/triggers.d.ts.map +1 -1
  111. package/dist/component/earnings/triggers.js +7 -1
  112. package/dist/component/earnings/triggers.js.map +1 -1
  113. package/dist/component/financialObservations/continuation.d.ts +7 -0
  114. package/dist/component/financialObservations/continuation.d.ts.map +1 -0
  115. package/dist/component/financialObservations/continuation.js +131 -0
  116. package/dist/component/financialObservations/continuation.js.map +1 -0
  117. package/dist/component/financialObservations/generations.d.ts +6 -0
  118. package/dist/component/financialObservations/generations.d.ts.map +1 -0
  119. package/dist/component/financialObservations/generations.js +46 -0
  120. package/dist/component/financialObservations/generations.js.map +1 -0
  121. package/dist/component/financialObservations/mutations.d.ts +62 -0
  122. package/dist/component/financialObservations/mutations.d.ts.map +1 -0
  123. package/dist/component/financialObservations/mutations.js +69 -0
  124. package/dist/component/financialObservations/mutations.js.map +1 -0
  125. package/dist/component/financialObservations/queries.d.ts +307 -0
  126. package/dist/component/financialObservations/queries.d.ts.map +1 -0
  127. package/dist/component/financialObservations/queries.js +219 -0
  128. package/dist/component/financialObservations/queries.js.map +1 -0
  129. package/dist/component/financialObservations/schema.d.ts +182 -0
  130. package/dist/component/financialObservations/schema.d.ts.map +1 -0
  131. package/dist/component/financialObservations/schema.js +53 -0
  132. package/dist/component/financialObservations/schema.js.map +1 -0
  133. package/dist/component/financialObservations/settlement.d.ts +7 -0
  134. package/dist/component/financialObservations/settlement.d.ts.map +1 -0
  135. package/dist/component/financialObservations/settlement.js +118 -0
  136. package/dist/component/financialObservations/settlement.js.map +1 -0
  137. package/dist/component/financialObservations/settlementHelpers.d.ts +46 -0
  138. package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -0
  139. package/dist/component/financialObservations/settlementHelpers.js +70 -0
  140. package/dist/component/financialObservations/settlementHelpers.js.map +1 -0
  141. package/dist/component/financialObservations/transferBatches.d.ts +12 -0
  142. package/dist/component/financialObservations/transferBatches.d.ts.map +1 -0
  143. package/dist/component/financialObservations/transferBatches.js +76 -0
  144. package/dist/component/financialObservations/transferBatches.js.map +1 -0
  145. package/dist/component/financialObservations/transferContinuation.d.ts +5 -0
  146. package/dist/component/financialObservations/transferContinuation.d.ts.map +1 -0
  147. package/dist/component/financialObservations/transferContinuation.js +35 -0
  148. package/dist/component/financialObservations/transferContinuation.js.map +1 -0
  149. package/dist/component/financialObservations/transferContinuationState.d.ts +8 -0
  150. package/dist/component/financialObservations/transferContinuationState.d.ts.map +1 -0
  151. package/dist/component/financialObservations/transferContinuationState.js +69 -0
  152. package/dist/component/financialObservations/transferContinuationState.js.map +1 -0
  153. package/dist/component/financialObservations/transferContinuationSteps.d.ts +5 -0
  154. package/dist/component/financialObservations/transferContinuationSteps.d.ts.map +1 -0
  155. package/dist/component/financialObservations/transferContinuationSteps.js +174 -0
  156. package/dist/component/financialObservations/transferContinuationSteps.js.map +1 -0
  157. package/dist/component/financialObservations/transferHelpers.d.ts +18 -0
  158. package/dist/component/financialObservations/transferHelpers.d.ts.map +1 -0
  159. package/dist/component/financialObservations/transferHelpers.js +37 -0
  160. package/dist/component/financialObservations/transferHelpers.js.map +1 -0
  161. package/dist/component/financialObservations/transferReferenceSchema.d.ts +56 -0
  162. package/dist/component/financialObservations/transferReferenceSchema.d.ts.map +1 -0
  163. package/dist/component/financialObservations/transferReferenceSchema.js +21 -0
  164. package/dist/component/financialObservations/transferReferenceSchema.js.map +1 -0
  165. package/dist/component/financialObservations/transferSchema.d.ts +237 -0
  166. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -0
  167. package/dist/component/financialObservations/transferSchema.js +65 -0
  168. package/dist/component/financialObservations/transferSchema.js.map +1 -0
  169. package/dist/component/financialObservations/transfers.d.ts +7 -0
  170. package/dist/component/financialObservations/transfers.d.ts.map +1 -0
  171. package/dist/component/financialObservations/transfers.js +79 -0
  172. package/dist/component/financialObservations/transfers.js.map +1 -0
  173. package/dist/component/financialOwnership/helpers.d.ts +37 -0
  174. package/dist/component/financialOwnership/helpers.d.ts.map +1 -0
  175. package/dist/component/financialOwnership/helpers.js +76 -0
  176. package/dist/component/financialOwnership/helpers.js.map +1 -0
  177. package/dist/component/financialOwnership/mutations.d.ts +28 -0
  178. package/dist/component/financialOwnership/mutations.d.ts.map +1 -0
  179. package/dist/component/financialOwnership/mutations.js +74 -0
  180. package/dist/component/financialOwnership/mutations.js.map +1 -0
  181. package/dist/component/financialOwnership/queries.d.ts +57 -0
  182. package/dist/component/financialOwnership/queries.d.ts.map +1 -0
  183. package/dist/component/financialOwnership/queries.js +50 -0
  184. package/dist/component/financialOwnership/queries.js.map +1 -0
  185. package/dist/component/financialOwnership/schema.d.ts +140 -0
  186. package/dist/component/financialOwnership/schema.d.ts.map +1 -0
  187. package/dist/component/financialOwnership/schema.js +35 -0
  188. package/dist/component/financialOwnership/schema.js.map +1 -0
  189. package/dist/component/payoutRelease/queries.d.ts +2 -2
  190. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  191. package/dist/component/refundHistory/commandBinding.d.ts +17 -0
  192. package/dist/component/refundHistory/commandBinding.d.ts.map +1 -0
  193. package/dist/component/refundHistory/commandBinding.js +41 -0
  194. package/dist/component/refundHistory/commandBinding.js.map +1 -0
  195. package/dist/component/refundHistory/commandEvidence.d.ts +50 -0
  196. package/dist/component/refundHistory/commandEvidence.d.ts.map +1 -0
  197. package/dist/component/refundHistory/commandEvidence.js +54 -0
  198. package/dist/component/refundHistory/commandEvidence.js.map +1 -0
  199. package/dist/component/refundHistory/commandEvidenceValidator.d.ts +89 -0
  200. package/dist/component/refundHistory/commandEvidenceValidator.d.ts.map +1 -0
  201. package/dist/component/refundHistory/commandEvidenceValidator.js +8 -0
  202. package/dist/component/refundHistory/commandEvidenceValidator.js.map +1 -0
  203. package/dist/component/refundHistory/commandFields.d.ts +8 -0
  204. package/dist/component/refundHistory/commandFields.d.ts.map +1 -0
  205. package/dist/component/refundHistory/commandFields.js +9 -0
  206. package/dist/component/refundHistory/commandFields.js.map +1 -0
  207. package/dist/component/refundHistory/mutations.d.ts +8 -0
  208. package/dist/component/refundHistory/mutations.d.ts.map +1 -0
  209. package/dist/component/refundHistory/mutations.js +25 -0
  210. package/dist/component/refundHistory/mutations.js.map +1 -0
  211. package/dist/component/refundHistory/queries.d.ts +51 -0
  212. package/dist/component/refundHistory/queries.d.ts.map +1 -1
  213. package/dist/component/refundHistory/queries.js +14 -0
  214. package/dist/component/refundHistory/queries.js.map +1 -1
  215. package/dist/component/schema.d.ts +261 -1
  216. package/dist/component/schema.js +14 -0
  217. package/dist/component/schema.js.map +1 -1
  218. package/dist/component/settlement/mutations.d.ts.map +1 -1
  219. package/dist/component/settlement/mutations.js +5 -1
  220. package/dist/component/settlement/mutations.js.map +1 -1
  221. package/dist/shared/refundCommandScope.d.ts +10 -0
  222. package/dist/shared/refundCommandScope.d.ts.map +1 -0
  223. package/dist/shared/refundCommandScope.js +9 -0
  224. package/dist/shared/refundCommandScope.js.map +1 -0
  225. package/docs/financial-observations.md +159 -0
  226. package/docs/financial-ownership.md +54 -0
  227. package/docs/personal-account-mapping.md +54 -0
  228. package/docs/refund-command-evidence.md +49 -0
  229. package/package.json +6 -2
  230. package/src/client/connect/refundCommandEvidence.ts +41 -0
  231. package/src/client/connect/refundCommandNormalization.ts +28 -0
  232. package/src/client/core/account-close-orchestration.test.ts +131 -0
  233. package/src/client/core/account-closure.test.ts +317 -0
  234. package/src/client/core/accountClosures.ts +37 -0
  235. package/src/client/core/accounts.test.ts +0 -111
  236. package/src/client/core/accounts.ts +24 -29
  237. package/src/client/core/personal-account-mapping.test.ts +71 -0
  238. package/src/client/core/personalAccountMapping.ts +23 -0
  239. package/src/client/financialObservations.test.ts +109 -0
  240. package/src/client/financialObservations.ts +106 -0
  241. package/src/client/financialOwnership.test.ts +80 -0
  242. package/src/client/financialOwnership.ts +116 -0
  243. package/src/client/index.ts +38 -35
  244. package/src/client/observationPagination.ts +11 -0
  245. package/src/client/publicTypes.ts +72 -0
  246. package/src/client/readContracts.ts +21 -0
  247. package/src/client/refund-command-evidence.test.ts +68 -0
  248. package/src/client/refund-command-normalization.test.ts +61 -0
  249. package/src/client/transferContinuation.test.ts +94 -0
  250. package/src/client/transferObservations.test.ts +98 -0
  251. package/src/client/transferObservations.ts +180 -0
  252. package/src/component/_generated/api.ts +52 -0
  253. package/src/component/_generated/component.ts +716 -0
  254. package/src/component/accountClosure/helpers.ts +21 -0
  255. package/src/component/accountClosure/mutations.ts +56 -0
  256. package/src/component/accountClosure/queries.ts +43 -0
  257. package/src/component/accountClosure/schema.ts +20 -0
  258. package/src/component/affiliateRecovery/mutations.ts +10 -1
  259. package/src/component/connect/mutations.ts +29 -2
  260. package/src/component/connect/reversalClaims.ts +19 -1
  261. package/src/component/connect/reversalReceipts.ts +2 -0
  262. package/src/component/connect/schema.ts +9 -1
  263. package/src/component/connect/validators.ts +2 -0
  264. package/src/component/core/mutations.ts +3 -0
  265. package/src/component/core/personal-account-mapping.test.ts +173 -0
  266. package/src/component/core/personalAccountMapping.ts +81 -0
  267. package/src/component/core/queries.ts +11 -0
  268. package/src/component/core/reset.test.ts +8 -1
  269. package/src/component/earnings/earnings-totals.test.ts +14 -10
  270. package/src/component/earnings/triggers.ts +9 -1
  271. package/src/component/financialObservations/continuation.test.ts +445 -0
  272. package/src/component/financialObservations/continuation.ts +159 -0
  273. package/src/component/financialObservations/generations.ts +53 -0
  274. package/src/component/financialObservations/mutations.ts +75 -0
  275. package/src/component/financialObservations/observation-boundaries.test.ts +466 -0
  276. package/src/component/financialObservations/queries.ts +246 -0
  277. package/src/component/financialObservations/schema.ts +68 -0
  278. package/src/component/financialObservations/settlement-observations.test.ts +86 -0
  279. package/src/component/financialObservations/settlement.ts +142 -0
  280. package/src/component/financialObservations/settlementHelpers.ts +92 -0
  281. package/src/component/financialObservations/transfer-batches.test.ts +61 -0
  282. package/src/component/financialObservations/transfer-boundaries.test.ts +116 -0
  283. package/src/component/financialObservations/transfer-continuation-guards.test.ts +428 -0
  284. package/src/component/financialObservations/transfer-continuation.test.ts +154 -0
  285. package/src/component/financialObservations/transfer-observations.test.ts +212 -0
  286. package/src/component/financialObservations/transfer-overflow.test.ts +181 -0
  287. package/src/component/financialObservations/transfer-writers.test.ts +162 -0
  288. package/src/component/financialObservations/transferBatches.ts +96 -0
  289. package/src/component/financialObservations/transferContinuation.ts +53 -0
  290. package/src/component/financialObservations/transferContinuationState.ts +85 -0
  291. package/src/component/financialObservations/transferContinuationSteps.ts +232 -0
  292. package/src/component/financialObservations/transferHelpers.ts +38 -0
  293. package/src/component/financialObservations/transferReferenceSchema.ts +20 -0
  294. package/src/component/financialObservations/transferSchema.ts +74 -0
  295. package/src/component/financialObservations/transfers.ts +99 -0
  296. package/src/component/financialOwnership/financial-ownership.test.ts +102 -0
  297. package/src/component/financialOwnership/helpers.ts +98 -0
  298. package/src/component/financialOwnership/mutations.ts +83 -0
  299. package/src/component/financialOwnership/ownership-boundaries.test.ts +308 -0
  300. package/src/component/financialOwnership/queries.ts +65 -0
  301. package/src/component/financialOwnership/schema.ts +35 -0
  302. package/src/component/refundHistory/command-evidence.test.ts +288 -0
  303. package/src/component/refundHistory/command-normalization-resource.test.ts +77 -0
  304. package/src/component/refundHistory/command-normalization.test.ts +229 -0
  305. package/src/component/refundHistory/command-provenance.test.ts +59 -0
  306. package/src/component/refundHistory/commandBinding.ts +54 -0
  307. package/src/component/refundHistory/commandEvidence.ts +71 -0
  308. package/src/component/refundHistory/commandEvidenceValidator.ts +18 -0
  309. package/src/component/refundHistory/commandFields.ts +9 -0
  310. package/src/component/refundHistory/mutations.ts +33 -0
  311. package/src/component/refundHistory/queries.ts +15 -0
  312. package/src/component/schema.ts +24 -0
  313. package/src/component/settlement/mutations.ts +5 -1
  314. package/src/shared/refundCommandScope.ts +19 -0
@@ -0,0 +1,54 @@
1
+ type Existing = {
2
+ metadata?: unknown;
3
+ refundCommandKey?: string;
4
+ refundCommandConflict?: boolean;
5
+ refundCommandObservedAt?: number;
6
+ };
7
+ function keyFrom(metadata: unknown) {
8
+ if (
9
+ metadata === null ||
10
+ typeof metadata !== "object" ||
11
+ Array.isArray(metadata)
12
+ )
13
+ return { kind: "missing" as const };
14
+ const key = (metadata as Record<string, unknown>).betterStripeRefundCommand;
15
+ if (key === undefined) return { kind: "missing" as const };
16
+ return typeof key === "string" && /^[A-Za-z0-9:_-]{16,200}$/.test(key)
17
+ ? { kind: "valid" as const, key }
18
+ : { kind: "invalid" as const };
19
+ }
20
+
21
+ /** First known metadata is observed before incoming changes; it is not provider-creation provenance. */
22
+ export function refundCommandBinding(
23
+ existing: Existing | null,
24
+ incoming: { metadata?: unknown },
25
+ now: number,
26
+ ) {
27
+ const old = keyFrom(existing?.metadata);
28
+ const next = Object.prototype.hasOwnProperty.call(incoming, "metadata")
29
+ ? keyFrom(incoming.metadata)
30
+ : undefined;
31
+ const first =
32
+ existing?.refundCommandKey ?? (old.kind === "valid" ? old.key : undefined);
33
+ const key = first ?? (next?.kind === "valid" ? next.key : undefined);
34
+ const conflict =
35
+ existing?.refundCommandConflict === true ||
36
+ old.kind === "invalid" ||
37
+ next?.kind === "invalid" ||
38
+ (existing?.refundCommandKey !== undefined &&
39
+ old.kind === "valid" &&
40
+ old.key !== existing.refundCommandKey) ||
41
+ (first !== undefined &&
42
+ next !== undefined &&
43
+ (next.kind !== "valid" || next.key !== first));
44
+ return {
45
+ refundCommandNormalizationVersion: 1 as const,
46
+ refundCommandConflict: conflict,
47
+ ...(key
48
+ ? {
49
+ refundCommandKey: key,
50
+ refundCommandObservedAt: existing?.refundCommandObservedAt ?? now,
51
+ }
52
+ : {}),
53
+ };
54
+ }
@@ -0,0 +1,71 @@
1
+ import type { QueryCtx } from "../_generated/server.js";
2
+ import {
3
+ assertRefundCommandScope,
4
+ type RefundCommandScope,
5
+ } from "../../shared/refundCommandScope.js";
6
+
7
+ /** Bounded global normalization and exact-key proof, never a provider history or retry claim. */
8
+ export async function readRefundCommandEvidence(
9
+ ctx: QueryCtx,
10
+ scope: RefundCommandScope,
11
+ ) {
12
+ assertRefundCommandScope(scope);
13
+ const legacy = await ctx.db
14
+ .query("refunds")
15
+ .withIndex("by_refund_command_normalization_version", (q) =>
16
+ q.eq("refundCommandNormalizationVersion", undefined),
17
+ )
18
+ .take(1);
19
+ if (legacy.length)
20
+ return {
21
+ status: "unavailable" as const,
22
+ reason: "normalization_incomplete" as const,
23
+ };
24
+ const rows = await ctx.db
25
+ .query("refunds")
26
+ .withIndex("by_refund_command_key", (q) =>
27
+ q.eq("refundCommandKey", scope.commandKey),
28
+ )
29
+ .take(2);
30
+ if (rows.length > 1)
31
+ return { status: "unavailable" as const, reason: "ambiguous" as const };
32
+ const row = rows[0];
33
+ if (!row)
34
+ return { status: "unavailable" as const, reason: "missing" as const };
35
+ if (row.refundCommandConflict)
36
+ return {
37
+ status: "unavailable" as const,
38
+ reason: "correlation_conflict" as const,
39
+ };
40
+ if (
41
+ row.accountId !== scope.accountId ||
42
+ row.stripePaymentIntentId !== scope.stripePaymentIntentId ||
43
+ row.stripeChargeId !== scope.stripeChargeId ||
44
+ row.currency !== scope.currency
45
+ )
46
+ return {
47
+ status: "unavailable" as const,
48
+ reason: "scope_mismatch" as const,
49
+ };
50
+ if (
51
+ !/^re_[A-Za-z0-9_]{1,252}$/.test(row.stripeRefundId) ||
52
+ !Number.isSafeInteger(row.amount) ||
53
+ row.amount <= 0 ||
54
+ !Number.isSafeInteger(row.refundCommandObservedAt) ||
55
+ (row.refundCommandObservedAt ?? -1) < 0 ||
56
+ (row.refundCommandObservedAt ?? Infinity) > Date.now()
57
+ )
58
+ return {
59
+ status: "unavailable" as const,
60
+ reason: "invalid_receipt" as const,
61
+ };
62
+ const identity = await ctx.db
63
+ .query("refunds")
64
+ .withIndex("by_stripe_refund_id", (q) =>
65
+ q.eq("stripeRefundId", row.stripeRefundId),
66
+ )
67
+ .take(2);
68
+ if (identity.length !== 1 || identity[0]?._id !== row._id)
69
+ return { status: "unavailable" as const, reason: "ambiguous" as const };
70
+ return { status: "observed" as const, refund: row };
71
+ }
@@ -0,0 +1,18 @@
1
+ import { v } from "convex/values";
2
+ import { refundDocValidator } from "../connect/validators.js";
3
+
4
+ /** Observation and coverage only; no state here means provider absence or retry authority. */
5
+ export const refundCommandEvidenceValidator = v.union(
6
+ v.object({ status: v.literal("observed"), refund: refundDocValidator }),
7
+ v.object({
8
+ status: v.literal("unavailable"),
9
+ reason: v.union(
10
+ v.literal("missing"),
11
+ v.literal("normalization_incomplete"),
12
+ v.literal("ambiguous"),
13
+ v.literal("correlation_conflict"),
14
+ v.literal("scope_mismatch"),
15
+ v.literal("invalid_receipt"),
16
+ ),
17
+ }),
18
+ );
@@ -0,0 +1,9 @@
1
+ import { v } from "convex/values";
2
+
3
+ /** Correlation projection only; raw provider refund fields remain authoritative. */
4
+ export const refundCommandFields = {
5
+ refundCommandNormalizationVersion: v.optional(v.literal(1)),
6
+ refundCommandKey: v.optional(v.string()),
7
+ refundCommandConflict: v.optional(v.boolean()),
8
+ refundCommandObservedAt: v.optional(v.number()),
9
+ };
@@ -0,0 +1,33 @@
1
+ import { v } from "convex/values";
2
+ import { mutation } from "../_generated/server.js";
3
+ import { refundCommandBinding } from "./commandBinding.js";
4
+
5
+ /** Trusted-host projection backfill; completion covers current component rows, never provider history. */
6
+ export const normalizeRefundCommandBindings = mutation({
7
+ args: { limit: v.number() },
8
+ returns: v.object({ normalized: v.number(), hasMore: v.boolean() }),
9
+ handler: async (ctx, { limit }) => {
10
+ if (!Number.isInteger(limit) || limit < 1 || limit > 100)
11
+ throw new Error("Normalization limit must be an integer from 1 to 100");
12
+ const rows = await ctx.db
13
+ .query("refunds")
14
+ .withIndex("by_refund_command_normalization_version", (q) =>
15
+ q.eq("refundCommandNormalizationVersion", undefined),
16
+ )
17
+ .take(limit);
18
+ const now = Date.now();
19
+ for (const row of rows)
20
+ await ctx.db.patch(
21
+ "refunds",
22
+ row._id,
23
+ refundCommandBinding(row, {}, now),
24
+ );
25
+ const pending = await ctx.db
26
+ .query("refunds")
27
+ .withIndex("by_refund_command_normalization_version", (q) =>
28
+ q.eq("refundCommandNormalizationVersion", undefined),
29
+ )
30
+ .take(1);
31
+ return { normalized: rows.length, hasMore: pending.length > 0 };
32
+ },
33
+ });
@@ -1,3 +1,5 @@
1
+ import { refundCommandEvidenceValidator } from "./commandEvidenceValidator.js";
2
+ import { readRefundCommandEvidence } from "./commandEvidence.js";
1
3
  import {
2
4
  paginationOptsValidator,
3
5
  paginationResultValidator,
@@ -97,3 +99,16 @@ function scopedRefunds(
97
99
  return refunds.withIndex("by_status", (q) => q.eq("status", status));
98
100
  return refunds;
99
101
  }
102
+
103
+ /** Exact command evidence is read-only and never authorizes a provider retry. */
104
+ export const getRefundCommandEvidence = query({
105
+ args: {
106
+ commandKey: v.string(),
107
+ accountId: v.string(),
108
+ stripePaymentIntentId: v.string(),
109
+ stripeChargeId: v.string(),
110
+ currency: v.string(),
111
+ },
112
+ returns: refundCommandEvidenceValidator,
113
+ handler: readRefundCommandEvidence,
114
+ });
@@ -1,3 +1,18 @@
1
+ import { transferBatchReferencesTable } from "./financialObservations/transferReferenceSchema.js";
2
+ import {
3
+ transferObservationsTable,
4
+ transferBatchesTable,
5
+ } from "./financialObservations/transferSchema.js";
6
+ import {
7
+ sourceObservationsTable,
8
+ sourceLegsTable,
9
+ observationGenerationsTable,
10
+ } from "./financialObservations/schema.js";
11
+ import {
12
+ ownershipTable,
13
+ generationsTable,
14
+ } from "./financialOwnership/schema.js";
15
+ import { accountClosuresTable } from "./accountClosure/schema.js";
1
16
  import { jobsTable as payoutWorkerJobsTable } from "./payoutWorker/schema.js";
2
17
  import {
3
18
  financialRevisionsTable,
@@ -59,6 +74,14 @@ import { pricesTable, productsTable } from "./products/schema";
59
74
  import { webhookEventsTable } from "./webhooks/schema";
60
75
 
61
76
  export default defineSchema({
77
+ financialTransferObservations: transferObservationsTable,
78
+ financialTransferBatches: transferBatchesTable,
79
+ financialTransferBatchReferences: transferBatchReferencesTable,
80
+ financialSourceObservations: sourceObservationsTable,
81
+ financialSourceLegs: sourceLegsTable,
82
+ financialObservationGenerations: observationGenerationsTable,
83
+ financialOwnership: ownershipTable,
84
+ financialOwnershipGenerations: generationsTable,
62
85
  payoutWorkerJobs: payoutWorkerJobsTable,
63
86
  payoutFinancialRevisions: financialRevisionsTable,
64
87
  payoutRiskEvents: riskEventsTable,
@@ -90,6 +113,7 @@ export default defineSchema({
90
113
  commissionDecisions: commissionDecisionsTable,
91
114
  // Core
92
115
  accounts: accountsTable,
116
+ accountClosures: accountClosuresTable,
93
117
 
94
118
  // Products
95
119
  products: productsTable,
@@ -1,3 +1,4 @@
1
+ import { observeSettlementAllocation } from "../financialObservations/settlement.js";
1
2
  import { paginator } from "convex-helpers/server/pagination";
2
3
  import schema from "../schema.js";
3
4
  import { updateObligation } from "../affiliateRecovery/accounting.js";
@@ -28,6 +29,7 @@ export const reserveSettlementAllocation = mutation({
28
29
  existing.sourceInvoiceId !== args.sourceInvoiceId
29
30
  )
30
31
  throw new Error("Settlement source identity cannot change.");
32
+ await observeSettlementAllocation(ctx, existing);
31
33
  return existing;
32
34
  }
33
35
  const adjustment = args.adjustmentAmount ?? 0;
@@ -59,7 +61,9 @@ export const reserveSettlementAllocation = mutation({
59
61
  "Settlement allocation must reconcile in integer currency units with unique recipient legs.",
60
62
  );
61
63
  const id = await ctx.db.insert("settlementAllocations", args);
62
- return (await ctx.db.get("settlementAllocations", id))!;
64
+ const stored = (await ctx.db.get("settlementAllocations", id))!;
65
+ await observeSettlementAllocation(ctx, stored);
66
+ return stored;
63
67
  },
64
68
  });
65
69
  export const claimCommissionInvoice = mutation({
@@ -0,0 +1,19 @@
1
+ /** Canonical server-owned selectors. Shape validation is not host authorization or currency support. */
2
+ export type RefundCommandScope = {
3
+ commandKey: string;
4
+ accountId: string;
5
+ stripePaymentIntentId: string;
6
+ stripeChargeId: string;
7
+ currency: string;
8
+ };
9
+
10
+ export function assertRefundCommandScope(input: RefundCommandScope): void {
11
+ if (
12
+ !/^[A-Za-z0-9:_-]{16,200}$/.test(input.commandKey) ||
13
+ !/^acct_[A-Za-z0-9_]{1,128}$/.test(input.accountId) ||
14
+ !/^pi_[A-Za-z0-9_]{1,252}$/.test(input.stripePaymentIntentId) ||
15
+ !/^ch_[A-Za-z0-9_]{1,252}$/.test(input.stripeChargeId) ||
16
+ !/^[a-z]{3}$/.test(input.currency)
17
+ )
18
+ throw new Error("Invalid refund command selectors");
19
+ }