@fantastic.dev/better-stripe 0.11.0 → 0.13.0

package/src/client/billing/invoicePreview.ts

@@ -0,0 +1,94 @@
+import type Stripe from "stripe";
+import { resolveOwnerAccount } from "../utils/owner.js";
+
+export type UpcomingInvoicePreviewOptions = {
+  /** Host must authorize this customer account before calling. */
+  customerAccount: string;
+  stripeSubscriptionId: string;
+};
+
+/** Provider amounts are integer minor units; all dates are milliseconds. */
+export type UpcomingInvoicePreview = {
+  stripeInvoiceId: string;
+  currency: string;
+  total: number;
+  subtotal: number;
+  amountDue: number;
+  nextBillingAt: number;
+  periodStart: number;
+  periodEnd: number;
+  linesComplete: true;
+  lines: {
+    id: string;
+    description: string;
+    amount: number;
+    currency: string;
+    periodStart: number;
+    periodEnd: number;
+  }[];
+};
+
+function integer(value: number): number {
+  if (!Number.isSafeInteger(value))
+    throw new Error("Invoice preview amounts and dates must be safe integers.");
+  return value;
+}
+
+export async function getUpcomingInvoicePreview(
+  stripe: Stripe,
+  opts: UpcomingInvoicePreviewOptions,
+): Promise<UpcomingInvoicePreview> {
+  if (!opts.customerAccount.startsWith("acct_") || !opts.stripeSubscriptionId)
+    throw new Error("A customer account and subscription are required.");
+  const subscription = await stripe.subscriptions.retrieve(
+    opts.stripeSubscriptionId,
+  );
+  if (resolveOwnerAccount(subscription) !== opts.customerAccount)
+    throw new Error("Subscription does not belong to the customer account.");
+  const preview = await stripe.invoices.createPreview({
+    customer_account: opts.customerAccount,
+    subscription: opts.stripeSubscriptionId,
+  });
+  const lines: UpcomingInvoicePreview["lines"] = [];
+  const append = (line: Stripe.InvoiceLineItem) => {
+    if (line.currency !== preview.currency)
+      throw new Error(
+        "Invoice preview line currency does not match the invoice.",
+      );
+    lines.push({
+      id: line.id,
+      description: line.description ?? "Subscription",
+      amount: integer(line.amount),
+      currency: line.currency,
+      periodStart: integer(line.period.start * 1000),
+      periodEnd: integer(line.period.end * 1000),
+    });
+  };
+  if (preview.lines.has_more) {
+    for await (const line of stripe.invoices.listLineItems(preview.id, {
+      limit: 100,
+    }))
+      append(line);
+  } else {
+    preview.lines.data.forEach(append);
+  }
+  const renewalDates = subscription.items.data.map(
+    (item) => item.current_period_end,
+  );
+  const nextBillingAt =
+    preview.next_payment_attempt ??
+    (subscription.status === "trialing" ? subscription.trial_end : null) ??
+    Math.min(...renewalDates);
+  return {
+    stripeInvoiceId: preview.id,
+    currency: preview.currency,
+    total: integer(preview.total),
+    subtotal: integer(preview.subtotal),
+    amountDue: integer(preview.amount_due),
+    nextBillingAt: integer(nextBillingAt * 1000),
+    periodStart: integer(preview.period_start * 1000),
+    periodEnd: integer(preview.period_end * 1000),
+    linesComplete: true,
+    lines,
+  };
+}

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

