@fantastic.dev/better-stripe 0.10.2 → 0.12.0

package/src/client/index.ts

@@ -1,3 +1,27 @@
+import { CostRecoveryClient } from "./costRecovery.js";
+export * from "./charge-currency.js";
+export * from "./costRecovery.js";
+import type { SubscriptionStatus } from "../component/billing/validators.js";
+import * as processingCostsImpl from "./settlement/processingCosts.js";
+export type {
+  ProcessingCostContext,
+  ProcessingCostOptions,
+  ProcessingCostTransaction,
+  ProcessingCostRecord,
+  ProcessingCostNotReadyReason,
+} from "./settlement/processingCosts.js";
+import * as balanceFundingImpl from "./billing/balanceFunding.js";
+export type {
+  BalanceFundingCapability,
+  BalanceFundingPreparation,
+  PrepareBalanceFundingOptions,
+  SetBalanceFundingOptions,
+} from "./billing/balanceFunding.js";
+import * as invoicePreviewImpl from "./billing/invoicePreview.js";
+export type {
+  UpcomingInvoicePreview,
+  UpcomingInvoicePreviewOptions,
+} from "./billing/invoicePreview.js";
 import type { HttpRouter } from "convex/server";
 import { registerClientRoutes } from "./previewRoutes.js";
 import {
@@ -47,10 +71,6 @@ import { v } from "convex/values";
 import Stripe from "stripe";
 
 import type { ComponentApi } from "../component/_generated/component.js";
-import type {
-  InvoiceStatus,
-  SubscriptionStatus,
-} from "../component/billing/validators.js";
 import type {
   DisputeStatus,
   PayoutStatus,
@@ -495,16 +515,7 @@ export class BetterStripe {
 
   // PRODUCT METHODS
 
-  async createProduct(
-    ctx: RunCtx,
-    opts: {
-      name: string;
-      description?: string;
-      active?: boolean;
-      accountId?: string;
-      metadata?: Record<string, string>;
-    },
-  ) {
+  async createProduct(ctx: RunCtx, opts: productsImpl.CreateProductOptions) {
     return productsImpl.createProduct(this.stripe(), this.component, ctx, {
       ...opts,
       // Stamp the per-store descriptor at create so it covers the first invoice
@@ -582,19 +593,7 @@ export class BetterStripe {
 
   // PRICE METHODS
 
-  async createPrice(
-    ctx: RunCtx,
-    opts: {
-      stripeProductId: string;
-      unitAmount: number;
-      currency?: string;
-      type: "one_time" | "recurring";
-      interval?: "day" | "week" | "month" | "year";
-      intervalCount?: number;
-      nickname?: string;
-      metadata?: Record<string, string>;
-    },
-  ) {
+  async createPrice(ctx: RunCtx, opts: pricesImpl.CreatePriceOptions) {
     return pricesImpl.createPrice(this.stripe(), this.component, ctx, opts);
   }
 
@@ -644,19 +643,7 @@ export class BetterStripe {
 
   async upsertPrice(
     ctx: RunCtx,
-    opts: {
-      stripePriceId: string;
-      productId: string;
-      stripeProductId: string;
-      nickname?: string;
-      unitAmount: number;
-      currency: string;
-      active: boolean;
-      type: "one_time" | "recurring";
-      interval?: "day" | "week" | "month" | "year";
-      intervalCount?: number;
-      metadata?: Record<string, unknown>;
-    },
+    opts: Parameters<typeof pricesImpl.upsertPrice>[2],
   ) {
     return pricesImpl.upsertPrice(this.component, ctx, opts);
   }
@@ -954,23 +941,7 @@ export class BetterStripe {
 
   async upsertSubscription(
     ctx: RunCtx,
-    opts: {
-      stripeSubscriptionId: string;
-      accountId?: string;
-      userId: string;
-      orgId?: string;
-      status: SubscriptionStatus;
-      priceId?: string;
-      quantity?: number;
-      currentPeriodStart?: string;
-      currentPeriodEnd?: string;
-      cancelAtPeriodEnd: boolean;
-      canceledAt?: string;
-      isTrialing: boolean;
-      trialStart?: string;
-      trialEnd?: string;
-      metadata?: Record<string, unknown>;
-    },
+    opts: Parameters<typeof subscriptionsImpl.upsertSubscription>[2],
   ) {
     return subscriptionsImpl.upsertSubscription(this.component, ctx, opts);
   }
@@ -1014,22 +985,7 @@ export class BetterStripe {
 
   async upsertInvoice(
     ctx: RunCtx,
-    opts: {
-      stripeInvoiceId: string;
-      userId: string;
-      orgId?: string;
-      accountId?: string;
-      subscriptionId?: string;
-      status: InvoiceStatus;
-      currency: string;
-      amountDue: number;
-      amountPaid: number;
-      hostedInvoiceUrl?: string;
-      invoicePdf?: string;
-      periodStart?: string;
-      periodEnd?: string;
-      metadata?: Record<string, unknown>;
-    },
+    opts: Parameters<typeof invoicesImpl.upsertInvoice>[2],
   ) {
     return invoicesImpl.upsertInvoice(this.component, ctx, opts);
   }
@@ -1042,6 +998,42 @@ export class BetterStripe {
     return configImpl.getStripeMode(this.component, ctx);
   }
 
+  getBalanceFundingCapability() {
+    return balanceFundingImpl.getBalanceFundingCapability(
+      this.stripeApiVersion,
+    );
+  }
+
+  async prepareBalanceFunding(
+    _ctx: RunCtx,
+    opts: balanceFundingImpl.PrepareBalanceFundingOptions,
+  ) {
+    return balanceFundingImpl.prepareBalanceFunding(
+      this.stripe(),
+      this.stripeApiVersion,
+      opts,
+    );
+  }
+
+  async setBalanceFunding(
+    _ctx: RunCtx,
+    opts: balanceFundingImpl.SetBalanceFundingOptions,
+  ) {
+    return balanceFundingImpl.setBalanceFunding(
+      this.stripe(),
+      this.stripeApiVersion,
+      opts,
+    );
+  }
+
+  /** Authorize the customer in the host; validates subscription ownership. */
+  async getUpcomingInvoicePreview(
+    _ctx: RunCtx,
+    opts: invoicePreviewImpl.UpcomingInvoicePreviewOptions,
+  ) {
+    return invoicePreviewImpl.getUpcomingInvoicePreview(this.stripe(), opts);
+  }
+
   async getInvoiceFromStripe(ctx: RunCtx, opts: { stripeInvoiceId: string }) {
     return invoicesImpl.getInvoiceFromStripe(this.stripe(), ctx, opts);
   }
@@ -1272,6 +1264,17 @@ export class BetterStripe {
   ) {
     return providerReads.getCouponFromStripe(this.stripe(), opts);
   }
+  get costRecovery() {
+    return new CostRecoveryClient(this.component);
+  }
+
+  async getProcessingCostContext(
+    _ctx: RunCtx,
+    opts: processingCostsImpl.ProcessingCostOptions,
+  ) {
+    return processingCostsImpl.getProcessingCostContext(this.stripe(), opts);
+  }
+
   async getVerifiedSale(
     _ctx: RunCtx,
     opts: saleContextImpl.VerifiedSaleOptions,

package/src/client/products/catalog-idempotency.test.ts

@@ -0,0 +1,116 @@
+import type Stripe from "stripe";
+import { type FunctionReference, componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import schema from "../../component/schema.js";
+import { initConvexTest } from "../setup.test.js";
+import { BetterStripe } from "../index.js";
+import { getStripeClient, type Component, type RunCtx } from "../helpers.js";
+const modules = import.meta.glob("../../component/**/*.{ts,js,tsx,jsx}");
+
+it("reuses provider products/prices after persistence failure and keeps old subscription prices", async () => {
+  const t = initConvexTest();
+  t.registerComponent("betterStripe", schema, modules);
+  const component = componentsGeneric().betterStripe as unknown as Component;
+  const key = `sk_test_catalog_${crypto.randomUUID()}`;
+  const stripe = new BetterStripe(component, { STRIPE_SECRET_KEY: key });
+  const sdk = getStripeClient(key);
+  const products = new Map<string, Stripe.Product>();
+  const prices = new Map<string, Stripe.Price>();
+  const productCreate = vi
+    .spyOn(sdk.products, "create")
+    .mockImplementation(async (params, options) => {
+      const id = options?.idempotencyKey ?? crypto.randomUUID();
+      if (!products.has(id))
+        products.set(id, {
+          id: `prod_${products.size}`,
+          ...params,
+          active: true,
+        } as Stripe.Product);
+      return products.get(id)! as Stripe.Response<Stripe.Product>;
+    });
+  const priceCreate = vi
+    .spyOn(sdk.prices, "create")
+    .mockImplementation(async (params, options) => {
+      const id = options?.idempotencyKey ?? crypto.randomUUID();
+      if (!prices.has(id))
+        prices.set(id, {
+          id: `price_${prices.size}`,
+          ...params,
+          active: true,
+        } as unknown as Stripe.Price);
+      return prices.get(id)! as Stripe.Response<Stripe.Price>;
+    });
+  let failNext = true;
+  const ctx = {
+    runQuery: (
+      ref: FunctionReference<"query">,
+      args: Record<string, unknown>,
+    ) => t.query(ref, args),
+    runMutation: (
+      ref: FunctionReference<"mutation">,
+      args: Record<string, unknown>,
+    ) => {
+      if (failNext) {
+        failNext = false;
+        throw new Error("simulated persistence outage");
+      }
+      return t.mutation(ref, args);
+    },
+  } as unknown as RunCtx;
+  const productOptions = {
+    name: "Retry-safe plan",
+    idempotencyKey: "catalog:product:plan",
+  };
+  await expect(stripe.createProduct(ctx, productOptions)).rejects.toThrow();
+  const product = await stripe.createProduct(ctx, productOptions);
+  expect(products.size).toBe(1);
+  expect(productCreate.mock.calls[1][1]).toEqual({
+    idempotencyKey: productOptions.idempotencyKey,
+  });
+  expect(product.productId).not.toBeNull();
+
+  const priceOptions = {
+    stripeProductId: product.stripeProductId,
+    unitAmount: 900,
+    type: "recurring" as const,
+    interval: "month" as const,
+    idempotencyKey: "catalog:plan:version:1",
+  };
+  failNext = true;
+  await expect(stripe.createPrice(ctx, priceOptions)).rejects.toThrow();
+  const oldPrice = await stripe.createPrice(ctx, priceOptions);
+  expect(prices.size).toBe(1);
+  expect(priceCreate.mock.calls[1][1]).toEqual({
+    idempotencyKey: priceOptions.idempotencyKey,
+  });
+  await stripe.upsertSubscription(ctx, {
+    stripeSubscriptionId: "sub_existing",
+    userId: "buyer",
+    accountId: "acct_buyer",
+    status: "active",
+    priceId: oldPrice.stripePriceId,
+    cancelAtPeriodEnd: false,
+    isTrialing: false,
+  });
+  const newPrice = await stripe.createPrice(ctx, {
+    ...priceOptions,
+    unitAmount: 4900,
+    idempotencyKey: "catalog:plan:version:2",
+  });
+  expect(newPrice.stripePriceId).not.toBe(oldPrice.stripePriceId);
+  expect(prices.size).toBe(2);
+  expect(
+    (
+      await stripe.getSubscriptionByStripeId(ctx, {
+        stripeSubscriptionId: "sub_existing",
+      })
+    )?.priceId,
+  ).toBe(oldPrice.stripePriceId);
+  expect(
+    (
+      await stripe.getPriceByStripeId(ctx, {
+        stripePriceId: oldPrice.stripePriceId,
+      })
+    )?.unitAmount,
+  ).toBe(900);
+});

package/src/client/products/prices.ts

@@ -1,4 +1,5 @@
 import type Stripe from "stripe";
+import { idempotencyOptions } from "../core/idempotency.js";
 
 import type { Component, RunCtx } from "../helpers.js";
 import { runMutationOrThrow } from "../helpers.js";
@@ -10,20 +11,23 @@ import { componentRef } from "../webhooks/helpers.js";
 // Price methods
 // =============================================================================
 
+export type CreatePriceOptions = {
+  stripeProductId: string;
+  unitAmount: number;
+  currency?: string;
+  type: "one_time" | "recurring";
+  interval?: "day" | "week" | "month" | "year";
+  intervalCount?: number;
+  nickname?: string;
+  metadata?: Record<string, string>;
+  idempotencyKey?: string;
+};
+
 export async function createPrice(
   stripe: Stripe,
   component: Component,
   ctx: RunCtx,
-  opts: {
-    stripeProductId: string;
-    unitAmount: number;
-    currency?: string;
-    type: "one_time" | "recurring";
-    interval?: "day" | "week" | "month" | "year";
-    intervalCount?: number;
-    nickname?: string;
-    metadata?: Record<string, string>;
-  },
+  opts: CreatePriceOptions,
 ) {
   // Validate the product exists in the component DB *before* writing to Stripe.
   // Creating the price first and throwing afterwards would orphan a price in
@@ -54,7 +58,10 @@ export async function createPrice(
     };
   }
 
-  const price = await stripe.prices.create(priceParams);
+  const requestOptions = idempotencyOptions(opts.idempotencyKey);
+  const price = requestOptions
+    ? await stripe.prices.create(priceParams, requestOptions)
+    : await stripe.prices.create(priceParams);
 
   await runMutationOrThrow(
     ctx,

package/src/client/products/products.ts

@@ -1,4 +1,5 @@
 import type Stripe from "stripe";
+import { idempotencyOptions } from "../core/idempotency.js";
 
 import type { Component, RunCtx } from "../helpers.js";
 import { runMutationOrThrow } from "../helpers.js";
@@ -53,19 +54,20 @@ async function resolveProductStatementDescriptor(
 // Product methods
 // =============================================================================
 
+export type CreateProductOptions = {
+  name: string;
+  description?: string;
+  active?: boolean;
+  accountId?: string;
+  metadata?: Record<string, string>;
+  idempotencyKey?: string;
+};
+
 export async function createProduct(
   stripe: Stripe,
   component: Component,
   ctx: RunCtx,
-  opts: {
-    name: string;
-    description?: string;
-    active?: boolean;
-    accountId?: string;
-    metadata?: Record<string, string>;
-    /** Platform default statement-descriptor suffix (BetterStripe option). */
-    defaultStatementDescriptorSuffix?: string;
-  },
+  opts: CreateProductOptions & { defaultStatementDescriptorSuffix?: string },
 ) {
   const statementDescriptor = await resolveProductStatementDescriptor(
     component,
@@ -74,7 +76,7 @@ export async function createProduct(
     opts.defaultStatementDescriptorSuffix,
   );
 
-  const product = await stripe.products.create({
+  const params: Stripe.ProductCreateParams = {
     name: opts.name,
     description: opts.description ?? undefined,
     active: opts.active ?? true,
@@ -82,7 +84,11 @@ export async function createProduct(
     ...(statementDescriptor
       ? { statement_descriptor: statementDescriptor }
       : {}),
-  });
+  };
+  const requestOptions = idempotencyOptions(opts.idempotencyKey);
+  const product = requestOptions
+    ? await stripe.products.create(params, requestOptions)
+    : await stripe.products.create(params);
 
   await runMutationOrThrow(
     ctx,