@fantastic.dev/better-stripe 0.35.0 → 0.37.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 (94) hide show
  1. package/CHANGELOG.md +225 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +178 -0
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +89 -0
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +178 -0
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +89 -0
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/operationEvidence.d.ts +37 -0
  12. package/dist/client/operationEvidence.d.ts.map +1 -0
  13. package/dist/client/operationEvidence.js +44 -0
  14. package/dist/client/operationEvidence.js.map +1 -0
  15. package/dist/client/publicTypes.d.ts +1 -0
  16. package/dist/client/publicTypes.d.ts.map +1 -1
  17. package/dist/client/readContracts.d.ts +2 -0
  18. package/dist/client/readContracts.d.ts.map +1 -1
  19. package/dist/client/readContracts.js +4 -0
  20. package/dist/client/readContracts.js.map +1 -1
  21. package/dist/component/_generated/component.d.ts +181 -0
  22. package/dist/component/_generated/component.d.ts.map +1 -1
  23. package/dist/component/earnings/pairedAdjustment.d.ts +12 -0
  24. package/dist/component/earnings/pairedAdjustment.d.ts.map +1 -0
  25. package/dist/component/earnings/pairedAdjustment.js +46 -0
  26. package/dist/component/earnings/pairedAdjustment.js.map +1 -0
  27. package/dist/component/earnings/triggers.d.ts +120 -0
  28. package/dist/component/earnings/triggers.d.ts.map +1 -1
  29. package/dist/component/earnings/triggers.js +10 -2
  30. package/dist/component/earnings/triggers.js.map +1 -1
  31. package/dist/component/operationEvidence/canonical.d.ts +4 -0
  32. package/dist/component/operationEvidence/canonical.d.ts.map +1 -0
  33. package/dist/component/operationEvidence/canonical.js +8 -0
  34. package/dist/component/operationEvidence/canonical.js.map +1 -0
  35. package/dist/component/operationEvidence/helpers.d.ts +87 -0
  36. package/dist/component/operationEvidence/helpers.d.ts.map +1 -0
  37. package/dist/component/operationEvidence/helpers.js +49 -0
  38. package/dist/component/operationEvidence/helpers.js.map +1 -0
  39. package/dist/component/operationEvidence/maintenance.d.ts +88 -0
  40. package/dist/component/operationEvidence/maintenance.d.ts.map +1 -0
  41. package/dist/component/operationEvidence/maintenance.js +59 -0
  42. package/dist/component/operationEvidence/maintenance.js.map +1 -0
  43. package/dist/component/operationEvidence/mutations.d.ts +97 -0
  44. package/dist/component/operationEvidence/mutations.d.ts.map +1 -0
  45. package/dist/component/operationEvidence/mutations.js +14 -0
  46. package/dist/component/operationEvidence/mutations.js.map +1 -0
  47. package/dist/component/operationEvidence/queries.d.ts +205 -0
  48. package/dist/component/operationEvidence/queries.d.ts.map +1 -0
  49. package/dist/component/operationEvidence/queries.js +75 -0
  50. package/dist/component/operationEvidence/queries.js.map +1 -0
  51. package/dist/component/operationEvidence/schema.d.ts +536 -0
  52. package/dist/component/operationEvidence/schema.d.ts.map +1 -0
  53. package/dist/component/operationEvidence/schema.js +53 -0
  54. package/dist/component/operationEvidence/schema.js.map +1 -0
  55. package/dist/component/payoutRelease/queries.d.ts +2 -2
  56. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  57. package/dist/component/refundHistory/commandEvidence.d.ts +1 -1
  58. package/dist/component/refundHistory/commandEvidence.d.ts.map +1 -1
  59. package/dist/component/refundHistory/commandEvidence.js +6 -2
  60. package/dist/component/refundHistory/commandEvidence.js.map +1 -1
  61. package/dist/component/refundHistory/originalSeller.d.ts +5 -0
  62. package/dist/component/refundHistory/originalSeller.d.ts.map +1 -0
  63. package/dist/component/refundHistory/originalSeller.js +35 -0
  64. package/dist/component/refundHistory/originalSeller.js.map +1 -0
  65. package/dist/component/refundHistory/queries.d.ts +1 -1
  66. package/dist/component/schema.d.ts +89 -0
  67. package/dist/component/schema.js +3 -0
  68. package/dist/component/schema.js.map +1 -1
  69. package/docs/financial-observations.md +85 -0
  70. package/docs/refund-command-evidence.md +6 -0
  71. package/package.json +1 -1
  72. package/src/client/operationEvidence.test.ts +110 -0
  73. package/src/client/operationEvidence.ts +92 -0
  74. package/src/client/publicTypes.ts +8 -0
  75. package/src/client/readContracts.ts +4 -0
  76. package/src/component/_generated/api.ts +10 -0
  77. package/src/component/_generated/component.ts +207 -0
  78. package/src/component/earnings/paired-adjustment.test.ts +258 -0
  79. package/src/component/earnings/pairedAdjustment.ts +77 -0
  80. package/src/component/earnings/triggers.ts +14 -10
  81. package/src/component/operationEvidence/canonical.ts +10 -0
  82. package/src/component/operationEvidence/helpers.ts +65 -0
  83. package/src/component/operationEvidence/integrity.test.ts +257 -0
  84. package/src/component/operationEvidence/maintenance.test.ts +152 -0
  85. package/src/component/operationEvidence/maintenance.ts +89 -0
  86. package/src/component/operationEvidence/mutations.ts +14 -0
  87. package/src/component/operationEvidence/queries.ts +108 -0
  88. package/src/component/operationEvidence/reads.test.ts +140 -0
  89. package/src/component/operationEvidence/schema.ts +62 -0
  90. package/src/component/refundHistory/commandEvidence.ts +7 -2
  91. package/src/component/refundHistory/original-seller-boundaries.test.ts +138 -0
  92. package/src/component/refundHistory/original-seller.test.ts +175 -0
  93. package/src/component/refundHistory/originalSeller.ts +48 -0
  94. package/src/component/schema.ts +6 -0
