@fantastic.dev/better-stripe 0.26.0 → 0.28.0

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

@@ -0,0 +1,139 @@
+// @vitest-environment jsdom
+import "@testing-library/jest-dom/vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { PayoutSettings } from "./PayoutSettings.js";
+afterEach(cleanup);
+it("requires explicit consent and sends a precise combined minimum to the host callback", async () => {
+  const onSave = vi.fn().mockResolvedValue({ status: "ready" });
+  render(
+    <PayoutSettings
+      scopeKey="recipient"
+      currency="usd"
+      policy={null}
+      onSave={onSave}
+    />,
+  );
+  await userEvent.selectOptions(screen.getByRole("combobox"), "custom");
+  await userEvent.type(
+    screen.getByRole("textbox", { name: /Minimum/ }),
+    "10.25",
+  );
+  expect(
+    screen.getByRole("button", { name: "Save payout settings" }),
+  ).toBeDisabled();
+  await userEvent.click(screen.getByRole("checkbox"));
+  await userEvent.click(
+    screen.getByRole("button", { name: "Save payout settings" }),
+  );
+  await waitFor(() =>
+    expect(onSave).toHaveBeenCalledWith({
+      currency: "usd",
+      mode: "custom",
+      expectedRevision: -1,
+      minimum: 1025,
+      consent: true,
+    }),
+  );
+  expect(await screen.findByText("Payout settings verified.")).toBeTruthy();
+});
+it("opts out account-wide without requiring custom consent or a numeric minimum", async () => {
+  const onSave = vi.fn().mockResolvedValue({ status: "ready" });
+  render(
+    <PayoutSettings
+      scopeKey="recipient"
+      currency="usd"
+      policy={{
+        mode: "custom",
+        status: "ready",
+        revision: 2,
+        thresholds: [{ currency: "usd", amount: 1000 }],
+      }}
+      onSave={onSave}
+    />,
+  );
+  await userEvent.selectOptions(screen.getByRole("combobox"), "stripe_managed");
+  await userEvent.click(
+    screen.getByRole("button", { name: "Save payout settings" }),
+  );
+  await waitFor(() =>
+    expect(onSave).toHaveBeenCalledWith({
+      currency: "usd",
+      mode: "stripe_managed",
+      expectedRevision: 2,
+      consent: false,
+    }),
+  );
+});
+it("shows a migration limitation without pretending settings were saved", async () => {
+  render(
+    <PayoutSettings
+      scopeKey="recipient"
+      currency="usd"
+      policy={null}
+      onSave={async () => ({
+        status: "migration_required",
+        reason: "existing_balance",
+      })}
+    />,
+  );
+  await userEvent.selectOptions(screen.getByRole("combobox"), "custom");
+  await userEvent.type(screen.getByRole("textbox"), "10");
+  await userEvent.click(screen.getByRole("checkbox"));
+  await userEvent.click(
+    screen.getByRole("button", { name: "Save payout settings" }),
+  );
+  expect((await screen.findByRole("status")).textContent).toContain(
+    "reconciliation",
+  );
+  expect(screen.queryByText("Payout settings verified.")).toBeNull();
+});
+it("locks edits during a pending schedule operation and retries the host's persisted operation", async () => {
+  const onRetry = vi.fn().mockResolvedValue({ status: "ready" });
+  const onSave = vi.fn();
+  render(
+    <PayoutSettings
+      scopeKey="recipient"
+      currency="usd"
+      policy={{
+        mode: "custom",
+        status: "changing",
+        revision: 1,
+        thresholds: [{ currency: "usd", amount: 1000 }],
+      }}
+      onSave={onSave}
+      onRetry={onRetry}
+    />,
+  );
+  expect(screen.getByRole("combobox")).toBeDisabled();
+  expect(
+    screen.getByRole("button", { name: "Save payout settings" }),
+  ).toBeDisabled();
+  await userEvent.click(
+    screen.getByRole("button", { name: "Retry settings verification" }),
+  );
+  await waitFor(() => expect(onRetry).toHaveBeenCalledTimes(1));
+  expect(onSave).not.toHaveBeenCalled();
+});
+it.each(["0", "10.001", "-2", "1e3", "10,20"])(
+  "does not round or submit invalid USD minimum %s",
+  async (value) => {
+    const onSave = vi.fn();
+    render(
+      <PayoutSettings
+        scopeKey="recipient"
+        currency="usd"
+        policy={null}
+        onSave={onSave}
+      />,
+    );
+    await userEvent.selectOptions(screen.getByRole("combobox"), "custom");
+    await userEvent.type(screen.getByRole("textbox"), value);
+    await userEvent.click(screen.getByRole("checkbox"));
+    expect(
+      screen.getByRole("button", { name: "Save payout settings" }),
+    ).toBeDisabled();
+    expect(onSave).not.toHaveBeenCalled();
+  },
+);

