@fantastic.dev/better-stripe 0.28.3 → 0.28.5

package/src/component/_generated/component.ts

@@ -2790,6 +2790,44 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        beginHoldingExpiry: FunctionReference<
+          "mutation",
+          "internal",
+          { accountId: string; ownerKey: string },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            country: string;
+            holdDeadline?: number;
+            holdingExpiry?: {
+              balances?: Array<{
+                available: number;
+                currency: string;
+                pending: number;
+              }>;
+              deadline: number;
+              observedAt?: number;
+              status:
+                | "unverified"
+                | "balance_remaining"
+                | "claims_unresolved"
+                | "no_held_balance";
+            };
+            mode: "stripe_managed" | "custom";
+            operationKey: string;
+            ownerKey: string;
+            previousSchedule?: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            revision: number;
+            status: "changing" | "ready";
+            thresholds: Array<{ amount: number; currency: string }>;
+          },
+          Name
+        >;
         cancelUnattempted: FunctionReference<
           "mutation",
           "internal",
@@ -2906,6 +2944,55 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        observeHoldingExpiry: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            balances: Array<{
+              available: number;
+              currency: string;
+              pending: number;
+            }>;
+            deadline: number;
+            expectedRevision: number;
+            observedAt: number;
+            ownerKey: string;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            accountId: string;
+            country: string;
+            holdDeadline?: number;
+            holdingExpiry?: {
+              balances?: Array<{
+                available: number;
+                currency: string;
+                pending: number;
+              }>;
+              deadline: number;
+              observedAt?: number;
+              status:
+                | "unverified"
+                | "balance_remaining"
+                | "claims_unresolved"
+                | "no_held_balance";
+            };
+            mode: "stripe_managed" | "custom";
+            operationKey: string;
+            ownerKey: string;
+            previousSchedule?: {
+              interval: "daily" | "weekly" | "monthly" | "manual";
+              monthlyDays?: Array<number>;
+              weeklyDays?: Array<string>;
+            };
+            revision: number;
+            status: "changing" | "ready";
+            thresholds: Array<{ amount: number; currency: string }>;
+          },
+          Name
+        >;
         prepare: FunctionReference<
           "mutation",
           "internal",
@@ -3007,6 +3094,20 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               accountId: string;
               country: string;
               holdDeadline?: number;
+              holdingExpiry?: {
+                balances?: Array<{
+                  available: number;
+                  currency: string;
+                  pending: number;
+                }>;
+                deadline: number;
+                observedAt?: number;
+                status:
+                  | "unverified"
+                  | "balance_remaining"
+                  | "claims_unresolved"
+                  | "no_held_balance";
+              };
               mode: "stripe_managed" | "custom";
               operationKey: string;
               ownerKey: string;
@@ -3032,6 +3133,20 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             accountId: string;
             country: string;
             holdDeadline?: number;
+            holdingExpiry?: {
+              balances?: Array<{
+                available: number;
+                currency: string;
+                pending: number;
+              }>;
+              deadline: number;
+              observedAt?: number;
+              status:
+                | "unverified"
+                | "balance_remaining"
+                | "claims_unresolved"
+                | "no_held_balance";
+            };
             mode: "stripe_managed" | "custom";
             operationKey: string;
             ownerKey: string;
@@ -3997,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;
@@ -4031,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;
@@ -4063,6 +4180,20 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               accountId: string;
               country: string;
               holdDeadline?: number;
+              holdingExpiry?: {
+                balances?: Array<{
+                  available: number;
+                  currency: string;
+                  pending: number;
+                }>;
+                deadline: number;
+                observedAt?: number;
+                status:
+                  | "unverified"
+                  | "balance_remaining"
+                  | "claims_unresolved"
+                  | "no_held_balance";
+              };
               mode: "stripe_managed" | "custom";
               operationKey: string;
               ownerKey: string;
@@ -4094,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;
@@ -4124,6 +4256,20 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               accountId: string;
               country: string;
               holdDeadline?: number;
+              holdingExpiry?: {
+                balances?: Array<{
+                  available: number;
+                  currency: string;
+                  pending: number;
+                }>;
+                deadline: number;
+                observedAt?: number;
+                status:
+                  | "unverified"
+                  | "balance_remaining"
+                  | "claims_unresolved"
+                  | "no_held_balance";
+              };
               mode: "stripe_managed" | "custom";
               operationKey: string;
               ownerKey: string;
@@ -4167,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/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/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>
+  );
+}