@fantastic.dev/better-stripe 0.37.0 → 0.38.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 (96) hide show
  1. package/CHANGELOG.md +64 -158
  2. package/README.md +5 -1
  3. package/dist/client/core/accountCapabilities.d.ts +20 -0
  4. package/dist/client/core/accountCapabilities.d.ts.map +1 -0
  5. package/dist/client/core/accountCapabilities.js +7 -0
  6. package/dist/client/core/accountCapabilities.js.map +1 -0
  7. package/dist/client/core/accountConfigurations.d.ts +46 -0
  8. package/dist/client/core/accountConfigurations.d.ts.map +1 -0
  9. package/dist/client/core/accountConfigurations.js +99 -0
  10. package/dist/client/core/accountConfigurations.js.map +1 -0
  11. package/dist/client/core/accountLinks.d.ts +29 -2
  12. package/dist/client/core/accountLinks.d.ts.map +1 -1
  13. package/dist/client/core/accountLinks.js +56 -4
  14. package/dist/client/core/accountLinks.js.map +1 -1
  15. package/dist/client/core/accounts.d.ts +2 -36
  16. package/dist/client/core/accounts.d.ts.map +1 -1
  17. package/dist/client/core/accounts.js +3 -73
  18. package/dist/client/core/accounts.js.map +1 -1
  19. package/dist/client/core/billingPortalClient.d.ts +14 -0
  20. package/dist/client/core/billingPortalClient.d.ts.map +1 -0
  21. package/dist/client/core/billingPortalClient.js +18 -0
  22. package/dist/client/core/billingPortalClient.js.map +1 -0
  23. package/dist/client/costRecovery-invoices.d.ts +4 -4
  24. package/dist/client/costRecovery.d.ts +1 -1
  25. package/dist/client/financialOutcomes/adapters.d.ts +18 -0
  26. package/dist/client/financialOutcomes/adapters.d.ts.map +1 -0
  27. package/dist/client/financialOutcomes/adapters.js +60 -0
  28. package/dist/client/financialOutcomes/adapters.js.map +1 -0
  29. package/dist/client/financialOutcomes/contracts.d.ts +42 -0
  30. package/dist/client/financialOutcomes/contracts.d.ts.map +1 -0
  31. package/dist/client/financialOutcomes/contracts.js +39 -0
  32. package/dist/client/financialOutcomes/contracts.js.map +1 -0
  33. package/dist/client/financialOutcomes/errors.d.ts +6 -0
  34. package/dist/client/financialOutcomes/errors.d.ts.map +1 -0
  35. package/dist/client/financialOutcomes/errors.js +22 -0
  36. package/dist/client/financialOutcomes/errors.js.map +1 -0
  37. package/dist/client/financialOutcomes/index.d.ts +6 -0
  38. package/dist/client/financialOutcomes/index.d.ts.map +1 -0
  39. package/dist/client/financialOutcomes/index.js +4 -0
  40. package/dist/client/financialOutcomes/index.js.map +1 -0
  41. package/dist/client/financialOutcomes/retry.d.ts +24 -0
  42. package/dist/client/financialOutcomes/retry.d.ts.map +1 -0
  43. package/dist/client/financialOutcomes/retry.js +31 -0
  44. package/dist/client/financialOutcomes/retry.js.map +1 -0
  45. package/dist/client/index.d.ts +20 -111
  46. package/dist/client/index.d.ts.map +1 -1
  47. package/dist/client/index.js +10 -85
  48. package/dist/client/index.js.map +1 -1
  49. package/dist/client/products/catalog.d.ts +26 -0
  50. package/dist/client/products/catalog.d.ts.map +1 -0
  51. package/dist/client/products/catalog.js +140 -0
  52. package/dist/client/products/catalog.js.map +1 -0
  53. package/dist/client/products/catalogClient.d.ts +109 -0
  54. package/dist/client/products/catalogClient.d.ts.map +1 -0
  55. package/dist/client/products/catalogClient.js +84 -0
  56. package/dist/client/products/catalogClient.js.map +1 -0
  57. package/dist/client/products/prices.d.ts +1 -0
  58. package/dist/client/products/prices.d.ts.map +1 -1
  59. package/dist/client/products/prices.js +1 -0
  60. package/dist/client/products/prices.js.map +1 -1
  61. package/dist/client/publicTypes.d.ts +2 -0
  62. package/dist/client/publicTypes.d.ts.map +1 -1
  63. package/dist/component/_generated/component.d.ts +8 -0
  64. package/dist/component/_generated/component.d.ts.map +1 -1
  65. package/dist/component/products/mutations.d.ts +9 -0
  66. package/dist/component/products/mutations.d.ts.map +1 -1
  67. package/dist/component/products/mutations.js +31 -2
  68. package/dist/component/products/mutations.js.map +1 -1
  69. package/docs/read-contracts.md +33 -0
  70. package/package.json +1 -1
  71. package/src/client/core/account-session-client.test.ts +74 -0
  72. package/src/client/core/accountCapabilities.ts +22 -0
  73. package/src/client/core/accountConfigurations.test.ts +183 -0
  74. package/src/client/core/accountConfigurations.ts +161 -0
  75. package/src/client/core/accountLinks.test.ts +6 -2
  76. package/src/client/core/accountLinks.ts +122 -5
  77. package/src/client/core/accounts.ts +8 -115
  78. package/src/client/core/billingPortal.test.ts +247 -0
  79. package/src/client/core/billingPortalClient.ts +35 -0
  80. package/src/client/financialOutcomes/adapters.ts +88 -0
  81. package/src/client/financialOutcomes/contracts.ts +43 -0
  82. package/src/client/financialOutcomes/errors.ts +29 -0
  83. package/src/client/financialOutcomes/index.ts +5 -0
  84. package/src/client/financialOutcomes/outcomes.test.ts +254 -0
  85. package/src/client/financialOutcomes/retry.ts +52 -0
  86. package/src/client/index.test.ts +0 -64
  87. package/src/client/index.ts +34 -185
  88. package/src/client/products/catalog.test.ts +389 -0
  89. package/src/client/products/catalog.ts +225 -0
  90. package/src/client/products/catalogClient.ts +172 -0
  91. package/src/client/products/prices.test.ts +24 -0
  92. package/src/client/products/prices.ts +2 -0
  93. package/src/client/publicTypes.ts +13 -0
  94. package/src/component/_generated/api.ts +4 -0
  95. package/src/component/_generated/component.ts +14 -0
  96. package/src/component/products/mutations.ts +39 -2
