@fantastic.dev/better-stripe 0.11.0 → 0.13.0

package/src/client/billing/balanceFunding.test.ts

@@ -0,0 +1,257 @@
+import type Stripe from "stripe";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  getBalanceFundingCapability,
+  prepareBalanceFunding,
+  setBalanceFunding,
+  type BalanceFundingPreparation,
+} from "./balanceFunding.js";
+
+const version = "2026-09-30.preview";
+const scope = {
+  customerAccount: "acct_store",
+  stripeSubscriptionId: "sub_store",
+};
+const preparation: BalanceFundingPreparation = {
+  ...scope,
+  paymentMethodId: "pm_balance",
+  previousPaymentMethodId: "pm_card",
+  previousPaymentMethodTypes: ["card"],
+};
+const raw = {
+  subscriptions: { retrieve: vi.fn(), update: vi.fn() },
+  paymentMethods: { create: vi.fn(), attach: vi.fn(), retrieve: vi.fn() },
+};
+const stripe = raw as unknown as Stripe;
+function sub(
+  method: string | null = "pm_card",
+  types: string[] | null = ["card"],
+) {
+  return {
+    id: "sub_store",
+    customer_account: "acct_store",
+    status: "active",
+    default_payment_method: method,
+    payment_settings: { payment_method_types: types },
+  };
+}
+beforeEach(() => {
+  vi.resetAllMocks();
+  raw.subscriptions.retrieve.mockResolvedValue(sub());
+  raw.subscriptions.update.mockResolvedValue({ id: "sub_store" });
+  raw.paymentMethods.create.mockResolvedValue({
+    id: "pm_balance",
+    type: "stripe_balance",
+  });
+  raw.paymentMethods.retrieve.mockImplementation(async (id: string) => ({
+    id,
+    type: id === "pm_balance" ? "stripe_balance" : "card",
+    customer_account: id === "pm_balance" ? null : "acct_store",
+  }));
+  raw.paymentMethods.attach.mockResolvedValue({ id: "pm_balance" });
+});
+const enable = (enabled = true) =>
+  setBalanceFunding(stripe, version, {
+    preparation,
+    enabled,
+    consent: enabled ? true : undefined,
+    idempotencyKey: "request-1",
+  });
+describe("explicit balance funding", () => {
+  it("reports a required explicit preview without claiming provider eligibility", () => {
+    expect(getBalanceFundingCapability("2026-09-30.endive")).toMatchObject({
+      configured: false,
+    });
+    expect(getBalanceFundingCapability(version)).toMatchObject({
+      configured: true,
+      requiresConnectedAccount: true,
+      eligibility: "provider_validates_on_prepare",
+    });
+  });
+  it("rejects GA calls and missing consent before provider requests", async () => {
+    await expect(
+      prepareBalanceFunding(stripe, "2026-09-30.endive", {
+        ...scope,
+        consent: true,
+        idempotencyKey: "request-1",
+      }),
+    ).rejects.toThrow(/preview/);
+    await expect(
+      setBalanceFunding(stripe, version, {
+        preparation,
+        enabled: true,
+        idempotencyKey: "request-1",
+      }),
+    ).rejects.toThrow(/consent/);
+    expect(raw.subscriptions.retrieve).not.toHaveBeenCalled();
+  });
+  it("prepares without changing the subscription and uses stable phase keys", async () => {
+    expect(
+      await prepareBalanceFunding(stripe, version, {
+        ...scope,
+        consent: true,
+        idempotencyKey: "request-1",
+      }),
+    ).toEqual(preparation);
+    expect(raw.paymentMethods.create).toHaveBeenCalledWith(
+      { type: "stripe_balance" },
+      { idempotencyKey: "request-1:create" },
+    );
+    expect(raw.paymentMethods.attach).toHaveBeenCalledWith(
+      "pm_balance",
+      {
+        customer_account: "acct_store",
+      },
+      { idempotencyKey: "request-1:attach" },
+    );
+    expect(raw.subscriptions.update).not.toHaveBeenCalled();
+  });
+  it("rejects mismatched subscription ownership before preparing or applying", async () => {
+    raw.subscriptions.retrieve.mockResolvedValue({
+      ...sub(),
+      customer_account: "acct_other",
+    });
+    await expect(
+      prepareBalanceFunding(stripe, version, {
+        ...scope,
+        consent: true,
+        idempotencyKey: "request-1",
+      }),
+    ).rejects.toThrow(/does not belong/);
+    await expect(enable()).rejects.toThrow(/does not belong/);
+    expect(raw.paymentMethods.create).not.toHaveBeenCalled();
+    expect(raw.subscriptions.update).not.toHaveBeenCalled();
+  });
+  it("enables and restores the exact previous settings on opt-out", async () => {
+    raw.paymentMethods.retrieve.mockResolvedValue({
+      id: "pm_balance",
+      type: "stripe_balance",
+      customer_account: "acct_store",
+    });
+    await enable();
+    expect(raw.subscriptions.update).toHaveBeenLastCalledWith(
+      "sub_store",
+      {
+        default_payment_method: "pm_balance",
+        payment_settings: { payment_method_types: ["stripe_balance"] },
+      },
+      { idempotencyKey: "request-1:enable" },
+    );
+    raw.subscriptions.retrieve.mockResolvedValue(
+      sub("pm_balance", ["stripe_balance"]),
+    );
+    await enable(false);
+    expect(raw.subscriptions.update).toHaveBeenLastCalledWith(
+      "sub_store",
+      {
+        default_payment_method: "pm_card",
+        payment_settings: { payment_method_types: ["card"] },
+      },
+      { idempotencyKey: "request-1:disable" },
+    );
+  });
+  it("clears the prior default and payment types when they originally inherited customer settings", async () => {
+    raw.paymentMethods.retrieve.mockResolvedValue({
+      id: "pm_balance",
+      type: "stripe_balance",
+      customer_account: "acct_store",
+    });
+    raw.subscriptions.retrieve.mockResolvedValue(
+      sub("pm_balance", ["stripe_balance"]),
+    );
+    await setBalanceFunding(stripe, version, {
+      preparation: {
+        ...preparation,
+        previousPaymentMethodId: null,
+        previousPaymentMethodTypes: null,
+      },
+      enabled: false,
+      idempotencyKey: "request-2",
+    });
+    expect(raw.subscriptions.update).toHaveBeenLastCalledWith(
+      "sub_store",
+      {
+        default_payment_method: "",
+        payment_settings: { payment_method_types: "" },
+      },
+      { idempotencyKey: "request-2:disable" },
+    );
+  });
+  it("recovers an applied provider update after host persistence fails without overwriting the original snapshot", async () => {
+    raw.paymentMethods.retrieve.mockResolvedValue({
+      id: "pm_balance",
+      type: "stripe_balance",
+      customer_account: "acct_store",
+    });
+    raw.subscriptions.retrieve.mockResolvedValue(
+      sub("pm_balance", ["stripe_balance"]),
+    );
+    expect(await enable()).toEqual({ enabled: true });
+    expect(raw.subscriptions.update).not.toHaveBeenCalled();
+    await expect(
+      prepareBalanceFunding(stripe, version, {
+        ...scope,
+        consent: true,
+        idempotencyKey: "new-prepare",
+      }),
+    ).rejects.toThrow(/restoration record/);
+  });
+  it("does not overwrite external payment-source changes with a stale preparation", async () => {
+    raw.paymentMethods.retrieve.mockResolvedValue({
+      id: "pm_balance",
+      type: "stripe_balance",
+      customer_account: "acct_store",
+    });
+    raw.subscriptions.retrieve.mockResolvedValue(
+      sub("pm_external", ["card", "link"]),
+    );
+    await expect(enable()).rejects.toThrow(/changed/);
+    await expect(enable(false)).rejects.toThrow(/changed/);
+    expect(raw.subscriptions.update).not.toHaveBeenCalled();
+  });
+  it("rejects an unrelated balance payment method", async () => {
+    raw.paymentMethods.retrieve.mockResolvedValue({
+      id: "pm_balance",
+      type: "stripe_balance",
+      customer_account: "acct_other",
+    });
+    await expect(enable()).rejects.toThrow(/payment method/);
+  });
+  it("preserves provider preview and update errors for retry decisions", async () => {
+    const failure = Object.assign(new Error("Preview access required"), {
+      code: "parameter_invalid",
+    });
+    raw.paymentMethods.create.mockRejectedValue(failure);
+    await expect(
+      prepareBalanceFunding(stripe, version, {
+        ...scope,
+        consent: true,
+        idempotencyKey: "request-1",
+      }),
+    ).rejects.toBe(failure);
+    raw.paymentMethods.retrieve.mockResolvedValue({
+      id: "pm_balance",
+      type: "stripe_balance",
+      customer_account: "acct_store",
+    });
+    raw.subscriptions.update.mockRejectedValue(failure);
+    await expect(enable()).rejects.toBe(failure);
+  });
+});
+it("requires an explicit runtime request identity and desired state for JavaScript callers", async () => {
+  await expect(
+    prepareBalanceFunding(stripe, version, {
+      ...scope,
+      consent: true,
+      idempotencyKey: undefined as unknown as string,
+    }),
+  ).rejects.toThrow(/required/);
+  await expect(
+    setBalanceFunding(stripe, version, {
+      preparation,
+      enabled: undefined as unknown as boolean,
+      idempotencyKey: "request-1",
+    }),
+  ).rejects.toThrow(/required/);
+  expect(raw.subscriptions.retrieve).not.toHaveBeenCalled();
+});