@@ -3380,6 +3380,213 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
3380
3380
  >;
3381
3381
  };
3382
3382
  };
3383
+ operationEvidence: {
3384
+ mutations: {
3385
+ capture: FunctionReference<
3386
+ "mutation",
3387
+ "internal",
3388
+ { sourceId: string },
3389
+ {
3390
+ coverage: "unknown";
3391
+ evidenceGeneration: number | null;
3392
+ header: {
3393
+ _creationTime: number;
3394
+ _id: string;
3395
+ firstObservedAt: number;
3396
+ generation: number;
3397
+ isContradictory: boolean;
3398
+ latestFingerprint: string;
3399
+ latestPayloadId: string;
3400
+ operationDigest: string;
3401
+ originalFingerprint: string;
3402
+ originalIdentityFingerprint: string;
3403
+ originalPayloadId: string;
3404
+ producer: "trusted_host_maintenance";
3405
+ producerVersion: 1;
3406
+ sourceChargeDigest: string;
3407
+ sourceCreatedAt: number;
3408
+ sourceId: string;
3409
+ } | null;
3410
+ status:
3411
+ | "captured"
3412
+ | "updated"
3413
+ | "unchanged"
3414
+ | "unavailable"
3415
+ | "source_unavailable";
3416
+ },
3417
+ Name
3418
+ >;
3419
+ };
3420
+ queries: {
3421
+ headers: FunctionReference<
3422
+ "query",
3423
+ "internal",
3424
+ {
3425
+ paginationOpts: {
3426
+ cursor: string | null;
3427
+ endCursor?: string | null;
3428
+ id?: number;
3429
+ maximumBytesRead?: number;
3430
+ maximumRowsRead?: number;
3431
+ numItems: number;
3432
+ };
3433
+ },
3434
+ {
3435
+ continueCursor: string;
3436
+ coverage: "unknown";
3437
+ evidenceGeneration: number | null;
3438
+ isDone: boolean;
3439
+ page: Array<{
3440
+ _creationTime: number;
3441
+ _id: string;
3442
+ firstObservedAt: number;
3443
+ generation: number;
3444
+ isContradictory: boolean;
3445
+ latestFingerprint: string;
3446
+ latestPayloadId: string;
3447
+ operationDigest: string;
3448
+ originalFingerprint: string;
3449
+ originalIdentityFingerprint: string;
3450
+ originalPayloadId: string;
3451
+ producer: "trusted_host_maintenance";
3452
+ producerVersion: 1;
3453
+ sourceChargeDigest: string;
3454
+ sourceCreatedAt: number;
3455
+ sourceId: string;
3456
+ }>;
3457
+ pageStatus?: "SplitRecommended" | "SplitRequired" | null;
3458
+ splitCursor?: string | null;
3459
+ },
3460
+ Name
3461
+ >;
3462
+ latest: FunctionReference<
3463
+ "query",
3464
+ "internal",
3465
+ { headerId: string },
3466
+ {
3467
+ coverage: "unknown";
3468
+ evidenceGeneration: number | null;
3469
+ header: {
3470
+ _creationTime: number;
3471
+ _id: string;
3472
+ firstObservedAt: number;
3473
+ generation: number;
3474
+ isContradictory: boolean;
3475
+ latestFingerprint: string;
3476
+ latestPayloadId: string;
3477
+ operationDigest: string;
3478
+ originalFingerprint: string;
3479
+ originalIdentityFingerprint: string;
3480
+ originalPayloadId: string;
3481
+ producer: "trusted_host_maintenance";
3482
+ producerVersion: 1;
3483
+ sourceChargeDigest: string;
3484
+ sourceCreatedAt: number;
3485
+ sourceId: string;
3486
+ } | null;
3487
+ payload: {
3488
+ _creationTime: number;
3489
+ _id: string;
3490
+ commissionExposure?: {
3491
+ chargeAmount: number;
3492
+ disputeId?: string;
3493
+ disputeState?: "open" | "lost" | "won";
3494
+ finalized: boolean;
3495
+ kind: "refund" | "dispute";
3496
+ principal: number;
3497
+ refundId?: string;
3498
+ refundedPrincipal?: number;
3499
+ };
3500
+ operationId: string;
3501
+ slices: Array<{
3502
+ from: number;
3503
+ stripeTransferId: string;
3504
+ to: number;
3505
+ }>;
3506
+ sourceChargeId: string;
3507
+ } | null;
3508
+ },
3509
+ Name
3510
+ >;
3511
+ original: FunctionReference<
3512
+ "query",
3513
+ "internal",
3514
+ { headerId: string },
3515
+ {
3516
+ coverage: "unknown";
3517
+ evidenceGeneration: number | null;
3518
+ header: {
3519
+ _creationTime: number;
3520
+ _id: string;
3521
+ firstObservedAt: number;
3522
+ generation: number;
3523
+ isContradictory: boolean;
3524
+ latestFingerprint: string;
3525
+ latestPayloadId: string;
3526
+ operationDigest: string;
3527
+ originalFingerprint: string;
3528
+ originalIdentityFingerprint: string;
3529
+ originalPayloadId: string;
3530
+ producer: "trusted_host_maintenance";
3531
+ producerVersion: 1;
3532
+ sourceChargeDigest: string;
3533
+ sourceCreatedAt: number;
3534
+ sourceId: string;
3535
+ } | null;
3536
+ payload: {
3537
+ _creationTime: number;
3538
+ _id: string;
3539
+ commissionExposure?: {
3540
+ chargeAmount: number;
3541
+ disputeId?: string;
3542
+ disputeState?: "open" | "lost" | "won";
3543
+ finalized: boolean;
3544
+ kind: "refund" | "dispute";
3545
+ principal: number;
3546
+ refundId?: string;
3547
+ refundedPrincipal?: number;
3548
+ };
3549
+ operationId: string;
3550
+ slices: Array<{
3551
+ from: number;
3552
+ stripeTransferId: string;
3553
+ to: number;
3554
+ }>;
3555
+ sourceChargeId: string;
3556
+ } | null;
3557
+ },
3558
+ Name
3559
+ >;
3560
+ resolve: FunctionReference<
3561
+ "query",
3562
+ "internal",
3563
+ { selector: "operationId" | "sourceChargeId"; value: string },
3564
+ {
3565
+ coverage: "unknown";
3566
+ evidenceGeneration: number | null;
3567
+ header: {
3568
+ _creationTime: number;
3569
+ _id: string;
3570
+ firstObservedAt: number;
3571
+ generation: number;
3572
+ isContradictory: boolean;
3573
+ latestFingerprint: string;
3574
+ latestPayloadId: string;
3575
+ operationDigest: string;
3576
+ originalFingerprint: string;
3577
+ originalIdentityFingerprint: string;
3578
+ originalPayloadId: string;
3579
+ producer: "trusted_host_maintenance";
3580
+ producerVersion: 1;
3581
+ sourceChargeDigest: string;
3582
+ sourceCreatedAt: number;
3583
+ sourceId: string;
3584
+ } | null;
3585
+ },
3586
+ Name
3587
+ >;
3588
+ };
3589
+ };
3383
3590
  payoutPolicy: {
3384
3591
  mutations: {
3385
3592
  beginAttempt: FunctionReference<
@@ -0,0 +1,258 @@
1
+ import { convexTest } from "convex-test";
2
+ import { expect, it, vi } from "vitest";
3
+ import { modules, schema } from "../../test.js";
4
+ import { api } from "../_generated/api.js";
5
+ import { replaceContribution } from "./pairedAdjustment.js";
6
+
7
+ const previous = {
8
+ accountId: "acct_pair",
9
+ currency: "usd",
10
+ gross: 5,
11
+ reversed: 1,
12
+ paidOut: 0,
13
+ count: 1,
14
+ };
15
+
16
+ it("validates subtract/reapply using one exact summary lookup", async () => {
17
+ const t = convexTest(schema, modules);
18
+ await t.run(async (ctx) => {
19
+ const id = await ctx.db.insert("currencyTotals", {
20
+ accountId: previous.accountId,
21
+ currency: previous.currency,
22
+ kind: "earnings",
23
+ gross: 12,
24
+ reversed: 2,
25
+ paidOut: 0,
26
+ count: 2,
27
+ });
28
+ const read = vi.spyOn(ctx.db, "query");
29
+ await replaceContribution(ctx, previous, { ...previous, reversed: 3 });
30
+ expect(read).toHaveBeenCalledTimes(1);
31
+ expect(await ctx.db.get("currencyTotals", id)).toMatchObject({
32
+ gross: 12,
33
+ reversed: 4,
34
+ count: 2,
35
+ });
36
+ });
37
+ });
38
+
39
+ it("preserves zero-count discard/reset and missing-summary subtraction semantics", async () => {
40
+ const t = convexTest(schema, modules);
41
+ await t.run(async (ctx) => {
42
+ await ctx.db.insert("currencyTotals", {
43
+ accountId: previous.accountId,
44
+ currency: previous.currency,
45
+ kind: "earnings",
46
+ gross: 10,
47
+ reversed: 1,
48
+ paidOut: 0,
49
+ count: 1,
50
+ });
51
+ await replaceContribution(ctx, previous, previous);
52
+ expect(await ctx.db.query("currencyTotals").unique()).toMatchObject({
53
+ gross: 5,
54
+ reversed: 1,
55
+ count: 1,
56
+ });
57
+ });
58
+ const empty = convexTest(schema, modules);
59
+ await empty.run((ctx) => replaceContribution(ctx, previous, previous));
60
+ expect(
61
+ await empty.run((ctx) => ctx.db.query("currencyTotals").take(1)),
62
+ ).toEqual([]);
63
+ });
64
+
65
+ it.each([
66
+ { gross: Number.MAX_SAFE_INTEGER, reversed: -5, count: 1 },
67
+ { gross: Number.NaN, reversed: 0, count: 1 },
68
+ { gross: 5, reversed: 0, count: Number.POSITIVE_INFINITY },
69
+ ])(
70
+ "does not bypass unsafe stored/intermediate totals on matching replay: %j",
71
+ async (totals) => {
72
+ const t = convexTest(schema, modules);
73
+ await t.run((ctx) =>
74
+ ctx.db.insert("currencyTotals", {
75
+ accountId: previous.accountId,
76
+ currency: previous.currency,
77
+ kind: "earnings",
78
+ paidOut: 0,
79
+ ...totals,
80
+ }),
81
+ );
82
+ const before = await t.run((ctx) =>
83
+ ctx.db.query("currencyTotals").unique(),
84
+ );
85
+ await expect(
86
+ t.run((ctx) => replaceContribution(ctx, previous, previous)),
87
+ ).rejects.toThrow(/safe integer/i);
88
+ expect(
89
+ await t.run((ctx) => ctx.db.query("currencyTotals").unique()),
90
+ ).toEqual(before);
91
+ },
92
+ );
93
+
94
+ it("skips only final unchanged nonzero persistence after validated reset/reapply", async () => {
95
+ const t = convexTest(schema, modules);
96
+ await t.run(async (ctx) => {
97
+ const id = await ctx.db.insert("currencyTotals", {
98
+ accountId: previous.accountId,
99
+ currency: previous.currency,
100
+ kind: "earnings",
101
+ gross: 5,
102
+ reversed: 1,
103
+ paidOut: 0,
104
+ count: 1,
105
+ });
106
+ const write = vi.spyOn(ctx.db, "patch");
107
+ await replaceContribution(ctx, previous, previous);
108
+ expect(write).not.toHaveBeenCalled();
109
+ expect(await ctx.db.get("currencyTotals", id)).not.toBeNull();
110
+ });
111
+ });
112
+
113
+ it("still deletes an unchanged numeric zero-count stored summary", async () => {
114
+ const t = convexTest(schema, modules);
115
+ await t.run(async (ctx) => {
116
+ const id = await ctx.db.insert("currencyTotals", {
117
+ accountId: previous.accountId,
118
+ currency: previous.currency,
119
+ kind: "earnings",
120
+ gross: 5,
121
+ reversed: 1,
122
+ paidOut: 0,
123
+ count: 0,
124
+ });
125
+ await replaceContribution(ctx, previous, previous);
126
+ expect(await ctx.db.get("currencyTotals", id)).toBeNull();
127
+ });
128
+ });
129
+
130
+ it.each(["subtract", "reapply"] as const)(
131
+ "checks unsafe %s arithmetic before unchanged-persistence decisions",
132
+ async (phase) => {
133
+ const t = convexTest(schema, modules);
134
+ await t.run((ctx) =>
135
+ ctx.db.insert("currencyTotals", {
136
+ accountId: previous.accountId,
137
+ currency: previous.currency,
138
+ kind: "earnings",
139
+ gross: Number.MAX_SAFE_INTEGER,
140
+ reversed: 0,
141
+ paidOut: 0,
142
+ count: 2,
143
+ }),
144
+ );
145
+ const old =
146
+ phase === "subtract"
147
+ ? { ...previous, gross: -1, reversed: 0 }
148
+ : { ...previous, reversed: 0 };
149
+ const next = phase === "subtract" ? old : { ...old, gross: 6 };
150
+ const before = await t.run((ctx) =>
151
+ ctx.db.query("currencyTotals").unique(),
152
+ );
153
+ await expect(
154
+ t.run((ctx) => replaceContribution(ctx, old, next)),
155
+ ).rejects.toThrow(/safe integer/i);
156
+ expect(
157
+ await t.run((ctx) => ctx.db.query("currencyTotals").unique()),
158
+ ).toEqual(before);
159
+ },
160
+ );
161
+
162
+ it("rejects duplicate or foreign currency summaries without repinning", async () => {
163
+ const t = convexTest(schema, modules);
164
+ await t.run(async (ctx) => {
165
+ for (let i = 0; i < 2; i++)
166
+ await ctx.db.insert("currencyTotals", {
167
+ accountId: previous.accountId,
168
+ currency: previous.currency,
169
+ kind: "earnings",
170
+ gross: 5,
171
+ reversed: 1,
172
+ paidOut: 0,
173
+ count: 1,
174
+ });
175
+ });
176
+ await expect(
177
+ t.run((ctx) => replaceContribution(ctx, previous, previous)),
178
+ ).rejects.toThrow();
179
+ await expect(
180
+ t.run((ctx) =>
181
+ replaceContribution(ctx, previous, { ...previous, currency: "eur" }),
182
+ ),
183
+ ).rejects.toThrow(/same currency bucket/);
184
+ });
185
+
186
+ it("registered frontier rollback preserves malformed summary, source and both revision fences", async () => {
187
+ const t = convexTest(schema, modules);
188
+ await t.mutation(api.connect.mutations.upsertTransfer, {
189
+ stripeTransferId: "tr_paired_rollback",
190
+ sourceChargeId: "ch_paired_rollback",
191
+ destinationAccountId: "acct_pair",
192
+ amount: 5,
193
+ currency: "usd",
194
+ status: "paid",
195
+ });
196
+ await t.run(async (ctx) => {
197
+ const total = (await ctx.db.query("currencyTotals").unique())!;
198
+ await ctx.db.patch("currencyTotals", total._id, { paidOut: Number.NaN });
199
+ });
200
+ const snapshot = () =>
201
+ t.run(async (ctx) => ({
202
+ source: await ctx.db.query("transfers").take(5),
203
+ totals: await ctx.db.query("currencyTotals").take(5),
204
+ financial: await ctx.db.query("payoutFinancialRevisions").take(5),
205
+ risk: await ctx.db.query("payoutRiskRevisions").take(5),
206
+ events: await ctx.db.query("payoutRiskEvents").take(5),
207
+ operations: await ctx.db.query("transferReversalOps").take(5),
208
+ }));
209
+ const before = await snapshot();
210
+ await expect(
211
+ t.mutation(api.connect.mutations.claimReversalSlices, {
212
+ operationId: "op_paired_rollback",
213
+ sourceChargeId: "ch_paired_rollback",
214
+ mode: { kind: "full" },
215
+ }),
216
+ ).rejects.toThrow(/safe integer/i);
217
+ expect(await snapshot()).toEqual(before);
218
+ });
219
+
220
+ it("retains moved currency buckets and unrecorded legacy contributions", async () => {
221
+ const t = convexTest(schema, modules);
222
+ const value = {
223
+ stripeTransferId: "tr_paired_move",
224
+ destinationAccountId: "acct_pair",
225
+ amount: 5,
226
+ currency: "usd",
227
+ status: "paid" as const,
228
+ };
229
+ await t.mutation(api.connect.mutations.upsertTransfer, value);
230
+ await t.mutation(api.connect.mutations.upsertTransfer, {
231
+ ...value,
232
+ destinationAccountId: "acct_other",
233
+ currency: "eur",
234
+ });
235
+ expect(
236
+ await t.query(api.connect.queries.getAccountEarningsByCurrency, {
237
+ destinationAccountId: "acct_pair",
238
+ previewLimit: 0,
239
+ }),
240
+ ).toMatchObject({ totals: [] });
241
+ expect(
242
+ await t.query(api.connect.queries.getAccountEarningsByCurrency, {
243
+ destinationAccountId: "acct_other",
244
+ previewLimit: 0,
245
+ }),
246
+ ).toMatchObject({
247
+ totals: [{ currency: "eur", gross: 5, transferCount: 1 }],
248
+ });
249
+ const legacy = { ...value, stripeTransferId: "tr_paired_legacy" };
250
+ await t.run((ctx) => ctx.db.insert("transfers", legacy));
251
+ await t.mutation(api.connect.mutations.upsertTransfer, legacy);
252
+ expect(
253
+ await t.query(api.connect.queries.getAccountEarningsByCurrency, {
254
+ destinationAccountId: "acct_pair",
255
+ previewLimit: 0,
256
+ }),
257
+ ).toMatchObject({ totals: [{ gross: 5, transferCount: 1 }] });
258
+ });
@@ -0,0 +1,77 @@
1
+ import type { MutationCtx } from "../_generated/server.js";
2
+ import { addSummaryAmounts } from "./arithmetic.js";
3
+
4
+ export type Contribution = {
5
+ accountId: string;
6
+ currency: string;
7
+ gross: number;
8
+ reversed: number;
9
+ paidOut: number;
10
+ count: number;
11
+ };
12
+ function apply(
13
+ row: {
14
+ gross: number;
15
+ reversed: number;
16
+ paidOut: number;
17
+ count: number;
18
+ } | null,
19
+ contribution: Contribution,
20
+ sign: 1 | -1,
21
+ ) {
22
+ const totals = {
23
+ gross: addSummaryAmounts(row?.gross ?? 0, sign * contribution.gross),
24
+ reversed: addSummaryAmounts(
25
+ row?.reversed ?? 0,
26
+ sign * contribution.reversed,
27
+ ),
28
+ paidOut: addSummaryAmounts(row?.paidOut ?? 0, sign * contribution.paidOut),
29
+ count: addSummaryAmounts(row?.count ?? 0, sign * contribution.count),
30
+ };
31
+ addSummaryAmounts(totals.gross, -totals.reversed);
32
+ return totals;
33
+ }
34
+ /** Same bucket only: preserve subtract/reset/reapply validation with one read. */
35
+ export async function replaceContribution(
36
+ ctx: MutationCtx,
37
+ previous: Contribution,
38
+ next: Contribution,
39
+ ) {
40
+ if (
41
+ previous.accountId !== next.accountId ||
42
+ previous.currency !== next.currency
43
+ )
44
+ throw new Error("Paired contributions require the same currency bucket");
45
+ const row = await ctx.db
46
+ .query("currencyTotals")
47
+ .withIndex("by_account_kind_currency", (q) =>
48
+ q
49
+ .eq("accountId", previous.accountId)
50
+ .eq("kind", "earnings")
51
+ .eq("currency", previous.currency),
52
+ )
53
+ .unique();
54
+ const removed = apply(row, previous, -1);
55
+ // The existing subtract path deletes a zero-count stored row before reapply.
56
+ const hasIntermediateRow = !row || removed.count !== 0;
57
+ const totals = apply(hasIntermediateRow ? removed : null, next, 1);
58
+ if (hasIntermediateRow && totals.count === 0) {
59
+ if (row) await ctx.db.delete("currencyTotals", row._id);
60
+ return;
61
+ }
62
+ if (
63
+ row &&
64
+ (["gross", "reversed", "paidOut", "count"] as const).every((field) =>
65
+ Object.is(row[field], totals[field]),
66
+ )
67
+ )
68
+ return;
69
+ if (row) await ctx.db.patch("currencyTotals", row._id, totals);
70
+ else
71
+ await ctx.db.insert("currencyTotals", {
72
+ accountId: next.accountId,
73
+ currency: next.currency,
74
+ kind: "earnings",
75
+ ...totals,
76
+ });
77
+ }
@@ -7,19 +7,12 @@ import {
7
7
  } from "convex-helpers/server/customFunctions";
8
8
  import type { DataModel } from "../_generated/dataModel.js";
9
9
  import { addSummaryAmounts } from "./arithmetic.js";
10
+ import { replaceContribution, type Contribution } from "./pairedAdjustment.js";
10
11
  import {
11
12
  mutation as rawMutation,
12
13
  type MutationCtx,
13
14
  } from "../_generated/server.js";
14
15
 
15
- type Contribution = {
16
- accountId: string;
17
- currency: string;
18
- gross: number;
19
- reversed: number;
20
- paidOut: number;
21
- count: number;
22
- };
23
16
  async function adjust(
24
17
  ctx: MutationCtx,
25
18
  kind: "earnings" | "payouts",
@@ -65,10 +58,21 @@ triggers.register("transfers", async (ctx, change) => {
65
58
  paidOut: 0,
66
59
  count: 1,
67
60
  });
68
- if (change.oldDoc?.totalsRecorded)
61
+ const canPair =
62
+ change.oldDoc?.totalsRecorded &&
63
+ change.newDoc &&
64
+ change.oldDoc.destinationAccountId === change.newDoc.destinationAccountId &&
65
+ change.oldDoc.currency === change.newDoc.currency;
66
+ if (canPair)
67
+ await replaceContribution(
68
+ ctx,
69
+ contribution(change.oldDoc!),
70
+ contribution(change.newDoc!),
71
+ );
72
+ else if (change.oldDoc?.totalsRecorded)
69
73
  await adjust(ctx, "earnings", contribution(change.oldDoc), -1);
70
74
  if (change.newDoc) {
71
- await adjust(ctx, "earnings", contribution(change.newDoc), 1);
75
+ if (!canPair) await adjust(ctx, "earnings", contribution(change.newDoc), 1);
72
76
  if (!change.newDoc.totalsRecorded) {
73
77
  await ctx.innerDb.patch("transfers", change.id, { totalsRecorded: true });
74
78
  // Frontier producers own bounded batch observation, including oversized release deferral.
@@ -0,0 +1,10 @@
1
+ import { convexToJson, type Value } from "convex/values";
2
+
3
+ /** Convex encoding preserves special floats and recursively sorts object keys. */
4
+ export async function canonicalFingerprint(value: Value) {
5
+ const bytes = new TextEncoder().encode(JSON.stringify(convexToJson(value)));
6
+ const hash = await crypto.subtle.digest("SHA-256", bytes);
7
+ return Array.from(new Uint8Array(hash), (byte) =>
8
+ byte.toString(16).padStart(2, "0"),
9
+ ).join("");
10
+ }
@@ -0,0 +1,65 @@
1
+ import type { Doc, Id } from "../_generated/dataModel.js";
2
+ import type { QueryCtx } from "../_generated/server.js";
3
+ import { observationGeneration } from "../financialObservations/generations.js";
4
+ import { canonicalFingerprint } from "./canonical.js";
5
+
6
+ export const operationEvidenceScope = "operation-evidence-maintenance-v1";
7
+ export async function readState(ctx: QueryCtx) {
8
+ return {
9
+ coverage: "unknown" as const,
10
+ evidenceGeneration: await observationGeneration(
11
+ ctx,
12
+ operationEvidenceScope,
13
+ ),
14
+ };
15
+ }
16
+ export function bodyOf(
17
+ row: Doc<"transferReversalOps"> | Doc<"operationEvidencePayloads">,
18
+ ) {
19
+ const { _id, _creationTime, ...fields } = row;
20
+ void _id;
21
+ void _creationTime;
22
+ return fields;
23
+ }
24
+ export function sourceFingerprint(body: ReturnType<typeof bodyOf>) {
25
+ return canonicalFingerprint({ domain: "operation-evidence-source-v1", body });
26
+ }
27
+ export function identityFingerprint(body: ReturnType<typeof bodyOf>) {
28
+ return canonicalFingerprint({
29
+ domain: "operation-evidence-identity-v1",
30
+ operationId: body.operationId,
31
+ sourceChargeId: body.sourceChargeId,
32
+ slices: body.slices,
33
+ });
34
+ }
35
+ export function selectorDigest(
36
+ selector: "operationId" | "sourceChargeId",
37
+ value: string,
38
+ ) {
39
+ return canonicalFingerprint({
40
+ domain: "operation-evidence-selector-v1",
41
+ selector,
42
+ value,
43
+ });
44
+ }
45
+ export function isValidHeader(header: Doc<"operationEvidenceHeaders">) {
46
+ return (
47
+ Number.isSafeInteger(header.generation) &&
48
+ header.generation >= 1 &&
49
+ header.originalPayloadId !== header.latestPayloadId
50
+ );
51
+ }
52
+ export async function uniqueSourceHeader(
53
+ ctx: QueryCtx,
54
+ sourceId: Id<"transferReversalOps">,
55
+ ) {
56
+ const headers = await ctx.db
57
+ .query("operationEvidenceHeaders")
58
+ .withIndex("by_source_id", (q) => q.eq("sourceId", sourceId))
59
+ .take(2);
60
+ return {
61
+ headers,
62
+ header:
63
+ headers.length === 1 && isValidHeader(headers[0]!) ? headers[0]! : null,
64
+ };
65
+ }