@fantastic.dev/better-stripe 0.42.0 → 0.44.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 +31 -0
  2. package/README.md +11 -4
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +1022 -0
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +511 -0
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +1054 -32
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +527 -16
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/costRecovery-invoices.d.ts +3 -2
  12. package/dist/client/costRecovery-invoices.d.ts.map +1 -1
  13. package/dist/client/costRecovery-invoices.js +10 -5
  14. package/dist/client/costRecovery-invoices.js.map +1 -1
  15. package/dist/client/costRecovery.d.ts +4 -2
  16. package/dist/client/costRecovery.d.ts.map +1 -1
  17. package/dist/client/costRecovery.js +2 -2
  18. package/dist/client/costRecovery.js.map +1 -1
  19. package/dist/client/processingCostReconciliation/client.d.ts +14 -0
  20. package/dist/client/processingCostReconciliation/client.d.ts.map +1 -0
  21. package/dist/client/processingCostReconciliation/client.js +35 -0
  22. package/dist/client/processingCostReconciliation/client.js.map +1 -0
  23. package/dist/client/processingCostReconciliation/contracts.d.ts +172 -0
  24. package/dist/client/processingCostReconciliation/contracts.d.ts.map +1 -0
  25. package/dist/client/processingCostReconciliation/contracts.js +55 -0
  26. package/dist/client/processingCostReconciliation/contracts.js.map +1 -0
  27. package/dist/client/processingCostReconciliation/invoiceFunding.d.ts +15 -0
  28. package/dist/client/processingCostReconciliation/invoiceFunding.d.ts.map +1 -0
  29. package/dist/client/processingCostReconciliation/invoiceFunding.js +195 -0
  30. package/dist/client/processingCostReconciliation/invoiceFunding.js.map +1 -0
  31. package/dist/client/processingCostReconciliation/provider.d.ts +9 -0
  32. package/dist/client/processingCostReconciliation/provider.d.ts.map +1 -0
  33. package/dist/client/processingCostReconciliation/provider.js +148 -0
  34. package/dist/client/processingCostReconciliation/provider.js.map +1 -0
  35. package/dist/client/settlement/processingCostHistory.d.ts +12 -0
  36. package/dist/client/settlement/processingCostHistory.d.ts.map +1 -0
  37. package/dist/client/settlement/processingCostHistory.js +20 -0
  38. package/dist/client/settlement/processingCostHistory.js.map +1 -0
  39. package/dist/client/settlement/processingCosts.d.ts +3 -0
  40. package/dist/client/settlement/processingCosts.d.ts.map +1 -1
  41. package/dist/client/settlement/processingCosts.js +27 -7
  42. package/dist/client/settlement/processingCosts.js.map +1 -1
  43. package/dist/component/_generated/api.d.ts +18 -0
  44. package/dist/component/_generated/api.d.ts.map +1 -1
  45. package/dist/component/_generated/api.js.map +1 -1
  46. package/dist/component/_generated/component.d.ts +515 -0
  47. package/dist/component/_generated/component.d.ts.map +1 -1
  48. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  49. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  50. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  51. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  52. package/dist/component/earnings/triggers.d.ts +318 -16
  53. package/dist/component/earnings/triggers.d.ts.map +1 -1
  54. package/dist/component/payoutRelease/queries.d.ts +2 -2
  55. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  56. package/dist/component/processingCostReconciliation/adoption.d.ts +29 -0
  57. package/dist/component/processingCostReconciliation/adoption.d.ts.map +1 -0
  58. package/dist/component/processingCostReconciliation/adoption.js +58 -0
  59. package/dist/component/processingCostReconciliation/adoption.js.map +1 -0
  60. package/dist/component/processingCostReconciliation/bridge.d.ts +45 -0
  61. package/dist/component/processingCostReconciliation/bridge.d.ts.map +1 -0
  62. package/dist/component/processingCostReconciliation/bridge.js +41 -0
  63. package/dist/component/processingCostReconciliation/bridge.js.map +1 -0
  64. package/dist/component/processingCostReconciliation/helpers.d.ts +327 -0
  65. package/dist/component/processingCostReconciliation/helpers.d.ts.map +1 -0
  66. package/dist/component/processingCostReconciliation/helpers.js +39 -0
  67. package/dist/component/processingCostReconciliation/helpers.js.map +1 -0
  68. package/dist/component/processingCostReconciliation/mutations.d.ts +303 -0
  69. package/dist/component/processingCostReconciliation/mutations.d.ts.map +1 -0
  70. package/dist/component/processingCostReconciliation/mutations.js +121 -0
  71. package/dist/component/processingCostReconciliation/mutations.js.map +1 -0
  72. package/dist/component/processingCostReconciliation/queries.d.ts +422 -0
  73. package/dist/component/processingCostReconciliation/queries.d.ts.map +1 -0
  74. package/dist/component/processingCostReconciliation/queries.js +19 -0
  75. package/dist/component/processingCostReconciliation/queries.js.map +1 -0
  76. package/dist/component/processingCostReconciliation/rollback.d.ts +21 -0
  77. package/dist/component/processingCostReconciliation/rollback.d.ts.map +1 -0
  78. package/dist/component/processingCostReconciliation/rollback.js +54 -0
  79. package/dist/component/processingCostReconciliation/rollback.js.map +1 -0
  80. package/dist/component/processingCostReconciliation/schema.d.ts +2460 -0
  81. package/dist/component/processingCostReconciliation/schema.d.ts.map +1 -0
  82. package/dist/component/processingCostReconciliation/schema.js +137 -0
  83. package/dist/component/processingCostReconciliation/schema.js.map +1 -0
  84. package/dist/component/processingCostReconciliation/steps.d.ts +306 -0
  85. package/dist/component/processingCostReconciliation/steps.d.ts.map +1 -0
  86. package/dist/component/processingCostReconciliation/steps.js +149 -0
  87. package/dist/component/processingCostReconciliation/steps.js.map +1 -0
  88. package/dist/component/processingCostReconciliation/validation.d.ts +13 -0
  89. package/dist/component/processingCostReconciliation/validation.d.ts.map +1 -0
  90. package/dist/component/processingCostReconciliation/validation.js +61 -0
  91. package/dist/component/processingCostReconciliation/validation.js.map +1 -0
  92. package/dist/component/processingCostReconciliation/workflow.d.ts +105 -0
  93. package/dist/component/processingCostReconciliation/workflow.d.ts.map +1 -0
  94. package/dist/component/processingCostReconciliation/workflow.js +33 -0
  95. package/dist/component/processingCostReconciliation/workflow.js.map +1 -0
  96. package/dist/component/schema.d.ts +511 -0
  97. package/dist/component/schema.js +2 -0
  98. package/dist/component/schema.js.map +1 -1
  99. package/docs/react-workflows.md +16 -8
  100. package/package.json +1 -1
  101. package/src/client/costRecovery-invoices.ts +19 -4
  102. package/src/client/costRecovery.ts +4 -2
  103. package/src/client/processingCostReconciliation/client.ts +75 -0
  104. package/src/client/processingCostReconciliation/contracts.ts +176 -0
  105. package/src/client/processingCostReconciliation/invoiceFunding.ts +270 -0
  106. package/src/client/processingCostReconciliation/invoiceProvider.test.ts +353 -0
  107. package/src/client/processingCostReconciliation/provider.test.ts +324 -0
  108. package/src/client/processingCostReconciliation/provider.ts +178 -0
  109. package/src/client/settlement/processingCostHistory.ts +31 -0
  110. package/src/client/settlement/processingCosts.ts +50 -15
  111. package/src/component/_generated/api.ts +18 -0
  112. package/src/component/_generated/component.ts +570 -0
  113. package/src/component/processingCostReconciliation/adoption.test.ts +206 -0
  114. package/src/component/processingCostReconciliation/adoption.ts +77 -0
  115. package/src/component/processingCostReconciliation/bridge.ts +50 -0
  116. package/src/component/processingCostReconciliation/helpers.ts +55 -0
  117. package/src/component/processingCostReconciliation/invoice.test.ts +152 -0
  118. package/src/component/processingCostReconciliation/mutations.ts +148 -0
  119. package/src/component/processingCostReconciliation/queries.ts +18 -0
  120. package/src/component/processingCostReconciliation/rollback.ts +72 -0
  121. package/src/component/processingCostReconciliation/schema.ts +191 -0
  122. package/src/component/processingCostReconciliation/state.test.ts +407 -0
  123. package/src/component/processingCostReconciliation/steps.ts +168 -0
  124. package/src/component/processingCostReconciliation/validation.ts +79 -0
  125. package/src/component/processingCostReconciliation/workflow.test.ts +329 -0
  126. package/src/component/processingCostReconciliation/workflow.ts +50 -0
  127. package/src/component/schema.ts +2 -0
