@fantastic.dev/better-stripe 0.26.0 → 0.27.0

package/dist/react/workflows/payout-progress-state.js

@@ -0,0 +1,93 @@
+import { formatPrice } from "../lib/price-helpers.js";
+const reasons = {
+    below_threshold: "Below-minimum funds remain owed and carry forward to a later automatic attempt.",
+    insufficient_available: "Qualifying earnings meet the minimum, but the supported Stripe payout balance is insufficient.",
+    affiliate_recovery_pending: "Commission recovery must settle before a new automatic payout can qualify.",
+    unallocated_history: "Previous Stripe activity needs reconciliation before unpaid entitlement can be assessed.",
+    pending_claim: "An existing payout is being reconciled before another payout can qualify.",
+    payout_unidentified: "A previous payout outcome needs reconciliation. No replacement payout will be created blindly.",
+    observations_stale: "Provider observations expired. Refresh the assessment.",
+    snapshot_limit: "This account needs continued history reconciliation before eligibility can be assessed.",
+    policy_changed: "Payout settings changed. Refresh the assessment.",
+};
+export function payoutProgressState({ policy, preview, currency, nextAttemptAt, locale = "en-US", }) {
+    const amount = (value) => formatPrice(value, currency, locale);
+    const state = {
+        status: "loading",
+        currency,
+        reason: null,
+        message: "Loading payout eligibility…",
+        metrics: [],
+        sources: [],
+        progress: null,
+        nextAttemptAt: null,
+        holdDeadline: policy?.mode === "custom" ? (policy.holdDeadline ?? null) : null,
+        observedAt: null,
+    };
+    if (policy !== undefined) {
+        if (!policy || policy.mode === "stripe_managed") {
+            state.status = "stripe_managed";
+            state.message =
+                "Stripe manages automatic payouts. No additional application minimum is set.";
+        }
+        else if (policy.status === "changing") {
+            state.status = "changing";
+            state.message =
+                "Payout settings are being verified. Eligibility is unavailable until the change completes.";
+        }
+        else if (preview !== undefined) {
+            state.nextAttemptAt = nextAttemptAt ?? null;
+            if (!preview || !("currency" in preview)) {
+                state.status = "unavailable";
+                state.reason = preview?.reason ?? "assessment_unavailable";
+                state.message =
+                    reasons[state.reason] ??
+                        "Automatic payout eligibility is unavailable. Refresh or contact support.";
+            }
+            else {
+                const configured = policy.thresholds.find((t) => t.currency === currency);
+                if (preview.currency !== currency ||
+                    !configured ||
+                    configured.amount !== preview.threshold)
+                    throw new Error("Payout progress currency or policy does not match the assessment.");
+                state.status = "assessed";
+                state.reason = preview.reason ?? null;
+                state.message =
+                    preview.status === "qualified"
+                        ? "The combined balance qualified at the assessment time. The automatic worker will verify it again before any payout."
+                        : (reasons[preview.reason ?? ""] ??
+                            "Automatic payout is on hold. Refresh or contact support.");
+                state.observedAt = preview.observedAt;
+                state.progress = {
+                    value: Math.max(0, Math.min(preview.threshold, preview.matureUnpaid)),
+                    max: preview.threshold,
+                };
+                const definitions = [
+                    ["qualifying", "Combined qualifying balance", preview.matureUnpaid],
+                    ["pending", "Pending settlement", preview.pendingCredits],
+                    ["minimum", "Combined payout minimum", preview.threshold],
+                    ["eligible", "Eligible at assessment", preview.amount],
+                    ["fees", "Confirmed payout costs", preview.confirmedFees],
+                    [
+                        "liabilities",
+                        "Other outstanding obligations",
+                        preview.independentLiabilities,
+                    ],
+                ];
+                state.metrics = definitions.map(([key, label, value]) => ({
+                    key,
+                    label,
+                    amount: value,
+                    formattedValue: amount(value),
+                }));
+                state.sources = preview.sources.map((source) => ({
+                    ...source,
+                    matureLabel: amount(source.matureUnpaid),
+                    pendingLabel: amount(source.pendingCredits),
+                }));
+            }
+        }
+    }
+    return state;
+}
+//# sourceMappingURL=payout-progress-state.js.map

package/dist/react/workflows/payout-progress-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payout-progress-state.js","sourceRoot":"","sources":["../../../src/react/workflows/payout-progress-state.ts"],"names":[],"mappings":"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"}

