@fantastic.dev/better-stripe 0.7.0 → 0.8.0

package/src/react/workflows/Collections.tsx

@@ -0,0 +1,213 @@
+"use client";
+import type { CollectionProps, WorkflowColumn } from "./Collection.js";
+import { Collection } from "./Collection.js";
+import { formatPrice } from "../lib/price-helpers.js";
+export type ResourceCollectionProps<Row> = Omit<
+  CollectionProps<Row>,
+  "columns" | "getKey"
+> & { columns?: WorkflowColumn<Row>[] };
+export type SaleRow = {
+  _id?: string;
+  planId: string;
+  paymentIntentId: string;
+  chargeId?: string;
+  gross: number;
+  processingFee: number;
+  platformNet: number;
+  affiliateNet: number;
+  costRecoveryAmount?: number;
+  sellerNet: number;
+  currency: string;
+  status: string;
+};
+export function Sales(props: ResourceCollectionProps<SaleRow>) {
+  const columns: WorkflowColumn<SaleRow>[] = [
+    { id: "planId", label: "Plan", cell: (row) => row.planId },
+    ...(
+      [
+        ["gross", "Sale"],
+        ["processingFee", "Stripe processing"],
+        ["platformNet", "Platform"],
+        ["affiliateNet", "Affiliate"],
+        ["costRecoveryAmount", "Cost recovery"],
+        ["sellerNet", "Your earnings"],
+      ] as const
+    ).map(([field, label]) => ({
+      id: field,
+      label,
+      align: "end" as const,
+      cell: (row: SaleRow) => formatPrice(row[field] ?? 0, row.currency),
+    })),
+    { id: "status", label: "Status", cell: (row) => row.status },
+    { id: "payment", label: "Payment", cell: (row) => row.paymentIntentId },
+  ];
+  return (
+    <Collection
+      emptyLabel="No sales yet."
+      {...props}
+      getKey={(row) => row._id ?? row.paymentIntentId}
+      columns={props.columns ?? columns}
+    />
+  );
+}
+export type InvoiceRow = {
+  stripeInvoiceId: string;
+  amountPaid?: number;
+  amountDue?: number;
+  currency: string;
+  status: string;
+  hostedInvoiceUrl?: string;
+};
+export function Invoices(props: ResourceCollectionProps<InvoiceRow>) {
+  const columns: WorkflowColumn<InvoiceRow>[] = [
+    { id: "id", label: "Invoice ID", cell: (row) => row.stripeInvoiceId },
+    {
+      id: "amount",
+      label: "Amount",
+      align: "end",
+      cell: (row) =>
+        formatPrice(row.amountPaid ?? row.amountDue ?? 0, row.currency),
+    },
+    { id: "status", label: "Status", cell: (row) => row.status },
+    {
+      id: "invoice",
+      label: "Invoice",
+      cell: (row) =>
+        row.hostedInvoiceUrl ? (
+          <a
+            href={row.hostedInvoiceUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            View invoice
+          </a>
+        ) : (
+          "Unavailable"
+        ),
+    },
+  ];
+  return (
+    <Collection
+      emptyLabel="No invoices yet."
+      {...props}
+      getKey={(row) => row.stripeInvoiceId}
+      columns={props.columns ?? columns}
+    />
+  );
+}
+export type RefundRow = {
+  /** Unix milliseconds, matching Convex creation timestamps. */
+  _creationTime?: number;
+  stripeRefundId: string;
+  amount: number;
+  currency: string;
+  status: string;
+  reason?: string;
+};
+export function RefundHistory(props: ResourceCollectionProps<RefundRow>) {
+  const columns: WorkflowColumn<RefundRow>[] = [
+    { id: "id", label: "Refund ID", cell: (row) => row.stripeRefundId },
+    {
+      id: "amount",
+      label: "Amount",
+      align: "end",
+      cell: (row) => formatPrice(row.amount, row.currency),
+    },
+    { id: "status", label: "Status", cell: (row) => row.status },
+    {
+      id: "reason",
+      label: "Reason",
+      cell: (row) => row.reason ?? "Not supplied",
+    },
+    {
+      id: "created",
+      label: "Created",
+      cell: (row) =>
+        row._creationTime === undefined
+          ? "Not supplied"
+          : new Date(row._creationTime).toLocaleString(),
+    },
+  ];
+  return (
+    <Collection
+      emptyLabel="No refunds yet."
+      {...props}
+      getKey={(row) => row.stripeRefundId}
+      columns={props.columns ?? columns}
+    />
+  );
+}
+export type ReferredSaleRow = {
+  stripeTransferId: string;
+  sourceChargeId?: string;
+  storeName?: string | null;
+  amount: number;
+  currency?: string;
+};
+export function ReferredSales(props: ResourceCollectionProps<ReferredSaleRow>) {
+  const columns: WorkflowColumn<ReferredSaleRow>[] = [
+    {
+      id: "store",
+      label: "Store",
+      cell: (row) => row.storeName ?? "Store unavailable",
+    },
+    {
+      id: "payment",
+      label: "Payment",
+      cell: (row) => row.sourceChargeId ?? row.stripeTransferId,
+    },
+    {
+      id: "commission",
+      label: "Commission",
+      align: "end",
+      cell: (row) => formatPrice(row.amount, row.currency ?? "usd"),
+    },
+  ];
+  return (
+    <Collection
+      emptyLabel="No referred sales yet."
+      {...props}
+      getKey={(row) => row.stripeTransferId}
+      columns={props.columns ?? columns}
+    />
+  );
+}
+export type WebhookEventRow = {
+  stripeEventId: string;
+  eventType: string;
+  status: string;
+  processedAt?: number;
+  lastError?: string;
+  livemode?: boolean;
+};
+export function WebhookEvents<Row extends WebhookEventRow>(
+  props: ResourceCollectionProps<Row>,
+) {
+  const columns: WorkflowColumn<Row>[] = [
+    { id: "type", label: "Type", cell: (row) => row.eventType },
+    { id: "status", label: "Status", cell: (row) => row.status },
+    { id: "id", label: "Event ID", cell: (row) => row.stripeEventId },
+    { id: "error", label: "Error", cell: (row) => row.lastError ?? "None" },
+    {
+      id: "processed",
+      label: "Processed",
+      cell: (row) =>
+        row.processedAt === undefined
+          ? "Not supplied"
+          : new Date(row.processedAt).toLocaleString(),
+    },
+    {
+      id: "mode",
+      label: "Mode",
+      cell: (row) => (row.livemode ? "Live" : "Test"),
+    },
+  ];
+  return (
+    <Collection
+      emptyLabel="No webhook events yet."
+      {...props}
+      getKey={(row) => row.stripeEventId}
+      columns={props.columns ?? columns}
+    />
+  );
+}

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

@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+vi.mock("../components/ConnectProvider.js", () => ({
+  ConnectProvider: ({ children }: { children: ReactNode }) => children,
+}));
+vi.mock("@stripe/react-connect-js", () => {
+  const Widget = ({
+    onLoadError,
+  }: {
+    onLoadError: (event: { error: { message: string } }) => void;
+  }) => (
+    <button
+      onClick={() =>
+        onLoadError({ error: { message: "Account not eligible" } })
+      }
+    >
+      Stripe widget
+    </button>
+  );
+  return {
+    ConnectAccountManagement: Widget,
+    ConnectAccountOnboarding: Widget,
+    ConnectBalances: Widget,
+    ConnectDisputesList: Widget,
+    ConnectNotificationBanner: Widget,
+    ConnectPayments: Widget,
+    ConnectPayouts: Widget,
+  };
+});
+import { Connect } from "./Connect.js";
+afterEach(cleanup);
+it("exposes Stripe widget errors and remounts only on retry", async () => {
+  render(
+    <Connect
+      component="payouts"
+      scopeKey="acct_test"
+      publishableKey="pk_test_example"
+      fetchClientSecret={async () => "secret"}
+    />,
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Stripe widget" }));
+  expect(screen.getByRole("alert").textContent).toContain(
+    "Account not eligible",
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Retry" }));
+  expect(screen.getByRole("button", { name: "Stripe widget" })).toBeTruthy();
+});

package/src/react/workflows/Connect.tsx

@@ -0,0 +1,107 @@
+"use client";
+import { useState, type ReactNode } from "react";
+import {
+  ConnectAccountManagement,
+  ConnectAccountOnboarding,
+  ConnectBalances,
+  ConnectDisputesList,
+  ConnectNotificationBanner,
+  ConnectPayments,
+  ConnectPayouts,
+} from "@stripe/react-connect-js";
+import {
+  ConnectProvider,
+  type ConnectProviderProps,
+} from "../components/ConnectProvider.js";
+export type ConnectComponent =
+  | "account"
+  | "onboarding"
+  | "payments"
+  | "refunds"
+  | "disputes"
+  | "balances"
+  | "payouts"
+  | "notifications";
+export type ConnectRenderProps = {
+  content: ReactNode;
+  error: string | null;
+  retry: () => void;
+  completed: boolean;
+};
+export type ConnectProps = Omit<ConnectProviderProps, "children"> & {
+  component: ConnectComponent;
+  /** Remounts the Stripe instance when the authenticated account changes. The server must authorize it independently. */
+  scopeKey: string;
+  onExit?: () => void;
+  children?: (state: ConnectRenderProps) => ReactNode;
+};
+const widgets = {
+  account: ConnectAccountManagement,
+  onboarding: ConnectAccountOnboarding,
+  payments: ConnectPayments,
+  refunds: ConnectPayments,
+  disputes: ConnectDisputesList,
+  balances: ConnectBalances,
+  payouts: ConnectPayouts,
+  notifications: ConnectNotificationBanner,
+};
+/** Unstyled, account-scoped Connect component with session refresh, error recovery, appearance, and locale. */
+export function Connect(props: ConnectProps) {
+  return (
+    <ConnectBody key={`${props.scopeKey}:${props.component}`} {...props} />
+  );
+}
+function ConnectBody({
+  component,
+  publishableKey,
+  fetchClientSecret,
+  appearance,
+  locale,
+  onExit,
+  children,
+}: ConnectProps) {
+  const [attempt, setAttempt] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+  const [completed, setCompleted] = useState(false);
+  const Widget = widgets[component];
+  const retry = () => {
+    setError(null);
+    setAttempt((value) => value + 1);
+  };
+  const content = error ? (
+    <div role="alert">
+      <p>{error}</p>
+      <button type="button" onClick={retry}>
+        Retry
+      </button>
+    </div>
+  ) : (
+    <ConnectProvider
+      key={attempt}
+      publishableKey={publishableKey}
+      appearance={appearance}
+      locale={locale}
+      fetchClientSecret={async () => {
+        try {
+          return await fetchClientSecret();
+        } catch (error) {
+          setError(error instanceof Error ? error.message : String(error));
+          throw error;
+        }
+      }}
+    >
+      <Widget
+        onLoadError={({ error }) =>
+          setError(error.message ?? "Stripe could not load this component.")
+        }
+        onExit={() => {
+          setCompleted(true);
+          onExit?.();
+        }}
+      />
+    </ConnectProvider>
+  );
+  return (
+    <>{children ? children({ content, error, retry, completed }) : content}</>
+  );
+}

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

@@ -0,0 +1,41 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import { CostRecovery, ChargebackLedger } from "./Costs.js";
+afterEach(cleanup);
+it("displays the authoritative cost balances without inventing a recovery policy", () => {
+  render(
+    <CostRecovery
+      rows={[
+        {
+          paymentIntentId: "pi_cost",
+          amountDue: 1000,
+          collectedAmount: 400,
+          invoicedAmount: 300,
+          outstanding: 300,
+          currency: "usd",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("$10.00")).toBeTruthy();
+  expect(screen.getByText("$4.00")).toBeTruthy();
+  expect(screen.getAllByText("$3.00")).toHaveLength(2);
+});
+it("renders chargeback economics and explicitly handles missing charge links", () => {
+  const { rerender } = render(<ChargebackLedger chargeback={null} />);
+  expect(screen.getByText(/No linked charge/)).toBeTruthy();
+  rerender(
+    <ChargebackLedger
+      chargeback={{
+        dispute: { stripeChargeId: "ch_one", currency: "usd", status: "lost" },
+        gross: 10000,
+        reversed: 2000,
+        net: 8000,
+        transfers: [],
+      }}
+    />,
+  );
+  expect(screen.getByText("$80.00")).toBeTruthy();
+  expect(screen.getByText("No transfer rows found.")).toBeTruthy();
+});

package/src/react/workflows/Costs.tsx

@@ -0,0 +1,133 @@
+"use client";
+import type { ReactNode } from "react";
+import { Collection, type WorkflowColumn } from "./Collection.js";
+import type { ResourceCollectionProps } from "./Collections.js";
+import { formatPrice } from "../lib/price-helpers.js";
+export type CostRecoveryRow = {
+  _id?: string;
+  id?: string;
+  paymentIntentId: string;
+  amountDue: number;
+  collectedAmount: number;
+  invoicedAmount: number;
+  outstanding: number;
+  currency: string;
+};
+export function CostRecovery(props: ResourceCollectionProps<CostRecoveryRow>) {
+  const columns: WorkflowColumn<CostRecoveryRow>[] = [
+    { id: "payment", label: "Payment", cell: (row) => row.paymentIntentId },
+    ...(
+      [
+        ["amountDue", "Total cost"],
+        ["collectedAmount", "Deducted from earnings"],
+        ["invoicedAmount", "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),
+    })),
+  ];
+  return (
+    <Collection
+      emptyLabel="No costs yet."
+      loadingLabel="Loading costs…"
+      {...props}
+      columns={props.columns ?? columns}
+      getKey={(row) => row._id ?? row.id ?? row.paymentIntentId}
+    />
+  );
+}
+export type ChargebackTransfer = {
+  stripeTransferId: string;
+  destinationAccountId: string;
+  amount: number;
+  currency: string;
+  role?: string;
+  reversedAmount?: number;
+  reversalStatus?: string;
+};
+export type ChargebackSummary = {
+  dispute: { stripeChargeId?: string; currency: string; status: string };
+  transfers: ChargebackTransfer[];
+  gross: number;
+  reversed: number;
+  net: number;
+};
+export type ChargebackLedgerRenderProps = {
+  data: ChargebackSummary | null | undefined;
+  isLoading: boolean;
+  isEmpty: boolean;
+  grossLabel: string;
+  reversedLabel: string;
+  netLabel: string;
+  columns: WorkflowColumn<ChargebackTransfer>[];
+};
+export function ChargebackLedger({
+  chargeback,
+  children,
+}: {
+  chargeback: ChargebackSummary | null | undefined;
+  children?: (state: ChargebackLedgerRenderProps) => ReactNode;
+}) {
+  const currency = chargeback?.dispute.currency ?? "usd";
+  const columns: WorkflowColumn<ChargebackTransfer>[] = [
+    { id: "transfer", label: "Transfer", cell: (row) => row.stripeTransferId },
+    {
+      id: "account",
+      label: "Recipient",
+      cell: (row) => row.destinationAccountId,
+    },
+    {
+      id: "amount",
+      label: "Amount",
+      align: "end",
+      cell: (row) => formatPrice(row.amount, row.currency),
+    },
+    {
+      id: "reversed",
+      label: "Reversed",
+      align: "end",
+      cell: (row) => formatPrice(row.reversedAmount ?? 0, row.currency),
+    },
+    {
+      id: "status",
+      label: "Status",
+      cell: (row) => row.reversalStatus ?? "Not reversed",
+    },
+  ];
+  const state: ChargebackLedgerRenderProps = {
+    data: chargeback,
+    isLoading: chargeback === undefined,
+    isEmpty: chargeback === null || !chargeback?.dispute.stripeChargeId,
+    grossLabel: formatPrice(chargeback?.gross ?? 0, currency),
+    reversedLabel: formatPrice(-(chargeback?.reversed ?? 0), currency),
+    netLabel: formatPrice(chargeback?.net ?? 0, currency),
+    columns,
+  };
+  if (children) return <>{children(state)}</>;
+  if (state.isLoading)
+    return <p role="status">Loading chargeback transfers…</p>;
+  if (state.isEmpty) return <p>No linked charge is available yet.</p>;
+  return (
+    <section data-better-stripe="chargeback-ledger">
+      <h3>Chargeback transfers</h3>
+      <dl>
+        <dt>Original transfers</dt>
+        <dd>{state.grossLabel}</dd>
+        <dt>Funds pulled back</dt>
+        <dd>{state.reversedLabel}</dd>
+        <dt>Recipient net</dt>
+        <dd>{state.netLabel}</dd>
+      </dl>
+      <Collection
+        rows={chargeback!.transfers}
+        columns={columns}
+        getKey={(row) => row.stripeTransferId}
+        emptyLabel="No transfer rows found."
+      />
+    </section>
+  );
+}

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

@@ -0,0 +1,25 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useDisputeResponse } from "./Disputes.js";
+afterEach(cleanup);
+it("requires explicit confirmation and clears it when selecting another dispute", async () => {
+  const acceptDispute = vi.fn().mockResolvedValue(null);
+  const { result } = renderHook(() =>
+    useDisputeResponse({ scopeKey: "seller", acceptDispute }),
+  );
+  act(() => result.current.setSelectedId("dp_one"));
+  await act(async () => {
+    await result.current.accept();
+  });
+  expect(acceptDispute).not.toHaveBeenCalled();
+  act(() => result.current.requestAccept());
+  act(() => result.current.setSelectedId("dp_two"));
+  expect(result.current.acceptStatus).toBe("idle");
+  act(() => result.current.requestAccept());
+  await act(async () => {
+    await result.current.accept();
+  });
+  expect(acceptDispute).toHaveBeenCalledWith("dp_two");
+  expect(result.current.acceptStatus).toBe("accepted");
+});