@fantastic.dev/better-stripe 0.41.0 → 0.43.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 (209) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +1 -1
  3. package/dist/client/balanceFundingWorkflow/client.d.ts +172 -0
  4. package/dist/client/balanceFundingWorkflow/client.d.ts.map +1 -0
  5. package/dist/client/balanceFundingWorkflow/client.js +289 -0
  6. package/dist/client/balanceFundingWorkflow/client.js.map +1 -0
  7. package/dist/client/billing/balanceFunding.d.ts +5 -0
  8. package/dist/client/billing/balanceFunding.d.ts.map +1 -1
  9. package/dist/client/billing/balanceFunding.js +30 -0
  10. package/dist/client/billing/balanceFunding.js.map +1 -1
  11. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +1388 -2
  12. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  13. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +710 -17
  14. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  15. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +1420 -34
  16. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  17. package/dist/client/connect/payoutSyncTestHelpers.d.ts +694 -1
  18. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  19. package/dist/client/costRecovery-invoices.d.ts +3 -2
  20. package/dist/client/costRecovery-invoices.d.ts.map +1 -1
  21. package/dist/client/costRecovery-invoices.js +10 -5
  22. package/dist/client/costRecovery-invoices.js.map +1 -1
  23. package/dist/client/costRecovery.d.ts +4 -2
  24. package/dist/client/costRecovery.d.ts.map +1 -1
  25. package/dist/client/costRecovery.js +2 -2
  26. package/dist/client/costRecovery.js.map +1 -1
  27. package/dist/client/index.d.ts +3 -0
  28. package/dist/client/index.d.ts.map +1 -1
  29. package/dist/client/index.js +4 -0
  30. package/dist/client/index.js.map +1 -1
  31. package/dist/client/processingCostReconciliation/client.d.ts +14 -0
  32. package/dist/client/processingCostReconciliation/client.d.ts.map +1 -0
  33. package/dist/client/processingCostReconciliation/client.js +35 -0
  34. package/dist/client/processingCostReconciliation/client.js.map +1 -0
  35. package/dist/client/processingCostReconciliation/contracts.d.ts +172 -0
  36. package/dist/client/processingCostReconciliation/contracts.d.ts.map +1 -0
  37. package/dist/client/processingCostReconciliation/contracts.js +55 -0
  38. package/dist/client/processingCostReconciliation/contracts.js.map +1 -0
  39. package/dist/client/processingCostReconciliation/invoiceFunding.d.ts +15 -0
  40. package/dist/client/processingCostReconciliation/invoiceFunding.d.ts.map +1 -0
  41. package/dist/client/processingCostReconciliation/invoiceFunding.js +195 -0
  42. package/dist/client/processingCostReconciliation/invoiceFunding.js.map +1 -0
  43. package/dist/client/processingCostReconciliation/provider.d.ts +9 -0
  44. package/dist/client/processingCostReconciliation/provider.d.ts.map +1 -0
  45. package/dist/client/processingCostReconciliation/provider.js +148 -0
  46. package/dist/client/processingCostReconciliation/provider.js.map +1 -0
  47. package/dist/client/settlement/processingCostHistory.d.ts +12 -0
  48. package/dist/client/settlement/processingCostHistory.d.ts.map +1 -0
  49. package/dist/client/settlement/processingCostHistory.js +20 -0
  50. package/dist/client/settlement/processingCostHistory.js.map +1 -0
  51. package/dist/client/settlement/processingCosts.d.ts +3 -0
  52. package/dist/client/settlement/processingCosts.d.ts.map +1 -1
  53. package/dist/client/settlement/processingCosts.js +27 -7
  54. package/dist/client/settlement/processingCosts.js.map +1 -1
  55. package/dist/component/_generated/api.d.ts +36 -0
  56. package/dist/component/_generated/api.d.ts.map +1 -1
  57. package/dist/component/_generated/api.js.map +1 -1
  58. package/dist/component/_generated/component.d.ts +988 -0
  59. package/dist/component/_generated/component.d.ts.map +1 -1
  60. package/dist/component/balanceFunding/helpers.d.ts +42 -0
  61. package/dist/component/balanceFunding/helpers.d.ts.map +1 -1
  62. package/dist/component/balanceFunding/internal/actions.d.ts +39 -0
  63. package/dist/component/balanceFunding/internal/actions.d.ts.map +1 -0
  64. package/dist/component/balanceFunding/internal/actions.js +80 -0
  65. package/dist/component/balanceFunding/internal/actions.js.map +1 -0
  66. package/dist/component/balanceFunding/internal/mutations.d.ts +55 -0
  67. package/dist/component/balanceFunding/internal/mutations.d.ts.map +1 -0
  68. package/dist/component/balanceFunding/internal/mutations.js +54 -0
  69. package/dist/component/balanceFunding/internal/mutations.js.map +1 -0
  70. package/dist/component/balanceFunding/internal/queries.d.ts +116 -0
  71. package/dist/component/balanceFunding/internal/queries.d.ts.map +1 -0
  72. package/dist/component/balanceFunding/internal/queries.js +35 -0
  73. package/dist/component/balanceFunding/internal/queries.js.map +1 -0
  74. package/dist/component/balanceFunding/internal/workflow.d.ts +10 -0
  75. package/dist/component/balanceFunding/internal/workflow.d.ts.map +1 -0
  76. package/dist/component/balanceFunding/internal/workflow.js +31 -0
  77. package/dist/component/balanceFunding/internal/workflow.js.map +1 -0
  78. package/dist/component/balanceFunding/lifecycleHandlers.d.ts +126 -0
  79. package/dist/component/balanceFunding/lifecycleHandlers.d.ts.map +1 -1
  80. package/dist/component/balanceFunding/mutations.d.ts +419 -16
  81. package/dist/component/balanceFunding/mutations.d.ts.map +1 -1
  82. package/dist/component/balanceFunding/mutations.js +24 -0
  83. package/dist/component/balanceFunding/mutations.js.map +1 -1
  84. package/dist/component/balanceFunding/preparationHandlers.d.ts +42 -0
  85. package/dist/component/balanceFunding/preparationHandlers.d.ts.map +1 -1
  86. package/dist/component/balanceFunding/queries.d.ts +78 -0
  87. package/dist/component/balanceFunding/queries.d.ts.map +1 -1
  88. package/dist/component/balanceFunding/queries.js +35 -0
  89. package/dist/component/balanceFunding/queries.js.map +1 -1
  90. package/dist/component/balanceFunding/receipt.d.ts +5 -0
  91. package/dist/component/balanceFunding/receipt.d.ts.map +1 -0
  92. package/dist/component/balanceFunding/receipt.js +37 -0
  93. package/dist/component/balanceFunding/receipt.js.map +1 -0
  94. package/dist/component/balanceFunding/schema.d.ts +506 -2
  95. package/dist/component/balanceFunding/schema.d.ts.map +1 -1
  96. package/dist/component/balanceFunding/schema.js +2 -0
  97. package/dist/component/balanceFunding/schema.js.map +1 -1
  98. package/dist/component/balanceFunding/stateHandlers.d.ts +42 -0
  99. package/dist/component/balanceFunding/stateHandlers.d.ts.map +1 -1
  100. package/dist/component/balanceFunding/workflowControl.d.ts +19 -0
  101. package/dist/component/balanceFunding/workflowControl.d.ts.map +1 -0
  102. package/dist/component/balanceFunding/workflowControl.js +149 -0
  103. package/dist/component/balanceFunding/workflowControl.js.map +1 -0
  104. package/dist/component/balanceFunding/workflowSchema.d.ts +356 -0
  105. package/dist/component/balanceFunding/workflowSchema.d.ts.map +1 -0
  106. package/dist/component/balanceFunding/workflowSchema.js +48 -0
  107. package/dist/component/balanceFunding/workflowSchema.js.map +1 -0
  108. package/dist/component/balanceFunding/workflowState.d.ts +157 -0
  109. package/dist/component/balanceFunding/workflowState.d.ts.map +1 -0
  110. package/dist/component/balanceFunding/workflowState.js +194 -0
  111. package/dist/component/balanceFunding/workflowState.js.map +1 -0
  112. package/dist/component/balanceFunding/workflowValidators.d.ts +306 -0
  113. package/dist/component/balanceFunding/workflowValidators.d.ts.map +1 -0
  114. package/dist/component/balanceFunding/workflowValidators.js +27 -0
  115. package/dist/component/balanceFunding/workflowValidators.js.map +1 -0
  116. package/dist/component/earnings/triggers.d.ts +388 -2
  117. package/dist/component/earnings/triggers.d.ts.map +1 -1
  118. package/dist/component/payoutRelease/queries.d.ts +2 -2
  119. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  120. package/dist/component/processingCostReconciliation/adoption.d.ts +29 -0
  121. package/dist/component/processingCostReconciliation/adoption.d.ts.map +1 -0
  122. package/dist/component/processingCostReconciliation/adoption.js +58 -0
  123. package/dist/component/processingCostReconciliation/adoption.js.map +1 -0
  124. package/dist/component/processingCostReconciliation/bridge.d.ts +45 -0
  125. package/dist/component/processingCostReconciliation/bridge.d.ts.map +1 -0
  126. package/dist/component/processingCostReconciliation/bridge.js +41 -0
  127. package/dist/component/processingCostReconciliation/bridge.js.map +1 -0
  128. package/dist/component/processingCostReconciliation/helpers.d.ts +327 -0
  129. package/dist/component/processingCostReconciliation/helpers.d.ts.map +1 -0
  130. package/dist/component/processingCostReconciliation/helpers.js +39 -0
  131. package/dist/component/processingCostReconciliation/helpers.js.map +1 -0
  132. package/dist/component/processingCostReconciliation/mutations.d.ts +303 -0
  133. package/dist/component/processingCostReconciliation/mutations.d.ts.map +1 -0
  134. package/dist/component/processingCostReconciliation/mutations.js +121 -0
  135. package/dist/component/processingCostReconciliation/mutations.js.map +1 -0
  136. package/dist/component/processingCostReconciliation/queries.d.ts +422 -0
  137. package/dist/component/processingCostReconciliation/queries.d.ts.map +1 -0
  138. package/dist/component/processingCostReconciliation/queries.js +19 -0
  139. package/dist/component/processingCostReconciliation/queries.js.map +1 -0
  140. package/dist/component/processingCostReconciliation/rollback.d.ts +21 -0
  141. package/dist/component/processingCostReconciliation/rollback.d.ts.map +1 -0
  142. package/dist/component/processingCostReconciliation/rollback.js +54 -0
  143. package/dist/component/processingCostReconciliation/rollback.js.map +1 -0
  144. package/dist/component/processingCostReconciliation/schema.d.ts +2460 -0
  145. package/dist/component/processingCostReconciliation/schema.d.ts.map +1 -0
  146. package/dist/component/processingCostReconciliation/schema.js +137 -0
  147. package/dist/component/processingCostReconciliation/schema.js.map +1 -0
  148. package/dist/component/processingCostReconciliation/steps.d.ts +306 -0
  149. package/dist/component/processingCostReconciliation/steps.d.ts.map +1 -0
  150. package/dist/component/processingCostReconciliation/steps.js +149 -0
  151. package/dist/component/processingCostReconciliation/steps.js.map +1 -0
  152. package/dist/component/processingCostReconciliation/validation.d.ts +13 -0
  153. package/dist/component/processingCostReconciliation/validation.d.ts.map +1 -0
  154. package/dist/component/processingCostReconciliation/validation.js +61 -0
  155. package/dist/component/processingCostReconciliation/validation.js.map +1 -0
  156. package/dist/component/processingCostReconciliation/workflow.d.ts +105 -0
  157. package/dist/component/processingCostReconciliation/workflow.d.ts.map +1 -0
  158. package/dist/component/processingCostReconciliation/workflow.js +33 -0
  159. package/dist/component/processingCostReconciliation/workflow.js.map +1 -0
  160. package/dist/component/schema.d.ts +694 -1
  161. package/dist/component/schema.js +2 -0
  162. package/dist/component/schema.js.map +1 -1
  163. package/package.json +1 -1
  164. package/src/client/balanceFundingWorkflow/capture.test.ts +144 -0
  165. package/src/client/balanceFundingWorkflow/client.ts +419 -0
  166. package/src/client/billing/balanceFunding.ts +50 -0
  167. package/src/client/costRecovery-invoices.ts +19 -4
  168. package/src/client/costRecovery.ts +4 -2
  169. package/src/client/index.ts +15 -0
  170. package/src/client/processingCostReconciliation/client.ts +75 -0
  171. package/src/client/processingCostReconciliation/contracts.ts +176 -0
  172. package/src/client/processingCostReconciliation/invoiceFunding.ts +270 -0
  173. package/src/client/processingCostReconciliation/invoiceProvider.test.ts +353 -0
  174. package/src/client/processingCostReconciliation/provider.test.ts +324 -0
  175. package/src/client/processingCostReconciliation/provider.ts +178 -0
  176. package/src/client/settlement/processingCostHistory.ts +31 -0
  177. package/src/client/settlement/processingCosts.ts +50 -15
  178. package/src/component/_generated/api.ts +36 -0
  179. package/src/component/_generated/component.ts +1094 -0
  180. package/src/component/balanceFunding/internal/actions.ts +107 -0
  181. package/src/component/balanceFunding/internal/mutations.ts +66 -0
  182. package/src/component/balanceFunding/internal/queries.ts +34 -0
  183. package/src/component/balanceFunding/internal/workflow.ts +49 -0
  184. package/src/component/balanceFunding/mutations.ts +34 -0
  185. package/src/component/balanceFunding/queries.ts +38 -0
  186. package/src/component/balanceFunding/receipt.ts +48 -0
  187. package/src/component/balanceFunding/schema.ts +2 -0
  188. package/src/component/balanceFunding/scopeLookup.test.ts +94 -0
  189. package/src/component/balanceFunding/workflow.fixtures.ts +366 -0
  190. package/src/component/balanceFunding/workflow.test.ts +552 -0
  191. package/src/component/balanceFunding/workflowControl.ts +198 -0
  192. package/src/component/balanceFunding/workflowSchema.ts +78 -0
  193. package/src/component/balanceFunding/workflowState.ts +285 -0
  194. package/src/component/balanceFunding/workflowValidators.ts +40 -0
  195. package/src/component/processingCostReconciliation/adoption.test.ts +206 -0
  196. package/src/component/processingCostReconciliation/adoption.ts +77 -0
  197. package/src/component/processingCostReconciliation/bridge.ts +50 -0
  198. package/src/component/processingCostReconciliation/helpers.ts +55 -0
  199. package/src/component/processingCostReconciliation/invoice.test.ts +152 -0
  200. package/src/component/processingCostReconciliation/mutations.ts +148 -0
  201. package/src/component/processingCostReconciliation/queries.ts +18 -0
  202. package/src/component/processingCostReconciliation/rollback.ts +72 -0
  203. package/src/component/processingCostReconciliation/schema.ts +191 -0
  204. package/src/component/processingCostReconciliation/state.test.ts +407 -0
  205. package/src/component/processingCostReconciliation/steps.ts +168 -0
  206. package/src/component/processingCostReconciliation/validation.ts +79 -0
  207. package/src/component/processingCostReconciliation/workflow.test.ts +329 -0
  208. package/src/component/processingCostReconciliation/workflow.ts +50 -0
  209. package/src/component/schema.ts +2 -0
