@fantastic.dev/better-stripe 0.34.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 (258) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +486 -2
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +243 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +486 -2
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +243 -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/publicTypes.d.ts +5 -0
  36. package/dist/client/publicTypes.d.ts.map +1 -1
  37. package/dist/client/readContracts.d.ts +29 -0
  38. package/dist/client/readContracts.d.ts.map +1 -1
  39. package/dist/client/readContracts.js +10 -0
  40. package/dist/client/readContracts.js.map +1 -1
  41. package/dist/client/transferObservations.d.ts +59 -0
  42. package/dist/client/transferObservations.d.ts.map +1 -0
  43. package/dist/client/transferObservations.js +82 -0
  44. package/dist/client/transferObservations.js.map +1 -0
  45. package/dist/component/_generated/component.d.ts +506 -0
  46. package/dist/component/_generated/component.d.ts.map +1 -1
  47. package/dist/component/affiliateRecovery/mutations.d.ts.map +1 -1
  48. package/dist/component/affiliateRecovery/mutations.js +4 -1
  49. package/dist/component/affiliateRecovery/mutations.js.map +1 -1
  50. package/dist/component/connect/mutations.d.ts.map +1 -1
  51. package/dist/component/connect/mutations.js +18 -2
  52. package/dist/component/connect/mutations.js.map +1 -1
  53. package/dist/component/connect/queries.d.ts +8 -0
  54. package/dist/component/connect/queries.d.ts.map +1 -1
  55. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  56. package/dist/component/connect/reversalClaims.js +7 -1
  57. package/dist/component/connect/reversalClaims.js.map +1 -1
  58. package/dist/component/connect/reversalReceipts.d.ts.map +1 -1
  59. package/dist/component/connect/reversalReceipts.js +2 -0
  60. package/dist/component/connect/reversalReceipts.js.map +1 -1
  61. package/dist/component/connect/schema.d.ts +11 -1
  62. package/dist/component/connect/schema.d.ts.map +1 -1
  63. package/dist/component/connect/schema.js +9 -1
  64. package/dist/component/connect/schema.js.map +1 -1
  65. package/dist/component/connect/validators.d.ts +9 -1
  66. package/dist/component/connect/validators.d.ts.map +1 -1
  67. package/dist/component/connect/validators.js +2 -0
  68. package/dist/component/connect/validators.js.map +1 -1
  69. package/dist/component/earnings/triggers.d.ts +426 -2
  70. package/dist/component/earnings/triggers.d.ts.map +1 -1
  71. package/dist/component/earnings/triggers.js +7 -1
  72. package/dist/component/earnings/triggers.js.map +1 -1
  73. package/dist/component/financialObservations/continuation.d.ts +7 -0
  74. package/dist/component/financialObservations/continuation.d.ts.map +1 -0
  75. package/dist/component/financialObservations/continuation.js +131 -0
  76. package/dist/component/financialObservations/continuation.js.map +1 -0
  77. package/dist/component/financialObservations/generations.d.ts +6 -0
  78. package/dist/component/financialObservations/generations.d.ts.map +1 -0
  79. package/dist/component/financialObservations/generations.js +46 -0
  80. package/dist/component/financialObservations/generations.js.map +1 -0
  81. package/dist/component/financialObservations/mutations.d.ts +62 -0
  82. package/dist/component/financialObservations/mutations.d.ts.map +1 -0
  83. package/dist/component/financialObservations/mutations.js +69 -0
  84. package/dist/component/financialObservations/mutations.js.map +1 -0
  85. package/dist/component/financialObservations/queries.d.ts +307 -0
  86. package/dist/component/financialObservations/queries.d.ts.map +1 -0
  87. package/dist/component/financialObservations/queries.js +219 -0
  88. package/dist/component/financialObservations/queries.js.map +1 -0
  89. package/dist/component/financialObservations/schema.d.ts +182 -0
  90. package/dist/component/financialObservations/schema.d.ts.map +1 -0
  91. package/dist/component/financialObservations/schema.js +53 -0
  92. package/dist/component/financialObservations/schema.js.map +1 -0
  93. package/dist/component/financialObservations/settlement.d.ts +7 -0
  94. package/dist/component/financialObservations/settlement.d.ts.map +1 -0
  95. package/dist/component/financialObservations/settlement.js +118 -0
  96. package/dist/component/financialObservations/settlement.js.map +1 -0
  97. package/dist/component/financialObservations/settlementHelpers.d.ts +46 -0
  98. package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -0
  99. package/dist/component/financialObservations/settlementHelpers.js +70 -0
  100. package/dist/component/financialObservations/settlementHelpers.js.map +1 -0
  101. package/dist/component/financialObservations/transferBatches.d.ts +12 -0
  102. package/dist/component/financialObservations/transferBatches.d.ts.map +1 -0
  103. package/dist/component/financialObservations/transferBatches.js +76 -0
  104. package/dist/component/financialObservations/transferBatches.js.map +1 -0
  105. package/dist/component/financialObservations/transferContinuation.d.ts +5 -0
  106. package/dist/component/financialObservations/transferContinuation.d.ts.map +1 -0
  107. package/dist/component/financialObservations/transferContinuation.js +35 -0
  108. package/dist/component/financialObservations/transferContinuation.js.map +1 -0
  109. package/dist/component/financialObservations/transferContinuationState.d.ts +8 -0
  110. package/dist/component/financialObservations/transferContinuationState.d.ts.map +1 -0
  111. package/dist/component/financialObservations/transferContinuationState.js +69 -0
  112. package/dist/component/financialObservations/transferContinuationState.js.map +1 -0
  113. package/dist/component/financialObservations/transferContinuationSteps.d.ts +5 -0
  114. package/dist/component/financialObservations/transferContinuationSteps.d.ts.map +1 -0
  115. package/dist/component/financialObservations/transferContinuationSteps.js +174 -0
  116. package/dist/component/financialObservations/transferContinuationSteps.js.map +1 -0
  117. package/dist/component/financialObservations/transferHelpers.d.ts +18 -0
  118. package/dist/component/financialObservations/transferHelpers.d.ts.map +1 -0
  119. package/dist/component/financialObservations/transferHelpers.js +37 -0
  120. package/dist/component/financialObservations/transferHelpers.js.map +1 -0
  121. package/dist/component/financialObservations/transferReferenceSchema.d.ts +56 -0
  122. package/dist/component/financialObservations/transferReferenceSchema.d.ts.map +1 -0
  123. package/dist/component/financialObservations/transferReferenceSchema.js +21 -0
  124. package/dist/component/financialObservations/transferReferenceSchema.js.map +1 -0
  125. package/dist/component/financialObservations/transferSchema.d.ts +237 -0
  126. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -0
  127. package/dist/component/financialObservations/transferSchema.js +65 -0
  128. package/dist/component/financialObservations/transferSchema.js.map +1 -0
  129. package/dist/component/financialObservations/transfers.d.ts +7 -0
  130. package/dist/component/financialObservations/transfers.d.ts.map +1 -0
  131. package/dist/component/financialObservations/transfers.js +79 -0
  132. package/dist/component/financialObservations/transfers.js.map +1 -0
  133. package/dist/component/financialOwnership/helpers.d.ts +37 -0
  134. package/dist/component/financialOwnership/helpers.d.ts.map +1 -0
  135. package/dist/component/financialOwnership/helpers.js +76 -0
  136. package/dist/component/financialOwnership/helpers.js.map +1 -0
  137. package/dist/component/financialOwnership/mutations.d.ts +28 -0
  138. package/dist/component/financialOwnership/mutations.d.ts.map +1 -0
  139. package/dist/component/financialOwnership/mutations.js +74 -0
  140. package/dist/component/financialOwnership/mutations.js.map +1 -0
  141. package/dist/component/financialOwnership/queries.d.ts +57 -0
  142. package/dist/component/financialOwnership/queries.d.ts.map +1 -0
  143. package/dist/component/financialOwnership/queries.js +50 -0
  144. package/dist/component/financialOwnership/queries.js.map +1 -0
  145. package/dist/component/financialOwnership/schema.d.ts +140 -0
  146. package/dist/component/financialOwnership/schema.d.ts.map +1 -0
  147. package/dist/component/financialOwnership/schema.js +35 -0
  148. package/dist/component/financialOwnership/schema.js.map +1 -0
  149. package/dist/component/payoutRelease/queries.d.ts +2 -2
  150. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  151. package/dist/component/refundHistory/commandBinding.d.ts +17 -0
  152. package/dist/component/refundHistory/commandBinding.d.ts.map +1 -0
  153. package/dist/component/refundHistory/commandBinding.js +41 -0
  154. package/dist/component/refundHistory/commandBinding.js.map +1 -0
  155. package/dist/component/refundHistory/commandEvidence.d.ts +50 -0
  156. package/dist/component/refundHistory/commandEvidence.d.ts.map +1 -0
  157. package/dist/component/refundHistory/commandEvidence.js +54 -0
  158. package/dist/component/refundHistory/commandEvidence.js.map +1 -0
  159. package/dist/component/refundHistory/commandEvidenceValidator.d.ts +89 -0
  160. package/dist/component/refundHistory/commandEvidenceValidator.d.ts.map +1 -0
  161. package/dist/component/refundHistory/commandEvidenceValidator.js +8 -0
  162. package/dist/component/refundHistory/commandEvidenceValidator.js.map +1 -0
  163. package/dist/component/refundHistory/commandFields.d.ts +8 -0
  164. package/dist/component/refundHistory/commandFields.d.ts.map +1 -0
  165. package/dist/component/refundHistory/commandFields.js +9 -0
  166. package/dist/component/refundHistory/commandFields.js.map +1 -0
  167. package/dist/component/refundHistory/mutations.d.ts +8 -0
  168. package/dist/component/refundHistory/mutations.d.ts.map +1 -0
  169. package/dist/component/refundHistory/mutations.js +25 -0
  170. package/dist/component/refundHistory/mutations.js.map +1 -0
  171. package/dist/component/refundHistory/queries.d.ts +51 -0
  172. package/dist/component/refundHistory/queries.d.ts.map +1 -1
  173. package/dist/component/refundHistory/queries.js +14 -0
  174. package/dist/component/refundHistory/queries.js.map +1 -1
  175. package/dist/component/schema.d.ts +243 -1
  176. package/dist/component/schema.js +12 -0
  177. package/dist/component/schema.js.map +1 -1
  178. package/dist/component/settlement/mutations.d.ts.map +1 -1
  179. package/dist/component/settlement/mutations.js +5 -1
  180. package/dist/component/settlement/mutations.js.map +1 -1
  181. package/dist/shared/refundCommandScope.d.ts +10 -0
  182. package/dist/shared/refundCommandScope.d.ts.map +1 -0
  183. package/dist/shared/refundCommandScope.js +9 -0
  184. package/dist/shared/refundCommandScope.js.map +1 -0
  185. package/docs/financial-observations.md +159 -0
  186. package/docs/financial-ownership.md +54 -0
  187. package/docs/refund-command-evidence.md +49 -0
  188. package/package.json +5 -2
  189. package/src/client/connect/refundCommandEvidence.ts +41 -0
  190. package/src/client/connect/refundCommandNormalization.ts +28 -0
  191. package/src/client/financialObservations.test.ts +109 -0
  192. package/src/client/financialObservations.ts +106 -0
  193. package/src/client/financialOwnership.test.ts +80 -0
  194. package/src/client/financialOwnership.ts +116 -0
  195. package/src/client/index.ts +2 -2
  196. package/src/client/observationPagination.ts +11 -0
  197. package/src/client/publicTypes.ts +37 -0
  198. package/src/client/readContracts.ts +21 -0
  199. package/src/client/refund-command-evidence.test.ts +68 -0
  200. package/src/client/refund-command-normalization.test.ts +61 -0
  201. package/src/client/transferContinuation.test.ts +94 -0
  202. package/src/client/transferObservations.test.ts +98 -0
  203. package/src/client/transferObservations.ts +180 -0
  204. package/src/component/_generated/api.ts +44 -0
  205. package/src/component/_generated/component.ts +590 -0
  206. package/src/component/affiliateRecovery/mutations.ts +10 -1
  207. package/src/component/connect/mutations.ts +29 -2
  208. package/src/component/connect/reversalClaims.ts +19 -1
  209. package/src/component/connect/reversalReceipts.ts +2 -0
  210. package/src/component/connect/schema.ts +9 -1
  211. package/src/component/connect/validators.ts +2 -0
  212. package/src/component/core/reset.test.ts +8 -1
  213. package/src/component/earnings/earnings-totals.test.ts +14 -10
  214. package/src/component/earnings/triggers.ts +9 -1
  215. package/src/component/financialObservations/continuation.test.ts +445 -0
  216. package/src/component/financialObservations/continuation.ts +159 -0
  217. package/src/component/financialObservations/generations.ts +53 -0
  218. package/src/component/financialObservations/mutations.ts +75 -0
  219. package/src/component/financialObservations/observation-boundaries.test.ts +466 -0
  220. package/src/component/financialObservations/queries.ts +246 -0
  221. package/src/component/financialObservations/schema.ts +68 -0
  222. package/src/component/financialObservations/settlement-observations.test.ts +86 -0
  223. package/src/component/financialObservations/settlement.ts +142 -0
  224. package/src/component/financialObservations/settlementHelpers.ts +92 -0
  225. package/src/component/financialObservations/transfer-batches.test.ts +61 -0
  226. package/src/component/financialObservations/transfer-boundaries.test.ts +116 -0
  227. package/src/component/financialObservations/transfer-continuation-guards.test.ts +428 -0
  228. package/src/component/financialObservations/transfer-continuation.test.ts +154 -0
  229. package/src/component/financialObservations/transfer-observations.test.ts +212 -0
  230. package/src/component/financialObservations/transfer-overflow.test.ts +181 -0
  231. package/src/component/financialObservations/transfer-writers.test.ts +162 -0
  232. package/src/component/financialObservations/transferBatches.ts +96 -0
  233. package/src/component/financialObservations/transferContinuation.ts +53 -0
  234. package/src/component/financialObservations/transferContinuationState.ts +85 -0
  235. package/src/component/financialObservations/transferContinuationSteps.ts +232 -0
  236. package/src/component/financialObservations/transferHelpers.ts +38 -0
  237. package/src/component/financialObservations/transferReferenceSchema.ts +20 -0
  238. package/src/component/financialObservations/transferSchema.ts +74 -0
  239. package/src/component/financialObservations/transfers.ts +99 -0
  240. package/src/component/financialOwnership/financial-ownership.test.ts +102 -0
  241. package/src/component/financialOwnership/helpers.ts +98 -0
  242. package/src/component/financialOwnership/mutations.ts +83 -0
  243. package/src/component/financialOwnership/ownership-boundaries.test.ts +308 -0
  244. package/src/component/financialOwnership/queries.ts +65 -0
  245. package/src/component/financialOwnership/schema.ts +35 -0
  246. package/src/component/refundHistory/command-evidence.test.ts +288 -0
  247. package/src/component/refundHistory/command-normalization-resource.test.ts +77 -0
  248. package/src/component/refundHistory/command-normalization.test.ts +229 -0
  249. package/src/component/refundHistory/command-provenance.test.ts +59 -0
  250. package/src/component/refundHistory/commandBinding.ts +54 -0
  251. package/src/component/refundHistory/commandEvidence.ts +71 -0
  252. package/src/component/refundHistory/commandEvidenceValidator.ts +18 -0
  253. package/src/component/refundHistory/commandFields.ts +9 -0
  254. package/src/component/refundHistory/mutations.ts +33 -0
  255. package/src/component/refundHistory/queries.ts +15 -0
  256. package/src/component/schema.ts +22 -0
  257. package/src/component/settlement/mutations.ts +5 -1
  258. package/src/shared/refundCommandScope.ts +19 -0
