@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
@@ -107,7 +107,10 @@ export async function createAccountSession(
107
107
  account: opts.stripeAccountId,
108
108
  components: opts.components,
109
109
  });
110
- return { clientSecret: session.client_secret };
110
+ return {
111
+ clientSecret: session.client_secret,
112
+ expiresAt: session.expires_at,
113
+ };
111
114
  } catch (error) {
112
115
  throwStripeError(
113
116
  "STRIPE_API_ERROR",
@@ -182,16 +185,130 @@ export async function getAccountLinkWithStatus(
182
185
  return getOnboardingLink();
183
186
  }
184
187
 
188
+ /** The connected account that owns the configuration and its customer data.
189
+ * Omit for platform scope. Hosts must authorize both this scope and the customer.
190
+ */
191
+ type BillingPortalScope = { connectedAccountId?: string };
192
+
193
+ export type CreateBillingPortalConfigurationOptions = BillingPortalScope & {
194
+ /** Host-owned allowlists, proration, cancellation, and branding policy. */
195
+ params: Stripe.BillingPortal.ConfigurationCreateParams;
196
+ };
197
+ export type RetrieveBillingPortalConfigurationOptions = BillingPortalScope & {
198
+ configurationId: string;
199
+ };
200
+ export type UpdateBillingPortalConfigurationOptions = BillingPortalScope & {
201
+ configurationId: string;
202
+ params: Stripe.BillingPortal.ConfigurationUpdateParams;
203
+ };
204
+ export type CreateBillingPortalSessionOptions = BillingPortalScope & {
205
+ /** Customer account opening the portal, distinct from connectedAccountId. */
206
+ stripeAccountId: string;
207
+ returnUrl: string;
208
+ /** Omit to use Stripe's default portal configuration. */
209
+ configurationId?: string;
210
+ };
211
+
212
+ export async function createBillingPortalConfiguration(
213
+ stripe: Stripe,
214
+ _ctx: RunCtx,
215
+ opts: CreateBillingPortalConfigurationOptions,
216
+ ): Promise<Stripe.BillingPortal.Configuration> {
217
+ try {
218
+ return opts.connectedAccountId !== undefined
219
+ ? await stripe.billingPortal.configurations.create(opts.params, {
220
+ stripeAccount: opts.connectedAccountId,
221
+ })
222
+ : await stripe.billingPortal.configurations.create(opts.params);
223
+ } catch (error) {
224
+ throwStripeError(
225
+ "STRIPE_API_ERROR",
226
+ "Failed to create Billing Portal configuration",
227
+ error,
228
+ );
229
+ }
230
+ }
231
+
232
+ export async function retrieveBillingPortalConfiguration(
233
+ stripe: Stripe,
234
+ _ctx: RunCtx,
235
+ opts: RetrieveBillingPortalConfigurationOptions,
236
+ ): Promise<Stripe.BillingPortal.Configuration> {
237
+ try {
238
+ return opts.connectedAccountId !== undefined
239
+ ? await stripe.billingPortal.configurations.retrieve(
240
+ opts.configurationId,
241
+ {},
242
+ {
243
+ stripeAccount: opts.connectedAccountId,
244
+ },
245
+ )
246
+ : await stripe.billingPortal.configurations.retrieve(
247
+ opts.configurationId,
248
+ );
249
+ } catch (error) {
250
+ throwStripeError(
251
+ "STRIPE_API_ERROR",
252
+ "Failed to retrieve Billing Portal configuration",
253
+ error,
254
+ );
255
+ }
256
+ }
257
+
258
+ export async function updateBillingPortalConfiguration(
259
+ stripe: Stripe,
260
+ _ctx: RunCtx,
261
+ opts: UpdateBillingPortalConfigurationOptions,
262
+ ): Promise<Stripe.BillingPortal.Configuration> {
263
+ try {
264
+ return opts.connectedAccountId !== undefined
265
+ ? await stripe.billingPortal.configurations.update(
266
+ opts.configurationId,
267
+ opts.params,
268
+ {
269
+ stripeAccount: opts.connectedAccountId,
270
+ },
271
+ )
272
+ : await stripe.billingPortal.configurations.update(
273
+ opts.configurationId,
274
+ opts.params,
275
+ );
276
+ } catch (error) {
277
+ throwStripeError(
278
+ "STRIPE_API_ERROR",
279
+ "Failed to update Billing Portal configuration",
280
+ error,
281
+ );
282
+ }
283
+ }
284
+
185
285
  export async function createBillingPortalSession(
186
286
  stripe: Stripe,
187
287
  _ctx: RunCtx,
188
- opts: { stripeAccountId: string; returnUrl: string },
288
+ opts: CreateBillingPortalSessionOptions,
189
289
  ) {
190
- const session = await stripe.billingPortal.sessions.create({
290
+ const params: Stripe.BillingPortal.SessionCreateParams = {
191
291
  customer_account: opts.stripeAccountId,
192
292
  return_url: opts.returnUrl,
193
- });
194
- return { url: session.url };
293
+ ...(opts.configurationId !== undefined
294
+ ? { configuration: opts.configurationId }
295
+ : {}),
296
+ };
297
+ try {
298
+ const session =
299
+ opts.connectedAccountId !== undefined
300
+ ? await stripe.billingPortal.sessions.create(params, {
301
+ stripeAccount: opts.connectedAccountId,
302
+ })
303
+ : await stripe.billingPortal.sessions.create(params);
304
+ return { url: session.url };
305
+ } catch (error) {
306
+ throwStripeError(
307
+ "STRIPE_API_ERROR",
308
+ "Failed to create Billing Portal session",
309
+ error,
310
+ );
311
+ }
195
312
  }
196
313
 
197
314
  export async function getCountrySpecs(
@@ -1,3 +1,4 @@
1
+ import { addCustomerConfiguration } from "./accountConfigurations.js";
1
2
  import { idempotencyOptions } from "./idempotency.js";
2
3
  export type CreateAccountOptions = {
3
4
  userId: string;
@@ -474,121 +475,13 @@ export async function restartAccountOnboarding(
474
475
  return closeAccount(stripe, component, ctx, opts);
475
476
  }
476
477
 
477
- /**
478
- * Default V2 customer configuration. Applying the customer configuration is
479
- * what makes a V2 Account billable — the customer-facing payment/billing flows
480
- * (subscriptions, invoices, billing portal). In the V2 Accounts API a single
481
- * Account with this configuration replaces the legacy V1 Customer object, so
482
- * `customer_account: acct_…` is what you pass to subscriptions, setup intents,
483
- * and billing-portal sessions. No capabilities are requested by default;
484
- * request `customer.capabilities.automatic_indirect_tax` separately if you need
485
- * automatic tax on this account's invoices/subscriptions.
486
- */
487
- export const DEFAULT_CUSTOMER_CONFIGURATION: Record<string, unknown> = {
488
- customer: {},
489
- };
490
-
491
- /**
492
- * Apply the customer configuration to an existing V2 Account, making it
493
- * billable, and record the resulting applied configurations on the component
494
- * account. The account must already exist in the component DB (e.g. created via
495
- * `createAccount`); its owning `userId` is recovered from that record.
496
- */
497
- export async function addCustomerConfiguration(
498
- stripe: Stripe,
499
- component: Component,
500
- ctx: RunCtx,
501
- opts: { stripeAccountId: string },
502
- ): Promise<{ success: true; appliedConfigurations: string[] }> {
503
- const existing = (await ctx.runQuery(
504
- componentRef(component, "core/queries/getAccountByStripeId"),
505
- { stripeAccountId: opts.stripeAccountId },
506
- )) as StripeComponentAccount | null;
507
-
508
- if (!existing) {
509
- throwStripeError(
510
- "ACCOUNT_NOT_FOUND",
511
- `No component account found for ${opts.stripeAccountId}; create it before applying the customer configuration`,
512
- );
513
- }
514
-
515
- await stripe.v2.core.accounts.update(opts.stripeAccountId, {
516
- configuration: DEFAULT_CUSTOMER_CONFIGURATION,
517
- } as V2AccountUpdateParams);
518
-
519
- // Re-fetch to record the configurations Stripe actually applied
520
- const updated = await stripe.v2.core.accounts.retrieve(opts.stripeAccountId);
521
- const appliedConfigurations = updated.applied_configurations ?? [];
522
-
523
- await runMutationOrThrow(
524
- ctx,
525
- componentRef(component, "core/mutations/upsertAccount"),
526
- {
527
- stripeAccountId: opts.stripeAccountId,
528
- userId: existing.userId,
529
- appliedConfigurations,
530
- },
531
- );
532
-
533
- return { success: true, appliedConfigurations };
534
- }
535
-
536
- /**
537
- * Apply the V2 recipient configuration to an existing account, and record the
538
- * resulting applied configurations on the component account. The account must
539
- * already exist in the component DB (e.g. from {@link createAccount}); its
540
- * owning `userId` is recovered from that record, matching
541
- * {@link addCustomerConfiguration}.
542
- */
543
- export async function addRecipientConfiguration(
544
- stripe: Stripe,
545
- component: Component,
546
- ctx: RunCtx,
547
- opts: { stripeAccountId: string },
548
- ): Promise<{ success: true; appliedConfigurations: string[] }> {
549
- const existing = (await ctx.runQuery(
550
- componentRef(component, "core/queries/getAccountByStripeId"),
551
- { stripeAccountId: opts.stripeAccountId },
552
- )) as StripeComponentAccount | null;
553
-
554
- if (!existing) {
555
- throwStripeError(
556
- "ACCOUNT_NOT_FOUND",
557
- `No component account found for ${opts.stripeAccountId}; create it before applying the recipient configuration`,
558
- );
559
- }
560
-
561
- await stripe.v2.core.accounts.update(opts.stripeAccountId, {
562
- configuration: {
563
- recipient: {
564
- // V2 (API 2026-05-27.dahlia) requires the `capabilities` wrapper with an
565
- // explicit `requested: true`. The bare `recipient.stripe_balance` shape
566
- // is rejected with "Unknown field" (confirmed against the Stripe sandbox).
567
- capabilities: {
568
- stripe_balance: {
569
- stripe_transfers: { requested: true },
570
- },
571
- },
572
- },
573
- },
574
- } as V2AccountUpdateParams);
575
-
576
- // Re-fetch to record the configurations Stripe actually applied
577
- const updated = await stripe.v2.core.accounts.retrieve(opts.stripeAccountId);
578
- const appliedConfigurations = updated.applied_configurations ?? [];
579
-
580
- await runMutationOrThrow(
581
- ctx,
582
- componentRef(component, "core/mutations/upsertAccount"),
583
- {
584
- stripeAccountId: opts.stripeAccountId,
585
- userId: existing.userId,
586
- appliedConfigurations,
587
- },
588
- );
589
-
590
- return { success: true, appliedConfigurations };
591
- }
478
+ export {
479
+ DEFAULT_CUSTOMER_CONFIGURATION,
480
+ addCustomerConfiguration,
481
+ addRecipientConfiguration,
482
+ addMerchantConfiguration,
483
+ } from "./accountConfigurations.js";
484
+ export { canReceiveTransfers } from "./accountCapabilities.js";
592
485
 
593
486
  // =============================================================================
594
487
  // Sync
@@ -0,0 +1,247 @@
1
+ import { describe, expect, it, vi } from "vitest";
2
+ import type Stripe from "stripe";
3
+ import { BetterStripe, type BetterStripeComponent } from "../index.js";
4
+ import type { RunCtx } from "../helpers.js";
5
+ import {
6
+ createBillingPortalConfiguration,
7
+ retrieveBillingPortalConfiguration,
8
+ updateBillingPortalConfiguration,
9
+ createBillingPortalSession,
10
+ } from "./accountLinks.js";
11
+ const ctx = {} as RunCtx;
12
+ function makeStripe() {
13
+ return {
14
+ billingPortal: {
15
+ configurations: { create: vi.fn(), retrieve: vi.fn(), update: vi.fn() },
16
+ sessions: { create: vi.fn() },
17
+ },
18
+ };
19
+ }
20
+ const asStripe = (stripe: ReturnType<typeof makeStripe>) =>
21
+ stripe as unknown as Stripe;
22
+
23
+ describe("Billing Portal configurations", () => {
24
+ const params = {
25
+ features: {
26
+ subscription_update: {
27
+ enabled: true,
28
+ default_allowed_updates: ["price" as const],
29
+ products: [
30
+ { product: "prod_host", prices: ["price_current", "price_legacy"] },
31
+ ],
32
+ proration_behavior: "always_invoice" as const,
33
+ },
34
+ subscription_cancel: { enabled: true, mode: "at_period_end" as const },
35
+ },
36
+ };
37
+
38
+ it.each([undefined, "acct_connected"])(
39
+ "creates a host-configured policy in scope %s",
40
+ async (connectedAccountId) => {
41
+ const stripe = makeStripe();
42
+ const configuration = { id: "bpc_host", ...params };
43
+ stripe.billingPortal.configurations.create.mockResolvedValue(
44
+ configuration,
45
+ );
46
+ const result = await createBillingPortalConfiguration(
47
+ asStripe(stripe),
48
+ ctx,
49
+ { params, connectedAccountId },
50
+ );
51
+ expect(result).toEqual(configuration);
52
+ expect(stripe.billingPortal.configurations.create.mock.calls[0]).toEqual(
53
+ connectedAccountId
54
+ ? [params, { stripeAccount: connectedAccountId }]
55
+ : [params],
56
+ );
57
+ },
58
+ );
59
+
60
+ it.each([undefined, "acct_connected"])(
61
+ "retrieves a configuration in scope %s",
62
+ async (connectedAccountId) => {
63
+ const stripe = makeStripe();
64
+ stripe.billingPortal.configurations.retrieve.mockResolvedValue({
65
+ id: "bpc_host",
66
+ ...params,
67
+ });
68
+ const result = await retrieveBillingPortalConfiguration(
69
+ asStripe(stripe),
70
+ ctx,
71
+ { configurationId: "bpc_host", connectedAccountId },
72
+ );
73
+ expect(result.id).toBe("bpc_host");
74
+ expect(
75
+ stripe.billingPortal.configurations.retrieve.mock.calls[0],
76
+ ).toEqual(
77
+ connectedAccountId
78
+ ? ["bpc_host", {}, { stripeAccount: connectedAccountId }]
79
+ : ["bpc_host"],
80
+ );
81
+ },
82
+ );
83
+
84
+ it.each([undefined, "acct_connected"])(
85
+ "updates a configuration in scope %s",
86
+ async (connectedAccountId) => {
87
+ const stripe = makeStripe();
88
+ const update = { active: false, ...params };
89
+ stripe.billingPortal.configurations.update.mockResolvedValue({
90
+ id: "bpc_host",
91
+ ...update,
92
+ });
93
+ const result = await updateBillingPortalConfiguration(
94
+ asStripe(stripe),
95
+ ctx,
96
+ { configurationId: "bpc_host", params: update, connectedAccountId },
97
+ );
98
+ expect(result.active).toBe(false);
99
+ expect(stripe.billingPortal.configurations.update.mock.calls[0]).toEqual(
100
+ connectedAccountId
101
+ ? ["bpc_host", update, { stripeAccount: connectedAccountId }]
102
+ : ["bpc_host", update],
103
+ );
104
+ },
105
+ );
106
+
107
+ it.each(["create", "retrieve", "update"] as const)(
108
+ "reports %s provider errors without an unscoped fallback",
109
+ async (operation) => {
110
+ const stripe = makeStripe();
111
+ stripe.billingPortal.configurations[operation].mockRejectedValue({
112
+ type: "StripeInvalidRequestError",
113
+ code: "resource_missing",
114
+ message: "Configuration unavailable in this account",
115
+ });
116
+ const opts = {
117
+ configurationId: "bpc_missing",
118
+ params,
119
+ connectedAccountId: "acct_connected",
120
+ };
121
+ const methods = {
122
+ create: createBillingPortalConfiguration,
123
+ retrieve: retrieveBillingPortalConfiguration,
124
+ update: updateBillingPortalConfiguration,
125
+ };
126
+ await expect(
127
+ methods[operation](asStripe(stripe), ctx, opts),
128
+ ).rejects.toMatchObject({
129
+ data: {
130
+ code: "STRIPE_API_ERROR",
131
+ stripeError: { code: "resource_missing" },
132
+ },
133
+ });
134
+ expect(
135
+ stripe.billingPortal.configurations[operation],
136
+ ).toHaveBeenCalledTimes(1);
137
+ },
138
+ );
139
+ });
140
+
141
+ describe("configured Billing Portal sessions", () => {
142
+ it.each([undefined, "acct_connected"])(
143
+ "selects the configuration and customer account in scope %s",
144
+ async (connectedAccountId) => {
145
+ const stripe = makeStripe();
146
+ stripe.billingPortal.sessions.create.mockResolvedValue({
147
+ url: "https://portal",
148
+ });
149
+ const result = await createBillingPortalSession(asStripe(stripe), ctx, {
150
+ stripeAccountId: "acct_customer",
151
+ returnUrl: "https://return",
152
+ configurationId: "bpc_host",
153
+ connectedAccountId,
154
+ });
155
+ expect(result).toEqual({ url: "https://portal" });
156
+ const params = {
157
+ customer_account: "acct_customer",
158
+ return_url: "https://return",
159
+ configuration: "bpc_host",
160
+ };
161
+ expect(stripe.billingPortal.sessions.create.mock.calls[0]).toEqual(
162
+ connectedAccountId
163
+ ? [params, { stripeAccount: connectedAccountId }]
164
+ : [params],
165
+ );
166
+ },
167
+ );
168
+
169
+ it("reports a provider error without retrying against platform scope", async () => {
170
+ const stripe = makeStripe();
171
+ stripe.billingPortal.sessions.create.mockRejectedValue({
172
+ type: "StripeInvalidRequestError",
173
+ code: "resource_missing",
174
+ message: "No such configuration",
175
+ });
176
+ await expect(
177
+ createBillingPortalSession(asStripe(stripe), ctx, {
178
+ stripeAccountId: "acct_customer",
179
+ returnUrl: "https://return",
180
+ configurationId: "bpc_missing",
181
+ connectedAccountId: "acct_connected",
182
+ }),
183
+ ).rejects.toMatchObject({
184
+ data: {
185
+ code: "STRIPE_API_ERROR",
186
+ stripeError: { code: "resource_missing" },
187
+ },
188
+ });
189
+ expect(stripe.billingPortal.sessions.create).toHaveBeenCalledTimes(1);
190
+ });
191
+ });
192
+
193
+ describe("BetterStripe portal API", () => {
194
+ it("exposes configuration lifecycle and configured sessions through the client", async () => {
195
+ const stripe = makeStripe();
196
+ class TestClient extends BetterStripe {
197
+ protected stripe() {
198
+ return asStripe(stripe);
199
+ }
200
+ }
201
+ const client = new TestClient({} as BetterStripeComponent);
202
+ const params = { features: { invoice_history: { enabled: true } } };
203
+ const opts = {
204
+ configurationId: "bpc_client",
205
+ params,
206
+ connectedAccountId: "acct_owner",
207
+ };
208
+ stripe.billingPortal.configurations.create.mockResolvedValue({
209
+ id: "bpc_client",
210
+ });
211
+ stripe.billingPortal.configurations.retrieve.mockResolvedValue({
212
+ id: "bpc_client",
213
+ });
214
+ stripe.billingPortal.configurations.update.mockResolvedValue({
215
+ id: "bpc_client",
216
+ active: false,
217
+ });
218
+ stripe.billingPortal.sessions.create.mockResolvedValue({
219
+ url: "https://portal",
220
+ });
221
+ expect(await client.createBillingPortalConfiguration(ctx, opts)).toEqual({
222
+ id: "bpc_client",
223
+ });
224
+ expect(await client.retrieveBillingPortalConfiguration(ctx, opts)).toEqual({
225
+ id: "bpc_client",
226
+ });
227
+ expect(await client.updateBillingPortalConfiguration(ctx, opts)).toEqual({
228
+ id: "bpc_client",
229
+ active: false,
230
+ });
231
+ expect(
232
+ await client.createBillingPortalSession(ctx, {
233
+ ...opts,
234
+ stripeAccountId: "acct_customer",
235
+ returnUrl: "https://return",
236
+ }),
237
+ ).toEqual({ url: "https://portal" });
238
+ expect(stripe.billingPortal.sessions.create).toHaveBeenCalledWith(
239
+ {
240
+ configuration: "bpc_client",
241
+ customer_account: "acct_customer",
242
+ return_url: "https://return",
243
+ },
244
+ { stripeAccount: "acct_owner" },
245
+ );
246
+ });
247
+ });
@@ -0,0 +1,35 @@
1
+ import type Stripe from "stripe";
2
+ import { FinancialOwnershipHost } from "../financialOwnership.js";
3
+ import type { RunCtx } from "../helpers.js";
4
+ import * as portal from "./accountLinks.js";
5
+
6
+ /** Portal APIs inherited by BetterStripe. Hosts authorize account scope and supply policy. */
7
+ export abstract class BillingPortalClient extends FinancialOwnershipHost {
8
+ async createBillingPortalConfiguration(
9
+ ctx: RunCtx,
10
+ opts: portal.CreateBillingPortalConfigurationOptions,
11
+ ): Promise<Stripe.BillingPortal.Configuration> {
12
+ return portal.createBillingPortalConfiguration(this.stripe(), ctx, opts);
13
+ }
14
+
15
+ async retrieveBillingPortalConfiguration(
16
+ ctx: RunCtx,
17
+ opts: portal.RetrieveBillingPortalConfigurationOptions,
18
+ ): Promise<Stripe.BillingPortal.Configuration> {
19
+ return portal.retrieveBillingPortalConfiguration(this.stripe(), ctx, opts);
20
+ }
21
+
22
+ async updateBillingPortalConfiguration(
23
+ ctx: RunCtx,
24
+ opts: portal.UpdateBillingPortalConfigurationOptions,
25
+ ): Promise<Stripe.BillingPortal.Configuration> {
26
+ return portal.updateBillingPortalConfiguration(this.stripe(), ctx, opts);
27
+ }
28
+
29
+ async createBillingPortalSession(
30
+ ctx: RunCtx,
31
+ opts: portal.CreateBillingPortalSessionOptions,
32
+ ) {
33
+ return portal.createBillingPortalSession(this.stripe(), ctx, opts);
34
+ }
35
+ }
@@ -0,0 +1,88 @@
1
+ import type { VerifiedSale } from "../settlement/verifiedSale.js";
2
+ import type { ProcessingCostContext } from "../settlement/processingCosts.js";
3
+ import type { FinancialUnavailable, FinancialOutcome } from "./contracts.js";
4
+
5
+ /** Additive adapter; the existing getVerifiedSale result remains unchanged. */
6
+ export function verifiedSaleOutcome(
7
+ sale: Exclude<VerifiedSale, { status: "ready" }>,
8
+ ): FinancialUnavailable;
9
+ export function verifiedSaleOutcome(
10
+ sale: VerifiedSale,
11
+ ): FinancialOutcome<Extract<VerifiedSale, { status: "ready" }>>;
12
+ export function verifiedSaleOutcome(
13
+ sale: VerifiedSale,
14
+ ): FinancialOutcome<Extract<VerifiedSale, { status: "ready" }>> {
15
+ if (sale.status === "ready") return { status: "ready", value: sale };
16
+ if (
17
+ sale.status === "not_payable" &&
18
+ ["payment_not_succeeded", "charge_refunded_or_disputed"].includes(
19
+ sale.reason,
20
+ )
21
+ )
22
+ return {
23
+ status: "rejected",
24
+ reason: "payment_not_payable",
25
+ retryable: false,
26
+ };
27
+ if (sale.status === "pending" && sale.retryable) {
28
+ if (sale.reason === "processing_fee_unavailable")
29
+ return { status: "not_ready", reason: "fee_pending", retryable: true };
30
+ if (
31
+ ["payment_processing", "charge_unavailable", "invoice_not_paid"].includes(
32
+ sale.reason,
33
+ )
34
+ )
35
+ return {
36
+ status: "not_ready",
37
+ reason: "provider_pending",
38
+ retryable: true,
39
+ };
40
+ }
41
+ return { status: "rejected", reason: "unsupported_source", retryable: false };
42
+ }
43
+
44
+ /** Missing fees never become zero; a currency mismatch is terminal. */
45
+ export function processingCostOutcome(
46
+ cost: Extract<ProcessingCostContext, { status: "not_ready" }>,
47
+ ): FinancialUnavailable;
48
+ export function processingCostOutcome(
49
+ cost: ProcessingCostContext,
50
+ ): FinancialOutcome<Extract<ProcessingCostContext, { status: "ready" }>>;
51
+ export function processingCostOutcome(
52
+ cost: ProcessingCostContext,
53
+ ): FinancialOutcome<Extract<ProcessingCostContext, { status: "ready" }>> {
54
+ if (cost.status === "ready") return { status: "ready", value: cost };
55
+ switch (cost.reason) {
56
+ case "payment_not_succeeded":
57
+ return {
58
+ status: "rejected",
59
+ reason: "payment_not_payable",
60
+ retryable: false,
61
+ };
62
+ case "currency_mismatch":
63
+ return {
64
+ status: "rejected",
65
+ reason: "currency_mismatch",
66
+ retryable: false,
67
+ };
68
+ case "charge_unavailable":
69
+ case "refund_pending":
70
+ return {
71
+ status: "not_ready",
72
+ reason: "provider_pending",
73
+ retryable: true,
74
+ };
75
+ case "charge_transaction_unavailable":
76
+ case "refund_transaction_unavailable":
77
+ case "refund_failure_transaction_unavailable":
78
+ case "dispute_transactions_unavailable":
79
+ case "dispute_reinstatement_unavailable":
80
+ return { status: "not_ready", reason: "fee_pending", retryable: true };
81
+ default:
82
+ return {
83
+ status: "rejected",
84
+ reason: "unsupported_source",
85
+ retryable: false,
86
+ };
87
+ }
88
+ }
@@ -0,0 +1,43 @@
1
+ import { z } from "zod";
2
+
3
+ /** Safe to persist. Provider messages, credentials and financial payloads stay out. */
4
+ export const financialUnavailableSchema = z.discriminatedUnion("status", [
5
+ z
6
+ .object({
7
+ status: z.literal("not_ready"),
8
+ reason: z.enum(["provider_pending", "fee_pending", "history_incomplete"]),
9
+ retryable: z.literal(true),
10
+ })
11
+ .strict(),
12
+ z
13
+ .object({
14
+ status: z.literal("conflict"),
15
+ reason: z.enum(["scope_busy", "revision_changed", "identity_changed"]),
16
+ retryable: z.literal(false),
17
+ })
18
+ .strict(),
19
+ z
20
+ .object({
21
+ status: z.literal("rejected"),
22
+ reason: z.enum([
23
+ "invalid_scope",
24
+ "unsupported_source",
25
+ "policy_invalid",
26
+ "payment_not_payable",
27
+ "currency_mismatch",
28
+ ]),
29
+ retryable: z.literal(false),
30
+ })
31
+ .strict(),
32
+ z
33
+ .object({
34
+ status: z.literal("unknown"),
35
+ reason: z.enum(["provider_outcome_unknown", "history_incomplete"]),
36
+ retryable: z.literal(false),
37
+ })
38
+ .strict(),
39
+ ]);
40
+
41
+ export type FinancialUnavailable = z.infer<typeof financialUnavailableSchema>;
42
+ export type FinancialOutcome<T> =
43
+ { status: "ready"; value: T } | FinancialUnavailable;