@@ -0,0 +1,107 @@
1
+ import type { FunctionHandle } from "convex/server";
2
+ import { internalAction } from "../../_generated/server.js";
3
+ import { internal } from "../../_generated/api.js";
4
+ import { phaseRefFields, type FundingPhaseRef } from "../workflowValidators.js";
5
+ import { providerResult, type ProviderResult } from "../workflowSchema.js";
6
+ import { normalizeReceipt } from "../receipt.js";
7
+ import { phaseKey, unknown } from "../workflowState.js";
8
+ export const bridge = internalAction({
9
+ args: phaseRefFields,
10
+ returns: providerResult,
11
+ handler: async (ctx, args): Promise<ProviderResult> => {
12
+ const { phase: _phase, providerKey: _key, ...base } = args;
13
+ const context = await ctx.runQuery(
14
+ internal.balanceFunding.internal.queries.readContext,
15
+ base,
16
+ );
17
+ if (phaseKey(context.operation, args.phase) !== args.providerKey)
18
+ return {
19
+ status: "conflict",
20
+ reason: "identity_changed",
21
+ retryable: false,
22
+ };
23
+ try {
24
+ const result: unknown = await ctx.runAction(
25
+ context.operation.execution!.providerAction as FunctionHandle<
26
+ "action",
27
+ FundingPhaseRef,
28
+ unknown
29
+ >,
30
+ args,
31
+ );
32
+ if (
33
+ result &&
34
+ typeof result === "object" &&
35
+ "status" in result &&
36
+ result.status === "ready" &&
37
+ "value" in result
38
+ ) {
39
+ const receipt = normalizeReceipt(result.value, args);
40
+ if (receipt) {
41
+ // Preserve positive evidence even if cancellation races this action.
42
+ // A failed receipt write is retried as its own workflow step.
43
+ try {
44
+ await ctx.runMutation(
45
+ internal.balanceFunding.internal.mutations.recordProviderReceipt,
46
+ { ...args, receipt },
47
+ );
48
+ } catch {
49
+ /* journal the validated receipt below */
50
+ }
51
+ return { status: "ready", value: receipt };
52
+ }
53
+ }
54
+ if (
55
+ result &&
56
+ typeof result === "object" &&
57
+ "status" in result &&
58
+ "reason" in result
59
+ ) {
60
+ const current = await ctx.runQuery(
61
+ internal.balanceFunding.internal.queries.readContext,
62
+ base,
63
+ );
64
+ if (!current.operation.execution?.[args.phase]) {
65
+ if (
66
+ result.status === "conflict" &&
67
+ (result.reason === "scope_busy" ||
68
+ result.reason === "revision_changed" ||
69
+ result.reason === "identity_changed")
70
+ )
71
+ return {
72
+ status: "conflict",
73
+ reason: result.reason,
74
+ retryable: false,
75
+ };
76
+ if (
77
+ result.status === "rejected" &&
78
+ (result.reason === "policy_invalid" ||
79
+ result.reason === "unsupported_source" ||
80
+ result.reason === "invalid_scope")
81
+ )
82
+ return {
83
+ status: "rejected",
84
+ reason: result.reason,
85
+ retryable: false,
86
+ };
87
+ if (
88
+ result.status === "not_ready" &&
89
+ result.reason === "provider_pending"
90
+ )
91
+ return {
92
+ status: "not_ready",
93
+ reason: "provider_pending",
94
+ retryable: true,
95
+ };
96
+ }
97
+ }
98
+ } catch {
99
+ /* Raw host/provider errors must never enter durable history. */
100
+ }
101
+ await ctx.runMutation(
102
+ internal.balanceFunding.internal.mutations.markProviderUnknown,
103
+ args,
104
+ );
105
+ return unknown();
106
+ },
107
+ });
@@ -0,0 +1,66 @@
1
+ import { v } from "convex/values";
2
+ import { internalMutation } from "../../_generated/server.js";
3
+ import { vWorkflowId } from "@convex-dev/workflow";
4
+ import { vResultValidator } from "@convex-dev/workpool";
5
+ import {
6
+ workflowRef,
7
+ workflowRefFields,
8
+ phaseRefFields,
9
+ } from "../workflowValidators.js";
10
+ import { provisioningReceipt } from "../workflowSchema.js";
11
+ import {
12
+ finishFromReceiptsHandler,
13
+ recordProviderReceiptHandler,
14
+ markProviderUnknownHandler,
15
+ readWorkflowContext,
16
+ } from "../workflowState.js";
17
+ export const recordProviderReceipt = internalMutation({
18
+ args: { ...phaseRefFields, receipt: provisioningReceipt },
19
+ returns: v.null(),
20
+ handler: recordProviderReceiptHandler,
21
+ });
22
+ export const markProviderUnknown = internalMutation({
23
+ args: phaseRefFields,
24
+ returns: v.null(),
25
+ handler: markProviderUnknownHandler,
26
+ });
27
+ export const finishFromReceipts = internalMutation({
28
+ args: workflowRefFields,
29
+ returns: v.null(),
30
+ handler: finishFromReceiptsHandler,
31
+ });
32
+ export const onComplete = internalMutation({
33
+ args: {
34
+ workflowId: vWorkflowId,
35
+ result: vResultValidator,
36
+ context: workflowRef,
37
+ },
38
+ returns: v.null(),
39
+ handler: async (ctx, args) => {
40
+ const { operation } = await readWorkflowContext(ctx, args.context);
41
+ if (
42
+ operation.execution?.workflowId !== args.workflowId ||
43
+ ["succeeded", "failed", "canceled"].includes(operation.state)
44
+ )
45
+ return null;
46
+ const unsettled = [
47
+ operation.execution?.create,
48
+ operation.execution?.attach,
49
+ operation.execution?.apply,
50
+ ].some((phase) => phase?.state === "running" || phase?.state === "unknown");
51
+ if (
52
+ args.result.kind !== "success" &&
53
+ (unsettled ||
54
+ (args.result.kind === "canceled" &&
55
+ [
56
+ operation.execution?.create,
57
+ operation.execution?.attach,
58
+ operation.execution?.apply,
59
+ ].some(Boolean)))
60
+ )
61
+ await ctx.db.patch("balanceFundingOperations", operation._id, {
62
+ state: "unknown",
63
+ });
64
+ return null;
65
+ },
66
+ });
@@ -0,0 +1,34 @@
1
+ import { v } from "convex/values";
2
+ import { internalQuery } from "../../_generated/server.js";
3
+ import { operationDoc, preparationDoc } from "../schema.js";
4
+ import { workflowRefFields } from "../workflowValidators.js";
5
+ import { readWorkflowContext } from "../workflowState.js";
6
+ export const readContext = internalQuery({
7
+ args: workflowRefFields,
8
+ returns: v.object({ operation: operationDoc, preparation: preparationDoc }),
9
+ handler: (ctx, args) => readWorkflowContext(ctx, args),
10
+ });
11
+ export const plan = internalQuery({
12
+ args: workflowRefFields,
13
+ returns: v.object({
14
+ createKey: v.optional(v.string()),
15
+ attachKey: v.optional(v.string()),
16
+ applyKey: v.string(),
17
+ kind: v.union(v.literal("prepare"), v.literal("apply")),
18
+ }),
19
+ handler: async (ctx, args) => {
20
+ const { operation } = await readWorkflowContext(ctx, args);
21
+ return {
22
+ kind: operation.kind,
23
+ applyKey: operation.enabled
24
+ ? operation.providerKeys.enable
25
+ : operation.providerKeys.disable,
26
+ ...(operation.providerKeys.create
27
+ ? { createKey: operation.providerKeys.create }
28
+ : {}),
29
+ ...(operation.providerKeys.attach
30
+ ? { attachKey: operation.providerKeys.attach }
31
+ : {}),
32
+ };
33
+ },
34
+ });
@@ -0,0 +1,49 @@
1
+ import { v } from "convex/values";
2
+ import { internal } from "../../_generated/api.js";
3
+ import { executionWorkflow } from "../../durableExecution/runtime.js";
4
+ import { workflowRefFields } from "../workflowValidators.js";
5
+ export const run = executionWorkflow.define({
6
+ args: workflowRefFields,
7
+ returns: v.null(),
8
+ handler: async (step, args): Promise<null> => {
9
+ const plan = await step.runQuery(
10
+ internal.balanceFunding.internal.queries.plan,
11
+ args,
12
+ { name: "plan-v1" },
13
+ );
14
+ for (const phase of plan.kind === "prepare"
15
+ ? (["create", "attach"] as const)
16
+ : (["apply"] as const)) {
17
+ const phaseArgs = {
18
+ ...args,
19
+ phase,
20
+ providerKey:
21
+ phase === "apply"
22
+ ? plan.applyKey
23
+ : phase === "create"
24
+ ? plan.createKey!
25
+ : plan.attachKey!,
26
+ };
27
+ const result = await step.runAction(
28
+ internal.balanceFunding.internal.actions.bridge,
29
+ phaseArgs,
30
+ { name: `${phase}-provider-v1`, retry: false },
31
+ );
32
+ if (result.status !== "ready")
33
+ throw new Error(
34
+ "Balance funding provider outcome requires reconciliation.",
35
+ );
36
+ await step.runMutation(
37
+ internal.balanceFunding.internal.mutations.recordProviderReceipt,
38
+ { ...phaseArgs, receipt: result.value },
39
+ { name: `${phase}-record-v1` },
40
+ );
41
+ }
42
+ await step.runMutation(
43
+ internal.balanceFunding.internal.mutations.finishFromReceipts,
44
+ args,
45
+ { name: "finish-v1" },
46
+ );
47
+ return null;
48
+ },
49
+ });
@@ -134,3 +134,37 @@ export const failBeforeStart = mutation({
134
134
  return { ...op, state: "failed" as const, failureCode: args.failureCode };
135
135
  },
136
136
  });
