@fantastic.dev/better-stripe 0.41.0 → 0.42.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 (108) hide show
  1. package/CHANGELOG.md +10 -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 +366 -2
  12. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  13. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +199 -17
  14. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  15. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +366 -2
  16. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  17. package/dist/client/connect/payoutSyncTestHelpers.d.ts +199 -17
  18. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  19. package/dist/client/index.d.ts +3 -0
  20. package/dist/client/index.d.ts.map +1 -1
  21. package/dist/client/index.js +4 -0
  22. package/dist/client/index.js.map +1 -1
  23. package/dist/component/_generated/api.d.ts +18 -0
  24. package/dist/component/_generated/api.d.ts.map +1 -1
  25. package/dist/component/_generated/api.js.map +1 -1
  26. package/dist/component/_generated/component.d.ts +473 -0
  27. package/dist/component/_generated/component.d.ts.map +1 -1
  28. package/dist/component/balanceFunding/helpers.d.ts +42 -0
  29. package/dist/component/balanceFunding/helpers.d.ts.map +1 -1
  30. package/dist/component/balanceFunding/internal/actions.d.ts +39 -0
  31. package/dist/component/balanceFunding/internal/actions.d.ts.map +1 -0
  32. package/dist/component/balanceFunding/internal/actions.js +80 -0
  33. package/dist/component/balanceFunding/internal/actions.js.map +1 -0
  34. package/dist/component/balanceFunding/internal/mutations.d.ts +55 -0
  35. package/dist/component/balanceFunding/internal/mutations.d.ts.map +1 -0
  36. package/dist/component/balanceFunding/internal/mutations.js +54 -0
  37. package/dist/component/balanceFunding/internal/mutations.js.map +1 -0
  38. package/dist/component/balanceFunding/internal/queries.d.ts +116 -0
  39. package/dist/component/balanceFunding/internal/queries.d.ts.map +1 -0
  40. package/dist/component/balanceFunding/internal/queries.js +35 -0
  41. package/dist/component/balanceFunding/internal/queries.js.map +1 -0
  42. package/dist/component/balanceFunding/internal/workflow.d.ts +10 -0
  43. package/dist/component/balanceFunding/internal/workflow.d.ts.map +1 -0
  44. package/dist/component/balanceFunding/internal/workflow.js +31 -0
  45. package/dist/component/balanceFunding/internal/workflow.js.map +1 -0
  46. package/dist/component/balanceFunding/lifecycleHandlers.d.ts +126 -0
  47. package/dist/component/balanceFunding/lifecycleHandlers.d.ts.map +1 -1
  48. package/dist/component/balanceFunding/mutations.d.ts +403 -0
  49. package/dist/component/balanceFunding/mutations.d.ts.map +1 -1
  50. package/dist/component/balanceFunding/mutations.js +24 -0
  51. package/dist/component/balanceFunding/mutations.js.map +1 -1
  52. package/dist/component/balanceFunding/preparationHandlers.d.ts +42 -0
  53. package/dist/component/balanceFunding/preparationHandlers.d.ts.map +1 -1
  54. package/dist/component/balanceFunding/queries.d.ts +78 -0
  55. package/dist/component/balanceFunding/queries.d.ts.map +1 -1
  56. package/dist/component/balanceFunding/queries.js +35 -0
  57. package/dist/component/balanceFunding/queries.js.map +1 -1
  58. package/dist/component/balanceFunding/receipt.d.ts +5 -0
  59. package/dist/component/balanceFunding/receipt.d.ts.map +1 -0
  60. package/dist/component/balanceFunding/receipt.js +37 -0
  61. package/dist/component/balanceFunding/receipt.js.map +1 -0
  62. package/dist/component/balanceFunding/schema.d.ts +506 -2
  63. package/dist/component/balanceFunding/schema.d.ts.map +1 -1
  64. package/dist/component/balanceFunding/schema.js +2 -0
  65. package/dist/component/balanceFunding/schema.js.map +1 -1
  66. package/dist/component/balanceFunding/stateHandlers.d.ts +50 -8
  67. package/dist/component/balanceFunding/stateHandlers.d.ts.map +1 -1
  68. package/dist/component/balanceFunding/workflowControl.d.ts +19 -0
  69. package/dist/component/balanceFunding/workflowControl.d.ts.map +1 -0
  70. package/dist/component/balanceFunding/workflowControl.js +149 -0
  71. package/dist/component/balanceFunding/workflowControl.js.map +1 -0
  72. package/dist/component/balanceFunding/workflowSchema.d.ts +356 -0
  73. package/dist/component/balanceFunding/workflowSchema.d.ts.map +1 -0
  74. package/dist/component/balanceFunding/workflowSchema.js +48 -0
  75. package/dist/component/balanceFunding/workflowSchema.js.map +1 -0
  76. package/dist/component/balanceFunding/workflowState.d.ts +157 -0
  77. package/dist/component/balanceFunding/workflowState.d.ts.map +1 -0
  78. package/dist/component/balanceFunding/workflowState.js +194 -0
  79. package/dist/component/balanceFunding/workflowState.js.map +1 -0
  80. package/dist/component/balanceFunding/workflowValidators.d.ts +306 -0
  81. package/dist/component/balanceFunding/workflowValidators.d.ts.map +1 -0
  82. package/dist/component/balanceFunding/workflowValidators.js +27 -0
  83. package/dist/component/balanceFunding/workflowValidators.js.map +1 -0
  84. package/dist/component/earnings/triggers.d.ts +102 -18
  85. package/dist/component/earnings/triggers.d.ts.map +1 -1
  86. package/dist/component/schema.d.ts +183 -1
  87. package/package.json +1 -1
  88. package/src/client/balanceFundingWorkflow/capture.test.ts +144 -0
  89. package/src/client/balanceFundingWorkflow/client.ts +419 -0
  90. package/src/client/billing/balanceFunding.ts +50 -0
  91. package/src/client/index.ts +15 -0
  92. package/src/component/_generated/api.ts +18 -0
  93. package/src/component/_generated/component.ts +524 -0
  94. package/src/component/balanceFunding/internal/actions.ts +107 -0
  95. package/src/component/balanceFunding/internal/mutations.ts +66 -0
  96. package/src/component/balanceFunding/internal/queries.ts +34 -0
  97. package/src/component/balanceFunding/internal/workflow.ts +49 -0
  98. package/src/component/balanceFunding/mutations.ts +34 -0
  99. package/src/component/balanceFunding/queries.ts +38 -0
  100. package/src/component/balanceFunding/receipt.ts +48 -0
  101. package/src/component/balanceFunding/schema.ts +2 -0
  102. package/src/component/balanceFunding/scopeLookup.test.ts +94 -0
  103. package/src/component/balanceFunding/workflow.fixtures.ts +366 -0
  104. package/src/component/balanceFunding/workflow.test.ts +552 -0
  105. package/src/component/balanceFunding/workflowControl.ts +198 -0
  106. package/src/component/balanceFunding/workflowSchema.ts +78 -0
  107. package/src/component/balanceFunding/workflowState.ts +285 -0
  108. package/src/component/balanceFunding/workflowValidators.ts +40 -0
@@ -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
+ });