@fantastic.dev/better-stripe 0.9.0 → 0.10.1

package/src/client/customer-preview.test.ts

@@ -0,0 +1,185 @@
+import Stripe from "stripe";
+import { componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { BetterStripe, type BetterStripeOptions } from "./index.js";
+import { getStripeClient, type Component, type RunCtx } from "./helpers.js";
+
+const preview = "2026-09-30.preview";
+const component = componentsGeneric().betterStripe as unknown as Component;
+const ctx = {
+  runQuery: vi.fn().mockImplementation(async (_ref, args) =>
+    args?.stripeAccountId
+      ? {
+          _id: "row",
+          userId: "buyer",
+          stripeAccountId: "acct_buyer",
+          appliedConfigurations: [],
+        }
+      : null,
+  ),
+  runMutation: vi.fn().mockResolvedValue("row"),
+} as unknown as RunCtx;
+function fixture(version: string | undefined) {
+  const key = `sk_test_preview_transport_${crypto.randomUUID()}`;
+  const bs = new BetterStripe(component, {
+    STRIPE_SECRET_KEY: key,
+    ...(version === undefined ? {} : { stripeApiVersion: version }),
+  } as BetterStripeOptions);
+  const calls: {
+    path: string;
+    version: string;
+    idempotency: string | undefined;
+    body: string;
+  }[] = [];
+  for (const selected of new Set([version, "2026-09-30.endive"])) {
+    const sdk = getStripeClient(key, selected);
+    (
+      sdk as unknown as { _setApiField: (name: string, value: unknown) => void }
+    )._setApiField("httpClient", {
+      getClientName: () => "preview-contract-test",
+      makeRequest: async (
+        ...[, , path, , headers, body]: Parameters<
+          ReturnType<typeof Stripe.createNodeHttpClient>["makeRequest"]
+        >
+      ) => {
+        calls.push({
+          path,
+          version: String(headers["Stripe-Version"]),
+          idempotency: headers["Idempotency-Key"] as string | undefined,
+          body: String(body),
+        });
+        const data = path.includes("/checkout/sessions")
+          ? {
+              id: "cs_preview",
+              object: "checkout.session",
+              client_secret: "test_secret",
+              status: "open",
+            }
+          : path.includes("/v2/core/accounts")
+            ? {
+                id: "acct_buyer",
+                object: "v2.core.account",
+                applied_configurations: ["customer"],
+                configuration: { customer: {} },
+                metadata: { userId: "buyer" },
+              }
+            : path.includes("/prices/")
+              ? {
+                  id: "price_preview",
+                  active: true,
+                  unit_amount: 1000,
+                  currency: "usd",
+                  type: "one_time",
+                  product: "prod_preview",
+                }
+              : path.includes("/products/")
+                ? { id: "prod_preview", active: true }
+                : path.includes("/billing_portal/sessions")
+                  ? {
+                      id: "bps_preview",
+                      url: "https://billing.stripe.com/test",
+                    }
+                  : path.includes("/refunds")
+                    ? { id: "re_preview", status: "succeeded" }
+                    : path.includes("/payment_intents/")
+                      ? {
+                          id: "pi_preview",
+                          latest_charge: {
+                            id: "ch_preview",
+                            amount: 1000,
+                            currency: "usd",
+                          },
+                        }
+                      : path.includes("/charges/")
+                        ? { id: "ch_preview", amount: 1000, currency: "usd" }
+                        : path.includes("/coupons/")
+                          ? { id: "coupon_preview", valid: true }
+                          : {
+                              id: "sub_preview",
+                              status: "active",
+                              customer_account: "acct_buyer",
+                              items: { data: [] },
+                              metadata: {},
+                            };
+        return {
+          getStatusCode: () => 200,
+          getHeaders: () => ({}),
+          getRawResponse: () => ({}),
+          toJSON: async () => data,
+          toStream: () => {
+            throw new Error("Unexpected stream");
+          },
+        };
+      },
+    });
+  }
+  return { bs, calls };
+}
+it.each([undefined, preview])(
+  "uses one selected version for account, Checkout, billing, refunds and authoritative reads (%s)",
+  async (version) => {
+    const { bs, calls } = fixture(version);
+    await bs.ensureCustomerAccount(ctx, {
+      userId: "buyer",
+      email: "buyer@example.com",
+      idempotencyKey: "account:buyer",
+    });
+    await bs.createCheckoutSession(ctx, {
+      userId: "buyer",
+      accountId: "acct_buyer",
+      stripePriceId: "price_preview",
+      mode: "payment",
+      returnUrl: "https://example.com/receipt",
+      idempotencyKey: "order:one",
+    });
+    await bs.getCheckoutSessionFromStripe(ctx, {
+      stripeSessionId: "cs_preview",
+    });
+    await bs.getSubscriptionFromStripe(ctx, {
+      stripeSubscriptionId: "sub_preview",
+    });
+    await bs.getCouponFromStripe(ctx, { stripeCouponId: "coupon_preview" });
+    await bs.cancelSubscription(ctx, { stripeSubscriptionId: "sub_preview" });
+    await bs.reactivateSubscription(ctx, {
+      stripeSubscriptionId: "sub_preview",
+    });
+    await bs.createBillingPortalSession(ctx, {
+      stripeAccountId: "acct_buyer",
+      returnUrl: "https://example.com/billing",
+    });
+    await bs.createRefund(ctx, {
+      stripeChargeId: "ch_preview",
+      idempotencyKey: "refund:one",
+    });
+    expect(calls.length).toBeGreaterThanOrEqual(8);
+    expect(new Set(calls.map((c) => c.version))).toEqual(
+      new Set([version ?? "2026-09-30.endive"]),
+    );
+    expect(calls.find((c) => c.path === "/v2/core/accounts")?.idempotency).toBe(
+      "account:buyer",
+    );
+    expect(
+      calls.find((c) => c.path === "/v1/checkout/sessions" && c.idempotency)
+        ?.idempotency,
+    ).toBe("order:one");
+    expect(
+      calls.find((c) => c.path === "/v1/checkout/sessions" && c.idempotency)
+        ?.body,
+    ).toContain("customer_account=acct_buyer");
+    expect(
+      calls.find((c) => c.path === "/v2/core/accounts")?.body,
+    ).not.toContain("merchant");
+    expect(bs.stripeApiVersion).toBe(version ?? "2026-09-30.endive");
+  },
+);
+it.each(["", "2020-08-27", "2026-09-30.preview; unsafe", "not-a-version"])(
+  "rejects unsupported client versions clearly (%s)",
+  (version) => {
+    expect(
+      () =>
+        new BetterStripe(component, {
+          stripeApiVersion: version,
+        } as unknown as BetterStripeOptions),
+    ).toThrow("Unsupported Stripe API version");
+  },
+);

package/src/client/index.ts

@@ -1,3 +1,47 @@
+import type { HttpRouter } from "convex/server";
+import { registerClientRoutes } from "./previewRoutes.js";
+import {
+  resolveStripeApiVersion,
+  type SupportedStripeApiVersion,
+} from "./apiVersion.js";
+export {
+  STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+  type SupportedStripeApiVersion,
+} from "./apiVersion.js";
+export type {
+  CheckoutSessionReadOptions,
+  SubscriptionReadOptions,
+  CouponReadOptions,
+} from "./billing/providerReads.js";
+import * as providerReads from "./billing/providerReads.js";
+export type { CreateAccountOptions } from "./core/accounts.js";
+import { buildAsyncHookRoutes } from "./webhooks/asyncHooks.js";
+import * as saleContextImpl from "./settlement/verifiedSale.js";
+import * as settlementImpl from "./settlement/settleSale.js";
+import * as commissionImpl from "./settlement/commissions.js";
+import * as payoutSnapshotImpl from "./connect/payoutSnapshot.js";
+export { allocateSale } from "./settlement/allocation.js";
+export type {
+  SaleAllocation,
+  SaleAllocationOptions,
+} from "./settlement/allocation.js";
+export type {
+  VerifiedSale,
+  VerifiedSaleOptions,
+} from "./settlement/verifiedSale.js";
+export type { SettleSaleOptions } from "./settlement/settleSale.js";
+export type { SettlementResult } from "./settlement/execution.js";
+export type {
+  CommissionTerm,
+  CommissionSelectionOptions,
+  CommissionSelection,
+  CommissionDecision,
+} from "./settlement/commissions.js";
+export type {
+  RecipientPayoutSnapshot,
+  RecipientPayoutRow,
+  PayoutSnapshotOptions,
+} from "./connect/payoutSnapshot.js";
 import { internalActionGeneric, internalMutationGeneric } from "convex/server";
 import { v } from "convex/values";
 import Stripe from "stripe";
@@ -146,12 +190,11 @@ function clonePlatformFee(config: PlatformFeeConfig): PlatformFeeConfig {
   };
 }
 
