@fantastic.dev/better-stripe 0.23.2 → 0.25.0

package/src/react/workflows/AffiliateRecovery.tsx

@@ -0,0 +1,273 @@
+"use client";
+import type { ReactNode } from "react";
+import type {
+  AffiliateRecoverySnapshot,
+  AffiliateRecoveryObligation,
+  AffiliateRecoveryOperation,
+} from "../../client/affiliateRecovery.js";
+import { formatPrice } from "../lib/price-helpers.js";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type RecoveryMetric = {
+  key: string;
+  label: string;
+  amount: number;
+  formattedValue: string;
+};
+export type RecoveryAdjustment = {
+  row: AffiliateRecoveryObligation;
+  source: string;
+  commission: string;
+  recovered: string;
+  debt: string;
+  status: string;
+};
+export type AffiliateRecoveryView = {
+  adjustments: RecoveryAdjustment[];
+  metrics: RecoveryMetric[];
+  rows: AffiliateRecoveryObligation[];
+  currency: string;
+  isLoading: boolean;
+  isComplete: boolean;
+  isPending: boolean;
+  error: string | null;
+  retry: (id: string) => Promise<unknown>;
+};
+export type AffiliateRecoveryProps = {
+  snapshot: AffiliateRecoverySnapshot | undefined | null;
+  currency: string;
+  showMetrics?: boolean;
+  locale?: string;
+  className?: string;
+  onRetry?: (obligationId: string) => Promise<unknown>;
+  onInspect?: (obligationId: string) => void;
+  sourceHref?: (row: AffiliateRecoveryObligation) => string | undefined;
+  children?: (state: AffiliateRecoveryView) => ReactNode;
+};
+/** Reusable, unstyled recovery state for earnings, referred sales and payouts. */
+export function AffiliateRecovery({
+  snapshot,
+  showMetrics = true,
+  currency,
+  locale,
+  className,
+  onRetry,
+  onInspect,
+  sourceHref,
+  children,
+}: AffiliateRecoveryProps) {
+  const action = useWorkflowAction(
+    async (id: string) => onRetry?.(id),
+    `affiliate-recovery:${currency}`,
+  );
+  const balance = snapshot?.balance;
+  if (
+    (balance && balance.currency !== currency) ||
+    snapshot?.obligations.page.some((row) => row.currency !== currency)
+  )
+    throw new Error("Affiliate recovery display cannot mix currencies.");
+  const definitions = [
+    ["originalCommission", "Original commission"],
+    ["recoveredAmount", "Reversed"],
+    ["outstandingDebt", "Outstanding debt"],
+    ["offsetAmount", "Recovered from future earnings"],
+    ["withheldAmount", "Withheld earnings"],
+    ["reservedRecovery", "Pending recovery"],
+    ["reservedRestoration", "Pending restoration"],
+    ["restoredAmount", "Restored"],
+    ["restorationDue", "Restoration owed"],
+    ["netPayable", "Net payable"],
+  ] as const;
+  const metrics = definitions.map(([key, label]) => {
+    const amount = balance?.[key] ?? 0;
+    return {
+      key,
+      label,
+      amount,
+      formattedValue: formatPrice(amount, currency, locale),
+    };
+  });
+  const adjustments = (snapshot?.obligations.page ?? []).map((row) => ({
+    row,
+    source: [
+      row.sourceChargeId,
+      row.storeAccountId,
+      row.sourceInvoiceId,
+      row.paymentId,
+      row.lastRefundId,
+      row.disputeId,
+    ]
+      .filter(Boolean)
+      .join(" · "),
+    commission: formatPrice(row.originalCommission, row.currency, locale),
+    recovered: formatPrice(
+      row.recoveredAmount + (row.offsetAmount ?? 0) - (row.restoredAmount ?? 0),
+      row.currency,
+      locale,
+    ),
+    debt: formatPrice(row.debtAmount ?? 0, row.currency, locale),
+    status: row.needsReconciliation
+      ? "Operator reconciliation required"
+      : (row.lastState ?? "Settled"),
+  }));
+  const state: AffiliateRecoveryView = {
+    adjustments,
+    metrics,
+    rows: snapshot?.obligations.page ?? [],
+    currency,
+    isLoading: snapshot === undefined,
+    isComplete: snapshot?.obligations.isDone ?? false,
+    isPending: action.isPending,
+    error: action.error,
+    retry: action.run,
+  };
+  if (children) return <>{children(state)}</>;
+  return (
+    <section className={className} data-better-stripe="affiliate-recovery">
+      <h2>Commission recovery ({currency.toUpperCase()})</h2>
+      {state.isLoading ? (
+        <p role="status">Loading commission recovery…</p>
+      ) : snapshot === null ? (
+        <p>Sign in to view your commission recovery.</p>
+      ) : (
+        <>
+          {showMetrics && (
+            <dl>
+              {metrics.map((metric) => (
+                <div key={metric.key}>
+                  <dt>{metric.label}</dt>
+                  <dd>{metric.formattedValue}</dd>
+                </div>
+              ))}
+            </dl>
+          )}
+          {state.error && <p role="alert">{state.error}</p>}
+          {!state.rows.length && <p>No commission adjustments yet.</p>}
+          <table>
+            <caption>Commission adjustments</caption>
+            <thead>
+              <tr>
+                <th scope="col">Original sale</th>
+                <th scope="col">Commission</th>
+                <th scope="col">Recovered</th>
+                <th scope="col">Debt</th>
+                <th scope="col">State</th>
+                {(onRetry || onInspect) && <th scope="col">Action</th>}
+              </tr>
+            </thead>
+            <tbody>
+              {state.rows.map((row) => (
+                <tr key={row._id}>
+                  <td>
+                    {sourceHref?.(row) ? (
+                      <a href={sourceHref(row)}>{row.sourceChargeId}</a>
+                    ) : (
+                      row.sourceChargeId
+                    )}
+                    <br />
+                    {[
+                      row.storeAccountId,
+                      row.sourceInvoiceId,
+                      row.paymentId,
+                      row.lastRefundId,
+                      row.disputeId,
+                    ]
+                      .filter(Boolean)
+                      .join(" · ")}
+                  </td>
+                  <td>
+                    {formatPrice(row.originalCommission, row.currency, locale)}
+                  </td>
+                  <td>
+                    {formatPrice(
+                      row.recoveredAmount +
+                        (row.offsetAmount ?? 0) -
+                        (row.restoredAmount ?? 0),
+                      row.currency,
+                      locale,
+                    )}
+                  </td>
+                  <td>
+                    {formatPrice(row.debtAmount ?? 0, row.currency, locale)}
+                  </td>
+                  <td>
+                    {row.needsReconciliation
+                      ? "Operator reconciliation required"
+                      : (row.lastState ?? "Settled")}
+                    {row.lastError && <p>{row.lastError}</p>}
+                  </td>
+                  {(onRetry || onInspect) && (
+                    <td>
+                      {onInspect && (
+                        <button
+                          type="button"
+                          onClick={() => onInspect(row._id)}
+                        >
+                          Inspect attempts
+                        </button>
+                      )}
+                      {onRetry && (
+                        <button
+                          type="button"
+                          disabled={state.isPending}
+                          onClick={() => {
+                            void state.retry(row._id);
+                          }}
+                        >
+                          Reconcile
+                        </button>
+                      )}
+                    </td>
+                  )}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+          {!state.isComplete && (
+            <p>
+              More adjustments are available. Totals include the complete
+              account ledger.
+            </p>
+          )}
+        </>
+      )}
+    </section>
+  );
+}
+export function AffiliateRecoveryHistory({
+  operations,
+  currency,
+  locale,
+}: {
+  operations: AffiliateRecoveryOperation[];
+  currency: string;
+  locale?: string;
+}) {
+  return (
+    <table data-better-stripe="affiliate-recovery-history">
+      <caption>Recovery receipts and attempts</caption>
+      <thead>
+        <tr>
+          <th scope="col">Operation</th>
+          <th scope="col">Amount</th>
+          <th scope="col">Outcome</th>
+          <th scope="col">Receipt</th>
+        </tr>
+      </thead>
+      <tbody>
+        {operations.map((op) => (
+          <tr key={op._id}>
+            <td>
+              {op.kind} · {op.sourceEventId ?? op._id}
+            </td>
+            <td>{formatPrice(op.amount, currency, locale)}</td>
+            <td>
+              {op.state}
+              {op.error && <p>{op.error}</p>}
+            </td>
+            <td>{op.receiptId ?? "Unconfirmed"}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

package/src/react/workflows/index.ts

@@ -265,6 +265,15 @@ export type {
   AffiliatePayoutEditorState,
   AffiliatePayoutUpdate,
 } from "./AffiliatePayoutEditor.js";
+export {
+  AffiliateRecovery,
+  AffiliateRecoveryHistory,
+} from "./AffiliateRecovery.js";
+export type {
+  AffiliateRecoveryProps,
+  AffiliateRecoveryView,
+  RecoveryMetric,
+} from "./AffiliateRecovery.js";
 
 export { EvidenceUpload } from "./EvidenceUpload.js";
 export type { EvidenceUploadProps } from "./EvidenceUpload.js";

package/src/testing/affiliate-recovery.ts

@@ -0,0 +1,137 @@
+import type { AffiliateRecoverySnapshot } from "../client/affiliateRecovery.js";
+export type AffiliateRecoveryScenario = {
+  id: string;
+  label: string;
+  evidence: "simulated";
+  snapshot: AffiliateRecoverySnapshot;
+};
+/** Presentation fixtures only. These IDs are not Stripe or bank-payout receipts. */
+export function affiliateRecoveryScenarios(): AffiliateRecoveryScenario[] {
+  const cases = [
+    {
+      id: "one-time-refund",
+      label: "One-time full refund",
+      finalized: 1001,
+      recovered: 1001,
+    },
+    {
+      id: "invoice-refund",
+      label: "Recurring invoice refund",
+      finalized: 1001,
+      recovered: 1001,
+      invoice: "fixture_invoice_renewal",
+    },
+    {
+      id: "partial-refund",
+      label: "Partial refund and rounding",
+      finalized: 501,
+      recovered: 501,
+    },
+    {
+      id: "open-dispute",
+      label: "Open monetary dispute",
+      finalized: 0,
+      provisional: 1001,
+      recovered: 1001,
+    },
+    {
+      id: "lost-dispute",
+      label: "Lost dispute finalized",
+      finalized: 1001,
+      recovered: 1001,
+    },
+    {
+      id: "won-dispute",
+      label: "Won dispute restored",
+      finalized: 0,
+      recovered: 1001,
+      restored: 1001,
+    },
+    {
+      id: "overlap",
+      label: "Refund retained after dispute win",
+      finalized: 501,
+      recovered: 1001,
+      restored: 500,
+    },
+    {
+      id: "paid-out",
+      label: "Insufficient balance after external payout",
+      finalized: 1001,
+      recovered: 0,
+      state: "insufficient_balance",
+    },
+    {
+      id: "future-offset",
+      label: "Debt recovered from future commission",
+      finalized: 1001,
+      recovered: 0,
+      offset: 1001,
+    },
+    {
+      id: "unknown",
+      label: "Provider timeout awaiting receipt",
+      finalized: 1001,
+      recovered: 0,
+      reserved: 1001,
+      state: "unknown",
+    },
+  ];
+  return cases.map((c) => {
+    const recoveredAmount = c.recovered,
+      offsetAmount = c.offset ?? 0,
+      restoredAmount = c.restored ?? 0;
+    const debt = Math.max(
+      0,
+      c.finalized +
+        (c.provisional ?? 0) -
+        recoveredAmount -
+        offsetAmount +
+        restoredAmount,
+    );
+    const row = {
+      _id: `fixture_${c.id}`,
+      _creationTime: 0,
+      sourceChargeId: `fixture_charge_${c.id}`,
+      sourceInvoiceId: c.invoice,
+      paymentIntentId: "fixture_payment",
+      affiliateAccountId: "fixture_affiliate",
+      currency: "usd",
+      chargeAmount: 10000,
+      originalCommission: 1001,
+      refundedPrincipal: c.finalized ? 10000 : 0,
+      disputedPrincipal: c.provisional ? 10000 : 0,
+      lostPrincipal: 0,
+      finalizedAmount: c.finalized,
+      provisionalAmount: c.provisional ?? 0,
+      recoveredAmount,
+      offsetAmount,
+      restoredAmount,
+      reservedRecovery: c.reserved ?? 0,
+      debtAmount: debt,
+      creditAmount: 0,
+      needsReconciliation: false,
+      lastState: c.state ?? "succeeded",
+    } as AffiliateRecoverySnapshot["obligations"]["page"][number];
+    const snapshot = {
+      balance: {
+        _id: `fixture_balance_${c.id}`,
+        _creationTime: 0,
+        affiliateAccountId: "fixture_affiliate",
+        currency: "usd",
+        originalCommission: 1001,
+        recoveredAmount,
+        offsetAmount,
+        restoredAmount,
+        outstandingDebt: debt,
+        reservedRecovery: c.reserved ?? 0,
+        reservedRestoration: 0,
+        restorationDue: 0,
+        withheldAmount: offsetAmount,
+        netPayable: 0,
+      },
+      obligations: { page: [row], continueCursor: "", isDone: true },
+    } as AffiliateRecoverySnapshot;
+    return { id: c.id, label: c.label, evidence: "simulated", snapshot };
+  });
+}

package/src/testing/index.ts

@@ -11,3 +11,5 @@ export {
   mockAccountUpdated,
   mockInvoicePaid,
 } from "./mock-webhooks.js";
+export { affiliateRecoveryScenarios } from "./affiliate-recovery.js";
+export type { AffiliateRecoveryScenario } from "./affiliate-recovery.js";