@fantastic.dev/better-stripe 0.28.6 → 0.30.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 (222) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/MIGRATION.md +14 -0
  3. package/README.md +7 -1
  4. package/dist/client/connect/payoutActivationProof.d.ts.map +1 -1
  5. package/dist/client/connect/payoutActivationProof.js +88 -42
  6. package/dist/client/connect/payoutActivationProof.js.map +1 -1
  7. package/dist/client/connect/payoutAdoption.d.ts +3 -0
  8. package/dist/client/connect/payoutAdoption.d.ts.map +1 -1
  9. package/dist/client/connect/payoutAdoption.js +218 -183
  10. package/dist/client/connect/payoutAdoption.js.map +1 -1
  11. package/dist/client/connect/payoutAdoptionCollection.d.ts +21 -0
  12. package/dist/client/connect/payoutAdoptionCollection.d.ts.map +1 -0
  13. package/dist/client/connect/payoutAdoptionCollection.js +44 -0
  14. package/dist/client/connect/payoutAdoptionCollection.js.map +1 -0
  15. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +54 -14
  16. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  17. package/dist/client/connect/payoutCollectedInput.d.ts +110 -0
  18. package/dist/client/connect/payoutCollectedInput.d.ts.map +1 -0
  19. package/dist/client/connect/payoutCollectedInput.js +70 -0
  20. package/dist/client/connect/payoutCollectedInput.js.map +1 -0
  21. package/dist/client/connect/payoutExecution.d.ts +1 -0
  22. package/dist/client/connect/payoutExecution.d.ts.map +1 -1
  23. package/dist/client/connect/payoutExecution.js +94 -67
  24. package/dist/client/connect/payoutExecution.js.map +1 -1
  25. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +29 -7
  26. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  27. package/dist/client/connect/payoutExecutionTestHelpers.js +9 -6
  28. package/dist/client/connect/payoutExecutionTestHelpers.js.map +1 -1
  29. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +3745 -0
  30. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -0
  31. package/dist/client/connect/payoutLargeAdoptionTestHelpers.js +55 -0
  32. package/dist/client/connect/payoutLargeAdoptionTestHelpers.js.map +1 -0
  33. package/dist/client/connect/payoutOutcomeBatches.d.ts +5 -0
  34. package/dist/client/connect/payoutOutcomeBatches.d.ts.map +1 -0
  35. package/dist/client/connect/payoutOutcomeBatches.js +21 -0
  36. package/dist/client/connect/payoutOutcomeBatches.js.map +1 -0
  37. package/dist/client/connect/payoutPolicyState.d.ts +14 -0
  38. package/dist/client/connect/payoutPolicyState.d.ts.map +1 -0
  39. package/dist/client/connect/payoutPolicyState.js +19 -0
  40. package/dist/client/connect/payoutPolicyState.js.map +1 -0
  41. package/dist/client/connect/payoutPreview.d.ts +1 -0
  42. package/dist/client/connect/payoutPreview.d.ts.map +1 -1
  43. package/dist/client/connect/payoutPreview.js +31 -19
  44. package/dist/client/connect/payoutPreview.js.map +1 -1
  45. package/dist/client/connect/payoutQualification.d.ts +7 -1
  46. package/dist/client/connect/payoutQualification.d.ts.map +1 -1
  47. package/dist/client/connect/payoutQualification.js +34 -19
  48. package/dist/client/connect/payoutQualification.js.map +1 -1
  49. package/dist/client/connect/payoutReconciliation.d.ts +11 -6
  50. package/dist/client/connect/payoutReconciliation.d.ts.map +1 -1
  51. package/dist/client/connect/payoutReconciliation.js +62 -16
  52. package/dist/client/connect/payoutReconciliation.js.map +1 -1
  53. package/dist/client/connect/payoutResumableProof.d.ts +17 -0
  54. package/dist/client/connect/payoutResumableProof.d.ts.map +1 -0
  55. package/dist/client/connect/payoutResumableProof.js +25 -0
  56. package/dist/client/connect/payoutResumableProof.js.map +1 -0
  57. package/dist/client/connect/payoutSyncTestHelpers.d.ts +27 -7
  58. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  59. package/dist/client/connect/payoutWorker.d.ts.map +1 -1
  60. package/dist/client/connect/payoutWorker.js +4 -1
  61. package/dist/client/connect/payoutWorker.js.map +1 -1
  62. package/dist/client/connect/transferReceipt.d.ts +6 -2
  63. package/dist/client/connect/transferReceipt.d.ts.map +1 -1
  64. package/dist/client/connect/transferReceipt.js +3 -3
  65. package/dist/client/connect/transferReceipt.js.map +1 -1
  66. package/dist/client/costRecovery.d.ts +5 -0
  67. package/dist/client/costRecovery.d.ts.map +1 -1
  68. package/dist/client/costRecovery.js +5 -0
  69. package/dist/client/costRecovery.js.map +1 -1
  70. package/dist/client/payoutPolicy.d.ts +4 -0
  71. package/dist/client/payoutPolicy.d.ts.map +1 -1
  72. package/dist/client/payoutPolicy.js +24 -14
  73. package/dist/client/payoutPolicy.js.map +1 -1
  74. package/dist/component/_generated/component.d.ts +247 -0
  75. package/dist/component/_generated/component.d.ts.map +1 -1
  76. package/dist/component/costRecovery/mutations.js +1 -1
  77. package/dist/component/costRecovery/queries.d.ts +9 -0
  78. package/dist/component/costRecovery/queries.d.ts.map +1 -1
  79. package/dist/component/costRecovery/queries.js +20 -0
  80. package/dist/component/costRecovery/queries.js.map +1 -1
  81. package/dist/component/earnings/triggers.d.ts +28 -10
  82. package/dist/component/earnings/triggers.d.ts.map +1 -1
  83. package/dist/component/payoutPolicy/adoption.d.ts.map +1 -1
  84. package/dist/component/payoutPolicy/adoption.js +12 -7
  85. package/dist/component/payoutPolicy/adoption.js.map +1 -1
  86. package/dist/component/payoutPolicy/mutations.d.ts +12 -0
  87. package/dist/component/payoutPolicy/mutations.d.ts.map +1 -1
  88. package/dist/component/payoutPolicy/queries.d.ts +2 -0
  89. package/dist/component/payoutPolicy/queries.d.ts.map +1 -1
  90. package/dist/component/payoutPolicy/schema.d.ts +31 -7
  91. package/dist/component/payoutPolicy/schema.d.ts.map +1 -1
  92. package/dist/component/payoutPolicy/schema.js +2 -0
  93. package/dist/component/payoutPolicy/schema.js.map +1 -1
  94. package/dist/component/payoutRelease/adoption.d.ts +9 -1
  95. package/dist/component/payoutRelease/adoption.d.ts.map +1 -1
  96. package/dist/component/payoutRelease/adoption.js +33 -16
  97. package/dist/component/payoutRelease/adoption.js.map +1 -1
  98. package/dist/component/payoutRelease/fees.d.ts.map +1 -1
  99. package/dist/component/payoutRelease/fees.js +7 -0
  100. package/dist/component/payoutRelease/fees.js.map +1 -1
  101. package/dist/component/payoutRelease/helpers.d.ts +4 -1
  102. package/dist/component/payoutRelease/helpers.d.ts.map +1 -1
  103. package/dist/component/payoutRelease/helpers.js +17 -10
  104. package/dist/component/payoutRelease/helpers.js.map +1 -1
  105. package/dist/component/payoutRelease/mutations.d.ts +79 -0
  106. package/dist/component/payoutRelease/mutations.d.ts.map +1 -1
  107. package/dist/component/payoutRelease/mutations.js +38 -81
  108. package/dist/component/payoutRelease/mutations.js.map +1 -1
  109. package/dist/component/payoutRelease/outcome.d.ts +69 -0
  110. package/dist/component/payoutRelease/outcome.d.ts.map +1 -0
  111. package/dist/component/payoutRelease/outcome.js +94 -0
  112. package/dist/component/payoutRelease/outcome.js.map +1 -0
  113. package/dist/component/payoutRelease/planning.d.ts +4 -0
  114. package/dist/component/payoutRelease/planning.d.ts.map +1 -1
  115. package/dist/component/payoutRelease/planning.js +8 -3
  116. package/dist/component/payoutRelease/planning.js.map +1 -1
  117. package/dist/component/payoutRelease/preview.d.ts +2 -0
  118. package/dist/component/payoutRelease/preview.d.ts.map +1 -1
  119. package/dist/component/payoutRelease/preview.js +2 -0
  120. package/dist/component/payoutRelease/preview.js.map +1 -1
  121. package/dist/component/payoutRelease/queries.d.ts +13 -2
  122. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  123. package/dist/component/payoutRelease/queries.js +2 -0
  124. package/dist/component/payoutRelease/queries.js.map +1 -1
  125. package/dist/component/payoutRelease/schema.d.ts +17 -2
  126. package/dist/component/payoutRelease/schema.d.ts.map +1 -1
  127. package/dist/component/payoutRelease/schema.js +3 -0
  128. package/dist/component/payoutRelease/schema.js.map +1 -1
  129. package/dist/component/payoutSnapshots/adoption.d.ts +88 -0
  130. package/dist/component/payoutSnapshots/adoption.d.ts.map +1 -0
  131. package/dist/component/payoutSnapshots/adoption.js +49 -0
  132. package/dist/component/payoutSnapshots/adoption.js.map +1 -0
  133. package/dist/component/payoutSnapshots/financial.d.ts +47 -0
  134. package/dist/component/payoutSnapshots/financial.d.ts.map +1 -0
  135. package/dist/component/payoutSnapshots/financial.js +103 -0
  136. package/dist/component/payoutSnapshots/financial.js.map +1 -0
  137. package/dist/component/payoutSnapshots/liabilities.d.ts +7 -0
  138. package/dist/component/payoutSnapshots/liabilities.d.ts.map +1 -0
  139. package/dist/component/payoutSnapshots/liabilities.js +18 -0
  140. package/dist/component/payoutSnapshots/liabilities.js.map +1 -0
  141. package/dist/component/payoutSnapshots/localState.d.ts +22 -16
  142. package/dist/component/payoutSnapshots/localState.d.ts.map +1 -1
  143. package/dist/component/payoutSnapshots/localState.js +19 -7
  144. package/dist/component/payoutSnapshots/localState.js.map +1 -1
  145. package/dist/component/payoutSnapshots/mutations.d.ts +6 -0
  146. package/dist/component/payoutSnapshots/mutations.d.ts.map +1 -1
  147. package/dist/component/payoutSnapshots/mutations.js +3 -1
  148. package/dist/component/payoutSnapshots/mutations.js.map +1 -1
  149. package/dist/component/payoutSnapshots/queries.d.ts +133 -0
  150. package/dist/component/payoutSnapshots/queries.d.ts.map +1 -0
  151. package/dist/component/payoutSnapshots/queries.js +86 -0
  152. package/dist/component/payoutSnapshots/queries.js.map +1 -0
  153. package/dist/component/payoutSnapshots/revisions.d.ts.map +1 -1
  154. package/dist/component/payoutSnapshots/revisions.js +19 -0
  155. package/dist/component/payoutSnapshots/revisions.js.map +1 -1
  156. package/dist/component/payoutSnapshots/schema.d.ts +20 -6
  157. package/dist/component/payoutSnapshots/schema.d.ts.map +1 -1
  158. package/dist/component/payoutSnapshots/schema.js +5 -1
  159. package/dist/component/payoutSnapshots/schema.js.map +1 -1
  160. package/dist/component/payoutWorker/mutations.d.ts.map +1 -1
  161. package/dist/component/payoutWorker/mutations.js +3 -1
  162. package/dist/component/payoutWorker/mutations.js.map +1 -1
  163. package/dist/component/schema.d.ts +27 -7
  164. package/dist/react/workflows/payout-attempt-state.d.ts.map +1 -1
  165. package/dist/react/workflows/payout-attempt-state.js +3 -0
  166. package/dist/react/workflows/payout-attempt-state.js.map +1 -1
  167. package/dist/react/workflows/payout-progress-state.d.ts.map +1 -1
  168. package/dist/react/workflows/payout-progress-state.js +3 -0
  169. package/dist/react/workflows/payout-progress-state.js.map +1 -1
  170. package/docs/settlement.md +136 -24
  171. package/package.json +1 -1
  172. package/src/client/connect/payoutActivationProof.ts +123 -53
  173. package/src/client/connect/payoutAdoption.ts +299 -215
  174. package/src/client/connect/payoutAdoptionCollection.ts +78 -0
  175. package/src/client/connect/payoutAdoptionConcurrency.test.ts +266 -0
  176. package/src/client/connect/payoutCacheIdentity.test.ts +93 -0
  177. package/src/client/connect/payoutCollectedInput.ts +120 -0
  178. package/src/client/connect/payoutExecution.ts +116 -84
  179. package/src/client/connect/payoutExecutionTestHelpers.ts +19 -6
  180. package/src/client/connect/payoutLargeAdoption.test.ts +541 -0
  181. package/src/client/connect/payoutLargeAdoptionTestHelpers.ts +74 -0
  182. package/src/client/connect/payoutLargeHistory.test.ts +222 -0
  183. package/src/client/connect/payoutLiabilityVersion.test.ts +221 -0
  184. package/src/client/connect/payoutOutcomeBatches.test.ts +40 -0
  185. package/src/client/connect/payoutOutcomeBatches.ts +24 -0
  186. package/src/client/connect/payoutPolicyState.ts +36 -0
  187. package/src/client/connect/payoutPreview.ts +42 -24
  188. package/src/client/connect/payoutQualification.ts +68 -21
  189. package/src/client/connect/payoutReconciliation.ts +86 -7
  190. package/src/client/connect/payoutResumableProof.ts +41 -0
  191. package/src/client/connect/payoutWorker.ts +4 -1
  192. package/src/client/connect/transferReceipt.ts +3 -2
  193. package/src/client/connect/transferReceiptBaseline.test.ts +55 -0
  194. package/src/client/costRecovery.ts +8 -0
  195. package/src/client/payoutPolicy.ts +37 -23
  196. package/src/component/_generated/api.ts +10 -0
  197. package/src/component/_generated/component.ts +288 -0
  198. package/src/component/costRecovery/mutations.ts +1 -1
  199. package/src/component/costRecovery/queries.ts +21 -0
  200. package/src/component/payout-snapshots.test.ts +45 -1
  201. package/src/component/payoutPolicy/adoption.ts +20 -7
  202. package/src/component/payoutPolicy/schema.ts +2 -0
  203. package/src/component/payoutRelease/adoption.ts +57 -27
  204. package/src/component/payoutRelease/fees.ts +9 -0
  205. package/src/component/payoutRelease/helpers.ts +19 -11
  206. package/src/component/payoutRelease/mutations.ts +43 -96
  207. package/src/component/payoutRelease/outcome.ts +119 -0
  208. package/src/component/payoutRelease/planning.ts +11 -2
  209. package/src/component/payoutRelease/preview.ts +2 -0
  210. package/src/component/payoutRelease/queries.ts +2 -0
  211. package/src/component/payoutRelease/schema.ts +3 -0
  212. package/src/component/payoutSnapshots/adoption.ts +73 -0
  213. package/src/component/payoutSnapshots/financial.ts +134 -0
  214. package/src/component/payoutSnapshots/liabilities.ts +25 -0
  215. package/src/component/payoutSnapshots/localState.ts +24 -6
  216. package/src/component/payoutSnapshots/mutations.ts +10 -1
  217. package/src/component/payoutSnapshots/queries.ts +104 -0
  218. package/src/component/payoutSnapshots/revisions.ts +26 -0
  219. package/src/component/payoutSnapshots/schema.ts +5 -0
  220. package/src/component/payoutWorker/mutations.ts +3 -1
  221. package/src/react/workflows/payout-attempt-state.ts +6 -0
  222. package/src/react/workflows/payout-progress-state.ts +6 -0
