@fantastic.dev/better-stripe 0.62.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 (217) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +22 -2
  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 +550 -0
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +275 -0
  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/paymentSource/resolver.d.ts +1 -0
  16. package/dist/client/paymentSource/resolver.d.ts.map +1 -1
  17. package/dist/client/paymentSource/resolver.js +11 -2
  18. package/dist/client/paymentSource/resolver.js.map +1 -1
  19. package/dist/client/paymentSource/zeroTierLines.d.ts +4 -0
  20. package/dist/client/paymentSource/zeroTierLines.d.ts.map +1 -0
  21. package/dist/client/paymentSource/zeroTierLines.js +35 -0
  22. package/dist/client/paymentSource/zeroTierLines.js.map +1 -0
  23. package/dist/client/payoutRevisionMigration.d.ts +37 -0
  24. package/dist/client/payoutRevisionMigration.d.ts.map +1 -0
  25. package/dist/client/payoutRevisionMigration.js +49 -0
  26. package/dist/client/payoutRevisionMigration.js.map +1 -0
  27. package/dist/client/publicTypes.d.ts +2 -0
  28. package/dist/client/publicTypes.d.ts.map +1 -1
  29. package/dist/client/reversalObservations.d.ts +62 -0
  30. package/dist/client/reversalObservations.d.ts.map +1 -0
  31. package/dist/client/reversalObservations.js +79 -0
  32. package/dist/client/reversalObservations.js.map +1 -0
  33. package/dist/client/usage/configuration.d.ts +13 -0
  34. package/dist/client/usage/configuration.d.ts.map +1 -0
  35. package/dist/client/usage/configuration.js +2 -0
  36. package/dist/client/usage/configuration.js.map +1 -0
  37. package/dist/client/usage/deliveryProvider.d.ts.map +1 -1
  38. package/dist/client/usage/deliveryProvider.js +16 -0
  39. package/dist/client/usage/deliveryProvider.js.map +1 -1
  40. package/dist/client/usage/index.d.ts +2 -0
  41. package/dist/client/usage/index.d.ts.map +1 -1
  42. package/dist/client/usage/invoiceSale.d.ts.map +1 -1
  43. package/dist/client/usage/invoiceSale.js +15 -2
  44. package/dist/client/usage/invoiceSale.js.map +1 -1
  45. package/dist/client/usage/observationClient.d.ts +2 -2
  46. package/dist/client/usage/observationClient.d.ts.map +1 -1
  47. package/dist/client/usage/views.d.ts +24 -0
  48. package/dist/client/usage/views.d.ts.map +1 -0
  49. package/dist/client/usage/views.js +2 -0
  50. package/dist/client/usage/views.js.map +1 -0
  51. package/dist/component/_generated/api.d.ts +28 -0
  52. package/dist/component/_generated/api.d.ts.map +1 -1
  53. package/dist/component/_generated/api.js.map +1 -1
  54. package/dist/component/_generated/component.d.ts +354 -0
  55. package/dist/component/_generated/component.d.ts.map +1 -1
  56. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  57. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  58. package/dist/component/connect/mutations.d.ts.map +1 -1
  59. package/dist/component/connect/mutations.js +2 -0
  60. package/dist/component/connect/mutations.js.map +1 -1
  61. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  62. package/dist/component/connect/reversalClaims.js +10 -1
  63. package/dist/component/connect/reversalClaims.js.map +1 -1
  64. package/dist/component/earnings/triggers.d.ts +408 -16
  65. package/dist/component/earnings/triggers.d.ts.map +1 -1
  66. package/dist/component/financialObservations/transferSchema.d.ts +1 -0
  67. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -1
  68. package/dist/component/financialObservations/transferSchema.js +1 -0
  69. package/dist/component/financialObservations/transferSchema.js.map +1 -1
  70. package/dist/component/payoutRevisionJournal/mutations.d.ts +15 -0
  71. package/dist/component/payoutRevisionJournal/mutations.d.ts.map +1 -0
  72. package/dist/component/payoutRevisionJournal/mutations.js +11 -0
  73. package/dist/component/payoutRevisionJournal/mutations.js.map +1 -0
  74. package/dist/component/payoutRevisionJournal/schema.d.ts +45 -0
  75. package/dist/component/payoutRevisionJournal/schema.d.ts.map +1 -0
  76. package/dist/component/payoutRevisionJournal/schema.js +22 -0
  77. package/dist/component/payoutRevisionJournal/schema.js.map +1 -0
  78. package/dist/component/payoutRevisionJournal/state.d.ts +36 -0
  79. package/dist/component/payoutRevisionJournal/state.d.ts.map +1 -0
  80. package/dist/component/payoutRevisionJournal/state.js +111 -0
  81. package/dist/component/payoutRevisionJournal/state.js.map +1 -0
  82. package/dist/component/payoutRevisionMigration/mutations.d.ts +36 -0
  83. package/dist/component/payoutRevisionMigration/mutations.d.ts.map +1 -0
  84. package/dist/component/payoutRevisionMigration/mutations.js +126 -0
  85. package/dist/component/payoutRevisionMigration/mutations.js.map +1 -0
  86. package/dist/component/payoutRevisionMigration/queries.d.ts +38 -0
  87. package/dist/component/payoutRevisionMigration/queries.d.ts.map +1 -0
  88. package/dist/component/payoutRevisionMigration/queries.js +39 -0
  89. package/dist/component/payoutRevisionMigration/queries.js.map +1 -0
  90. package/dist/component/payoutRevisionMigration/schema.d.ts +115 -0
  91. package/dist/component/payoutRevisionMigration/schema.d.ts.map +1 -0
  92. package/dist/component/payoutRevisionMigration/schema.js +52 -0
  93. package/dist/component/payoutRevisionMigration/schema.js.map +1 -0
  94. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts +4 -0
  95. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts.map +1 -0
  96. package/dist/component/payoutSnapshots/legacyRevisionWriter.js +33 -0
  97. package/dist/component/payoutSnapshots/legacyRevisionWriter.js.map +1 -0
  98. package/dist/component/payoutSnapshots/revisions.d.ts.map +1 -1
  99. package/dist/component/payoutSnapshots/revisions.js +23 -29
  100. package/dist/component/payoutSnapshots/revisions.js.map +1 -1
  101. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  102. package/dist/component/refundSync/mutations.d.ts +1 -1
  103. package/dist/component/refundSync/mutations.d.ts.map +1 -1
  104. package/dist/component/reversalObservations/capture.d.ts +6 -0
  105. package/dist/component/reversalObservations/capture.d.ts.map +1 -0
  106. package/dist/component/reversalObservations/capture.js +96 -0
  107. package/dist/component/reversalObservations/capture.js.map +1 -0
  108. package/dist/component/reversalObservations/indexSlice.d.ts +29 -0
  109. package/dist/component/reversalObservations/indexSlice.d.ts.map +1 -0
  110. package/dist/component/reversalObservations/indexSlice.js +101 -0
  111. package/dist/component/reversalObservations/indexSlice.js.map +1 -0
  112. package/dist/component/reversalObservations/integrity.d.ts +25 -0
  113. package/dist/component/reversalObservations/integrity.d.ts.map +1 -0
  114. package/dist/component/reversalObservations/integrity.js +19 -0
  115. package/dist/component/reversalObservations/integrity.js.map +1 -0
  116. package/dist/component/reversalObservations/mutations.d.ts +37 -0
  117. package/dist/component/reversalObservations/mutations.d.ts.map +1 -0
  118. package/dist/component/reversalObservations/mutations.js +181 -0
  119. package/dist/component/reversalObservations/mutations.js.map +1 -0
  120. package/dist/component/reversalObservations/pagination.d.ts +34 -0
  121. package/dist/component/reversalObservations/pagination.d.ts.map +1 -0
  122. package/dist/component/reversalObservations/pagination.js +31 -0
  123. package/dist/component/reversalObservations/pagination.js.map +1 -0
  124. package/dist/component/reversalObservations/queries.d.ts +221 -0
  125. package/dist/component/reversalObservations/queries.d.ts.map +1 -0
  126. package/dist/component/reversalObservations/queries.js +114 -0
  127. package/dist/component/reversalObservations/queries.js.map +1 -0
  128. package/dist/component/reversalObservations/references.d.ts +17 -0
  129. package/dist/component/reversalObservations/references.d.ts.map +1 -0
  130. package/dist/component/reversalObservations/references.js +95 -0
  131. package/dist/component/reversalObservations/references.js.map +1 -0
  132. package/dist/component/reversalObservations/schema.d.ts +525 -0
  133. package/dist/component/reversalObservations/schema.d.ts.map +1 -0
  134. package/dist/component/reversalObservations/schema.js +92 -0
  135. package/dist/component/reversalObservations/schema.js.map +1 -0
  136. package/dist/component/reversalObservations/selectors.d.ts +3 -0
  137. package/dist/component/reversalObservations/selectors.d.ts.map +1 -0
  138. package/dist/component/reversalObservations/selectors.js +8 -0
  139. package/dist/component/reversalObservations/selectors.js.map +1 -0
  140. package/dist/component/reversalObservations/state.d.ts +34 -0
  141. package/dist/component/reversalObservations/state.d.ts.map +1 -0
  142. package/dist/component/reversalObservations/state.js +34 -0
  143. package/dist/component/reversalObservations/state.js.map +1 -0
  144. package/dist/component/schema.d.ts +275 -0
  145. package/dist/component/schema.js +10 -0
  146. package/dist/component/schema.js.map +1 -1
  147. package/dist/component/usage/allowance.fixtures.d.ts +291 -16
  148. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  149. package/dist/component/usageCredits/accounting.fixtures.d.ts +275 -0
  150. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  151. package/dist/react/workflows/Usage.types.d.ts +2 -23
  152. package/dist/react/workflows/Usage.types.d.ts.map +1 -1
  153. package/dist/react/workflows/Usage.types.js.map +1 -1
  154. package/dist/react/workflows/UsageConfiguration.types.d.ts +3 -11
  155. package/dist/react/workflows/UsageConfiguration.types.d.ts.map +1 -1
  156. package/docs/README.md +4 -1
  157. package/docs/client-api.md +6 -0
  158. package/docs/financial-observations.md +51 -8
  159. package/docs/payout-revision-migration.md +54 -0
  160. package/docs/react-workflows-audit.md +73 -2
  161. package/docs/usage-configuration.md +4 -0
  162. package/docs/usage-delivery.md +4 -0
  163. package/docs/usage-example.md +250 -0
  164. package/docs/usage-react.md +4 -0
  165. package/docs/usage-settlement.md +8 -3
  166. package/package.json +4 -2
  167. package/src/client/financialOwnership.ts +2 -2
  168. package/src/client/paymentSource/resolver.ts +14 -2
  169. package/src/client/paymentSource/zeroTierLines.ts +42 -0
  170. package/src/client/payoutRevisionMigration.test.ts +40 -0
  171. package/src/client/payoutRevisionMigration.ts +96 -0
  172. package/src/client/publicTypes.ts +15 -0
  173. package/src/client/reversalObservations.test.ts +69 -0
  174. package/src/client/reversalObservations.ts +151 -0
  175. package/src/client/usage/configuration.ts +9 -0
  176. package/src/client/usage/deliveryProvider.test.ts +77 -37
  177. package/src/client/usage/deliveryProvider.ts +19 -0
  178. package/src/client/usage/index.ts +4 -0
  179. package/src/client/usage/invoiceSale.test.ts +68 -0
  180. package/src/client/usage/invoiceSale.ts +20 -2
  181. package/src/client/usage/views.ts +23 -0
  182. package/src/component/_generated/api.ts +28 -0
  183. package/src/component/_generated/component.ts +423 -0
  184. package/src/component/connect/mutations.ts +2 -0
  185. package/src/component/connect/reversalClaims.ts +13 -1
  186. package/src/component/financialObservations/transferSchema.ts +1 -0
  187. package/src/component/payoutRevisionJournal/mutations.ts +11 -0
  188. package/src/component/payoutRevisionJournal/schema.ts +34 -0
  189. package/src/component/payoutRevisionJournal/state.ts +141 -0
  190. package/src/component/payoutRevisionMigration/mutations.ts +135 -0
  191. package/src/component/payoutRevisionMigration/queries.ts +50 -0
  192. package/src/component/payoutRevisionMigration/schema.ts +51 -0
  193. package/src/component/payoutSnapshots/legacy-revisions.test.ts +246 -0
  194. package/src/component/payoutSnapshots/legacyRevisionWriter.ts +39 -0
  195. package/src/component/payoutSnapshots/revision-journal-callbacks.test.ts +160 -0
  196. package/src/component/payoutSnapshots/revision-journal-held.test.ts +94 -0
  197. package/src/component/payoutSnapshots/revision-journal.test.ts +310 -0
  198. package/src/component/payoutSnapshots/revision-migration.test.ts +128 -0
  199. package/src/component/payoutSnapshots/revisions.ts +22 -30
  200. package/src/component/reversalObservations/boundaries.test.ts +62 -0
  201. package/src/component/reversalObservations/capture-integrity.test.ts +119 -0
  202. package/src/component/reversalObservations/capture.ts +129 -0
  203. package/src/component/reversalObservations/continuation.test.ts +131 -0
  204. package/src/component/reversalObservations/indexSlice.ts +124 -0
  205. package/src/component/reversalObservations/integrity.ts +31 -0
  206. package/src/component/reversalObservations/lifecycle.test.ts +81 -0
  207. package/src/component/reversalObservations/mutations.ts +211 -0
  208. package/src/component/reversalObservations/pagination.ts +40 -0
  209. package/src/component/reversalObservations/provenance.test.ts +167 -0
  210. package/src/component/reversalObservations/queries.ts +121 -0
  211. package/src/component/reversalObservations/references.ts +134 -0
  212. package/src/component/reversalObservations/schema.ts +100 -0
  213. package/src/component/reversalObservations/selectors.ts +9 -0
  214. package/src/component/reversalObservations/state.ts +42 -0
  215. package/src/component/schema.ts +18 -0
  216. package/src/react/workflows/Usage.types.ts +5 -29
  217. package/src/react/workflows/UsageConfiguration.types.ts +3 -11
