@fantastic.dev/better-stripe 0.10.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,13 @@
+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,
@@ -184,6 +194,7 @@ function clonePlatformFee(config: PlatformFeeConfig): PlatformFeeConfig {
 
 export class BetterStripe {
   public component: Component;
+  readonly stripeApiVersion: SupportedStripeApiVersion;
   private _apiKey?: string;
   private _triggers?: SyncTriggers;
   private _hooks?: AsyncHooks;
@@ -192,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;
@@ -240,8 +252,15 @@ 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)
@@ -1427,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 }) {
@@ -1442,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;
@@ -1456,7 +1468,10 @@ 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

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,
+  });
+}

package/src/client/stripe-version.test.ts

@@ -11,10 +11,16 @@ describe("Stripe version pin", () => {
     expect(Stripe.API_VERSION).toBe(STRIPE_API_VERSION);
   });
 
-  it.each([getStripeClient, getStripe])(
+  it.each(
+    [getStripeClient, getStripe].flatMap((factory) =>
+      [undefined, "2026-09-30.preview" as const].map(
+        (version) => [factory, version] as const,
+      ),
+    ),
+  )(
     "pins outgoing API requests from each factory",
-    async (factory) => {
-      const stripe = factory("sk_test_version_transport_only");
+    async (factory, selectedVersion) => {
+      const stripe = factory("sk_test_version_transport_only", selectedVersion);
       let version: string | undefined;
       // Factories deliberately expose no transport override. Replace only the
       // SDK's transport slot, leaving its request serializer/headers untouched.
@@ -41,7 +47,7 @@ describe("Stripe version pin", () => {
         },
       });
       await stripe.products.retrieve("prod_local");
-      expect(version).toBe(STRIPE_API_VERSION);
+      expect(version).toBe(selectedVersion ?? STRIPE_API_VERSION);
     },
   );
 });

package/src/client/types/options.ts

@@ -1,3 +1,4 @@
+import type { SupportedStripeApiVersion } from "../apiVersion.js";
 import type {
   StripeEventHandler,
   StripeEventHandlers,
@@ -51,6 +52,8 @@ export type FeeOverride = PlatformFeeConfig;
 // ---------------------------------------------------------------------------
 
 export type BetterStripeOptions = {
+  /** Defaults to GA. Non-Connect Accounts v2 customers require explicit preview opt-in. */
+  stripeApiVersion?: SupportedStripeApiVersion;
   STRIPE_SECRET_KEY?: string;
   /** Sync triggers — run in the same transaction as component DB writes */
   triggers?: SyncTriggers;

package/src/client/utils/webhookEndpoints.ts

@@ -1,3 +1,5 @@
+import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
+import { throwStripeError } from "../errors.js";
 import type Stripe from "stripe";
 
 import type { RunCtx } from "../helpers.js";
@@ -73,6 +75,13 @@ export const BETTER_STRIPE_V2_WEBHOOK_EVENTS = [
   "v2.core.account_link.returned",
 ] as const;
 
+/** Minimal customer lifecycle subscription for non-Connect preview merchants. */
+export const BETTER_STRIPE_CUSTOMER_ACCOUNT_EVENTS = [
+  "v2.core.account.created",
+  "v2.core.account[configuration.customer].updated",
+  "v2.core.account[identity].updated",
+] as const;
+
 export type BetterStripeV2WebhookEvent =
   (typeof BETTER_STRIPE_V2_WEBHOOK_EVENTS)[number];
 
@@ -103,14 +112,19 @@ export async function listWebhookEndpoints(
   }));
 }
 