@@ -0,0 +1,70 @@
+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.each([undefined, "2026-09-30.preview"] as const)(
+  "uses the configured API version for subscription and preview reads: %s",
+  async (version) => {
+    const key = `sk_test_invoice_transport_${crypto.randomUUID()}`;
+    const bs = new BetterStripe(
+      componentsGeneric().betterStripe as unknown as Component,
+      {
+        STRIPE_SECRET_KEY: key,
+        stripeApiVersion: version,
+      },
+    );
+    const versions: string[] = [];
+    const sdk = getStripeClient(key, version);
+    (
+      sdk as unknown as { _setApiField: (name: string, value: unknown) => void }
+    )._setApiField("httpClient", {
+      getClientName: () => "invoice-contract-test",
+      makeRequest: async (
+        ...[, , path, , headers]: Parameters<
+          ReturnType<typeof Stripe.createNodeHttpClient>["makeRequest"]
+        >
+      ) => {
+        versions.push(String(headers["Stripe-Version"]));
+        const data = path.includes("/subscriptions/")
+          ? {
+              id: "sub_test",
+              customer_account: "acct_buyer",
+              items: { data: [{ current_period_end: 1800000000 }] },
+            }
+          : {
+              id: "in_preview",
+              currency: "usd",
+              total: 100,
+              subtotal: 100,
+              amount_due: 100,
+              period_start: 1800000000,
+              period_end: 1802592000,
+              lines: { data: [], has_more: false },
+            };
+        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;
+    expect(
+      await bs.getUpcomingInvoicePreview(ctx, {
+        customerAccount: "acct_buyer",
+        stripeSubscriptionId: "sub_test",
+      }),
+    ).toMatchObject({ total: 100, linesComplete: true });
+    expect(versions).toEqual(Array(2).fill(version ?? "2026-09-30.endive"));
+    expect(ctx.runQuery).not.toHaveBeenCalled();
+  },
+);

package/src/client/charge-currency-format.ts

@@ -0,0 +1,29 @@
+/** Internal exact renderer. Callers establish units and amount eligibility. */
+export function renderCurrencyUnits(
+  amount: number,
+  currency: string,
+  apiDecimals: 0 | 2,
+  displayDecimals: 0 | 2,
+  locale: string,
+): string {
+  const scale = 10n ** BigInt(apiDecimals);
+  const units = BigInt(Math.abs(amount));
+  const whole = units / scale;
+  const signedWhole = amount < 0 ? (whole === 0n ? -0 : -whole) : whole;
+  const formatter = new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: currency.toUpperCase(),
+    minimumFractionDigits: displayDecimals,
+    maximumFractionDigits: displayDecimals,
+  });
+  const digits = new Intl.NumberFormat(locale, { useGrouping: false });
+  const fraction = (units % scale).toString().padStart(apiDecimals, "0");
+  return formatter
+    .formatToParts(signedWhole)
+    .map((part) =>
+      part.type === "fraction"
+        ? [...fraction].map((digit) => digits.format(Number(digit))).join("")
+        : part.value,
+    )
+    .join("");
+}

package/src/client/charge-currency.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  chargeAmountToDecimal,
+  formatChargeAmount,
+  getChargeCurrencyMetadata,
+  parseChargeAmount,
+} from "./charge-currency.js";
+
+describe("charge currency units", () => {
+  it("produces exact editable decimals in charge units", () => {
+    expect(chargeAmountToDecimal(Number.MAX_SAFE_INTEGER, "usd")).toBe(
+      "90071992547409.91",
+    );
+    expect(chargeAmountToDecimal(500, "jpy")).toBe("500");
+    expect(chargeAmountToDecimal(50000, "isk")).toBe("500");
+    expect(chargeAmountToDecimal(1045, "huf")).toBe("10.45");
+    expect(chargeAmountToDecimal(0, "usd")).toBe("0.00");
+  });
+  it.each([
+    [101, "isk"],
+    [-1, "usd"],
+    [1.5, "usd"],
+    [100, "ZZZ"],
+    [100, "bhd"],
+    [Number.MAX_SAFE_INTEGER + 1, "usd"],
+  ])("refuses invalid initial charge units %s %s", (amount, currency) => {
+    expect(chargeAmountToDecimal(amount, currency)).toBeNull();
+  });
+  it.each([
+    ["USD", "10.05", 1005, 2, 2],
+    ["jpy", "500", 500, 0, 0],
+    ["mga", "500", 500, 0, 0],
+    ["isk", "500", 50000, 2, 0],
+    ["ugx", "500", 50000, 2, 0],
+    ["huf", "10.45", 1045, 2, 2],
+    ["twd", "800.45", 80045, 2, 2],
+    ["afn", "1.25", 125, 2, 2],
+  ])(
+    "parses %s using charge rules",
+    (currency, decimal, units, apiDecimals, displayDecimals) => {
+      expect(getChargeCurrencyMetadata(currency)).toEqual({
+        currency: currency.toLowerCase(),
+        apiDecimals,
+        displayDecimals,
+      });
+      expect(parseChargeAmount(decimal, currency)).toBe(units);
+      const parts = new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: currency.toUpperCase(),
+        minimumFractionDigits: displayDecimals,
+        maximumFractionDigits: displayDecimals,
+      }).format(Number(decimal));
+      expect(formatChargeAmount(units, currency)).toBe(parts);
+    },
+  );
+
+  it.each(["ZZZ", "", "usd ", "BHD", "CLF"])(
+    "rejects unknown or unsupported precision %s",
+    (currency) => {
+      expect(getChargeCurrencyMetadata(currency)).toBeNull();
+      expect(parseChargeAmount("1", currency)).toBeNull();
+      expect(() => formatChargeAmount(100, currency)).toThrow(RangeError);
+    },
+  );
+
+  it.each([
+    ["", "usd"],
+    ["1e2", "usd"],
+    ["1,000", "usd"],
+    ["-1", "usd"],
+    ["1.005", "usd"],
+    ["0.5", "jpy"],
+    ["0.5", "mga"],
+    ["1.01", "isk"],
+    ["1.01", "ugx"],
+    ["90071992547409.92", "usd"],
+  ])("rejects invalid decimal %s %s without rounding", (decimal, currency) => {
+    expect(parseChargeAmount(decimal, currency)).toBeNull();
+  });
+
+  it.each([NaN, Infinity, 1.5, Number.MAX_SAFE_INTEGER + 1])(
+    "rejects invalid provider units %s",
+    (amount) => {
+      expect(() => formatChargeAmount(amount, "usd")).toThrow(RangeError);
+    },
+  );
+
+  it("rejects fractional compatibility units", () => {
+    expect(() => formatChargeAmount(101, "isk")).toThrow(RangeError);
+    expect(() => formatChargeAmount(101, "ugx")).toThrow(RangeError);
+  });
+
+  it("keeps the final minor unit at the safe integer boundary", () => {
+    expect(formatChargeAmount(-1, "usd")).toBe("-$0.01");
+    expect(formatChargeAmount(-Number.MAX_SAFE_INTEGER, "usd")).toBe(
+      "-$90,071,992,547,409.91",
+    );
+    expect(parseChargeAmount("90071992547409.91", "usd")).toBe(
+      Number.MAX_SAFE_INTEGER,
+    );
+    expect(formatChargeAmount(Number.MAX_SAFE_INTEGER, "usd")).toBe(
+      "$90,071,992,547,409.91",
+    );
+    expect(formatChargeAmount(0, "usd")).toBe("$0.00");
+    expect(parseChargeAmount("0", "usd")).toBe(0);
+  });
+
+  it("localizes grouping and digits without losing provider precision", () => {
+    expect(formatChargeAmount(123456, "eur", "de-DE")).toBe("1.234,56 €");
+    expect(formatChargeAmount(125, "usd", "ar-EG")).toContain("١٫٢٥");
+  });
+});