@@ -0,0 +1,211 @@
1
+ import { validPayload } from "./integrity.js";
2
+ import { v } from "convex/values";
3
+ import { mutation } from "../_generated/server.js";
4
+ import { operationResult } from "./schema.js";
5
+ import { header, readState } from "./state.js";
6
+ import { indexSlice } from "./indexSlice.js";
7
+ import { lifecycleScope } from "./capture.js";
8
+ import { referenceChunkSize } from "./references.js";
9
+ import { identityFingerprint } from "../operationEvidence/helpers.js";
10
+ import { canonicalFingerprint } from "../operationEvidence/canonical.js";
11
+ import {
12
+ advanceObservationGeneration,
13
+ observationGeneration,
14
+ } from "../financialObservations/generations.js";
15
+ import { transferProducerScope } from "../financialObservations/transferHelpers.js";
16
+ /** Trusted-host bounded diagnostic enrichment; never executes a reversal or grants coverage. */
17
+ export const resume = mutation({
18
+ args: {
19
+ operationId: v.id("transferReversalOps"),
20
+ expectedGeneration: v.number(),
21
+ batchSize: v.optional(v.number()),
22
+ },
23
+ returns: operationResult,
24
+ handler: async (ctx, args) => {
25
+ const batchSize = args.batchSize ?? 10;
26
+ if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 20)
27
+ throw new Error(
28
+ "Reversal observation batch must contain 1 to 20 slices.",
29
+ );
30
+ const row = await header(ctx, args.operationId);
31
+ if (!row) return { ...(await readState(ctx)), observation: null };
32
+ if (args.expectedGeneration !== row.generation)
33
+ throw new Error("Reversal observation generation changed.");
34
+ if (row.status === "held" || row.status === "complete")
35
+ return { ...(await readState(ctx)), observation: row };
36
+ const payload = await validPayload(ctx, row, "original");
37
+ const hold = async () => {
38
+ await ctx.db.patch("reversalObservations", row._id, { status: "held" });
39
+ await advanceObservationGeneration(ctx, lifecycleScope);
40
+ };
41
+ if (
42
+ !payload ||
43
+ payload.slices.length !== row.sliceCount ||
44
+ (await identityFingerprint(payload)) !== row.originalIdentityFingerprint
45
+ ) {
46
+ await hold();
47
+ return {
48
+ ...(await readState(ctx)),
49
+ observation: await header(ctx, args.operationId),
50
+ };
51
+ }
52
+ const producerGeneration = await observationGeneration(
53
+ ctx,
54
+ transferProducerScope,
55
+ );
56
+ if (producerGeneration === null) {
57
+ await hold();
58
+ return {
59
+ ...(await readState(ctx)),
60
+ observation: await header(ctx, args.operationId),
61
+ };
62
+ }
63
+ if (
64
+ (row.nextIndex !== 0 || row.status === "validating") &&
65
+ producerGeneration !== row.indexTransferGeneration
66
+ ) {
67
+ await ctx.db.patch("reversalObservations", row._id, {
68
+ status: "pending",
69
+ nextIndex: 0,
70
+ indexTransferGeneration: producerGeneration,
71
+ });
72
+ await advanceObservationGeneration(ctx, lifecycleScope);
73
+ return {
74
+ ...(await readState(ctx)),
75
+ observation: await header(ctx, args.operationId),
76
+ };
77
+ }
78
+ let indexedCount = row.indexedCount;
79
+ const limit = Math.min(row.sliceCount, row.nextIndex + batchSize);
80
+ let end = row.nextIndex;
81
+ for (let i = row.nextIndex; i < limit; i++) {
82
+ const budget = await ctx.meta.getTransactionMetrics();
83
+ if (
84
+ budget.bytesRead.remaining < 9_000_000 ||
85
+ budget.databaseQueries.remaining < 16
86
+ ) {
87
+ if (end === row.nextIndex)
88
+ throw new Error(
89
+ "Reversal observation requires a fresh transaction with read headroom.",
90
+ );
91
+ break;
92
+ }
93
+ const chunks = await ctx.db
94
+ .query("reversalObservationRefs")
95
+ .withIndex("by_observation_chunk", (q) =>
96
+ q
97
+ .eq("observationId", row._id)
98
+ .eq("chunkIndex", Math.floor(i / referenceChunkSize)),
99
+ )
100
+ .take(2);
101
+ const reference = chunks[0]?.refs[i % referenceChunkSize];
102
+ const chunkIndex = Math.floor(i / referenceChunkSize);
103
+ if (
104
+ chunks.length === 1 &&
105
+ (await canonicalFingerprint({ refs: chunks[0].refs })) !==
106
+ row.referenceFingerprints[chunkIndex]
107
+ ) {
108
+ await hold();
109
+ return {
110
+ ...(await readState(ctx)),
111
+ observation: await header(ctx, args.operationId),
112
+ };
113
+ }
114
+ if (chunks.length !== 1 || reference === undefined) {
115
+ await hold();
116
+ return {
117
+ ...(await readState(ctx)),
118
+ observation: await header(ctx, args.operationId),
119
+ };
120
+ }
121
+ const indexed = await indexSlice(
122
+ ctx,
123
+ reference,
124
+ payload.slices[i].stripeTransferId,
125
+ payload.sourceChargeId,
126
+ );
127
+ if (!indexed) {
128
+ await hold();
129
+ return {
130
+ ...(await readState(ctx)),
131
+ observation: await header(ctx, args.operationId),
132
+ };
133
+ }
134
+ const fields = {
135
+ observationId: row._id,
136
+ originalOperationId: row.originalOperationId,
137
+ sliceIndex: i,
138
+ generation: row.generation,
139
+ ...indexed,
140
+ };
141
+ const existing = await ctx.db
142
+ .query("reversalObservationSlices")
143
+ .withIndex("by_observation_slice", (q) =>
144
+ q.eq("observationId", row._id).eq("sliceIndex", i),
145
+ )
146
+ .take(2);
147
+ if (existing.length > 1) {
148
+ await hold();
149
+ return {
150
+ ...(await readState(ctx)),
151
+ observation: await header(ctx, args.operationId),
152
+ };
153
+ }
154
+ if (row.status === "validating") {
155
+ const prior = existing[0];
156
+ if (!prior) {
157
+ await hold();
158
+ return {
159
+ ...(await readState(ctx)),
160
+ observation: await header(ctx, args.operationId),
161
+ };
162
+ }
163
+ const { _id, _creationTime, ...stored } = prior;
164
+ void _id;
165
+ void _creationTime;
166
+ if (
167
+ (await canonicalFingerprint(stored)) !==
168
+ (await canonicalFingerprint(fields))
169
+ ) {
170
+ await hold();
171
+ return {
172
+ ...(await readState(ctx)),
173
+ observation: await header(ctx, args.operationId),
174
+ };
175
+ }
176
+ } else if (!existing[0] && i < indexedCount) {
177
+ await hold();
178
+ return {
179
+ ...(await readState(ctx)),
180
+ observation: await header(ctx, args.operationId),
181
+ };
182
+ } else if (existing[0])
183
+ await ctx.db.replace(
184
+ "reversalObservationSlices",
185
+ existing[0]._id,
186
+ fields,
187
+ );
188
+ else {
189
+ await ctx.db.insert("reversalObservationSlices", fields);
190
+ indexedCount++;
191
+ }
192
+ end = i + 1;
193
+ }
194
+ await ctx.db.patch("reversalObservations", row._id, {
195
+ indexedCount,
196
+ indexTransferGeneration: producerGeneration,
197
+ nextIndex: end === row.sliceCount ? 0 : end,
198
+ status:
199
+ end === row.sliceCount
200
+ ? row.status === "validating"
201
+ ? "complete"
202
+ : "validating"
203
+ : row.status,
204
+ });
205
+ await advanceObservationGeneration(ctx, lifecycleScope);
206
+ return {
207
+ ...(await readState(ctx)),
208
+ observation: await header(ctx, args.operationId),
209
+ };
210
+ },
211
+ });
@@ -0,0 +1,40 @@
1
+ import { v } from "convex/values";
2
+ import type { Validator } from "convex/values";
3
+ import type { PaginationOptions } from "convex/server";
4
+ export const readFields = {
5
+ coverage: v.literal("unknown"),
6
+ generation: v.union(v.number(), v.null()),
7
+ transferGeneration: v.union(v.number(), v.null()),
8
+ };
9
+ export function pageResult<T>(doc: Validator<T, "required", string>) {
10
+ return v.object({
11
+ ...readFields,
12
+ page: v.array(doc),
13
+ isDone: v.boolean(),
14
+ continueCursor: v.string(),
15
+ splitCursor: v.optional(v.union(v.string(), v.null())),
16
+ pageStatus: v.optional(
17
+ v.union(
18
+ v.literal("SplitRecommended"),
19
+ v.literal("SplitRequired"),
20
+ v.null(),
21
+ ),
22
+ ),
23
+ });
24
+ }
25
+ export function boundedPage(options: PaginationOptions) {
26
+ if (
27
+ !Number.isInteger(options.numItems) ||
28
+ options.numItems < 1 ||
29
+ options.numItems > 100
30
+ )
31
+ throw new Error("Reversal observation pages must contain 1 to 100 rows.");
32
+ for (const value of [options.maximumBytesRead, options.maximumRowsRead])
33
+ if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
34
+ throw new Error("Invalid pagination read budget.");
35
+ return {
36
+ ...options,
37
+ maximumRowsRead: Math.min(options.maximumRowsRead ?? 100, 100),
38
+ maximumBytesRead: Math.min(options.maximumBytesRead ?? 262144, 262144),
39
+ };
40
+ }
@@ -0,0 +1,167 @@
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 m = (name: string) => makeFunctionReference<"mutation">(name);
7
+ const q = (name: string) =>
8
+ makeFunctionReference<"query">(`reversalObservations/queries:${name}`);
9
+ async function setup() {
10
+ const t = convexTest(schema, modules);
11
+ await t.mutation(m("financialOwnership/mutations:register"), {
12
+ bucketKey: "acct_provenance",
13
+ kind: "logical",
14
+ userId: "owner",
15
+ source: { integration: "test", recordId: "owner" },
16
+ });
17
+ await t.mutation(m("connect/mutations:upsertTransfer"), {
18
+ stripeTransferId: "tr_provenance",
19
+ sourceChargeId: "ch_provenance",
20
+ destinationAccountId: "acct_provenance",
21
+ amount: 10,
22
+ currency: "usd",
23
+ role: "store",
24
+ status: "paid",
25
+ });
26
+ const args = {
27
+ operationId: "op_provenance",
28
+ sourceChargeId: "ch_provenance",
29
+ mode: { kind: "full" as const },
30
+ commissionExposure: {
31
+ kind: "refund" as const,
32
+ chargeAmount: 10,
33
+ principal: 5,
34
+ finalized: false,
35
+ },
36
+ };
37
+ await t.mutation(m("connect/mutations:claimReversalSlices"), args);
38
+ const op = await t.run((ctx) => ctx.db.query("transferReversalOps").first());
39
+ return { t, args, operationId: op!._id };
40
+ }
41
+ it("verifies the full original exposure body after replay changes latest exposure", async () => {
42
+ const { t, args, operationId } = await setup();
43
+ await t.mutation(m("connect/mutations:claimReversalSlices"), {
44
+ ...args,
45
+ commissionExposure: { ...args.commissionExposure, finalized: true },
46
+ });
47
+ const state = await t.query(q("operation"), { operationId });
48
+ expect(state.observation.generation).toBe(2);
49
+ expect(
50
+ (await t.query(q("payload"), { operationId, version: "original" })).payload
51
+ .commissionExposure.finalized,
52
+ ).toBe(false);
53
+ expect(
54
+ (await t.query(q("payload"), { operationId, version: "latest" })).payload
55
+ .commissionExposure.finalized,
56
+ ).toBe(true);
57
+ await t.run((ctx) =>
58
+ ctx.db.patch(
59
+ "reversalObservationPayloads",
60
+ state.observation.originalPayloadId,
61
+ { commissionExposure: { ...args.commissionExposure, principal: 9 } },
62
+ ),
63
+ );
64
+ expect(
65
+ (await t.query(q("payload"), { operationId, version: "original" })).payload,
66
+ ).toBeNull();
67
+ expect(
68
+ await t.mutation(m("reversalObservations/mutations:resume"), {
69
+ operationId,
70
+ expectedGeneration: 2,
71
+ }),
72
+ ).toMatchObject({ coverage: "unknown", observation: { status: "held" } });
73
+ });
74
+ it("rejects a later foreign-source transfer alias despite an unchanged original marker", async () => {
75
+ const { t, operationId } = await setup();
76
+ await t.run((ctx) =>
77
+ ctx.db.insert("transfers", {
78
+ stripeTransferId: "tr_provenance",
79
+ sourceChargeId: "ch_foreign",
80
+ destinationAccountId: "acct_other",
81
+ amount: 10,
82
+ currency: "usd",
83
+ role: "store",
84
+ status: "paid",
85
+ }),
86
+ );
87
+ await t.mutation(m("reversalObservations/mutations:resume"), {
88
+ operationId,
89
+ expectedGeneration: 1,
90
+ });
91
+ const page = await t.query(q("slices"), {
92
+ operationId,
93
+ paginationOpts: { numItems: 10, cursor: null },
94
+ });
95
+ expect(page.page[0]).toMatchObject({
96
+ identityStatus: "contradictory",
97
+ ownershipStatus: "unknown",
98
+ originalOperationId: operationId,
99
+ });
100
+ });
101
+ it("exposes late transfer receipts through a new diagnostic generation without rewriting original claims", async () => {
102
+ const { t, args, operationId } = await setup();
103
+ const before = await t.query(q("operation"), { operationId });
104
+ await t.mutation(m("connect/mutations:recordTransferReversal"), {
105
+ stripeTransferId: "tr_provenance",
106
+ reversedAmount: 1,
107
+ });
108
+ const after = await t.query(q("operation"), { operationId });
109
+ expect(after.observation).toEqual(before.observation);
110
+ expect(after.transferGeneration).toBeGreaterThan(before.transferGeneration);
111
+ const replay = await t.mutation(
112
+ m("connect/mutations:claimReversalSlices"),
113
+ args,
114
+ );
115
+ expect(replay).toMatchObject({ replay: true, slices: [{ confirmed: 1 }] });
116
+ });
117
+ it("holds a deleted previously indexed slot during a new generation without inflating counts", async () => {
118
+ const { t, args, operationId } = await setup();
119
+ await t.mutation(m("reversalObservations/mutations:resume"), {
120
+ operationId,
121
+ expectedGeneration: 1,
122
+ });
123
+ await t.mutation(m("reversalObservations/mutations:resume"), {
124
+ operationId,
125
+ expectedGeneration: 1,
126
+ });
127
+ await t.mutation(m("connect/mutations:claimReversalSlices"), {
128
+ ...args,
129
+ commissionExposure: { ...args.commissionExposure, finalized: true },
130
+ });
131
+ await t.run(async (ctx) => {
132
+ const row = await ctx.db.query("reversalObservationSlices").first();
133
+ await ctx.db.delete("reversalObservationSlices", row!._id);
134
+ });
135
+ expect(
136
+ await t.mutation(m("reversalObservations/mutations:resume"), {
137
+ operationId,
138
+ expectedGeneration: 2,
139
+ }),
140
+ ).toMatchObject({
141
+ coverage: "unknown",
142
+ observation: { status: "held", indexedCount: 1, sliceCount: 1 },
143
+ });
144
+ });
145
+ it.each([false, true])(
146
+ "holds a corrupted frozen destination digest with missing source=%s",
147
+ async (missing) => {
148
+ const { t, operationId } = await setup();
149
+ await t.run(async (ctx) => {
150
+ const chunk = (await ctx.db.query("reversalObservationRefs").first())!;
151
+ const original = chunk.refs[0]!;
152
+ await ctx.db.patch("reversalObservationRefs", chunk._id, {
153
+ refs: [{ ...original, bucketDigest: "f".repeat(64) }],
154
+ });
155
+ if (missing) await ctx.db.delete("transfers", original.transferId);
156
+ });
157
+ expect(
158
+ await t.mutation(m("reversalObservations/mutations:resume"), {
159
+ operationId,
160
+ expectedGeneration: 1,
161
+ }),
162
+ ).toMatchObject({
163
+ coverage: "unknown",
164
+ observation: { status: "held", indexedCount: 0 },
165
+ });
166
+ },
167
+ );
@@ -0,0 +1,121 @@
1
+ import { paginator } from "convex-helpers/server/pagination";
2
+ import schema from "../schema.js";
3
+ import { validPayload } from "./integrity.js";
4
+ import { v } from "convex/values";
5
+ import { query } from "../_generated/server.js";
6
+ import { operationResult } from "./schema.js";
7
+ import { header, readState } from "./state.js";
8
+ export const operation = query({
9
+ args: { operationId: v.id("transferReversalOps") },
10
+ returns: operationResult,
11
+ handler: async (ctx, { operationId }) => ({
12
+ ...(await readState(ctx)),
13
+ observation: await header(ctx, operationId),
14
+ }),
15
+ });
16
+
17
+ import { paginationOptsValidator } from "convex/server";
18
+ import { headerDoc, sliceDoc, payloadDoc } from "./schema.js";
19
+ import { boundedPage, pageResult, readFields } from "./pagination.js";
20
+ import { bucketDigest, ownerDigest } from "./selectors.js";
21
+ import { selectorDigest } from "../operationEvidence/helpers.js";
22
+ export const slices = query({
23
+ args: {
24
+ operationId: v.id("transferReversalOps"),
25
+ paginationOpts: paginationOptsValidator,
26
+ },
27
+ returns: pageResult(sliceDoc),
28
+ handler: async (ctx, { operationId, paginationOpts }) => {
29
+ const options = boundedPage(paginationOpts);
30
+ const row = await header(ctx, operationId);
31
+ if (!row)
32
+ return {
33
+ ...(await readState(ctx)),
34
+ page: [],
35
+ isDone: true,
36
+ continueCursor: "",
37
+ };
38
+ return {
39
+ ...(await readState(ctx)),
40
+ ...(await paginator(ctx.db, schema)
41
+ .query("reversalObservationSlices")
42
+ .withIndex("by_observation_slice", (q) =>
43
+ q.eq("observationId", row._id),
44
+ )
45
+ .paginate(options)),
46
+ };
47
+ },
48
+ });
49
+ export const bucket = query({
50
+ args: { bucketKey: v.string(), paginationOpts: paginationOptsValidator },
51
+ returns: pageResult(sliceDoc),
52
+ handler: async (ctx, { bucketKey, paginationOpts }) => {
53
+ const digest = await bucketDigest(bucketKey);
54
+ return {
55
+ ...(await readState(ctx)),
56
+ ...(await paginator(ctx.db, schema)
57
+ .query("reversalObservationSlices")
58
+ .withIndex("by_bucket", (q) => q.eq("bucketDigest", digest))
59
+ .paginate(boundedPage(paginationOpts))),
60
+ };
61
+ },
62
+ });
63
+ export const owner = query({
64
+ args: {
65
+ userId: v.string(),
66
+ orgId: v.optional(v.string()),
67
+ paginationOpts: paginationOptsValidator,
68
+ },
69
+ returns: pageResult(sliceDoc),
70
+ handler: async (ctx, { userId, orgId, paginationOpts }) => {
71
+ const digest = await ownerDigest(userId, orgId);
72
+ return {
73
+ ...(await readState(ctx)),
74
+ ...(await paginator(ctx.db, schema)
75
+ .query("reversalObservationSlices")
76
+ .withIndex("by_owner", (q) => q.eq("ownerDigest", digest))
77
+ .paginate(boundedPage(paginationOpts))),
78
+ };
79
+ },
80
+ });
81
+ export const history = query({
82
+ args: {
83
+ selector: v.union(v.literal("operationId"), v.literal("sourceChargeId")),
84
+ value: v.string(),
85
+ paginationOpts: paginationOptsValidator,
86
+ },
87
+ returns: pageResult(headerDoc),
88
+ handler: async (ctx, { selector, value, paginationOpts }) => {
89
+ const digest = await selectorDigest(selector, value);
90
+ const rows =
91
+ selector === "operationId"
92
+ ? paginator(ctx.db, schema)
93
+ .query("reversalObservations")
94
+ .withIndex("by_operation_digest", (q) =>
95
+ q.eq("operationDigest", digest),
96
+ )
97
+ : paginator(ctx.db, schema)
98
+ .query("reversalObservations")
99
+ .withIndex("by_source_charge_digest", (q) =>
100
+ q.eq("sourceChargeDigest", digest),
101
+ );
102
+ return {
103
+ ...(await readState(ctx)),
104
+ ...(await rows.paginate(boundedPage(paginationOpts))),
105
+ };
106
+ },
107
+ });
108
+ export const payload = query({
109
+ args: {
110
+ operationId: v.id("transferReversalOps"),
111
+ version: v.union(v.literal("original"), v.literal("latest")),
112
+ },
113
+ returns: v.object({ ...readFields, payload: v.union(payloadDoc, v.null()) }),
114
+ handler: async (ctx, { operationId, version }) => {
115
+ const row = await header(ctx, operationId);
116
+ return {
117
+ ...(await readState(ctx)),
118
+ payload: row ? await validPayload(ctx, row, version) : null,
119
+ };
120
+ },
121
+ });
@@ -0,0 +1,134 @@
1
+ import { paginator } from "convex-helpers/server/pagination";
2
+ import schema from "../schema.js";
3
+ import type { Doc, Id } from "../_generated/dataModel.js";
4
+ import type { MutationCtx } from "../_generated/server.js";
5
+ import type { Infer } from "convex/values";
6
+ import type { ref } from "./schema.js";
7
+ import {
8
+ transferFingerprint,
9
+ transferIdentity,
10
+ } from "../financialObservations/transferHelpers.js";
11
+ import { bucketDigest, ownerDigest } from "./selectors.js";
12
+ export const referenceChunkSize = 64;
13
+
14
+ /** Only pure derived values are memoized; no source read or financial callback is bypassed. */
15
+ export async function reversalReferences(
16
+ ctx: MutationCtx,
17
+ op: Doc<"transferReversalOps">,
18
+ rows: Doc<"transfers">[],
19
+ ) {
20
+ if (op.slices.length === 0) return [];
21
+ const selected = new Map(rows.map((row) => [row.stripeTransferId, row]));
22
+ const counts = new Map<string, number>();
23
+ for (const row of rows)
24
+ counts.set(
25
+ row.stripeTransferId,
26
+ (counts.get(row.stripeTransferId) ?? 0) + 1,
27
+ );
28
+ const budget = await ctx.meta.getTransactionMetrics();
29
+ const page =
30
+ budget.bytesRead.remaining > 2_500_000 &&
31
+ budget.databaseQueries.remaining > 10
32
+ ? await paginator(ctx.db, schema)
33
+ .query("financialTransferObservations")
34
+ .withIndex("by_source_charge_id", (q) =>
35
+ q.eq("sourceChargeId", op.sourceChargeId),
36
+ )
37
+ .paginate({
38
+ numItems: 1001,
39
+ cursor: null,
40
+ maximumRowsRead: 1001,
41
+ maximumBytesRead: 262144,
42
+ })
43
+ : { page: [] };
44
+ const markers = new Map<
45
+ Id<"transfers">,
46
+ Doc<"financialTransferObservations"> | null
47
+ >();
48
+ for (const marker of page.page)
49
+ markers.set(
50
+ marker.transferId,
51
+ markers.has(marker.transferId) ? null : marker,
52
+ );
53
+ const buckets = new Map<string, Promise<string>>();
54
+ const owners = new Map<string, Promise<string>>();
55
+ const identities = new Map<Id<"transfers">, Promise<string>>();
56
+ const digestFor = (
57
+ key: string,
58
+ cache: Map<string, Promise<string>>,
59
+ calculate: () => Promise<string>,
60
+ ) => {
61
+ let value = cache.get(key);
62
+ if (!value) {
63
+ value = calculate();
64
+ cache.set(key, value);
65
+ }
66
+ return value;
67
+ };
68
+ const capture = async (
69
+ slice: Doc<"transferReversalOps">["slices"][number],
70
+ ): Promise<Infer<typeof ref> | null> => {
71
+ const row = selected.get(slice.stripeTransferId);
72
+ if (!row) return null;
73
+ let identity = identities.get(row._id);
74
+ if (!identity) {
75
+ identity = transferFingerprint(transferIdentity(row));
76
+ identities.set(row._id, identity);
77
+ }
78
+ const [identityFingerprint, bucket] = await Promise.all([
79
+ identity,
80
+ digestFor(row.destinationAccountId, buckets, () =>
81
+ bucketDigest(row.destinationAccountId),
82
+ ),
83
+ ]);
84
+ const marker = markers.get(row._id);
85
+ const usable =
86
+ marker &&
87
+ /^[a-f0-9]{32}$/.test(marker.ownershipFingerprint) &&
88
+ !marker.isContradictory &&
89
+ marker.fingerprint === identityFingerprint &&
90
+ marker.stripeTransferId === slice.stripeTransferId &&
91
+ marker.sourceChargeId === op.sourceChargeId &&
92
+ marker.bucketKey === row.destinationAccountId &&
93
+ marker.role === row.role &&
94
+ Number.isSafeInteger(marker.generation) &&
95
+ marker.generation >= 1;
96
+ const owner =
97
+ usable &&
98
+ marker.registrationId &&
99
+ marker.ownershipStatus === "registered" &&
100
+ marker.userId !== undefined
101
+ ? await digestFor(
102
+ JSON.stringify([marker.userId, marker.orgId]),
103
+ owners,
104
+ () => ownerDigest(marker.userId!, marker.orgId),
105
+ )
106
+ : undefined;
107
+ return {
108
+ transferId: row._id,
109
+ identityFingerprint,
110
+ bucketDigest: bucket,
111
+ ...(owner ? { ownerDigest: owner } : {}),
112
+ ambiguous: counts.get(slice.stripeTransferId) !== 1,
113
+ ...(usable
114
+ ? {
115
+ markerId: marker._id,
116
+ markerGeneration: marker.generation,
117
+ markerIdentityFingerprint: marker.fingerprint,
118
+ ownershipFingerprint: marker.ownershipFingerprint,
119
+ ...(marker.registrationId && marker.ownershipStatus === "registered"
120
+ ? { registrationId: marker.registrationId }
121
+ : {}),
122
+ }
123
+ : {}),
124
+ };
125
+ };
126
+ const result: (Infer<typeof ref> | null)[] = [];
127
+ for (let start = 0; start < op.slices.length; start += referenceChunkSize)
128
+ result.push(
129
+ ...(await Promise.all(
130
+ op.slices.slice(start, start + referenceChunkSize).map(capture),
131
+ )),
132
+ );
133
+ return result;
134
+ }