@fantastic.dev/better-stripe 0.63.0 → 0.64.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 (174) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +19 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +550 -0
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +275 -0
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +582 -32
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +291 -16
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/financialOwnership.d.ts +2 -2
  12. package/dist/client/financialOwnership.d.ts.map +1 -1
  13. package/dist/client/financialOwnership.js +2 -2
  14. package/dist/client/financialOwnership.js.map +1 -1
  15. package/dist/client/payoutRevisionMigration.d.ts +37 -0
  16. package/dist/client/payoutRevisionMigration.d.ts.map +1 -0
  17. package/dist/client/payoutRevisionMigration.js +49 -0
  18. package/dist/client/payoutRevisionMigration.js.map +1 -0
  19. package/dist/client/publicTypes.d.ts +2 -0
  20. package/dist/client/publicTypes.d.ts.map +1 -1
  21. package/dist/client/reversalObservations.d.ts +62 -0
  22. package/dist/client/reversalObservations.d.ts.map +1 -0
  23. package/dist/client/reversalObservations.js +79 -0
  24. package/dist/client/reversalObservations.js.map +1 -0
  25. package/dist/component/_generated/api.d.ts +28 -0
  26. package/dist/component/_generated/api.d.ts.map +1 -1
  27. package/dist/component/_generated/api.js.map +1 -1
  28. package/dist/component/_generated/component.d.ts +354 -0
  29. package/dist/component/_generated/component.d.ts.map +1 -1
  30. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  31. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  32. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  33. package/dist/component/connect/mutations.d.ts.map +1 -1
  34. package/dist/component/connect/mutations.js +2 -0
  35. package/dist/component/connect/mutations.js.map +1 -1
  36. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  37. package/dist/component/connect/reversalClaims.js +10 -1
  38. package/dist/component/connect/reversalClaims.js.map +1 -1
  39. package/dist/component/earnings/triggers.d.ts +408 -16
  40. package/dist/component/earnings/triggers.d.ts.map +1 -1
  41. package/dist/component/financialObservations/transferSchema.d.ts +1 -0
  42. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -1
  43. package/dist/component/financialObservations/transferSchema.js +1 -0
  44. package/dist/component/financialObservations/transferSchema.js.map +1 -1
  45. package/dist/component/payoutRelease/queries.d.ts +2 -2
  46. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  47. package/dist/component/payoutRevisionJournal/mutations.d.ts +15 -0
  48. package/dist/component/payoutRevisionJournal/mutations.d.ts.map +1 -0
  49. package/dist/component/payoutRevisionJournal/mutations.js +11 -0
  50. package/dist/component/payoutRevisionJournal/mutations.js.map +1 -0
  51. package/dist/component/payoutRevisionJournal/schema.d.ts +45 -0
  52. package/dist/component/payoutRevisionJournal/schema.d.ts.map +1 -0
  53. package/dist/component/payoutRevisionJournal/schema.js +22 -0
  54. package/dist/component/payoutRevisionJournal/schema.js.map +1 -0
  55. package/dist/component/payoutRevisionJournal/state.d.ts +36 -0
  56. package/dist/component/payoutRevisionJournal/state.d.ts.map +1 -0
  57. package/dist/component/payoutRevisionJournal/state.js +111 -0
  58. package/dist/component/payoutRevisionJournal/state.js.map +1 -0
  59. package/dist/component/payoutRevisionMigration/mutations.d.ts +36 -0
  60. package/dist/component/payoutRevisionMigration/mutations.d.ts.map +1 -0
  61. package/dist/component/payoutRevisionMigration/mutations.js +126 -0
  62. package/dist/component/payoutRevisionMigration/mutations.js.map +1 -0
  63. package/dist/component/payoutRevisionMigration/queries.d.ts +38 -0
  64. package/dist/component/payoutRevisionMigration/queries.d.ts.map +1 -0
  65. package/dist/component/payoutRevisionMigration/queries.js +39 -0
  66. package/dist/component/payoutRevisionMigration/queries.js.map +1 -0
  67. package/dist/component/payoutRevisionMigration/schema.d.ts +115 -0
  68. package/dist/component/payoutRevisionMigration/schema.d.ts.map +1 -0
  69. package/dist/component/payoutRevisionMigration/schema.js +52 -0
  70. package/dist/component/payoutRevisionMigration/schema.js.map +1 -0
  71. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts +4 -0
  72. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts.map +1 -0
  73. package/dist/component/payoutSnapshots/legacyRevisionWriter.js +33 -0
  74. package/dist/component/payoutSnapshots/legacyRevisionWriter.js.map +1 -0
  75. package/dist/component/payoutSnapshots/revisions.d.ts.map +1 -1
  76. package/dist/component/payoutSnapshots/revisions.js +23 -29
  77. package/dist/component/payoutSnapshots/revisions.js.map +1 -1
  78. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  79. package/dist/component/refundSync/mutations.d.ts +1 -1
  80. package/dist/component/refundSync/mutations.d.ts.map +1 -1
  81. package/dist/component/reversalObservations/capture.d.ts +6 -0
  82. package/dist/component/reversalObservations/capture.d.ts.map +1 -0
  83. package/dist/component/reversalObservations/capture.js +96 -0
  84. package/dist/component/reversalObservations/capture.js.map +1 -0
  85. package/dist/component/reversalObservations/indexSlice.d.ts +29 -0
  86. package/dist/component/reversalObservations/indexSlice.d.ts.map +1 -0
  87. package/dist/component/reversalObservations/indexSlice.js +101 -0
  88. package/dist/component/reversalObservations/indexSlice.js.map +1 -0
  89. package/dist/component/reversalObservations/integrity.d.ts +25 -0
  90. package/dist/component/reversalObservations/integrity.d.ts.map +1 -0
  91. package/dist/component/reversalObservations/integrity.js +19 -0
  92. package/dist/component/reversalObservations/integrity.js.map +1 -0
  93. package/dist/component/reversalObservations/mutations.d.ts +37 -0
  94. package/dist/component/reversalObservations/mutations.d.ts.map +1 -0
  95. package/dist/component/reversalObservations/mutations.js +181 -0
  96. package/dist/component/reversalObservations/mutations.js.map +1 -0
  97. package/dist/component/reversalObservations/pagination.d.ts +34 -0
  98. package/dist/component/reversalObservations/pagination.d.ts.map +1 -0
  99. package/dist/component/reversalObservations/pagination.js +31 -0
  100. package/dist/component/reversalObservations/pagination.js.map +1 -0
  101. package/dist/component/reversalObservations/queries.d.ts +221 -0
  102. package/dist/component/reversalObservations/queries.d.ts.map +1 -0
  103. package/dist/component/reversalObservations/queries.js +114 -0
  104. package/dist/component/reversalObservations/queries.js.map +1 -0
  105. package/dist/component/reversalObservations/references.d.ts +17 -0
  106. package/dist/component/reversalObservations/references.d.ts.map +1 -0
  107. package/dist/component/reversalObservations/references.js +95 -0
  108. package/dist/component/reversalObservations/references.js.map +1 -0
  109. package/dist/component/reversalObservations/schema.d.ts +525 -0
  110. package/dist/component/reversalObservations/schema.d.ts.map +1 -0
  111. package/dist/component/reversalObservations/schema.js +92 -0
  112. package/dist/component/reversalObservations/schema.js.map +1 -0
  113. package/dist/component/reversalObservations/selectors.d.ts +3 -0
  114. package/dist/component/reversalObservations/selectors.d.ts.map +1 -0
  115. package/dist/component/reversalObservations/selectors.js +8 -0
  116. package/dist/component/reversalObservations/selectors.js.map +1 -0
  117. package/dist/component/reversalObservations/state.d.ts +34 -0
  118. package/dist/component/reversalObservations/state.d.ts.map +1 -0
  119. package/dist/component/reversalObservations/state.js +34 -0
  120. package/dist/component/reversalObservations/state.js.map +1 -0
  121. package/dist/component/schema.d.ts +275 -0
  122. package/dist/component/schema.js +10 -0
  123. package/dist/component/schema.js.map +1 -1
  124. package/dist/component/usage/allowance.fixtures.d.ts +291 -16
  125. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  126. package/dist/component/usageCredits/accounting.fixtures.d.ts +275 -0
  127. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  128. package/docs/README.md +2 -1
  129. package/docs/client-api.md +6 -0
  130. package/docs/financial-observations.md +51 -8
  131. package/docs/payout-revision-migration.md +54 -0
  132. package/docs/react-workflows-audit.md +73 -2
  133. package/docs/usage-example.md +4 -0
  134. package/package.json +3 -2
  135. package/src/client/financialOwnership.ts +2 -2
  136. package/src/client/payoutRevisionMigration.test.ts +40 -0
  137. package/src/client/payoutRevisionMigration.ts +96 -0
  138. package/src/client/publicTypes.ts +15 -0
  139. package/src/client/reversalObservations.test.ts +69 -0
  140. package/src/client/reversalObservations.ts +151 -0
  141. package/src/component/_generated/api.ts +28 -0
  142. package/src/component/_generated/component.ts +423 -0
  143. package/src/component/connect/mutations.ts +2 -0
  144. package/src/component/connect/reversalClaims.ts +13 -1
  145. package/src/component/financialObservations/transferSchema.ts +1 -0
  146. package/src/component/payoutRevisionJournal/mutations.ts +11 -0
  147. package/src/component/payoutRevisionJournal/schema.ts +34 -0
  148. package/src/component/payoutRevisionJournal/state.ts +141 -0
  149. package/src/component/payoutRevisionMigration/mutations.ts +135 -0
  150. package/src/component/payoutRevisionMigration/queries.ts +50 -0
  151. package/src/component/payoutRevisionMigration/schema.ts +51 -0
  152. package/src/component/payoutSnapshots/legacy-revisions.test.ts +246 -0
  153. package/src/component/payoutSnapshots/legacyRevisionWriter.ts +39 -0
  154. package/src/component/payoutSnapshots/revision-journal-callbacks.test.ts +160 -0
  155. package/src/component/payoutSnapshots/revision-journal-held.test.ts +94 -0
  156. package/src/component/payoutSnapshots/revision-journal.test.ts +310 -0
  157. package/src/component/payoutSnapshots/revision-migration.test.ts +128 -0
  158. package/src/component/payoutSnapshots/revisions.ts +22 -30
  159. package/src/component/reversalObservations/boundaries.test.ts +62 -0
  160. package/src/component/reversalObservations/capture-integrity.test.ts +119 -0
  161. package/src/component/reversalObservations/capture.ts +129 -0
  162. package/src/component/reversalObservations/continuation.test.ts +131 -0
  163. package/src/component/reversalObservations/indexSlice.ts +124 -0
  164. package/src/component/reversalObservations/integrity.ts +31 -0
  165. package/src/component/reversalObservations/lifecycle.test.ts +81 -0
  166. package/src/component/reversalObservations/mutations.ts +211 -0
  167. package/src/component/reversalObservations/pagination.ts +40 -0
  168. package/src/component/reversalObservations/provenance.test.ts +167 -0
  169. package/src/component/reversalObservations/queries.ts +121 -0
  170. package/src/component/reversalObservations/references.ts +134 -0
  171. package/src/component/reversalObservations/schema.ts +100 -0
  172. package/src/component/reversalObservations/selectors.ts +9 -0
  173. package/src/component/reversalObservations/state.ts +42 -0
  174. package/src/component/schema.ts +18 -0