+export type WebhookEndpointOptions = {
+  url: string;
+  description?: string;
+  enabledEvents?: string[];
+};
+export type EventDestinationOptions = WebhookEndpointOptions & {
+  name?: string;
+  eventPayload?: "snapshot" | "thin";
+};
 export async function createWebhookEndpoint(
   stripe: Stripe,
   _ctx: RunCtx,
-  opts: {
-    url: string;
-    description?: string;
-    enabledEvents?: string[];
-  },
+  opts: WebhookEndpointOptions & { apiVersion?: string },
 ): Promise<{ id: string; secret: string; url: string }> {
   // Remove existing endpoint with same URL (secret is only available on create)
   const existing = await stripe.webhookEndpoints.list({ limit: 100 });
@@ -121,6 +135,12 @@ export async function createWebhookEndpoint(
 
   const endpoint = await stripe.webhookEndpoints.create({
     url: opts.url,
+    ...(opts.apiVersion
+      ? {
+          api_version:
+            opts.apiVersion as Stripe.WebhookEndpointCreateParams.ApiVersion,
+        }
+      : {}),
     enabled_events: (opts.enabledEvents ??
       BETTER_STRIPE_WEBHOOK_EVENTS) as Stripe.WebhookEndpointCreateParams.EnabledEvent[],
     description:
@@ -189,14 +209,7 @@ export async function listEventDestinations(
 export async function setupEventDestination(
   stripe: Stripe,
   _ctx: RunCtx,
-  opts: {
-    url: string;
-    name?: string;
-    description?: string;
-    enabledEvents?: string[];
-    /** 'snapshot' for V1 events, 'thin' for V2 events. Defaults to 'thin'. */
-    eventPayload?: "snapshot" | "thin";
-  },
+  opts: EventDestinationOptions & { apiVersion?: string },
 ): Promise<{
   id: string;
   secret: string;
@@ -208,7 +221,9 @@ export async function setupEventDestination(
   const events =
     opts.enabledEvents ??
     (payloadType === "thin"
-      ? [...BETTER_STRIPE_V2_WEBHOOK_EVENTS]
+      ? opts.apiVersion === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+        ? [...BETTER_STRIPE_CUSTOMER_ACCOUNT_EVENTS]
+        : [...BETTER_STRIPE_V2_WEBHOOK_EVENTS]
       : [...BETTER_STRIPE_WEBHOOK_EVENTS]);
   const name =
     opts.name ??
@@ -228,6 +243,36 @@ export async function setupEventDestination(
       d.webhook_endpoint?.url === opts.url && d.event_payload === payloadType,
   );
 
+  if (
+    match &&
+    payloadType === "snapshot" &&
+    opts.apiVersion &&
+    match.snapshot_api_version !== opts.apiVersion
+  )
+    throwStripeError(
+      "INVALID_CONFIGURATION",
+      "Existing snapshot destination API version differs. Create a replacement destination with the selected version and configure its signing secret before retiring the old destination.",
+    );
+
+  if (match && opts.apiVersion === STRIPE_CUSTOMER_PREVIEW_API_VERSION) {
+    const scopes = new Set(
+      (match.events_from ?? []).map((scope) =>
+        scope === "self"
+          ? "@self"
+          : scope === "other_accounts"
+            ? "@accounts"
+            : scope,
+      ),
+    );
+    const required =
+      payloadType === "thin" ? ["@self", "@accounts"] : ["@self"];
+    if (required.some((scope) => !scopes.has(scope)))
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Existing destination event scope differs. Create a replacement with the customer preview scopes before retiring the old destination.",
+      );
+  }
+
   if (match) {
     const updated = await stripe.v2.core.eventDestinations.update(match.id, {
       name,
@@ -256,7 +301,17 @@ export async function setupEventDestination(
     type: "webhook_endpoint",
     event_payload: payloadType,
     enabled_events: events,
-    events_from: payloadType === "thin" ? ["self", "other_accounts"] : ["self"],
+    ...(payloadType === "snapshot" && opts.apiVersion
+      ? { snapshot_api_version: opts.apiVersion }
+      : {}),
+    events_from:
+      opts.apiVersion === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+        ? payloadType === "thin"
+          ? ["@self", "@accounts"]
+          : ["@self"]
+        : payloadType === "thin"
+          ? ["self", "other_accounts"]
+          : ["self"],
     webhook_endpoint: { url: opts.url },
     include: ["webhook_endpoint.signing_secret", "webhook_endpoint.url"],
   });

package/src/client/webhooks/v2.ts

@@ -1,3 +1,4 @@
+import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
 import type Stripe from "stripe";
 
 import { deriveAccountStatus } from "../core/accountStatus.js";
@@ -74,16 +75,19 @@ export async function handleV2Event(
     return null;
   }
 
-  const retrieveParams = {
-    include: [
-      "configuration.merchant",
-      "configuration.recipient",
-      "configuration.customer",
-      "identity",
-      "requirements",
-    ] satisfies NonNullable<
-      Parameters<Stripe["v2"]["core"]["accounts"]["retrieve"]>[1]
-    >["include"],
+  const retrieveParams: NonNullable<
+    Parameters<Stripe["v2"]["core"]["accounts"]["retrieve"]>[1]
+  > = {
+    include:
+      whCtx.config?.stripeApiVersion === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+        ? ["configuration.customer", "identity"]
+        : [
+            "configuration.merchant",
+            "configuration.recipient",
+            "configuration.customer",
+            "identity",
+            "requirements",
+          ],
   };
   // Preserve the verified notification's account/organization context when
   // fetching the latest resource; otherwise organization keys can fetch from

package/src/component/lib/stripeFactory.ts

@@ -1,6 +1,10 @@
 import Stripe from "stripe";
 
-import { STRIPE_API_VERSION } from "../../client/constants.js";
+import {
+  resolveStripeApiVersion,
+  type SupportedStripeApiVersion,
+} from "../../client/apiVersion.js";
+import type { StripeApiVersion } from "../../client/stripe-types.js";
 
 /**
  * Keyed cache for Stripe SDK instances.
@@ -14,14 +18,18 @@ const _clients = new Map<string, Stripe>();
 
 /**
  * Get or create a Stripe SDK instance for the given API key.
- * Uses the component's pinned API version.
+ * Defaults to GA; an explicitly selected supported preview gets its own cache entry.
  */
-export function getStripe(apiKey: string): Stripe {
-  const cacheKey = `${apiKey}:${STRIPE_API_VERSION}`;
+export function getStripe(
+  apiKey: string,
+  apiVersion?: SupportedStripeApiVersion,
+): Stripe {
+  const version = resolveStripeApiVersion(apiVersion);
+  const cacheKey = `${apiKey}:${version}`;
   let client = _clients.get(cacheKey);
   if (!client) {
     client = new Stripe(apiKey, {
-      apiVersion: STRIPE_API_VERSION,
+      apiVersion: version as StripeApiVersion,
       typescript: true,
     });
     _clients.set(cacheKey, client);