@fantastic.dev/better-stripe 0.11.0 → 0.13.0

package/src/react/lib/price-helpers.ts

@@ -1,6 +1,11 @@
 /**
  * Price formatting and filtering utilities.
  */
+import {
+  formatChargeAmount,
+  getChargeCurrencyMetadata,
+} from "../../client/charge-currency.js";
+import { renderCurrencyUnits } from "../../client/charge-currency-format.js";
 
 type PriceLike = {
   unitAmount?: number | null;
@@ -12,19 +17,29 @@ type PriceLike = {
 };
 
 /**
- * Format a price amount in cents to a display string.
+ * Legacy display helper for observed ordinary account/charge units.
+ * Preserves fractional ISK/UGX balances; does not validate charge eligibility.
  * e.g. 2000, 'usd' → '$20.00'
  */
 export function formatPrice(
-  amountInCents: number,
+  amount: number,
   currency: string,
   locale = "en-US",
 ): string {
-  return new Intl.NumberFormat(locale, {
-    style: "currency",
-    currency: currency.toUpperCase(),
-    minimumFractionDigits: 2,
-  }).format(amountInCents / 100);
+  const metadata = getChargeCurrencyMetadata(currency);
+  if (!metadata || !Number.isSafeInteger(amount))
+    throw new RangeError("Invalid amount or unsupported currency");
+  const displayDecimals =
+    amount % 10 ** metadata.apiDecimals === 0
+      ? metadata.displayDecimals
+      : metadata.apiDecimals;
+  return renderCurrencyUnits(
+    amount,
+    metadata.currency,
+    metadata.apiDecimals,
+    displayDecimals,
+    locale,
+  );
 }
 
 /**
@@ -34,8 +49,10 @@ export function formatPrice(
 export function formatPriceWithInterval(
   price: PriceLike,
   locale = "en-US",
+  customPriceLabel = "Custom price",
 ): string {
-  const amount = formatPrice(price.unitAmount ?? 0, price.currency, locale);
+  if (price.unitAmount == null) return customPriceLabel;
+  const amount = formatChargeAmount(price.unitAmount, price.currency, locale);
   if (price.type === "one_time" || !price.interval) {
     return amount;
   }

package/src/react/workflows/Billing.test.tsx

@@ -34,7 +34,7 @@ it("loads an itemized estimate only when requested and displays the server total
     nextBillingAt: 1800000000000,
     lines: [
       { id: "plan", description: "Store plan", amount: 2900 },
-      { id: "cost", description: "Refund costs", amount: 800 },
+      { id: "cost", description: "Refund costs", amount: 700 },
     ],
   });
   render(<InvoiceEstimate scopeKey="seller" load={load} />);

package/src/react/workflows/Collections.test.tsx

@@ -84,3 +84,39 @@ it("preserves store attribution in referred sales and refund statuses in history
   expect(screen.getByText("failed")).toBeTruthy();
   expect(screen.getByRole("columnheader", { name: "Created" })).toBeTruthy();
 });
+
+it("renders observed refund units and unavailable data without throwing", () => {
+  render(
+    <RefundHistory
+      rows={[
+        {
+          stripeRefundId: "re_jpy",
+          amount: 500,
+          currency: "jpy",
+          status: "succeeded",
+        },
+        {
+          stripeRefundId: "re_ugx",
+          amount: 101,
+          currency: "ugx",
+          status: "pending",
+        },
+        {
+          stripeRefundId: "re_unknown",
+          amount: 100,
+          currency: "zzz",
+          status: "failed",
+        },
+        {
+          stripeRefundId: "re_invalid",
+          amount: -1,
+          currency: "usd",
+          status: "canceled",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("¥500")).toBeTruthy();
+  expect(screen.getByText("UGX 1.01")).toBeTruthy();
+  expect(screen.getAllByText("Amount unavailable")).toHaveLength(2);
+});

package/src/react/workflows/Collections.tsx

@@ -2,6 +2,7 @@
 import type { CollectionProps, WorkflowColumn } from "./Collection.js";
 import { Collection } from "./Collection.js";
 import { formatPrice } from "../lib/price-helpers.js";
+import { formatRefundAmount } from "./refund-preview.js";
 export type ResourceCollectionProps<Row> = Omit<
   CollectionProps<Row>,
   "columns" | "getKey"
@@ -111,7 +112,8 @@ export function RefundHistory(props: ResourceCollectionProps<RefundRow>) {
       id: "amount",
       label: "Amount",
       align: "end",
-      cell: (row) => formatPrice(row.amount, row.currency),
+      cell: (row) =>
+        formatRefundAmount(row.amount, row.currency) ?? "Amount unavailable",
     },
     { id: "status", label: "Status", cell: (row) => row.status },
     {

package/src/react/workflows/PlanPricingEditor.currency.test.tsx

@@ -0,0 +1,164 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+import type { ComponentProps } from "react";
+import { act, cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { PlanPricingEditor } from "./PlanPricingEditor.js";
+afterEach(cleanup);
+const plan = {
+  id: "plan",
+  name: "Plan",
+  monthlyAmount: 500,
+  feeBasisPoints: 500,
+  affiliateBasisPoints: 4000,
+  version: 1,
+};
+
+it.each([
+  ["usd", 500, "5.00", "12.34", 1234, "decimal"],
+  ["jpy", 500, "500", "600", 600, "numeric"],
+  ["mga", 500, "500", "600", 600, "numeric"],
+  ["isk", 50000, "500", "600", 60000, "numeric"],
+  ["ugx", 50000, "500", "600", 60000, "numeric"],
+  ["huf", 1045, "10.45", "12.34", 1234, "decimal"],
+  ["twd", 1045, "10.45", "12.34", 1234, "decimal"],
+  [
+    "usd",
+    Number.MAX_SAFE_INTEGER,
+    "90071992547409.91",
+    "90071992547409.91",
+    Number.MAX_SAFE_INTEGER,
+    "decimal",
+  ],
+])(
+  "initializes and saves exact %s provider price units",
+  async (currency, monthlyAmount, initial, input, expected, inputMode) => {
+    const onSave = vi.fn().mockResolvedValue(undefined);
+    render(
+      <PlanPricingEditor
+        plan={{ ...plan, currency, monthlyAmount }}
+        onSave={onSave}
+      />,
+    );
+    const field = screen.getByLabelText(
+      `Monthly price (${currency.toUpperCase()})`,
+    );
+    expect(field).toHaveValue(initial);
+    expect(field).toHaveAttribute("inputmode", inputMode);
+    await userEvent.clear(field);
+    await userEvent.type(field, input);
+    await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+    expect(onSave).toHaveBeenCalledWith({
+      monthlyAmount: expected,
+      feeBasisPoints: 500,
+      affiliateBasisPoints: 4000,
+      expectedVersion: 1,
+    });
+  },
+);
+
+it.each([
+  ["jpy", "0.5"],
+  ["mga", "1.5"],
+  ["isk", "1.01"],
+  ["ugx", "1.01"],
+  ["usd", "1.005"],
+  ["usd", "90071992547409.92"],
+  ["usd", "0"],
+  ["usd", "1e2"],
+  ["ZZZ", "1"],
+  ["bhd", "1"],
+])(
+  "rejects invalid %s price %s before the callback",
+  async (currency, value) => {
+    const onSave = vi.fn();
+    render(<PlanPricingEditor plan={{ ...plan, currency }} onSave={onSave} />);
+    const field = screen.getByLabelText(
+      `Monthly price (${currency.toUpperCase()})`,
+    );
+    await userEvent.clear(field);
+    await userEvent.type(field, value);
+    await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+    expect(screen.getByRole("alert")).toBeTruthy();
+    expect(onSave).not.toHaveBeenCalled();
+  },
+);
+
+it("resets currency-scoped headless fields and ignores a late previous save", async () => {
+  let resolveOld: (() => void) | undefined;
+  const onSave = vi
+    .fn()
+    .mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveOld = resolve;
+        }),
+    )
+    .mockResolvedValue(undefined);
+  const children = (
+    state: Parameters<
+      NonNullable<ComponentProps<typeof PlanPricingEditor>["children"]>
+    >[0],
+  ) => (
+    <>
+      <output>
+        {state.monthlyPrice}|{state.isPending ? "pending" : "idle"}|
+        {state.message ?? ""}
+      </output>
+      <button onClick={() => void state.save()}>Save</button>
+      <button onClick={() => state.setMonthlyPrice("777")}>Edit</button>
+    </>
+  );
+  const { rerender } = render(
+    <PlanPricingEditor plan={{ ...plan, currency: "usd" }} onSave={onSave}>
+      {children}
+    </PlanPricingEditor>,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Save" }));
+  expect(screen.getByRole("status")).toHaveTextContent("pending");
+  rerender(
+    <PlanPricingEditor plan={{ ...plan, currency: "jpy" }} onSave={onSave}>
+      {children}
+    </PlanPricingEditor>,
+  );
+  expect(screen.getByRole("status")).toHaveTextContent("500|idle|");
+  await act(async () => resolveOld?.());
+  expect(screen.getByRole("status")).toHaveTextContent("500|idle|");
+  await userEvent.click(screen.getByRole("button", { name: "Save" }));
+  expect(onSave).toHaveBeenLastCalledWith({
+    monthlyAmount: 500,
+    feeBasisPoints: 500,
+    affiliateBasisPoints: 4000,
+    expectedVersion: 1,
+  });
+  await userEvent.click(screen.getByRole("button", { name: "Edit" }));
+  rerender(
+    <PlanPricingEditor
+      plan={{ ...plan, currency: "jpy", version: 2, monthlyAmount: 600 }}
+      onSave={onSave}
+    >
+      {children}
+    </PlanPricingEditor>,
+  );
+  expect(screen.getByRole("status")).toHaveTextContent("600|idle|");
+});
+
+it("keeps currency-aware retries on the same plan version", async () => {
+  const onSave = vi
+    .fn()
+    .mockRejectedValueOnce(new Error("Retry"))
+    .mockResolvedValue(undefined);
+  render(
+    <PlanPricingEditor plan={{ ...plan, currency: "jpy" }} onSave={onSave} />,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(screen.getByRole("alert")).toHaveTextContent("Retry");
+  await userEvent.click(screen.getByRole("button", { name: "Save pricing" }));
+  expect(onSave).toHaveBeenNthCalledWith(2, {
+    monthlyAmount: 500,
+    feeBasisPoints: 500,
+    affiliateBasisPoints: 4000,
+    expectedVersion: 1,
+  });
+});

package/src/react/workflows/PlanPricingEditor.tsx

@@ -1,10 +1,17 @@
 "use client";
 import { useId, useState, type ReactNode } from "react";
+import {
+  chargeAmountToDecimal,
+  getChargeCurrencyMetadata,
+  parseChargeAmount,
+} from "../../client/charge-currency.js";
 import { useWorkflowAction } from "./useWorkflowAction.js";
 export type PlanPricing = {
   id: string;
   name: string;
   monthlyAmount: number;
+  /** Defaults to USD for existing consumers. Charge/Price currency, not payout units. */
+  currency?: string;
   feeBasisPoints: number | null;
   affiliateBasisPoints?: number | null;
   version: number;
@@ -16,6 +23,8 @@ export type PlanPricingUpdate = {
   expectedVersion: number;
 };
 export type PlanPricingEditorState = {
+  currency: string;
+  inputDecimalPlaces: 0 | 2 | null;
   monthlyPrice: string;
   saleFee: string;
   affiliateShare: string;
@@ -39,24 +48,27 @@ export function PlanPricingEditor({
   children,
 }: PlanPricingEditorProps) {
   const id = useId();
-  const scope = `${plan.id}:${plan.version}`;
+  const currency = (plan.currency ?? "usd").toLowerCase();
+  const metadata = getChargeCurrencyMetadata(currency);
+  const scope = `${plan.id}:${plan.version}:${currency}`;
   const initial = {
     scope,
     affiliateShare: String((plan.affiliateBasisPoints ?? 0) / 100),
-    monthlyPrice: (plan.monthlyAmount / 100).toFixed(2),
+    monthlyPrice: chargeAmountToDecimal(plan.monthlyAmount, currency) ?? "",
     saleFee:
       plan.feeBasisPoints === null ? "" : String(plan.feeBasisPoints / 100),
   };
   const [fields, setFields] = useState(initial);
   if (fields.scope !== scope) setFields(initial);
   const action = useWorkflowAction(async () => {
-    if (!/^\d+(\.\d{1,2})?$/.test(fields.monthlyPrice.trim()))
+    const monthlyAmount = parseChargeAmount(
+      fields.monthlyPrice.trim(),
+      currency,
+    );
+    if (monthlyAmount === null || monthlyAmount <= 0)
       throw new Error(
-        "Enter a positive monthly price with at most two decimal places.",
+        "Enter a positive monthly price in supported currency units.",
       );
-    const monthlyAmount = Math.round(Number(fields.monthlyPrice) * 100);
-    if (!Number.isSafeInteger(monthlyAmount) || monthlyAmount <= 0)
-      throw new Error("Enter a positive monthly price.");
     const feeBasisPoints =
       fields.saleFee.trim() === ""
         ? null
@@ -90,8 +102,10 @@ export function PlanPricingEditor({
       expectedVersion: plan.version,
     });
     return "Pricing saved. Existing subscriptions keep their monthly price.";
-  }, plan.id);
+  }, scope);
   const state: PlanPricingEditorState = {
+    currency,
+    inputDecimalPlaces: metadata?.displayDecimals ?? null,
     ...fields,
     setMonthlyPrice: (monthlyPrice) =>
       setFields((previous) => ({ ...previous, monthlyPrice })),
@@ -114,10 +128,12 @@ export function PlanPricingEditor({
       aria-label={`${plan.name} pricing`}
     >
       <h3>{plan.name}</h3>
-      <label htmlFor={`${id}-monthly`}>Monthly price (USD)</label>
+      <label htmlFor={`${id}-monthly`}>
+        Monthly price ({currency.toUpperCase()})
+      </label>
       <input
         id={`${id}-monthly`}
-        inputMode="decimal"
+        inputMode={state.inputDecimalPlaces === 0 ? "numeric" : "decimal"}
         value={state.monthlyPrice}
         disabled={state.isPending}
         onChange={(event) => state.setMonthlyPrice(event.target.value)}

package/src/react/workflows/Refunds.currency.test.tsx

@@ -0,0 +1,290 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+import {
+  act,
+  cleanup,
+  render,
+  renderHook,
+  screen,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { Refunds, useRefunds } from "./Refunds.js";
+afterEach(cleanup);
+it.each([
+  ["usd", "12.34", 1234],
+  ["jpy", "500", 500],
+  ["mga", "500", 500],
+  ["isk", "500", 50000],
+  ["ugx", "500", 50000],
+  ["huf", "10.45", 1045],
+  ["twd", "800.45", 80045],
+  ["usd", "90071992547409.91", Number.MAX_SAFE_INTEGER],
+])(
+  "preserves original %s partial refund units",
+  async (currency, input, expected) => {
+    const issueRefund = vi
+      .fn()
+      .mockResolvedValue({ stripeRefundId: "re_test" });
+    const { result } = renderHook(() =>
+      useRefunds({
+        scopeKey: "seller",
+        paymentIntentId: "pi_test",
+        paymentCurrency: currency,
+        issueRefund,
+      }),
+    );
+    act(() => result.current.setRefundAmount(input));
+    await act(async () => {
+      await result.current.submitRefund("partial");
+    });
+    expect(issueRefund).toHaveBeenCalledWith({
+      stripePaymentIntentId: "pi_test",
+      amountCents: expected,
+      reason: "requested_by_customer",
+    });
+  },
+);
+it.each([
+  ["jpy", "0.5"],
+  ["mga", "1.5"],
+  ["isk", "1.01"],
+  ["ugx", "1.01"],
+  ["usd", "0"],
+  ["usd", "1.005"],
+  ["usd", "1e2"],
+  ["usd", "90071992547409.92"],
+  ["ZZZ", "1"],
+  ["bhd", "1"],
+  [null, "1"],
+])("blocks invalid original %s amount %s", async (currency, input) => {
+  const issueRefund = vi.fn();
+  const { result } = renderHook(() =>
+    useRefunds({
+      scopeKey: "seller",
+      paymentIntentId: "pi_test",
+      paymentCurrency: currency,
+      issueRefund,
+    }),
+  );
+  act(() => result.current.setRefundAmount(input));
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(issueRefund).not.toHaveBeenCalled();
+  expect(result.current.error).toBeTruthy();
+});
+it("uses independent original charge units for transfer reversal", async () => {
+  const issueRefund = vi.fn().mockResolvedValue({ stripeRefundId: "re_test" });
+  const reverseTransfers = vi.fn().mockResolvedValue({
+    reversals: [],
+    summary: { reversalCount: 0, totalReversed: 0 },
+  });
+  const { result } = renderHook(() =>
+    useRefunds({
+      scopeKey: "seller",
+      paymentIntentId: "pi_test",
+      paymentCurrency: "jpy",
+      sourceChargeId: "ch_test",
+      sourceChargeCurrency: "isk",
+      issueRefund,
+      reverseTransfers,
+    }),
+  );
+  act(() => {
+    result.current.setRefundAmount("500");
+    result.current.setReversalAmount("500");
+  });
+  await act(async () => {
+    await result.current.submitRefund("partial");
+    await result.current.submitReversal("partial");
+  });
+  expect(issueRefund.mock.calls[0][0].amountCents).toBe(500);
+  expect(reverseTransfers).toHaveBeenCalledWith({
+    sourceChargeId: "ch_test",
+    amountCents: 50000,
+  });
+});
+it("omits amount for full operations even with unavailable currency", async () => {
+  const issueRefund = vi.fn().mockResolvedValue({ stripeRefundId: "re_full" });
+  const reverseTransfers = vi.fn().mockResolvedValue({
+    reversals: [],
+    summary: { reversalCount: 0, totalReversed: 0 },
+  });
+  const { result } = renderHook(() =>
+    useRefunds({
+      scopeKey: "seller",
+      paymentIntentId: "pi_test",
+      paymentCurrency: null,
+      sourceChargeId: "ch_test",
+      sourceChargeCurrency: null,
+      issueRefund,
+      reverseTransfers,
+    }),
+  );
+  await act(async () => {
+    await result.current.submitRefund("full");
+    await result.current.submitReversal("full");
+  });
+  expect(
+    Object.prototype.hasOwnProperty.call(
+      issueRefund.mock.calls[0][0],
+      "amountCents",
+    ),
+  ).toBe(false);
+  expect(
+    Object.prototype.hasOwnProperty.call(
+      reverseTransfers.mock.calls[0][0],
+      "amountCents",
+    ),
+  ).toBe(false);
+});
+it("does not apply a verified payment currency to another editable identifier", async () => {
+  const issueRefund = vi.fn();
+  const { result } = renderHook(() =>
+    useRefunds({
+      scopeKey: "seller",
+      paymentIntentId: "pi_verified",
+      paymentCurrency: "jpy",
+      issueRefund,
+    }),
+  );
+  act(() => {
+    result.current.setPaymentIntentId("pi_other");
+    result.current.setRefundAmount("500");
+  });
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(issueRefund).not.toHaveBeenCalled();
+  expect(result.current.error).toMatch(/currency|identifier/i);
+});
+it("requires an identified original payment when currency context is explicit", async () => {
+  const issueRefund = vi.fn();
+  const { result } = renderHook(() =>
+    useRefunds({ scopeKey: "seller", paymentCurrency: "jpy", issueRefund }),
+  );
+  act(() => {
+    result.current.setPaymentIntentId("pi_unverified");
+    result.current.setRefundAmount("500");
+  });
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(issueRefund).not.toHaveBeenCalled();
+});
+it("does not apply a verified charge currency to another reversal identifier", async () => {
+  const reverseTransfers = vi.fn();
+  const { result } = renderHook(() =>
+    useRefunds({
+      scopeKey: "seller",
+      sourceChargeId: "ch_verified",
+      sourceChargeCurrency: "jpy",
+      issueRefund: vi.fn(),
+      reverseTransfers,
+    }),
+  );
+  act(() => {
+    result.current.setSourceChargeId("ch_other");
+    result.current.setReversalAmount("500");
+  });
+  await act(async () => {
+    await result.current.submitReversal("partial");
+  });
+  expect(reverseTransfers).not.toHaveBeenCalled();
+});
+it("resets currency and payment scoped amounts/pending and ignores late completion", async () => {
+  let finish: ((value: { stripeRefundId: string }) => void) | undefined;
+  const issueRefund = vi
+    .fn()
+    .mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        }),
+    )
+    .mockResolvedValue({ stripeRefundId: "re_new" });
+  const { result, rerender } = renderHook(
+    ({ currency, id }) =>
+      useRefunds({
+        scopeKey: "seller",
+        paymentIntentId: id,
+        paymentCurrency: currency,
+        issueRefund,
+      }),
+    { initialProps: { currency: "usd", id: "pi_one" } },
+  );
+  act(() => result.current.setRefundAmount("10.00"));
+  let pending: Promise<unknown> | undefined;
+  act(() => {
+    pending = result.current.submitRefund("partial");
+  });
+  expect(result.current.isPending).toBe(true);
+  rerender({ currency: "jpy", id: "pi_two" });
+  expect(result.current.refundAmount).toBe("");
+  expect(result.current.isPending).toBe(false);
+  await act(async () => {
+    finish?.({ stripeRefundId: "re_old" });
+    await pending;
+  });
+  expect(result.current.refundResult).toBeNull();
+  act(() => result.current.setRefundAmount("500"));
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(issueRefund).toHaveBeenLastCalledWith({
+    stripePaymentIntentId: "pi_two",
+    amountCents: 500,
+    reason: "requested_by_customer",
+  });
+});
+it("retains exact currency units through a retry", async () => {
+  const issueRefund = vi
+    .fn()
+    .mockRejectedValueOnce(new Error("Retry"))
+    .mockResolvedValue({ stripeRefundId: "re_retry" });
+  const { result } = renderHook(() =>
+    useRefunds({
+      scopeKey: "seller",
+      paymentIntentId: "pi_test",
+      paymentCurrency: "jpy",
+      issueRefund,
+    }),
+  );
+  act(() => result.current.setRefundAmount("500"));
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(result.current.error).toBe("Retry");
+  await act(async () => {
+    await result.current.submitRefund("partial");
+  });
+  expect(issueRefund).toHaveBeenNthCalledWith(2, {
+    stripePaymentIntentId: "pi_test",
+    amountCents: 500,
+    reason: "requested_by_customer",
+  });
+});
+it("labels and validates native original-currency fields", async () => {
+  const issueRefund = vi
+    .fn()
+    .mockResolvedValue({ stripeRefundId: "re_native" });
+  render(
+    <Refunds
+      scopeKey="seller"
+      paymentIntentId="pi_test"
+      paymentCurrency="jpy"
+      issueRefund={issueRefund}
+    />,
+  );
+  const field = screen.getByLabelText("Partial refund amount (JPY)");
+  expect(field).toHaveAttribute("step", "1");
+  expect(field).toHaveAttribute("inputmode", "numeric");
+  await userEvent.type(field, "500");
+  await userEvent.click(screen.getByRole("button", { name: "Partial refund" }));
+  expect(issueRefund).toHaveBeenCalledWith({
+    stripePaymentIntentId: "pi_test",
+    amountCents: 500,
+    reason: "requested_by_customer",
+  });
+});