package/src/client/billing/balanceFunding.ts

@@ -0,0 +1,183 @@
+import type Stripe from "stripe";
+import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
+import { idempotencyOptions } from "../core/idempotency.js";
+import { resolveOwnerAccount } from "../utils/owner.js";
+
+export type BalanceFundingCapability = {
+  configured: boolean;
+  requiredApiVersion: typeof STRIPE_CUSTOMER_PREVIEW_API_VERSION;
+  requiresConnectedAccount: true;
+  eligibility: "provider_validates_on_prepare";
+};
+export function getBalanceFundingCapability(
+  version: string,
+): BalanceFundingCapability {
+  return {
+    configured: version === STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+    requiredApiVersion: STRIPE_CUSTOMER_PREVIEW_API_VERSION,
+    requiresConnectedAccount: true,
+    eligibility: "provider_validates_on_prepare",
+  };
+}
+export type BalanceFundingScope = {
+  customerAccount: string;
+  stripeSubscriptionId: string;
+};
+/** Persist server-side before applying; never accept this record from a browser. */
+export type BalanceFundingPreparation = BalanceFundingScope & {
+  paymentMethodId: string;
+  previousPaymentMethodId: string | null;
+  previousPaymentMethodTypes: string[] | null;
+};
+export type PrepareBalanceFundingOptions = BalanceFundingScope & {
+  consent: true;
+  idempotencyKey: string;
+};
+export type SetBalanceFundingOptions = {
+  preparation: BalanceFundingPreparation;
+  enabled: boolean;
+  consent?: true;
+  idempotencyKey: string;
+};
+function request(version: string, key: string, phase: string) {
+  if (!getBalanceFundingCapability(version).configured)
+    throw new Error(
+      "Balance funding requires explicit Stripe preview API configuration.",
+    );
+  if (typeof key !== "string")
+    throw new Error(
+      "An explicit idempotency key is required for balance funding.",
+    );
+  idempotencyOptions(key);
+  return idempotencyOptions(`${key}:${phase}`)!;
+}
+async function subscription(stripe: Stripe, scope: BalanceFundingScope) {
+  if (!scope.customerAccount.startsWith("acct_") || !scope.stripeSubscriptionId)
+    throw new Error("A customer account and subscription are required.");
+  const sub = await stripe.subscriptions.retrieve(scope.stripeSubscriptionId);
+  if (resolveOwnerAccount(sub) !== scope.customerAccount)
+    throw new Error("Subscription does not belong to the customer account.");
+  if (!["active", "past_due", "trialing"].includes(sub.status))
+    throw new Error("This subscription cannot change payment sources.");
+  return sub;
+}
+function methodId(sub: Stripe.Subscription) {
+  const pm = sub.default_payment_method;
+  return typeof pm === "string" ? pm : (pm?.id ?? null);
+}
+
+/** Capture restoration settings, provision and attach; does not enable billing. */
+export async function prepareBalanceFunding(
+  stripe: Stripe,
+  version: string,
+  opts: PrepareBalanceFundingOptions,
+): Promise<BalanceFundingPreparation> {
+  const createOptions = request(version, opts.idempotencyKey, "create");
+  const attachOptions = request(version, opts.idempotencyKey, "attach");
+  if (opts.consent !== true)
+    throw new Error("Explicit consent is required for balance funding.");
+  const sub = await subscription(stripe, opts);
+  const previous = methodId(sub);
+  const types = sub.payment_settings?.payment_method_types ?? null;
+  if (
+    types?.includes("stripe_balance") ||
+    (previous &&
+      (await stripe.paymentMethods.retrieve(previous)).type ===
+        "stripe_balance")
+  )
+    throw new Error(
+      "Balance funding is already configured; reuse the persisted restoration record.",
+    );
+  const pm = await stripe.paymentMethods.create(
+    { type: "stripe_balance" },
+    createOptions,
+  );
+  if (pm.type !== "stripe_balance")
+    throw new Error("Stripe did not return a balance payment method.");
+  const current = await stripe.paymentMethods.retrieve(pm.id);
+  if (resolveOwnerAccount(current) === null) {
+    await stripe.paymentMethods.attach(
+      pm.id,
+      { customer_account: opts.customerAccount },
+      attachOptions,
+    );
+  } else if (resolveOwnerAccount(current) !== opts.customerAccount) {
+    throw new Error(
+      "Balance payment method belongs to a different customer account.",
+    );
+  }
+  return {
+    customerAccount: opts.customerAccount,
+    stripeSubscriptionId: opts.stripeSubscriptionId,
+    paymentMethodId: pm.id,
+    previousPaymentMethodId: previous,
+    previousPaymentMethodTypes: types,
+  };
+}
+function sameTypes(a: string[] | null, b: string[] | null) {
+  return a === null || b === null
+    ? a === b
+    : a.length === b.length &&
+        [...a].sort().every((type, i) => type === [...b].sort()[i]);
+}
+
+/** Apply a host-persisted preparation. Host serializes changes per subscription. */
+export async function setBalanceFunding(
+  stripe: Stripe,
+  version: string,
+  opts: SetBalanceFundingOptions,
+): Promise<{ enabled: boolean }> {
+  if (typeof opts.enabled !== "boolean")
+    throw new Error(
+      "An explicit enabled state is required for balance funding.",
+    );
+  const requestOptions = request(
+    version,
+    opts.idempotencyKey,
+    opts.enabled ? "enable" : "disable",
+  );
+  if (opts.enabled && opts.consent !== true)
+    throw new Error("Explicit consent is required for balance funding.");
+  const prep = opts.preparation;
+  const sub = await subscription(stripe, prep);
+  const pm = await stripe.paymentMethods.retrieve(prep.paymentMethodId);
+  if (
+    pm.type !== "stripe_balance" ||
+    resolveOwnerAccount(pm) !== prep.customerAccount
+  )
+    throw new Error(
+      "Balance payment method does not belong to the customer account.",
+    );
+  const original =
+    methodId(sub) === prep.previousPaymentMethodId &&
+    sameTypes(
+      sub.payment_settings?.payment_method_types ?? null,
+      prep.previousPaymentMethodTypes,
+    );
+  const balance =
+    methodId(sub) === prep.paymentMethodId &&
+    sameTypes(sub.payment_settings?.payment_method_types ?? null, [
+      "stripe_balance",
+    ]);
+  if (!original && !balance)
+    throw new Error(
+      "Subscription payment settings changed; reconcile before applying this restoration record.",
+    );
+  if ((opts.enabled && balance) || (!opts.enabled && original))
+    return { enabled: opts.enabled };
+  await stripe.subscriptions.update(
+    sub.id,
+    {
+      default_payment_method: opts.enabled
+        ? prep.paymentMethodId
+        : (prep.previousPaymentMethodId ?? ""),
+      payment_settings: {
+        payment_method_types: opts.enabled
+          ? ["stripe_balance"]
+          : (prep.previousPaymentMethodTypes ?? ""),
+      },
+    },
+    requestOptions,
+  );
+  return { enabled: opts.enabled };
+}

