@fantastic.dev/better-stripe 0.12.0 → 0.13.0

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

package/src/react/workflows/Refunds.tsx

@@ -2,12 +2,20 @@
 import { useState, useId, type ReactNode } from "react";
 import { useWorkflowAction } from "./useWorkflowAction.js";
 import { Connect, type ConnectProps } from "./Connect.js";
+import {
+  getChargeCurrencyMetadata,
+  parseChargeAmount,
+} from "../../client/charge-currency.js";
 export type RefundRequest = {
   stripePaymentIntentId: string;
+  /** Original payment currency's provider units. Legacy name, not universal cents. */
   amountCents?: number;
   reason: "requested_by_customer";
 };
-export type ReversalRequest = { sourceChargeId: string; amountCents?: number };
+export type ReversalRequest = {
+  sourceChargeId: string;
+  /** Original charge provider units. */ amountCents?: number;
+};
 export type RefundResult = { stripeRefundId: string };
 export type ReversalResult = {
   reversals: { stripeTransferId: string; amount: number }[];
@@ -17,26 +25,50 @@ export type RefundActionsProps = {
   scopeKey: string;
   paymentIntentId?: string;
   sourceChargeId?: string;
+  /** Verified currency for paymentIntentId. Omitted = legacy USD; null = unknown. */
+  paymentCurrency?: string | null;
+  /** Verified currency for sourceChargeId, independently of the refund payment. */
+  sourceChargeCurrency?: string | null;
   issueRefund: (args: RefundRequest) => Promise<RefundResult>;
   reverseTransfers?: (args: ReversalRequest) => Promise<ReversalResult>;
 };
-/** Currency input expressed in two decimal minor units. Rejects rounding and scientific notation. */
+/** Exact positive refund amount in the original charge currency's provider units. */
+export function parseRefundAmount(
+  value: string,
+  currency: string,
+): number | null {
+  const amount = parseChargeAmount(value.trim(), currency);
+  return amount !== null && amount > 0 ? amount : null;
+}
+/** Legacy USD-only parser. Use parseRefundAmount for original-currency inputs. */
 export function parseAmountCents(value: string): number | null {
-  if (!/^\d+(?:\.\d{1,2})?$/.test(value.trim())) return null;
-  const [whole, fraction = ""] = value.trim().split(".");
-  const amount = Number(whole) * 100 + Number(fraction.padEnd(2, "0"));
-  return Number.isSafeInteger(amount) && amount > 0 ? amount : null;
+  return parseRefundAmount(value, "usd");
 }
 export function useRefunds(props: RefundActionsProps) {
+  const paymentCurrency =
+    props.paymentCurrency === undefined
+      ? "usd"
+      : (props.paymentCurrency?.toLowerCase() ?? null);
+  const sourceChargeCurrency =
+    props.sourceChargeCurrency === undefined
+      ? "usd"
+      : (props.sourceChargeCurrency?.toLowerCase() ?? null);
+  const scope = JSON.stringify([
+    props.scopeKey,
+    props.paymentIntentId?.trim(),
+    props.sourceChargeId?.trim(),
+    paymentCurrency,
+    sourceChargeCurrency,
+  ]);
   const initial = {
-    scope: props.scopeKey,
+    scope,
     paymentIntentId: props.paymentIntentId ?? "",
     sourceChargeId: props.sourceChargeId ?? "",
     refundAmount: "",
     reversalAmount: "",
   };
   const [fields, setFields] = useState(initial);
-  if (fields.scope !== props.scopeKey) setFields(initial);
+  if (fields.scope !== scope) setFields(initial);
   const [operationType, setOperationType] = useState<"refund" | "reversal">(
     "refund",
   );
@@ -57,24 +89,43 @@ export function useRefunds(props: RefundActionsProps) {
             ? "Enter a PaymentIntent id before issuing a refund."
             : "Enter a source charge id before reversing transfers.",
         );
+      const currency =
+        operation.type === "refund" ? paymentCurrency : sourceChargeCurrency;
+      const boundId =
+        operation.type === "refund"
+          ? props.paymentIntentId
+          : props.sourceChargeId;
+      const hasExplicitCurrency =
+        operation.type === "refund"
+          ? props.paymentCurrency !== undefined
+          : props.sourceChargeCurrency !== undefined;
+      if (
+        operation.kind === "partial" &&
+        hasExplicitCurrency &&
+        id !== boundId?.trim()
+      )
+        throw new Error(
+          "Original currency is not verified for this identifier.",
+        );
       const amount =
         operation.kind === "partial"
-          ? parseAmountCents(
+          ? parseRefundAmount(
               operation.type === "refund"
                 ? fields.refundAmount
                 : fields.reversalAmount,
+              currency ?? "",
             )
           : undefined;
       if (amount === null)
         throw new Error(
-          `Enter a positive partial ${operation.type === "refund" ? "refund" : "reversal"} amount with at most two decimal places.`,
+          `Enter a positive partial ${operation.type === "refund" ? "refund" : "reversal"} amount in supported original currency units.`,
         );
       if (operation.type === "refund")
         return {
           type: "refund" as const,
           value: await props.issueRefund({
             stripePaymentIntentId: id,
-            amountCents: amount,
+            ...(amount === undefined ? {} : { amountCents: amount }),
             reason: "requested_by_customer",
           }),
         };
@@ -84,11 +135,15 @@ export function useRefunds(props: RefundActionsProps) {
         type: "reversal" as const,
         value: await props.reverseTransfers({
           sourceChargeId: id,
-          amountCents: amount,
+          ...(amount === undefined ? {} : { amountCents: amount }),
         }),
       };
     },
-    props.scopeKey,
+    JSON.stringify([
+      scope,
+      fields.paymentIntentId.trim(),
+      fields.sourceChargeId.trim(),
+    ]),
   );
   const set = (
     name:
@@ -97,6 +152,14 @@ export function useRefunds(props: RefundActionsProps) {
   ) => setFields((previous) => ({ ...previous, [name]: value }));
   return {
     ...fields,
+    scope: props.scopeKey,
+    paymentCurrency,
+    sourceChargeCurrency,
+    refundInputDecimalPlaces:
+      getChargeCurrencyMetadata(paymentCurrency ?? "")?.displayDecimals ?? null,
+    reversalInputDecimalPlaces:
+      getChargeCurrencyMetadata(sourceChargeCurrency ?? "")?.displayDecimals ??
+      null,
     setPaymentIntentId: (value: string) => set("paymentIntentId", value),
     setSourceChargeId: (value: string) => set("sourceChargeId", value),
     setRefundAmount: (value: string) => set("refundAmount", value),
@@ -127,6 +190,35 @@ export function Refunds(props: RefundsProps) {
     <RefundsBody key={props.scopeKey} {...props} />
   );
 }
+function RefundAmountInput(props: {
+  id: string;
+  label: string;
+  currency: string | null | undefined;
+  decimalPlaces: number | null;
+  value: string;
+  onChange: (value: string) => void;
+}) {
+  const step = props.decimalPlaces === 0 ? "1" : "0.01";
+  return (
+    <>
+      <label htmlFor={props.id}>
+        {props.label}
+        {props.currency !== undefined
+          ? ` (${props.currency?.toUpperCase() ?? "currency unavailable"})`
+          : ""}
+      </label>
+      <input
+        id={props.id}
+        type="number"
+        min={step}
+        step={step}
+        inputMode={props.decimalPlaces === 0 ? "numeric" : "decimal"}
+        value={props.value}
+        onChange={(event) => props.onChange(event.target.value)}
+      />
+    </>
+  );
+}
 function RefundsBody(
   props: RefundActionsProps & {
     children?: (state: RefundsRenderProps) => ReactNode;
@@ -145,14 +237,13 @@ function RefundsBody(
         value={state.paymentIntentId}
         onChange={(event) => state.setPaymentIntentId(event.target.value)}
       />
-      <label htmlFor={`${id}-amount`}>Partial refund amount</label>
-      <input
+      <RefundAmountInput
         id={`${id}-amount`}
-        type="number"
-        min="0.01"
-        step="0.01"
+        label="Partial refund amount"
+        currency={props.paymentCurrency}
+        decimalPlaces={state.refundInputDecimalPlaces}
         value={state.refundAmount}
-        onChange={(event) => state.setRefundAmount(event.target.value)}
+        onChange={state.setRefundAmount}
       />
       <button
         type="button"
@@ -184,14 +275,13 @@ function RefundsBody(
             value={state.sourceChargeId}
             onChange={(event) => state.setSourceChargeId(event.target.value)}
           />
-          <label htmlFor={`${id}-reversal`}>Partial reversal amount</label>
-          <input
+          <RefundAmountInput
             id={`${id}-reversal`}
-            type="number"
-            min="0.01"
-            step="0.01"
+            label="Partial reversal amount"
+            currency={props.sourceChargeCurrency}
+            decimalPlaces={state.reversalInputDecimalPlaces}
             value={state.reversalAmount}
-            onChange={(event) => state.setReversalAmount(event.target.value)}
+            onChange={state.setReversalAmount}
           />
           <button
             type="button"

package/src/react/workflows/index.ts

@@ -34,7 +34,12 @@ export type {
   PayoutSnapshot,
   PayoutRow,
 } from "./Payouts.js";
-export { Refunds, useRefunds, parseAmountCents } from "./Refunds.js";
+export {
+  Refunds,
+  useRefunds,
+  parseAmountCents,
+  parseRefundAmount,
+} from "./Refunds.js";
 export type {
   RefundsProps,
   RefundsRenderProps,
@@ -45,6 +50,8 @@ export type {
   ReversalResult,
 } from "./Refunds.js";
 export { Collection } from "./Collection.js";
+export { formatRefundAmount, groupRefundPreview } from "./refund-preview.js";
+export type { RefundPreviewGroup } from "./refund-preview.js";
 export type {
   CollectionProps,
   CollectionRenderProps,

package/src/react/workflows/refund-preview.test.ts

@@ -0,0 +1,65 @@
+import { expect, it } from "vitest";
+import { formatRefundAmount, groupRefundPreview } from "./refund-preview.js";
+
+it("isolates loaded amounts by currency and provider status", () => {
+  expect(
+    groupRefundPreview([
+      { amount: 100, currency: "USD", status: "succeeded" },
+      { amount: 250, currency: "usd", status: "succeeded" },
+      { amount: 500, currency: "jpy", status: "succeeded" },
+      { amount: 200, currency: "eur", status: "pending" },
+      { amount: 300, currency: "jpy", status: "failed" },
+      { amount: 400, currency: "usd", status: "canceled" },
+    ]),
+  ).toEqual([
+    { currency: "usd", status: "succeeded", amount: 350, count: 2 },
+    { currency: "jpy", status: "succeeded", amount: 500, count: 1 },
+    { currency: "eur", status: "pending", amount: 200, count: 1 },
+    { currency: "jpy", status: "failed", amount: 300, count: 1 },
+    { currency: "usd", status: "canceled", amount: 400, count: 1 },
+  ]);
+});
+
+it("keeps empty separate from recorded zero and fails closed on invalid/unsafe groups", () => {
+  expect(groupRefundPreview([])).toEqual([]);
+  expect(
+    groupRefundPreview([{ amount: 0, currency: "usd", status: "succeeded" }])[0]
+      ?.amount,
+  ).toBe(0);
+  for (const amount of [-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+    expect(
+      groupRefundPreview([{ amount, currency: "usd", status: "succeeded" }])[0]
+        ?.amount,
+    ).toBeNull();
+  }
+  expect(
+    groupRefundPreview([
+      { amount: Number.MAX_SAFE_INTEGER, currency: "usd", status: "succeeded" },
+      { amount: 1, currency: "usd", status: "succeeded" },
+    ])[0]?.amount,
+  ).toBeNull();
+  expect(
+    groupRefundPreview([{ amount: 100, currency: "zzz", status: "pending" }])[0]
+      ?.amount,
+  ).toBeNull();
+});
+
+it.each([
+  [500, "jpy", "¥500"],
+  [500, "mga", "MGA\u00a0500"],
+  [50000, "isk", "ISK\u00a0500"],
+  [101, "ugx", "UGX\u00a01.01"],
+  [1045, "huf", "HUF\u00a010.45"],
+  [0, "usd", "$0.00"],
+])(
+  "formats observed original refund units %s %s",
+  (amount, currency, expected) => {
+    expect(formatRefundAmount(amount, currency)).toBe(expected);
+  },
+);
+
+it("does not throw for unknown currency or invalid observed amounts", () => {
+  expect(formatRefundAmount(100, "zzz")).toBeNull();
+  expect(formatRefundAmount(-1, "usd")).toBeNull();
+  expect(formatRefundAmount(1.5, "jpy")).toBeNull();
+});