@fantastic.dev/better-stripe 0.28.3 → 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/react/workflows/PayoutProgress.test.tsx

@@ -264,3 +264,45 @@ it("explains the deadline waiver without a minimum progress bar", () => {
   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/payout-progress-state.ts

@@ -42,10 +42,23 @@ export type PayoutProgressState = {
   nextAttemptAt: number | null;
   holdDeadline: number | null;
   observedAt: number | null;
+  recovery?: {
+    status: NonNullable<PayoutPolicy["holdingExpiry"]>["status"];
+    balances?: {
+      currency: string;
+      available: number;
+      pending: number;
+      availableLabel: string;
+      pendingLabel: string;
+    }[];
+  };
 };
 export type PayoutProgressProps = {
   policy:
-    | Pick<PayoutPolicy, "mode" | "status" | "thresholds" | "holdDeadline">
+    | Pick<
+        PayoutPolicy,
+        "mode" | "status" | "thresholds" | "holdDeadline" | "holdingExpiry"
+      >
     | null
     | undefined;
   preview?: PayoutPreview | null;
@@ -104,6 +117,33 @@ export function payoutProgressState({
       state.status = "changing";
       state.message =
         "Payout settings are being verified. Eligibility is unavailable until the change completes.";
+    } else if (
+      policy?.holdingExpiry &&
+      policy.holdingExpiry.status !== "no_held_balance"
+    ) {
+      const expiry = policy.holdingExpiry;
+      state.status = "unavailable";
+      state.reason = "holding_expiry_unresolved";
+      state.holdDeadline = expiry.deadline;
+      state.observedAt = expiry.observedAt ?? null;
+      state.message =
+        "The holding deadline has passed. Schedule restoration does not confirm disbursement. " +
+        (expiry.status === "unverified"
+          ? "Stripe balance verification is unavailable. "
+          : "Stripe balances or payout claims still require recovery. ") +
+        "Contact platform support; automatic recovery checks will retry.";
+      state.recovery = {
+        status: expiry.status,
+        ...(expiry.balances
+          ? {
+              balances: expiry.balances.map((b) => ({
+                ...b,
+                availableLabel: formatPrice(b.available, b.currency, locale),
+                pendingLabel: formatPrice(b.pending, b.currency, locale),
+              })),
+            }
+          : {}),
+      };
     } else if (!policy || policy.mode === "stripe_managed") {
       state.status = "stripe_managed";
       state.message =