@fantastic.dev/better-stripe 0.37.1 → 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 +33 -0
  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
@@ -1,5 +1,6 @@
1
1
  import * as personalAccountMappingImpl from "./core/personalAccountMapping.js";
2
2
  export type * from "./publicTypes.js";
3
+ export * from "./financialOutcomes/index.js";
3
4
  import * as accountClosuresImpl from "./core/accountClosures.js";
4
5
  import type { PaginationOptions } from "convex/server";
5
6
  import { reconcilePayoutAndTrigger } from "./webhooks/payoutReconciliation.js";
@@ -18,26 +19,25 @@ import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js"
18
19
  export type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
19
20
  import * as intentsImpl from "./billing/intents.js";
20
21
  export type * from "./billing/intents.js";
21
- import { FinancialOwnershipHost } from "./financialOwnership.js";
22
+ import { CatalogClient } from "./products/catalogClient.js";
23
+ export type {
24
+ CreateBillingPortalConfigurationOptions,
25
+ RetrieveBillingPortalConfigurationOptions,
26
+ UpdateBillingPortalConfigurationOptions,
27
+ CreateBillingPortalSessionOptions,
28
+ } from "./core/accountLinks.js";
29
+ export type {
30
+ AdoptProductOptions,
31
+ EnsurePriceOptions,
32
+ } from "./products/catalog.js";
33
+ export type { CreatePriceOptions } from "./products/prices.js";
34
+ export type { CreateProductOptions } from "./products/products.js";
22
35
  import { CostRecoveryClient } from "./costRecovery.js";
23
36
  export * from "./charge-currency.js";
24
37
  export * from "./costRecovery.js";
25
38
  import type { SubscriptionStatus } from "../component/billing/validators.js";
26
39
  import * as processingCostsImpl from "./settlement/processingCosts.js";
27
- export type {
28
- ProcessingCostContext,
29
- ProcessingCostOptions,
30
- ProcessingCostTransaction,
31
- ProcessingCostRecord,
32
- ProcessingCostNotReadyReason,
33
- } from "./settlement/processingCosts.js";
34
40
  import * as balanceFundingImpl from "./billing/balanceFunding.js";
35
- export type {
36
- BalanceFundingCapability,
37
- BalanceFundingPreparation,
38
- PrepareBalanceFundingOptions,
39
- SetBalanceFundingOptions,
40
- } from "./billing/balanceFunding.js";
41
41
  import * as invoicePreviewImpl from "./billing/invoicePreview.js";
