@fantastic.dev/better-stripe 0.38.0 → 0.39.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 (127) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/MIGRATION.md +9 -0
  3. package/README.md +21 -1
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +506 -2
  5. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +253 -1
  7. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +506 -2
  9. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts +253 -1
  11. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  12. package/dist/client/costRecovery.d.ts +18 -0
  13. package/dist/client/costRecovery.d.ts.map +1 -1
  14. package/dist/client/costRecovery.js +4 -0
  15. package/dist/client/costRecovery.js.map +1 -1
  16. package/dist/client/index.d.ts +1 -0
  17. package/dist/client/index.d.ts.map +1 -1
  18. package/dist/client/index.js +1 -0
  19. package/dist/client/index.js.map +1 -1
  20. package/dist/client/processingCostDeficit/index.d.ts +27 -0
  21. package/dist/client/processingCostDeficit/index.d.ts.map +1 -0
  22. package/dist/client/processingCostDeficit/index.js +54 -0
  23. package/dist/client/processingCostDeficit/index.js.map +1 -0
  24. package/dist/component/_generated/api.d.ts +284 -0
  25. package/dist/component/_generated/api.d.ts.map +1 -0
  26. package/dist/component/_generated/api.js +31 -0
  27. package/dist/component/_generated/api.js.map +1 -0
  28. package/dist/component/_generated/component.d.ts +527 -0
  29. package/dist/component/_generated/component.d.ts.map +1 -1
  30. package/dist/component/balanceFunding/helpers.d.ts +86 -0
  31. package/dist/component/balanceFunding/helpers.d.ts.map +1 -0
  32. package/dist/component/balanceFunding/helpers.js +68 -0
  33. package/dist/component/balanceFunding/helpers.js.map +1 -0
  34. package/dist/component/balanceFunding/importHandler.d.ts +13 -0
  35. package/dist/component/balanceFunding/importHandler.d.ts.map +1 -0
  36. package/dist/component/balanceFunding/importHandler.js +130 -0
  37. package/dist/component/balanceFunding/importHandler.js.map +1 -0
  38. package/dist/component/balanceFunding/lifecycleHandlers.d.ts +85 -0
  39. package/dist/component/balanceFunding/lifecycleHandlers.d.ts.map +1 -0
  40. package/dist/component/balanceFunding/lifecycleHandlers.js +60 -0
  41. package/dist/component/balanceFunding/lifecycleHandlers.js.map +1 -0
  42. package/dist/component/balanceFunding/mutationValidators.d.ts +238 -0
  43. package/dist/component/balanceFunding/mutationValidators.d.ts.map +1 -0
  44. package/dist/component/balanceFunding/mutationValidators.js +55 -0
  45. package/dist/component/balanceFunding/mutationValidators.js.map +1 -0
  46. package/dist/component/balanceFunding/mutations.d.ts +335 -0
  47. package/dist/component/balanceFunding/mutations.d.ts.map +1 -0
  48. package/dist/component/balanceFunding/mutations.js +106 -0
  49. package/dist/component/balanceFunding/mutations.js.map +1 -0
  50. package/dist/component/balanceFunding/preparationHandlers.d.ts +55 -0
  51. package/dist/component/balanceFunding/preparationHandlers.d.ts.map +1 -0
  52. package/dist/component/balanceFunding/preparationHandlers.js +165 -0
  53. package/dist/component/balanceFunding/preparationHandlers.js.map +1 -0
  54. package/dist/component/balanceFunding/queries.d.ts +151 -0
  55. package/dist/component/balanceFunding/queries.d.ts.map +1 -0
  56. package/dist/component/balanceFunding/queries.js +180 -0
  57. package/dist/component/balanceFunding/queries.js.map +1 -0
  58. package/dist/component/balanceFunding/schema.d.ts +748 -0
  59. package/dist/component/balanceFunding/schema.d.ts.map +1 -0
  60. package/dist/component/balanceFunding/schema.js +124 -0
  61. package/dist/component/balanceFunding/schema.js.map +1 -0
  62. package/dist/component/balanceFunding/stateHandlers.d.ts +58 -0
  63. package/dist/component/balanceFunding/stateHandlers.d.ts.map +1 -0
  64. package/dist/component/balanceFunding/stateHandlers.js +160 -0
  65. package/dist/component/balanceFunding/stateHandlers.js.map +1 -0
  66. package/dist/component/convex.config.d.ts.map +1 -1
  67. package/dist/component/convex.config.js +2 -0
  68. package/dist/component/convex.config.js.map +1 -1
  69. package/dist/component/costRecovery/completion.d.ts +1 -0
  70. package/dist/component/costRecovery/completion.d.ts.map +1 -1
  71. package/dist/component/costRecovery/helpers.d.ts +1 -0
  72. package/dist/component/costRecovery/helpers.d.ts.map +1 -1
  73. package/dist/component/costRecovery/mutations.d.ts +5 -0
  74. package/dist/component/costRecovery/mutations.d.ts.map +1 -1
  75. package/dist/component/costRecovery/preparation.d.ts +50 -0
  76. package/dist/component/costRecovery/preparation.d.ts.map +1 -0
  77. package/dist/component/costRecovery/preparation.js +108 -0
  78. package/dist/component/costRecovery/preparation.js.map +1 -0
  79. package/dist/component/costRecovery/queries.d.ts +1 -0
  80. package/dist/component/costRecovery/queries.d.ts.map +1 -1
  81. package/dist/component/costRecovery/reservations.d.ts +2 -0
  82. package/dist/component/costRecovery/reservations.d.ts.map +1 -1
  83. package/dist/component/costRecovery/schema.d.ts +7 -2
  84. package/dist/component/costRecovery/schema.d.ts.map +1 -1
  85. package/dist/component/costRecovery/schema.js +1 -0
  86. package/dist/component/costRecovery/schema.js.map +1 -1
  87. package/dist/component/durableExecution/runtime.d.ts +3 -0
  88. package/dist/component/durableExecution/runtime.d.ts.map +1 -0
  89. package/dist/component/durableExecution/runtime.js +12 -0
  90. package/dist/component/durableExecution/runtime.js.map +1 -0
  91. package/dist/component/earnings/triggers.d.ts +242 -2
  92. package/dist/component/earnings/triggers.d.ts.map +1 -1
  93. package/dist/component/schema.d.ts +253 -1
  94. package/dist/component/schema.js +4 -0
  95. package/dist/component/schema.js.map +1 -1
  96. package/package.json +4 -2
  97. package/src/client/costRecovery.test.ts +34 -0
  98. package/src/client/costRecovery.ts +21 -0
  99. package/src/client/index.ts +1 -0
  100. package/src/client/processingCostDeficit/README.md +35 -0
  101. package/src/client/processingCostDeficit/calculator.test.ts +176 -0
  102. package/src/client/processingCostDeficit/index.ts +91 -0
  103. package/src/component/_generated/api.ts +23 -1
  104. package/src/component/_generated/component.ts +693 -0
  105. package/src/component/balanceFunding/failure.test.ts +116 -0
  106. package/src/component/balanceFunding/helpers.ts +102 -0
  107. package/src/component/balanceFunding/import.test.ts +221 -0
  108. package/src/component/balanceFunding/importHandler.ts +146 -0
  109. package/src/component/balanceFunding/lifecycleHandlers.ts +90 -0
  110. package/src/component/balanceFunding/lookup.test.ts +113 -0
  111. package/src/component/balanceFunding/mutationValidators.ts +63 -0
  112. package/src/component/balanceFunding/mutations.ts +136 -0
  113. package/src/component/balanceFunding/preparation.test.ts +146 -0
  114. package/src/component/balanceFunding/preparationHandlers.ts +204 -0
  115. package/src/component/balanceFunding/queries.ts +221 -0
  116. package/src/component/balanceFunding/requestLookup.test.ts +160 -0
  117. package/src/component/balanceFunding/schema.ts +169 -0
  118. package/src/component/balanceFunding/state.test.ts +352 -0
  119. package/src/component/balanceFunding/stateHandlers.ts +198 -0
  120. package/src/component/balanceFunding/validation.test.ts +100 -0
  121. package/src/component/convex.config.ts +2 -0
  122. package/src/component/costRecovery/preparation.test.ts +355 -0
  123. package/src/component/costRecovery/preparation.ts +124 -0
  124. package/src/component/costRecovery/schema.ts +1 -0
  125. package/src/component/durableExecution/composition.test.ts +568 -0
  126. package/src/component/durableExecution/runtime.ts +12 -0
  127. package/src/component/schema.ts +8 -0