-// =============================================================================
 // BETTER STRIPE CLIENT
-// =============================================================================
 
 export class BetterStripe {
   public component: Component;
+  readonly stripeApiVersion: SupportedStripeApiVersion;
   private _apiKey?: string;
   private _triggers?: SyncTriggers;
   private _hooks?: AsyncHooks;
@@ -160,6 +203,7 @@ export class BetterStripe {
 
   constructor(component: BetterStripeComponent, options?: BetterStripeOptions) {
     this.component = component;
+    this.stripeApiVersion = resolveStripeApiVersion(options?.stripeApiVersion);
     this._apiKey = options?.STRIPE_SECRET_KEY;
     this._triggers = options?.triggers;
     this._hooks = options?.hooks;
@@ -208,13 +252,18 @@ export class BetterStripe {
     return key;
   }
 
-  private stripe(apiVersion?: string): Stripe {
-    return getStripeClient(this.apiKey, apiVersion);
+  registerRoutes(
+    http: HttpRouter,
+    config?: Parameters<typeof registerClientRoutes>[2],
+  ) {
+    return registerClientRoutes(this, http, config);
+  }
+
+  private stripe(): Stripe {
+    return getStripeClient(this.apiKey, this.stripeApiVersion);
   }
 
-  // ============================================================================
   // Static defaults (preserved for backwards compatibility)
-  // ============================================================================
 
   static DEFAULT_ACCOUNT_CONFIGURATION =
     accountsImpl.DEFAULT_ACCOUNT_CONFIGURATION;
@@ -222,21 +271,9 @@ export class BetterStripe {
   static DEFAULT_CUSTOMER_CONFIGURATION =
     accountsImpl.DEFAULT_CUSTOMER_CONFIGURATION;
 
-  // ============================================================================
   // ACCOUNT METHODS
-  // ============================================================================
 
-  async createAccount(
-    ctx: RunCtx,
-    opts: {
-      userId: string;
-      email?: string;
-      name?: string;
-      country?: string;
-      orgId?: string;
-      metadata?: Record<string, string>;
-    },
-  ) {
+  async createAccount(ctx: RunCtx, opts: accountsImpl.CreateAccountOptions) {
     return accountsImpl.createAccount(this.stripe(), this.component, ctx, opts);
   }
 
@@ -276,14 +313,7 @@ export class BetterStripe {
 
   async getOrCreateAccount(
     ctx: RunCtx,
-    opts: {
-      userId: string;
-      email?: string;
-      name?: string;
-      country?: string;
-      orgId?: string;
-      metadata?: Record<string, string>;
-    },
+    opts: accountsImpl.CreateAccountOptions,
   ) {
     return accountsImpl.getOrCreateAccount(
       this.stripe(),
@@ -453,14 +483,7 @@ export class BetterStripe {
    */
   async ensureCustomerAccount(
     ctx: RunCtx,
-    opts: {
-      userId: string;
-      email?: string;
-      name?: string;
-      country?: string;
-      orgId?: string;
-      metadata?: Record<string, string>;
-    },
+    opts: accountsImpl.CreateAccountOptions,
   ) {
     return accountsImpl.ensureCustomerAccount(
       this.stripe(),
@@ -470,9 +493,7 @@ export class BetterStripe {
     );
   }
 
-  // ============================================================================
   // PRODUCT METHODS
-  // ============================================================================
 
   async createProduct(
     ctx: RunCtx,
@@ -559,9 +580,7 @@ export class BetterStripe {
     return productsImpl.deleteProduct(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // PRICE METHODS
-  // ============================================================================
 
   async createPrice(
     ctx: RunCtx,
@@ -649,13 +668,12 @@ export class BetterStripe {
     return pricesImpl.listStripePrices(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // CHECKOUT METHODS
-  // ============================================================================
 
   async createCheckoutSession(
     ctx: RunCtx,
     opts: {
+      idempotencyKey?: string;
       userId: string;
       orgId?: string;
       stripePriceId: string;
@@ -744,9 +762,7 @@ export class BetterStripe {
     return checkoutImpl.updateCheckoutSession(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // SUBSCRIPTION METHODS
-  // ============================================================================
 
   /**
    * Create a subscription directly for a V2 buyer (`customer_account`), off the
@@ -943,14 +959,7 @@ export class BetterStripe {
       accountId?: string;
       userId: string;
       orgId?: string;
-      status:
-        | "active"
-        | "trialing"
-        | "past_due"
-        | "canceled"
-        | "incomplete"
-        | "unpaid"
-        | "paused";
+      status: SubscriptionStatus;
       priceId?: string;
       quantity?: number;
       currentPeriodStart?: string;
@@ -970,9 +979,7 @@ export class BetterStripe {
     return subscriptionsImpl.getTrialStatus(this.component, ctx, opts);
   }
 
-  // ============================================================================
   // INVOICE METHODS
-  // ============================================================================
 
   async listInvoices(
     ctx: RunCtx,
@@ -1039,9 +1046,7 @@ export class BetterStripe {
     return invoicesImpl.getInvoiceFromStripe(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // PAYMENT METHOD METHODS
-  // ============================================================================
 
   async listPaymentMethods(
     ctx: RunCtx,
@@ -1072,9 +1077,7 @@ export class BetterStripe {
     return paymentMethodsImpl.setDefaultPaymentMethod(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // ACCOUNT LINK METHODS
-  // ============================================================================
 
   async createAccountLink(
     ctx: RunCtx,
@@ -1150,9 +1153,7 @@ export class BetterStripe {
     return accountLinksImpl.getCountrySpecs(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // PAYOUT METHODS
-  // ============================================================================
 
   async createPayout(
     ctx: RunCtx,
@@ -1253,6 +1254,50 @@ export class BetterStripe {
    * (`{ available, pending, currency }`, minor units) per currency — each entry
    * feeds the headless `PayoutSchedule` component's `balance` prop directly.
    */
+  async getCheckoutSessionFromStripe(
+    _ctx: RunCtx,
+    opts: providerReads.CheckoutSessionReadOptions,
+  ) {
+    return providerReads.getCheckoutSessionFromStripe(this.stripe(), opts);
+  }
+  async getSubscriptionFromStripe(
+    _ctx: RunCtx,
+    opts: providerReads.SubscriptionReadOptions,
+  ) {
+    return providerReads.getSubscriptionFromStripe(this.stripe(), opts);
+  }
+  async getCouponFromStripe(
+    _ctx: RunCtx,
+    opts: providerReads.CouponReadOptions,
+  ) {
+    return providerReads.getCouponFromStripe(this.stripe(), opts);
+  }
+  async getVerifiedSale(
+    _ctx: RunCtx,
+    opts: saleContextImpl.VerifiedSaleOptions,
+  ) {
+    return saleContextImpl.getVerifiedSale(this.stripe(), opts);
+  }
+  async settleSale(ctx: RunCtx, opts: settlementImpl.SettleSaleOptions) {
+    return settlementImpl.settleSale(this.stripe(), this.component, ctx, opts);
+  }
+  async selectCommissionInvoice(
+    ctx: RunCtx,
+    opts: commissionImpl.CommissionSelectionOptions,
+  ) {
+    return commissionImpl.selectCommissionInvoice(
+      this.stripe(),
+      this.component,
+      ctx,
+      opts,
+    );
+  }
+  async getPayoutSnapshot(
+    _ctx: RunCtx,
+    opts: payoutSnapshotImpl.PayoutSnapshotOptions,
+  ) {
+    return payoutSnapshotImpl.getPayoutSnapshot(this.stripe(), opts);
+  }
   async getAccountBalance(_ctx: RunCtx, opts: { stripeAccountId: string }) {
     return payoutsImpl.getAccountBalance(this.stripe(), opts);
   }
@@ -1268,9 +1313,7 @@ export class BetterStripe {
     return payoutsImpl.listPayouts(this.component, ctx, opts);
   }
 
-  // ============================================================================
   // REFUND METHODS
-  // ============================================================================
 
   /**
    * Issue a refund (BTS-34). `refundApplicationFee` and `reverseTransfer`
@@ -1325,9 +1368,7 @@ export class BetterStripe {
     return refundsImpl.listRefunds(this.component, ctx, opts);
   }
 
-  // ============================================================================
   // DISPUTE METHODS
-  // ============================================================================
 
   async getDisputeByStripeId(
     ctx: RunCtx,
@@ -1397,9 +1438,7 @@ export class BetterStripe {
     return disputesImpl.closeDispute(this.stripe(), this.component, ctx, opts);
   }
 
-  // ============================================================================
   // WEBHOOK ENDPOINT MANAGEMENT
-  // ============================================================================
 
   async listWebhookEndpoints(ctx: RunCtx, opts?: { limit?: number }) {
     return webhookEndpointsImpl.listWebhookEndpoints(this.stripe(), ctx, opts);
@@ -1407,13 +1446,12 @@ export class BetterStripe {
 
   async createWebhookEndpoint(
     ctx: RunCtx,
-    opts: {
-      url: string;
-      description?: string;
-      enabledEvents?: string[];
-    },
+    opts: webhookEndpointsImpl.WebhookEndpointOptions,
   ): Promise<{ id: string; secret: string; url: string }> {
-    return webhookEndpointsImpl.createWebhookEndpoint(this.stripe(), ctx, opts);
+    return webhookEndpointsImpl.createWebhookEndpoint(this.stripe(), ctx, {
+      ...opts,
+      apiVersion: this.stripeApiVersion,
+    });
   }
 
   async listEventDestinations(ctx: RunCtx, opts?: { limit?: number }) {
@@ -1422,13 +1460,7 @@ export class BetterStripe {
 
   async setupEventDestination(
     ctx: RunCtx,
-    opts: {
-      url: string;
-      name?: string;
-      description?: string;
-      enabledEvents?: string[];
-      eventPayload?: "snapshot" | "thin";
-    },
+    opts: webhookEndpointsImpl.EventDestinationOptions,
   ): Promise<{
     id: string;
     secret: string;
@@ -1436,12 +1468,13 @@ export class BetterStripe {
     enabledEvents: string[];
     created: boolean;
   }> {
-    return webhookEndpointsImpl.setupEventDestination(this.stripe(), ctx, opts);
+    return webhookEndpointsImpl.setupEventDestination(this.stripe(), ctx, {
+      ...opts,
+      apiVersion: this.stripeApiVersion,
+    });
   }
 
-  // ============================================================================
   // WEBHOOK EVENT QUERIES
-  // ============================================================================
 
   async listWebhookEvents(
     ctx: RunCtx,
@@ -1462,17 +1495,13 @@ export class BetterStripe {
     }>;
   }
 
-  // ============================================================================
   // DATA MANAGEMENT
-  // ============================================================================
 
   async clearAll(ctx: RunCtx): Promise<{ cleared: number; tables: string[] }> {
     return dataImpl.clearAll(this.component, ctx);
   }
 
-  // ============================================================================
   // SYNC METHODS
-  // ============================================================================
 
   async syncAllAccounts(ctx: RunCtx) {
     return accountsImpl.syncAllAccounts(this.stripe(), this.component, ctx);
@@ -1490,9 +1519,7 @@ export class BetterStripe {
     );
   }
 
-  // ============================================================================
   // WEBHOOK HANDLER EXPORT (BetterAuth-style)
-  // ============================================================================
 
   /**
    * Build the two webhook handler function definitions for the app to export
@@ -1811,38 +1838,7 @@ export class BetterStripe {
         ),
     };
 
-    /** One routing entry per async hook — identical mapping to the old API. */
-    const ASYNC: Record<
-      AsyncHookName,
-      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined
-    > = {
-      afterAccountUpdated: hooks?.onAccountUpdated as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterCheckoutCompleted: hooks?.onCheckoutCompleted as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterSubscriptionUpdated: hooks?.onSubscriptionUpdated as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterSubscriptionCanceled: hooks?.onSubscriptionCanceled as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterTrialEnding: hooks?.onTrialEnding as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterInvoicePaid: hooks?.onInvoicePaid as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterInvoicePaymentFailed: hooks?.onInvoicePaymentFailed as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterPaymentSucceeded: hooks?.onPaymentSucceeded as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterPaymentFailed: hooks?.onPaymentFailed as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterPayoutCompleted: hooks?.onPayoutCompleted as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterRefundCreated: hooks?.onRefundCreated as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterDisputeCreated: hooks?.onDisputeCreated as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-      afterDisputeClosed: hooks?.onDisputeClosed as
-        ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
-    };
+    const ASYNC = buildAsyncHookRoutes(hooks);
 
     const syncWebhook = internalMutationGeneric({
       args: { dispatcher: v.string(), data: v.any() },

package/src/client/previewRoutes.ts

@@ -0,0 +1,26 @@
+import type { HttpRouter } from "convex/server";
+import type { Component } from "./helpers.js";
+import type { RegisterRoutesConfig } from "./types.js";
+import { registerRoutes } from "./webhooks/index.js";
+import { throwStripeError } from "./errors.js";
+export function registerClientRoutes(
+  client: { component: Component; apiKey: string; stripeApiVersion: string },
+  http: HttpRouter,
+  config?: RegisterRoutesConfig,
+) {
+  if (
+    (config?.stripeApiVersion !== undefined &&
+      config.stripeApiVersion !== client.stripeApiVersion) ||
+    (config?.stripeSecretKey !== undefined &&
+      config.stripeSecretKey !== client.apiKey)
+  )
+    throwStripeError(
+      "INVALID_CONFIGURATION",
+      "Webhook API version and secret key must match the BetterStripe client.",
+    );
+  registerRoutes(http, client.component, {
+    ...config,
+    stripeApiVersion: client.stripeApiVersion,
+    stripeSecretKey: client.apiKey,
+  });
+}