@@ -6,6 +6,15 @@ export declare const upsertProduct: import("convex/server").RegisteredMutation<"
6
6
  name: string;
7
7
  stripeProductId: string;
8
8
  }, Promise<null>>;
9
+ /** Atomically import provider fields without reassigning a claimed owner. */
10
+ export declare const adoptProduct: import("convex/server").RegisteredMutation<"public", {
11
+ accountId?: string | undefined;
12
+ active: boolean;
13
+ description?: string | undefined;
14
+ metadata?: any;
15
+ name: string;
16
+ stripeProductId: string;
17
+ }, Promise<null>>;
9
18
  export declare const upsertPrice: import("convex/server").RegisteredMutation<"public", {
10
19
  active: boolean;
11
20
  currency: string;
@@ -1 +1 @@
1
- {"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../../src/component/products/mutations.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,aAAa;;;;;;;iBA0BxB,CAAC;AAMH,eAAO,MAAM,WAAW;;;;;;;;;;;;iBA+BtB,CAAC"}
1
+ {"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../../src/component/products/mutations.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,aAAa;;;;;;;iBA0BxB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,YAAY;;;;;;;iBA8BvB,CAAC;AAMH,eAAO,MAAM,WAAW;;;;;;;;;;;;iBA+BtB,CAAC"}
@@ -1,6 +1,6 @@
1
- import { v } from "convex/values";
1
+ import { ConvexError, v } from "convex/values";
2
2
  import { mutation } from "../_generated/server";
3
- import { priceIntervalValidator, priceTypeValidator } from "./validators";
3
+ import { priceIntervalValidator, priceTypeValidator, productFields, } from "./validators";
4
4
  // =============================================================================
5
5
  // PRODUCT MUTATIONS
6
6
  // =============================================================================
@@ -28,6 +28,35 @@ export const upsertProduct = mutation({
28
28
  return null;
29
29
  },
30
30
  });