@@ -0,0 +1,119 @@
1
+ // @vitest-environment edge-runtime
2
+ import { convexTest } from "convex-test";
3
+ import { expect, it } from "vitest";
4
+ import { schema, modules } from "../../test.js";
5
+ import { captureReversal } from "./capture.js";
6
+ import {
7
+ transferFingerprint,
8
+ transferIdentity,
9
+ } from "../financialObservations/transferHelpers.js";
10
+ it("retains every original transfer reference while omitting an unbounded malformed pin digest", async () => {
11
+ const t = convexTest(schema, modules);
12
+ await t.run(async (ctx) => {
13
+ const transferId = await ctx.db.insert("transfers", {
14
+ stripeTransferId: "tr_bad_pin",
15
+ sourceChargeId: "ch_bad_pin",
16
+ destinationAccountId: "acct_pin",
17
+ amount: 10,
18
+ currency: "usd",
19
+ role: "store",
20
+ status: "paid",
21
+ });
22
+ const row = (await ctx.db.get("transfers", transferId))!;
23
+ const fingerprint = await transferFingerprint(transferIdentity(row));
24
+ await ctx.db.insert("financialTransferObservations", {
25
+ transferId,
26
+ stripeTransferId: row.stripeTransferId,
27
+ sourceChargeId: row.sourceChargeId,
28
+ bucketKey: row.destinationAccountId,
29
+ role: "store",
30
+ ownershipStatus: "unknown",
31
+ producer: "transfer_fact",
32
+ producerVersion: 1,
33
+ fingerprint,
34
+ observedFingerprint: fingerprint,
35
+ ownershipFingerprint: "x".repeat(900_000),
36
+ generation: 1,
37
+ isContradictory: false,
38
+ });
39
+ const id = await ctx.db.insert("transferReversalOps", {
40
+ operationId: "bad_pin",
41
+ sourceChargeId: "ch_bad_pin",
42
+ slices: [{ stripeTransferId: "tr_bad_pin", from: 0, to: 10 }],
43
+ });
44
+ await captureReversal(
45
+ ctx,
46
+ (await ctx.db.get("transferReversalOps", id))!,
47
+ false,
48
+ [row],
49
+ );
50
+ const chunks = await ctx.db.query("reversalObservationRefs").take(5);
51
+ expect(chunks).toHaveLength(1);
52
+ expect(chunks[0].refs[0]).toMatchObject({ transferId });
53
+ expect(chunks[0].refs[0]?.ownershipFingerprint === undefined).toBe(true);
54
+ expect(JSON.stringify(chunks[0]).length).toBeLessThan(2048);
55
+ });
56
+ });
57
+ it("retains a valid original ownership pin using the existing transfer fingerprint encoding", async () => {
58
+ const t = convexTest(schema, modules);
59
+ await t.run(async (ctx) => {
60
+ const transferId = await ctx.db.insert("transfers", {
61
+ stripeTransferId: "tr_valid_pin",
62
+ sourceChargeId: "ch_valid_pin",
63
+ destinationAccountId: "acct_pin",
64
+ amount: 10,
65
+ currency: "usd",
66
+ role: "store",
67
+ status: "paid",
68
+ });
69
+ const row = (await ctx.db.get("transfers", transferId))!;
70
+ const registrationId = await ctx.db.insert("financialOwnership", {
71
+ bucketKey: "acct_pin",
72
+ kind: "logical",
73
+ userId: "original_owner",
74
+ source: { integration: "test", recordId: "original" },
75
+ generation: 1,
76
+ });
77
+ const fingerprint = await transferFingerprint(transferIdentity(row));
78
+ const ownershipFingerprint = await transferFingerprint({
79
+ registrationId,
80
+ userId: "original_owner",
81
+ ownershipStatus: "registered",
82
+ });
83
+ const markerId = await ctx.db.insert("financialTransferObservations", {
84
+ transferId,
85
+ stripeTransferId: row.stripeTransferId,
86
+ sourceChargeId: row.sourceChargeId,
87
+ bucketKey: row.destinationAccountId,
88
+ role: "store",
89
+ registrationId,
90
+ userId: "original_owner",
91
+ ownershipStatus: "registered",
92
+ producer: "transfer_fact",
93
+ producerVersion: 1,
94
+ fingerprint,
95
+ observedFingerprint: fingerprint,
96
+ ownershipFingerprint,
97
+ generation: 1,
98
+ isContradictory: false,
99
+ });
100
+ const id = await ctx.db.insert("transferReversalOps", {
101
+ operationId: "valid_pin",
102
+ sourceChargeId: "ch_valid_pin",
103
+ slices: [{ stripeTransferId: "tr_valid_pin", from: 0, to: 10 }],
104
+ });
105
+ await captureReversal(
106
+ ctx,
107
+ (await ctx.db.get("transferReversalOps", id))!,
108
+ false,
109
+ [row],
110
+ );
111
+ const chunks = await ctx.db.query("reversalObservationRefs").take(5);
112
+ expect(chunks[0].refs[0]).toMatchObject({
113
+ transferId,
114
+ markerId,
115
+ registrationId,
116
+ ownershipFingerprint,
117
+ });
118
+ });
119
+ });
@@ -0,0 +1,129 @@
1
+ import { canonicalFingerprint } from "../operationEvidence/canonical.js";
2
+ import { reversalReferences, referenceChunkSize } from "./references.js";
3
+ import type { Doc } from "../_generated/dataModel.js";
4
+ import type { MutationCtx } from "../_generated/server.js";
5
+ import {
6
+ bodyOf,
7
+ identityFingerprint,
8
+ selectorDigest,
9
+ sourceFingerprint,
10
+ } from "../operationEvidence/helpers.js";
11
+
12
+ import { advanceObservationGeneration } from "../financialObservations/generations.js";
13
+ export const lifecycleScope = "reversal-claim-lifecycle-v1";
14
+
15
+ /** Called inside financial claim/replay/release transactions, including raw handlers. */
16
+ export async function captureReversal(
17
+ ctx: MutationCtx,
18
+ op: Doc<"transferReversalOps">,
19
+ deleted = false,
20
+ originalRows?: Doc<"transfers">[],
21
+ ) {
22
+ const headers = await ctx.db
23
+ .query("reversalObservations")
24
+ .withIndex("by_original_operation", (q) =>
25
+ q.eq("originalOperationId", op._id),
26
+ )
27
+ .take(2);
28
+ const prior = headers[0];
29
+ if (
30
+ headers.length > 1 ||
31
+ (prior &&
32
+ (!Number.isSafeInteger(prior.generation) ||
33
+ prior.generation < 1 ||
34
+ prior.generation >= Number.MAX_SAFE_INTEGER))
35
+ ) {
36
+ await advanceObservationGeneration(ctx, lifecycleScope);
37
+ return;
38
+ }
39
+ const body = bodyOf(op);
40
+ const fingerprint = await sourceFingerprint(body);
41
+ if (prior?.fingerprint === fingerprint && prior.deleted === deleted) return;
42
+ const identity = await identityFingerprint(body);
43
+ if (prior) {
44
+ let latestPayloadId = prior.latestPayloadId;
45
+ if (prior.fingerprint !== fingerprint) {
46
+ if (prior.latestPayloadId === prior.originalPayloadId)
47
+ latestPayloadId = await ctx.db.insert(
48
+ "reversalObservationPayloads",
49
+ body,
50
+ );
51
+ else
52
+ await ctx.db.replace(
53
+ "reversalObservationPayloads",
54
+ latestPayloadId,
55
+ body,
56
+ );
57
+ }
58
+ const isContradictory =
59
+ prior.isContradictory || prior.originalIdentityFingerprint !== identity;
60
+ await ctx.db.patch("reversalObservations", prior._id, {
61
+ latestPayloadId,
62
+ latestIdentityFingerprint: identity,
63
+ fingerprint,
64
+ deleted,
65
+ generation: prior.generation + 1,
66
+ isContradictory,
67
+ status:
68
+ prior.legacy || isContradictory
69
+ ? "held"
70
+ : prior.sliceCount === 0
71
+ ? "complete"
72
+ : "pending",
73
+ nextIndex: 0,
74
+ });
75
+ await advanceObservationGeneration(ctx, lifecycleScope);
76
+ return;
77
+ }
78
+ const refs = originalRows
79
+ ? await reversalReferences(ctx, op, originalRows)
80
+ : [];
81
+ const chunks = [];
82
+ for (let offset = 0; offset < refs.length; offset += referenceChunkSize)
83
+ chunks.push(refs.slice(offset, offset + referenceChunkSize));
84
+ const referenceFingerprints = await Promise.all(
85
+ chunks.map((refs) => canonicalFingerprint({ refs })),
86
+ );
87
+ const originalPayloadId = await ctx.db.insert(
88
+ "reversalObservationPayloads",
89
+ body,
90
+ );
91
+ const id = await ctx.db.insert("reversalObservations", {
92
+ originalOperationId: op._id,
93
+ sourceCreatedAt: op._creationTime,
94
+ producer: "reversal_claim_lifecycle",
95
+ producerVersion: 1,
96
+ originalPayloadId,
97
+ latestPayloadId: originalPayloadId,
98
+ referenceFingerprints,
99
+ originalFingerprint: fingerprint,
100
+ latestIdentityFingerprint: identity,
101
+ originalIdentityFingerprint: identity,
102
+ fingerprint,
103
+ operationDigest: await selectorDigest("operationId", op.operationId),
104
+ sourceChargeDigest: await selectorDigest(
105
+ "sourceChargeId",
106
+ op.sourceChargeId,
107
+ ),
108
+ generation: 1,
109
+ deleted,
110
+ sliceCount: op.slices.length,
111
+ indexedCount: 0,
112
+ nextIndex: 0,
113
+ status: originalRows
114
+ ? op.slices.length === 0
115
+ ? "complete"
116
+ : "pending"
117
+ : "held",
118
+ legacy: !originalRows,
119
+ isContradictory: false,
120
+ indexTransferGeneration: null,
121
+ });
122
+ for (let index = 0; index < chunks.length; index++)
123
+ await ctx.db.insert("reversalObservationRefs", {
124
+ observationId: id,
125
+ chunkIndex: index,
126
+ refs: chunks[index],
127
+ });
128
+ await advanceObservationGeneration(ctx, lifecycleScope);
129
+ }
@@ -0,0 +1,131 @@
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 f = (name: string) => makeFunctionReference<"mutation">(name);
7
+ const resume = f("reversalObservations/mutations:resume");
8
+ const read = makeFunctionReference<"query">(
9
+ "reversalObservations/queries:operation",
10
+ );
11
+ const slices = makeFunctionReference<"query">(
12
+ "reversalObservations/queries:slices",
13
+ );
14
+ const owner = makeFunctionReference<"query">(
15
+ "reversalObservations/queries:owner",
16
+ );
17
+ it("indexes every exact original slice across bounded pages and preserves original owner pins", async () => {
18
+ const t = convexTest(schema, modules);
19
+ await t.mutation(f("financialOwnership/mutations:register"), {
20
+ bucketKey: "acct_owned",
21
+ kind: "logical",
22
+ userId: "original_owner",
23
+ source: { integration: "test", recordId: "owner" },
24
+ });
25
+ for (let i = 0; i < 3; i++)
26
+ await t.mutation(f("connect/mutations:upsertTransfer"), {
27
+ stripeTransferId: `tr_index_${i}`,
28
+ sourceChargeId: "ch_index",
29
+ destinationAccountId: i === 0 ? "acct_owned" : "acct_unknown",
30
+ amount: 10,
31
+ currency: "usd",
32
+ role: "affiliate",
33
+ status: "paid",
34
+ });
35
+ await t.mutation(f("connect/mutations:claimReversalSlices"), {
36
+ operationId: "op_index",
37
+ sourceChargeId: "ch_index",
38
+ mode: { kind: "full" },
39
+ });
40
+ const op = await t.run((ctx) => ctx.db.query("transferReversalOps").first());
41
+ let state = await t.query(read, { operationId: op!._id });
42
+ for (let n = 0; n < 20 && state.observation.status !== "complete"; n++)
43
+ state = await t.mutation(resume, {
44
+ operationId: op!._id,
45
+ expectedGeneration: state.observation.generation,
46
+ batchSize: 1,
47
+ });
48
+ expect(state).toMatchObject({
49
+ coverage: "unknown",
50
+ observation: { status: "complete", indexedCount: 3 },
51
+ });
52
+ const page1 = await t.query(slices, {
53
+ operationId: op!._id,
54
+ paginationOpts: { numItems: 2, cursor: null },
55
+ });
56
+ const page2 = await t.query(slices, {
57
+ operationId: op!._id,
58
+ paginationOpts: { numItems: 2, cursor: page1.continueCursor },
59
+ });
60
+ expect(
61
+ [...page1.page, ...page2.page].map(
62
+ (x: { sliceIndex: number }) => x.sliceIndex,
63
+ ),
64
+ ).toEqual([0, 1, 2]);
65
+ expect(page2.isDone).toBe(true);
66
+ const owned = await t.query(owner, {
67
+ userId: "original_owner",
68
+ paginationOpts: { numItems: 10, cursor: null },
69
+ });
70
+ expect(owned.page).toHaveLength(1);
71
+ expect(owned.page[0]).toMatchObject({
72
+ ownershipStatus: "registered",
73
+ bucketKey: "acct_owned",
74
+ identityStatus: "matched",
75
+ });
76
+ await t.mutation(f("financialOwnership/mutations:register"), {
77
+ bucketKey: "acct_unknown",
78
+ kind: "logical",
79
+ userId: "later_owner",
80
+ source: { integration: "test", recordId: "late" },
81
+ });
82
+ expect(
83
+ (
84
+ await t.query(owner, {
85
+ userId: "later_owner",
86
+ paginationOpts: { numItems: 10, cursor: null },
87
+ })
88
+ ).page,
89
+ ).toEqual([]);
90
+ });
91
+ it("retains original destination discovery as UNKNOWN after the original transfer disappears", async () => {
92
+ const t = convexTest(schema, modules);
93
+ await t.mutation(f("connect/mutations:upsertTransfer"), {
94
+ stripeTransferId: "tr_missing",
95
+ sourceChargeId: "ch_missing",
96
+ destinationAccountId: "acct_original",
97
+ amount: 10,
98
+ currency: "usd",
99
+ role: "store",
100
+ status: "paid",
101
+ });
102
+ await t.mutation(f("connect/mutations:claimReversalSlices"), {
103
+ operationId: "op_missing",
104
+ sourceChargeId: "ch_missing",
105
+ mode: { kind: "full" },
106
+ });
107
+ const op = await t.run((ctx) => ctx.db.query("transferReversalOps").first());
108
+ const transferId = await t.run(
109
+ async (ctx) => (await ctx.db.query("transfers").first())!._id,
110
+ );
111
+ await t.run((ctx) => ctx.db.delete("transfers", transferId));
112
+ let state = await t.query(read, { operationId: op!._id });
113
+ for (let n = 0; n < 4 && state.observation.status !== "complete"; n++)
114
+ state = await t.mutation(resume, {
115
+ operationId: op!._id,
116
+ expectedGeneration: state.observation.generation,
117
+ });
118
+ const page = await t.query(
119
+ makeFunctionReference<"query">("reversalObservations/queries:bucket"),
120
+ {
121
+ bucketKey: "acct_original",
122
+ paginationOpts: { numItems: 10, cursor: null },
123
+ },
124
+ );
125
+ expect(page.page).toHaveLength(1);
126
+ expect(page.page[0]).toMatchObject({
127
+ transferId,
128
+ identityStatus: "unknown",
129
+ ownershipStatus: "unknown",
130
+ });
131
+ });
@@ -0,0 +1,124 @@
1
+ import { bucketDigest, ownerDigest } from "./selectors.js";
2
+ import type { Infer } from "convex/values";
3
+ import type { ref } from "./schema.js";
4
+ import type { MutationCtx } from "../_generated/server.js";
5
+ import {
6
+ transferFingerprint,
7
+ transferIdentity,
8
+ } from "../financialObservations/transferHelpers.js";
9
+ import { legOwnership } from "../financialObservations/settlementHelpers.js";
10
+ const compact = (value: string | undefined) =>
11
+ value !== undefined && new TextEncoder().encode(value).length <= 256
12
+ ? value
13
+ : undefined;
14
+ /** Original refs and pins are evidence. New registrations never fill old unknown ownership. */
15
+ export async function indexSlice(
16
+ ctx: MutationCtx,
17
+ reference: Infer<typeof ref> | null,
18
+ stripeTransferId: string,
19
+ sourceChargeId: string,
20
+ ) {
21
+ const unknown = {
22
+ ownershipStatus: "unknown" as const,
23
+ identityStatus: "unknown" as const,
24
+ transferGeneration: null,
25
+ };
26
+ if (!reference) return unknown;
27
+ const original = {
28
+ ...unknown,
29
+ transferId: reference.transferId,
30
+ bucketDigest: reference.bucketDigest,
31
+ ...(reference.ownerDigest ? { ownerDigest: reference.ownerDigest } : {}),
32
+ ...(reference.registrationId
33
+ ? { registrationId: reference.registrationId }
34
+ : {}),
35
+ };
36
+ const row = await ctx.db.get("transfers", reference.transferId);
37
+ if (!row) return original;
38
+ if (
39
+ reference.ambiguous ||
40
+ row.stripeTransferId !== stripeTransferId ||
41
+ row.sourceChargeId !== sourceChargeId ||
42
+ (await transferFingerprint(transferIdentity(row))) !==
43
+ reference.identityFingerprint
44
+ )
45
+ return { ...original, identityStatus: "contradictory" as const };
46
+ const sourceRows = await ctx.db
47
+ .query("transfers")
48
+ .withIndex("by_stripe_transfer_id", (q) =>
49
+ q.eq("stripeTransferId", stripeTransferId),
50
+ )
51
+ .take(2);
52
+ if (sourceRows.length !== 1 || sourceRows[0]._id !== row._id)
53
+ return { ...original, identityStatus: "contradictory" as const };
54
+ if ((await bucketDigest(row.destinationAccountId)) !== reference.bucketDigest)
55
+ return null;
56
+ const matched = {
57
+ ...original,
58
+ identityStatus: "matched" as const,
59
+ ...(compact(row.destinationAccountId) !== undefined
60
+ ? { bucketKey: row.destinationAccountId }
61
+ : {}),
62
+ };
63
+ const markers = await ctx.db
64
+ .query("financialTransferObservations")
65
+ .withIndex("by_transfer_id", (q) =>
66
+ q.eq("transferId", reference.transferId),
67
+ )
68
+ .take(2);
69
+ const marker = markers[0];
70
+ const markerMatches =
71
+ markers.length === 1 &&
72
+ marker._id === reference.markerId &&
73
+ !marker.isContradictory &&
74
+ marker.fingerprint === reference.markerIdentityFingerprint &&
75
+ marker.stripeTransferId === stripeTransferId &&
76
+ marker.sourceChargeId === sourceChargeId &&
77
+ marker.bucketKey === row.destinationAccountId &&
78
+ marker.role === row.role;
79
+ const transferGeneration =
80
+ markerMatches &&
81
+ Number.isSafeInteger(marker.generation) &&
82
+ marker.generation >= 1
83
+ ? marker.generation
84
+ : null;
85
+ if (!reference.registrationId || !reference.ownershipFingerprint)
86
+ return { ...matched, transferGeneration };
87
+ const registration = await ctx.db.get(
88
+ "financialOwnership",
89
+ reference.registrationId,
90
+ );
91
+ if (!registration) return { ...matched, transferGeneration };
92
+ if (registration.bucketKey !== row.destinationAccountId) return null;
93
+ const pin = {
94
+ registrationId: registration._id,
95
+ userId: registration.userId,
96
+ orgId: registration.orgId,
97
+ };
98
+ if (
99
+ (await transferFingerprint({ ...pin, ownershipStatus: "registered" })) !==
100
+ reference.ownershipFingerprint
101
+ )
102
+ return null;
103
+ if (
104
+ reference.ownerDigest &&
105
+ (await ownerDigest(pin.userId, pin.orgId)) !== reference.ownerDigest
106
+ )
107
+ return null;
108
+ const live = await legOwnership(ctx, row.destinationAccountId, pin);
109
+ return {
110
+ ...matched,
111
+ transferGeneration,
112
+ ...(reference.ownerDigest &&
113
+ reference.ownerDigest === (await ownerDigest(pin.userId, pin.orgId))
114
+ ? { ownerDigest: reference.ownerDigest }
115
+ : {}),
116
+ ...(compact(pin.userId) !== undefined ? { userId: pin.userId } : {}),
117
+ ...(compact(pin.orgId) !== undefined ? { orgId: pin.orgId } : {}),
118
+ ownershipStatus:
119
+ markerMatches &&
120
+ marker.ownershipFingerprint === reference.ownershipFingerprint
121
+ ? live.ownershipStatus
122
+ : ("contradictory" as const),
123
+ };
124
+ }
@@ -0,0 +1,31 @@
1
+ import type { Doc } from "../_generated/dataModel.js";
2
+ import type { QueryCtx } from "../_generated/server.js";
3
+ import {
4
+ sourceFingerprint,
5
+ identityFingerprint,
6
+ } from "../operationEvidence/helpers.js";
7
+ /** Validate the exact original/latest bytes; exposure is part of provenance too. */
8
+ export async function validPayload(
9
+ ctx: QueryCtx,
10
+ header: Doc<"reversalObservations">,
11
+ version: "original" | "latest",
12
+ ) {
13
+ const row = await ctx.db.get(
14
+ "reversalObservationPayloads",
15
+ version === "original" ? header.originalPayloadId : header.latestPayloadId,
16
+ );
17
+ if (!row) return null;
18
+ const { _id, _creationTime, ...body } = row;
19
+ void _id;
20
+ void _creationTime;
21
+ const full =
22
+ version === "original" ? header.originalFingerprint : header.fingerprint;
23
+ const identity =
24
+ version === "original"
25
+ ? header.originalIdentityFingerprint
26
+ : header.latestIdentityFingerprint;
27
+ return (await sourceFingerprint(body)) === full &&
28
+ (await identityFingerprint(body)) === identity
29
+ ? row
30
+ : null;
31
+ }
@@ -0,0 +1,81 @@
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
+ import { claimReversalSlicesDefinition } from "../connect/reversalClaims.js";
7
+ const m = (name: string) =>
8
+ makeFunctionReference<"mutation">(`connect/mutations:${name}`);
9
+ const read = makeFunctionReference<"query">(
10
+ "reversalObservations/queries:operation",
11
+ );
12
+ it("captures raw-context claims, stable replay and deletion without changing original operation provenance", async () => {
13
+ const t = convexTest(schema, modules);
14
+ await t.run((ctx) =>
15
+ ctx.db.insert("transfers", {
16
+ stripeTransferId: "tr_raw",
17
+ sourceChargeId: "ch_raw",
18
+ destinationAccountId: "acct_raw",
19
+ amount: 100,
20
+ currency: "usd",
21
+ status: "paid",
22
+ role: "affiliate",
23
+ }),
24
+ );
25
+ const args = {
26
+ operationId: "refund_raw",
27
+ sourceChargeId: "ch_raw",
28
+ mode: { kind: "full" as const },
29
+ };
30
+ const result = await t.run((ctx) =>
31
+ claimReversalSlicesDefinition.handler(ctx, args),
32
+ );
33
+ expect(result).toMatchObject({
34
+ replay: false,
35
+ slices: [{ stripeTransferId: "tr_raw", from: 0, to: 100, confirmed: 0 }],
36
+ });
37
+ const op = await t.run((ctx) => ctx.db.query("transferReversalOps").first());
38
+ const first = await t.query(read, { operationId: op!._id });
39
+ expect(first).toMatchObject({
40
+ coverage: "unknown",
41
+ observation: {
42
+ originalOperationId: op!._id,
43
+ generation: 1,
44
+ deleted: false,
45
+ sliceCount: 1,
46
+ },
47
+ });
48
+ expect(
49
+ await t.run((ctx) => claimReversalSlicesDefinition.handler(ctx, args)),
50
+ ).toMatchObject({ replay: true });
51
+ expect(await t.query(read, { operationId: op!._id })).toEqual(first);
52
+ await t.mutation(m("releaseReversalClaim"), {
53
+ operationId: args.operationId,
54
+ verified: [{ stripeTransferId: "tr_raw", amountReversed: 0 }],
55
+ });
56
+ expect(await t.query(read, { operationId: op!._id })).toMatchObject({
57
+ coverage: "unknown",
58
+ observation: { originalOperationId: op!._id, generation: 2, deleted: true },
59
+ });
60
+ await t.run((ctx) => claimReversalSlicesDefinition.handler(ctx, args));
61
+ const ops = await t.run((ctx) => ctx.db.query("transferReversalOps").take(5));
62
+ expect(ops[0]._id).not.toBe(op!._id);
63
+ expect(await t.query(read, { operationId: op!._id })).toMatchObject({
64
+ observation: { originalOperationId: op!._id, deleted: true },
65
+ });
66
+ });
67
+ it("records empty operations without inventing recipients", async () => {
68
+ const t = convexTest(schema, modules);
69
+ await t.run((ctx) =>
70
+ claimReversalSlicesDefinition.handler(ctx, {
71
+ operationId: "empty",
72
+ sourceChargeId: "ch_empty",
73
+ mode: { kind: "full" },
74
+ }),
75
+ );
76
+ const op = await t.run((ctx) => ctx.db.query("transferReversalOps").first());
77
+ expect(await t.query(read, { operationId: op!._id })).toMatchObject({
78
+ coverage: "unknown",
79
+ observation: { sliceCount: 0, indexedCount: 0 },
80
+ });
81
+ });