package/src/react/workflows/PayoutSettings.tsx

@@ -0,0 +1,209 @@
+"use client";
+import { useId, useState, type ReactNode } from "react";
+import type { PayoutPolicy } from "../../client/payoutPolicy.js";
+import {
+  chargeAmountToDecimal,
+  parseChargeAmount,
+} from "../../client/charge-currency.js";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type PayoutSettingsChange = {
+  currency: string;
+  mode: "custom" | "stripe_managed";
+  expectedRevision: number;
+  minimum?: number;
+  consent: boolean;
+};
+export type PayoutSettingsResult = {
+  status:
+    | "ready"
+    | "unsupported"
+    | "migration_required"
+    | "schedule_drift"
+    | "canceled";
+  reason?: string;
+};
+export type PayoutSettingsProps = {
+  scopeKey: string;
+  currency: string;
+  policy:
+    | Pick<PayoutPolicy, "mode" | "status" | "revision" | "thresholds">
+    | null
+    | undefined;
+  onSave: (change: PayoutSettingsChange) => Promise<PayoutSettingsResult>;
+  onRetry?: () => Promise<PayoutSettingsResult>;
+  children?: (state: PayoutSettingsState) => ReactNode;
+};
+export type PayoutSettingsState = {
+  inputId: string;
+  currency: string;
+  mode: "custom" | "stripe_managed";
+  setMode: (mode: "custom" | "stripe_managed") => void;
+  minimum: string;
+  setMinimum: (minimum: string) => void;
+  consent: boolean;
+  setConsent: (consent: boolean) => void;
+  isLoading: boolean;
+  isChanging: boolean;
+  isPending: boolean;
+  canSave: boolean;
+  error: string | null;
+  message: string | null;
+  save: () => Promise<unknown>;
+  retry: () => Promise<unknown>;
+};
+const messages: Record<PayoutSettingsResult["status"], string> = {
+  ready: "Payout settings verified.",
+  migration_required:
+    "Existing funds or payouts need reconciliation before this schedule can change.",
+  unsupported:
+    "Custom payout scheduling is unavailable for this account. Review the current policy and Stripe schedule.",
+  schedule_drift:
+    "The Stripe payout schedule changed. Reconciliation is required before this operation can complete.",
+  canceled:
+    "The settings change was canceled. Refresh to view the current payout policy.",
+};
+/** Host callbacks authorize ownership and persist immutable schedule operations. */
+export function usePayoutSettings(
+  props: PayoutSettingsProps,
+): PayoutSettingsState {
+  const inputId = useId();
+  const scope = `${props.scopeKey}:${props.currency}:${props.policy?.revision ?? -1}:${props.policy?.status ?? "default"}`;
+  const configured = props.policy?.thresholds.find(
+    (t) => t.currency === props.currency,
+  );
+  const initial = {
+    scope,
+    mode: props.policy?.mode ?? ("stripe_managed" as const),
+    minimum: configured
+      ? (chargeAmountToDecimal(configured.amount, props.currency) ?? "")
+      : "",
+    consent: false,
+  };
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== scope) setFields(initial);
+  const isLoading = props.policy === undefined;
+  const isChanging = props.policy?.status === "changing";
+  // This only parses ordinary currency units; provider capability/floor checks stay on the server.
+  const minimum = parseChargeAmount(fields.minimum.trim(), props.currency);
+  const valid =
+    fields.mode === "stripe_managed" ||
+    (minimum !== null && minimum > 0 && fields.consent);
+  const action = useWorkflowAction(async (retry: boolean) => {
+    if (retry) {
+      if (!props.onRetry) throw new Error("Settings retry is unavailable.");
+      return props.onRetry();
+    }
+    if (isLoading || isChanging || !valid)
+      throw new Error(
+        "Enter a positive minimum and consent to custom scheduling before saving.",
+      );
+    return props.onSave({
+      currency: props.currency,
+      expectedRevision: props.policy?.revision ?? -1,
+      mode: fields.mode,
+      ...(fields.mode === "custom" ? { minimum: minimum! } : {}),
+      consent: fields.mode === "custom" && fields.consent,
+    });
+  }, scope);
+  const update = (values: Partial<typeof fields>) => {
+    action.reset();
+    setFields((old) => ({ ...old, ...values }));
+  };
+  return {
+    inputId,
+    currency: props.currency,
+    mode: fields.mode,
+    minimum: fields.minimum,
+    consent: fields.consent,
+    setMode: (mode) => update({ mode, consent: false }),
+    setMinimum: (minimum) => update({ minimum }),
+    setConsent: (consent) => update({ consent }),
+    isLoading,
+    isChanging,
+    isPending: action.isPending,
+    canSave: !isLoading && !isChanging && !action.isPending && valid,
+    error: action.error,
+    message: action.result ? messages[action.result.status] : null,
+    save: () => action.run(false),
+    retry: () => action.run(true),
+  };
+}
+/** Unstyled account-wide schedule editor. It offers no payout or withdrawal action. */
+export function PayoutSettings(props: PayoutSettingsProps) {
+  const state = usePayoutSettings(props);
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <form
+      data-better-stripe="payout-settings"
+      onSubmit={(event) => {
+        event.preventDefault();
+        void state.save();
+      }}
+    >
+      <h2>Payout settings</h2>
+      <label htmlFor={`${state.inputId}-mode`}>Automatic payout policy</label>
+      <select
+        id={`${state.inputId}-mode`}
+        value={state.mode}
+        disabled={state.isLoading || state.isPending || state.isChanging}
+        onChange={(event) =>
+          state.setMode(event.target.value as PayoutSettingsState["mode"])
+        }
+      >
+        <option value="stripe_managed">
+          Stripe-managed automatic payouts, all currencies
+        </option>
+        <option value="custom">Custom combined minimum</option>
+      </select>
+      {state.mode === "custom" && (
+        <>
+          <label htmlFor={`${state.inputId}-minimum`}>
+            Minimum ({props.currency.toUpperCase()})
+          </label>
+          <input
+            id={`${state.inputId}-minimum`}
+            inputMode="decimal"
+            value={state.minimum}
+            disabled={state.isPending || state.isChanging}
+            onChange={(event) => state.setMinimum(event.target.value)}
+          />
+          <label>
+            <input
+              type="checkbox"
+              checked={state.consent}
+              disabled={state.isPending || state.isChanging}
+              onChange={(event) => state.setConsent(event.target.checked)}
+            />
+            I agree to hold funds in my Stripe balance until the combined
+            minimum is met, subject to the holding deadline.
+          </label>
+          <p>
+            Store and affiliate earnings combine per currency. Below-minimum
+            funds remain owed. Other currency minimums are preserved.
+          </p>
+        </>
+      )}
+      {state.isLoading && <p role="status">Loading payout settings…</p>}
+      {state.isChanging && (
+        <p role="status">
+          A settings change is being verified. The automatic worker will resume
+          it.
+        </p>
+      )}
+      {state.error && <p role="alert">{state.error}</p>}
+      {state.message && <p role="status">{state.message}</p>}
+      <button type="submit" disabled={!state.canSave}>
+        {state.isPending ? "Saving…" : "Save payout settings"}
+      </button>
+      {state.isChanging && props.onRetry && (
+        <button
+          type="button"
+          disabled={state.isPending}
+          onClick={() => void state.retry()}
+        >
+          Retry settings verification
+        </button>
+      )}
+    </form>
+  );
+}