31
+ /** Atomically import provider fields without reassigning a claimed owner. */
32
+ export const adoptProduct = mutation({
33
+ args: productFields,
34
+ returns: v.null(),
35
+ handler: async (ctx, args) => {
36
+ const existing = await ctx.db
37
+ .query("products")
38
+ .withIndex("by_stripe_product_id", (q) => q.eq("stripeProductId", args.stripeProductId))
39
+ .first();
40
+ if (existing?.accountId !== undefined &&
41
+ args.accountId !== undefined &&
42
+ existing.accountId !== args.accountId) {
43
+ throw new ConvexError({
44
+ code: "INVALID_CONFIGURATION",
45
+ message: "Product ownership cannot be reassigned by adoption",
46
+ });
47
+ }
48
+ if (existing) {
49
+ await ctx.db.patch("products", existing._id, {
50
+ ...args,
51
+ accountId: existing.accountId ?? args.accountId,
52
+ });
53
+ }
54
+ else {
55
+ await ctx.db.insert("products", args);
56
+ }
57
+ return null;
58
+ },
59
+ });
31
60
  // =============================================================================
32
61
  // PRICE MUTATIONS
33
62
  // =============================================================================
@@ -1 +1 @@
1
- {"version":3,"file":"mutations.js","sourceRoot":"","sources":["../../../src/component/products/mutations.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"mutations.js","sourceRoot":"","sources":["../../../src/component/products/mutations.ts"],"names":[],"mappings":"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"}
@@ -322,3 +322,36 @@ partial-capture units, history budgets and creation-time host obligations are
322
322
  specified in [refund context](./refund-context.md). Invoice allocations and
323
323
  authorized gross amounts are not remaining refundable principal. No access,
324
324
  subscription or financial state is changed by this reader.
325
+
326
+ ## Financial readiness and bounded retries
327
+
328
+ The additive `verifiedSaleOutcome` and `processingCostOutcome` adapters preserve
329
+ the original SDK reader results. A ready outcome contains that result in
330
+ `value`. Missing provider data becomes `not_ready` with `provider_pending` or
331
+ `fee_pending`; it never becomes a zero fee. Unsupported sources and currency
332
+ mismatches are rejected. Unknown legacy reason strings fail closed.
333
+
334
+ `FinancialUnavailable` distinguishes pending reads, conflicts, rejections and
335
+ uncertain provider writes. A conflict requires fresh state and a policy decision.
336
+ An `unknown` provider outcome requires reconciliation of the original operation
337
+ and receipts before another write. Bounded history that is still incomplete
338
+ after exhaustion must remain unknown.
339
+
340
+ `financialRetryDecision(outcome, attempt, policy)` is a pure scheduling decision.
341
+ It retries only validated `not_ready` outcomes. The caller supplies all policy
342
+ fields: `maxRetries` from 0 to 20, positive integer `initialDelayMs`, and
343
+ `maxDelayMs` no greater than one day or less than the initial delay. Attempt zero
344
+ is the initial call; a limit of ten allows ten additional calls. Delays double
345
+ until the configured cap. Exhaustion returns `stop/exhausted`. The helper runs
346
+ no action and provides no permission to repeat an uncertain money movement.
347
+
348
+ `throwFinancialOutcome` carries only the validated status, reason and retryable
349
+ flag in a structured Convex error. `readFinancialOutcomeError` reads that data
350
+ across action boundaries, without inspecting exception messages. Other errors
351
+ propagate unchanged. These helpers do not classify transport errors or establish
352
+ whether a provider write succeeded.
353
+
354
+ The example settlement and processing-cost wrappers use ten retries, a one-second
355
+ initial delay and a one-minute cap. They retry structured readiness observations.
356
+ Revision conflicts and terminal errors now propagate for fresh-state handling
357
+ instead of matching English text and rerunning the financial action.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.37.0",
3
+ "version": "0.38.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -0,0 +1,74 @@
1
+ import { ConvexError } from "convex/values";
2
+ import { beforeEach, describe, expect, it, vi } from "vitest";
3
+ import { components } from "../setup.test.js";
4
+
5
+ const { create } = vi.hoisted(() => ({ create: vi.fn() }));
6
+ vi.mock("stripe", () => ({
7
+ default: class {
8
+ accountSessions = { create };
9
+ },
10
+ }));
11
+ const { BetterStripe } = await import("../index.js");
12
+ const mockCtx = { runQuery: vi.fn(), runMutation: vi.fn(), runAction: vi.fn() };
13
+ beforeEach(() => vi.resetAllMocks());
14
+
15
+ describe("createAccountSession", () => {
16
+ it("returns the provider client secret and expiry through BetterStripe", async () => {
17
+ const bs = new BetterStripe(components.betterStripe, {
18
+ STRIPE_SECRET_KEY: "sk_test_xxx",
19
+ });
20
+
21
+ create.mockResolvedValue({
22
+ client_secret: "as_secret_123",
23
+ expires_at: 1234567890,
24
+ });
25
+
26
+ const result = await bs.createAccountSession(mockCtx, {
27
+ stripeAccountId: "acct_123",
28
+ components: {
29
+ account_management: { enabled: true },
30
+ },
31
+ });
32
+
33
+ expect(create).toHaveBeenCalledWith({
34
+ account: "acct_123",
35
+ components: {
36
+ account_management: { enabled: true },
37
+ },
38
+ });
39
+ expect(result).toEqual({
40
+ clientSecret: "as_secret_123",
41
+ expiresAt: 1234567890,
42
+ });
43
+ });
44
+
45
+ it("wraps Stripe failures in a structured STRIPE_API_ERROR", async () => {
46
+ const bs = new BetterStripe(components.betterStripe, {
47
+ STRIPE_SECRET_KEY: "sk_test_xxx",
48
+ });
49
+
50
+ create.mockRejectedValue(
51
+ Object.assign(new Error("No such account: acct_missing"), {
52
+ type: "StripeInvalidRequestError",
53
+ code: "resource_missing",
54
+ }),
55
+ );
56
+
57
+ const error = await bs
58
+ .createAccountSession(mockCtx, {
59
+ stripeAccountId: "acct_missing",
60
+ components: { account_onboarding: { enabled: true } },
61
+ })
62
+ .catch((e: unknown) => e);
63
+
64
+ expect(error).toBeInstanceOf(ConvexError);
65
+ expect((error as { data: Record<string, unknown> }).data).toMatchObject({
66
+ code: "STRIPE_API_ERROR",
67
+ stripeError: {
68
+ type: "StripeInvalidRequestError",
69
+ code: "resource_missing",
70
+ message: "No such account: acct_missing",
71
+ },
72
+ });
73
+ });
74
+ });
@@ -0,0 +1,22 @@
1
+ /** Provider capability shape shared by V1 and V2 accounts. */
2
+ export type TransferCapabilityAccount = {
3
+ configuration?: {
4
+ recipient?: {
5
+ capabilities?: {
6
+ stripe_balance?: { stripe_transfers?: { status?: string } };
7
+ };
8
+ } | null;
9
+ } | null;
10
+ capabilities?: { transfers?: string } | null;
11
+ };
12
+
13
+ /** True when Stripe reports active recipient transfers in either supported API shape. */
14
+ export function canReceiveTransfers(
15
+ account: TransferCapabilityAccount | null | undefined,
16
+ ): boolean {
17
+ return (
18
+ account?.configuration?.recipient?.capabilities?.stripe_balance
19
+ ?.stripe_transfers?.status === "active" ||
20
+ account?.capabilities?.transfers === "active"
21
+ );
22
+ }
@@ -0,0 +1,183 @@
1
+ // @vitest-environment edge-runtime
2
+ import { describe, expect, it, vi } from "vitest";
3
+ import type Stripe from "stripe";
4
+ import type { Component, RunCtx } from "../helpers.js";
5
+ import { components, initConvexTest } from "../setup.test.js";
6
+ import schema from "../../component/schema.js";
7
+ import * as accounts from "./accounts.js";
8
+
9
+ const modules = import.meta.glob("../../component/**/*.{ts,js,tsx,jsx}");
10
+ function setup() {
11
+ const t = initConvexTest();
12
+ t.registerComponent("betterStripe", schema, modules);
13
+ const component = components.betterStripe as unknown as Component;
14
+ const ctx = {
15
+ runQuery: (ref: any, args: any) => t.query(ref, args),
16
+ runMutation: (ref: any, args: any) => t.mutation(ref, args),
17
+ } as RunCtx;
18
+ const update = vi.fn().mockResolvedValue({});
19
+ const retrieve = vi.fn().mockResolvedValue({
20
+ id: "acct_merchant",
21
+ applied_configurations: ["recipient", "merchant"],
22
+ });
23
+ const stripe = {
24
+ v2: { core: { accounts: { update, retrieve } } },
25
+ } as unknown as Stripe;
26
+ return { t, component, ctx, stripe, update, retrieve };
27
+ }
28
+
29
+ describe("merchant configuration", () => {
30
+ it("requests card payments and persists only the target account without changing ownership", async () => {
31
+ const { t, component, ctx, stripe, update, retrieve } = setup();
32
+ for (const stripeAccountId of ["acct_merchant", "acct_other"]) {
33
+ await t.mutation(component.core.mutations.upsertAccount, {
34
+ stripeAccountId,
35
+ userId: "owner",
36
+ orgId: "org",
37
+ appliedConfigurations: ["recipient"],
38
+ });
39
+ }
40
+ expect(typeof accounts.addMerchantConfiguration).toBe("function");
41
+ const result = await accounts.addMerchantConfiguration(
42
+ stripe,
43
+ component,
44
+ ctx,
45
+ { stripeAccountId: "acct_merchant" },
46
+ );
47
+ expect(result).toEqual({
48
+ success: true,
49
+ appliedConfigurations: ["recipient", "merchant"],
50
+ });
51
+ expect(update).toHaveBeenCalledWith("acct_merchant", {
52
+ configuration: {
53
+ merchant: { capabilities: { card_payments: { requested: true } } },
54
+ },
55
+ });
56
+ expect(retrieve).toHaveBeenCalledWith("acct_merchant");
57
+ expect(
58
+ await t.query(component.core.queries.getAccountByStripeId, {
59
+ stripeAccountId: "acct_merchant",
60
+ }),
61
+ ).toMatchObject({
62
+ userId: "owner",
63
+ orgId: "org",
64
+ appliedConfigurations: ["recipient", "merchant"],
65
+ });
66
+ expect(
67
+ await t.query(component.core.queries.getAccountByStripeId, {
68
+ stripeAccountId: "acct_other",
69
+ }),
70
+ ).toMatchObject({ appliedConfigurations: ["recipient"] });
71
+ });
72
+
73
+ it.each([
74
+ "addMerchantConfiguration",
75
+ "addCustomerConfiguration",
76
+ "addRecipientConfiguration",
77
+ ] as const)(
78
+ "%s preserves organization ownership pinned by a pending closure",
79
+ async (method) => {
80
+ const { t, component, ctx, stripe } = setup();
81
+ await t.mutation(component.core.mutations.upsertAccount, {
82
+ stripeAccountId: "acct_merchant",
83
+ userId: "owner",
84
+ orgId: "org",
85
+ appliedConfigurations: ["recipient"],
86
+ });
87
+ await t.mutation(component.accountClosure.mutations.prepare, {
88
+ stripeAccountId: "acct_merchant",
89
+ });
90
+ await accounts[method](stripe, component, ctx, {
91
+ stripeAccountId: "acct_merchant",
92
+ });
93
+ expect(
94
+ await t.query(component.core.queries.getAccountByStripeId, {
95
+ stripeAccountId: "acct_merchant",
96
+ }),
97
+ ).toMatchObject({
98
+ userId: "owner",
99
+ orgId: "org",
100
+ appliedConfigurations: ["recipient", "merchant"],
101
+ });
102
+ },
103
+ );
104
+
105
+ it("rejects missing component ownership before provider mutation", async () => {
106
+ const { component, ctx, stripe, update } = setup();
107
+ expect(typeof accounts.addMerchantConfiguration).toBe("function");
108
+ await expect(
109
+ accounts.addMerchantConfiguration(stripe, component, ctx, {
110
+ stripeAccountId: "acct_missing",
111
+ }),
112
+ ).rejects.toMatchObject({ data: { code: "ACCOUNT_NOT_FOUND" } });
113
+ expect(update).not.toHaveBeenCalled();
114
+ });
115
+
116
+ it("propagates failed readback and recovers on retry with provider configurations", async () => {
117
+ const { t, component, ctx, stripe, retrieve } = setup();
118
+ await t.mutation(component.core.mutations.upsertAccount, {
119
+ stripeAccountId: "acct_merchant",
120
+ userId: "owner",
121
+ appliedConfigurations: ["recipient"],
122
+ });
123
+ retrieve.mockRejectedValueOnce(new Error("readback unavailable"));
124
+ expect(typeof accounts.addMerchantConfiguration).toBe("function");
125
+ await expect(
126
+ accounts.addMerchantConfiguration(stripe, component, ctx, {
127
+ stripeAccountId: "acct_merchant",
128
+ }),
129
+ ).rejects.toThrow("readback unavailable");
130
+ expect(
131
+ await t.query(component.core.queries.getAccountByStripeId, {
132
+ stripeAccountId: "acct_merchant",
133
+ }),
134
+ ).toMatchObject({ appliedConfigurations: ["recipient"] });
135
+ await accounts.addMerchantConfiguration(stripe, component, ctx, {
136
+ stripeAccountId: "acct_merchant",
137
+ });
138
+ expect(
139
+ await t.query(component.core.queries.getAccountByStripeId, {
140
+ stripeAccountId: "acct_merchant",
141
+ }),
142
+ ).toMatchObject({ appliedConfigurations: ["recipient", "merchant"] });
143
+ });
144
+ });
145
+
146
+ describe("transfer capability", () => {
147
+ it("accepts active V2 recipient transfers and V1 transfers", () => {
148
+ expect(typeof accounts.canReceiveTransfers).toBe("function");
149
+ expect(
150
+ accounts.canReceiveTransfers({
151
+ configuration: {
152
+ recipient: {
153
+ capabilities: {
154
+ stripe_balance: { stripe_transfers: { status: "active" } },
155
+ },
156
+ },
157
+ },
158
+ }),
159
+ ).toBe(true);
160
+ expect(
161
+ accounts.canReceiveTransfers({ capabilities: { transfers: "active" } }),
162
+ ).toBe(true);
163
+ });
164
+ it.each([
165
+ null,
166
+ undefined,
167
+ {},
168
+ { capabilities: { transfers: "pending" } },
169
+ { configuration: { recipient: null } },
170
+ {
171
+ configuration: {
172
+ recipient: {
173
+ capabilities: {
174
+ stripe_balance: { stripe_transfers: { status: "inactive" } },
175
+ },
176
+ },
177
+ },
178
+ },
179
+ ])("rejects absent or unready capability %#", (account) => {
180
+ expect(typeof accounts.canReceiveTransfers).toBe("function");
181
+ expect(accounts.canReceiveTransfers(account)).toBe(false);
182
+ });
183
+ });
@@ -0,0 +1,161 @@
1
+ import type Stripe from "stripe";
2
+ import type { Component, RunCtx } from "../helpers.js";
3
+ import { runMutationOrThrow } from "../helpers.js";
4
+ import { throwStripeError } from "../errors.js";
5
+ import type { V2AccountUpdateParams } from "../stripe-types.js";
6
+ import type { StripeComponentAccount } from "../types.js";
7
+ import { componentRef } from "../webhooks/helpers.js";
8
+ import { DEFAULT_ACCOUNT_CONFIGURATION } from "./accountDefaults.js";
9
+
10
+ /**
11
+ * Default V2 customer configuration. Applying the customer configuration is
12
+ * what makes a V2 Account billable — the customer-facing payment/billing flows
13
+ * (subscriptions, invoices, billing portal). In the V2 Accounts API a single
14
+ * Account with this configuration replaces the legacy V1 Customer object, so
15
+ * `customer_account: acct_…` is what you pass to subscriptions, setup intents,
16
+ * and billing-portal sessions. No capabilities are requested by default;
17
+ * request `customer.capabilities.automatic_indirect_tax` separately if you need
18
+ * automatic tax on this account's invoices/subscriptions.
19
+ */
20
+ export const DEFAULT_CUSTOMER_CONFIGURATION: Record<string, unknown> = {
21
+ customer: {},
22
+ };
23
+
24
+ /**
25
+ * Apply the customer configuration to an existing V2 Account, making it
26
+ * billable, and record the resulting applied configurations on the component
27
+ * account. The account must already exist in the component DB (e.g. created via
28
+ * `createAccount`); its owning `userId` is recovered from that record.
29
+ */
30
+ export async function addCustomerConfiguration(
31
+ stripe: Stripe,
32
+ component: Component,
33
+ ctx: RunCtx,
34
+ opts: { stripeAccountId: string },
35
+ ): Promise<{ success: true; appliedConfigurations: string[] }> {
36
+ const existing = (await ctx.runQuery(
37
+ componentRef(component, "core/queries/getAccountByStripeId"),
38
+ { stripeAccountId: opts.stripeAccountId },
39
+ )) as StripeComponentAccount | null;
40
+
41
+ if (!existing) {
42
+ throwStripeError(
43
+ "ACCOUNT_NOT_FOUND",
44
+ `No component account found for ${opts.stripeAccountId}; create it before applying the customer configuration`,
45
+ );
46
+ }
47
+
48
+ await stripe.v2.core.accounts.update(opts.stripeAccountId, {
49
+ configuration: DEFAULT_CUSTOMER_CONFIGURATION,
50
+ } as V2AccountUpdateParams);
51
+
52
+ // Re-fetch to record the configurations Stripe actually applied
53
+ const updated = await stripe.v2.core.accounts.retrieve(opts.stripeAccountId);
54
+ const appliedConfigurations = updated.applied_configurations ?? [];
55
+
56
+ await runMutationOrThrow(
57
+ ctx,
58
+ componentRef(component, "core/mutations/upsertAccount"),
59
+ {
60
+ stripeAccountId: opts.stripeAccountId,
61
+ userId: existing.userId,
62
+ ...(existing.orgId !== undefined ? { orgId: existing.orgId } : {}),
63
+ appliedConfigurations,
64
+ },
65
+ );
66
+
67
+ return { success: true, appliedConfigurations };
68
+ }
69
+
70
+ /**
71
+ * Apply the V2 recipient configuration to an existing account, and record the
72
+ * resulting applied configurations on the component account. The account must
73
+ * already exist in the component DB (e.g. from {@link createAccount}); its
74
+ * owning `userId` is recovered from that record, matching
75
+ * {@link addCustomerConfiguration}.
76
+ */
77
+ export async function addRecipientConfiguration(
78
+ stripe: Stripe,
79
+ component: Component,
80
+ ctx: RunCtx,
81
+ opts: { stripeAccountId: string },
82
+ ): Promise<{ success: true; appliedConfigurations: string[] }> {
83
+ const existing = (await ctx.runQuery(
84
+ componentRef(component, "core/queries/getAccountByStripeId"),
85
+ { stripeAccountId: opts.stripeAccountId },
86
+ )) as StripeComponentAccount | null;
87
+
88
+ if (!existing) {
89
+ throwStripeError(
90
+ "ACCOUNT_NOT_FOUND",
91
+ `No component account found for ${opts.stripeAccountId}; create it before applying the recipient configuration`,
92
+ );
93
+ }
94
+
95
+ await stripe.v2.core.accounts.update(opts.stripeAccountId, {
96
+ configuration: {
97
+ recipient: {
98
+ // V2 (API 2026-05-27.dahlia) requires the `capabilities` wrapper with an
99
+ // explicit `requested: true`. The bare `recipient.stripe_balance` shape
100
+ // is rejected with "Unknown field" (confirmed against the Stripe sandbox).
101
+ capabilities: {
102
+ stripe_balance: {
103
+ stripe_transfers: { requested: true },
104
+ },
105
+ },
106
+ },
107
+ },
108
+ } as V2AccountUpdateParams);
109
+
110
+ // Re-fetch to record the configurations Stripe actually applied
111
+ const updated = await stripe.v2.core.accounts.retrieve(opts.stripeAccountId);
112
+ const appliedConfigurations = updated.applied_configurations ?? [];
113
+
114
+ await runMutationOrThrow(
115
+ ctx,
116
+ componentRef(component, "core/mutations/upsertAccount"),
117
+ {
118
+ stripeAccountId: opts.stripeAccountId,
119
+ userId: existing.userId,
120
+ ...(existing.orgId !== undefined ? { orgId: existing.orgId } : {}),
121
+ appliedConfigurations,
122
+ },
123
+ );
124
+
125
+ return { success: true, appliedConfigurations };
126
+ }
127
+
128
+ /** Request merchant card payments and refresh only this account's applied configurations. */
129
+ export async function addMerchantConfiguration(
130
+ stripe: Stripe,
131
+ component: Component,
132
+ ctx: RunCtx,
133
+ opts: { stripeAccountId: string },
134
+ ): Promise<{ success: true; appliedConfigurations: string[] }> {
135
+ const existing = (await ctx.runQuery(
136
+ componentRef(component, "core/queries/getAccountByStripeId"),
137
+ { stripeAccountId: opts.stripeAccountId },
138
+ )) as StripeComponentAccount | null;
139
+ if (!existing) {
140
+ throwStripeError(
141
+ "ACCOUNT_NOT_FOUND",
142
+ `No component account found for ${opts.stripeAccountId}; create it before applying the merchant configuration`,
143
+ );
144
+ }
145
+ await stripe.v2.core.accounts.update(opts.stripeAccountId, {
146
+ configuration: DEFAULT_ACCOUNT_CONFIGURATION,
147
+ } as V2AccountUpdateParams);
148
+ const updated = await stripe.v2.core.accounts.retrieve(opts.stripeAccountId);
149
+ const appliedConfigurations = updated.applied_configurations ?? [];
150
+ await runMutationOrThrow(
151
+ ctx,
152
+ componentRef(component, "core/mutations/upsertAccount"),
153
+ {
154
+ stripeAccountId: opts.stripeAccountId,
155
+ userId: existing.userId,
156
+ ...(existing.orgId !== undefined ? { orgId: existing.orgId } : {}),
157
+ appliedConfigurations,
158
+ },
159
+ );
160
+ return { success: true, appliedConfigurations };
161
+ }
@@ -169,10 +169,11 @@ describe("createV2AccountLink", () => {
169
169
  });
170
170
 
171
171
  describe("createAccountSession", () => {
172
- it("returns the client secret on success", async () => {
172
+ it("returns the provider client secret and expiry on success", async () => {
173
173
  const stripe = makeStripe();
174
174
  stripe.accountSessions.create.mockResolvedValue({
175
175
  client_secret: "secret_123",
176
+ expires_at: 1234567890,
176
177
  });
177
178
 
178
179
  const result = await createAccountSession(asStripe(stripe), ctx, {
@@ -180,7 +181,10 @@ describe("createAccountSession", () => {
180
181
  components: { account_onboarding: { enabled: true } },
181
182
  });
182
183
 
183
- expect(result).toEqual({ clientSecret: "secret_123" });
184
+ expect(result).toEqual({
185
+ clientSecret: "secret_123",
186
+ expiresAt: 1234567890,
187
+ });
184
188
  expect(stripe.accountSessions.create).toHaveBeenCalledWith({
185
189
  account: "acct_5",
186
190
  components: { account_onboarding: { enabled: true } },