@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,246 @@
1
+ import { transferReferenceDoc } from "./transferReferenceSchema.js";
2
+ import { transferReaderState } from "./transferBatches.js";
3
+ import { transferObservationDoc, transferBatchDoc } from "./transferSchema.js";
4
+ import {
5
+ paginationOptsValidator,
6
+ paginationResultValidator,
7
+ } from "convex/server";
8
+ import { paginator } from "convex-helpers/server/pagination";
9
+ import { v } from "convex/values";
10
+ import { query } from "../_generated/server.js";
11
+ import { assertOwner, assertSelector } from "../financialOwnership/helpers.js";
12
+ import { ownerFields } from "../financialOwnership/schema.js";
13
+ import schema from "../schema.js";
14
+ import {
15
+ bucketScope,
16
+ observationGeneration,
17
+ ownerScope,
18
+ } from "./generations.js";
19
+ import { legDoc, sourceDoc } from "./schema.js";
20
+
21
+ const transferReadFields = {
22
+ coverage: v.literal("unknown"),
23
+ producerGeneration: v.union(v.number(), v.null()),
24
+ hasDeferredWork: v.boolean(),
25
+ };
26
+
27
+ export const source = query({
28
+ args: { allocationId: v.id("settlementAllocations") },
29
+ returns: v.object({
30
+ coverage: v.literal("unknown"),
31
+ observation: v.union(v.null(), sourceDoc),
32
+ }),
33
+ handler: async (ctx, args) => {
34
+ const rows = await ctx.db
35
+ .query("financialSourceObservations")
36
+ .withIndex("by_allocation_id", (q) =>
37
+ q.eq("allocationId", args.allocationId),
38
+ )
39
+ .take(2);
40
+ return {
41
+ coverage: "unknown" as const,
42
+ observation:
43
+ rows.length === 1 &&
44
+ Number.isSafeInteger(rows[0]!.generation) &&
45
+ rows[0]!.generation >= 1
46
+ ? rows[0]!
47
+ : null,
48
+ };
49
+ },
50
+ });
51
+ const result = v.object({
52
+ ...paginationResultValidator(legDoc).fields,
53
+ coverage: v.literal("unknown"),
54
+ generation: v.union(v.number(), v.null()),
55
+ });
56
+ function assertPageSize(numItems: number) {
57
+ if (!Number.isInteger(numItems) || numItems < 1 || numItems > 100)
58
+ throw new Error("Observation page size must be between 1 and 100");
59
+ }
60
+ /** Trusted host boundary; exact keys do not authorize end-user access. */
61
+ export const bucket = query({
62
+ args: { bucketKey: v.string(), paginationOpts: paginationOptsValidator },
63
+ returns: result,
64
+ handler: async (ctx, args) => {
65
+ assertSelector(args.bucketKey);
66
+ assertPageSize(args.paginationOpts.numItems);
67
+ const page = await paginator(ctx.db, schema)
68
+ .query("financialSourceLegs")
69
+ .withIndex("by_bucket_key", (q) => q.eq("bucketKey", args.bucketKey))
70
+ .order("desc")
71
+ .paginate({
72
+ ...args.paginationOpts,
73
+ maximumRowsRead: 200,
74
+ maximumBytesRead: 1_000_000,
75
+ });
76
+ return {
77
+ ...page,
78
+ coverage: "unknown" as const,
79
+ generation: await observationGeneration(ctx, bucketScope(args.bucketKey)),
80
+ };
81
+ },
82
+ });
83
+ export const owner = query({
84
+ args: { ...ownerFields, paginationOpts: paginationOptsValidator },
85
+ returns: result,
86
+ handler: async (ctx, args) => {
87
+ assertOwner(args);
88
+ assertPageSize(args.paginationOpts.numItems);
89
+ const page = await paginator(ctx.db, schema)
90
+ .query("financialSourceLegs")
91
+ .withIndex("by_owner", (q) =>
92
+ q.eq("userId", args.userId).eq("orgId", args.orgId),
93
+ )
94
+ .order("desc")
95
+ .paginate({
96
+ ...args.paginationOpts,
97
+ maximumRowsRead: 200,
98
+ maximumBytesRead: 1_000_000,
99
+ });
100
+ return {
101
+ ...page,
102
+ coverage: "unknown" as const,
103
+ generation: await observationGeneration(
104
+ ctx,
105
+ ownerScope(args.userId, args.orgId),
106
+ ),
107
+ };
108
+ },
109
+ });
110
+
111
+ export const transfer = query({
112
+ args: { transferId: v.id("transfers") },
113
+ returns: v.object({
114
+ ...transferReadFields,
115
+ observation: v.union(transferObservationDoc, v.null()),
116
+ }),
117
+ handler: async (ctx, args) => {
118
+ const rows = await ctx.db
119
+ .query("financialTransferObservations")
120
+ .withIndex("by_transfer_id", (q) => q.eq("transferId", args.transferId))
121
+ .take(2);
122
+ const row = rows.length === 1 ? rows[0] : null;
123
+ return {
124
+ ...(await transferReaderState(ctx)),
125
+ observation:
126
+ row && Number.isSafeInteger(row.generation) && row.generation >= 1
127
+ ? row
128
+ : null,
129
+ };
130
+ },
131
+ });
132
+ export const transferBatches = query({
133
+ args: { operationId: v.string(), paginationOpts: paginationOptsValidator },
134
+ returns: v.object({
135
+ ...paginationResultValidator(transferBatchDoc).fields,
136
+ coverage: v.literal("unknown"),
137
+ hasDeferredWork: v.boolean(),
138
+ producerGeneration: v.union(v.number(), v.null()),
139
+ }),
140
+ handler: async (ctx, args) => {
141
+ assertSelector(args.operationId);
142
+ assertPageSize(args.paginationOpts.numItems);
143
+ const page = await paginator(ctx.db, schema)
144
+ .query("financialTransferBatches")
145
+ .withIndex("by_operation_id", (q) =>
146
+ q.eq("operationId", args.operationId),
147
+ )
148
+ .order("desc")
149
+ .paginate({
150
+ ...args.paginationOpts,
151
+ maximumRowsRead: 200,
152
+ maximumBytesRead: 1_000_000,
153
+ });
154
+ return { ...page, ...(await transferReaderState(ctx)) };
155
+ },
156
+ });
157
+ const transferPageResult = v.object({
158
+ ...paginationResultValidator(transferObservationDoc).fields,
159
+ ...transferReadFields,
160
+ generation: v.union(v.number(), v.null()),
161
+ });
162
+ export const transferBucket = query({
163
+ args: { bucketKey: v.string(), paginationOpts: paginationOptsValidator },
164
+ returns: transferPageResult,
165
+ handler: async (ctx, args) => {
166
+ assertSelector(args.bucketKey);
167
+ assertPageSize(args.paginationOpts.numItems);
168
+ const page = await paginator(ctx.db, schema)
169
+ .query("financialTransferObservations")
170
+ .withIndex("by_bucket_key", (q) => q.eq("bucketKey", args.bucketKey))
171
+ .order("desc")
172
+ .paginate({
173
+ ...args.paginationOpts,
174
+ maximumRowsRead: 200,
175
+ maximumBytesRead: 1_000_000,
176
+ });
177
+ return {
178
+ ...page,
179
+ ...(await transferReaderState(ctx)),
180
+ generation: await observationGeneration(ctx, bucketScope(args.bucketKey)),
181
+ };
182
+ },
183
+ });
184
+ export const transferOwner = query({
185
+ args: { ...ownerFields, paginationOpts: paginationOptsValidator },
186
+ returns: transferPageResult,
187
+ handler: async (ctx, args) => {
188
+ assertOwner(args);
189
+ assertPageSize(args.paginationOpts.numItems);
190
+ const page = await paginator(ctx.db, schema)
191
+ .query("financialTransferObservations")
192
+ .withIndex("by_owner", (q) =>
193
+ q.eq("userId", args.userId).eq("orgId", args.orgId),
194
+ )
195
+ .order("desc")
196
+ .paginate({
197
+ ...args.paginationOpts,
198
+ maximumRowsRead: 200,
199
+ maximumBytesRead: 1_000_000,
200
+ });
201
+ return {
202
+ ...page,
203
+ ...(await transferReaderState(ctx)),
204
+ generation: await observationGeneration(
205
+ ctx,
206
+ ownerScope(args.userId, args.orgId),
207
+ ),
208
+ };
209
+ },
210
+ });
211
+
212
+ export const transferReferences = query({
213
+ args: {
214
+ batchId: v.id("financialTransferBatches"),
215
+ paginationOpts: paginationOptsValidator,
216
+ },
217
+ returns: v.object({
218
+ ...paginationResultValidator(transferReferenceDoc).fields,
219
+ ...transferReadFields,
220
+ }),
221
+ handler: async (ctx, args) => {
222
+ assertPageSize(args.paginationOpts.numItems);
223
+ const page = await paginator(ctx.db, schema)
224
+ .query("financialTransferBatchReferences")
225
+ .withIndex("by_batch_position", (q) => q.eq("batchId", args.batchId))
226
+ .order("asc")
227
+ .paginate({
228
+ ...args.paginationOpts,
229
+ maximumRowsRead: 200,
230
+ maximumBytesRead: 1_000_000,
231
+ });
232
+ return { ...page, ...(await transferReaderState(ctx)) };
233
+ },
234
+ });
235
+
236
+ export const transferBatch = query({
237
+ args: { batchId: v.id("financialTransferBatches") },
238
+ returns: v.object({
239
+ ...transferReadFields,
240
+ batch: v.union(transferBatchDoc, v.null()),
241
+ }),
242
+ handler: async (ctx, args) => ({
243
+ ...(await transferReaderState(ctx)),
244
+ batch: await ctx.db.get("financialTransferBatches", args.batchId),
245
+ }),
246
+ });
@@ -0,0 +1,68 @@
1
+ import { defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ import { splitRecipientRoleValidator } from "../lib/fees.js";
4
+
5
+ export const sourceFields = {
6
+ allocationId: v.id("settlementAllocations"),
7
+ sourceChargeId: v.string(),
8
+ producer: v.literal("settlement_allocation"),
9
+ producerVersion: v.literal(1),
10
+ fingerprint: v.string(),
11
+ observedFingerprint: v.string(),
12
+ ownershipFingerprint: v.string(),
13
+ generation: v.number(),
14
+ legCount: v.number(),
15
+ indexedLegCount: v.number(),
16
+ isOverflow: v.boolean(),
17
+ isContradictory: v.boolean(),
18
+ continuation: v.optional(
19
+ v.object({
20
+ state: v.union(
21
+ v.literal("indexing"),
22
+ v.literal("validating"),
23
+ v.literal("complete"),
24
+ v.literal("held"),
25
+ ),
26
+ nextLeg: v.number(),
27
+ validatedLegs: v.number(),
28
+ }),
29
+ ),
30
+ };
31
+ export const sourceDoc = v.object({
32
+ ...sourceFields,
33
+ _id: v.id("financialSourceObservations"),
34
+ _creationTime: v.number(),
35
+ });
36
+ export const sourceObservationsTable = defineTable(sourceFields).index(
37
+ "by_allocation_id",
38
+ ["allocationId"],
39
+ );
40
+ export const legFields = {
41
+ allocationId: v.id("settlementAllocations"),
42
+ sourceChargeId: v.string(),
43
+ legIndex: v.number(),
44
+ bucketKey: v.string(),
45
+ role: splitRecipientRoleValidator,
46
+ registrationId: v.optional(v.id("financialOwnership")),
47
+ userId: v.optional(v.string()),
48
+ orgId: v.optional(v.string()),
49
+ ownershipStatus: v.union(
50
+ v.literal("registered"),
51
+ v.literal("unknown"),
52
+ v.literal("ambiguous"),
53
+ v.literal("contradictory"),
54
+ ),
55
+ };
56
+ export const legDoc = v.object({
57
+ ...legFields,
58
+ _id: v.id("financialSourceLegs"),
59
+ _creationTime: v.number(),
60
+ });
61
+ export const sourceLegsTable = defineTable(legFields)
62
+ .index("by_allocation_id_and_leg_index", ["allocationId", "legIndex"])
63
+ .index("by_bucket_key", ["bucketKey"])
64
+ .index("by_owner", ["userId", "orgId"]);
65
+ export const observationGenerationsTable = defineTable({
66
+ scopeKey: v.string(),
67
+ generation: v.number(),
68
+ }).index("by_scope_key", ["scopeKey"]);
@@ -0,0 +1,86 @@
1
+ import { convexTest } from "convex-test";
2
+ import { makeFunctionReference } from "convex/server";
3
+ import { expect, it } from "vitest";
4
+ import { modules, schema } from "../../test.js";
5
+
6
+ const reserve = makeFunctionReference<"mutation">(
7
+ "settlement/mutations:reserveSettlementAllocation",
8
+ );
9
+ const register = makeFunctionReference<"mutation">(
10
+ "financialOwnership/mutations:register",
11
+ );
12
+ const source = makeFunctionReference<"query">(
13
+ "financialObservations/queries:source",
14
+ );
15
+ const bucket = makeFunctionReference<"query">(
16
+ "financialObservations/queries:bucket",
17
+ );
18
+ const allocation = {
19
+ sourceChargeId: "ch_observed",
20
+ gross: 1000,
21
+ currency: "usd",
22
+ processingFee: 100,
23
+ platformNet: 100,
24
+ transfers: [
25
+ {
26
+ destinationAccountId: "opaque-seller",
27
+ role: "store" as const,
28
+ amount: 600,
29
+ },
30
+ {
31
+ destinationAccountId: "opaque-affiliate",
32
+ role: "affiliate" as const,
33
+ amount: 200,
34
+ },
35
+ ],
36
+ };
37
+ const page = { numItems: 25, cursor: null };
38
+ it("atomically observes raw settlement destinations without guessing unassigned ownership", async () => {
39
+ const t = convexTest(schema, modules);
40
+ await t.mutation(register, {
41
+ bucketKey: "opaque-seller",
42
+ kind: "logical",
43
+ userId: "seller",
44
+ source: { integration: "host", recordId: "seller-source" },
45
+ });
46
+ const original = await t.mutation(reserve, allocation);
47
+ expect(await t.query(source, { allocationId: original._id })).toMatchObject({
48
+ coverage: "unknown",
49
+ observation: {
50
+ producer: "settlement_allocation",
51
+ producerVersion: 1,
52
+ generation: 1,
53
+ sourceChargeId: "ch_observed",
54
+ legCount: 2,
55
+ indexedLegCount: 2,
56
+ isOverflow: false,
57
+ },
58
+ });
59
+ expect(
60
+ await t.query(bucket, { bucketKey: "opaque-seller", paginationOpts: page }),
61
+ ).toMatchObject({
62
+ coverage: "unknown",
63
+ generation: 1,
64
+ page: [
65
+ expect.objectContaining({
66
+ allocationId: original._id,
67
+ bucketKey: "opaque-seller",
68
+ role: "store",
69
+ userId: "seller",
70
+ ownershipStatus: "registered",
71
+ }),
72
+ ],
73
+ });
74
+ expect(
75
+ await t.query(bucket, {
76
+ bucketKey: "opaque-affiliate",
77
+ paginationOpts: page,
78
+ }),
79
+ ).toMatchObject({
80
+ coverage: "unknown",
81
+ page: [expect.objectContaining({ ownershipStatus: "unknown" })],
82
+ });
83
+ expect(
84
+ await t.run((ctx) => ctx.db.get("settlementAllocations", original._id)),
85
+ ).toEqual(original);
86
+ });
@@ -0,0 +1,142 @@
1
+ import type { Infer } from "convex/values";
2
+ import type { Doc } from "../_generated/dataModel.js";
3
+ import type { MutationCtx } from "../_generated/server.js";
4
+ import { generateIdempotencyKey } from "../lib/idempotency.js";
5
+ import {
6
+ hasInvalidLegIdentity,
7
+ invalidate,
8
+ legOwnership,
9
+ settlementFingerprint,
10
+ } from "./settlementHelpers.js";
11
+ import type { legDoc } from "./schema.js";
12
+
13
+ /** Larger allocations require explicit bounded continuation; aggregate coverage stays UNKNOWN. */
14
+ export const synchronousSettlementLegLimit = 100;
15
+ type Leg = Omit<Infer<typeof legDoc>, "_id" | "_creationTime">;
16
+
17
+ /** Persist diagnostic provenance in the SAME raw mutation; never mutate the financial source. */
18
+ export async function observeSettlementAllocation(
19
+ ctx: MutationCtx,
20
+ row: Doc<"settlementAllocations">,
21
+ ) {
22
+ const markers = await ctx.db
23
+ .query("financialSourceObservations")
24
+ .withIndex("by_allocation_id", (q) => q.eq("allocationId", row._id))
25
+ .take(2);
26
+ if (markers.length > 1) return;
27
+ const prior = markers[0];
28
+ const oldLegs = await ctx.db
29
+ .query("financialSourceLegs")
30
+ .withIndex("by_allocation_id_and_leg_index", (q) =>
31
+ q.eq("allocationId", row._id),
32
+ )
33
+ .take(synchronousSettlementLegLimit + 1);
34
+ const fingerprint = await settlementFingerprint(row);
35
+ const sources = await ctx.db
36
+ .query("settlementAllocations")
37
+ .withIndex("by_source_charge", (q) =>
38
+ q.eq("sourceChargeId", row.sourceChargeId),
39
+ )
40
+ .take(2);
41
+ const isContinuedOverflow =
42
+ prior?.isOverflow === true && prior.continuation !== undefined;
43
+ const hasInvalidLegs =
44
+ hasInvalidLegIdentity(row, oldLegs) ||
45
+ (prior !== undefined &&
46
+ ((!isContinuedOverflow && prior.indexedLegCount !== oldLegs.length) ||
47
+ (!prior.isOverflow &&
48
+ !prior.isContradictory &&
49
+ (prior.legCount !== row.transfers.length ||
50
+ oldLegs.length !== row.transfers.length))));
51
+ const isContradictory =
52
+ hasInvalidLegs ||
53
+ sources.length !== 1 ||
54
+ sources[0]?._id !== row._id ||
55
+ prior?.isContradictory === true ||
56
+ (prior !== undefined && prior.fingerprint !== fingerprint) ||
57
+ (oldLegs.length > synchronousSettlementLegLimit && !isContinuedOverflow);
58
+ const isOverflow = row.transfers.length > synchronousSettlementLegLimit;
59
+ const legs: Leg[] = [];
60
+ if (!isOverflow && !isContradictory)
61
+ for (const [legIndex, leg] of row.transfers.entries()) {
62
+ const previous = oldLegs.find((l) => l.legIndex === legIndex);
63
+ legs.push({
64
+ allocationId: row._id,
65
+ sourceChargeId: row.sourceChargeId,
66
+ legIndex,
67
+ bucketKey: leg.destinationAccountId,
68
+ role: leg.role,
69
+ ...(await legOwnership(ctx, leg.destinationAccountId, previous)),
70
+ });
71
+ }
72
+ if (isContinuedOverflow && !isContradictory) return;
73
+ const ownershipFingerprint = await generateIdempotencyKey(
74
+ "settlement-leg-ownership-v1",
75
+ { legs },
76
+ );
77
+ if (
78
+ prior &&
79
+ prior.observedFingerprint === fingerprint &&
80
+ prior.ownershipFingerprint === ownershipFingerprint &&
81
+ prior.isContradictory === isContradictory &&
82
+ prior.isOverflow === isOverflow
83
+ )
84
+ return;
85
+ const generation = (prior?.generation ?? 0) + 1;
86
+ if (
87
+ !Number.isSafeInteger(generation) ||
88
+ generation < 1 ||
89
+ (prior && prior.generation < 1)
90
+ ) {
91
+ if (prior && prior.generation !== 0) {
92
+ await ctx.db.patch("financialSourceObservations", prior._id, {
93
+ generation: 0,
94
+ isContradictory: true,
95
+ });
96
+ await invalidate(ctx, oldLegs);
97
+ }
98
+ return;
99
+ }
100
+ if (!isOverflow && !isContradictory)
101
+ for (const leg of legs) {
102
+ const existing = oldLegs.find((l) => l.legIndex === leg.legIndex);
103
+ if (existing)
104
+ await ctx.db.patch("financialSourceLegs", existing._id, leg);
105
+ else await ctx.db.insert("financialSourceLegs", leg);
106
+ }
107
+ if (isContradictory && !hasInvalidLegs)
108
+ for (const leg of oldLegs)
109
+ await ctx.db.patch("financialSourceLegs", leg._id, {
110
+ ownershipStatus: "contradictory",
111
+ });
112
+ const fields = {
113
+ allocationId: row._id,
114
+ sourceChargeId: prior?.sourceChargeId ?? row.sourceChargeId,
115
+ producer: "settlement_allocation" as const,
116
+ producerVersion: 1 as const,
117
+ fingerprint: prior?.fingerprint ?? fingerprint,
118
+ observedFingerprint: fingerprint,
119
+ ownershipFingerprint,
120
+ generation,
121
+ legCount: row.transfers.length,
122
+ indexedLegCount: isContinuedOverflow
123
+ ? prior.indexedLegCount
124
+ : isOverflow || isContradictory
125
+ ? oldLegs.length
126
+ : legs.length,
127
+ ...(prior?.continuation && isContradictory
128
+ ? {
129
+ continuation: {
130
+ ...prior.continuation,
131
+ state: "held" as const,
132
+ },
133
+ }
134
+ : {}),
135
+ isOverflow,
136
+ isContradictory,
137
+ };
138
+ if (prior)
139
+ await ctx.db.patch("financialSourceObservations", prior._id, fields);
140
+ else await ctx.db.insert("financialSourceObservations", fields);
141
+ await invalidate(ctx, [...oldLegs, ...legs]);
142
+ }
@@ -0,0 +1,92 @@
1
+ import type { Infer } from "convex/values";
2
+ import type { Doc } from "../_generated/dataModel.js";
3
+ import type { MutationCtx } from "../_generated/server.js";
4
+ import { generateIdempotencyKey } from "../lib/idempotency.js";
5
+ import {
6
+ advanceObservationGeneration,
7
+ bucketScope,
8
+ ownerScope,
9
+ } from "./generations.js";
10
+ import type { legDoc } from "./schema.js";
11
+
12
+ type Leg = Omit<Infer<typeof legDoc>, "_id" | "_creationTime">;
13
+ export async function legOwnership(
14
+ ctx: MutationCtx,
15
+ bucketKey: string,
16
+ prior:
17
+ | Pick<Doc<"financialSourceLegs">, "registrationId" | "userId" | "orgId">
18
+ | undefined,
19
+ ) {
20
+ const registrations = await ctx.db
21
+ .query("financialOwnership")
22
+ .withIndex("by_bucket_key", (q) => q.eq("bucketKey", bucketKey))
23
+ .take(2);
24
+ const registration = registrations[0];
25
+ const pin = prior?.registrationId
26
+ ? {
27
+ registrationId: prior.registrationId,
28
+ userId: prior.userId,
29
+ orgId: prior.orgId,
30
+ }
31
+ : {};
32
+ if (registrations.length > 1)
33
+ return { ...pin, ownershipStatus: "ambiguous" as const };
34
+ if (!registration) return { ...pin, ownershipStatus: "unknown" as const };
35
+ if (
36
+ prior?.registrationId &&
37
+ (prior.registrationId !== registration._id ||
38
+ prior.userId !== registration.userId ||
39
+ prior.orgId !== registration.orgId)
40
+ )
41
+ return { ...pin, ownershipStatus: "contradictory" as const };
42
+ return {
43
+ registrationId: registration._id,
44
+ userId: registration.userId,
45
+ orgId: registration.orgId,
46
+ ownershipStatus: "registered" as const,
47
+ };
48
+ }
49
+ export async function invalidate(
50
+ ctx: MutationCtx,
51
+ legs: Pick<Leg, "bucketKey" | "userId" | "orgId">[],
52
+ ) {
53
+ const scopes = new Set<string>();
54
+ for (const leg of legs) {
55
+ scopes.add(bucketScope(leg.bucketKey));
56
+ if (leg.userId !== undefined) scopes.add(ownerScope(leg.userId, leg.orgId));
57
+ }
58
+ for (const scope of scopes) await advanceObservationGeneration(ctx, scope);
59
+ }
60
+ export function hasInvalidLegIdentity(
61
+ row: Doc<"settlementAllocations">,
62
+ legs: Doc<"financialSourceLegs">[],
63
+ ) {
64
+ const slots = new Set<number>();
65
+ return legs.some((leg) => {
66
+ const original = row.transfers[leg.legIndex];
67
+ const isInvalid =
68
+ slots.has(leg.legIndex) ||
69
+ !Number.isInteger(leg.legIndex) ||
70
+ !original ||
71
+ leg.sourceChargeId !== row.sourceChargeId ||
72
+ leg.bucketKey !== original.destinationAccountId ||
73
+ leg.role !== original.role;
74
+ slots.add(leg.legIndex);
75
+ return isInvalid;
76
+ });
77
+ }
78
+
79
+ export async function settlementFingerprint(row: Doc<"settlementAllocations">) {
80
+ return generateIdempotencyKey("settlement-allocation-observation-v1", {
81
+ sourceChargeId: row.sourceChargeId,
82
+ paymentIntentId: row.paymentIntentId,
83
+ sourceInvoiceId: row.sourceInvoiceId,
84
+ gross: row.gross,
85
+ currency: row.currency,
86
+ processingFee: row.processingFee,
87
+ platformNet: row.platformNet,
88
+ adjustmentAmount: row.adjustmentAmount,
89
+ paymentId: row.paymentId,
90
+ transfers: row.transfers,
91
+ });
92
+ }
@@ -0,0 +1,61 @@
1
+ import { convexTest } from "convex-test";
2
+ import { expect, it } from "vitest";
3
+ import { modules, schema } from "../../test.js";
4
+ import { deferTransferFacts } from "./transferBatches.js";
5
+
6
+ it("keeps matching deferred source replay stable and retains original references on conflict", async () => {
7
+ const t = convexTest(schema, modules);
8
+ const f = await t.run(async (ctx) => {
9
+ const ids = [];
10
+ for (let i = 0; i < 2; i++)
11
+ ids.push(
12
+ await ctx.db.insert("transfers", {
13
+ stripeTransferId: `tr_${i}`,
14
+ destinationAccountId: "opaque",
15
+ amount: 1,
16
+ currency: "usd",
17
+ status: "paid",
18
+ }),
19
+ );
20
+ const id = await ctx.db.insert("transferReversalOps", {
21
+ operationId: "op",
22
+ sourceChargeId: "ch",
23
+ slices: [],
24
+ });
25
+ return { ids, operation: (await ctx.db.get("transferReversalOps", id))! };
26
+ });
27
+ await t.run((ctx) => deferTransferFacts(ctx, f.operation, f.ids));
28
+ const before = await t.run((ctx) =>
29
+ ctx.db.query("financialTransferBatches").collect(),
30
+ );
31
+ const generation = await t.run((ctx) =>
32
+ ctx.db.query("financialObservationGenerations").collect(),
33
+ );
34
+ await t.run((ctx) => deferTransferFacts(ctx, f.operation, f.ids));
35
+ expect(
36
+ await t.run((ctx) => ctx.db.query("financialTransferBatches").collect()),
37
+ ).toEqual(before);
38
+ expect(
39
+ await t.run((ctx) =>
40
+ ctx.db.query("financialObservationGenerations").collect(),
41
+ ),
42
+ ).toEqual(generation);
43
+ await t.run((ctx) => deferTransferFacts(ctx, f.operation, [f.ids[0]]));
44
+ const changed = await t.run((ctx) =>
45
+ ctx.db.query("financialTransferBatches").collect(),
46
+ );
47
+ expect(changed[0]).toMatchObject({
48
+ fingerprint: before[0].fingerprint,
49
+ transferIds: f.ids,
50
+ referenceCount: 2,
51
+ generation: 2,
52
+ isContradictory: true,
53
+ });
54
+ expect(changed[0].observedFingerprint).not.toBe(
55
+ before[0].observedFingerprint,
56
+ );
57
+ await t.run((ctx) => deferTransferFacts(ctx, f.operation, [f.ids[0]]));
58
+ expect(
59
+ await t.run((ctx) => ctx.db.query("financialTransferBatches").collect()),
60
+ ).toEqual(changed);
61
+ });