package/docs/react-workflows-audit.md

@@ -16,7 +16,7 @@ uses render props or companion hooks to apply shadcn styling.
 | Customer invoices                         | `Invoices`                                                                                                                                             |
 | Customer payment methods                  | `usePaymentMethodsManager`, `PaymentMethods`, `PaymentMethodsList`, `AddCardForm`, Stripe providers                                                    |
 | Seller overview                           | `PayoutOverview`, `AccountCreateCard`, `ConnectStatusBadge`                                                                                            |
-| Seller and affiliate payouts              | `Payouts`, `PayoutHistory`, live balances, upcoming date, history and pagination                                                                       |
+| Seller and affiliate payouts              | `Payouts`, `PayoutHistory`, `PayoutProgress`, `PayoutSettings`, live balances, upcoming date, history and pagination                                   |
 | Seller earnings                           | `EarningsSummary`, `PayoutSchedule`, `PayoutHistory`, `earningsFromBalance`, `useWorkflowResource`                                                     |
 | Seller sales                              | `Sales`                                                                                                                                                |
 | Seller subscriptions                      | `Subscriptions`, `SubscriptionCard`                                                                                                                    |

package/docs/react-workflows.md

@@ -640,6 +640,87 @@ Consumer applications still need to verify their own authenticated adapters and
 See [sandbox setup findings](accounts-v2-preview.md#connect-sandbox-setup-findings-2026-10-15)
 for the account eligibility requirement.
 
+## Combined automatic payout progress
+
+`PayoutProgress` is an unstyled, read-only view of a custom recipient's combined
+eligibility assessment. Load the policy and
+[preview](settlement.md#payout-eligibility-preview) through an authorized server
+adapter. Derive independent liabilities on the server. Read the worker's next
+attempt separately from the provider's actual bank arrival dates.
+
+```tsx
+import { PayoutProgress } from "@fantastic.dev/better-stripe/react";
+
+<PayoutProgress
+  policy={policy}
+  preview={preview}
+  currency="usd"
+  nextAttemptAt={job?.nextAttemptAt}
+  locale="en-US"
+  timeZone="UTC"
+/>;
+```
+
+The default markup uses a single accessible progress indicator, financial
+metrics, source contributions and assessment/attempt/deadline dates. Store and
+affiliate contributions share one minimum. Pending credits are separate, shared
+costs reduce the combined entitlement once, and negative entitlement remains
+visible even though the visual progress indicator stops at zero. A qualified
+assessment is informational; the automatic worker verifies it again before a
+payout. The component has no withdrawal action.
+
+`policy={undefined}` means loading. A null policy or `stripe_managed` mode shows
+Stripe-managed defaults without inventing a numeric provider floor. Changing
+policies suppress prior financial progress. For a ready custom policy, an
+undefined preview means loading; a null or minimal held preview shows an
+unavailable assessment rather than fabricated zero balances. A mismatched
+currency or configured minimum rejects the display.
+
+Use the `children` render prop for translated labels and application cards. It
+receives `status`, `reason`, `metrics`, `sources`, `progress`, `observedAt`,
+`nextAttemptAt` and `holdDeadline`. Metrics include stable keys and raw minor-unit
+amounts as well as formatted values. Render props use the same state calculation
+as the native markup; replace the English message with your own translated copy
+selected by `status` and `reason`.
+
+Scope and refresh the host data when the recipient or settlement currency
+changes. Keep currencies separate. This display does not configure policies,
+install a scheduler or bypass the release API's capability/history limits.
+
+## Payout settings
+
+`PayoutSettings` and `usePayoutSettings` own minimum entry, explicit custom-hold
+consent, loading/error states and callback locking. They never create a payout.
+`onSave` receives `{ currency, mode, expectedRevision, minimum?, consent }`.
+The minimum uses ordinary Stripe currency units. No provider floor is guessed.
+The host must derive the authenticated account/owner, preserve the policy's
+other currency minimums, and call `payoutPolicy.prepare` and `apply` with a
+stable immutable operation identity. Return `{ status, reason? }`; supported
+statuses are `ready`, `unsupported`, `migration_required`, `schedule_drift` and
+`canceled`.
+
+When a provider outcome is unknown, refresh the policy instead of inventing
+success or creating a new operation. `onRetry` resumes the server's stored
+pending operation; the installed recurring job also resumes it. The editor
+locks changes while `policy.status` is `changing`. Render props expose the same
+state for translated forms and design-system controls.
+
+The example's `recipientPayoutPolicy` actions bind the demo user to its account
+server-side and derive uncollected seller costs through the same query as the
+worker. They preserve other currencies, replay stored changes without rolling
+back newer settings, and restore the original schedule on opt-out. The public
+`payoutPreviewValidator` lets the host validate the package assessment without
+copying its return schema. Production apps must replace demo persona selection
+with authenticated ownership; the demo is not evidence of production auth.
+
+Custom schedules affect the entire recipient account. Configure each settlement
+currency. Choosing Stripe-managed mode restores the original schedule for all
+currencies and removes application minimums. Funded accounts needing historical
+adoption show `migration_required`; this form does not guess their source
+allocations or automatically adopt unallocated money. Install worker recovery
+and deadline-expiry jobs before exposing activation, and use the reset guard
+described in the [settlement guide](settlement.md#development-reset-safeguards).
+
 ## Component history and currency summaries
 
 See the [read contract guide](read-contracts.md) for reactive product, price and payout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",

package/src/client/payoutPolicy.test.ts

@@ -126,6 +126,19 @@ it("persists original provider settings, verifies manual schedule and restores o
   });
   expect((await client.get(ctx, scope))!.mode).toBe("stripe_managed");
 });