package/src/client/billing/balanceFundingTransport.test.ts

@@ -0,0 +1,89 @@
+import type Stripe from "stripe";
+import { componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { BetterStripe } from "../index.js";
+import { getStripeClient, type Component, type RunCtx } from "../helpers.js";
+
+it("keeps balance operations on the explicitly selected preview and serializes phase keys", async () => {
+  const key = `sk_test_balance_transport_${crypto.randomUUID()}`;
+  const version = "2026-09-30.preview";
+  const bs = new BetterStripe(
+    componentsGeneric().betterStripe as unknown as Component,
+    {
+      STRIPE_SECRET_KEY: key,
+      stripeApiVersion: version,
+    },
+  );
+  const calls: {
+    path: string;
+    version: string;
+    body: string;
+    idempotency?: string;
+  }[] = [];
+  let attached = false;
+  const sdk = getStripeClient(key, version);
+  (
+    sdk as unknown as { _setApiField: (name: string, value: unknown) => void }
+  )._setApiField("httpClient", {
+    getClientName: () => "balance-contract-test",
+    makeRequest: async (
+      ...[, , path, , headers, body]: Parameters<
+        ReturnType<typeof Stripe.createNodeHttpClient>["makeRequest"]
+      >
+    ) => {
+      calls.push({
+        path,
+        version: String(headers["Stripe-Version"]),
+        body: String(body),
+        idempotency: headers["Idempotency-Key"] as string | undefined,
+      });
+      let data: object;
+      if (path.includes("/subscriptions/"))
+        data = {
+          id: "sub_test",
+          status: "active",
+          customer_account: "acct_store",
+          default_payment_method: null,
+          payment_settings: { payment_method_types: null },
+        };
+      else {
+        if (path.endsWith("/attach")) attached = true;
+        data = {
+          id: "pm_balance",
+          type: "stripe_balance",
+          customer_account: attached ? "acct_store" : null,
+        };
+      }
+      return {
+        getStatusCode: () => 200,
+        getHeaders: () => ({}),
+        getRawResponse: () => ({}),
+        toJSON: async () => data,
+        toStream: () => {
+          throw new Error("Unexpected stream");
+        },
+      };
+    },
+  });
+  const ctx = { runQuery: vi.fn(), runMutation: vi.fn() } as unknown as RunCtx;
+  const prep = await bs.prepareBalanceFunding(ctx, {
+    customerAccount: "acct_store",
+    stripeSubscriptionId: "sub_test",
+    consent: true,
+    idempotencyKey: "prepare-1",
+  });
+  await bs.setBalanceFunding(ctx, {
+    preparation: prep,
+    enabled: true,
+    consent: true,
+    idempotencyKey: "enable-1",
+  });
+  expect(bs.getBalanceFundingCapability().configured).toBe(true);
+  expect(calls.every((call) => call.version === version)).toBe(true);
+  expect(
+    calls.filter((call) => call.idempotency).map((call) => call.idempotency),
+  ).toEqual(["prepare-1:create", "prepare-1:attach", "enable-1:enable"]);
+  expect(calls[calls.length - 1]?.body).toContain(
+    "payment_settings[payment_method_types][0]=stripe_balance",
+  );
+});

package/src/client/billing/invoicePreview.test.ts

@@ -0,0 +1,123 @@
+import type Stripe from "stripe";
+import { describe, expect, it, vi } from "vitest";
+import { getUpcomingInvoicePreview } from "./invoicePreview.js";
+
+const opts = {
+  customerAccount: "acct_buyer",
+  stripeSubscriptionId: "sub_test",
+};
+const line = (id: string, amount = 100) => ({
+  id,
+  amount,
+  currency: "usd",
+  description: "Subscription",
+  period: { start: 1800000000, end: 1802592000 },
+});
+function fixture(hasMore = false) {
+  const raw = {
+    subscriptions: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: opts.stripeSubscriptionId,
+        customer_account: opts.customerAccount,
+        items: { data: [{ current_period_end: 1800000000 }] },
+      }),
+    },
+    invoices: {
+      createPreview: vi.fn().mockResolvedValue({
+        id: "in_preview",
+        currency: "usd",
+        total: 275,
+        subtotal: 300,
+        amount_due: 275,
+        period_start: 1800000000,
+        period_end: 1802592000,
+        lines: { data: [line("il_first")], has_more: hasMore },
+      }),
+      listLineItems: vi.fn().mockImplementation(async function* () {
+        yield line("il_first");
+        yield line("il_second", 200);
+      }),
+    },
+  };
+  return { raw, stripe: raw as unknown as Stripe };
+}
+describe("authoritative upcoming invoice preview", () => {
+  it("keeps provider totals and converts dates to milliseconds", async () => {
+    const { raw, stripe } = fixture();
+    const preview = await getUpcomingInvoicePreview(stripe, opts);
+    expect(preview).toMatchObject({
+      total: 275,
+      subtotal: 300,
+      amountDue: 275,
+      currency: "usd",
+      nextBillingAt: 1800000000000,
+      linesComplete: true,
+      periodStart: 1800000000000,
+      periodEnd: 1802592000000,
+      lines: [{ id: "il_first", amount: 100, periodStart: 1800000000000 }],
+    });
+    expect(raw.invoices.createPreview).toHaveBeenCalledWith({
+      customer_account: "acct_buyer",
+      subscription: "sub_test",
+    });
+    expect(raw.invoices.listLineItems).not.toHaveBeenCalled();
+  });
+  it("loads every provider line when the initial embedded page is truncated", async () => {
+    const { raw, stripe } = fixture(true);
+    expect(
+      (await getUpcomingInvoicePreview(stripe, opts)).lines.map((l) => l.id),
+    ).toEqual(["il_first", "il_second"]);
+    expect(raw.invoices.listLineItems).toHaveBeenCalledWith("in_preview", {
+      limit: 100,
+    });
+  });
+  it("rejects a subscription owned by a different account before creating a preview", async () => {
+    const { raw, stripe } = fixture();
+    raw.subscriptions.retrieve.mockResolvedValueOnce({
+      customer_account: "acct_other",
+    });
+    await expect(getUpcomingInvoicePreview(stripe, opts)).rejects.toThrow(
+      "does not belong",
+    );
+    expect(raw.invoices.createPreview).not.toHaveBeenCalled();
+  });
+  it("preserves unavailable preview errors and does not return partial pagination", async () => {
+    const { raw, stripe } = fixture(true);
+    const unavailable = Object.assign(new Error("No upcoming invoice"), {
+      code: "invoice_upcoming_none",
+    });
+    raw.invoices.createPreview.mockRejectedValueOnce(unavailable);
+    await expect(getUpcomingInvoicePreview(stripe, opts)).rejects.toBe(
+      unavailable,
+    );
+    const failedPage = new Error("Provider page unavailable");
+    raw.invoices.listLineItems.mockImplementationOnce(async function* () {
+      yield line("il_first");
+      throw failedPage;
+    });
+    await expect(getUpcomingInvoicePreview(stripe, opts)).rejects.toBe(
+      failedPage,
+    );
+  });
+  it("rejects inconsistent currency or fractional provider amounts", async () => {
+    const { raw, stripe } = fixture();
+    const preview = await raw.invoices.createPreview();
+    raw.invoices.createPreview.mockResolvedValueOnce({
+      ...preview,
+      total: 1.5,
+    });
+    await expect(getUpcomingInvoicePreview(stripe, opts)).rejects.toThrow(
+      "integer",
+    );
+    raw.invoices.createPreview.mockResolvedValueOnce({
+      ...preview,
+      lines: {
+        data: [{ ...line("il_bad"), currency: "eur" }],
+        has_more: false,
+      },
+    });
+    await expect(getUpcomingInvoicePreview(stripe, opts)).rejects.toThrow(
+      "currency",
+    );
+  });
+});