package/src/client/charge-currency.ts

@@ -0,0 +1,119 @@
+/** Stripe charge/Price units. These are not payout or Global Payouts rules. */
+import { renderCurrencyUnits } from "./charge-currency-format.js";
+const zeroDecimal = new Set([
+  "bif",
+  "clp",
+  "djf",
+  "gnf",
+  "jpy",
+  "kmf",
+  "krw",
+  "mga",
+  "pyg",
+  "rwf",
+  "vnd",
+  "vuv",
+  "xaf",
+  "xof",
+  "xpf",
+]);
+const unsupportedPrecision = new Set([
+  "bhd",
+  "clf",
+  "iqd",
+  "jod",
+  "kwd",
+  "lyd",
+  "omr",
+  "tnd",
+  "uyw",
+]);
+const currencyIntl: typeof Intl & {
+  supportedValuesOf?: (key: "currency") => string[];
+} = Intl;
+const knownCurrencies = new Set(
+  (currencyIntl.supportedValuesOf?.("currency") ?? []).map((code) =>
+    code.toLowerCase(),
+  ),
+);
+
+export type ChargeCurrencyMetadata = {
+  currency: string;
+  apiDecimals: 0 | 2;
+  displayDecimals: 0 | 2;
+};
+
+/** Metadata does not establish account/country/payment-method support. */
+export function getChargeCurrencyMetadata(
+  currency: string,
+): ChargeCurrencyMetadata | null {
+  const code = currency.toLowerCase();
+  if (!knownCurrencies.has(code) || unsupportedPrecision.has(code)) return null;
+  if (zeroDecimal.has(code))
+    return { currency: code, apiDecimals: 0, displayDecimals: 0 };
+  return {
+    currency: code,
+    apiDecimals: 2,
+    displayDecimals: code === "isk" || code === "ugx" ? 0 : 2,
+  };
+}
+
+/** Parse a nonnegative ASCII decimal exactly. Invalid input is never rounded. */
+export function parseChargeAmount(
+  value: string,
+  currency: string,
+): number | null {
+  const metadata = getChargeCurrencyMetadata(currency);
+  if (!metadata || !/^\d+(?:\.\d+)?$/.test(value)) return null;
+  const [whole, fraction = ""] = value.split(".");
+  if (fraction.length > metadata.displayDecimals) return null;
+  const units =
+    BigInt(whole) * 10n ** BigInt(metadata.apiDecimals) +
+    BigInt(fraction.padEnd(metadata.apiDecimals, "0") || "0");
+  return units <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(units) : null;
+}
+
+/** Exact ASCII decimal for charge inputs; invalid source units stay unavailable. */
+export function chargeAmountToDecimal(
+  amount: number,
+  currency: string,
+): string | null {
+  const metadata = getChargeCurrencyMetadata(currency);
+  if (
+    !metadata ||
+    !Number.isSafeInteger(amount) ||
+    amount < 0 ||
+    (metadata.displayDecimals === 0 &&
+      amount % 10 ** metadata.apiDecimals !== 0)
+  )
+    return null;
+  const units = BigInt(amount);
+  const scale = 10n ** BigInt(metadata.apiDecimals);
+  const whole = (units / scale).toString();
+  if (metadata.displayDecimals === 0) return whole;
+  return `${whole}.${(units % scale).toString().padStart(metadata.apiDecimals, "0")}`;
+}
+
+/** Format signed integer charge units without floating-point division. */
+export function formatChargeAmount(
+  amount: number,
+  currency: string,
+  locale = "en-US",
+): string {
+  const metadata = getChargeCurrencyMetadata(currency);
+  if (
+    !metadata ||
+    !Number.isSafeInteger(amount) ||
+    (metadata.displayDecimals === 0 &&
+      amount % 10 ** metadata.apiDecimals !== 0)
+  ) {
+    throw new RangeError("Invalid charge amount or unsupported currency");
+  }
+  return renderCurrencyUnits(
+    amount,
+    metadata.currency,
+    metadata.apiDecimals,
+    metadata.displayDecimals,
+    locale,
+  );
+}