137
+
138
+ import {
139
+ workflowRefFields,
140
+ phaseRefFields,
141
+ workflowStartResult,
142
+ phaseClaimResult,
143
+ } from "./workflowValidators.js";
144
+ import { safeStatus } from "./schema.js";
145
+ import { claimProviderPhaseHandler } from "./workflowState.js";
146
+ import {
147
+ startWorkflowHandler,
148
+ resumeWorkflowHandler,
149
+ cancelWorkflowHandler,
150
+ } from "./workflowControl.js";
151
+ export const startWorkflow = mutation({
152
+ args: { ...workflowRefFields, providerAction: v.string() },
153
+ returns: workflowStartResult,
154
+ handler: startWorkflowHandler,
155
+ });
156
+ export const resumeWorkflow = mutation({
157
+ args: workflowRefFields,
158
+ returns: workflowStartResult,
159
+ handler: resumeWorkflowHandler,
160
+ });
161
+ export const cancelWorkflow = mutation({
162
+ args: workflowRefFields,
163
+ returns: safeStatus,
164
+ handler: cancelWorkflowHandler,
165
+ });
166
+ export const claimProviderPhase = mutation({
167
+ args: phaseRefFields,
168
+ returns: phaseClaimResult,
169
+ handler: claimProviderPhaseHandler,
170
+ });
@@ -219,3 +219,41 @@ export const findPreparationOperation = query({
219
219
  };
220
220
  },
