@fantastic.dev/better-stripe 0.28.2 → 0.28.4

package/src/component/core/resetSafety.ts

@@ -1,39 +1,51 @@
 import type { MutationCtx } from "../_generated/server.js";
 /** A database reset cannot erase the only restoration or unresolved-payout record. */
 export async function assertPayoutResetSafe(ctx: MutationCtx) {
-  const [bound, custom, changing, reserved, submitted, pending, transit] =
-    await Promise.all([
-      ctx.db
-        .query("payoutSnapshots")
-        .withIndex("by_read_only", (q) => q.eq("readOnly", false))
-        .first(),
-      ctx.db
-        .query("payoutPolicies")
-        .withIndex("by_mode_status", (q) => q.eq("mode", "custom"))
-        .first(),
-      ctx.db
-        .query("payoutPolicies")
-        .withIndex("by_mode_status", (q) =>
-          q.eq("mode", "stripe_managed").eq("status", "changing"),
-        )
-        .first(),
-      ctx.db
-        .query("payoutReleaseClaims")
-        .withIndex("by_status", (q) => q.eq("status", "reserved"))
-        .first(),
-      ctx.db
-        .query("payoutReleaseClaims")
-        .withIndex("by_status", (q) => q.eq("status", "submitted"))
-        .first(),
-      ctx.db
-        .query("payouts")
-        .withIndex("by_status", (q) => q.eq("status", "pending"))
-        .first(),
-      ctx.db
-        .query("payouts")
-        .withIndex("by_status", (q) => q.eq("status", "in_transit"))
-        .first(),
-    ]);
+  const [
+    bound,
+    custom,
+    changing,
+    reserved,
+    submitted,
+    pending,
+    transit,
+    deadline,
+  ] = await Promise.all([
+    ctx.db
+      .query("payoutSnapshots")
+      .withIndex("by_read_only", (q) => q.eq("readOnly", false))
+      .first(),
+    ctx.db
+      .query("payoutPolicies")
+      .withIndex("by_mode_status", (q) => q.eq("mode", "custom"))
+      .first(),
+    ctx.db
+      .query("payoutPolicies")
+      .withIndex("by_mode_status", (q) =>
+        q.eq("mode", "stripe_managed").eq("status", "changing"),
+      )
+      .first(),
+    ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_status", (q) => q.eq("status", "reserved"))
+      .first(),
+    ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_status", (q) => q.eq("status", "submitted"))
+      .first(),
+    ctx.db
+      .query("payouts")
+      .withIndex("by_status", (q) => q.eq("status", "pending"))
+      .first(),
+    ctx.db
+      .query("payouts")
+      .withIndex("by_status", (q) => q.eq("status", "in_transit"))
+      .first(),
+    ctx.db
+      .query("payoutPolicies")
+      .withIndex("by_deadline", (q) => q.gt("holdDeadline", 0))
+      .first(),
+  ]);
   if (bound)
     throw new Error(
       "A financially bound payout collection must be resolved before reset.",
@@ -42,6 +54,10 @@ export async function assertPayoutResetSafe(ctx: MutationCtx) {
     throw new Error(
       "Restore and verify payout schedules before reset; restoration records cannot be erased.",
     );
+  if (deadline)
+    throw new Error(
+      "Resolve holding expiry recovery before reset; its deadline and balance record cannot be erased.",
+    );
   if (reserved || submitted)
     throw new Error(
       "Resolve payout claims before reset; unresolved reservations cannot be erased.",

package/src/component/payout-reset-safety.test.ts

@@ -146,3 +146,31 @@ it.each(["pending", "unknown"] as const)(
     ).toHaveLength(1);
   },
 );
+
+it("retains an unresolved holding-expiry record after automatic scheduling was restored", async () => {
+  const t = convexTest(schema, modules);
+  await t.run((ctx) =>
+    ctx.db.insert("payoutPolicies", {
+      ...scope,
+      revision: 1,
+      mode: "stripe_managed",
+      status: "ready",
+      operationKey: "restore",
+      country: "US",
+      thresholds: [],
+      holdDeadline: Date.now() - 1,
+      holdingExpiry: {
+        deadline: Date.now() - 1,
+        status: "balance_remaining",
+        balances: [{ currency: "usd", available: 999, pending: 0 }],
+        observedAt: Date.now(),
+      },
+    }),
+  );
+  await expect(t.mutation(reset, {})).rejects.toThrow(
+    /holding expiry.*recovery/i,
+  );
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutPolicies").first()),
+  ).not.toBeNull();
+});

package/src/component/payoutPolicy/expiry.ts

@@ -0,0 +1,80 @@
+import type { MutationCtx } from "../_generated/server.js";
+import { readPolicy } from "./helpers.js";
+type Scope = { accountId: string; ownerKey: string };
+export async function beginHoldingExpiry(ctx: MutationCtx, args: Scope) {
+  const p = await readPolicy(ctx, args);
+  if (
+    !p ||
+    p.mode !== "custom" ||
+    !p.holdDeadline ||
+    p.holdDeadline > Date.now()
+  )
+    throw new Error("A due custom holding deadline is required.");
+  if (p.holdingExpiry?.deadline === p.holdDeadline) return p;
+  if (p.holdingExpiry && p.holdingExpiry.status !== "no_held_balance")
+    throw new Error("Previous holding expiry recovery is unresolved.");
+  await ctx.db.patch("payoutPolicies", p._id, {
+    holdingExpiry: { deadline: p.holdDeadline, status: "unverified" },
+  });
+  return (await ctx.db.get("payoutPolicies", p._id))!;
+}
+export async function observeHoldingExpiry(
+  ctx: MutationCtx,
+  args: Scope & {
+    expectedRevision: number;
+    deadline: number;
+    observedAt: number;
+    balances: { currency: string; available: number; pending: number }[];
+  },
+) {
+  const p = await readPolicy(ctx, args);
+  if (
+    !p ||
+    p.revision !== args.expectedRevision ||
+    p.mode !== "stripe_managed" ||
+    p.status !== "ready" ||
+    p.holdingExpiry?.deadline !== args.deadline ||
+    p.holdDeadline !== args.deadline
+  )
+    throw new Error("Holding expiry recovery changed.");
+  if (
+    !Number.isSafeInteger(args.observedAt) ||
+    args.observedAt > Date.now() ||
+    args.observedAt < Date.now() - 30000 ||
+    new Set(args.balances.map((b) => b.currency)).size !==
+      args.balances.length ||
+    args.balances.some(
+      (b) =>
+        !/^[a-z]{3}$/.test(b.currency) ||
+        !Number.isSafeInteger(b.available) ||
+        !Number.isSafeInteger(b.pending),
+    )
+  )
+    throw new Error("Invalid or stale holding expiry balance observation.");
+  const unresolved = await Promise.all(
+    (["reserved", "submitted"] as const).map((status) =>
+      ctx.db
+        .query("payoutReleaseClaims")
+        .withIndex("by_account_status", (q) =>
+          q.eq("accountId", args.accountId).eq("status", status),
+        )
+        .first(),
+    ),
+  );
+  const status = unresolved.some(Boolean)
+    ? ("claims_unresolved" as const)
+    : args.balances.some((b) => b.available !== 0 || b.pending !== 0)
+      ? ("balance_remaining" as const)
+      : ("no_held_balance" as const);
+  await ctx.db.patch("payoutPolicies", p._id, {
+    holdingExpiry: {
+      deadline: args.deadline,
+      observedAt: args.observedAt,
+      balances: args.balances,
+      status,
+    },
+    // Retain due discovery until both provider balances and durable claims clear.
+    holdDeadline: status === "no_held_balance" ? undefined : args.deadline,
+  });
+  return (await ctx.db.get("payoutPolicies", p._id))!;
+}

package/src/component/payoutPolicy/mutations.ts

@@ -1,8 +1,14 @@
+import {
+  beginHoldingExpiry as beginExpiry,
+  observeHoldingExpiry as observeExpiry,
+} from "./expiry.js";
 import { validateAdoption } from "./adoption.js";
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
 import {
   adoptionProof,
+  expiryBalance,
+  policyDoc,
   prepareFields,
   operationDoc,
   scopeFields,
@@ -69,6 +75,14 @@ export const prepare = mutation({
     )
       throw new Error("Payout policy observation is stale or in the future.");
     const policy = await readPolicy(ctx, args);
+    if (
+      args.mode === "custom" &&
+      policy?.holdingExpiry &&
+      policy.holdingExpiry.status !== "no_held_balance"
+    )
+      throw new Error(
+        "Holding expiry requires recovery before custom activation.",
+      );
     if (policy?.status === "changing")
       throw new Error("A payout policy operation is pending.");
     if ((policy?.revision ?? -1) !== args.expectedRevision)
@@ -177,7 +191,14 @@ export const confirm = mutation({
       thresholds: op.thresholds,
       status: "ready",
       ...(op.mode === "stripe_managed"
-        ? { previousSchedule: undefined, holdDeadline: undefined }
+        ? {
+            previousSchedule: undefined,
+            holdDeadline:
+              policy.holdingExpiry &&
+              policy.holdingExpiry.status !== "no_held_balance"
+                ? policy.holdDeadline
+                : undefined,
+          }
         : {}),
     });
     return (await ctx.db.get("payoutPolicyOperations", op._id))!;
@@ -263,9 +284,33 @@ export const cancelUnattempted = mutation({
     await ctx.db.patch("payoutPolicies", policy._id, {
       status: "ready",
       ...(policy.mode === "stripe_managed"
-        ? { previousSchedule: undefined, holdDeadline: undefined }
+        ? {
+            previousSchedule: undefined,
+            holdDeadline:
+              policy.holdingExpiry &&
+              policy.holdingExpiry.status !== "no_held_balance"
+                ? policy.holdDeadline
+                : undefined,
+          }
         : {}),
     });
     return (await ctx.db.get("payoutPolicyOperations", op._id))!;
   },
 });
+
+export const beginHoldingExpiry = mutation({
+  args: scopeFields,
+  returns: policyDoc,
+  handler: beginExpiry,
+});
+export const observeHoldingExpiry = mutation({
+  args: {
+    ...scopeFields,
+    expectedRevision: v.number(),
+    deadline: v.number(),
+    observedAt: v.number(),
+    balances: v.array(expiryBalance),
+  },
+  returns: policyDoc,
+  handler: observeExpiry,
+});

package/src/component/payoutPolicy/schema.ts

@@ -34,6 +34,22 @@ export const prepareFields = {
   observedSchedule: schedule,
   observedAt: v.optional(v.number()),
 };
+export const expiryBalance = v.object({
+  currency: v.string(),
+  available: v.number(),
+  pending: v.number(),
+});
+export const holdingExpiry = v.object({
+  deadline: v.number(),
+  status: v.union(
+    v.literal("unverified"),
+    v.literal("balance_remaining"),
+    v.literal("claims_unresolved"),
+    v.literal("no_held_balance"),
+  ),
+  observedAt: v.optional(v.number()),
+  balances: v.optional(v.array(expiryBalance)),
+});
 export const policyFields = {
   ...scopeFields,
   revision: v.number(),
@@ -44,6 +60,7 @@ export const policyFields = {
   country: v.string(),
   previousSchedule: v.optional(schedule),
   holdDeadline: v.optional(v.number()),
+  holdingExpiry: v.optional(holdingExpiry),
 };
 export const operationFields = {
   ...prepareFields,

package/src/component/payoutRelease/deadline.ts

@@ -0,0 +1,24 @@
+/** One operational day to retry final payouts before the country holding deadline. */
+export const finalAttemptWindowMs = 86400000;
+type Policy = { holdDeadline?: number } | null;
+export function finalAttemptStartsAt(policy: Policy): number | undefined {
+  return policy?.holdDeadline === undefined
+    ? undefined
+    : policy.holdDeadline - finalAttemptWindowMs;
+}
+export function waiveApplicationMinimum(policy: Policy, now: number): boolean {
+  const start = finalAttemptStartsAt(policy);
+  return start !== undefined && now >= start && now < policy!.holdDeadline!;
+}
+export function nextPayoutAttempt(
+  policy: Policy,
+  now: number,
+  cadence: number,
+) {
+  const start = finalAttemptStartsAt(policy);
+  if (waiveApplicationMinimum(policy, now))
+    return now + Math.min(cadence, 300000);
+  return start !== undefined && start > now
+    ? Math.min(now + cadence, start)
+    : now + cadence;
+}

package/src/component/payoutRelease/planning.ts

@@ -5,6 +5,7 @@ import type { observation } from "./observation.js";
 import { checkSnapshot, sourceById } from "./helpers.js";
 import { readFees } from "./fees.js";
 import { planRecipientPayout, type PayoutFundingSource } from "./allocation.js";
+import { waiveApplicationMinimum } from "./deadline.js";
 import { assertAllocationTotals } from "./allocationTotals.js";
 export async function readPayoutPlan(
   ctx: MutationCtx | QueryCtx,
@@ -45,13 +46,15 @@ export async function readPayoutPlan(
   }
   const fees = await readFees(ctx, args);
   await assertAllocationTotals(ctx, args, sources);
+  const minimumWaived = waiveApplicationMinimum(policy, Date.now());
   const plan = planRecipientPayout({
     currency: args.currency,
-    threshold: minimum.amount,
+    // One minor unit is the positive-money guard, not an asserted provider floor.
+    threshold: minimumWaived ? 1 : minimum.amount,
     providerAvailable: args.providerAvailable,
     independentLiabilities: args.independentLiabilities,
     confirmedFees: fees?.amount ?? 0,
     sources,
   });
-  return { plan, sources, fees, threshold: minimum.amount };
+  return { plan, sources, fees, threshold: minimum.amount, minimumWaived };
 }

package/src/component/payoutRelease/preview.ts

@@ -28,6 +28,8 @@ export const previewResult = v.union(
     currency: v.string(),
     amount: v.number(),
     threshold: v.number(),
+    minimumWaived: v.optional(v.boolean()),
+    holdDeadline: v.optional(v.number()),
     providerMinimum: v.null(),
     matureUnpaid: v.number(),
     pendingCredits: v.number(),
@@ -81,6 +83,7 @@ export async function previewPlan(
     sources: funding,
     fees,
     threshold,
+    minimumWaived,
   } = await readPayoutPlan(ctx, args, policy);
   const progress = summarizePayoutProgress(
     plan,
@@ -93,6 +96,8 @@ export async function previewPlan(
     currency: plan.currency,
     amount: plan.amount,
     threshold,
+    minimumWaived,
+    holdDeadline: policy.holdDeadline,
     providerMinimum: null,
     matureUnpaid: plan.matureUnpaid,
     pendingCredits: plan.pendingCredits,

package/src/component/payoutWorker/mutations.ts

@@ -1,5 +1,9 @@
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
+import {
+  finalAttemptStartsAt,
+  nextPayoutAttempt,
+} from "../payoutRelease/deadline.js";
 import { readPolicy } from "../payoutPolicy/helpers.js";
 import { claimByKey, add } from "../payoutRelease/helpers.js";
 import { balance as recoveryBalance } from "../affiliateRecovery/accounting.js";
@@ -38,7 +42,15 @@ export const begin = mutation({
         reason: "worker_busy",
         nextAttemptAt: job.leaseUntil,
       };
-    if (job && job.nextAttemptAt > now)
+    const finalStart = finalAttemptStartsAt(policy);
+    const enteringFinalWindow =
+      policy?.mode === "custom" &&
+      policy.status === "ready" &&
+      finalStart !== undefined &&
+      finalStart <= now &&
+      policy.holdDeadline! > now &&
+      (job?.lastAttemptAt ?? 0) < finalStart;
+    if (job && job.nextAttemptAt > now && !enteringFinalWindow)
       return {
         status: "held" as const,
         reason: "not_due",
@@ -65,7 +77,7 @@ export const begin = mutation({
           hasOperation: false,
           leaseUntil: undefined,
           lastReason: "policy_inactive",
-          nextAttemptAt: now + args.cadenceMs,
+          nextAttemptAt: nextPayoutAttempt(policy, now, args.cadenceMs),
         });
       return { status: "held" as const, reason: "policy_inactive" };
     }
@@ -95,7 +107,7 @@ export const begin = mutation({
           recovery.reservedRestoration > 0 ||
           recovery.activePayoutKey)
       ) {
-        const nextAttemptAt = now + args.cadenceMs;
+        const nextAttemptAt = nextPayoutAttempt(policy, now, args.cadenceMs);
         await ctx.db.patch("payoutWorkerJobs", job._id, {
           operationKey: undefined,
           hasOperation: false,
@@ -171,7 +183,11 @@ export const finish = mutation({
       operationKey: retain ? job.operationKey : undefined,
       hasOperation: retain,
       leaseUntil: undefined,
-      nextAttemptAt: Date.now() + job.cadenceMs,
+      nextAttemptAt: nextPayoutAttempt(
+        await readPolicy(ctx, args),
+        Date.now(),
+        job.cadenceMs,
+      ),
       lastReason: args.reason,
       completedGeneration: args.generation,
       completedOperationKey: args.operationKey,

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

@@ -241,3 +241,68 @@ it("does not display a former custom holding deadline for Stripe-managed payouts
   );
   expect(screen.queryByText(/Custom holding deadline:/)).toBeNull();
 });
+
+it("explains the deadline waiver without a minimum progress bar", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      currency="usd"
+      preview={{
+        ...preview,
+        status: "qualified",
+        reason: undefined,
+        amount: 999,
+        minimumWaived: true,
+        holdDeadline: policy.holdDeadline,
+      }}
+    />,
+  );
+  expect(screen.getByRole("status").textContent).toContain("holding deadline");
+  expect(screen.getByRole("status").textContent).toContain(
+    "application minimum is waived",
+  );
+  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();
+});

package/src/react/workflows/PayoutProgress.tsx

@@ -29,6 +29,25 @@ export function PayoutProgress(props: PayoutProgressProps) {
       <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.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 +121,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/PayoutSettings.tsx

@@ -179,7 +179,10 @@ export function PayoutSettings(props: PayoutSettingsProps) {
           </label>
           <p>
             Store and affiliate earnings combine per currency. Below-minimum
-            funds remain owed. Other currency minimums are preserved.
+            funds remain owed. During the final day before the holding deadline,
+            the application minimum is waived for automatic payout attempts.
+            Stripe payout limits and balance checks still apply. Other currency
+            minimums are preserved.
           </p>
         </>
       )}