@fantastic.dev/better-stripe 0.28.1 → 0.28.3

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

@@ -0,0 +1,168 @@
+// @vitest-environment edge-runtime
+import { afterEach, expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import { setup, scope, component } from "./payoutExecutionTestHelpers.js";
+import { PayoutWorkerClient } from "./payoutWorker.js";
+import { reconcileRecipientPayout } from "./payoutReconciliation.js";
+import { previewRecipientPayout } from "./payoutPreview.js";
+afterEach(() => vi.useRealTimers());
+async function recipient(hours: number, amounts = [599, 400]) {
+  const s = await setup(amounts);
+  const deadline = Date.now() + hours * 3600000;
+  await s.t.run(async (ctx) => {
+    const policy = (await ctx.db.query("payoutPolicies").first())!;
+    await ctx.db.patch(policy._id, { holdDeadline: deadline });
+  });
+  const client = new PayoutWorkerClient(
+    component,
+    (_ctx, opts) => s.run(opts),
+    (_ctx, opts) =>
+      reconcileRecipientPayout(
+        s.provider as unknown as Stripe,
+        component,
+        s.ctx,
+        opts,
+      ),
+  );
+  const run = (cadenceMs = 300000) =>
+    client.run(s.ctx, { ...scope, cadenceMs });
+  return { ...s, deadline, client, worker: run };
+}
+it("the scheduled worker releases below-custom-minimum funds in the final day", async () => {
+  const s = await recipient(12);
+  expect(await s.worker()).toMatchObject({
+    payout: { claim: { status: "paid", amount: 999 } },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+  const policy = await s.t.run((ctx) => ctx.db.query("payoutPolicies").first());
+  expect(policy).toMatchObject({
+    thresholds: [{ currency: "usd", amount: 1000 }],
+    holdDeadline: s.deadline,
+  });
+});
+it("retains the configured minimum before the final day", async () => {
+  const s = await recipient(48);
+  expect(await s.worker()).toMatchObject({
+    payout: { status: "held", reason: "below_threshold" },
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+it("the final attempt still subtracts known liabilities", async () => {
+  const s = await recipient(12);
+  expect(await s.run({ independentLiabilities: 100 })).toMatchObject({
+    claim: { status: "paid", amount: 899 },
+  });
+});
+it("previews the deadline waiver without changing the configured minimum or reserving money", async () => {
+  const s = await recipient(12);
+  expect(
+    await previewRecipientPayout(
+      s.provider as unknown as Stripe,
+      component,
+      s.ctx,
+      scope,
+      s.verify,
+    ),
+  ).toMatchObject({
+    status: "qualified",
+    amount: 999,
+    threshold: 1000,
+    minimumWaived: true,
+    holdDeadline: s.deadline,
+    providerMinimum: null,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+  ).toEqual([]);
+});
+it("caps a daily cadence at the beginning of the final-attempt window", async () => {
+  vi.useFakeTimers();
+  const s = await recipient(25);
+  expect(await s.worker(86400000)).toMatchObject({
+    payout: { reason: "below_threshold" },
+    job: { nextAttemptAt: s.deadline - 86400000 },
+  });
+  vi.advanceTimersByTime(3600000);
+  expect(await s.worker(86400000)).toMatchObject({
+    payout: { claim: { amount: 999, status: "paid" } },
+  });
+});
+it("retains an unknown final-attempt claim and reconciles without another create", async () => {
+  vi.useFakeTimers();
+  const s = await recipient(12);
+  const create = s.provider.payouts.create.getMockImplementation()!;
+  s.provider.payouts.create.mockImplementationOnce(async (params) => {
+    await create(params);
+    throw new Error("response lost after provider accepted");
+  });
+  await expect(s.worker()).rejects.toThrow(/response lost/);
+  vi.advanceTimersByTime(300000);
+  expect(await s.worker()).toMatchObject({
+    payout: { claim: { amount: 999, status: "paid" } },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+
+it.each(["balance_insufficient", "amount_too_small"])(
+  "the final attempt preserves provider rejection %s",
+  async (code) => {
+    const s = await recipient(12);
+    s.provider.payouts.create.mockRejectedValueOnce(
+      Object.assign(new Error(code), {
+        type: "StripeInvalidRequestError",
+        code,
+        requestId: "req_declined",
+      }),
+    );
+    expect(await s.worker()).toMatchObject({
+      payout: { claim: { status: "rejected", rejection: { code } } },
+    });
+    expect(
+      await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+    ).toMatchObject([{ reservedAmount: 0 }, { reservedAmount: 0 }]);
+  },
+);
+it("an exhausted balance cannot qualify a zero-amount final payout", async () => {
+  const s = await recipient(12);
+  expect(await s.run({ independentLiabilities: 999 })).toMatchObject({
+    status: "held",
+    amount: 0,
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+it("does not begin a new payout after the holding deadline", async () => {
+  const s = await recipient(-1);
+  expect(await s.worker()).toMatchObject({
+    status: "held",
+    reason: "policy_inactive",
+  });
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+});
+
+it("retries an unknown final attempt within five minutes even with a daily cadence", async () => {
+  vi.useFakeTimers();
+  const s = await recipient(12);
+  s.provider.payouts.create.mockRejectedValueOnce(
+    new Error("network outcome unknown"),
+  );
+  await expect(s.worker(86400000)).rejects.toThrow(/network outcome unknown/);
+  expect((await s.client.get(s.ctx, scope))!.nextAttemptAt).toBe(
+    Date.now() + 300000,
+  );
+});
+
+it("rescues a pre-existing job whose stored cadence would skip the final window", async () => {
+  vi.useFakeTimers();
+  const s = await recipient(25);
+  await s.worker(86400000);
+  await s.t.run(async (ctx) => {
+    const job = (await ctx.db.query("payoutWorkerJobs").first())!;
+    await ctx.db.patch(job._id, { nextAttemptAt: Date.now() + 86400000 });
+  });
+  vi.advanceTimersByTime(3600000);
+  expect(await s.worker(86400000)).toMatchObject({
+    payout: { claim: { amount: 999, status: "paid" } },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});

package/src/client/connect/payoutExecutionTestHelpers.ts

@@ -32,7 +32,7 @@ export async function setup(amounts = [600, 400]) {
       operationKey: "enable",
       country: "US",
       thresholds: [{ currency: "usd", amount: 1000 }],
-      holdDeadline: Date.now() + 86400000,
+      holdDeadline: Date.now() + 7 * 86400000,
     });
     for (let i = 0; i < amounts.length; i++)
       await ctx.db.insert("transfers", {

package/src/client/payoutPolicy.test.ts

@@ -242,6 +242,40 @@ it("restores original settings at the holding deadline, without extending it", a
   expect((await client.get(ctx, scope))!.mode).toBe("stripe_managed");
   expect(provider.balanceSettings.update).toHaveBeenCalledTimes(2);
 });
+it("retains pending expiry restoration and retries the same provider operation", async () => {
+  const { client, ctx, t, provider } = await setup();
+  await client.prepare(ctx, options);
+  await client.apply(ctx, { ...scope, operationKey: "enable" });
+  await t.run(async (c) => {
+    const p = await c.db.query("payoutPolicies").first();
+    await c.db.patch(p!._id, { holdDeadline: Date.now() - 1 });
+  });
+  provider.balanceSettings.update.mockRejectedValueOnce(
+    new Error("restoration timeout"),
+  );
+  await expect(client.expire(ctx, scope)).rejects.toThrow(
+    "restoration timeout",
+  );
+  const pending = await client.get(ctx, scope);
+  expect(pending).toMatchObject({
+    mode: "custom",
+    status: "changing",
+    previousSchedule: { interval: "weekly", weeklyDays: ["monday"] },
+  });
+  expect(pending!.holdDeadline).toBeLessThan(Date.now());
+  await client.expire(ctx, scope);
+  expect(await client.get(ctx, scope)).toMatchObject({
+    mode: "stripe_managed",
+    status: "ready",
+  });
+  expect(provider.balanceSettings.update).toHaveBeenCalledTimes(3);
+  expect(provider.balanceSettings.update.mock.calls[1][1]).toEqual(
+    provider.balanceSettings.update.mock.calls[2][1],
+  );
+  expect(
+    (await provider.balanceSettings.retrieve()).payments.payouts.schedule,
+  ).toMatchObject({ interval: "weekly", weekly_payout_days: ["monday"] });
+});
 it("re-checks live control on every payout-policy verification", async () => {
   const { client, ctx, setSchedule } = await setup();
   await client.prepare(ctx, options);

package/src/component/_generated/api.ts

@@ -53,6 +53,7 @@ import type * as payoutPolicy_queries from "../payoutPolicy/queries.js";
 import type * as payoutRelease_adoption from "../payoutRelease/adoption.js";
 import type * as payoutRelease_allocation from "../payoutRelease/allocation.js";
 import type * as payoutRelease_allocationTotals from "../payoutRelease/allocationTotals.js";
+import type * as payoutRelease_deadline from "../payoutRelease/deadline.js";
 import type * as payoutRelease_fees from "../payoutRelease/fees.js";
 import type * as payoutRelease_helpers from "../payoutRelease/helpers.js";
 import type * as payoutRelease_mutations from "../payoutRelease/mutations.js";
@@ -137,6 +138,7 @@ const fullApi: ApiFromModules<{
   "payoutRelease/adoption": typeof payoutRelease_adoption;
   "payoutRelease/allocation": typeof payoutRelease_allocation;
   "payoutRelease/allocationTotals": typeof payoutRelease_allocationTotals;
+  "payoutRelease/deadline": typeof payoutRelease_deadline;
   "payoutRelease/fees": typeof payoutRelease_fees;
   "payoutRelease/helpers": typeof payoutRelease_helpers;
   "payoutRelease/mutations": typeof payoutRelease_mutations;

package/src/component/_generated/component.ts

@@ -3639,8 +3639,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               amount: number;
               confirmedFees: number;
               currency: string;
+              holdDeadline?: number;
               independentLiabilities: number;
               matureUnpaid: number;
+              minimumWaived?: boolean;
               observedAt: number;
               pendingCredits: number;
               providerAvailable: number;

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

@@ -90,6 +90,20 @@ it("shows verified carry forward, withholding, in-flight and paid totals separat
   expect(screen.getByRole("columnheader", { name: "Paid out" })).toBeTruthy();
   expect(screen.getByRole("columnheader", { name: "In flight" })).toBeTruthy();
 });
+it("explains an expired holding deadline without inventing a payable balance", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      currency="usd"
+      preview={{ status: "held", reason: "expired", amount: 0 }}
+    />,
+  );
+  expect(screen.getByRole("status").textContent).toContain(
+    "holding deadline has passed",
+  );
+  expect(screen.queryByRole("progressbar")).toBeNull();
+  expect(screen.queryByText("$0.00")).toBeNull();
+});
 it("does not invent new accounting totals for a legacy assessment", () => {
   render(<PayoutProgress policy={policy} preview={preview} currency="usd" />);
   expect(screen.queryByText("Carried forward")).toBeNull();
@@ -103,16 +117,37 @@ it("keeps Stripe-managed defaults distinct from a custom application minimum", (
   expect(screen.queryByRole("progressbar")).toBeNull();
   expect(screen.queryByText("$1.00")).toBeNull();
 });
-it("does not reuse a prior assessment while the schedule change is pending", () => {
+it.each(["custom", "stripe_managed"] as const)(
+  "keeps %s mode unverified while the schedule change is pending",
+  (mode) => {
+    render(
+      <PayoutProgress
+        policy={{ ...policy, mode, status: "changing" }}
+        preview={preview}
+        currency="usd"
+      />,
+    );
+    expect(screen.getByRole("status").textContent).toContain("being verified");
+    expect(screen.queryByRole("progressbar")).toBeNull();
+    expect(screen.queryByText(/Stripe manages automatic payouts/)).toBeNull();
+    expect(screen.queryByText("Combined qualifying balance")).toBeNull();
+  },
+);
+it("gives host cards an unverified state during activation from Stripe-managed defaults", () => {
   render(
     <PayoutProgress
-      policy={{ ...policy, status: "changing" }}
+      policy={{ ...policy, mode: "stripe_managed", status: "changing" }}
       preview={preview}
       currency="usd"
-    />,
+    >
+      {(state) => (
+        <span data-testid="restoration">
+          {state.status}:{state.metrics.length}
+        </span>
+      )}
+    </PayoutProgress>,
   );
-  expect(screen.getByRole("status").textContent).toContain("being verified");
-  expect(screen.queryByRole("progressbar")).toBeNull();
+  expect(screen.getByTestId("restoration").textContent).toBe("changing:0");
 });
 it("preserves negative entitlement while clamping only the visual progress", () => {
   render(
@@ -206,3 +241,26 @@ 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();
+});

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>
         </>
       )}

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

@@ -72,6 +72,8 @@ const reasons: Record<string, string> = {
   payout_unidentified:
     "A previous payout outcome needs reconciliation. No replacement payout will be created blindly.",
   observations_stale: "Provider observations expired. Refresh the assessment.",
+  expired:
+    "The custom holding deadline has passed. Eligibility is unavailable until the payout schedule is restored and verified.",
   snapshot_limit:
     "This account needs continued history reconciliation before eligibility can be assessed.",
   policy_changed: "Payout settings changed. Refresh the assessment.",
@@ -98,14 +100,14 @@ export function payoutProgressState({
     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") {
+    if (policy?.status === "changing") {
       state.status = "changing";
       state.message =
         "Payout settings are being verified. Eligibility is unavailable until the change completes.";
+    } else if (!policy || policy.mode === "stripe_managed") {
+      state.status = "stripe_managed";
+      state.message =
+        "Stripe manages automatic payouts. No additional application minimum is set.";
     } else if (preview !== undefined) {
       state.nextAttemptAt = nextAttemptAt ?? null;
       if (!preview || !("currency" in preview)) {
@@ -121,24 +123,36 @@ export function payoutProgressState({
         if (
           preview.currency !== currency ||
           !configured ||
-          configured.amount !== preview.threshold
+          configured.amount !== preview.threshold ||
+          (preview.minimumWaived &&
+            preview.holdDeadline !== policy.holdDeadline)
         )
           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"
+        state.message = preview.minimumWaived
+          ? "The holding deadline is approaching. The application minimum is waived for final automatic attempts; provider limits and all balance checks still apply. " +
+            (preview.status === "qualified"
+              ? "The worker will verify eligibility again before any payout."
+              : (reasons[preview.reason ?? ""] ??
+                "Automatic payout remains on hold. Contact support before the deadline."))
+          : 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,
-        };
+        state.progress = preview.minimumWaived
+          ? null
+          : {
+              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],