221
221
  });
222
+
223
+ /** Server-only canonical capture lookup. Never forward restoration data to browsers. */
224
+ export const readScopePreparation = query({
225
+ args: {
226
+ ...scopeFields,
227
+ stripeSubscriptionId: v.string(),
228
+ providerApiVersion: v.string(),
229
+ },
230
+ returns: v.union(preparationDoc, conflict, invalidScope, v.null()),
231
+ handler: async (ctx, args) => {
232
+ try {
233
+ validateScope(args);
234
+ text(args.stripeSubscriptionId);
235
+ text(args.providerApiVersion);
236
+ } catch {
237
+ return {
238
+ status: "rejected" as const,
239
+ reason: "invalid_scope" as const,
240
+ retryable: false as const,
241
+ };
242
+ }
243
+ const saved = await ctx.db
244
+ .query("balanceFundingPreparations")
245
+ .withIndex("by_account_subscription", (q) =>
246
+ q
247
+ .eq("accountId", args.accountId)
248
+ .eq("preparation.stripeSubscriptionId", args.stripeSubscriptionId),
249
+ )
250
+ .unique();
251
+ if (!saved) return null;
252
+ if (
253
+ saved.scopeKey !== args.scopeKey ||
254
+ saved.providerApiVersion !== args.providerApiVersion
255
+ )
256
+ return unavailable("identity_changed");
257
+ return saved;
258
+ },
259
+ });
@@ -0,0 +1,48 @@
1
+ import type { FundingPhaseRef } from "./workflowValidators.js";
2
+ import type { ProvisioningReceipt } from "./workflowSchema.js";
3
+ /** Allowlist only bound, nonsecret provider evidence before durable journaling. */
4
+ export function normalizeReceipt(
5
+ value: unknown,
6
+ args: FundingPhaseRef,
7
+ ): ProvisioningReceipt | null {
8
+ if (!value || typeof value !== "object") return null;
9
+ const r = value as Record<string, unknown>;
10
+ if (
11
+ r.phase !== args.phase ||
12
+ r.customerAccount !== args.accountId ||
13
+ r.stripeSubscriptionId !== args.stripeSubscriptionId ||
14
+ r.providerApiVersion !== args.providerApiVersion ||
15
+ (r.paymentMethodId !== null &&
16
+ (typeof r.paymentMethodId !== "string" ||
17
+ !r.paymentMethodId.trim() ||
18
+ r.paymentMethodId.length > 200)) ||
19
+ (args.phase !== "apply" && r.paymentMethodId === null)
20
+ )
21
+ return null;
22
+ if (
23
+ args.phase === "apply" &&
24
+ (typeof r.enabled !== "boolean" ||
25
+ !(
26
+ r.paymentMethodTypes === null ||
27
+ (Array.isArray(r.paymentMethodTypes) &&
28
+ r.paymentMethodTypes.length <= 50 &&
29
+ r.paymentMethodTypes.every(
30
+ (x) => typeof x === "string" && x.length <= 200,
31
+ ))
32
+ ))
33
+ )
34
+ return null;
35
+ return {
36
+ phase: args.phase,
37
+ customerAccount: args.accountId,
38
+ stripeSubscriptionId: args.stripeSubscriptionId,
39
+ providerApiVersion: args.providerApiVersion,
40
+ paymentMethodId: r.paymentMethodId as string | null,
41
+ ...(args.phase === "apply"
42
+ ? {
43
+ enabled: r.enabled as boolean,
44
+ paymentMethodTypes: r.paymentMethodTypes as string[] | null,
45
+ }
46
+ : {}),
47
+ };
48
+ }
@@ -1,5 +1,6 @@
1
1
  import { defineTable } from "convex/server";