@@ -0,0 +1,355 @@
1
+ // @vitest-environment edge-runtime
2
+ import { convexTest } from "convex-test";
3
+ import { makeFunctionReference } from "convex/server";
4
+ import { expect, it } from "vitest";
5
+ import { schema, modules } from "../../test.js";
6
+ const prepare = makeFunctionReference<"mutation">(
7
+ "costRecovery/preparation:prepare",
8
+ );
9
+ const record = makeFunctionReference<"mutation">(
10
+ "costRecovery/mutations:record",
11
+ );
12
+ const scope = { accountId: "acct_owner", scopeKey: "opaque", currency: "usd" };
13
+ const options = {
14
+ ...scope,
15
+ groupKey: "group",
16
+ sourceKind: "invoice" as const,
17
+ sourceId: "in_original",
18
+ maxDebit: 1000,
19
+ maxCredit: 1000,
20
+ };
21
+ const observation = (claimKey: string, amountDue: number, revision = 1) => ({
22
+ ...scope,
23
+ claimKey,
24
+ sourceChargeId: `ch_${claimKey}`,
25
+ sourceGross: 10000,
26
+ sourceProcessingFee: 320,
27
+ amountDue,
28
+ revision,
29
+ });
30
+ it("reserves and seals a complete group in one mutation, with stable replay", async () => {
31
+ const t = convexTest(schema, modules);
32
+ await t.mutation(record, observation("fee", 320));
33
+ const result = await t.mutation(prepare, options);
34
+ expect(result).toMatchObject({
35
+ status: "prepared",
36
+ isDone: true,
37
+ group: { amount: 320, status: "sealed" },
38
+ });
39
+ expect(await t.mutation(prepare, options)).toEqual(result);
40
+ expect(
41
+ await t.run((ctx) => ctx.db.query("recoveryReservations").collect()),
42
+ ).toHaveLength(1);
43
+ });
44
+ it("prepares a bounded batch and advances to seal on a later invocation", async () => {
45
+ const t = convexTest(schema, modules);
46
+ for (let i = 0; i < 3; i++)
47
+ await t.mutation(record, observation(`fee${i}`, 10));
48
+ expect(await t.mutation(prepare, { ...options, limit: 1 })).toMatchObject({
49
+ status: "prepared",
50
+ isDone: false,
51
+ group: { amount: 10, status: "open" },
52
+ });
53
+ expect(await t.mutation(prepare, { ...options, limit: 1 })).toMatchObject({
54
+ status: "prepared",
55
+ isDone: false,
56
+ group: { amount: 20 },
57
+ });
58
+ expect(await t.mutation(prepare, { ...options, limit: 1 })).toMatchObject({
59
+ status: "prepared",
60
+ isDone: true,
61
+ group: { amount: 30, status: "sealed" },
62
+ });
63
+ });
64
+ it("returns scope_busy for a concurrent foreign boundary without reserving twice", async () => {
65
+ const t = convexTest(schema, modules);
66
+ await t.mutation(record, observation("fee", 320));
67
+ const results = await Promise.all([
68
+ t.mutation(prepare, { ...options, groupKey: "one" }),
69
+ t.mutation(prepare, { ...options, groupKey: "two" }),
70
+ ]);
71
+ expect(results.map((result) => result.status).sort()).toEqual([
72
+ "conflict",
73
+ "prepared",
74
+ ]);
75
+ expect(results.find((result) => result.status === "conflict")).toEqual({
76
+ status: "conflict",
77
+ reason: "scope_busy",
78
+ retryable: false,
79
+ });
80
+ expect(
81
+ await t.run((ctx) => ctx.db.query("recoveryReservations").collect()),
82
+ ).toHaveLength(1);
83
+ });
84
+ it.each([
85
+ { accountId: "acct_foreign" },
86
+ { scopeKey: "foreign" },
87
+ { currency: "eur" },
88
+ { sourceId: "in_foreign" },
89
+ { sourceKind: "settlement", sourceGross: 10000, sourceProcessingFee: 320 },
90
+ { maxDebit: 900 },
91
+ { maxCredit: 900 },
92
+ { sourceGross: 10000 },
93
+ { sourceProcessingFee: 0 },
94
+ ])(
95
+ "rejects immutable identity changes even after sealing: %j",
96
+ async (changes) => {
97
+ const t = convexTest(schema, modules);
98
+ await t.mutation(record, observation("fee", 320));
99
+ const initial = await t.mutation(prepare, options);
100
+ expect(await t.mutation(prepare, { ...options, ...changes })).toEqual({
101
+ status: "conflict",
102
+ reason: "identity_changed",
103
+ retryable: false,
104
+ });
105
+ expect(await t.mutation(prepare, options)).toEqual(initial);
106
+ },
107
+ );
108
+ it.each([
109
+ [{ accountId: "" }, "invalid_scope"],
110
+ [{ currency: "USD" }, "invalid_scope"],
111
+ [{ groupKey: " " }, "invalid_scope"],
112
+ [{ sourceId: "" }, "invalid_scope"],
113
+ [{ limit: 0 }, "policy_invalid"],
114
+ [{ limit: 101 }, "policy_invalid"],
115
+ [{ maxDebit: -1 }, "policy_invalid"],
116
+ [{ maxCredit: 1.5 }, "policy_invalid"],
117
+ [{ sourceGross: 0 }, "policy_invalid"],
118
+ [{ sourceProcessingFee: -1 }, "policy_invalid"],
119
+ ])(
120
+ "rejects invalid scope or policy before writing: %j",
121
+ async (changes, reason) => {
122
+ const t = convexTest(schema, modules);
123
+ expect(await t.mutation(prepare, { ...options, ...changes })).toEqual({
124
+ status: "rejected",
125
+ reason,
126
+ retryable: false,
127
+ });
128
+ expect(
129
+ await t.run((ctx) => ctx.db.query("recoveryGroups").collect()),
130
+ ).toHaveLength(0);
131
+ },
132
+ );
133
+ it("does not recycle an empty legacy operation identity when continuing an open group", async () => {
134
+ const t = convexTest(schema, modules);
135
+ await t.mutation(
136
+ makeFunctionReference<"mutation">("costRecovery/mutations:reserve"),
137
+ {
138
+ ...options,
139
+ operationKey: 'prepare:["group",1]',
140
+ },
141
+ );
142
+ await t.mutation(record, observation("fee", 320));
143
+ expect(await t.mutation(prepare, options)).toMatchObject({
144
+ status: "prepared",
145
+ isDone: true,
146
+ group: { amount: 320, preparationSequence: 1 },
147
+ });
148
+ const operations = await t.run((ctx) =>
149
+ ctx.db.query("recoveryReservations").collect(),
150
+ );
151
+ expect(operations).toHaveLength(2);
152
+ expect(
153
+ operations.find((op) => op.operationKey === 'prepare:["group",1]')?.status,
154
+ ).toBe("empty");
155
+ });
156
+ it("rejects a caller-created preparation key collision without recycling it", async () => {
157
+ const t = convexTest(schema, modules);
158
+ await t.mutation(
159
+ makeFunctionReference<"mutation">("costRecovery/mutations:reserve"),
160
+ {
161
+ ...options,
162
+ operationKey: 'recovery-preparation:["group",1]',
163
+ },
164
+ );
165
+ await t.mutation(record, observation("fee", 320));
166
+ expect(await t.mutation(prepare, options)).toEqual({
167
+ status: "conflict",
168
+ reason: "identity_changed",
169
+ retryable: false,
170
+ });
171
+ expect(
172
+ await t.run((ctx) => ctx.db.query("recoveryReservations").collect()),
173
+ ).toHaveLength(1);
174
+ });
175
+ it.each(["accountId", "scopeKey"])(
176
+ "rejects whitespace-only %s",
177
+ async (key) => {
178
+ const t = convexTest(schema, modules);
179
+ expect(await t.mutation(prepare, { ...options, [key]: " " })).toEqual({
180
+ status: "rejected",
181
+ reason: "invalid_scope",
182
+ retryable: false,
183
+ });
184
+ },
185
+ );
186
+ it("recomputes a changed signed target between batches and preserves ledger totals", async () => {
187
+ const t = convexTest(schema, modules);
188
+ await t.mutation(record, observation("one", 10));
189
+ await t.mutation(record, observation("two", 10));
190
+ const first = await t.mutation(prepare, { ...options, limit: 1 });
191
+ expect(first).toMatchObject({
192
+ status: "prepared",
193
+ isDone: false,
194
+ group: { amount: 10 },
195
+ });
196
+ const reserved = await t.run((ctx) =>
197
+ ctx.db.query("recoveryClaims").collect(),
198
+ );
199
+ const selected = reserved.find((claim) => claim.reservedAmount === 10)!;
200
+ await t.mutation(record, observation(selected.claimKey, -15, 2));
201
+ expect(await t.mutation(prepare, { ...options, limit: 1 })).toMatchObject({
202
+ status: "prepared",
203
+ isDone: true,
204
+ group: { amount: -5, preparationSequence: 2 },
205
+ });
206
+ const balance = await t.run((ctx) =>
207
+ ctx.db.query("recoveryBalances").unique(),
208
+ );
209
+ expect(balance).toMatchObject({
210
+ amountDue: -5,
211
+ collectedAmount: 0,
212
+ reservedAmount: -5,
213
+ outstanding: 0,
214
+ });
215
+ const claims = await t.run((ctx) => ctx.db.query("recoveryClaims").collect());
216
+ for (const claim of claims)
217
+ expect(claim.amountDue).toBe(
218
+ claim.collectedAmount + claim.reservedAmount + claim.outstanding,
219
+ );
220
+ });
221
+ it("advances a shared group's sequence for concurrent bounded invocations", async () => {
222
+ const t = convexTest(schema, modules);
223
+ for (let i = 0; i < 3; i++)
224
+ await t.mutation(record, observation(`fee${i}`, 10));
225
+ const results = await Promise.all([
226
+ t.mutation(prepare, { ...options, limit: 1 }),
227
+ t.mutation(prepare, { ...options, limit: 1 }),
228
+ ]);
229
+ expect(
230
+ results.map((result) => result.group.amount).sort((a, b) => a - b),
231
+ ).toEqual([10, 20]);
232
+ const operations = await t.run((ctx) =>
233
+ ctx.db.query("recoveryReservations").collect(),
234
+ );
235
+ expect(
236
+ new Set(operations.map((operation) => operation.operationKey)).size,
237
+ ).toBe(2);
238
+ expect(await t.mutation(prepare, { ...options, limit: 1 })).toMatchObject({
239
+ isDone: true,
240
+ group: { amount: 30, preparationSequence: 3 },
241
+ });
242
+ });
243
+ it("seals an empty group once and does not allocate on replay", async () => {
244
+ const t = convexTest(schema, modules);
245
+ const result = await t.mutation(prepare, options);
246
+ expect(result).toMatchObject({
247
+ isDone: true,
248
+ group: { amount: 0, preparationSequence: 1, status: "sealed" },
249
+ });
250
+ expect(await t.mutation(prepare, options)).toEqual(result);
251
+ expect(
252
+ await t.run((ctx) => ctx.db.query("recoveryReservations").collect()),
253
+ ).toHaveLength(1);
254
+ });
255
+ it("caps the debit target while leaving further liabilities outstanding", async () => {
256
+ const t = convexTest(schema, modules);
257
+ await t.mutation(record, observation("fee", 320));
258
+ expect(
259
+ await t.mutation(prepare, { ...options, maxDebit: 100 }),
260
+ ).toMatchObject({ isDone: true, group: { amount: 100, status: "sealed" } });
261
+ expect(
262
+ await t.run((ctx) => ctx.db.query("recoveryBalances").unique()),
263
+ ).toMatchObject({ outstanding: 220, reservedAmount: 100 });
264
+ });
265
+ it("prepares 101 claims in two default bounded calls", async () => {
266
+ const t = convexTest(schema, modules);
267
+ for (let i = 0; i < 101; i++)
268
+ await t.mutation(record, observation(`fee${i}`, 1));
269
+ const first = await t.mutation(prepare, options);
270
+ expect(first).toMatchObject({
271
+ isDone: false,
272
+ group: { amount: 100, preparationSequence: 1 },
273
+ });
274
+ expect(await t.mutation(prepare, options)).toMatchObject({
275
+ isDone: true,
276
+ group: { amount: 101, preparationSequence: 2 },
277
+ });
278
+ const operations = await t.run((ctx) =>
279
+ ctx.db.query("recoveryReservations").collect(),
280
+ );
281
+ expect(
282
+ operations.map((op) => op.allocations.length).sort((a, b) => a - b),
283
+ ).toEqual([1, 100]);
284
+ });
285
+ it("replays a collected group without allocating or collecting again", async () => {
286
+ const t = convexTest(schema, modules);
287
+ await t.mutation(record, observation("fee", 320));
288
+ await t.mutation(prepare, options);
289
+ const finished = await t.mutation(
290
+ makeFunctionReference<"mutation">("costRecovery/mutations:finish"),
291
+ { groupKey: options.groupKey, outcome: "collect" },
292
+ );
293
+ expect(await t.mutation(prepare, options)).toEqual({
294
+ status: "prepared",
295
+ isDone: true,
296
+ group: finished.group,
297
+ });
298
+ expect(
299
+ await t.run((ctx) => ctx.db.query("recoveryReservations").collect()),
300
+ ).toHaveLength(1);
301
+ expect(
302
+ await t.run((ctx) => ctx.db.query("recoveryBalances").unique()),
303
+ ).toMatchObject({ collectedAmount: 320, reservedAmount: 0, outstanding: 0 });
304
+ });
305
+ it.each([
306
+ { accountId: "acct_foreign" },
307
+ { scopeKey: "foreign" },
308
+ { currency: "eur" },
309
+ ])("isolates foreign claims and active boundaries: %j", async (foreign) => {
310
+ const t = convexTest(schema, modules);
311
+ await t.mutation(record, observation("own", 100));
312
+ await t.mutation(record, { ...observation("foreign", 900), ...foreign });
313
+ await t.mutation(prepare, {
314
+ ...options,
315
+ ...foreign,
316
+ groupKey: "foreign-group",
317
+ });
318
+ expect(await t.mutation(prepare, options)).toMatchObject({
319
+ isDone: true,
320
+ group: {
321
+ amount: 100,
322
+ accountId: scope.accountId,
323
+ scopeKey: scope.scopeKey,
324
+ currency: scope.currency,
325
+ },
326
+ });
327
+ });
328
+ it("uses the original settlement economics and signed credit limit", async () => {
329
+ const t = convexTest(schema, modules);
330
+ await t.mutation(record, observation("credit", -320));
331
+ const settlement = {
332
+ ...options,
333
+ sourceKind: "settlement",
334
+ sourceId: "ch_original",
335
+ sourceGross: 10000,
336
+ sourceProcessingFee: 320,
337
+ maxCredit: 50,
338
+ };
339
+ expect(await t.mutation(prepare, settlement)).toMatchObject({
340
+ isDone: true,
341
+ group: { amount: -50, sourceGross: 10000, sourceProcessingFee: 320 },
342
+ });
343
+ expect(
344
+ await t.run((ctx) => ctx.db.query("recoveryBalances").unique()),
345
+ ).toMatchObject({ outstanding: -270, reservedAmount: -50 });
346
+ });
347
+ it("requires original settlement funding economics before reserving", async () => {
348
+ const t = convexTest(schema, modules);
349
+ expect(
350
+ await t.mutation(prepare, { ...options, sourceKind: "settlement" }),
351
+ ).toEqual({ status: "rejected", reason: "policy_invalid", retryable: false });
352
+ expect(
353
+ await t.run((ctx) => ctx.db.query("recoveryGroups").collect()),
354
+ ).toHaveLength(0);
355
+ });
@@ -0,0 +1,124 @@
1
+ import { v } from "convex/values";
2
+ import { mutation } from "../earnings/triggers.js";
3
+ import { groupDoc, groupInput } from "./schema.js";
4
+ import {
5
+ balance,
6
+ batchLimit,
7
+ groupTarget,
8
+ integer,
9
+ readBalance,
10
+ validateScope,
11
+ } from "./helpers.js";
12
+ import { reserveGroup, sealGroup } from "./reservations.js";
13
+
14
+ const unavailable = v.union(
15
+ v.object({
16
+ status: v.literal("conflict"),
17
+ reason: v.union(v.literal("scope_busy"), v.literal("identity_changed")),
18
+ retryable: v.literal(false),
19
+ }),
20
+ v.object({
21
+ status: v.literal("rejected"),
22
+ reason: v.union(v.literal("invalid_scope"), v.literal("policy_invalid")),
23
+ retryable: v.literal(false),
24
+ }),
25
+ );
26
+ const rejected = (reason: "invalid_scope" | "policy_invalid") => ({
27
+ status: "rejected" as const,
28
+ reason,
29
+ retryable: false as const,
30
+ });
31
+ const conflict = (reason: "scope_busy" | "identity_changed") => ({
32
+ status: "conflict" as const,
33
+ reason,
34
+ retryable: false as const,
35
+ });
36
+
37
+ /** Host authorizes opaque scope and policy. One call reserves at most one batch. */
38
+ export const prepare = mutation({
39
+ args: { ...groupInput, limit: v.optional(v.number()) },
40
+ returns: v.union(
41
+ v.object({
42
+ status: v.literal("prepared"),
43
+ group: groupDoc,
44
+ isDone: v.boolean(),
45
+ }),
46
+ unavailable,
47
+ ),
48
+ handler: async (ctx, args) => {
49
+ try {
50
+ validateScope(args);
51
+ if (
52
+ !args.accountId.trim() ||
53
+ !args.scopeKey.trim() ||
54
+ !args.groupKey.trim() ||
55
+ !args.sourceId.trim()
56
+ )
57
+ return rejected("invalid_scope");
58
+ } catch {
59
+ return rejected("invalid_scope");
60
+ }
61
+ try {
62
+ batchLimit(args.limit ?? 100);
63
+ [args.maxDebit, args.maxCredit].forEach(integer);
64
+ if (args.maxDebit < 0 || args.maxCredit < 0)
65
+ return rejected("policy_invalid");
66
+ if (args.sourceGross !== undefined && integer(args.sourceGross) <= 0)
67
+ return rejected("policy_invalid");
68
+ if (
69
+ args.sourceProcessingFee !== undefined &&
70
+ integer(args.sourceProcessingFee) < 0
71
+ )
72
+ return rejected("policy_invalid");
73
+ if (
74
+ args.sourceKind === "settlement" &&
75
+ (args.sourceGross === undefined ||
76
+ args.sourceProcessingFee === undefined)
77
+ )
78
+ return rejected("policy_invalid");
79
+ } catch {
80
+ return rejected("policy_invalid");
81
+ }
82
+ const existing = await ctx.db
83
+ .query("recoveryGroups")
84
+ .withIndex("by_key", (q) => q.eq("groupKey", args.groupKey))
85
+ .unique();
86
+ if (existing) {
87
+ for (const key of [
88
+ "accountId",
89
+ "scopeKey",
90
+ "currency",
91
+ "sourceKind",
92
+ "sourceId",
93
+ "sourceGross",
94
+ "sourceProcessingFee",
95
+ "maxDebit",
96
+ "maxCredit",
97
+ ] as const)
98
+ if (existing[key] !== args[key]) return conflict("identity_changed");
99
+ if (existing.status !== "open")
100
+ return { status: "prepared" as const, group: existing, isDone: true };
101
+ }
102
+ const current = await readBalance(ctx, args);
103
+ if (current?.activeGroupKey && current.activeGroupKey !== args.groupKey)
104
+ return conflict("scope_busy");
105
+ const sequence = integer((existing?.preparationSequence ?? 0) + 1);
106
+ const operationKey = `recovery-preparation:${JSON.stringify([args.groupKey, sequence])}`;
107
+ // Legacy callers can choose arbitrary keys. A collision must never replay their operation.
108
+ const collision = await ctx.db
109
+ .query("recoveryReservations")
110
+ .withIndex("by_key", (q) => q.eq("operationKey", operationKey))
111
+ .unique();
112
+ if (collision) return conflict("identity_changed");
113
+ const { group } = await reserveGroup(ctx, { ...args, operationKey });
114
+ await ctx.db.patch("recoveryGroups", group._id, {
115
+ preparationSequence: sequence,
116
+ });
117
+ const ledger = await balance(ctx, args);
118
+ const isDone = groupTarget(group, ledger.outstanding) === group.amount;
119
+ const result = isDone
120
+ ? await sealGroup(ctx, { groupKey: args.groupKey })
121
+ : (await ctx.db.get("recoveryGroups", group._id))!;
122
+ return { status: "prepared" as const, group: result, isDone };
123
+ },
124
+ });
@@ -68,6 +68,7 @@ export const groupFields = {
68
68
  ...groupInput,
69
69
  amount: v.number(),
70
70
  pendingOperations: v.number(),
71
+ preparationSequence: v.optional(v.number()),
71
72
  invoiceItemId: v.optional(v.string()),
72
73
  invoiceFunding: v.optional(
73
74
  v.object({