package/src/react/workflows/index.ts

@@ -27,6 +27,19 @@ export type {
   ConnectRenderProps,
 } from "./Connect.js";
 export { Payouts } from "./Payouts.js";
+export { PayoutProgress } from "./PayoutProgress.js";
+export { PayoutSettings, usePayoutSettings } from "./PayoutSettings.js";
+export type {
+  PayoutSettingsProps,
+  PayoutSettingsState,
+  PayoutSettingsChange,
+  PayoutSettingsResult,
+} from "./PayoutSettings.js";
+export type {
+  PayoutProgressProps,
+  PayoutProgressState,
+  PayoutProgressMetric,
+} from "./PayoutProgress.js";
 export type {
   PayoutsProps,
   HeadlessPayoutsProps,

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

@@ -0,0 +1,199 @@
+import type { ReactNode } from "react";
+import type { PayoutPolicy, PayoutPreview } from "../../client/payoutPolicy.js";
+import { formatPrice } from "../lib/price-helpers.js";
+export type PayoutProgressMetric = {
+  key:
+    | "qualifying"
+    | "pending"
+    | "minimum"
+    | "eligible"
+    | "fees"
+    | "liabilities"
+    | "carried"
+    | "withheld"
+    | "reserved"
+    | "released";
+  label: string;
+  amount: number;
+  formattedValue: string;
+};
+export type PayoutProgressState = {
+  status:
+    "loading" | "stripe_managed" | "changing" | "unavailable" | "assessed";
+  currency: string;
+  reason: string | null;
+  message: string;
+  metrics: PayoutProgressMetric[];
+  accounting?: NonNullable<
+    Extract<PayoutPreview, { currency: string }>["accounting"]
+  >;
+  sources: {
+    role: "store" | "affiliate" | "other";
+    matureUnpaid: number;
+    pendingCredits: number;
+    matureLabel: string;
+    pendingLabel: string;
+    releasedAmount?: number;
+    reservedAmount?: number;
+    releasedLabel?: string;
+    reservedLabel?: string;
+  }[];
+  progress: { value: number; max: number } | null;
+  nextAttemptAt: number | null;
+  holdDeadline: number | null;
+  observedAt: number | null;
+};
+export type PayoutProgressProps = {
+  policy:
+    | Pick<PayoutPolicy, "mode" | "status" | "thresholds" | "holdDeadline">
+    | null
+    | undefined;
+  preview?: PayoutPreview | null;
+  currency: string;
+  /** Application worker attempt time, never a bank arrival estimate. */
+  nextAttemptAt?: number | null;
+  locale?: string;
+  timeZone?: string;
+  className?: string;
+  /** Compose translated host cards with the same financial state. */
+  children?: (state: PayoutProgressState) => ReactNode;
+};
+const reasons: Record<string, string> = {
+  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",
+}: PayoutProgressProps): PayoutProgressState {
+  const amount = (value: number) => formatPrice(value, currency, locale);
+  const state: PayoutProgressState = {
+    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.accounting = preview.accounting;
+        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],
+          ...(preview.accounting
+            ? ([
+                [
+                  "carried",
+                  "Carried forward",
+                  preview.accounting.carriedForwardAmount,
+                ],
+                [
+                  "withheld",
+                  "Withheld for costs",
+                  preview.accounting.withheldAmount,
+                ],
+                [
+                  "reserved",
+                  "Payouts in progress",
+                  preview.accounting.reservedAmount,
+                ],
+                [
+                  "released",
+                  "Paid out, net of returns",
+                  preview.accounting.releasedAmount,
+                ],
+              ] as const)
+            : []),
+          ["fees", "Confirmed payout costs", preview.confirmedFees],
+          [
+            "liabilities",
+            "Other outstanding obligations",
+            preview.independentLiabilities,
+          ],
+        ] as const;
+        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),
+          ...(source.releasedAmount === undefined
+            ? {}
+            : { releasedLabel: amount(source.releasedAmount) }),
+          ...(source.reservedAmount === undefined
+            ? {}
+            : { reservedLabel: amount(source.reservedAmount) }),
+        }));
+      }
+    }
+  }
+  return state;
+}