2
2
  import { v } from "convex/values";
3
+ import { workflowBinding } from "./workflowSchema.js";
3
4
  export const scopeFields = { accountId: v.string(), scopeKey: v.string() };
4
5
  export const originalFields = {
5
6
  customerAccount: v.string(),
@@ -77,6 +78,7 @@ export const operationFields = {
77
78
  failureCode: v.optional(failureCode),
78
79
  providerKeys,
79
80
  receipt: v.optional(receiptValue),
81
+ execution: v.optional(workflowBinding),
80
82
  };
81
83
  export const operationDoc = v.object({
82
84
  ...operationFields,
@@ -0,0 +1,94 @@
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 mutation = (name: string) =>
7
+ makeFunctionReference<"mutation">(`balanceFunding/mutations:${name}`);
8
+ const scope = { accountId: "acct_owner", scopeKey: "opaque-scope" };
9
+ const stripeSubscriptionId = "sub_original";
10
+ const providerApiVersion = "2026-06-30.preview";
11
+ const original = {
12
+ customerAccount: scope.accountId,
13
+ stripeSubscriptionId,
14
+ previousPaymentMethodId: "pm_original",
15
+ previousPaymentMethodTypes: ["card"],
16
+ };
17
+ const identity = { ...scope, stripeSubscriptionId, providerApiVersion };
18
+ const conflict = {
19
+ status: "conflict",
20
+ reason: "identity_changed",
21
+ retryable: false,
22
+ };
23
+ async function fixture() {
24
+ const t = convexTest(schema, modules);
25
+ const intent = await t.mutation(mutation("prepare"), {
26
+ ...scope,
27
+ preparation: original,
28
+ consent: true,
29
+ consentAt: 100,
30
+ consentReference: "original-consent",
31
+ providerApiVersion,
32
+ requestKey: "prepare-once",
33
+ });
34
+ const read = (args: typeof identity = identity) => {
35
+ return t.query(
36
+ makeFunctionReference<"query">(
37
+ "balanceFunding/queries:readScopePreparation",
38
+ ),
39
+ args,
40
+ );
41
+ };
42
+ return { t, intent, read };
43
+ }
44
+
45
+ it("finds the canonical capture before any retry can recapture provider settings", async () => {
46
+ const s = await fixture();
47
+ expect(await s.read()).toMatchObject({
48
+ ...scope,
49
+ preparation: original,
50
+ verified: false,
51
+ consentAt: 100,
52
+ consentReference: "original-consent",
53
+ providerApiVersion,
54
+ activeOperationId: s.intent.operation.operationId,
55
+ });
56
+ });
57
+
58
+ it("binds server-only lookup to owner scope, subscription and immutable API version", async () => {
59
+ const s = await fixture();
60
+ expect(await s.read({ ...identity, scopeKey: "alias" })).toEqual(conflict);
61
+ expect(
62
+ await s.read({ ...identity, stripeSubscriptionId: "sub_foreign" }),
63
+ ).toBeNull();
64
+ expect(
65
+ await s.read({ ...identity, providerApiVersion: "changed-version" }),
66
+ ).toEqual(conflict);
67
+ });
68
+
69
+ it("retains the original capture while an uncertain effect holds its reservation", async () => {
70
+ const s = await fixture();
71
+ await s.t.mutation(mutation("start"), s.intent.operation);
72
+ await s.t.mutation(mutation("markUnknown"), s.intent.operation);
73
+ expect(await s.read()).toMatchObject({
74
+ preparation: original,
75
+ activeOperationId: s.intent.operation.operationId,
76
+ verified: false,
77
+ });
78
+ const safe = await s.t.query(
79
+ makeFunctionReference<"query">("balanceFunding/queries:getPreparation"),
80
+ { ...s.intent.operation, stripeSubscriptionId },
81
+ );
82
+ expect(safe).toEqual({ status: "unknown", operation: s.intent.operation });
83
+ expect(JSON.stringify(safe)).not.toContain("pm_original");
84
+ expect(JSON.stringify(safe)).not.toContain("original-consent");
85
+ });
86
+
87
+ it("rejects invalid server scope without returning restoration data", async () => {
88
+ const s = await fixture();
89
+ expect(await s.read({ ...identity, scopeKey: "" })).toEqual({
90
+ status: "rejected",
91
+ reason: "invalid_scope",
92
+ retryable: false,
93
+ });
94
+ });