@fantastic.dev/better-stripe 0.28.3 → 0.28.5

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

@@ -264,3 +264,93 @@ it("explains the deadline waiver without a minimum progress bar", () => {
   expect(screen.queryByRole("progressbar")).toBeNull();
   expect(screen.getByText("Combined payout minimum")).toBeTruthy();
 });
+
+it("shows expiry recovery after automatic schedule restoration without claiming disbursement", () => {
+  render(
+    <PayoutProgress
+      policy={{
+        ...policy,
+        mode: "stripe_managed",
+        thresholds: [],
+        holdingExpiry: {
+          deadline: policy.holdDeadline,
+          status: "balance_remaining",
+          observedAt: 1800000000000,
+          balances: [{ currency: "usd", available: 999, pending: 25 }],
+        },
+      }}
+      currency="usd"
+    />,
+  );
+  expect(screen.getByRole("status").textContent).toContain(
+    "does not confirm disbursement",
+  );
+  expect(screen.queryByText(/Stripe manages automatic payouts/)).toBeNull();
+  expect(screen.queryByRole("progressbar")).toBeNull();
+  expect(screen.getByText("$9.99")).toBeTruthy();
+  expect(screen.getByText("$0.25")).toBeTruthy();
+});
+it("keeps unavailable expiry balances unverified instead of showing fabricated zero", () => {
+  render(
+    <PayoutProgress
+      policy={{
+        ...policy,
+        mode: "stripe_managed",
+        holdingExpiry: { deadline: policy.holdDeadline, status: "unverified" },
+      }}
+      currency="usd"
+    />,
+  );
+  expect(screen.getByRole("status").textContent).toContain(
+    "verification is unavailable",
+  );
+  expect(screen.queryByText("$0.00")).toBeNull();
+});
+
+it("shows a previous Stripe rejection separately from informational eligibility", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      preview={{
+        ...preview,
+        status: "qualified",
+        reason: undefined,
+        amount: 999,
+        minimumWaived: true,
+        holdDeadline: policy.holdDeadline,
+      }}
+      currency="usd"
+      lastAttempt={{
+        currency: "usd",
+        status: "rejected",
+        reason: "balance_insufficient",
+        at: 1800000000000,
+      }}
+      nextAttemptAt={1800000300000}
+      timeZone="UTC"
+    />,
+  );
+  expect(
+    screen.getByText(
+      /Stripe rejected the payout because the available balance changed/,
+    ),
+  ).toBeTruthy();
+  expect(screen.getByText(/Next automatic attempt/)).toBeTruthy();
+});
+it("does not display an old paid result or stale retry time while a new check is running", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      preview={preview}
+      currency="usd"
+      lastAttempt={{
+        currency: "usd",
+        status: "running",
+        reason: "pending_claim",
+      }}
+      nextAttemptAt={1800000000000}
+    />,
+  );
+  expect(screen.getByText(/automatic payout check is running/)).toBeTruthy();
+  expect(screen.queryByText(/Next automatic attempt/)).toBeNull();
+});

package/src/react/workflows/PayoutProgress.tsx

@@ -1,4 +1,5 @@
 "use client";