@@ -0,0 +1,85 @@
1
+ import type { Doc } from "../_generated/dataModel.js";
2
+ import type { MutationCtx } from "../_generated/server.js";
3
+ import { observationGeneration } from "./generations.js";
4
+ import {
5
+ transferFingerprint,
6
+ transferProducerScope,
7
+ } from "./transferHelpers.js";
8
+ export type TransferBatch = Doc<"financialTransferBatches">;
9
+ export const transferReferenceBatchLimit = 50;
10
+ export function transferBatchFingerprint(marker: TransferBatch) {
11
+ return transferFingerprint({
12
+ originalOperationId: marker.originalOperationId,
13
+ operationId: marker.operationId,
14
+ sourceChargeId: marker.sourceChargeId,
15
+ producer: marker.producer,
16
+ producerVersion: marker.producerVersion,
17
+ fingerprint: marker.fingerprint,
18
+ referenceCount: marker.referenceCount,
19
+ transferIds: marker.transferIds,
20
+ });
21
+ }
22
+ export async function holdTransferBatch(
23
+ ctx: MutationCtx,
24
+ marker: TransferBatch,
25
+ nextReference = marker.continuation?.nextReference ?? 0,
26
+ ) {
27
+ const cursor = marker.continuation ?? {
28
+ state: "indexing" as const,
29
+ nextReference: 0,
30
+ validatedReferences: 0,
31
+ producerGeneration:
32
+ (await observationGeneration(ctx, transferProducerScope)) ?? 0,
33
+ sourceFingerprint: await transferBatchFingerprint(marker),
34
+ };
35
+ await ctx.db.patch("financialTransferBatches", marker._id, {
36
+ generation: Number.isSafeInteger(marker.generation + 1)
37
+ ? marker.generation + 1
38
+ : 0,
39
+ state: "pending",
40
+ isContradictory: true,
41
+ continuation: { ...cursor, state: "held", nextReference },
42
+ });
43
+ }
44
+ export function isInvalidTransferCursor(
45
+ marker: TransferBatch,
46
+ fingerprint: string,
47
+ ) {
48
+ const c = marker.continuation;
49
+ const count = marker.referenceCount;
50
+ if (
51
+ !Number.isSafeInteger(marker.generation) ||
52
+ marker.generation < 1 ||
53
+ !Number.isSafeInteger(marker.generation + 1) ||
54
+ !Number.isSafeInteger(count) ||
55
+ count < 1 ||
56
+ count !== marker.transferIds.length ||
57
+ marker.fingerprint !== marker.observedFingerprint
58
+ )
59
+ return true;
60
+ if (!c) return marker.state !== "pending";
61
+ return (
62
+ c.sourceFingerprint !== fingerprint ||
63
+ !Number.isSafeInteger(c.nextReference) ||
64
+ c.nextReference < 0 ||
65
+ c.nextReference > count ||
66
+ !Number.isSafeInteger(c.validatedReferences) ||
67
+ c.validatedReferences < 0 ||
68
+ c.validatedReferences > c.nextReference ||
69
+ !Number.isSafeInteger(c.producerGeneration) ||
70
+ c.producerGeneration < 1 ||
71
+ (c.state === "indexing" &&
72
+ (c.nextReference >= count ||
73
+ c.validatedReferences !== 0 ||
74
+ marker.state !== "pending")) ||
75
+ (c.state === "validating" &&
76
+ (c.nextReference !== count ||
77
+ c.validatedReferences >= count ||
78
+ marker.state !== "pending")) ||
79
+ (c.state === "complete" &&
80
+ (c.nextReference !== count ||
81
+ c.validatedReferences !== count ||
82
+ marker.state !== "complete")) ||
83
+ (marker.state === "complete" && c.state !== "complete")
84
+ );
85
+ }
@@ -0,0 +1,232 @@
1
+ import type { Doc } from "../_generated/dataModel.js";
2
+ import type { MutationCtx } from "../_generated/server.js";
3
+ import {
4
+ advanceObservationGeneration,
5
+ observationGeneration,
6
+ } from "./generations.js";
7
+ import { legOwnership } from "./settlementHelpers.js";
8
+ import {
9
+ transferFingerprint,
10
+ transferIdentity,
11
+ transferProducerScope,
12
+ } from "./transferHelpers.js";
13
+ import { observeTransfer } from "./transfers.js";
14
+ import {
15
+ holdTransferBatch,
16
+ transferReferenceBatchLimit,
17
+ type TransferBatch,
18
+ } from "./transferContinuationState.js";
19
+ async function observationFor(
20
+ ctx: MutationCtx,
21
+ transferId: Doc<"transfers">["_id"],
22
+ ) {
23
+ const rows = await ctx.db
24
+ .query("financialTransferObservations")
25
+ .withIndex("by_transfer_id", (q) => q.eq("transferId", transferId))
26
+ .take(2);
27
+ return rows.length === 1 ? rows[0] : null;
28
+ }
29
+ export async function indexTransferReferences(
30
+ ctx: MutationCtx,
31
+ marker: TransferBatch,
32
+ sourceFingerprint: string,
33
+ ) {
34
+ const start = marker.continuation?.nextReference ?? 0;
35
+ const end = Math.min(
36
+ start + transferReferenceBatchLimit,
37
+ marker.referenceCount,
38
+ );
39
+ const future = await ctx.db
40
+ .query("financialTransferBatchReferences")
41
+ .withIndex("by_batch_position", (q) =>
42
+ q.eq("batchId", marker._id).gte("position", start),
43
+ )
44
+ .take(1);
45
+ if (future.length) return holdTransferBatch(ctx, marker);
46
+ const seen = new Set<string>();
47
+ const rows: Doc<"transfers">[] = [];
48
+ for (let position = start; position < end; position++) {
49
+ const id = marker.transferIds[position]!;
50
+ const previous = await ctx.db
51
+ .query("financialTransferBatchReferences")
52
+ .withIndex("by_batch_transfer", (q) =>
53
+ q.eq("batchId", marker._id).eq("transferId", id),
54
+ )
55
+ .take(1);
56
+ const row = await ctx.db.get("transfers", id);
57
+ if (
58
+ !row ||
59
+ row.sourceChargeId !== marker.sourceChargeId ||
60
+ seen.has(id) ||
61
+ previous.length
62
+ )
63
+ return holdTransferBatch(ctx, marker);
64
+ seen.add(id);
65
+ const aliases = await ctx.db
66
+ .query("transfers")
67
+ .withIndex("by_stripe_transfer_id", (q) =>
68
+ q.eq("stripeTransferId", row.stripeTransferId),
69
+ )
70
+ .take(2);
71
+ const priorRows = await ctx.db
72
+ .query("financialTransferObservations")
73
+ .withIndex("by_transfer_id", (q) => q.eq("transferId", id))
74
+ .take(2);
75
+ const prior = priorRows[0];
76
+ const ownership =
77
+ prior && !prior.registrationId
78
+ ? { ownershipStatus: prior.ownershipStatus }
79
+ : await legOwnership(
80
+ ctx,
81
+ prior?.bucketKey ?? row.destinationAccountId,
82
+ prior,
83
+ );
84
+ if (
85
+ aliases.length !== 1 ||
86
+ aliases[0]._id !== id ||
87
+ priorRows.length > 1 ||
88
+ prior?.isContradictory ||
89
+ ownership.ownershipStatus === "ambiguous" ||
90
+ ownership.ownershipStatus === "contradictory" ||
91
+ (prior &&
92
+ (!Number.isSafeInteger(prior.generation) ||
93
+ prior.generation < 1 ||
94
+ prior.generation === Number.MAX_SAFE_INTEGER ||
95
+ prior.fingerprint !==
96
+ (await transferFingerprint(transferIdentity(row)))))
97
+ )
98
+ return holdTransferBatch(ctx, marker);
99
+ rows.push(row);
100
+ }
101
+ for (let offset = 0; offset < rows.length; offset++) {
102
+ const row = rows[offset]!;
103
+ await observeTransfer(ctx, row, { preserveUnregisteredOwnership: true });
104
+ const observation = await observationFor(ctx, row._id);
105
+ if (
106
+ !observation ||
107
+ observation.isContradictory ||
108
+ observation.generation < 1
109
+ )
110
+ return holdTransferBatch(ctx, marker, start + offset);
111
+ await ctx.db.insert("financialTransferBatchReferences", {
112
+ batchId: marker._id,
113
+ position: start + offset,
114
+ transferId: row._id,
115
+ observationId: observation._id,
116
+ observationGeneration: observation.generation,
117
+ sourceFingerprint: observation.fingerprint,
118
+ observedFingerprint: observation.observedFingerprint,
119
+ ownershipFingerprint: observation.ownershipFingerprint,
120
+ });
121
+ }
122
+ const generation = await observationGeneration(ctx, transferProducerScope);
123
+ if (generation === null) return holdTransferBatch(ctx, marker, end);
124
+ await ctx.db.patch("financialTransferBatches", marker._id, {
125
+ generation: marker.generation + 1,
126
+ continuation: {
127
+ state: end === marker.referenceCount ? "validating" : "indexing",
128
+ nextReference: end,
129
+ validatedReferences: 0,
130
+ producerGeneration: generation,
131
+ sourceFingerprint,
132
+ },
133
+ });
134
+ }
135
+ async function isInvalidReference(
136
+ ctx: MutationCtx,
137
+ marker: TransferBatch,
138
+ reference: Doc<"financialTransferBatchReferences">,
139
+ position: number,
140
+ ) {
141
+ if (
142
+ reference.position !== position ||
143
+ reference.transferId !== marker.transferIds[position]
144
+ )
145
+ return true;
146
+ const duplicates = await ctx.db
147
+ .query("financialTransferBatchReferences")
148
+ .withIndex("by_batch_transfer", (q) =>
149
+ q.eq("batchId", marker._id).eq("transferId", reference.transferId),
150
+ )
151
+ .take(2);
152
+ const source = await ctx.db.get("transfers", reference.transferId);
153
+ const observation = await observationFor(ctx, reference.transferId);
154
+ if (
155
+ duplicates.length !== 1 ||
156
+ duplicates[0]._id !== reference._id ||
157
+ !source ||
158
+ source.sourceChargeId !== marker.sourceChargeId ||
159
+ !observation ||
160
+ observation._id !== reference.observationId ||
161
+ observation.isContradictory ||
162
+ observation.generation !== reference.observationGeneration ||
163
+ observation.fingerprint !== reference.sourceFingerprint ||
164
+ observation.observedFingerprint !== reference.observedFingerprint ||
165
+ observation.ownershipFingerprint !== reference.ownershipFingerprint
166
+ )
167
+ return true;
168
+ const ownershipFingerprint = await transferFingerprint({
169
+ registrationId: observation.registrationId,
170
+ userId: observation.userId,
171
+ orgId: observation.orgId,
172
+ ownershipStatus: observation.ownershipStatus,
173
+ });
174
+ if (
175
+ observation.transferId !== source._id ||
176
+ observation.stripeTransferId !== source.stripeTransferId ||
177
+ observation.bucketKey !== source.destinationAccountId ||
178
+ observation.sourceChargeId !== source.sourceChargeId ||
179
+ observation.sourceInvoiceId !== source.sourceInvoiceId ||
180
+ observation.role !== source.role ||
181
+ ownershipFingerprint !== reference.ownershipFingerprint ||
182
+ observation.ownershipStatus === "ambiguous" ||
183
+ observation.ownershipStatus === "contradictory"
184
+ )
185
+ return true;
186
+ const { totalsRecorded, ...financial } = source;
187
+ void totalsRecorded;
188
+ return (
189
+ reference.sourceFingerprint !==
190
+ (await transferFingerprint(transferIdentity(source))) ||
191
+ reference.observedFingerprint !== (await transferFingerprint(financial))
192
+ );
193
+ }
194
+ export async function validateTransferReferences(
195
+ ctx: MutationCtx,
196
+ marker: TransferBatch,
197
+ ) {
198
+ const cursor = marker.continuation!;
199
+ const start = cursor.validatedReferences;
200
+ const rows = await ctx.db
201
+ .query("financialTransferBatchReferences")
202
+ .withIndex("by_batch_position", (q) =>
203
+ q.eq("batchId", marker._id).gte("position", start),
204
+ )
205
+ .take(transferReferenceBatchLimit + 1);
206
+ const batch = rows.slice(0, transferReferenceBatchLimit);
207
+ if (
208
+ !batch.length ||
209
+ (rows.length <= transferReferenceBatchLimit &&
210
+ start + batch.length !== marker.referenceCount)
211
+ )
212
+ return holdTransferBatch(ctx, marker);
213
+ for (let i = 0; i < batch.length; i++)
214
+ if (await isInvalidReference(ctx, marker, batch[i]!, start + i))
215
+ return holdTransferBatch(ctx, marker);
216
+ const end = start + batch.length;
217
+ const isComplete = rows.length <= transferReferenceBatchLimit;
218
+ if (isComplete)
219
+ await advanceObservationGeneration(ctx, transferProducerScope);
220
+ const generation = await observationGeneration(ctx, transferProducerScope);
221
+ if (generation === null) return holdTransferBatch(ctx, marker);
222
+ await ctx.db.patch("financialTransferBatches", marker._id, {
223
+ generation: marker.generation + 1,
224
+ state: isComplete ? "complete" : "pending",
225
+ continuation: {
226
+ ...cursor,
227
+ state: isComplete ? "complete" : "validating",
228
+ validatedReferences: end,
229
+ producerGeneration: generation,
230
+ },
231
+ });
232
+ }
@@ -0,0 +1,38 @@
1
+ import { convexToJson, type JSONValue, type Value } from "convex/values";
2
+ import type { Doc } from "../_generated/dataModel.js";
3
+ import { generateIdempotencyKey } from "../lib/idempotency.js";
4
+ export const transferProducerScope = JSON.stringify([
5
+ "producer",
6
+ "transfer_fact",
7
+ 1,
8
+ ]);
9
+ function canonical(value: JSONValue): JSONValue {
10
+ if (Array.isArray(value)) return value.map(canonical);
11
+ if (value !== null && typeof value === "object")
12
+ return Object.fromEntries(
13
+ Object.entries(value)
14
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
15
+ .map(([key, child]) => [key, canonical(child)]),
16
+ );
17
+ return value;
18
+ }
19
+ export function transferFingerprint(value: Value) {
20
+ return generateIdempotencyKey("transfer-observation-v1", {
21
+ value: canonical(convexToJson(value)),
22
+ });
23
+ }
24
+ export function transferIdentity(row: Doc<"transfers">) {
25
+ return {
26
+ transferId: row._id,
27
+ createdAt: row._creationTime,
28
+ stripeTransferId: row.stripeTransferId,
29
+ sourceChargeId: row.sourceChargeId,
30
+ sourceInvoiceId: row.sourceInvoiceId,
31
+ destinationAccountId: row.destinationAccountId,
32
+ amount: row.amount,
33
+ currency: row.currency,
34
+ role: row.role,
35
+ paymentId: row.paymentId,
36
+ reinstatement: row.reinstatement,
37
+ };
38
+ }
@@ -0,0 +1,20 @@
1
+ import { defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ export const transferReferenceFields = {
4
+ batchId: v.id("financialTransferBatches"),
5
+ position: v.number(),
6
+ transferId: v.id("transfers"),
7
+ observationId: v.id("financialTransferObservations"),
8
+ observationGeneration: v.number(),
9
+ sourceFingerprint: v.string(),
10
+ observedFingerprint: v.string(),
11
+ ownershipFingerprint: v.string(),
12
+ };
13
+ export const transferReferenceDoc = v.object({
14
+ ...transferReferenceFields,
15
+ _id: v.id("financialTransferBatchReferences"),
16
+ _creationTime: v.number(),
17
+ });
18
+ export const transferBatchReferencesTable = defineTable(transferReferenceFields)
19
+ .index("by_batch_position", ["batchId", "position"])
20
+ .index("by_batch_transfer", ["batchId", "transferId"]);
@@ -0,0 +1,74 @@
1
+ import { defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ import { splitRecipientRoleValidator } from "../lib/fees.js";
4
+ import { legFields } from "./schema.js";
5
+ export const transferFields = {
6
+ transferId: v.id("transfers"),
7
+ stripeTransferId: v.string(),
8
+ sourceChargeId: v.optional(v.string()),
9
+ sourceInvoiceId: v.optional(v.string()),
10
+ bucketKey: v.string(),
11
+ role: v.optional(splitRecipientRoleValidator),
12
+ registrationId: legFields.registrationId,
13
+ userId: legFields.userId,
14
+ orgId: legFields.orgId,
15
+ ownershipStatus: legFields.ownershipStatus,
16
+ producer: v.literal("transfer_fact"),
17
+ producerVersion: v.literal(1),
18
+ fingerprint: v.string(),
19
+ observedFingerprint: v.string(),
20
+ ownershipFingerprint: v.string(),
21
+ generation: v.number(),
22
+ isContradictory: v.boolean(),
23
+ };
24
+ export const transferObservationDoc = v.object({
25
+ ...transferFields,
26
+ _id: v.id("financialTransferObservations"),
27
+ _creationTime: v.number(),
28
+ });
29
+ export const transferObservationsTable = defineTable(transferFields)
30
+ .index("by_transfer_id", ["transferId"])
31
+ .index("by_bucket_key", ["bucketKey"])
32
+ .index("by_owner", ["userId", "orgId"]);
33
+ export const transferBatchFields = {
34
+ originalOperationId: v.id("transferReversalOps"),
35
+ operationId: v.string(),
36
+ sourceChargeId: v.string(),
37
+ producer: v.union(
38
+ v.literal("transfer_frontier_release"),
39
+ v.literal("transfer_frontier_claim"),
40
+ ),
41
+ producerVersion: v.literal(1),
42
+ fingerprint: v.string(),
43
+ generation: v.number(),
44
+ observedFingerprint: v.string(),
45
+ isContradictory: v.boolean(),
46
+ referenceCount: v.number(),
47
+ transferIds: v.array(v.id("transfers")),
48
+ isOverflow: v.literal(true),
49
+ state: v.union(v.literal("pending"), v.literal("complete")),
50
+ continuation: v.optional(
51
+ v.object({
52
+ state: v.union(
53
+ v.literal("indexing"),
54
+ v.literal("validating"),
55
+ v.literal("complete"),
56
+ v.literal("held"),
57
+ ),
58
+ nextReference: v.number(),
59
+ validatedReferences: v.number(),
60
+ producerGeneration: v.number(),
61
+ sourceFingerprint: v.string(),
62
+ }),
63
+ ),
64
+ };
65
+ export const transferBatchDoc = v.object({
66
+ ...transferBatchFields,
67
+ _id: v.id("financialTransferBatches"),
68
+ _creationTime: v.number(),
69
+ });
70
+ export const transferBatchesTable = defineTable(transferBatchFields)
71
+ .index("by_original_operation_id", ["originalOperationId"])
72
+ .index("by_original_operation_producer", ["originalOperationId", "producer"])
73
+ .index("by_operation_id", ["operationId"])
74
+ .index("by_state", ["state"]);
@@ -0,0 +1,99 @@
1
+ import type { Doc } from "../_generated/dataModel.js";
2
+ import type { MutationCtx } from "../_generated/server.js";
3
+ import { advanceObservationGeneration } from "./generations.js";
4
+ import { invalidate, legOwnership } from "./settlementHelpers.js";
5
+ import {
6
+ transferFingerprint,
7
+ transferIdentity,
8
+ transferProducerScope,
9
+ } from "./transferHelpers.js";
10
+ /** Record references only; never reject or rewrite a financial source to repair diagnostics. */
11
+ export async function observeTransfer(
12
+ ctx: MutationCtx,
13
+ row: Doc<"transfers">,
14
+ options: { preserveUnregisteredOwnership?: boolean } = {},
15
+ ) {
16
+ const markers = await ctx.db
17
+ .query("financialTransferObservations")
18
+ .withIndex("by_transfer_id", (q) => q.eq("transferId", row._id))
19
+ .take(2);
20
+ if (markers.length > 1) {
21
+ await advanceObservationGeneration(ctx, transferProducerScope);
22
+ return;
23
+ }
24
+ const prior = markers[0];
25
+ const identity = await transferFingerprint(transferIdentity(row));
26
+ const { totalsRecorded, ...financial } = row;
27
+ void totalsRecorded;
28
+ const observedFingerprint = await transferFingerprint(financial);
29
+ const ownership =
30
+ options.preserveUnregisteredOwnership && prior && !prior.registrationId
31
+ ? {
32
+ registrationId: prior.registrationId,
33
+ userId: prior.userId,
34
+ orgId: prior.orgId,
35
+ ownershipStatus: prior.ownershipStatus,
36
+ }
37
+ : await legOwnership(
38
+ ctx,
39
+ prior?.bucketKey ?? row.destinationAccountId,
40
+ prior,
41
+ );
42
+ const ownershipFingerprint = await transferFingerprint(ownership);
43
+ const sourceRows = await ctx.db
44
+ .query("transfers")
45
+ .withIndex("by_stripe_transfer_id", (q) =>
46
+ q.eq("stripeTransferId", row.stripeTransferId),
47
+ )
48
+ .take(2);
49
+ const isContradictory =
50
+ sourceRows.length !== 1 ||
51
+ sourceRows[0]?._id !== row._id ||
52
+ prior?.isContradictory === true ||
53
+ (prior !== undefined && prior.fingerprint !== identity);
54
+ if (
55
+ prior?.observedFingerprint === observedFingerprint &&
56
+ prior.ownershipFingerprint === ownershipFingerprint &&
57
+ prior.isContradictory === isContradictory
58
+ )
59
+ return;
60
+ const generation = (prior?.generation ?? 0) + 1;
61
+ if (
62
+ !Number.isSafeInteger(generation) ||
63
+ generation < 1 ||
64
+ (prior && prior.generation < 1)
65
+ ) {
66
+ if (prior)
67
+ await ctx.db.patch("financialTransferObservations", prior._id, {
68
+ generation: 0,
69
+ isContradictory: true,
70
+ });
71
+ await advanceObservationGeneration(ctx, transferProducerScope);
72
+ return;
73
+ }
74
+ const fields = {
75
+ transferId: row._id,
76
+ stripeTransferId: prior?.stripeTransferId ?? row.stripeTransferId,
77
+ sourceChargeId: prior ? prior.sourceChargeId : row.sourceChargeId,
78
+ sourceInvoiceId: prior ? prior.sourceInvoiceId : row.sourceInvoiceId,
79
+ bucketKey: prior?.bucketKey ?? row.destinationAccountId,
80
+ role: prior ? prior.role : row.role,
81
+ ...ownership,
82
+ producer: "transfer_fact" as const,
83
+ producerVersion: 1 as const,
84
+ fingerprint: prior?.fingerprint ?? identity,
85
+ observedFingerprint,
86
+ ownershipFingerprint,
87
+ generation,
88
+ isContradictory,
89
+ };
90
+ if (prior)
91
+ await ctx.db.patch("financialTransferObservations", prior._id, fields);
92
+ else await ctx.db.insert("financialTransferObservations", fields);
93
+ await invalidate(ctx, [
94
+ ...(prior ? [prior] : []),
95
+ fields,
96
+ { bucketKey: row.destinationAccountId },
97
+ ]);
98
+ await advanceObservationGeneration(ctx, transferProducerScope);
99
+ }
@@ -0,0 +1,102 @@
1
+ import { convexTest } from "convex-test";
2
+ import { makeFunctionReference } from "convex/server";
3
+ import { describe, expect, it } from "vitest";
4
+
5
+ import { modules, schema } from "../../test.js";
6
+
7
+ const register = makeFunctionReference<"mutation">(
8
+ "financialOwnership/mutations:register",
9
+ );
10
+ const lookup = makeFunctionReference<"query">(
11
+ "financialOwnership/queries:lookup",
12
+ );
13
+ const discover = makeFunctionReference<"query">(
14
+ "financialOwnership/queries:discover",
15
+ );
16
+ const physical = {
17
+ bucketKey: "acct_original",
18
+ kind: "stripe_account",
19
+ userId: "user_original",
20
+ };
21
+ const logical = {
22
+ bucketKey: "unassigned:opaque:42",
23
+ kind: "logical",
24
+ userId: "user_original",
25
+ source: { integration: "host-affiliate-migration-v1", recordId: "award_42" },
26
+ };
27
+ const fixture = () => convexTest(schema, modules);
28
+
29
+ describe("immutable financial ownership provenance", () => {
30
+ it("keeps an unregistered opaque bucket unknown without guessing ownership", async () => {
31
+ const t = fixture();
32
+ expect(await t.query(lookup, { bucketKey: "user:user_original" })).toEqual({
33
+ status: "unknown",
34
+ coverage: "unknown",
35
+ });
36
+ });
37
+
38
+ it("registers verified reciprocal physical ownership but never claims coverage", async () => {
39
+ const t = fixture();
40
+ await t.run((ctx) =>
41
+ ctx.db.insert("accounts", {
42
+ stripeAccountId: "acct_original",
43
+ userId: "user_original",
44
+ onboardingStatus: "pending",
45
+ }),
46
+ );
47
+ const result = await t.mutation(register, physical);
48
+ expect(result).toMatchObject({
49
+ status: "registered",
50
+ coverage: "unknown",
51
+ registration: {
52
+ ...physical,
53
+ generation: 1,
54
+ source: { integration: "component-account" },
55
+ },
56
+ });
57
+ expect(await t.query(lookup, { bucketKey: physical.bucketKey })).toEqual(
58
+ result,
59
+ );
60
+ });
61
+
62
+ it("registers explicit logical provenance and replays without advancing generation", async () => {
63
+ const t = fixture();
64
+ const first = await t.mutation(register, logical);
65
+ expect(first).toMatchObject({
66
+ status: "registered",
67
+ coverage: "unknown",
68
+ registration: { ...logical, generation: 1 },
69
+ });
70
+ expect(await t.mutation(register, logical)).toEqual(first);
71
+ await expect(
72
+ t.mutation(register, { ...logical, userId: "user_other" }),
73
+ ).rejects.toThrow("immutable");
74
+ await expect(
75
+ t.mutation(register, {
76
+ ...logical,
77
+ source: { ...logical.source, recordId: "another_award" },
78
+ }),
79
+ ).rejects.toThrow("immutable");
80
+ });
81
+
82
+ it("discovers owner buckets with a bounded page and unknown completeness", async () => {
83
+ const t = fixture();
84
+ await t.mutation(register, logical);
85
+ const result = await t.query(discover, {
86
+ userId: logical.userId,
87
+ paginationOpts: { numItems: 1, cursor: null },
88
+ });
89
+ expect(result).toMatchObject({
90
+ coverage: "unknown",
91
+ generation: 1,
92
+ isDone: false,
93
+ page: [expect.objectContaining({ bucketKey: logical.bucketKey })],
94
+ });
95
+ expect(
96
+ await t.query(discover, {
97
+ userId: logical.userId,
98
+ paginationOpts: { numItems: 1, cursor: result.continueCursor },
99
+ }),
100
+ ).toMatchObject({ coverage: "unknown", isDone: true, page: [] });
101
+ });
102
+ });