@fantastic.dev/better-stripe 0.37.1 → 0.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/MIGRATION.md +9 -0
  3. package/README.md +25 -1
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +506 -2
  5. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +253 -1
  7. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +506 -2
  9. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts +253 -1
  11. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  12. package/dist/client/core/accountCapabilities.d.ts +20 -0
  13. package/dist/client/core/accountCapabilities.d.ts.map +1 -0
  14. package/dist/client/core/accountCapabilities.js +7 -0
  15. package/dist/client/core/accountCapabilities.js.map +1 -0
  16. package/dist/client/core/accountConfigurations.d.ts +46 -0
  17. package/dist/client/core/accountConfigurations.d.ts.map +1 -0
  18. package/dist/client/core/accountConfigurations.js +99 -0
  19. package/dist/client/core/accountConfigurations.js.map +1 -0
  20. package/dist/client/core/accountLinks.d.ts +29 -2
  21. package/dist/client/core/accountLinks.d.ts.map +1 -1
  22. package/dist/client/core/accountLinks.js +56 -4
  23. package/dist/client/core/accountLinks.js.map +1 -1
  24. package/dist/client/core/accounts.d.ts +2 -36
  25. package/dist/client/core/accounts.d.ts.map +1 -1
  26. package/dist/client/core/accounts.js +3 -73
  27. package/dist/client/core/accounts.js.map +1 -1
  28. package/dist/client/core/billingPortalClient.d.ts +14 -0
  29. package/dist/client/core/billingPortalClient.d.ts.map +1 -0
  30. package/dist/client/core/billingPortalClient.js +18 -0
  31. package/dist/client/core/billingPortalClient.js.map +1 -0
  32. package/dist/client/costRecovery-invoices.d.ts +4 -4
  33. package/dist/client/costRecovery.d.ts +19 -1
  34. package/dist/client/costRecovery.d.ts.map +1 -1
  35. package/dist/client/costRecovery.js +4 -0
  36. package/dist/client/costRecovery.js.map +1 -1
  37. package/dist/client/financialOutcomes/adapters.d.ts +18 -0
  38. package/dist/client/financialOutcomes/adapters.d.ts.map +1 -0
  39. package/dist/client/financialOutcomes/adapters.js +60 -0
  40. package/dist/client/financialOutcomes/adapters.js.map +1 -0
  41. package/dist/client/financialOutcomes/contracts.d.ts +42 -0
  42. package/dist/client/financialOutcomes/contracts.d.ts.map +1 -0
  43. package/dist/client/financialOutcomes/contracts.js +39 -0
  44. package/dist/client/financialOutcomes/contracts.js.map +1 -0
  45. package/dist/client/financialOutcomes/errors.d.ts +6 -0
  46. package/dist/client/financialOutcomes/errors.d.ts.map +1 -0
  47. package/dist/client/financialOutcomes/errors.js +22 -0
  48. package/dist/client/financialOutcomes/errors.js.map +1 -0
  49. package/dist/client/financialOutcomes/index.d.ts +6 -0
  50. package/dist/client/financialOutcomes/index.d.ts.map +1 -0
  51. package/dist/client/financialOutcomes/index.js +4 -0
  52. package/dist/client/financialOutcomes/index.js.map +1 -0
  53. package/dist/client/financialOutcomes/retry.d.ts +24 -0
  54. package/dist/client/financialOutcomes/retry.d.ts.map +1 -0
  55. package/dist/client/financialOutcomes/retry.js +31 -0
  56. package/dist/client/financialOutcomes/retry.js.map +1 -0
  57. package/dist/client/index.d.ts +21 -111
  58. package/dist/client/index.d.ts.map +1 -1
  59. package/dist/client/index.js +11 -85
  60. package/dist/client/index.js.map +1 -1
  61. package/dist/client/processingCostDeficit/index.d.ts +27 -0
  62. package/dist/client/processingCostDeficit/index.d.ts.map +1 -0
  63. package/dist/client/processingCostDeficit/index.js +54 -0
  64. package/dist/client/processingCostDeficit/index.js.map +1 -0
  65. package/dist/client/products/catalog.d.ts +26 -0
  66. package/dist/client/products/catalog.d.ts.map +1 -0
  67. package/dist/client/products/catalog.js +140 -0
  68. package/dist/client/products/catalog.js.map +1 -0
  69. package/dist/client/products/catalogClient.d.ts +109 -0
  70. package/dist/client/products/catalogClient.d.ts.map +1 -0
  71. package/dist/client/products/catalogClient.js +84 -0
  72. package/dist/client/products/catalogClient.js.map +1 -0
  73. package/dist/client/products/prices.d.ts +1 -0
  74. package/dist/client/products/prices.d.ts.map +1 -1
  75. package/dist/client/products/prices.js +1 -0
  76. package/dist/client/products/prices.js.map +1 -1
  77. package/dist/client/publicTypes.d.ts +2 -0
  78. package/dist/client/publicTypes.d.ts.map +1 -1
  79. package/dist/component/_generated/api.d.ts +284 -0
  80. package/dist/component/_generated/api.d.ts.map +1 -0
  81. package/dist/component/_generated/api.js +31 -0
  82. package/dist/component/_generated/api.js.map +1 -0
  83. package/dist/component/_generated/component.d.ts +535 -0
  84. package/dist/component/_generated/component.d.ts.map +1 -1
  85. package/dist/component/balanceFunding/helpers.d.ts +86 -0
  86. package/dist/component/balanceFunding/helpers.d.ts.map +1 -0
  87. package/dist/component/balanceFunding/helpers.js +68 -0
  88. package/dist/component/balanceFunding/helpers.js.map +1 -0
  89. package/dist/component/balanceFunding/importHandler.d.ts +13 -0
  90. package/dist/component/balanceFunding/importHandler.d.ts.map +1 -0
  91. package/dist/component/balanceFunding/importHandler.js +130 -0
  92. package/dist/component/balanceFunding/importHandler.js.map +1 -0
  93. package/dist/component/balanceFunding/lifecycleHandlers.d.ts +85 -0
  94. package/dist/component/balanceFunding/lifecycleHandlers.d.ts.map +1 -0
  95. package/dist/component/balanceFunding/lifecycleHandlers.js +60 -0
  96. package/dist/component/balanceFunding/lifecycleHandlers.js.map +1 -0
  97. package/dist/component/balanceFunding/mutationValidators.d.ts +238 -0
  98. package/dist/component/balanceFunding/mutationValidators.d.ts.map +1 -0
  99. package/dist/component/balanceFunding/mutationValidators.js +55 -0
  100. package/dist/component/balanceFunding/mutationValidators.js.map +1 -0
  101. package/dist/component/balanceFunding/mutations.d.ts +335 -0
  102. package/dist/component/balanceFunding/mutations.d.ts.map +1 -0
  103. package/dist/component/balanceFunding/mutations.js +106 -0
  104. package/dist/component/balanceFunding/mutations.js.map +1 -0
  105. package/dist/component/balanceFunding/preparationHandlers.d.ts +55 -0
  106. package/dist/component/balanceFunding/preparationHandlers.d.ts.map +1 -0
  107. package/dist/component/balanceFunding/preparationHandlers.js +165 -0
  108. package/dist/component/balanceFunding/preparationHandlers.js.map +1 -0
  109. package/dist/component/balanceFunding/queries.d.ts +151 -0
  110. package/dist/component/balanceFunding/queries.d.ts.map +1 -0
  111. package/dist/component/balanceFunding/queries.js +180 -0
  112. package/dist/component/balanceFunding/queries.js.map +1 -0
  113. package/dist/component/balanceFunding/schema.d.ts +748 -0
  114. package/dist/component/balanceFunding/schema.d.ts.map +1 -0
  115. package/dist/component/balanceFunding/schema.js +124 -0
  116. package/dist/component/balanceFunding/schema.js.map +1 -0
  117. package/dist/component/balanceFunding/stateHandlers.d.ts +58 -0
  118. package/dist/component/balanceFunding/stateHandlers.d.ts.map +1 -0
  119. package/dist/component/balanceFunding/stateHandlers.js +160 -0
  120. package/dist/component/balanceFunding/stateHandlers.js.map +1 -0
  121. package/dist/component/convex.config.d.ts.map +1 -1
  122. package/dist/component/convex.config.js +2 -0
  123. package/dist/component/convex.config.js.map +1 -1
  124. package/dist/component/costRecovery/completion.d.ts +1 -0
  125. package/dist/component/costRecovery/completion.d.ts.map +1 -1
  126. package/dist/component/costRecovery/helpers.d.ts +1 -0
  127. package/dist/component/costRecovery/helpers.d.ts.map +1 -1
  128. package/dist/component/costRecovery/mutations.d.ts +5 -0
  129. package/dist/component/costRecovery/mutations.d.ts.map +1 -1
  130. package/dist/component/costRecovery/preparation.d.ts +50 -0
  131. package/dist/component/costRecovery/preparation.d.ts.map +1 -0
  132. package/dist/component/costRecovery/preparation.js +108 -0
  133. package/dist/component/costRecovery/preparation.js.map +1 -0
  134. package/dist/component/costRecovery/queries.d.ts +1 -0
  135. package/dist/component/costRecovery/queries.d.ts.map +1 -1
  136. package/dist/component/costRecovery/reservations.d.ts +2 -0
  137. package/dist/component/costRecovery/reservations.d.ts.map +1 -1
  138. package/dist/component/costRecovery/schema.d.ts +7 -2
  139. package/dist/component/costRecovery/schema.d.ts.map +1 -1
  140. package/dist/component/costRecovery/schema.js +1 -0
  141. package/dist/component/costRecovery/schema.js.map +1 -1
  142. package/dist/component/durableExecution/runtime.d.ts +3 -0
  143. package/dist/component/durableExecution/runtime.d.ts.map +1 -0
  144. package/dist/component/durableExecution/runtime.js +12 -0
  145. package/dist/component/durableExecution/runtime.js.map +1 -0
  146. package/dist/component/earnings/triggers.d.ts +242 -2
  147. package/dist/component/earnings/triggers.d.ts.map +1 -1
  148. package/dist/component/products/mutations.d.ts +9 -0
  149. package/dist/component/products/mutations.d.ts.map +1 -1
  150. package/dist/component/products/mutations.js +31 -2
  151. package/dist/component/products/mutations.js.map +1 -1
  152. package/dist/component/schema.d.ts +253 -1
  153. package/dist/component/schema.js +4 -0
  154. package/dist/component/schema.js.map +1 -1
  155. package/docs/read-contracts.md +33 -0
  156. package/package.json +4 -2
  157. package/src/client/core/account-session-client.test.ts +74 -0
  158. package/src/client/core/accountCapabilities.ts +22 -0
  159. package/src/client/core/accountConfigurations.test.ts +183 -0
  160. package/src/client/core/accountConfigurations.ts +161 -0
  161. package/src/client/core/accountLinks.test.ts +6 -2
  162. package/src/client/core/accountLinks.ts +122 -5
  163. package/src/client/core/accounts.ts +8 -115
  164. package/src/client/core/billingPortal.test.ts +247 -0
  165. package/src/client/core/billingPortalClient.ts +35 -0
  166. package/src/client/costRecovery.test.ts +34 -0
  167. package/src/client/costRecovery.ts +21 -0
  168. package/src/client/financialOutcomes/adapters.ts +88 -0
  169. package/src/client/financialOutcomes/contracts.ts +43 -0
  170. package/src/client/financialOutcomes/errors.ts +29 -0
  171. package/src/client/financialOutcomes/index.ts +5 -0
  172. package/src/client/financialOutcomes/outcomes.test.ts +254 -0
  173. package/src/client/financialOutcomes/retry.ts +52 -0
  174. package/src/client/index.test.ts +0 -64
  175. package/src/client/index.ts +35 -185
  176. package/src/client/processingCostDeficit/README.md +35 -0
  177. package/src/client/processingCostDeficit/calculator.test.ts +176 -0
  178. package/src/client/processingCostDeficit/index.ts +91 -0
  179. package/src/client/products/catalog.test.ts +389 -0
  180. package/src/client/products/catalog.ts +225 -0
  181. package/src/client/products/catalogClient.ts +172 -0
  182. package/src/client/products/prices.test.ts +24 -0
  183. package/src/client/products/prices.ts +2 -0
  184. package/src/client/publicTypes.ts +13 -0
  185. package/src/component/_generated/api.ts +27 -1
  186. package/src/component/_generated/component.ts +707 -0
  187. package/src/component/balanceFunding/failure.test.ts +116 -0
  188. package/src/component/balanceFunding/helpers.ts +102 -0
  189. package/src/component/balanceFunding/import.test.ts +221 -0
  190. package/src/component/balanceFunding/importHandler.ts +146 -0
  191. package/src/component/balanceFunding/lifecycleHandlers.ts +90 -0
  192. package/src/component/balanceFunding/lookup.test.ts +113 -0
  193. package/src/component/balanceFunding/mutationValidators.ts +63 -0
  194. package/src/component/balanceFunding/mutations.ts +136 -0
  195. package/src/component/balanceFunding/preparation.test.ts +146 -0
  196. package/src/component/balanceFunding/preparationHandlers.ts +204 -0
  197. package/src/component/balanceFunding/queries.ts +221 -0
  198. package/src/component/balanceFunding/requestLookup.test.ts +160 -0
  199. package/src/component/balanceFunding/schema.ts +169 -0
  200. package/src/component/balanceFunding/state.test.ts +352 -0
  201. package/src/component/balanceFunding/stateHandlers.ts +198 -0
  202. package/src/component/balanceFunding/validation.test.ts +100 -0
  203. package/src/component/convex.config.ts +2 -0
  204. package/src/component/costRecovery/preparation.test.ts +355 -0
  205. package/src/component/costRecovery/preparation.ts +124 -0
  206. package/src/component/costRecovery/schema.ts +1 -0
  207. package/src/component/durableExecution/composition.test.ts +568 -0
  208. package/src/component/durableExecution/runtime.ts +12 -0
  209. package/src/component/products/mutations.ts +39 -2
  210. package/src/component/schema.ts +8 -0
