@fantastic.dev/better-stripe 0.28.2 → 0.28.4

package/src/client/connect/payoutExpiry.ts

@@ -0,0 +1,132 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import type { policyDoc } from "../../component/payoutPolicy/schema.js";
+type Scope = { accountId: string; ownerKey: string };
+type Policy = Infer<typeof policyDoc>;
+function expiryBalances(balance: Stripe.Balance) {
+  const values = new Map<
+    string,
+    { currency: string; available: number; pending: number }
+  >();
+  for (const type of ["available", "pending"] as const) {
+    const seen = new Set<string>();
+    for (const row of balance[type]) {
+      if (
+        !/^[a-z]{3}$/.test(row.currency) ||
+        !Number.isSafeInteger(row.amount) ||
+        seen.has(row.currency)
+      )
+        throw new Error("Invalid expiry balance.");
+      seen.add(row.currency);
+      const value = values.get(row.currency) ?? {
+        currency: row.currency,
+        available: 0,
+        pending: 0,
+      };
+      value[type] = row.amount;
+      values.set(row.currency, value);
+    }
+  }
+  return [...values.values()].sort((a, b) =>
+    a.currency.localeCompare(b.currency),
+  );
+}
+/** Restore controls, then separately verify remaining balances and durable claims. Never creates a payout. */
+export async function expirePayoutPolicy<
+  R extends { status: string },
+  P extends { status: string },
+>(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  scope: Scope,
+  client: {
+    get(ctx: RunCtx, scope: Scope): Promise<Policy | null>;
+    apply(ctx: RunCtx, args: Scope & { operationKey: string }): Promise<R>;
+    prepare(
+      ctx: RunCtx,
+      args: Scope & {
+        operationKey: string;
+        expectedRevision: number;
+        mode: "stripe_managed";
+        thresholds: [];
+      },
+    ): Promise<P>;
+  },
+) {
+  scope = { accountId: scope.accountId, ownerKey: scope.ownerKey };
+  let policy = await client.get(ctx, scope);
+  if (!policy?.holdDeadline || policy.holdDeadline > Date.now())
+    return { status: "not_due" as const };
+  if (policy.mode === "custom")
+    policy = (await runMutationOrThrow(
+      ctx,
+      componentRef(component, "payoutPolicy/mutations/beginHoldingExpiry"),
+      scope,
+    )) as Policy;
+  if (policy.status === "changing") {
+    const result = await client.apply(ctx, {
+      ...scope,
+      operationKey: policy.operationKey,
+    });
+    if (result.status !== "ready") return result;
+    policy = await client.get(ctx, scope);
+  }
+  if (!policy) return { status: "not_due" as const };
+  if (policy.mode === "custom") {
+    const operationKey = `bs:payout-expiry:${scope.accountId}:${policy.revision}`;
+    const prepared = await client.prepare(ctx, {
+      ...scope,
+      operationKey,
+      expectedRevision: policy.revision,
+      mode: "stripe_managed",
+      thresholds: [],
+    });
+    if (prepared.status !== "prepared") return prepared;
+    const applied = await client.apply(ctx, { ...scope, operationKey });
+    if (applied.status !== "ready") return applied;
+    policy = await client.get(ctx, scope);
+  }
+  if (
+    !policy?.holdingExpiry ||
+    policy.mode !== "stripe_managed" ||
+    policy.status !== "ready"
+  )
+    return { status: "not_due" as const };
+  const unresolved = {
+    status: "expiry_unresolved" as const,
+    holdingExpiry: policy.holdingExpiry,
+  };
+  let balances;
+  const observedAt = Date.now();
+  try {
+    balances = expiryBalances(
+      await stripe.balance.retrieve(undefined, {
+        stripeAccount: scope.accountId,
+      }),
+    );
+  } catch {
+    return unresolved;
+  }
+  if (Date.now() - observedAt > 30000) return unresolved;
+  const observed = (await runMutationOrThrow(
+    ctx,
+    componentRef(component, "payoutPolicy/mutations/observeHoldingExpiry"),
+    {
+      ...scope,
+      expectedRevision: policy.revision,
+      deadline: policy.holdingExpiry.deadline,
+      observedAt,
+      balances,
+    },
+  )) as Policy;
+  if (observed.holdingExpiry!.status !== "no_held_balance")
+    return {
+      status: "expiry_unresolved" as const,
+      holdingExpiry: observed.holdingExpiry!,
+    };
+  return client.apply(ctx, { ...scope, operationKey: policy.operationKey });
+}

