@fantastic.dev/better-stripe 0.28.4 → 0.28.5

package/docs/react-workflows.md

@@ -752,3 +752,22 @@ described in the [settlement guide](settlement.md#development-reset-safeguards).
 See the [read contract guide](read-contracts.md) for reactive product, price and payout
 cursors, exact currency summaries, legacy backfill, payout failure details, and
 published-version adoption requirements.
+
+### Latest automatic payout attempt
+
+`payoutAttemptStatus(job)` projects a package worker job into the public
+`PayoutAttempt` contract. Use `payoutAttemptValidator` in host response validators
+and forward the result as `lastAttempt` to `PayoutProgress`, or render the
+unstyled `PayoutAttemptStatus` workflow directly. Its render prop supplies a
+safe message, tone and localized result time for host cards.
+
+Stripe rejections retain `balance_insufficient` or `amount_too_small` instead of
+a generic rejection. This history is separate from an informational eligibility
+preview; qualification does not promise provider acceptance. A running lease
+or unresolved operation suppresses an older paid result. The workflow hides a
+stale retry date while a check runs. Legacy jobs without a recorded result time
+show no invented timestamp. Result/check times are not bank arrival estimates.
+
+The example uses the same package workflow in API and BetterStripe-component
+views, including seller and affiliate payout panels. No status control is a
+manual withdrawal request. Unknown outcomes reconcile the original operation.

package/docs/settlement.md

@@ -801,3 +801,19 @@ Pending or unknown direct affiliate payouts and recovery operations also block
 reset, preserving the receipts and obligations needed for reconciliation.
 The guard preserves the restoration and payout records until that work is done.
 Read-only cache collections can be cleared with the other development data.
+
+### Observing automatic attempt outcomes
+
+Worker jobs record `lastResultAt` with each completed check and retain a verified
+Stripe rejection code in `lastReason`. `payoutAttemptStatus(job)` distinguishes
+running, reconciling, rejected, failed, held and paid results. Active generations
+take precedence over old successes; missing legacy result times remain unknown.
+Use the exported `payoutAttemptValidator` for a host DTO and keep the operation's
+immutable rejection receipt for audits. The example warns operators on rejected
+payouts before the holding deadline, without logging raw provider errors.
+
+A rejected request releases proven reservations; it does not forfeit unpaid
+entitlement. Refunds/reversals still reduce qualifying funds. Provider floors
+remain provider-enforced and numerically unknown when not exposed. Reassess fresh
+receipts and balances on the next scheduled attempt rather than manually
+recreating uncertain requests.

package/package.json

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

package/src/client/connect/payoutWorker.test.ts

@@ -3,7 +3,7 @@ import { afterEach, expect, it, vi } from "vitest";
 import type Stripe from "stripe";
 import { setup, scope, component } from "./payoutExecutionTestHelpers.js";
 import { reconcileRecipientPayout } from "./payoutReconciliation.js";
-import { PayoutWorkerClient } from "./payoutWorker.js";
+import { PayoutWorkerClient, payoutAttemptStatus } from "./payoutWorker.js";
 import { changeBalance } from "../../component/affiliateRecovery/accounting.js";
 afterEach(() => vi.useRealTimers());
 async function worker(amounts?: number[]) {
@@ -143,3 +143,59 @@ it("reports affiliate recovery holds before a fresh attempt without creating a p
   });
   expect(s.provider.payouts.create).not.toHaveBeenCalled();
 });
+
+it.each(["balance_insufficient", "amount_too_small"])(
+  "persists actionable %s rejection and its result time",
+  async (code) => {
+    const s = await worker();
+    s.provider.payouts.create.mockRejectedValueOnce(
+      Object.assign(new Error(code), {
+        type: "StripeInvalidRequestError",
+        code,
+        requestId: "req_rejected",
+      }),
+    );
+    expect(await s.run()).toMatchObject({
+      job: { lastReason: code, lastResultAt: expect.any(Number) },
+      payout: { claim: { status: "rejected", rejection: { code } } },
+    });
+  },
+);
+
+it("does not reuse a prior paid result or timestamp for a newer running generation", async () => {
+  const s = await worker();
+  const result = await s.run();
+  if (result.status !== "completed")
+    throw new Error("Expected completed fixture");
+  const active = {
+    ...result.job,
+    generation: result.job.generation + 1,
+    completedGeneration: result.job.generation,
+    hasOperation: true,
+    operationKey: "new-operation",
+    lastReason: "paid",
+    lastResultAt: 1000,
+    lastAttemptAt: 2000,
+    leaseUntil: 3000,
+  };
+  expect(payoutAttemptStatus(active, 2100)).toEqual({
+    currency: "usd",
+    status: "running",
+    reason: "pending_claim",
+    at: 2000,
+  });
+  expect(payoutAttemptStatus(active, 4000)).toEqual({
+    currency: "usd",
+    status: "reconciling",
+    reason: "pending_claim",
+  });
+});
+it("keeps legacy result times unknown rather than inventing a completion time", async () => {
+  const s = await worker();
+  const result = await s.run();
+  if (result.status !== "completed")
+    throw new Error("Expected completed fixture");
+  expect(
+    payoutAttemptStatus({ ...result.job, lastResultAt: undefined }),
+  ).toEqual({ currency: "usd", status: "paid", reason: "paid" });
+});

package/src/client/connect/payoutWorker.ts

@@ -1,5 +1,8 @@
 import type { Infer } from "convex/values";
-import type { jobDoc } from "../../component/payoutWorker/schema.js";
+import type {
+  jobDoc,
+  attemptStatus,
+} from "../../component/payoutWorker/schema.js";
 import type { policyDoc } from "../../component/payoutPolicy/schema.js";
 import type { Component, RunCtx } from "../helpers.js";
 import { runMutationOrThrow } from "../helpers.js";
@@ -138,7 +141,48 @@ export class PayoutWorkerClient {
       throw error;
     }
     const reason =
-      payout.status === "held" ? payout.reason : payout.claim.status;
+      payout.status === "held"
+        ? payout.reason
+        : (payout.claim.rejection?.code ?? payout.claim.status);
     return { status: "completed", job: await finish(reason), payout };
   }
 }
+
+export type PayoutAttempt = Infer<typeof attemptStatus>;
+/** Current lease and generation take precedence over a prior result. Legacy timestamps remain unknown. */
+export function payoutAttemptStatus(
+  job: PayoutWorkerJob | null,
+  now = Date.now(),
+): PayoutAttempt | null {
+  if (!job || (!job.hasOperation && !job.lastReason)) return null;
+  const completed = job.completedGeneration === job.generation;
+  const running = job.hasOperation && (job.leaseUntil ?? 0) > now;
+  const reason =
+    job.hasOperation && !completed
+      ? "pending_claim"
+      : (job.lastReason ?? "pending_claim");
+  const status = running
+    ? "running"
+    : job.hasOperation
+      ? "reconciling"
+      : ["balance_insufficient", "amount_too_small", "rejected"].includes(
+            reason,
+          )
+        ? "rejected"
+        : reason === "paid"
+          ? "paid"
+          : ["worker_error", "returned"].includes(reason)
+            ? "failed"
+            : "held";
+  const at = running
+    ? job.lastAttemptAt
+    : job.hasOperation && !completed
+      ? undefined
+      : job.lastResultAt;
+  return {
+    currency: job.currency,
+    status,
+    reason,
+    ...(at === undefined ? {} : { at }),
+  };
+}

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/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";