@@ -0,0 +1,221 @@
1
+ import { v } from "convex/values";
2
+ import { query } from "../_generated/server.js";
3
+ import {
4
+ scopeFields,
5
+ preparationDoc,
6
+ operationDoc,
7
+ operationRefFields,
8
+ safeStatus,
9
+ preparationLookup,
10
+ conflict,
11
+ invalidScope,
12
+ } from "./schema.js";
13
+ import {
14
+ readPreparation as readSavedPreparation,
15
+ readOperation,
16
+ ref,
17
+ unavailable,
18
+ validateScope,
19
+ integer,
20
+ text,
21
+ same,
22
+ } from "./helpers.js";
23
+ const lookupArgs = { ...operationRefFields, stripeSubscriptionId: v.string() };
24
+ /** Server-only provider execution reader. Never expose restoration data to browsers. */
25
+ export const readPreparation = query({
26
+ args: {
27
+ ...scopeFields,
28
+ preparationId: v.id("balanceFundingPreparations"),
29
+ stripeSubscriptionId: v.string(),
30
+ },
31
+ returns: v.union(preparationDoc, v.null()),
32
+ handler: async (ctx, args) => {
33
+ const saved = await readSavedPreparation(ctx, args);
34
+ if (
35
+ saved &&
36
+ saved.preparation.stripeSubscriptionId !== args.stripeSubscriptionId
37
+ )
38
+ throw new Error("Preparation subscription identity does not match.");
39
+ return saved;
40
+ },
41
+ });
42
+ /** Server-only provider action reader; require all saved identity bindings. */
43
+ export const inspectOperation = query({
44
+ args: lookupArgs,
45
+ returns: v.union(operationDoc, v.null()),
46
+ handler: async (ctx, args) => {
47
+ const operation = await readOperation(ctx, args);
48
+ if (!operation) return null;
49
+ const preparation = await ctx.db.get(
50
+ "balanceFundingPreparations",
51
+ operation.preparationId,
52
+ );
53
+ if (
54
+ !preparation ||
55
+ preparation.accountId !== args.accountId ||
56
+ preparation.scopeKey !== args.scopeKey ||
57
+ preparation.preparation.stripeSubscriptionId !== args.stripeSubscriptionId
58
+ )
59
+ throw new Error("Operation subscription identity does not match.");
60
+ return operation;
61
+ },
62
+ });
63
+ /** Safe operation state, without provider keys, receipts or restoration settings. */
64
+ export const getOperation = query({
65
+ args: lookupArgs,
66
+ returns: v.union(safeStatus, v.null()),
67
+ handler: async (ctx, args) => {
68
+ const operation = await readOperation(ctx, args);
69
+ if (!operation) return null;
70
+ const preparation = await ctx.db.get(
71
+ "balanceFundingPreparations",
72
+ operation.preparationId,
73
+ );
74
+ if (
75
+ !preparation ||
76
+ preparation.accountId !== args.accountId ||
77
+ preparation.scopeKey !== args.scopeKey ||
78
+ preparation.preparation.stripeSubscriptionId !== args.stripeSubscriptionId
79
+ )
80
+ throw new Error("Operation subscription identity does not match.");
81
+ return {
82
+ ...ref(operation),
83
+ state: operation.state,
84
+ cancelRequested: operation.cancelRequested,
85
+ ...(operation.failureCode ? { failureCode: operation.failureCode } : {}),
86
+ };
87
+ },
88
+ });
89
+ /** A missing or unverified result never authorizes another provider effect. */
90
+ export const getPreparation = query({
91
+ args: lookupArgs,
92
+ returns: preparationLookup,
93
+ handler: async (ctx, args) => {
94
+ try {
95
+ validateScope(args);
96
+ integer(args.version, 1);
97
+ if (!args.stripeSubscriptionId.trim())
98
+ throw new Error("Invalid subscription");
99
+ } catch {
100
+ return {
101
+ status: "rejected" as const,
102
+ reason: "invalid_scope" as const,
103
+ retryable: false as const,
104
+ };
105
+ }
106
+ const operation = await ctx.db.get(
107
+ "balanceFundingOperations",
108
+ args.operationId,
109
+ );
110
+ if (!operation) return null;
111
+ const saved = await ctx.db.get(
112
+ "balanceFundingPreparations",
113
+ operation.preparationId,
114
+ );
115
+ if (
116
+ !saved ||
117
+ saved.accountId !== args.accountId ||
118
+ saved.scopeKey !== args.scopeKey ||
119
+ operation.kind !== "prepare" ||
120
+ operation.accountId !== args.accountId ||
121
+ operation.scopeKey !== args.scopeKey ||
122
+ operation.version !== args.version ||
123
+ saved.preparation.stripeSubscriptionId !== args.stripeSubscriptionId
124
+ )
125
+ return unavailable("identity_changed");
126
+ if (operation.state === "succeeded") {
127
+ if (!saved.verified || !saved.preparation.paymentMethodId)
128
+ return unavailable("identity_changed");
129
+ return {
130
+ status: "prepared" as const,
131
+ operation: ref(operation),
132
+ stripeSubscriptionId: args.stripeSubscriptionId,
133
+ preparationId: saved._id,
134
+ };
135
+ }
136
+ return {
137
+ status: operation.state,
138
+ operation: ref(operation),
139
+ ...(operation.failureCode ? { failureCode: operation.failureCode } : {}),
140
+ };
141
+ },
142
+ });
143
+ /** Recover the original public request before any provider/settings/consent recapture. */
144
+ export const findPreparationOperation = query({
145
+ args: {
146
+ ...scopeFields,
147
+ stripeSubscriptionId: v.string(),
148
+ requestKey: v.string(),
149
+ providerApiVersion: v.string(),
150
+ consent: v.boolean(),
151
+ },
152
+ returns: v.union(safeStatus, conflict, invalidScope, v.null()),
153
+ handler: async (ctx, args) => {
154
+ try {
155
+ validateScope(args);
156
+ text(args.stripeSubscriptionId);
157
+ text(args.requestKey);
158
+ text(args.providerApiVersion);
159
+ } catch {
160
+ return {
161
+ status: "rejected" as const,
162
+ reason: "invalid_scope" as const,
163
+ retryable: false as const,
164
+ };
165
+ }
166
+ if (args.consent !== true) return unavailable("identity_changed");
167
+ const request = await ctx.db
168
+ .query("balanceFundingRequests")
169
+ .withIndex("by_request", (q) => q.eq("requestKey", args.requestKey))
170
+ .unique();
171
+ if (!request) return null;
172
+ if (request.result?.status !== "accepted")
173
+ return unavailable("identity_changed");
174
+ const operation = await ctx.db.get(
175
+ "balanceFundingOperations",
176
+ request.result.operation.operationId,
177
+ );
178
+ if (
179
+ !operation ||
180
+ operation.kind !== "prepare" ||
181
+ operation.accountId !== args.accountId ||
182
+ operation.scopeKey !== args.scopeKey ||
183
+ !same(ref(operation), request.result.operation) ||
184
+ request.preparationId !== operation.preparationId
185
+ )
186
+ return unavailable("identity_changed");
187
+ const saved = await ctx.db.get(
188
+ "balanceFundingPreparations",
189
+ operation.preparationId,
190
+ );
191
+ if (
192
+ !saved ||
193
+ saved.accountId !== args.accountId ||
194
+ saved.scopeKey !== args.scopeKey ||
195
+ saved.preparation.stripeSubscriptionId !== args.stripeSubscriptionId ||
196
+ saved.providerApiVersion !== args.providerApiVersion
197
+ )
198
+ return unavailable("identity_changed");
199
+ try {
200
+ const snapshot = JSON.parse(request.payload);
201
+ if (
202
+ snapshot.consent !== true ||
203
+ snapshot.accountId !== args.accountId ||
204
+ snapshot.scopeKey !== args.scopeKey ||
205
+ snapshot.requestKey !== args.requestKey ||
206
+ snapshot.providerApiVersion !== args.providerApiVersion ||
207
+ snapshot.preparation?.customerAccount !== args.accountId ||
208
+ snapshot.preparation?.stripeSubscriptionId !== args.stripeSubscriptionId
209
+ )
210
+ return unavailable("identity_changed");
211
+ } catch {
212
+ return unavailable("identity_changed");
213
+ }
214
+ return {
215
+ ...ref(operation),
216
+ state: operation.state,
217
+ cancelRequested: operation.cancelRequested,
218
+ ...(operation.failureCode ? { failureCode: operation.failureCode } : {}),
219
+ };
220
+ },
221
+ });
@@ -0,0 +1,160 @@
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) =>
7
+ makeFunctionReference<"mutation">(`balanceFunding/mutations:${name}`);
8
+ const q = (name: string) =>
9
+ makeFunctionReference<"query">(`balanceFunding/queries:${name}`);
10
+ const scope = { accountId: "acct_recover", scopeKey: "recover" };
11
+ const original = {
12
+ customerAccount: scope.accountId,
13
+ stripeSubscriptionId: "sub_recover",
14
+ previousPaymentMethodId: "pm_original",
15
+ previousPaymentMethodTypes: ["card"],
16
+ };
17
+ const prepare = {
18
+ ...scope,
19
+ preparation: original,
20
+ consent: true,
21
+ consentAt: 10,
22
+ consentReference: "consent",
23
+ providerApiVersion: "preview",
24
+ requestKey: "recover-request",
25
+ };
26
+ const lookup = {
27
+ ...scope,
28
+ stripeSubscriptionId: "sub_recover",
29
+ requestKey: prepare.requestKey,
30
+ providerApiVersion: "preview",
31
+ consent: true,
32
+ };
33
+ it("recovers a lost prepare response from the original public request without recapturing settings or time", async () => {
34
+ const t = convexTest(schema, modules);
35
+ await t.mutation(m("prepare"), prepare);
36
+ const found = await t.query(q("findPreparationOperation"), lookup);
37
+ expect(found.state).toBe("pending");
38
+ expect(Object.keys(found).sort()).toEqual([
39
+ "accountId",
40
+ "cancelRequested",
41
+ "operationId",
42
+ "scopeKey",
43
+ "state",
44
+ "version",
45
+ ]);
46
+ const operation = {
47
+ accountId: found.accountId,
48
+ scopeKey: found.scopeKey,
49
+ operationId: found.operationId,
50
+ version: found.version,
51
+ };
52
+ await t.mutation(m("finishPreparation"), {
53
+ ...operation,
54
+ preparation: { ...original, paymentMethodId: "pm_balance" },
55
+ providerApiVersion: "preview",
56
+ });
57
+ expect((await t.query(q("findPreparationOperation"), lookup)).state).toBe(
58
+ "succeeded",
59
+ );
60
+ expect(
61
+ (
62
+ await t.query(q("getPreparation"), {
63
+ ...operation,
64
+ stripeSubscriptionId: "sub_recover",
65
+ })
66
+ ).status,
67
+ ).toBe("prepared");
68
+ await expect(
69
+ t.mutation(m("prepare"), { ...prepare, consentAt: 11 }),
70
+ ).resolves.toEqual({
71
+ status: "conflict",
72
+ reason: "identity_changed",
73
+ retryable: false,
74
+ });
75
+ });
76
+ it("returns null for missing requests and conflicts for changed scope, subscription, API version or consent", async () => {
77
+ const t = convexTest(schema, modules);
78
+ expect(await t.query(q("findPreparationOperation"), lookup)).toBeNull();
79
+ await t.mutation(m("prepare"), prepare);
80
+ for (const args of [
81
+ { ...lookup, accountId: "foreign" },
82
+ { ...lookup, scopeKey: "foreign" },
83
+ { ...lookup, stripeSubscriptionId: "foreign" },
84
+ { ...lookup, providerApiVersion: "changed" },
85
+ { ...lookup, consent: false },
86
+ ])
87
+ expect(await t.query(q("findPreparationOperation"), args)).toEqual({
88
+ status: "conflict",
89
+ reason: "identity_changed",
90
+ retryable: false,
91
+ });
92
+ expect(
93
+ await t.query(q("findPreparationOperation"), { ...lookup, requestKey: "" }),
94
+ ).toEqual({ status: "rejected", reason: "invalid_scope", retryable: false });
95
+ });
96
+ it("rejects apply and foreign request identities instead of returning their operation", async () => {
97
+ const t = convexTest(schema, modules);
98
+ const first = await t.mutation(m("prepare"), prepare);
99
+ await t.mutation(m("finishPreparation"), {
100
+ ...first.operation,
101
+ preparation: { ...original, paymentMethodId: "pm_balance" },
102
+ providerApiVersion: "preview",
103
+ });
104
+ const prepared = await t.query(q("getPreparation"), {
105
+ ...first.operation,
106
+ stripeSubscriptionId: "sub_recover",
107
+ });
108
+ await t.mutation(m("begin"), {
109
+ ...scope,
110
+ preparationId: prepared.preparationId,
111
+ enabled: true,
112
+ consent: true,
113
+ requestKey: "apply-request",
114
+ });
115
+ expect(
116
+ await t.query(q("findPreparationOperation"), {
117
+ ...lookup,
118
+ requestKey: "apply-request",
119
+ }),
120
+ ).toEqual({
121
+ status: "conflict",
122
+ reason: "identity_changed",
123
+ retryable: false,
124
+ });
125
+ });
126
+ it("recovers unknown and failed intent identities without exposing restoration, keys or preparation IDs", async () => {
127
+ const t = convexTest(schema, modules);
128
+ const first = await t.mutation(m("prepare"), prepare);
129
+ await t.mutation(m("start"), first.operation);
130
+ await t.mutation(m("markUnknown"), first.operation);
131
+ const unknown = await t.query(q("findPreparationOperation"), lookup);
132
+ expect(unknown.state).toBe("unknown");
133
+ expect(unknown.operationId).toBe(first.operation.operationId);
134
+ expect(Object.keys(unknown)).not.toContain("preparationId");
135
+ const next = await t.mutation(m("prepare"), {
136
+ ...prepare,
137
+ preparation: { ...original, stripeSubscriptionId: "sub_failed" },
138
+ requestKey: "failed-request",
139
+ });
140
+ await t.mutation(m("failBeforeStart"), {
141
+ ...next.operation,
142
+ failureCode: "unsupported_source",
143
+ });
144
+ const failed = await t.query(q("findPreparationOperation"), {
145
+ ...lookup,
146
+ stripeSubscriptionId: "sub_failed",
147
+ requestKey: "failed-request",
148
+ });
149
+ expect(failed.state).toBe("failed");
150
+ expect(failed.failureCode).toBe("unsupported_source");
151
+ expect(Object.keys(failed).sort()).toEqual([
152
+ "accountId",
153
+ "cancelRequested",
154
+ "failureCode",
155
+ "operationId",
156
+ "scopeKey",
157
+ "state",
158
+ "version",
159
+ ]);
160
+ });
@@ -0,0 +1,169 @@
1
+ import { defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ export const scopeFields = { accountId: v.string(), scopeKey: v.string() };
4
+ export const originalFields = {
5
+ customerAccount: v.string(),
6
+ stripeSubscriptionId: v.string(),
7
+ previousPaymentMethodId: v.union(v.string(), v.null()),
8
+ previousPaymentMethodTypes: v.union(v.array(v.string()), v.null()),
9
+ };
10
+ export const originalValue = v.object(originalFields);
11
+ export const capturedValue = v.object({
12
+ ...originalFields,
13
+ paymentMethodId: v.optional(v.string()),
14
+ });
15
+ export const preparationValue = v.object({
16
+ ...originalFields,
17
+ paymentMethodId: v.string(),
18
+ });
19
+ export const receiptValue = v.object({
20
+ customerAccount: v.string(),
21
+ stripeSubscriptionId: v.string(),
22
+ paymentMethodId: v.union(v.string(), v.null()),
23
+ paymentMethodTypes: v.union(v.array(v.string()), v.null()),
24
+ providerApiVersion: v.string(),
25
+ });
26
+ export const preparationFields = {
27
+ ...scopeFields,
28
+ preparation: capturedValue,
29
+ consentAt: v.number(),
30
+ consentReference: v.string(),
31
+ providerApiVersion: v.string(),
32
+ enabled: v.boolean(),
33
+ startsPaused: v.boolean(),
34
+ verified: v.boolean(),
35
+ preparationOperationId: v.optional(v.id("balanceFundingOperations")),
36
+ operationVersion: v.number(),
37
+ activeOperationId: v.optional(v.id("balanceFundingOperations")),
38
+ };
39
+ export const preparationDoc = v.object({
40
+ ...preparationFields,
41
+ _id: v.id("balanceFundingPreparations"),
42
+ _creationTime: v.number(),
43
+ });
44
+ export const operationRefFields = {
45
+ ...scopeFields,
46
+ operationId: v.id("balanceFundingOperations"),
47
+ version: v.number(),
48
+ };
49
+ export const operationRef = v.object(operationRefFields);
50
+ export const providerKeys = v.object({
51
+ enable: v.string(),
52
+ disable: v.string(),
53
+ create: v.optional(v.string()),
54
+ attach: v.optional(v.string()),
55
+ });
56
+ export const failureCode = v.union(
57
+ v.literal("invalid_scope"),
58
+ v.literal("unsupported_source"),
59
+ v.literal("policy_invalid"),
60
+ );
61
+ export const operationFields = {
62
+ ...scopeFields,
63
+ preparationId: v.id("balanceFundingPreparations"),
64
+ version: v.number(),
65
+ enabled: v.boolean(),
66
+ kind: v.union(v.literal("prepare"), v.literal("apply")),
67
+ providerKey: v.string(),
68
+ state: v.union(
69
+ v.literal("pending"),
70
+ v.literal("running"),
71
+ v.literal("unknown"),
72
+ v.literal("succeeded"),
73
+ v.literal("canceled"),
74
+ v.literal("failed"),
75
+ ),
76
+ cancelRequested: v.boolean(),
77
+ failureCode: v.optional(failureCode),
78
+ providerKeys,
79
+ receipt: v.optional(receiptValue),
80
+ };
81
+ export const operationDoc = v.object({
82
+ ...operationFields,
83
+ _id: v.id("balanceFundingOperations"),
84
+ _creationTime: v.number(),
85
+ });
86
+ export const conflict = v.object({
87
+ status: v.literal("conflict"),
88
+ reason: v.union(
89
+ v.literal("scope_busy"),
90
+ v.literal("identity_changed"),
91
+ v.literal("revision_changed"),
92
+ ),
93
+ retryable: v.literal(false),
94
+ });
95
+ export const rejected = v.object({
96
+ status: v.literal("rejected"),
97
+ reason: v.literal("policy_invalid"),
98
+ retryable: v.literal(false),
99
+ });
100
+ export const beginResult = v.union(
101
+ v.object({ status: v.literal("accepted"), operation: operationRef }),
102
+ v.object({ status: v.literal("unchanged"), enabled: v.boolean() }),
103
+ conflict,
104
+ rejected,
105
+ v.object({
106
+ status: v.literal("not_ready"),
107
+ reason: v.literal("provider_pending"),
108
+ retryable: v.literal(true),
109
+ }),
110
+ );
111
+ export const preparationsTable = defineTable(preparationFields).index(
112
+ "by_account_subscription",
113
+ ["accountId", "preparation.stripeSubscriptionId"],
114
+ );
115
+ export const operationsTable = defineTable(operationFields).index(
116
+ "by_preparation_version",
117
+ ["preparationId", "version"],
118
+ );
119
+ export const importResult = v.object({
120
+ preparationId: v.id("balanceFundingPreparations"),
121
+ operation: v.optional(operationRef),
122
+ });
123
+ export const requestsTable = defineTable({
124
+ requestKey: v.string(),
125
+ payload: v.string(),
126
+ preparationId: v.id("balanceFundingPreparations"),
127
+ result: v.optional(beginResult),
128
+ imported: v.optional(importResult),
129
+ }).index("by_request", ["requestKey"]);
130
+ export const safeStatus = v.object({
131
+ ...operationRefFields,
132
+ state: v.union(
133
+ v.literal("pending"),
134
+ v.literal("running"),
135
+ v.literal("unknown"),
136
+ v.literal("succeeded"),
137
+ v.literal("canceled"),
138
+ v.literal("failed"),
139
+ ),
140
+ cancelRequested: v.boolean(),
141
+ failureCode: v.optional(failureCode),
142
+ });
143
+ export const invalidScope = v.object({
144
+ status: v.literal("rejected"),
145
+ reason: v.literal("invalid_scope"),
146
+ retryable: v.literal(false),
147
+ });
148
+ export const preparationLookup = v.union(
149
+ v.object({
150
+ status: v.literal("prepared"),
151
+ operation: operationRef,
152
+ stripeSubscriptionId: v.string(),
153
+ preparationId: v.id("balanceFundingPreparations"),
154
+ }),
155
+ v.object({
156
+ status: v.union(
157
+ v.literal("pending"),
158
+ v.literal("running"),
159
+ v.literal("unknown"),
160
+ v.literal("canceled"),
161
+ v.literal("failed"),
162
+ ),
163
+ operation: operationRef,
164
+ failureCode: v.optional(failureCode),
165
+ }),
166
+ conflict,
167
+ invalidScope,
168
+ v.null(),
169
+ );