+it("replays equivalent threshold objects regardless of transport property order", async () => {
+  const { client, ctx, provider } = await setup();
+  expect((await client.prepare(ctx, options)).status).toBe("prepared");
+  expect(
+    (
+      await client.prepare(ctx, {
+        ...options,
+        thresholds: [{ amount: 1000, currency: "usd" }],
+      })
+    ).status,
+  ).toBe("prepared");
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+});
 it("recovers provider success after a failed persistence write without changing the request", async () => {
   const { client, ctx, provider } = await setup();
   await client.prepare(ctx, options);

package/src/client/payoutPolicy.ts

@@ -3,6 +3,7 @@ import {
   type PayoutPreviewOptions,
 } from "./connect/payoutPreview.js";
 export type * from "./connect/payoutPreview.js";
+export { previewResult as payoutPreviewValidator } from "../component/payoutRelease/preview.js";
 import { PayoutWorkerClient } from "./connect/payoutWorker.js";
 export type * from "./connect/payoutWorker.js";
 import {
@@ -312,7 +313,10 @@ export class PayoutPolicyClient {
       if (
         prior.mode !== opts.mode ||
         prior.expectedRevision !== opts.expectedRevision ||
-        !equal(prior.thresholds, thresholds) ||
+        !equal(
+          canonicalThresholds(prior.thresholds, prior.mode === "custom"),
+          thresholds,
+        ) ||
         Boolean(prior.adoption) !== Boolean(opts.adoptExistingBalance)
       )
         throw new Error("Payout policy operation identity cannot be reused.");

package/src/component/payoutPolicy/helpers.ts

@@ -55,7 +55,9 @@ export function canonicalThresholds(
     )
   )
     throw new Error("Invalid custom payout thresholds.");
-  return [...values].sort((a, b) => a.currency.localeCompare(b.currency));
+  return values
+    .map(({ currency, amount }) => ({ currency, amount }))
+    .sort((a, b) => a.currency.localeCompare(b.currency));
 }
 export function validateScope(scope: { accountId: string; ownerKey: string }) {
   if (

package/src/component/payoutPolicy/mutations.ts

@@ -52,7 +52,10 @@ export const prepare = mutation({
         old.country !== args.country ||
         old.observedAt !== args.observedAt ||
         Boolean(old.adoption) !== Boolean(args.adoption) ||
-        !same(old.thresholds, args.thresholds) ||
+        !same(
+          canonicalThresholds(old.thresholds, old.mode === "custom"),
+          args.thresholds,
+        ) ||
         !same(old.observedSchedule, args.observedSchedule)
       )
         throw new Error("Payout policy operation identity cannot be reused.");

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

@@ -0,0 +1,169 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import type { PayoutPreview } from "../../client/payoutPolicy.js";
+import { PayoutProgress } from "./PayoutProgress.js";
+afterEach(cleanup);
+const policy = {
+  mode: "custom" as const,
+  status: "ready" as const,
+  thresholds: [{ currency: "usd", amount: 1000 }],
+  holdDeadline: 1900000000000,
+};
+const preview: PayoutPreview = {
+  status: "held",
+  reason: "below_threshold",
+  amount: 0,
+  currency: "usd",
+  threshold: 1000,
+  providerMinimum: null,
+  matureUnpaid: 999,
+  pendingCredits: 200,
+  confirmedFees: 0,
+  independentLiabilities: 0,
+  providerAvailable: 999,
+  observedAt: 1800000000000,
+  sources: [
+    { role: "store", matureUnpaid: 599, pendingCredits: 200 },
+    { role: "affiliate", matureUnpaid: 400, pendingCredits: 0 },
+    { role: "other", matureUnpaid: 0, pendingCredits: 0 },
+  ],
+};
+it("shows one combined minimum, pending settlement and source contributions", () => {
+  render(<PayoutProgress policy={policy} preview={preview} currency="usd" />);
+  expect(screen.getByRole("progressbar").getAttribute("max")).toBe("1000");
+  expect(screen.getByRole("progressbar").getAttribute("value")).toBe("999");
+  expect(screen.getByText("$9.99")).toBeTruthy();
+  expect(screen.getByText("$5.99")).toBeTruthy();
+  expect(screen.getByText("$4.00")).toBeTruthy();
+  expect(screen.getByText(/Below-minimum funds remain owed/)).toBeTruthy();
+  expect(
+    screen.queryByRole("button", { name: /withdraw|pay out/i }),
+  ).toBeNull();
+});
+it("does not invent zero balances or progress for an unavailable assessment", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      currency="usd"
+      preview={{
+        status: "held",
+        reason: "unallocated_history",
+        amount: 0,
+      }}
+    />,
+  );
+  expect(screen.getByRole("status").textContent).toContain("reconciliation");
+  expect(screen.queryByRole("progressbar")).toBeNull();
+  expect(screen.queryByText("$0.00")).toBeNull();
+});
+it("keeps Stripe-managed defaults distinct from a custom application minimum", () => {
+  render(<PayoutProgress policy={null} currency="usd" />);
+  expect(screen.getByRole("status").textContent).toContain("Stripe manages");
+  expect(screen.getByText(/numeric amount is unavailable/)).toBeTruthy();
+  expect(screen.queryByRole("progressbar")).toBeNull();
+  expect(screen.queryByText("$1.00")).toBeNull();
+});
+it("does not reuse a prior assessment while the schedule change is pending", () => {
+  render(
+    <PayoutProgress
+      policy={{ ...policy, status: "changing" }}
+      preview={preview}
+      currency="usd"
+    />,
+  );
+  expect(screen.getByRole("status").textContent).toContain("being verified");
+  expect(screen.queryByRole("progressbar")).toBeNull();
+});
+it("preserves negative entitlement while clamping only the visual progress", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      preview={{ ...preview, matureUnpaid: -100 }}
+      currency="usd"
+    />,
+  );
+  expect(screen.getByText("-$1.00")).toBeTruthy();
+  expect(screen.getByRole("progressbar").getAttribute("value")).toBe("0");
+});
+it("distinguishes the next worker attempt from a bank arrival date", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      preview={preview}
+      currency="usd"
+      nextAttemptAt={1800000000000}
+      timeZone="UTC"
+    />,
+  );
+  expect(screen.getByText(/Next automatic attempt:/).textContent).toContain(
+    "not a bank arrival date",
+  );
+  expect(screen.getByText(/Custom holding deadline:/)).toBeTruthy();
+});
+it("rejects another currency or changed threshold instead of displaying mixed progress", () => {
+  expect(() =>
+    render(<PayoutProgress policy={policy} preview={preview} currency="eur" />),
+  ).toThrow("does not match");
+  expect(() =>
+    render(
+      <PayoutProgress
+        policy={{ ...policy, thresholds: [{ currency: "usd", amount: 2000 }] }}
+        preview={preview}
+        currency="usd"
+      />,
+    ),
+  ).toThrow("does not match");
+});
+it("exposes the same financial state for translated host cards", () => {
+  render(
+    <PayoutProgress policy={policy} preview={preview} currency="usd">
+      {(state) => (
+        <article data-testid="custom">
+          {state.status}{" "}
+          {
+            state.metrics.find((metric) => metric.key === "qualifying")
+              ?.formattedValue
+          }
+        </article>
+      )}
+    </PayoutProgress>,
+  );
+  expect(screen.getByTestId("custom").textContent).toBe("assessed $9.99");
+  expect(screen.queryByText("Source contributions")).toBeNull();
+});
+it.each([1000, 1100])(
+  "shows a qualifying combined assessment at %i without separate category minimums",
+  (total) => {
+    render(
+      <PayoutProgress
+        policy={policy}
+        currency="usd"
+        preview={{
+          ...preview,
+          status: "qualified",
+          reason: undefined,
+          amount: total,
+          matureUnpaid: total,
+          sources: [
+            { role: "store", matureUnpaid: total - 400, pendingCredits: 0 },
+            { role: "affiliate", matureUnpaid: 400, pendingCredits: 0 },
+          ],
+        }}
+      />,
+    );
+    expect(screen.getByRole("status").textContent).toContain("qualif");
+    expect(screen.getAllByRole("progressbar")).toHaveLength(1);
+    expect(screen.getByRole("progressbar").getAttribute("value")).toBe("1000");
+  },
+);
+it("does not display a former custom holding deadline for Stripe-managed payouts", () => {
+  render(
+    <PayoutProgress
+      policy={{ ...policy, mode: "stripe_managed" }}
+      currency="usd"
+      preview={preview}
+    />,
+  );
+  expect(screen.queryByText(/Custom holding deadline:/)).toBeNull();
+});