+import { PayoutAttemptStatus } from "./PayoutAttemptStatus.js";
 import { useMemo } from "react";
 import {
   payoutProgressState,
@@ -28,7 +29,31 @@ export function PayoutProgress(props: PayoutProgressProps) {
     <section className={className} data-better-stripe="payout-progress">
       <h2>Automatic payout progress ({currency.toUpperCase()})</h2>
       <p role="status">{state.message}</p>
+      <PayoutAttemptStatus
+        attempt={state.lastAttempt}
+        locale={locale}
+        timeZone={timeZone}
+      />
       <p>Stripe enforces its payout floor; a numeric amount is unavailable.</p>
+      {state.recovery?.balances && (
+        <div>
+          <h3>Stripe balances at last expiry check</h3>
+          <p>
+            Provider balances are not a payable earnings assessment. Currencies
+            remain separate.
+          </p>
+          <dl>
+            {state.recovery.balances.map((balance) => (
+              <div key={balance.currency}>
+                <dt>{balance.currency.toUpperCase()} available</dt>
+                <dd>{balance.availableLabel}</dd>
+                <dt>{balance.currency.toUpperCase()} pending</dt>
+                <dd>{balance.pendingLabel}</dd>
+              </div>
+            ))}
+          </dl>
+        </div>
+      )}
       {state.progress && (
         <progress
           aria-label="Combined payout minimum"
@@ -102,7 +127,12 @@ export function PayoutProgress(props: PayoutProgressProps) {
       {state.holdDeadline !== null && (
         <p>Custom holding deadline: {date(state.holdDeadline)}</p>
       )}
-      {state.observedAt !== null && <p>Assessed: {date(state.observedAt)}</p>}
+      {state.observedAt !== null && (
+        <p>
+          {state.recovery ? "Last recovery check" : "Assessed"}:{" "}
+          {date(state.observedAt)}
+        </p>
+      )}
     </section>
   );
 }

package/src/react/workflows/index.ts

@@ -290,3 +290,9 @@ export type {
 
 export { EvidenceUpload } from "./EvidenceUpload.js";
 export type { EvidenceUploadProps } from "./EvidenceUpload.js";
+
+export { PayoutAttemptStatus } from "./PayoutAttemptStatus.js";
+export type {
+  PayoutAttemptStatusProps,
+  PayoutAttemptState,
+} from "./PayoutAttemptStatus.js";

package/src/react/workflows/payout-attempt-state.ts

@@ -0,0 +1,70 @@
+import type { PayoutAttempt } from "../../client/connect/payoutWorker.js";
+const messages: Record<string, string> = {
+  balance_insufficient:
+    "Stripe rejected the payout because the available balance changed. Remaining unpaid entitlement is preserved; any retry requires fresh balance verification.",
+  amount_too_small:
+    "Stripe rejected the payout below its supported minimum. A numeric provider floor is unavailable. Review payout settings promptly; holding limits still apply.",
+  worker_error:
+    "The automatic payout check could not complete. An uncertain outcome must be reconciled before another payout can be created.",
+  returned:
+    "The bank returned the payout. Returned funds will be assessed again when available.",
+  bank_destination_unavailable:
+    "Add or verify a supported payout bank account before the worker can retry.",
+  affiliate_recovery_pending:
+    "Commission recovery must settle before a new automatic payout can qualify.",
+  below_threshold:
+    "No payout was requested because the combined balance is below the application minimum.",
+  insufficient_available:
+    "No payout was requested because the supported available Stripe balance is insufficient.",
+  schedule_drift:
+    "Payout scheduling changed outside the application. Contact platform support to verify controls.",
+  snapshot_limit:
+    "History reconciliation is incomplete. No payout was requested from a partial balance.",
+  policy_inactive:
+    "The application-managed payout policy is inactive. No new application payout was requested.",
+};
+export type PayoutAttemptState = PayoutAttempt & {
+  message: string;
+  tone: "warning" | "neutral" | "success";
+  formattedAt?: string;
+  timeLabel?: string;
+};
+export function payoutAttemptState(
+  attempt: PayoutAttempt | null | undefined,
+  locale = "en-US",
+  timeZone?: string,
+): PayoutAttemptState | undefined {
+  if (!attempt) return undefined;
+  const message =
+    attempt.status === "running"
+      ? "An automatic payout check is running. Its outcome is not verified yet."
+      : attempt.status === "reconciling"
+        ? "The payout outcome needs verification. The same operation will be reconciled before any new payout."
+        : attempt.status === "paid"
+          ? "The latest application payout was verified as paid by Stripe."
+          : (messages[attempt.reason] ??
+            "The latest automatic payout check did not complete. Review account settings or contact platform support.");
+  return {
+    ...attempt,
+    message,
+    tone:
+      attempt.status === "paid"
+        ? "success"
+        : ["rejected", "failed", "reconciling"].includes(attempt.status)
+          ? "warning"
+          : "neutral",
+    ...(attempt.at === undefined
+      ? {}
+      : {
+          formattedAt: new Intl.DateTimeFormat(locale, {
+            dateStyle: "medium",
+            timeStyle: "short",
+            timeZone,
+          }).format(attempt.at),
+          timeLabel:
+            attempt.status === "running"
+              ? "Attempt started"
+              : "Result recorded",
+        }),
+  };
+}

package/src/react/workflows/payout-progress-state.ts

@@ -1,3 +1,8 @@
+import {
+  payoutAttemptState,
+  type PayoutAttemptState,
+} from "./payout-attempt-state.js";
+import type { PayoutAttempt } from "../../client/connect/payoutWorker.js";
 import type { ReactNode } from "react";
 import type { PayoutPolicy, PayoutPreview } from "../../client/payoutPolicy.js";
 import { formatPrice } from "../lib/price-helpers.js";
@@ -42,13 +47,28 @@ export type PayoutProgressState = {
   nextAttemptAt: number | null;
   holdDeadline: number | null;
   observedAt: number | null;
+  lastAttempt?: PayoutAttemptState;
+  recovery?: {
+    status: NonNullable<PayoutPolicy["holdingExpiry"]>["status"];
+    balances?: {
+      currency: string;
+      available: number;
+      pending: number;
+      availableLabel: string;
+      pendingLabel: string;
+    }[];
+  };
 };
 export type PayoutProgressProps = {
   policy:
-    | Pick<PayoutPolicy, "mode" | "status" | "thresholds" | "holdDeadline">
+    | Pick<
+        PayoutPolicy,
+        "mode" | "status" | "thresholds" | "holdDeadline" | "holdingExpiry"
+      >
     | null
     | undefined;
   preview?: PayoutPreview | null;
+  lastAttempt?: PayoutAttempt | null;
   currency: string;
   /** Application worker attempt time, never a bank arrival estimate. */
   nextAttemptAt?: number | null;
@@ -83,8 +103,14 @@ export function payoutProgressState({
   preview,
   currency,
   nextAttemptAt,
+  lastAttempt,
+  timeZone,
   locale = "en-US",
 }: PayoutProgressProps): PayoutProgressState {
+  if (lastAttempt && lastAttempt.currency !== currency)
+    throw new Error(
+      "Payout attempt currency does not match the selected currency.",
+    );
   const amount = (value: number) => formatPrice(value, currency, locale);
   const state: PayoutProgressState = {
     status: "loading",
@@ -98,18 +124,52 @@ export function payoutProgressState({
     holdDeadline:
       policy?.mode === "custom" ? (policy.holdDeadline ?? null) : null,
     observedAt: null,
+    lastAttempt:
+      policy === undefined
+        ? undefined
+        : payoutAttemptState(lastAttempt, locale, timeZone),
   };
   if (policy !== undefined) {
     if (policy?.status === "changing") {
       state.status = "changing";
       state.message =
         "Payout settings are being verified. Eligibility is unavailable until the change completes.";
+    } else if (
+      policy?.holdingExpiry &&
+      policy.holdingExpiry.status !== "no_held_balance"
+    ) {
+      const expiry = policy.holdingExpiry;
+      state.status = "unavailable";
+      state.reason = "holding_expiry_unresolved";
+      state.holdDeadline = expiry.deadline;
+      state.observedAt = expiry.observedAt ?? null;
+      state.message =
+        "The holding deadline has passed. Schedule restoration does not confirm disbursement. " +
+        (expiry.status === "unverified"
+          ? "Stripe balance verification is unavailable. "
+          : "Stripe balances or payout claims still require recovery. ") +
+        "Contact platform support; automatic recovery checks will retry.";
+      state.recovery = {
+        status: expiry.status,
+        ...(expiry.balances
+          ? {
+              balances: expiry.balances.map((b) => ({
+                ...b,
+                availableLabel: formatPrice(b.available, b.currency, locale),
+                pendingLabel: formatPrice(b.pending, b.currency, locale),
+              })),
+            }
+          : {}),
+      };
     } else if (!policy || policy.mode === "stripe_managed") {
       state.status = "stripe_managed";
       state.message =
         "Stripe manages automatic payouts. No additional application minimum is set.";
     } else if (preview !== undefined) {
-      state.nextAttemptAt = nextAttemptAt ?? null;
+      state.nextAttemptAt =
+        state.lastAttempt?.status === "running"
+          ? null
+          : (nextAttemptAt ?? null);
       if (!preview || !("currency" in preview)) {
         state.status = "unavailable";
         state.reason = preview?.reason ?? "assessment_unavailable";