package/src/client/payoutPolicy.test.ts

@@ -381,3 +381,199 @@ it("requires adoption for historical payouts even when today's balance is zero",
   expect(provider.balanceSettings.update).not.toHaveBeenCalled();
   expect(await client.get(ctx, scope)).toBeNull();
 });
+
+async function expiredRecipient() {
+  const s = await setup();
+  await s.client.prepare(s.ctx, options);
+  await s.client.apply(s.ctx, { ...scope, operationKey: "enable" });
+  const deadline = Date.now() - 1;
+  await s.t.run(async (ctx) => {
+    const p = (await ctx.db.query("payoutPolicies").first())!;
+    await ctx.db.patch(p._id, { holdDeadline: deadline });
+  });
+  return { ...s, deadline };
+}
+it("keeps funded expiry discoverable after restoring weekly controls until fresh balances clear", async () => {
+  const s = await expiredRecipient();
+  s.provider.balance.retrieve.mockResolvedValue({
+    available: [{ currency: "usd", amount: 999 }],
+    pending: [],
+  });
+  expect(await s.client.expire(s.ctx, scope)).toMatchObject({
+    status: "expiry_unresolved",
+  });
+  expect(await s.client.get(s.ctx, scope)).toMatchObject({
+    mode: "stripe_managed",
+    status: "ready",
+    holdDeadline: s.deadline,
+    holdingExpiry: {
+      deadline: s.deadline,
+      status: "balance_remaining",
+      balances: [{ currency: "usd", available: 999, pending: 0 }],
+    },
+  });
+  expect(
+    (await s.client.due(s.ctx, { cursor: null, numItems: 10 })).page,
+  ).toHaveLength(1);
+  await s.client.expire(s.ctx, scope);
+  expect(s.provider.balanceSettings.update).toHaveBeenCalledTimes(2);
+  s.provider.balance.retrieve.mockResolvedValue({
+    available: [{ currency: "usd", amount: 0 }],
+    pending: [],
+  });
+  expect(await s.client.expire(s.ctx, scope)).toMatchObject({
+    status: "ready",
+  });
+  expect((await s.client.get(s.ctx, scope))!.holdDeadline).toBeUndefined();
+  expect((await s.client.get(s.ctx, scope))!.holdingExpiry).toMatchObject({
+    status: "no_held_balance",
+    deadline: s.deadline,
+  });
+  expect(
+    (await s.client.due(s.ctx, { cursor: null, numItems: 10 })).page,
+  ).toHaveLength(0);
+});
+it("restores controls even if expiry balance verification is unavailable, without fabricating zero", async () => {
+  const s = await expiredRecipient();
+  s.provider.balance.retrieve.mockRejectedValue(
+    new Error("provider unavailable"),
+  );
+  expect(await s.client.expire(s.ctx, scope)).toMatchObject({
+    status: "expiry_unresolved",
+  });
+  const p = await s.client.get(s.ctx, scope);
+  expect(p).toMatchObject({
+    mode: "stripe_managed",
+    holdDeadline: s.deadline,
+    holdingExpiry: { status: "unverified" },
+  });
+  expect(p!.holdingExpiry!.balances).toBeUndefined();
+  expect(
+    (await s.provider.balanceSettings.retrieve()).payments.payouts.schedule
+      .interval,
+  ).toBe("weekly");
+});
+it("does not clear an unknown payout claim at expiry even when Stripe balance is zero", async () => {
+  const s = await expiredRecipient();
+  const id = await s.t.run((ctx) =>
+    ctx.db.insert("payoutReleaseClaims", {
+      ...scope,
+      operationKey: "unknown-payout",
+      expectedRevision: 0,
+      amount: 999,
+      currency: "usd",
+      allocations: [],
+      observations: [],
+      status: "reserved",
+      attemptedAt: Date.now(),
+    }),
+  );
+  expect(await s.client.expire(s.ctx, scope)).toMatchObject({
+    status: "expiry_unresolved",
+  });
+  expect((await s.client.get(s.ctx, scope))!.holdingExpiry).toMatchObject({
+    status: "claims_unresolved",
+  });
+  expect(await s.t.run((ctx) => ctx.db.get(id))).toMatchObject({
+    status: "reserved",
+    amount: 999,
+  });
+  await expect(
+    s.client.prepare(s.ctx, {
+      ...options,
+      expectedRevision: 1,
+      operationKey: "reactivate",
+    }),
+  ).rejects.toThrow(/expiry.*recovery/i);
+});
+it("does not net currencies or pending funds when checking expiry recovery", async () => {
+  const s = await expiredRecipient();
+  s.provider.balance.retrieve.mockResolvedValue({
+    available: [
+      { currency: "usd", amount: 100 },
+      { currency: "eur", amount: -100 },
+    ],
+    pending: [{ currency: "usd", amount: 25 }],
+  });
+  expect(await s.client.expire(s.ctx, scope)).toMatchObject({
+    status: "expiry_unresolved",
+  });
+  expect((await s.client.get(s.ctx, scope))!.holdingExpiry!.balances).toEqual([
+    { currency: "eur", available: -100, pending: 0 },
+    { currency: "usd", available: 100, pending: 25 },
+  ]);
+});
+
+it("does not label a delayed expiry balance response as a fresh observation", async () => {
+  vi.useFakeTimers();
+  try {
+    const s = await expiredRecipient();
+    s.provider.balance.retrieve.mockImplementation(async () => {
+      vi.advanceTimersByTime(31000);
+      return { available: [{ currency: "usd", amount: 0 }], pending: [] };
+    });
+    expect(await s.client.expire(s.ctx, scope)).toMatchObject({
+      status: "expiry_unresolved",
+    });
+    expect((await s.client.get(s.ctx, scope))!.holdingExpiry).toMatchObject({
+      status: "unverified",
+    });
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+it("retries a lost recovery write without losing its original deadline or restoring twice", async () => {
+  const s = await expiredRecipient();
+  const write = s.ctx.runMutation!;
+  s.ctx.runMutation = (async (ref: Record<symbol, string>, args: never) => {
+    if (ref[symbol].endsWith("/observeHoldingExpiry"))
+      throw new Error("recovery write failed");
+    return write(ref as never, args);
+  }) as never;
+  await expect(s.client.expire(s.ctx, scope)).rejects.toThrow(
+    /recovery write failed/,
+  );
+  expect(await s.client.get(s.ctx, scope)).toMatchObject({
+    mode: "stripe_managed",
+    holdDeadline: s.deadline,
+    holdingExpiry: { status: "unverified" },
+  });
+  s.ctx.runMutation = write;
+  expect(await s.client.expire(s.ctx, scope)).toMatchObject({
+    status: "ready",
+  });
+  expect(s.provider.balanceSettings.update).toHaveBeenCalledTimes(2);
+});
+it("concurrent expiry retries preserve one restoration identity and unresolved funds", async () => {
+  const s = await expiredRecipient();
+  s.provider.balance.retrieve.mockResolvedValue({
+    available: [{ currency: "usd", amount: 999 }],
+    pending: [],
+  });
+  const results = await Promise.allSettled([
+    s.client.expire(s.ctx, scope),
+    s.client.expire(s.ctx, scope),
+  ]);
+  expect(results.some((r) => r.status === "fulfilled")).toBe(true);
+  expect(await s.client.expire(s.ctx, scope)).toMatchObject({
+    status: "expiry_unresolved",
+  });
+  expect(await s.client.get(s.ctx, scope)).toMatchObject({
+    mode: "stripe_managed",
+    holdDeadline: s.deadline,
+    holdingExpiry: { status: "balance_remaining" },
+  });
+  const restoreKeys = s.provider.balanceSettings.update.mock.calls
+    .slice(1)
+    .map((c) => (c[1] as { idempotencyKey: string }).idempotencyKey);
+  expect(new Set(restoreKeys).size).toBe(1);
+});
+
+it("accepts a due policy document as scope without forwarding its extra fields to mutations", async () => {
+  const s = await expiredRecipient();
+  const policy = (await s.client.get(s.ctx, scope))!;
+  expect(await s.client.expire(s.ctx, policy)).toMatchObject({
+    status: "ready",
+  });
+});

package/src/client/payoutPolicy.ts

@@ -1,3 +1,5 @@
+export { holdingExpiry as payoutHoldingExpiryValidator } from "../component/payoutPolicy/schema.js";
+import { expirePayoutPolicy } from "./connect/payoutExpiry.js";
 import {
   previewRecipientPayout,
   type PayoutPreviewOptions,
@@ -570,28 +572,12 @@ export class PayoutPolicyClient {
   }
   /** A host cron must page due() and call expire(); payout execution is a separate boundary. */
   async expire(ctx: RunCtx, scope: PayoutPolicyScope) {
-    let policy = await this.get(ctx, scope);
-    if (!policy?.holdDeadline || policy.holdDeadline > Date.now())
-      return { status: "not_due" as const };
-    if (policy.status === "changing") {
-      const result = await this.apply(ctx, {
-        ...scope,
-        operationKey: policy.operationKey,
-      });
-      if (result.status !== "ready") return result;
-      policy = await this.get(ctx, scope);
-    }
-    if (!policy || policy.mode !== "custom")
-      return { status: "not_due" as const };
-    const operationKey = `bs:payout-expiry:${scope.accountId}:${policy.revision}`;
-    const prepared = await this.prepare(ctx, {
-      ...scope,
-      operationKey,
-      expectedRevision: policy.revision,
-      mode: "stripe_managed",
-      thresholds: [],
-    });
-    if (prepared.status !== "prepared") return prepared;
-    return this.apply(ctx, { ...scope, operationKey });
+    return expirePayoutPolicy(
+      this.provider(),
+      this.component,
+      ctx,
+      scope,
+      this,
+    );
   }
 }

package/src/component/_generated/api.ts

@@ -47,12 +47,14 @@ import type * as lib_paymentSeller from "../lib/paymentSeller.js";
 import type * as lib_reversals from "../lib/reversals.js";
 import type * as lib_stripeFactory from "../lib/stripeFactory.js";
 import type * as payoutPolicy_adoption from "../payoutPolicy/adoption.js";
+import type * as payoutPolicy_expiry from "../payoutPolicy/expiry.js";
 import type * as payoutPolicy_helpers from "../payoutPolicy/helpers.js";
 import type * as payoutPolicy_mutations from "../payoutPolicy/mutations.js";
 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";
@@ -131,12 +133,14 @@ const fullApi: ApiFromModules<{
   "lib/reversals": typeof lib_reversals;
   "lib/stripeFactory": typeof lib_stripeFactory;
   "payoutPolicy/adoption": typeof payoutPolicy_adoption;
+  "payoutPolicy/expiry": typeof payoutPolicy_expiry;
   "payoutPolicy/helpers": typeof payoutPolicy_helpers;
   "payoutPolicy/mutations": typeof payoutPolicy_mutations;
   "payoutPolicy/queries": typeof payoutPolicy_queries;
   "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

@@ -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;
@@ -3639,8 +3754,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;
@@ -4061,6 +4178,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;
@@ -4122,6 +4253,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;