package/src/react/workflows/PayoutProgress.tsx

@@ -0,0 +1,94 @@
+"use client";
+import { useMemo } from "react";
+import {
+  payoutProgressState,
+  type PayoutProgressProps,
+} from "./payout-progress-state.js";
+export type {
+  PayoutProgressMetric,
+  PayoutProgressProps,
+  PayoutProgressState,
+} from "./payout-progress-state.js";
+/** Unstyled, read-only progress. A preview never authorizes or requests a payout. */
+export function PayoutProgress(props: PayoutProgressProps) {
+  const { currency, locale = "en-US", timeZone, className, children } = props;
+  const state = payoutProgressState(props);
+  const formatter = useMemo(
+    () =>
+      new Intl.DateTimeFormat(locale, {
+        dateStyle: "medium",
+        timeStyle: "short",
+        timeZone,
+      }),
+    [locale, timeZone],
+  );
+  if (children) return <>{children(state)}</>;
+  const date = (value: number) => formatter.format(value);
+  return (
+    <section className={className} data-better-stripe="payout-progress">
+      <h2>Automatic payout progress ({currency.toUpperCase()})</h2>
+      <p role="status">{state.message}</p>
+      <p>Stripe enforces its payout floor; a numeric amount is unavailable.</p>
+      {state.progress && (
+        <progress
+          aria-label="Combined payout minimum"
+          value={state.progress.value}
+          max={state.progress.max}
+        />
+      )}
+      {state.metrics.length > 0 && (
+        <dl>
+          {state.metrics.map((metric) => (
+            <div key={metric.key}>
+              <dt>{metric.label}</dt>
+              <dd>{metric.formattedValue}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+      {state.sources.length > 0 && (
+        <>
+          <p>
+            All categories contribute to one minimum. Source amounts are before
+            shared costs and obligations. Pending funds do not qualify.
+          </p>
+          <table>
+            <caption>Source contributions</caption>
+            <thead>
+              <tr>
+                <th scope="col">Source</th>
+                <th scope="col">Mature unpaid</th>
+                <th scope="col">Pending settlement</th>
+              </tr>
+            </thead>
+            <tbody>
+              {state.sources.map((source) => (
+                <tr key={source.role}>
+                  <th scope="row">
+                    {source.role === "store"
+                      ? "Store"
+                      : source.role === "affiliate"
+                        ? "Affiliate"
+                        : "Other"}
+                  </th>
+                  <td>{source.matureLabel}</td>
+                  <td>{source.pendingLabel}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </>
+      )}
+      {state.nextAttemptAt !== null && (
+        <p>
+          Next automatic attempt: {date(state.nextAttemptAt)}. This is not a
+          bank arrival date.
+        </p>
+      )}
+      {state.holdDeadline !== null && (
+        <p>Custom holding deadline: {date(state.holdDeadline)}</p>
+      )}
+      {state.observedAt !== null && <p>Assessed: {date(state.observedAt)}</p>}
+    </section>
+  );
+}