@fantastic.dev/better-stripe 0.15.0 → 0.17.0

package/src/react/components/EarningsSummary.tsx

@@ -46,6 +46,8 @@ export type EarningsSummaryProps = {
     net?: string;
     paidOut?: string;
   };
+  /** Override formatting for observed currencies outside the charge formatter. */
+  formatAmount?: (amount: number, currency: string, locale?: string) => string;
   locale?: string;
   className?: string;
   children?: (props: EarningsSummaryRenderProps) => ReactNode;
@@ -70,6 +72,7 @@ export function EarningsSummary({
   noPayoutsLabel = "No payouts yet",
   labels,
   locale,
+  formatAmount = formatPrice,
   className,
   children,
 }: EarningsSummaryProps) {
@@ -93,12 +96,12 @@ export function EarningsSummary({
     ? latestPayoutLabel
         .replace(
           "{amount}",
-          formatPrice(latestPayout.amount, latestPayout.currency, locale),
+          formatAmount(latestPayout.amount, latestPayout.currency, locale),
         )
         .replace("{status}", latestPayout.status)
     : noPayoutsLabel;
 
-  const money = (amount: number) => formatPrice(amount, currency, locale);
+  const money = (amount: number) => formatAmount(amount, currency, locale);
   const renderProps: EarningsSummaryRenderProps = {
     grossLabel: money(gross),
     reversedLabel: money(reversed),

package/src/react/hooks/useCurrencyEarnings.test.ts

@@ -0,0 +1,59 @@
+import { expect, it } from "vitest";
+import { createUseCurrencyEarnings } from "./useCurrencyEarnings.js";
+it("joins exact server totals by currency without summing preview rows", () => {
+  const earnings = {
+    totals: [
+      {
+        currency: "jpy",
+        gross: 1000,
+        reversed: 100,
+        net: 900,
+        transferCount: 99,
+      },
+    ],
+    transfers: [],
+  };
+  const payouts = {
+    totals: [{ currency: "usd", paidOut: 50, payoutCount: 20 }],
+    payouts: [],
+  };
+  const useEarnings = createUseCurrencyEarnings(
+    (ref) => (ref === "earnings" ? earnings : payouts),
+    "earnings",
+    "payouts",
+  );
+  expect(useEarnings("acct_a").totals).toEqual([
+    {
+      currency: "jpy",
+      gross: 1000,
+      reversed: 100,
+      net: 900,
+      transferCount: 99,
+      paidOut: 0,
+      payoutCount: 0,
+    },
+    {
+      currency: "usd",
+      gross: 0,
+      reversed: 0,
+      net: 0,
+      transferCount: 0,
+      paidOut: 50,
+      payoutCount: 20,
+    },
+  ]);
+});
+it("skips unresolved accounts and distinguishes loading from empty totals", () => {
+  const args: unknown[] = [];
+  const hook = createUseCurrencyEarnings(
+    (_ref, value) => {
+      args.push(value);
+      return undefined;
+    },
+    "earnings",
+    "payouts",
+  );
+  expect(hook(undefined)).toMatchObject({ totals: [], isLoading: false });
+  expect(args).toEqual(["skip", "skip"]);
+  expect(hook("acct_a").isLoading).toBe(true);
+});

package/src/react/hooks/useCurrencyEarnings.ts

@@ -0,0 +1,73 @@
+"use client";
+import type { EarningsTransfer } from "./useEarnings.js";
+import type { StripeComponentPayout } from "../types.js";
+export type CurrencyEarningsTotal = {
+  currency: string;
+  gross: number;
+  reversed: number;
+  net: number;
+  transferCount: number;
+};
+export type CurrencyPayoutTotal = {
+  currency: string;
+  paidOut: number;
+  payoutCount: number;
+};
+export type AccountCurrencyEarnings = {
+  totals: CurrencyEarningsTotal[];
+  transfers: EarningsTransfer[];
+};
+export type AccountCurrencyPayouts = {
+  totals: CurrencyPayoutTotal[];
+  payouts: StripeComponentPayout[];
+};
+export type UseCurrencyEarningsResult = {
+  totals: (CurrencyEarningsTotal & CurrencyPayoutTotal)[];
+  transfers: EarningsTransfer[];
+  payouts: StripeComponentPayout[];
+  isLoading: boolean;
+};
+/** Bind authorized host queries to the maintained component currency summaries. */
+export function createUseCurrencyEarnings(
+  useQuery: (ref: any, args: Record<string, unknown> | "skip") => any,
+  earningsRef: any,
+  payoutsRef: any,
+) {
+  return function useCurrencyEarnings(
+    accountId: string | undefined,
+  ): UseCurrencyEarningsResult {
+    const earnings = useQuery(
+      earningsRef,
+      accountId ? { destinationAccountId: accountId } : "skip",
+    ) as AccountCurrencyEarnings | undefined;
+    const payouts = useQuery(payoutsRef, accountId ? { accountId } : "skip") as
+      AccountCurrencyPayouts | undefined;
+    const byCurrency = new Map<
+      string,
+      CurrencyEarningsTotal & CurrencyPayoutTotal
+    >();
+    for (const row of earnings?.totals ?? [])
+      byCurrency.set(row.currency, { ...row, paidOut: 0, payoutCount: 0 });
+    for (const row of payouts?.totals ?? [])
+      byCurrency.set(row.currency, {
+        ...(byCurrency.get(row.currency) ?? {
+          currency: row.currency,
+          gross: 0,
+          reversed: 0,
+          net: 0,
+          transferCount: 0,
+        }),
+        ...row,
+      });
+    return {
+      totals: [...byCurrency.values()].sort((a, b) =>
+        a.currency.localeCompare(b.currency),
+      ),
+      transfers: earnings?.transfers ?? [],
+      payouts: payouts?.payouts ?? [],
+      isLoading:
+        accountId !== undefined &&
+        (earnings === undefined || payouts === undefined),
+    };
+  };
+}

package/src/react/index.ts

@@ -293,3 +293,15 @@ export {
 
 export { SaveCard } from "./workflows/SaveCard.js";
 export type { SaveCardProps, SaveCardFormState } from "./workflows/SaveCard.js";
+
+export { createUseCurrencyEarnings } from "./hooks/useCurrencyEarnings.js";
+export type {
+  CurrencyEarningsTotal,
+  CurrencyPayoutTotal,
+  AccountCurrencyEarnings,
+  AccountCurrencyPayouts,
+  UseCurrencyEarningsResult,
+} from "./hooks/useCurrencyEarnings.js";
+
+// Pins end cursors for the component paginator, including reactive page splits.
+export { usePaginatedQuery as useComponentPaginatedQuery } from "convex-helpers/react";

package/src/react/read-contracts.render.test.tsx

@@ -0,0 +1,20 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, it } from "vitest";
+import { EarningsSummary } from "./components/EarningsSummary.js";
+it("lets currency-aware earnings consumers format three-decimal observed amounts", () => {
+  const html = renderToStaticMarkup(
+    createElement(EarningsSummary, {
+      gross: 1234,
+      reversed: 100,
+      net: 1134,
+      paidOut: 1000,
+      currency: "kwd",
+      payouts: [],
+      formatAmount: (amount: number, currency: string) =>
+        `${currency.toUpperCase()} ${(amount / 1000).toFixed(3)}`,
+    }),
+  );
+  expect(html).toContain("KWD 1.234");
+  expect(html).toContain("KWD 1.134");
+});

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

@@ -39,3 +39,24 @@ it("renders chargeback economics and explicitly handles missing charge links", (
   expect(screen.getByText("$80.00")).toBeTruthy();
   expect(screen.getByText("No transfer rows found.")).toBeTruthy();
 });
+it("distinguishes reserved recovery from money already collected", () => {
+  render(
+    <CostRecovery
+      rows={[
+        {
+          paymentIntentId: "pi_reserved",
+          amountDue: 1000,
+          collectedAmount: 400,
+          invoicedAmount: 999,
+          reservedAmount: 300,
+          outstanding: 300,
+          currency: "usd",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("Collected")).toBeTruthy();
+  expect(screen.getByText("Reserved")).toBeTruthy();
+  expect(screen.queryByText("$9.99")).toBeNull();
+  expect(screen.getAllByText("$3.00")).toHaveLength(2);
+});

package/src/react/workflows/Costs.tsx

@@ -10,24 +10,30 @@ export type CostRecoveryRow = {
   amountDue: number;
   collectedAmount: number;
   invoicedAmount: number;
+  reservedAmount?: number;
   outstanding: number;
   currency: string;
 };
 export function CostRecovery(props: ResourceCollectionProps<CostRecoveryRow>) {
+  const reserved = props.rows?.some((row) => row.reservedAmount !== undefined);
   const columns: WorkflowColumn<CostRecoveryRow>[] = [
     { id: "payment", label: "Payment", cell: (row) => row.paymentIntentId },
     ...(
       [
         ["amountDue", "Total cost"],
-        ["collectedAmount", "Deducted from earnings"],
-        ["invoicedAmount", "Added to invoice"],
+        ["collectedAmount", reserved ? "Collected" : "Deducted from earnings"],
+        [
+          reserved ? "reservedAmount" : "invoicedAmount",
+          reserved ? "Reserved" : "Added to invoice",
+        ],
         ["outstanding", "Outstanding"],
       ] as const
     ).map(([field, label]) => ({
       id: field,
       label,
       align: "end" as const,
-      cell: (row: CostRecoveryRow) => formatPrice(row[field], row.currency),
+      cell: (row: CostRecoveryRow) =>
+        formatPrice(row[field] ?? row.invoicedAmount, row.currency),
     })),
   ];
   return (