@fantastic.dev/better-stripe 0.11.0 → 0.13.0

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

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

@@ -0,0 +1,56 @@
+import { getChargeCurrencyMetadata } from "../../client/charge-currency.js";
+import { formatPrice } from "../lib/price-helpers.js";
+
+export type RefundPreviewGroup = {
+  currency: string;
+  status: string;
+  /** Loaded rows only. Null means unknown/invalid units or an unsafe sum. */
+  amount: number | null;
+  count: number;
+};
+
+function isRefundAmount(amount: number, currency: string): boolean {
+  return (
+    Number.isSafeInteger(amount) &&
+    amount >= 0 &&
+    getChargeCurrencyMetadata(currency) !== null
+  );
+}
+
+/** Observed refund units, including fractional ISK/UGX amounts; not input eligibility. */
+export function formatRefundAmount(
+  amount: number,
+  currency: string,
+  locale = "en-US",
+): string | null {
+  return isRefundAmount(amount, currency)
+    ? formatPrice(amount, currency, locale)
+    : null;
+}
+
+/** Group only the supplied preview, preserving provider status and currency. */
+export function groupRefundPreview(
+  rows: readonly { amount: number; currency: string; status: string }[],
+): RefundPreviewGroup[] {
+  const groups = new Map<string, RefundPreviewGroup>();
+  for (const row of rows) {
+    const currency = row.currency.toLowerCase();
+    const key = JSON.stringify([currency, row.status]);
+    const group = groups.get(key) ?? {
+      currency,
+      status: row.status,
+      amount: 0,
+      count: 0,
+    };
+    group.count++;
+    if (group.amount === null || !isRefundAmount(row.amount, currency))
+      group.amount = null;
+    else {
+      const sum = BigInt(group.amount) + BigInt(row.amount);
+      group.amount =
+        sum <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(sum) : null;
+    }
+    groups.set(key, group);
+  }
+  return [...groups.values()];
+}