@@ -0,0 +1,18 @@
1
+ import { query, internalQuery } from "../_generated/server.js";
2
+ import { refFields, safeStatus, operationDoc } from "./schema.js";
3
+ import { read, status } from "./helpers.js";
4
+ export const get = query({
5
+ args: refFields,
6
+ returns: safeStatus,
7
+ handler: async (ctx, args) => status(await read(ctx, args)),
8
+ });
9
+ export const snapshot = query({
10
+ args: refFields,
11
+ returns: operationDoc,
12
+ handler: read,
13
+ });
14
+ export const saved = internalQuery({
15
+ args: refFields,
16
+ returns: operationDoc,
17
+ handler: read,
18
+ });
@@ -0,0 +1,72 @@
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 { observation } from "./schema.js";
5
+ import { conflict } from "./helpers.js";
6
+ /** All checks precede every import/claim/rollback write in the parent transaction. */
7
+ export async function checkRollback(
8
+ ctx: MutationCtx,
9
+ op: Doc<"processingCostReconciliationOperations">,
10
+ o: Infer<typeof observation>,
11
+ ) {
12
+ if (!op.rollback)
13
+ return op.source.kind === "invoice_recovery"
14
+ ? conflict("identity_changed")
15
+ : ({ status: "ready", bindFunding: false } as const);
16
+ const group = await ctx.db
17
+ .query("recoveryGroups")
18
+ .withIndex("by_key", (q) => q.eq("groupKey", op.rollback!.groupKey))
19
+ .unique();
20
+ if (
21
+ !group ||
22
+ group.accountId !== op.accountId ||
23
+ group.scopeKey !== op.scopeKey ||
24
+ group.currency !== op.currency
25
+ )
26
+ return conflict("identity_changed");
27
+ if (group.status !== "collected")
28
+ return {
29
+ status: "not_ready",
30
+ reason: "provider_pending",
31
+ retryable: true,
32
+ } as const;
33
+ if (
34
+ op.source.kind === "invoice_recovery" &&
35
+ (op.source.groupKey !== group.groupKey || group.sourceKind !== "invoice")
36
+ )
37
+ return conflict("identity_changed");
38
+ if (
39
+ group.sourceKind === "invoice" &&
40
+ (!group.invoiceItemId ||
41
+ o.provenance.invoiceId !== group.sourceId ||
42
+ o.provenance.customerAccountId !== group.accountId ||
43
+ o.provenance.recoveryInvoiceItemId !== group.invoiceItemId)
44
+ )
45
+ return conflict("identity_changed");
46
+ const funding =
47
+ group.sourceKind === "settlement"
48
+ ? {
49
+ sourceChargeId: group.sourceId,
50
+ sourceGross: group.sourceGross,
51
+ sourceProcessingFee: group.sourceProcessingFee,
52
+ }
53
+ : group.invoiceFunding;
54
+ if (
55
+ funding &&
56
+ (funding.sourceChargeId !== o.sourceChargeId ||
57
+ funding.sourceGross !== o.gross ||
58
+ funding.sourceProcessingFee !== o.originalProcessingFee)
59
+ )
60
+ return conflict("identity_changed");
61
+ if (!funding && group.sourceKind !== "invoice")
62
+ return conflict("identity_changed");
63
+ const previous = await ctx.db
64
+ .query("recoveryClaims")
65
+ .withIndex("by_key", (q) =>
66
+ q.eq("claimKey", `rollback:${op.rollback!.groupKey}`),
67
+ )
68
+ .unique();
69
+ if ((previous?.revision ?? -1) !== op.rollback.expectedRevision)
70
+ return conflict("revision_changed");
71
+ return { status: "ready", bindFunding: !funding } as const;
72
+ }
@@ -0,0 +1,191 @@
1
+ import { defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ import { scopeFields, claimDoc } from "../costRecovery/schema.js";
4
+ export const source = v.union(
5
+ v.object({
6
+ kind: v.literal("sale"),
7
+ paymentIntentId: v.string(),
8
+ gross: v.number(),
9
+ customerAccountId: v.string(),
10
+ invoiceId: v.optional(v.string()),
11
+ subscriptionId: v.optional(v.string()),
12
+ stripeAccountId: v.optional(v.string()),
13
+ stripePriceId: v.optional(v.string()),
14
+ stripeProductId: v.optional(v.string()),
15
+ }),
16
+ v.object({
17
+ kind: v.literal("invoice_recovery"),
18
+ paymentIntentId: v.string(),
19
+ gross: v.number(),
20
+ groupKey: v.string(),
21
+ }),
22
+ );
23
+ export const policy = v.object({
24
+ sellingFee: v.number(),
25
+ liability: v.object({
26
+ processingCosts: v.union(
27
+ v.literal("uncovered"),
28
+ v.literal("all"),
29
+ v.literal("none"),
30
+ ),
31
+ disputeCosts: v.union(v.literal("all"), v.literal("none")),
32
+ }),
33
+ rounding: v.union(
34
+ v.literal("nearest"),
35
+ v.literal("floor"),
36
+ v.literal("ceil"),
37
+ ),
38
+ });
39
+ export const provenance = v.object({
40
+ invoiceId: v.string(),
41
+ invoicePaymentId: v.string(),
42
+ recoveryInvoiceItemId: v.optional(v.string()),
43
+ customerAccountId: v.string(),
44
+ subscriptionId: v.optional(v.string()),
45
+ stripePriceId: v.optional(v.string()),
46
+ stripeProductId: v.optional(v.string()),
47
+ });
48
+ export const observation = v.object({
49
+ paymentIntentId: v.string(),
50
+ sourceChargeId: v.string(),
51
+ currency: v.string(),
52
+ gross: v.number(),
53
+ originalProcessingFee: v.number(),
54
+ processingFee: v.number(),
55
+ disputeFees: v.number(),
56
+ principalReturned: v.number(),
57
+ provenance,
58
+ });
59
+ export const deficit = v.object({
60
+ currency: v.string(),
61
+ retainedFee: v.number(),
62
+ processingLiability: v.number(),
63
+ disputeLiability: v.number(),
64
+ amountDue: v.number(),
65
+ });
66
+ export const result = v.object({
67
+ claim: claimDoc,
68
+ rollbackClaim: v.optional(claimDoc),
69
+ deficit,
70
+ observation,
71
+ });
72
+ export const failure = v.union(
73
+ v.object({
74
+ status: v.literal("not_ready"),
75
+ reason: v.union(
76
+ v.literal("provider_pending"),
77
+ v.literal("fee_pending"),
78
+ v.literal("history_incomplete"),
79
+ ),
80
+ retryable: v.literal(true),
81
+ }),
82
+ v.object({
83
+ status: v.literal("conflict"),
84
+ reason: v.union(
85
+ v.literal("scope_busy"),
86
+ v.literal("revision_changed"),
87
+ v.literal("identity_changed"),
88
+ ),
89
+ retryable: v.literal(false),
90
+ }),
91
+ v.object({
92
+ status: v.literal("rejected"),
93
+ reason: v.union(
94
+ v.literal("invalid_scope"),
95
+ v.literal("unsupported_source"),
96
+ v.literal("policy_invalid"),
97
+ v.literal("payment_not_payable"),
98
+ v.literal("currency_mismatch"),
99
+ ),
100
+ retryable: v.literal(false),
101
+ }),
102
+ v.object({
103
+ status: v.literal("unknown"),
104
+ reason: v.union(
105
+ v.literal("provider_outcome_unknown"),
106
+ v.literal("history_incomplete"),
107
+ ),
108
+ retryable: v.literal(false),
109
+ }),
110
+ );
111
+ export const bindingFields = {
112
+ ...scopeFields,
113
+ claimKey: v.string(),
114
+ source,
115
+ policy,
116
+ expectedRevision: v.number(),
117
+ rollback: v.optional(
118
+ v.object({ groupKey: v.string(), expectedRevision: v.number() }),
119
+ ),
120
+ provider: v.string(),
121
+ projection: v.optional(v.string()),
122
+ importHook: v.optional(v.string()),
123
+ providerApiVersion: v.string(),
124
+ definitionVersion: v.number(),
125
+ maxAttempts: v.number(),
126
+ retryDelayMs: v.number(),
127
+ };
128
+ export const startFields = { ...bindingFields, requestKey: v.string() };
129
+ export const operationFields = {
130
+ ...startFields,
131
+ version: v.number(),
132
+ workflowId: v.optional(v.string()),
133
+ status: v.union(
134
+ v.literal("queued"),
135
+ v.literal("running"),
136
+ v.literal("waiting"),
137
+ v.literal("completed"),
138
+ v.literal("conflict"),
139
+ v.literal("rejected"),
140
+ v.literal("unknown"),
141
+ ),
142
+ failure: v.optional(failure),
143
+ result: v.optional(result),
144
+ };
145
+ export const operationsTable = defineTable(operationFields)
146
+ .index("by_request", ["requestKey"])
147
+ .index("by_claim_status", ["claimKey", "status"])
148
+ .index("by_payment_scope", [
149
+ "accountId",
150
+ "scopeKey",
151
+ "currency",
152
+ "source.paymentIntentId",
153
+ ]);
154
+ export const refFields = {
155
+ ...scopeFields,
156
+ operationId: v.id("processingCostReconciliationOperations"),
157
+ version: v.number(),
158
+ };
159
+ export const operationDoc = v.object({
160
+ ...operationFields,
161
+ _id: v.id("processingCostReconciliationOperations"),
162
+ _creationTime: v.number(),
163
+ });
164
+ const publicFailureFields = {
165
+ ...refFields,
166
+ status: v.union(
167
+ v.literal("not_ready"),
168
+ v.literal("conflict"),
169
+ v.literal("rejected"),
170
+ v.literal("unknown"),
171
+ ),
172
+ reason: v.string(),
173
+ retryable: v.boolean(),
174
+ };
175
+ export const safeStatus = v.union(
176
+ v.object({
177
+ ...refFields,
178
+ status: v.union(v.literal("queued"), v.literal("running")),
179
+ }),
180
+ v.object({ ...refFields, status: v.literal("completed"), result }),
181
+ v.object(publicFailureFields),
182
+ );
183
+ export const importSnapshot = v.union(
184
+ v.null(),
185
+ v.object({
186
+ operationKey: v.string(),
187
+ amountDue: v.number(),
188
+ collectedAmount: v.number(),
189
+ revision: v.number(),
190
+ }),
191
+ );
@@ -0,0 +1,407 @@
1
+ import { convexTest } from "convex-test";
2
+ import workflowTest from "@convex-dev/workflow/test";
3
+ import { makeFunctionReference } from "convex/server";
4
+ import { expect, it } from "vitest";
5
+ import { schema, modules } from "../../test.js";
6
+ const start = makeFunctionReference<"mutation">(
7
+ "processingCostReconciliation/mutations:start",
8
+ );
9
+ const apply = makeFunctionReference<"mutation">(
10
+ "processingCostReconciliation/steps:apply",
11
+ );
12
+ const scope = { accountId: "acct_seller", scopeKey: "store", currency: "usd" };
13
+ const args = {
14
+ ...scope,
15
+ claimKey: "cost:pi_a",
16
+ requestKey: "refund:re_a",
17
+ expectedRevision: -1,
18
+ source: {
19
+ kind: "sale",
20
+ paymentIntentId: "pi_a",
21
+ gross: 1000,
22
+ customerAccountId: "acct_buyer",
23
+ invoiceId: "in_a",
24
+ },
25
+ policy: {
26
+ sellingFee: 100,
27
+ liability: { processingCosts: "uncovered", disputeCosts: "all" },
28
+ rounding: "nearest",
29
+ },
30
+ provider: "function://fixture/provider",
31
+ providerApiVersion: "2026-09-30.endive",
32
+ definitionVersion: 1,
33
+ maxAttempts: 3,
34
+ retryDelayMs: 1,
35
+ };
36
+ const observation = {
37
+ paymentIntentId: "pi_a",
38
+ sourceChargeId: "ch_a",
39
+ currency: "usd",
40
+ gross: 1000,
41
+ originalProcessingFee: 30,
42
+ processingFee: 30,
43
+ disputeFees: 0,
44
+ principalReturned: 1000,
45
+ provenance: {
46
+ invoiceId: "in_a",
47
+ invoicePaymentId: "inpay_a",
48
+ customerAccountId: "acct_buyer",
49
+ stripePriceId: "price_original",
50
+ stripeProductId: "prod_original",
51
+ },
52
+ };
53
+ const reference = (op: { operationId: string; version: number }) => ({
54
+ ...scope,
55
+ operationId: op.operationId,
56
+ version: op.version,
57
+ });
58
+ function fixture() {
59
+ const t = convexTest(schema, modules);
60
+ workflowTest.register(t, "workflow");
61
+ return t;
62
+ }
63
+ it("records a verified deficit once and replays the original operation result", async () => {
64
+ const t = fixture();
65
+ const op = await t.mutation(start, args);
66
+ const result = await t.mutation(apply, { ...reference(op), observation });
67
+ expect(result).toMatchObject({
68
+ status: "completed",
69
+ result: {
70
+ claim: {
71
+ revision: 0,
72
+ amountDue: 30,
73
+ collectedAmount: 0,
74
+ reservedAmount: 0,
75
+ outstanding: 30,
76
+ },
77
+ },
78
+ });
79
+ expect(await t.mutation(apply, { ...reference(op), observation })).toEqual(
80
+ result,
81
+ );
82
+ expect((await t.mutation(start, args)).operationId).toBe(op.operationId);
83
+ expect(
84
+ await t.run((ctx) => ctx.db.query("recoveryClaims").collect()),
85
+ ).toHaveLength(1);
86
+ });
87
+ it("a competing refund/dispute observation cannot reuse an already advanced revision", async () => {
88
+ const t = fixture();
89
+ const a = await t.mutation(start, args);
90
+ const b = await t.mutation(start, { ...args, requestKey: "dispute:dp_a" });
91
+ await t.mutation(apply, { ...reference(a), observation });
92
+ expect(
93
+ await t.mutation(apply, {
94
+ ...reference(b),
95
+ observation: { ...observation, disputeFees: 15 },
96
+ }),
97
+ ).toMatchObject({
98
+ status: "conflict",
99
+ reason: "revision_changed",
100
+ retryable: false,
101
+ });
102
+ expect(
103
+ await t.run((ctx) => ctx.db.query("recoveryClaims").first()),
104
+ ).toMatchObject({ revision: 0, amountDue: 30, outstanding: 30 });
105
+ });
106
+ async function collectedGroup(
107
+ t: ReturnType<typeof fixture>,
108
+ accountId = scope.accountId,
109
+ ) {
110
+ await t.run((ctx) =>
111
+ ctx.db.insert("recoveryGroups", {
112
+ ...scope,
113
+ accountId,
114
+ groupKey: "original-adjustment",
115
+ sourceKind: "settlement",
116
+ sourceId: "ch_a",
117
+ sourceGross: 1000,
118
+ sourceProcessingFee: 30,
119
+ amount: 80,
120
+ maxDebit: 100,
121
+ maxCredit: 0,
122
+ pendingOperations: 0,
123
+ status: "collected",
124
+ }),
125
+ );
126
+ }
127
+ it("atomically records returned collected adjustment using the rollback claim's own revision", async () => {
128
+ const t = fixture();
129
+ await collectedGroup(t);
130
+ const op = await t.mutation(start, {
131
+ ...args,
132
+ rollback: { groupKey: "original-adjustment", expectedRevision: -1 },
133
+ });
134
+ const result = await t.mutation(apply, {
135
+ ...reference(op),
136
+ observation: { ...observation, principalReturned: 500 },
137
+ });
138
+ expect(result).toMatchObject({
139
+ status: "completed",
140
+ result: {
141
+ claim: { revision: 0, amountDue: 0 },
142
+ rollbackClaim: {
143
+ claimKey: "rollback:original-adjustment",
144
+ revision: 0,
145
+ amountDue: 40,
146
+ },
147
+ },
148
+ });
149
+ expect(
150
+ await t.mutation(apply, {
151
+ ...reference(op),
152
+ observation: { ...observation, principalReturned: 500 },
153
+ }),
154
+ ).toEqual(result);
155
+ expect(
156
+ await t.run((ctx) => ctx.db.query("recoveryBalances").first()),
157
+ ).toMatchObject({
158
+ amountDue: 40,
159
+ collectedAmount: 0,
160
+ reservedAmount: 0,
161
+ outstanding: 40,
162
+ });
163
+ });
164
+ it("a rollback revision race rejects the entire observation before recording the main claim", async () => {
165
+ const t = fixture();
166
+ await collectedGroup(t);
167
+ const op = await t.mutation(start, {
168
+ ...args,
169
+ rollback: { groupKey: "original-adjustment", expectedRevision: -1 },
170
+ });
171
+ await t.mutation(
172
+ makeFunctionReference<"mutation">("costRecovery/mutations:rollback"),
173
+ { groupKey: "original-adjustment", revision: 0, returnedPrincipal: 250 },
174
+ );
175
+ expect(
176
+ await t.mutation(apply, { ...reference(op), observation }),
177
+ ).toMatchObject({
178
+ status: "conflict",
179
+ reason: "revision_changed",
180
+ retryable: false,
181
+ });
182
+ expect(
183
+ await t.run((ctx) =>
184
+ ctx.db
185
+ .query("recoveryClaims")
186
+ .withIndex("by_key", (q) => q.eq("claimKey", args.claimKey))
187
+ .unique(),
188
+ ),
189
+ ).toBeNull();
190
+ expect(
191
+ await t.run((ctx) =>
192
+ ctx.db
193
+ .query("recoveryClaims")
194
+ .withIndex("by_key", (q) =>
195
+ q.eq("claimKey", "rollback:original-adjustment"),
196
+ )
197
+ .unique(),
198
+ ),
199
+ ).toMatchObject({ revision: 0, amountDue: 20 });
200
+ });
201
+ it("cannot roll back another account's collected receipt", async () => {
202
+ const t = fixture();
203
+ await collectedGroup(t, "acct_foreign");
204
+ const op = await t.mutation(start, {
205
+ ...args,
206
+ rollback: { groupKey: "original-adjustment", expectedRevision: -1 },
207
+ });
208
+ expect(
209
+ await t.mutation(apply, { ...reference(op), observation }),
210
+ ).toMatchObject({
211
+ status: "conflict",
212
+ reason: "identity_changed",
213
+ retryable: false,
214
+ });
215
+ expect(
216
+ await t.run((ctx) => ctx.db.query("recoveryClaims").collect()),
217
+ ).toEqual([]);
218
+ });
219
+ it("rejects immutable request changes without exposing the saved operation reference", async () => {
220
+ const t = fixture();
221
+ await t.mutation(start, args);
222
+ expect(
223
+ await t.mutation(start, {
224
+ ...args,
225
+ policy: { ...args.policy, sellingFee: 90 },
226
+ }),
227
+ ).toEqual({
228
+ status: "conflict",
229
+ reason: "identity_changed",
230
+ retryable: false,
231
+ });
232
+ });
233
+ it("a later revision cannot replace the original selling fee or original price", async () => {
234
+ const t = fixture();
235
+ const first = await t.mutation(start, args);
236
+ await t.mutation(apply, { ...reference(first), observation });
237
+ for (const variant of [
238
+ {
239
+ requestKey: "changed-fee",
240
+ policy: { ...args.policy, sellingFee: 99 },
241
+ observation,
242
+ },
243
+ {
244
+ requestKey: "changed-price",
245
+ policy: args.policy,
246
+ observation: {
247
+ ...observation,
248
+ provenance: {
249
+ ...observation.provenance,
250
+ stripePriceId: "price_current",
251
+ },
252
+ },
253
+ },
254
+ ]) {
255
+ const op = await t.mutation(start, {
256
+ ...args,
257
+ requestKey: variant.requestKey,
258
+ expectedRevision: 0,
259
+ policy: variant.policy,
260
+ });
261
+ expect(
262
+ await t.mutation(apply, {
263
+ ...reference(op),
264
+ observation: variant.observation,
265
+ }),
266
+ ).toMatchObject({
267
+ status: "conflict",
268
+ reason: "identity_changed",
269
+ retryable: false,
270
+ });
271
+ }
272
+ expect(
273
+ await t.run((ctx) => ctx.db.query("recoveryClaims").first()),
274
+ ).toMatchObject({ revision: 0, amountDue: 30 });
275
+ });
276
+ it("does not admit another claim key for the same scoped payment", async () => {
277
+ const t = fixture();
278
+ await t.mutation(start, args);
279
+ expect(
280
+ await t.mutation(start, {
281
+ ...args,
282
+ requestKey: "other-key",
283
+ claimKey: "different-cost",
284
+ }),
285
+ ).toMatchObject({
286
+ status: "conflict",
287
+ reason: "identity_changed",
288
+ retryable: false,
289
+ });
290
+ });
291
+ it("rejects malformed provider economics rather than treating them as a valid deficit", async () => {
292
+ const t = fixture();
293
+ const op = await t.mutation(start, args);
294
+ expect(
295
+ await t.mutation(apply, {
296
+ ...reference(op),
297
+ observation: { ...observation, principalReturned: 1001 },
298
+ }),
299
+ ).toMatchObject({
300
+ status: "rejected",
301
+ reason: "unsupported_source",
302
+ retryable: false,
303
+ });
304
+ expect(
305
+ await t.run((ctx) => ctx.db.query("recoveryClaims").collect()),
306
+ ).toEqual([]);
307
+ });
308
+
309
+ it.each([-2, 0.5, Number.MAX_SAFE_INTEGER + 1])(
310
+ "rejects invalid independent rollback revision %s before inserting metadata",
311
+ async (expectedRevision) => {
312
+ const t = fixture();
313
+ await expect(
314
+ t.mutation(start, {
315
+ ...args,
316
+ rollback: { groupKey: "group", expectedRevision },
317
+ }),
318
+ ).rejects.toThrow("Invalid processing-cost reconciliation policy");
319
+ expect(
320
+ await t.run((ctx) =>
321
+ ctx.db.query("processingCostReconciliationOperations").collect(),
322
+ ),
323
+ ).toEqual([]);
324
+ },
325
+ );
326
+ it("requires the explicit collected invoice group to match the rollback group before starting", async () => {
327
+ const t = fixture();
328
+ await expect(
329
+ t.mutation(start, {
330
+ ...args,
331
+ source: {
332
+ kind: "invoice_recovery",
333
+ groupKey: "original",
334
+ paymentIntentId: "pi_a",
335
+ gross: 1000,
336
+ },
337
+ rollback: { groupKey: "other", expectedRevision: -1 },
338
+ }),
339
+ ).rejects.toThrow("Invalid processing-cost reconciliation policy");
340
+ });
341
+
342
+ it("a won dispute produces a credit after rollback collection without recollecting its original result", async () => {
343
+ const t = fixture();
344
+ await collectedGroup(t);
345
+ const first = await t.mutation(start, {
346
+ ...args,
347
+ rollback: { groupKey: "original-adjustment", expectedRevision: -1 },
348
+ });
349
+ const originalResult = await t.mutation(apply, {
350
+ ...reference(first),
351
+ observation: { ...observation, principalReturned: 500 },
352
+ });
353
+ await t.mutation(
354
+ makeFunctionReference<"mutation">("costRecovery/mutations:reserve"),
355
+ {
356
+ ...scope,
357
+ groupKey: "collect-rollback",
358
+ sourceKind: "invoice",
359
+ sourceId: "in_collect",
360
+ maxDebit: 40,
361
+ maxCredit: 0,
362
+ operationKey: "collect-rollback:0",
363
+ },
364
+ );
365
+ await t.mutation(
366
+ makeFunctionReference<"mutation">("costRecovery/mutations:seal"),
367
+ { groupKey: "collect-rollback" },
368
+ );
369
+ await t.mutation(
370
+ makeFunctionReference<"mutation">("costRecovery/mutations:finish"),
371
+ { groupKey: "collect-rollback", outcome: "collect" },
372
+ );
373
+ const won = await t.mutation(start, {
374
+ ...args,
375
+ requestKey: "dispute-won",
376
+ expectedRevision: 0,
377
+ rollback: { groupKey: "original-adjustment", expectedRevision: 0 },
378
+ });
379
+ expect(
380
+ await t.mutation(apply, {
381
+ ...reference(won),
382
+ observation: { ...observation, principalReturned: 0 },
383
+ }),
384
+ ).toMatchObject({
385
+ status: "completed",
386
+ result: {
387
+ claim: { revision: 1, amountDue: 0 },
388
+ rollbackClaim: {
389
+ revision: 1,
390
+ amountDue: 0,
391
+ collectedAmount: 40,
392
+ outstanding: -40,
393
+ },
394
+ },
395
+ });
396
+ expect(await t.mutation(apply, { ...reference(first), observation })).toEqual(
397
+ originalResult,
398
+ );
399
+ expect(
400
+ await t.run((ctx) => ctx.db.query("recoveryBalances").first()),
401
+ ).toMatchObject({
402
+ amountDue: 0,
403
+ collectedAmount: 40,
404
+ reservedAmount: 0,
405
+ outstanding: -40,
406
+ });
407
+ });