42
42
  export type {
43
43
  UpcomingInvoicePreview,
@@ -72,6 +72,10 @@ export type {
72
72
  ProviderCheckoutSessionPage,
73
73
  } from "./billing/checkoutPages.js";
74
74
  export type { CreateAccountOptions } from "./core/accounts.js";
75
+ export {
76
+ canReceiveTransfers,
77
+ type TransferCapabilityAccount,
78
+ } from "./core/accountCapabilities.js";
75
79
  import { buildAsyncHookRoutes } from "./webhooks/asyncHooks.js";
76
80
  import * as saleContextImpl from "./settlement/verifiedSale.js";
77
81
  import * as settlementImpl from "./settlement/settleSale.js";
@@ -144,8 +148,6 @@ import type {
144
148
  V2AccountUpdateParams,
145
149
  } from "./stripe-types.js";
146
150
  import { componentRef, DISPATCHER_UPSERT_PATHS } from "./webhooks/helpers.js";
147
- import * as pricesImpl from "./products/prices.js";
148
- import * as productsImpl from "./products/products.js";
149
151
  import type {
150
152
  AccountLinkWithStatus,
151
153
  AsyncHookCtx,
@@ -202,7 +204,7 @@ export type BetterStripeComponent = ComponentApi;
202
204
 
203
205
  // BETTER STRIPE CLIENT
204
206
 
205
- export class BetterStripe extends FinancialOwnershipHost {
207
+ export class BetterStripe extends CatalogClient {
206
208
  readonly stripeApiVersion: SupportedStripeApiVersion;
207
209
  private _apiKey?: string;
208
210
  private _triggers?: SyncTriggers;
@@ -464,11 +466,7 @@ export class BetterStripe extends FinancialOwnershipHost {
464
466
  );
465
467
  }
466
468
 
467
- /**
468
- * Apply the V2 recipient configuration to an existing account, and record
469
- * the applied configurations on the component account. The account must
470
- * already exist in the component DB (e.g. from {@link createAccount}).
471
- */
469
+ /** Request recipient transfers and persist the provider configurations for this account. */
472
470
  async addRecipientConfiguration(
473
471
  ctx: RunCtx,
474
472
  opts: { stripeAccountId: string },
@@ -481,12 +479,7 @@ export class BetterStripe extends FinancialOwnershipHost {
481
479
  );
482
480
  }
483
481
 
484
- /**
485
- * Apply the V2 customer configuration to an existing account, making it
486
- * billable (subscriptions, invoices, billing portal via `customer_account`),
487
- * and record the applied configurations on the component account. The account
488
- * must already exist in the component DB (e.g. from {@link createAccount}).
489
- */
482
+ /** Make an existing account billable and persist its provider configurations. */
490
483
  async addCustomerConfiguration(
491
484
  ctx: RunCtx,
492
485
  opts: { stripeAccountId: string },
@@ -499,6 +492,19 @@ export class BetterStripe extends FinancialOwnershipHost {
499
492
  );
500
493
  }
501
494
 
495
+ /** Request merchant card payments and persist only this account's provider configurations. */
496
+ async addMerchantConfiguration(
497
+ ctx: RunCtx,
498
+ opts: { stripeAccountId: string },
499
+ ) {
500
+ return accountsImpl.addMerchantConfiguration(
501
+ this.stripe(),
502
+ this.component,
503
+ ctx,
504
+ opts,
505
+ );
506
+ }
507
+
502
508
  /**
503
509
  * Store (or clear, with `null`) a per-store statement-descriptor suffix on a
504
510
  * seller's account record (BTS-32). Destination charges to that account then
@@ -534,148 +540,6 @@ export class BetterStripe extends FinancialOwnershipHost {
534
540
  );
535
541
  }
536
542
 
537
- // PRODUCT METHODS
538
-
539
- async createProduct(ctx: RunCtx, opts: productsImpl.CreateProductOptions) {
540
- return productsImpl.createProduct(this.stripe(), this.component, ctx, {
541
- ...opts,
542
- // Stamp the per-store descriptor at create so it covers the first invoice
543
- // charge (BTS-67); resolves the store's suffix, else this default.
544
- defaultStatementDescriptorSuffix: this._statementDescriptorSuffix,
545
- });
546
- }
547
-
548
- async updateProduct(
549
- ctx: RunCtx,
550
- opts: {
551
- stripeProductId: string;
552
- name?: string;
553
- description?: string;
554
- active?: boolean;
555
- defaultPrice?: string | null;
556
- metadata?: Record<string, string>;
557
- },
558
- ) {
559
- return productsImpl.updateProduct(this.stripe(), this.component, ctx, {
560
- ...opts,
561
- defaultStatementDescriptorSuffix: this._statementDescriptorSuffix,
562
- });
563
- }
564
-
565
- async deactivateProduct(ctx: RunCtx, opts: { stripeProductId: string }) {
566
- return productsImpl.deactivateProduct(this.stripe(), ctx, opts);
567
- }
568
-
569
- async getProduct(
570
- ctx: RunCtx,
571
- opts: { productId: string },
572
- ): Promise<StripeComponentProduct | null> {
573
- return productsImpl.getProduct(this.component, ctx, opts);
574
- }
575
-
576
- async getProductByStripeId(
577
- ctx: RunCtx,
578
- opts: { stripeProductId: string },
579
- ): Promise<StripeComponentProduct | null> {
580
- return productsImpl.getProductByStripeId(this.component, ctx, opts);
581
- }
582
-
583
- async listProducts(
584
- ctx: RunCtx,
585
- opts?: { accountId?: string; active?: boolean; limit?: number },
586
- ): Promise<StripeComponentProduct[]> {
587
- return productsImpl.listProducts(this.component, ctx, opts);
588
- }
589
-
590
- async upsertProduct(
591
- ctx: RunCtx,
592
- opts: {
593
- stripeProductId: string;
594
- accountId?: string;
595
- name: string;
596
- description?: string;
597
- active: boolean;
598
- metadata?: Record<string, unknown>;
599
- },
600
- ) {
601
- return productsImpl.upsertProduct(this.component, ctx, opts);
602
- }
603
-
604
- async listStripeProducts(
605
- ctx: RunCtx,
606
- opts?: { active?: boolean; limit?: number },
607
- ) {
608
- return productsImpl.listStripeProducts(this.stripe(), ctx, opts);
609
- }
610
-
611
- async deleteProduct(ctx: RunCtx, opts: { stripeProductId: string }) {
612
- return productsImpl.deleteProduct(this.stripe(), ctx, opts);
613
- }
614
-
615
- // PRICE METHODS
616
-
617
- async createPrice(ctx: RunCtx, opts: pricesImpl.CreatePriceOptions) {
618
- return pricesImpl.createPrice(this.stripe(), this.component, ctx, opts);
619
- }
620
-
621
- async updatePrice(
622
- ctx: RunCtx,
623
- opts: {
624
- stripePriceId: string;
625
- active?: boolean;
626
- nickname?: string;
627
- metadata?: Record<string, string>;
628
- },
629
- ) {
630
- return pricesImpl.updatePrice(this.stripe(), ctx, opts);
631
- }
632
-
633
- async deactivatePrice(ctx: RunCtx, opts: { stripePriceId: string }) {
634
- return pricesImpl.deactivatePrice(this.stripe(), ctx, opts);
635
- }
636
-
637
- async getPrice(
638
- ctx: RunCtx,
639
- opts: { priceId: string },
640
- ): Promise<StripeComponentPrice | null> {
641
- return pricesImpl.getPrice(this.component, ctx, opts);
642
- }
643
-
644
- async getPriceByStripeId(
645
- ctx: RunCtx,
646
- opts: { stripePriceId: string },
647
- ): Promise<StripeComponentPrice | null> {
648
- return pricesImpl.getPriceByStripeId(this.component, ctx, opts);
649
- }
650
-
651
- async listPrices(
652
- ctx: RunCtx,
653
- opts?: { productId?: string; active?: boolean; limit?: number },
654
- ): Promise<StripeComponentPrice[]> {
655
- return pricesImpl.listPrices(this.component, ctx, opts);
656
- }
657
-
658
- async listPricesByProduct(
659
- ctx: RunCtx,
660
- opts: { stripeProductId: string },
661
- ): Promise<StripeComponentPrice[]> {
662
- return pricesImpl.listPricesByProduct(this.component, ctx, opts);
663
- }
664
-
665
- async upsertPrice(
666
- ctx: RunCtx,
667
- opts: Parameters<typeof pricesImpl.upsertPrice>[2],
668
- ) {
669
- return pricesImpl.upsertPrice(this.component, ctx, opts);
670
- }
671
-
672
- async listStripePrices(
673
- ctx: RunCtx,
674
- opts?: { productId?: string; active?: boolean; limit?: number },
675
- ) {
676
- return pricesImpl.listStripePrices(this.stripe(), ctx, opts);
677
- }
678
-
679
543
  /** Card-only one-time checkout. Host authorizes price and authenticated customer. */
680
544
  async createPaymentIntent(
681
545
  ctx: RunCtx,
@@ -1133,17 +997,6 @@ export class BetterStripe extends FinancialOwnershipHost {
1133
997
  return accountLinksImpl.getAccountLinkWithStatus(this.stripe(), ctx, opts);
1134
998
  }
1135
999
 
1136
- async createBillingPortalSession(
1137
- ctx: RunCtx,
1138
- opts: { stripeAccountId: string; returnUrl: string },
1139
- ) {
1140
- return accountLinksImpl.createBillingPortalSession(
1141
- this.stripe(),
1142
- ctx,
1143
- opts,
1144
- );
1145
- }
1146
-
1147
1000
  async getCountrySpecs(ctx: RunCtx, opts: { countryCode: string }) {
1148
1001
  return accountLinksImpl.getCountrySpecs(this.stripe(), ctx, opts);
1149
1002
  }
@@ -1509,10 +1362,6 @@ export class BetterStripe extends FinancialOwnershipHost {
1509
1362
  return accountsImpl.syncAllAccounts(this.stripe(), this.component, ctx);
1510
1363
  }
1511
1364
 
1512
- async syncAllProducts(ctx: RunCtx) {
1513
- return productsImpl.syncAllProducts(this.stripe(), this.component, ctx);
1514
- }
1515
-
1516
1365
  async syncAllSubscriptions(ctx: RunCtx) {
1517
1366
  return subscriptionsImpl.syncAllSubscriptions(
1518
1367
  this.stripe(),
@@ -0,0 +1,389 @@
1
+ import type Stripe from "stripe";
2
+ import { componentsGeneric, type FunctionReference } from "convex/server";
3
+ import { beforeEach, describe, expect, it, vi } from "vitest";
4
+ import schema from "../../component/schema.js";
5
+ import { initConvexTest } from "../setup.test.js";
6
+ import { BetterStripe } from "../index.js";
7
+ import { getStripeClient, type Component, type RunCtx } from "../helpers.js";
8
+ const modules = import.meta.glob("../../component/**/*.{ts,js,tsx,jsx}");
9
+
10
+ describe("lookup-key catalog", () => {
11
+ const options = {
12
+ stripeProductId: "prod_catalog",
13
+ lookupKey: "plan:v1",
14
+ unitAmount: 900,
15
+ currency: "usd",
16
+ type: "recurring" as const,
17
+ interval: "month" as const,
18
+ idempotencyKey: "catalog:plan:v1",
19
+ };
20
+ let client: BetterStripe;
21
+ let sdk: Stripe;
22
+ let ctx: RunCtx;
23
+ let price: Stripe.Price;
24
+ let list: ReturnType<typeof vi.spyOn>;
25
+ let create: ReturnType<typeof vi.spyOn>;
26
+ let retrieve: ReturnType<typeof vi.spyOn>;
27
+ beforeEach(() => {
28
+ const t = initConvexTest();
29
+ t.registerComponent("betterStripe", schema, modules);
30
+ const key = `sk_test_lookup_${crypto.randomUUID()}`;
31
+ client = new BetterStripe(
32
+ componentsGeneric().betterStripe as unknown as Component,
33
+ { STRIPE_SECRET_KEY: key },
34
+ );
35
+ sdk = getStripeClient(key);
36
+ ctx = {
37
+ runQuery: (
38
+ ref: FunctionReference<"query">,
39
+ args: Record<string, unknown>,
40
+ ) => t.query(ref, args),
41
+ runMutation: (
42
+ ref: FunctionReference<"mutation">,
43
+ args: Record<string, unknown>,
44
+ ) => t.mutation(ref, args),
45
+ } as unknown as RunCtx;
46
+ price = {
47
+ id: "price_catalog",
48
+ product: "prod_catalog",
49
+ active: true,
50
+ currency: "usd",
51
+ unit_amount: 900,
52
+ unit_amount_decimal: "900",
53
+ lookup_key: "plan:v1",
54
+ type: "recurring",
55
+ billing_scheme: "per_unit",
56
+ recurring: {
57
+ interval: "month",
58
+ interval_count: 1,
59
+ usage_type: "licensed",
60
+ },
61
+ metadata: {},
62
+ nickname: null,
63
+ } as unknown as Stripe.Price;
64
+ list = vi.spyOn(sdk.prices, "list").mockResolvedValue({
65
+ data: [price],
66
+ has_more: false,
67
+ } as Stripe.Response<Stripe.ApiList<Stripe.Price>>);
68
+ create = vi
69
+ .spyOn(sdk.prices, "create")
70
+ .mockResolvedValue(price as Stripe.Response<Stripe.Price>);
71
+ retrieve = vi.spyOn(sdk.products, "retrieve").mockResolvedValue({
72
+ id: "prod_catalog",
73
+ active: true,
74
+ name: "Catalog",
75
+ description: null,
76
+ metadata: {},
77
+ } as Stripe.Response<Stripe.Product>);
78
+ });
79
+ it("looks up without modifying the component", async () => {
80
+ expect(
81
+ (
82
+ await client.getStripePriceByLookupKey(ctx, {
83
+ lookupKey: options.lookupKey,
84
+ })
85
+ )?.id,
86
+ ).toBe(price.id);
87
+ expect(
88
+ await client.getProductByStripeId(ctx, {
89
+ stripeProductId: options.stripeProductId,
90
+ }),
91
+ ).toBeNull();
92
+ expect(list).toHaveBeenCalledWith({
93
+ lookup_keys: [options.lookupKey],
94
+ limit: 2,
95
+ });
96
+ });
97
+ it("adopts a matching price and product into existing mirrors", async () => {
98
+ expect(await client.ensurePrice(ctx, options)).toEqual({
99
+ stripePriceId: price.id,
100
+ });
101
+ const stored = await client.getPriceByStripeId(ctx, {
102
+ stripePriceId: price.id,
103
+ });
104
+ expect(stored).toMatchObject({
105
+ unitAmount: 900,
106
+ intervalCount: 1,
107
+ type: "recurring",
108
+ });
109
+ expect(
110
+ await client.getProductByStripeId(ctx, {
111
+ stripeProductId: options.stripeProductId,
112
+ }),
113
+ ).toMatchObject({ name: "Catalog" });
114
+ expect(create).not.toHaveBeenCalled();
115
+ });
116
+ it("creates a missing price with a caller-scoped idempotency key", async () => {
117
+ list.mockResolvedValue({ data: [], has_more: false });
118
+ await client.ensurePrice(ctx, options);
119
+ expect(create).toHaveBeenCalledWith(
120
+ expect.objectContaining({
121
+ lookup_key: options.lookupKey,
122
+ product: options.stripeProductId,
123
+ recurring: { interval: "month", interval_count: 1 },
124
+ }),
125
+ { idempotencyKey: options.idempotencyKey },
126
+ );
127
+ });
128
+ it.each([
129
+ { product: "prod_other" },
130
+ { unit_amount: 901 },
131
+ { currency: "eur" },
132
+ { active: false },
133
+ {
134
+ recurring: {
135
+ interval: "year",
136
+ interval_count: 1,
137
+ usage_type: "licensed",
138
+ },
139
+ },
140
+ {
141
+ recurring: {
142
+ interval: "month",
143
+ interval_count: 2,
144
+ usage_type: "licensed",
145
+ },
146
+ },
147
+ {
148
+ recurring: {
149
+ interval: "month",
150
+ interval_count: 1,
151
+ usage_type: "metered",
152
+ },
153
+ },
154
+ { type: "one_time", recurring: null },
155
+ { transform_quantity: { divide_by: 10, round: "up" } },
156
+ { billing_scheme: "tiered" },
157
+ ])(
158
+ "rejects incompatible lookup results %j before mirroring",
159
+ async (patch) => {
160
+ Object.assign(price, patch);
161
+ await expect(client.ensurePrice(ctx, options)).rejects.toThrow(
162
+ /incompatible/,
163
+ );
164
+ expect(retrieve).not.toHaveBeenCalled();
165
+ expect(create).not.toHaveBeenCalled();
166
+ expect(
167
+ await client.getPriceByStripeId(ctx, { stripePriceId: price.id }),
168
+ ).toBeNull();
169
+ },
170
+ );
171
+ it("reconciles another creator winning the lookup key", async () => {
172
+ list.mockResolvedValueOnce({ data: [], has_more: false });
173
+ create.mockRejectedValueOnce(new Error("lookup key already exists"));
174
+ await expect(client.ensurePrice(ctx, options)).resolves.toEqual({
175
+ stripePriceId: price.id,
176
+ });
177
+ });
178
+ it("preserves a provider error when no winning price exists", async () => {
179
+ list.mockResolvedValue({ data: [], has_more: false });
180
+ const failure = new Error("provider unavailable");
181
+ create.mockRejectedValue(failure);
182
+ await expect(client.ensurePrice(ctx, options)).rejects.toBe(failure);
183
+ });
184
+ it("repairs component persistence after Stripe succeeds", async () => {
185
+ list.mockResolvedValueOnce({ data: [], has_more: false });
186
+ const failing = {
187
+ ...ctx,
188
+ runMutation: vi
189
+ .fn()
190
+ .mockRejectedValueOnce(new Error("persistence outage")),
191
+ } as RunCtx;
192
+ await expect(client.ensurePrice(failing, options)).rejects.toThrow(
193
+ "persistence outage",
194
+ );
195
+ await client.ensurePrice(ctx, options);
196
+ expect(create).toHaveBeenCalledTimes(1);
197
+ expect(
198
+ await client.getPriceByStripeId(ctx, { stripePriceId: price.id }),
199
+ ).not.toBeNull();
200
+ });
201
+ it.each([
202
+ { unitAmount: -1 },
203
+ { unitAmount: 1.5 },
204
+ { currency: "bogus" },
205
+ { interval: undefined },
206
+ { intervalCount: 0 },
207
+ { lookupKey: "" },
208
+ { idempotencyKey: "" },
209
+ ])("rejects invalid inputs before provider calls %j", async (patch) => {
210
+ await expect(
211
+ client.ensurePrice(ctx, { ...options, ...patch }),
212
+ ).rejects.toThrow();
213
+ expect(list).not.toHaveBeenCalled();
214
+ expect(create).not.toHaveBeenCalled();
215
+ });
216
+ it("rejects an ambiguous lookup without adoption", async () => {
217
+ list.mockResolvedValue({ data: [price, price], has_more: false });
218
+ await expect(client.ensurePrice(ctx, options)).rejects.toThrow(/Ambiguous/);
219
+ expect(retrieve).not.toHaveBeenCalled();
220
+ });
221
+ it("creates and mirrors a zero-cost one-time price", async () => {
222
+ Object.assign(price, { type: "one_time", recurring: null, unit_amount: 0 });
223
+ await client.ensurePrice(ctx, {
224
+ ...options,
225
+ type: "one_time",
226
+ interval: undefined,
227
+ unitAmount: 0,
228
+ currency: "USD",
229
+ });
230
+ expect(
231
+ await client.getPriceByStripeId(ctx, { stripePriceId: price.id }),
232
+ ).toMatchObject({ type: "one_time", unitAmount: 0 });
233
+ });
234
+ it("keeps the original provider error if reconciliation fails", async () => {
235
+ const failure = new Error("provider timed out");
236
+ list
237
+ .mockResolvedValueOnce({ data: [], has_more: false })
238
+ .mockRejectedValueOnce(new Error("read failed"));
239
+ create.mockRejectedValueOnce(failure);
240
+ await expect(client.ensurePrice(ctx, options)).rejects.toBe(failure);
241
+ });
242
+ it("repairs a failed price mirror write after the product was adopted", async () => {
243
+ const original = ctx.runMutation!;
244
+ let calls = 0;
245
+ const failing = {
246
+ ...ctx,
247
+ runMutation: async (
248
+ ref: FunctionReference<"mutation">,
249
+ args: Record<string, unknown>,
250
+ ) => {
251
+ if (++calls === 2) throw new Error("price mirror outage");
252
+ return original(ref, args);
253
+ },
254
+ } as RunCtx;
255
+ await expect(client.ensurePrice(failing, options)).rejects.toThrow(
256
+ "price mirror outage",
257
+ );
258
+ await client.ensurePrice(ctx, options);
259
+ expect(
260
+ await client.getPriceByStripeId(ctx, { stripePriceId: price.id }),
261
+ ).not.toBeNull();
262
+ expect(create).not.toHaveBeenCalled();
263
+ });
264
+ it("converges concurrent callers on the provider lookup winner", async () => {
265
+ list
266
+ .mockResolvedValueOnce({ data: [], has_more: false })
267
+ .mockResolvedValueOnce({ data: [], has_more: false });
268
+ create
269
+ .mockResolvedValueOnce(price)
270
+ .mockRejectedValueOnce(new Error("lookup collision"));
271
+ const results = await Promise.all([
272
+ client.ensurePrice(ctx, options),
273
+ client.ensurePrice(ctx, {
274
+ ...options,
275
+ idempotencyKey: "other-agent:same-plan",
276
+ }),
277
+ ]);
278
+ expect(results).toEqual([
279
+ { stripePriceId: price.id },
280
+ { stripePriceId: price.id },
281
+ ]);
282
+ expect(await client.listPrices(ctx)).toHaveLength(1);
283
+ expect(await client.listProducts(ctx)).toHaveLength(1);
284
+ });
285
+ it("atomically rejects concurrent adoption into different owning accounts", async () => {
286
+ let reads = 0;
287
+ let release!: () => void;
288
+ const bothRead = new Promise<void>((resolve) => {
289
+ release = resolve;
290
+ });
291
+ const synchronized = {
292
+ ...ctx,
293
+ runQuery: async (
294
+ ref: FunctionReference<"query">,
295
+ args: Record<string, unknown>,
296
+ ) => {
297
+ const result = await ctx.runQuery(ref, args);
298
+ if (++reads <= 2) {
299
+ if (reads === 2) release();
300
+ await bothRead;
301
+ }
302
+ return result;
303
+ },
304
+ } as RunCtx;
305
+ const outcomes = await Promise.allSettled([
306
+ client.adoptProduct(synchronized, {
307
+ stripeProductId: options.stripeProductId,
308
+ accountId: "acct_a",
309
+ }),
310
+ client.adoptProduct(synchronized, {
311
+ stripeProductId: options.stripeProductId,
312
+ accountId: "acct_b",
313
+ }),
314
+ ]);
315
+ expect(
316
+ outcomes.filter((result) => result.status === "fulfilled"),
317
+ ).toHaveLength(1);
318
+ const rejected = outcomes.find((result) => result.status === "rejected");
319
+ expect(rejected?.status === "rejected" && String(rejected.reason)).toMatch(
320
+ /ownership/,
321
+ );
322
+ const stored = await client.getProductByStripeId(ctx, {
323
+ stripeProductId: options.stripeProductId,
324
+ });
325
+ const winner = outcomes[0].status === "fulfilled" ? "acct_a" : "acct_b";
326
+ expect(stored?.accountId).toBe(winner);
327
+ });
328
+ it("adopts products without changing existing ownership", async () => {
329
+ await client.upsertProduct(ctx, {
330
+ stripeProductId: options.stripeProductId,
331
+ accountId: "acct_owner",
332
+ name: "Old",
333
+ active: true,
334
+ });
335
+ await client.adoptProduct(ctx, {
336
+ stripeProductId: options.stripeProductId,
337
+ });
338
+ expect(
339
+ await client.getProductByStripeId(ctx, {
340
+ stripeProductId: options.stripeProductId,
341
+ }),
342
+ ).toMatchObject({ name: "Catalog", accountId: "acct_owner" });
343
+ await expect(
344
+ client.adoptProduct(ctx, {
345
+ stripeProductId: options.stripeProductId,
346
+ accountId: "acct_other",
347
+ }),
348
+ ).rejects.toThrow(/ownership/);
349
+ });
350
+ it("rejects a different explicit owner when the stored owner is an empty string", async () => {
351
+ await client.upsertProduct(ctx, {
352
+ stripeProductId: options.stripeProductId,
353
+ accountId: "",
354
+ name: "Existing",
355
+ active: true,
356
+ });
357
+ const mutation = vi.fn().mockResolvedValue(null);
358
+ await expect(
359
+ client.adoptProduct({ ...ctx, runMutation: mutation } as RunCtx, {
360
+ stripeProductId: options.stripeProductId,
361
+ accountId: "acct_other",
362
+ }),
363
+ ).rejects.toThrow(/ownership/);
364
+ expect(mutation).not.toHaveBeenCalled();
365
+ });
366
+ it("retains deliberate legacy upsert ownership changes", async () => {
367
+ await client.adoptProduct(ctx, {
368
+ stripeProductId: options.stripeProductId,
369
+ accountId: "acct_a",
370
+ });
371
+ await client.upsertProduct(ctx, {
372
+ stripeProductId: options.stripeProductId,
373
+ accountId: "acct_b",
374
+ name: "Deliberately reassigned",
375
+ active: true,
376
+ });
377
+ expect(
378
+ await client.getProductByStripeId(ctx, {
379
+ stripeProductId: options.stripeProductId,
380
+ }),
381
+ ).toMatchObject({ accountId: "acct_b", name: "Deliberately reassigned" });
382
+ });
383
+ it("rejects deleted products", async () => {
384
+ retrieve.mockResolvedValue({ id: options.stripeProductId, deleted: true });
385
+ await expect(
386
+ client.adoptProduct(ctx, { stripeProductId: options.stripeProductId }),
387
+ ).rejects.toThrow(/deleted/);
388
+ });
389
+ });