@@ -1,3 +1,4 @@
1
+ import { adoptionCollection } from "../payoutSnapshots/adoption.js";
1
2
  import type { Infer } from "convex/values";
2
3
  import type { MutationCtx } from "../_generated/server.js";
3
4
  import type { adoptionProof } from "./schema.js";
@@ -14,16 +15,26 @@ export async function validateAdoption(
14
15
  scope: { accountId: string; ownerKey: string },
15
16
  proof: Infer<typeof adoptionProof>,
16
17
  ) {
17
- await checkSnapshot(ctx, scope.accountId, proof.observations, true);
18
- const rows = await ctx.db
19
- .query("payoutReleaseClaims")
20
- .withIndex("by_account_status", (q) => q.eq("accountId", scope.accountId))
21
- .take(101);
18
+ const collected = await adoptionCollection(ctx, scope, proof);
19
+ await checkSnapshot(
20
+ ctx,
21
+ scope.accountId,
22
+ proof.observations,
23
+ true,
24
+ undefined,
25
+ collected?.sources,
26
+ );
27
+ const rows =
28
+ collected?.claims ??
29
+ (await ctx.db
30
+ .query("payoutReleaseClaims")
31
+ .withIndex("by_account_status", (q) => q.eq("accountId", scope.accountId))
32
+ .take(101));
22
33
  const expected = new Map(
23
34
  proof.claims.map((c) => [c.operationKey, c.fingerprint]),
24
35
  );
25
36
  if (
26
- rows.length > 100 ||
37
+ (!collected && rows.length > 100) ||
27
38
  expected.size !== proof.claims.length ||
28
39
  rows.length !== expected.size ||
29
40
  rows.some(
@@ -39,7 +50,9 @@ export async function validateAdoption(
39
50
  );
40
51
  const owed = new Map<string, number>();
41
52
  for (const o of proof.observations) {
42
- const source = await sourceById(ctx, o.stripeTransferId);
53
+ const source = collected?.allocations?.has(o.stripeTransferId)
54
+ ? collected.allocations.get(o.stripeTransferId)
55
+ : await sourceById(ctx, o.stripeTransferId);
43
56
  if (
44
57
  source &&
45
58
  (source.accountId !== scope.accountId ||
@@ -17,6 +17,8 @@ export const thresholds = v.array(
17
17
  v.object({ currency: v.string(), amount: v.number() }),
18
18
  );
19
19
  export const adoptionProof = v.object({
20
+ snapshotId: v.optional(v.id("payoutSnapshots")),
21
+ collectionKey: v.optional(v.string()),
20
22
  observations: v.array(observation),
21
23
  claims: v.array(
22
24
  v.object({ operationKey: v.string(), fingerprint: v.string() }),
@@ -1,3 +1,5 @@
1
+ import type { Doc } from "../_generated/dataModel.js";
2
+ import { adoptionCollection } from "../payoutSnapshots/adoption.js";
1
3
  import { v, type Infer } from "convex/values";
2
4
  import type { MutationCtx } from "../_generated/server.js";
3
5
  import { scopeFields } from "../payoutPolicy/schema.js";
@@ -32,7 +34,11 @@ type Args = {
32
34
  [K in keyof typeof historicalArgs]: Infer<(typeof historicalArgs)[K]>;
33
35
  };
34
36
  /** Trusted package observations only. Provider history and historical maturity are verified upstream. */
35
- export async function adoptHistoricalPayout(ctx: MutationCtx, args: Args) {
37
+ export async function adoptHistoricalPayout(
38
+ ctx: MutationCtx,
39
+ args: Args,
40
+ collected?: Map<string, Doc<"transfers">>,
41
+ ) {
36
42
  const policy = await readPolicy(ctx, args);
37
43
  if (!policy || policy.revision !== args.expectedRevision)
38
44
  throw new Error("Historical payout policy revision changed.");
@@ -61,12 +67,9 @@ export async function adoptHistoricalPayout(ctx: MutationCtx, args: Args) {
61
67
  : p.returnTransactionId !== undefined || p.returnFee !== undefined)
62
68
  )
63
69
  throw new Error("Invalid historical payout receipt.");
64
- const rows = await checkSnapshot(
65
- ctx,
66
- args.accountId,
67
- args.observations,
68
- true,
69
- );
70
+ const rows =
71
+ collected ??
72
+ (await checkSnapshot(ctx, args.accountId, args.observations, true));
70
73
  const byObservation = new Map(
71
74
  args.observations.map((o) => [o.stripeTransferId, o]),
72
75
  );
@@ -142,12 +145,14 @@ export async function adoptHistoricalPayout(ctx: MutationCtx, args: Args) {
142
145
  "Resolve existing payout attempts before historical adoption.",
143
146
  );
144
147
  }
145
- const history = await ctx.db
146
- .query("payoutReleaseClaims")
147
- .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
148
- .take(100);
149
- if (history.length >= 100)
150
- throw new Error("Historical payout snapshot limit exceeded.");
148
+ if (!collected) {
149
+ const history = await ctx.db
150
+ .query("payoutReleaseClaims")
151
+ .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
152
+ .take(100);
153
+ if (history.length >= 100)
154
+ throw new Error("Historical payout snapshot limit exceeded.");
155
+ }
151
156
  for (const a of allocations) {
152
157
  const source = await sourceById(ctx, a.stripeTransferId);
153
158
  if (
@@ -185,7 +190,10 @@ export async function adoptHistoricalPayout(ctx: MutationCtx, args: Args) {
185
190
  amount: p.amount,
186
191
  destinationId: p.destinationId,
187
192
  allocations,
188
- observations: args.observations,
193
+ // Complete batch membership is validated above. Keep the immutable receipt
194
+ // evidence for every source allocated to this historical payout, rather than
195
+ // duplicating unrelated source proofs on every imported claim.
196
+ observations: args.observations.filter((o) => seen.has(o.stripeTransferId)),
189
197
  status: p.status,
190
198
  attemptedAt: p.created * 1000,
191
199
  stripePayoutId: p.stripePayoutId,
@@ -208,6 +216,7 @@ export async function adoptHistoricalPayout(ctx: MutationCtx, args: Args) {
208
216
  }
209
217
 
210
218
  export const historicalBatchArgs = {
219
+ snapshotId: v.optional(v.id("payoutSnapshots")),
211
220
  ...scopeFields,
212
221
  expectedRevision: v.number(),
213
222
  observations: v.array(observation),
@@ -227,17 +236,34 @@ type BatchArgs = {
227
236
  >;
228
237
  };
229
238
  export async function adoptHistoricalBatch(ctx: MutationCtx, args: BatchArgs) {
230
- if (!args.payouts.length || args.payouts.length > 100)
239
+ if (!args.payouts.length || (!args.snapshotId && args.payouts.length > 100))
231
240
  throw new Error("Invalid historical payout batch size.");
232
- const rows = await ctx.db
233
- .query("payoutReleaseClaims")
234
- .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
235
- .take(101);
241
+ const collected = await adoptionCollection(ctx, args, {
242
+ snapshotId: args.snapshotId,
243
+ observations: args.observations,
244
+ claims: args.expectedClaims,
245
+ });
246
+ const validated = collected
247
+ ? await checkSnapshot(
248
+ ctx,
249
+ args.accountId,
250
+ args.observations,
251
+ true,
252
+ undefined,
253
+ collected.sources,
254
+ )
255
+ : undefined;
256
+ const rows =
257
+ collected?.claims ??
258
+ (await ctx.db
259
+ .query("payoutReleaseClaims")
260
+ .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
261
+ .take(101));
236
262
  const expected = new Map(
237
263
  args.expectedClaims.map((c) => [c.operationKey, c.fingerprint]),
238
264
  );
239
265
  if (
240
- rows.length > 100 ||
266
+ (!collected && rows.length > 100) ||
241
267
  expected.size !== args.expectedClaims.length ||
242
268
  rows.length !== expected.size ||
243
269
  rows.some(
@@ -250,13 +276,17 @@ export async function adoptHistoricalBatch(ctx: MutationCtx, args: BatchArgs) {
250
276
  const claims = [];
251
277
  for (const p of args.payouts)
252
278
  claims.push(
253
- await adoptHistoricalPayout(ctx, {
254
- accountId: args.accountId,
255
- ownerKey: args.ownerKey,
256
- expectedRevision: args.expectedRevision,
257
- observations: args.observations,
258
- ...p,
259
- }),
279
+ await adoptHistoricalPayout(
280
+ ctx,
281
+ {
282
+ accountId: args.accountId,
283
+ ownerKey: args.ownerKey,
284
+ expectedRevision: args.expectedRevision,
285
+ observations: args.observations,
286
+ ...p,
287
+ },
288
+ validated,
289
+ ),
260
290
  );
261
291
  return { claims };
262
292
  }
@@ -66,6 +66,15 @@ export async function recordFees(
66
66
  )
67
67
  throw new Error("Verified payout return fee receipt changed.");
68
68
  const delta = add(fee, -(claim.providerFee ?? 0));
69
+ // Idempotent paid-history reads must not rewrite an already verified claim.
70
+ // Receipt identity, signed fee arithmetic and uniqueness were checked above.
71
+ if (
72
+ delta === 0 &&
73
+ claim.debitTransactionId === proof.debitTransactionId &&
74
+ claim.debitFee === proof.debitFee &&
75
+ claim.providerFee === fee
76
+ )
77
+ return;
69
78
  if (delta !== 0) {
70
79
  const balance = await readFees(ctx, claim);
71
80
  const amount = add(balance?.amount ?? 0, delta);
@@ -72,24 +72,29 @@ export async function checkSnapshot(
72
72
  observations: Infer<typeof observation>[],
73
73
  fresh: boolean,
74
74
  freshCurrency?: string,
75
+ membership?: Map<string, Doc<"transfers">>,
75
76
  ) {
76
- const rows = await ctx.db
77
- .query("transfers")
78
- .withIndex("by_destination_account_id", (q) =>
79
- q.eq("destinationAccountId", accountId),
80
- )
81
- .take(101);
77
+ const rows = membership
78
+ ? [...membership.values()]
79
+ : await ctx.db
80
+ .query("transfers")
81
+ .withIndex("by_destination_account_id", (q) =>
82
+ q.eq("destinationAccountId", accountId),
83
+ )
84
+ .take(101);
82
85
  if (
83
- rows.length > 100 ||
86
+ (!membership && rows.length > 100) ||
84
87
  observations.length !== rows.length ||
85
88
  new Set(observations.map((o) => o.stripeTransferId)).size !== rows.length
86
89
  )
87
90
  throw new Error("Payout source snapshot is incomplete or duplicated.");
88
91
  const byId = new Map(rows.map((row) => [row.stripeTransferId, row]));
89
- const allocated = await ctx.db
90
- .query("payoutSourceAllocations")
91
- .withIndex("by_account", (q) => q.eq("accountId", accountId))
92
- .take(101);
92
+ const allocated = membership
93
+ ? []
94
+ : await ctx.db
95
+ .query("payoutSourceAllocations")
96
+ .withIndex("by_account", (q) => q.eq("accountId", accountId))
97
+ .take(101);
93
98
  if (
94
99
  allocated.length > 100 ||
95
100
  allocated.some((source) => !byId.has(source.stripeTransferId))
@@ -179,6 +184,9 @@ export function payoutClaimFingerprint(c: Doc<"payoutReleaseClaims">) {
179
184
  c.ownerKey,
180
185
  c.operationKey,
181
186
  c.historical ?? false,
187
+ c.snapshotId,
188
+ c.liabilityRevision,
189
+ c.independentLiabilities,
182
190
  c.currency,
183
191
  c.amount,
184
192
  c.status,
@@ -1,3 +1,9 @@
1
+ import { outcomeArgs, recordPayoutOutcome } from "./outcome.js";
2
+ import {
3
+ collectedSources,
4
+ bindCollection,
5
+ retireCollection,
6
+ } from "../payoutSnapshots/financial.js";
1
7
  import {
2
8
  reserveRecoveryGuard,
3
9
  releaseRecoveryGuard,
@@ -6,7 +12,7 @@ import {
6
12
  historicalBatchArgs,
7
13
  adoptHistoricalBatch as importHistoricalBatch,
8
14
  } from "./adoption.js";
9
- import { readFees, recordFees } from "./fees.js";
15
+ import { readFees } from "./fees.js";
10
16
  import { v } from "convex/values";
11
17
  import { mutation } from "../earnings/triggers.js";
12
18
  import { identity, observation, claimDoc } from "./schema.js";
@@ -43,6 +49,8 @@ export const claim = mutation({
43
49
  providerAvailable: v.number(),
44
50
  independentLiabilities: v.number(),
45
51
  observations: v.array(observation),
52
+ snapshotId: v.optional(v.id("payoutSnapshots")),
53
+ liabilityRevision: v.optional(v.number()),
46
54
  },
47
55
  returns: v.union(claimDoc, held),
48
56
  handler: async (ctx, args) => {
@@ -106,10 +114,17 @@ export const claim = mutation({
106
114
  ...(args.destinationId ? { destinationId: args.destinationId } : {}),
107
115
  allocations: plan.allocations,
108
116
  observations: args.observations,
117
+ independentLiabilities: args.independentLiabilities,
118
+ ...(args.snapshotId ? { snapshotId: args.snapshotId } : {}),
119
+ ...(args.liabilityRevision === undefined
120
+ ? {}
121
+ : { liabilityRevision: args.liabilityRevision }),
109
122
  feeRevision: fees?.revision ?? 0,
110
123
  status: "reserved",
111
124
  });
112
- return (await ctx.db.get("payoutReleaseClaims", id))!;
125
+ const claim = (await ctx.db.get("payoutReleaseClaims", id))!;
126
+ await bindCollection(ctx, claim);
127
+ return claim;
113
128
  },
114
129
  });
115
130
  export const beginAttempt = mutation({
@@ -130,11 +145,13 @@ export const beginAttempt = mutation({
130
145
  claim.observations,
131
146
  true,
132
147
  claim.currency,
148
+ (await collectedSources(ctx, claim, claim.observations))?.transfers,
133
149
  );
134
150
  await reserveRecoveryGuard(ctx, claim, claim.amount);
135
151
  await ctx.db.patch("payoutReleaseClaims", claim._id, {
136
152
  attemptedAt: Date.now(),
137
153
  });
154
+ await retireCollection(ctx, claim);
138
155
  return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
139
156
  },
140
157
  });
@@ -151,6 +168,7 @@ export const cancelUnattempted = mutation({
151
168
  throw new Error("An attempted payout claim cannot be canceled.");
152
169
  if (claim.status === "canceled") return claim;
153
170
  await moveAllocations(ctx, claim, "release");
171
+ await retireCollection(ctx, claim);
154
172
  await releaseRecoveryGuard(ctx, claim);
155
173
  await ctx.db.patch("payoutReleaseClaims", claim._id, {
156
174
  status: "canceled",
@@ -159,107 +177,36 @@ export const cancelUnattempted = mutation({
159
177
  },
160
178
  });
161
179
  export const recordOutcome = mutation({
180
+ args: outcomeArgs,
181
+ returns: claimDoc,
182
+ handler: recordPayoutOutcome,
183
+ });
184
+ /** Bounded atomic reconciliation; every row retains the single-outcome validation. */
185
+ export const recordOutcomes = mutation({
162
186
  args: {
163
- ...identity,
164
- stripePayoutId: v.string(),
165
- amount: v.number(),
166
- currency: v.string(),
167
- providerStatus: v.union(
168
- v.literal("pending"),
169
- v.literal("in_transit"),
170
- v.literal("paid"),
171
- v.literal("failed"),
172
- v.literal("canceled"),
173
- ),
174
- returnTransactionId: v.optional(v.string()),
175
- debitTransactionId: v.optional(v.string()),
176
- debitFee: v.optional(v.number()),
177
- returnFee: v.optional(v.number()),
187
+ accountId: v.string(),
188
+ ownerKey: v.string(),
189
+ outcomes: v.array(outcomeArgs),
178
190
  },
179
- returns: claimDoc,
191
+ returns: v.array(claimDoc),
180
192
  handler: async (ctx, args) => {
181
- const claim = await claimByKey(ctx, args);
182
- if (
183
- !claim ||
184
- claim.attemptedAt === undefined ||
185
- claim.status === "canceled" ||
186
- claim.status === "rejected"
187
- )
188
- throw new Error("Payout receipt has no attempted claim.");
189
193
  if (
190
- !/^po_\w+$/.test(args.stripePayoutId) ||
191
- args.stripePayoutId.trim() !== args.stripePayoutId ||
192
- args.currency !== claim.currency ||
193
- args.amount !== claim.amount ||
194
- (claim.stripePayoutId !== undefined &&
195
- claim.stripePayoutId !== args.stripePayoutId)
194
+ !args.outcomes.length ||
195
+ args.outcomes.length > 25 ||
196
+ new Set(args.outcomes.map((o) => o.operationKey)).size !==
197
+ args.outcomes.length
196
198
  )
197
- throw new Error("Payout receipt identity or amount does not match.");
198
- const adopted = await ctx.db
199
- .query("payoutReleaseClaims")
200
- .withIndex("by_provider_payout", (q) =>
201
- q.eq("stripePayoutId", args.stripePayoutId),
199
+ throw new Error("Invalid payout outcome batch.");
200
+ const results = [];
201
+ for (const outcome of args.outcomes) {
202
+ if (
203
+ outcome.accountId !== args.accountId ||
204
+ outcome.ownerKey !== args.ownerKey
202
205
  )
203
- .unique();
204
- if (adopted && adopted._id !== claim._id)
205
- throw new Error("Payout receipt identity is already allocated.");
206
- if (
207
- args.returnTransactionId !== undefined &&
208
- (!/^txn_\w+$/.test(args.returnTransactionId) ||
209
- args.returnTransactionId.trim() !== args.returnTransactionId)
210
- )
211
- throw new Error("Invalid payout return receipt identity.");
212
- const returned =
213
- (args.providerStatus === "failed" ||
214
- args.providerStatus === "canceled") &&
215
- args.returnTransactionId !== undefined;
216
- if (returned) {
217
- const adoptedReturn = await ctx.db
218
- .query("payoutReleaseClaims")
219
- .withIndex("by_return_receipt", (q) =>
220
- q.eq("returnTransactionId", args.returnTransactionId),
221
- )
222
- .unique();
223
- if (adoptedReturn && adoptedReturn._id !== claim._id)
224
- throw new Error("Payout return receipt is already allocated.");
225
- }
226
- if (claim.status === "returned") {
227
- if (returned && args.returnTransactionId !== claim.returnTransactionId)
228
- throw new Error("Payout return receipt identity changed.");
229
- if (returned) {
230
- await recordFees(ctx, claim, args, true);
231
- return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
232
- }
233
- return claim;
234
- }
235
- if (claim.status === "paid" && args.providerStatus !== "paid" && !returned)
236
- return claim;
237
- await recordFees(ctx, claim, args, returned);
238
- await releaseRecoveryGuard(ctx, claim);
239
- if (returned) {
240
- await moveAllocations(
241
- ctx,
242
- claim,
243
- claim.status === "paid" ? "return" : "release",
244
- );
245
- await ctx.db.patch("payoutReleaseClaims", claim._id, {
246
- status: "returned",
247
- stripePayoutId: args.stripePayoutId,
248
- returnTransactionId: args.returnTransactionId,
249
- });
250
- } else if (args.providerStatus === "paid" && claim.status !== "paid") {
251
- await moveAllocations(ctx, claim, "pay");
252
- await ctx.db.patch("payoutReleaseClaims", claim._id, {
253
- status: "paid",
254
- stripePayoutId: args.stripePayoutId,
255
- });
256
- } else if (claim.status !== "paid") {
257
- await ctx.db.patch("payoutReleaseClaims", claim._id, {
258
- status: "submitted",
259
- stripePayoutId: args.stripePayoutId,
260
- });
206
+ throw new Error("Payout outcome batch ownership changed.");
207
+ results.push(await recordPayoutOutcome(ctx, outcome));
261
208
  }
262
- return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
209
+ return results;
263
210
  },
264
211
  });
265
212
 
@@ -0,0 +1,119 @@
1
+ import { v, type Infer } from "convex/values";
2
+ import type { MutationCtx } from "../_generated/server.js";
3
+ import { identity } from "./schema.js";
4
+ import { claimByKey, moveAllocations } from "./helpers.js";
5
+ import { recordFees } from "./fees.js";
6
+ import { releaseRecoveryGuard } from "../affiliatePayouts/recipientGuard.js";
7
+
8
+ export const outcomeArgs = v.object({
9
+ ...identity,
10
+ stripePayoutId: v.string(),
11
+ amount: v.number(),
12
+ currency: v.string(),
13
+ providerStatus: v.union(
14
+ v.literal("pending"),
15
+ v.literal("in_transit"),
16
+ v.literal("paid"),
17
+ v.literal("failed"),
18
+ v.literal("canceled"),
19
+ ),
20
+ returnTransactionId: v.optional(v.string()),
21
+ debitTransactionId: v.optional(v.string()),
22
+ debitFee: v.optional(v.number()),
23
+ returnFee: v.optional(v.number()),
24
+ });
25
+ export async function recordPayoutOutcome(
26
+ ctx: MutationCtx,
27
+ args: Infer<typeof outcomeArgs>,
28
+ ) {
29
+ const claim = await claimByKey(ctx, args);
30
+ if (
31
+ !claim ||
32
+ claim.attemptedAt === undefined ||
33
+ claim.status === "canceled" ||
34
+ claim.status === "rejected"
35
+ )
36
+ throw new Error("Payout receipt has no attempted claim.");
37
+ if (
38
+ !/^po_\w+$/.test(args.stripePayoutId) ||
39
+ args.stripePayoutId.trim() !== args.stripePayoutId ||
40
+ args.currency !== claim.currency ||
41
+ args.amount !== claim.amount ||
42
+ (claim.stripePayoutId !== undefined &&
43
+ claim.stripePayoutId !== args.stripePayoutId)
44
+ )
45
+ throw new Error("Payout receipt identity or amount does not match.");
46
+ const adopted = await ctx.db
47
+ .query("payoutReleaseClaims")
48
+ .withIndex("by_provider_payout", (q) =>
49
+ q.eq("stripePayoutId", args.stripePayoutId),
50
+ )
51
+ .unique();
52
+ if (adopted && adopted._id !== claim._id)
53
+ throw new Error("Payout receipt identity is already allocated.");
54
+ if (
55
+ args.returnTransactionId !== undefined &&
56
+ (!/^txn_\w+$/.test(args.returnTransactionId) ||
57
+ args.returnTransactionId.trim() !== args.returnTransactionId)
58
+ )
59
+ throw new Error("Invalid payout return receipt identity.");
60
+ const returned =
61
+ (args.providerStatus === "failed" || args.providerStatus === "canceled") &&
62
+ args.returnTransactionId !== undefined;
63
+ if (returned) {
64
+ const adoptedReturn = await ctx.db
65
+ .query("payoutReleaseClaims")
66
+ .withIndex("by_return_receipt", (q) =>
67
+ q.eq("returnTransactionId", args.returnTransactionId),
68
+ )
69
+ .unique();
70
+ if (adoptedReturn && adoptedReturn._id !== claim._id)
71
+ throw new Error("Payout return receipt is already allocated.");
72
+ }
73
+ if (claim.status === "returned") {
74
+ if (returned && args.returnTransactionId !== claim.returnTransactionId)
75
+ throw new Error("Payout return receipt identity changed.");
76
+ if (returned) {
77
+ await recordFees(ctx, claim, args, true);
78
+ return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
79
+ }
80
+ return claim;
81
+ }
82
+ if (claim.status === "paid" && args.providerStatus !== "paid" && !returned)
83
+ return claim;
84
+ await recordFees(ctx, claim, args, returned);
85
+ await releaseRecoveryGuard(ctx, claim);
86
+ if (
87
+ claim.status === "paid" &&
88
+ args.providerStatus === "paid" &&
89
+ args.debitTransactionId !== undefined &&
90
+ claim.debitTransactionId === args.debitTransactionId &&
91
+ claim.debitFee === args.debitFee &&
92
+ claim.providerFee === args.debitFee
93
+ )
94
+ return claim;
95
+ if (returned) {
96
+ await moveAllocations(
97
+ ctx,
98
+ claim,
99
+ claim.status === "paid" ? "return" : "release",
100
+ );
101
+ await ctx.db.patch("payoutReleaseClaims", claim._id, {
102
+ status: "returned",
103
+ stripePayoutId: args.stripePayoutId,
104
+ returnTransactionId: args.returnTransactionId,
105
+ });
106
+ } else if (args.providerStatus === "paid" && claim.status !== "paid") {
107
+ await moveAllocations(ctx, claim, "pay");
108
+ await ctx.db.patch("payoutReleaseClaims", claim._id, {
109
+ status: "paid",
110
+ stripePayoutId: args.stripePayoutId,
111
+ });
112
+ } else if (claim.status !== "paid") {
113
+ await ctx.db.patch("payoutReleaseClaims", claim._id, {
114
+ status: "submitted",
115
+ stripePayoutId: args.stripePayoutId,
116
+ });
117
+ }
118
+ return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
119
+ }
@@ -1,3 +1,5 @@
1
+ import { collectedSources } from "../payoutSnapshots/financial.js";
2
+ import type { Id } from "../_generated/dataModel.js";
1
3
  import type { Infer } from "convex/values";
2
4
  import type { MutationCtx, QueryCtx } from "../_generated/server.js";
3
5
  import type { policyDoc } from "../payoutPolicy/schema.js";
@@ -14,6 +16,9 @@ export async function readPayoutPlan(
14
16
  ownerKey: string;
15
17
  currency: string;
16
18
  observations: Infer<typeof observation>[];
19
+ snapshotId?: Id<"payoutSnapshots">;
20
+ operationKey?: string;
21
+ liabilityRevision?: number;
17
22
  providerAvailable: number;
18
23
  independentLiabilities: number;
19
24
  },
@@ -21,16 +26,20 @@ export async function readPayoutPlan(
21
26
  ) {
22
27
  const minimum = policy.thresholds.find((t) => t.currency === args.currency);
23
28
  if (!minimum) throw new Error("Payout policy currency is not configured.");
29
+ const collection = await collectedSources(ctx, args, args.observations);
24
30
  const rows = await checkSnapshot(
25
31
  ctx,
26
32
  args.accountId,
27
33
  args.observations,
28
34
  true,
29
35
  args.currency,
36
+ collection?.transfers,
30
37
  );
31
38
  const sources: PayoutFundingSource[] = [];
32
39
  for (const observation of args.observations) {
33
- const prior = await sourceById(ctx, observation.stripeTransferId);
40
+ const prior = collection?.allocations.has(observation.stripeTransferId)
41
+ ? collection.allocations.get(observation.stripeTransferId)
42
+ : await sourceById(ctx, observation.stripeTransferId);
34
43
  if (
35
44
  prior &&
36
45
  (prior.accountId !== args.accountId ||
@@ -46,7 +55,7 @@ export async function readPayoutPlan(
46
55
  });
47
56
  }
48
57
  const fees = await readFees(ctx, args);
49
- await assertAllocationTotals(ctx, args, sources);
58
+ if (!args.snapshotId) await assertAllocationTotals(ctx, args, sources);
50
59
  const minimumWaived = waiveApplicationMinimum(policy, Date.now());
51
60
  const plan = planRecipientPayout({
52
61
  currency: args.currency,
@@ -14,6 +14,8 @@ export const previewFields = {
14
14
  providerAvailable: v.number(),
15
15
  independentLiabilities: v.number(),
16
16
  observations: v.array(observation),
17
+ snapshotId: v.optional(v.id("payoutSnapshots")),
18
+ liabilityRevision: v.optional(v.number()),
17
19
  };
18
20
  const held = v.object({
19
21
  status: v.literal("held"),
@@ -97,6 +97,8 @@ export const snapshot = query({
97
97
  q.eq("destinationAccountId", args.accountId),
98
98
  )
99
99
  .take(101);
100
+ if (transfers.length > 100)
101
+ return { status: "held" as const, reason: "snapshot_limit" as const };
100
102
  const claims = await ctx.db
101
103
  .query("payoutReleaseClaims")
102
104
  .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
@@ -13,6 +13,9 @@ export const allocation = v.object({
13
13
  export const claimFields = {
14
14
  ...scopeFields,
15
15
  historical: v.optional(v.boolean()),
16
+ snapshotId: v.optional(v.id("payoutSnapshots")),
17
+ liabilityRevision: v.optional(v.number()),
18
+ independentLiabilities: v.optional(v.number()),
16
19
  operationKey: v.string(),
17
20
  expectedRevision: v.number(),
18
21
  currency: v.string(),