@fantastic.dev/better-stripe 0.28.4 → 0.28.6

package/src/client/payoutPolicy.ts

@@ -1,3 +1,5 @@
+export { payoutAttemptStatus } from "./connect/payoutWorker.js";
+export { attemptStatus as payoutAttemptValidator } from "../component/payoutWorker/schema.js";
 export { holdingExpiry as payoutHoldingExpiryValidator } from "../component/payoutPolicy/schema.js";
 import { expirePayoutPolicy } from "./connect/payoutExpiry.js";
 import {

package/src/component/_generated/component.ts

@@ -4112,6 +4112,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 hasOperation: boolean;
                 lastAttemptAt?: number;
                 lastReason?: string;
+                lastResultAt?: number;
                 leaseUntil?: number;
                 nextAttemptAt: number;
                 operationKey?: string;
@@ -4146,6 +4147,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             hasOperation: boolean;
             lastAttemptAt?: number;
             lastReason?: string;
+            lastResultAt?: number;
             leaseUntil?: number;
             nextAttemptAt: number;
             operationKey?: string;
@@ -4223,6 +4225,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             hasOperation: boolean;
             lastAttemptAt?: number;
             lastReason?: string;
+            lastResultAt?: number;
             leaseUntil?: number;
             nextAttemptAt: number;
             operationKey?: string;
@@ -4310,6 +4313,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               hasOperation: boolean;
               lastAttemptAt?: number;
               lastReason?: string;
+              lastResultAt?: number;
               leaseUntil?: number;
               nextAttemptAt: number;
               operationKey?: string;

package/src/component/payoutRelease/helpers.ts

@@ -71,6 +71,7 @@ export async function checkSnapshot(
   accountId: string,
   observations: Infer<typeof observation>[],
   fresh: boolean,
+  freshCurrency?: string,
 ) {
   const rows = await ctx.db
     .query("transfers")
@@ -106,6 +107,7 @@ export async function checkSnapshot(
       throw new Error("Payout source snapshot changed or is not ready.");
     if (
       fresh &&
+      (freshCurrency === undefined || o.currency === freshCurrency) &&
       (!Number.isSafeInteger(o.observedAt) ||
         o.observedAt > Date.now() ||
         o.observedAt < Date.now() - 30000)

package/src/component/payoutRelease/mutations.ts

@@ -124,7 +124,13 @@ export const beginAttempt = mutation({
     const feeRevision = (await readFees(ctx, claim))?.revision ?? 0;
     if (feeRevision !== (claim.feeRevision ?? 0))
       throw new Error("Payout fee revision changed after reservation.");
-    await checkSnapshot(ctx, claim.accountId, claim.observations, true);
+    await checkSnapshot(
+      ctx,
+      claim.accountId,
+      claim.observations,
+      true,
+      claim.currency,
+    );
     await reserveRecoveryGuard(ctx, claim, claim.amount);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       attemptedAt: Date.now(),

package/src/component/payoutRelease/planning.ts

@@ -26,6 +26,7 @@ export async function readPayoutPlan(
     args.accountId,
     args.observations,
     true,
+    args.currency,
   );
   const sources: PayoutFundingSource[] = [];
   for (const observation of args.observations) {

package/src/component/payoutRelease/preview.ts

@@ -106,7 +106,9 @@ export async function previewPlan(
     providerAvailable: args.providerAvailable,
     observedAt: Math.min(
       Date.now(),
-      ...args.observations.map((o) => o.observedAt),
+      ...args.observations
+        .filter((o) => o.currency === args.currency)
+        .map((o) => o.observedAt),
     ),
     ...progress,
   };

package/src/component/payoutWorker/mutations.ts

@@ -77,6 +77,7 @@ export const begin = mutation({
           hasOperation: false,
           leaseUntil: undefined,
           lastReason: "policy_inactive",
+          lastResultAt: now,
           nextAttemptAt: nextPayoutAttempt(policy, now, args.cadenceMs),
         });
       return { status: "held" as const, reason: "policy_inactive" };
@@ -113,6 +114,7 @@ export const begin = mutation({
           hasOperation: false,
           leaseUntil: undefined,
           lastReason: "affiliate_recovery_pending",
+          lastResultAt: now,
           nextAttemptAt,
         });
         return {
@@ -189,6 +191,7 @@ export const finish = mutation({
         job.cadenceMs,
       ),
       lastReason: args.reason,
+      lastResultAt: Date.now(),
       completedGeneration: args.generation,
       completedOperationKey: args.operationKey,
     });

package/src/component/payoutWorker/schema.ts

@@ -13,6 +13,7 @@ export const fields = {
   hasOperation: v.boolean(),
   lastReason: v.optional(v.string()),
   lastAttemptAt: v.optional(v.number()),
+  lastResultAt: v.optional(v.number()),
   completedGeneration: v.optional(v.number()),
   completedOperationKey: v.optional(v.string()),
 };
@@ -24,3 +25,17 @@ export const jobDoc = v.object({
 export const jobsTable = defineTable(fields)
   .index("by_account_currency", ["accountId", "currency"])
   .index("by_operation_pending", ["hasOperation", "nextAttemptAt"]);
+
+export const attemptStatus = v.object({
+  currency: v.string(),
+  status: v.union(
+    v.literal("running"),
+    v.literal("reconciling"),
+    v.literal("rejected"),
+    v.literal("failed"),
+    v.literal("paid"),
+    v.literal("held"),
+  ),
+  reason: v.string(),
+  at: v.optional(v.number()),
+});

package/src/react/workflows/PayoutAttemptStatus.tsx

@@ -0,0 +1,44 @@
+"use client";
+import type { ReactNode } from "react";
+import type { PayoutAttempt } from "../../client/connect/payoutWorker.js";
+import {
+  payoutAttemptState,
+  type PayoutAttemptState,
+} from "./payout-attempt-state.js";
+export type { PayoutAttemptState } from "./payout-attempt-state.js";
+export type PayoutAttemptStatusProps = {
+  attempt?: PayoutAttempt | null;
+  locale?: string;
+  timeZone?: string;
+  className?: string;
+  children?: (state: PayoutAttemptState) => ReactNode;
+};
+/** Unstyled worker status. Result times are not bank arrival estimates. */
+export function PayoutAttemptStatus({
+  attempt,
+  locale,
+  timeZone,
+  className,
+  children,
+}: PayoutAttemptStatusProps) {
+  const state = payoutAttemptState(attempt, locale, timeZone);
+  if (!state) return null;
+  if (children) return <>{children(state)}</>;
+  return (
+    <aside
+      className={className}
+      data-better-stripe="payout-attempt"
+      data-tone={state.tone}
+    >
+      <h3>Latest automatic payout check</h3>
+      <p role="status" aria-label="Latest automatic payout attempt">
+        {state.message}
+      </p>
+      {state.formattedAt && (
+        <p>
+          {state.timeLabel}: {state.formattedAt}
+        </p>
+      )}
+    </aside>
+  );
+}

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

@@ -306,3 +306,51 @@ it("keeps unavailable expiry balances unverified instead of showing fabricated z
   );
   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,6 +29,11 @@ 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>

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,6 +47,7 @@ export type PayoutProgressState = {
   nextAttemptAt: number | null;
   holdDeadline: number | null;
   observedAt: number | null;
+  lastAttempt?: PayoutAttemptState;
   recovery?: {
     status: NonNullable<PayoutPolicy["holdingExpiry"]>["status"];
     balances?: {
@@ -62,6 +68,7 @@ export type PayoutProgressProps = {
     | null
     | undefined;
   preview?: PayoutPreview | null;
+  lastAttempt?: PayoutAttempt | null;
   currency: string;
   /** Application worker attempt time, never a bank arrival estimate. */
   nextAttemptAt?: number | null;
@@ -96,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",
@@ -111,6 +124,10 @@ 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") {
@@ -149,7 +166,10 @@ export function payoutProgressState({
       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";