@fantastic.dev/better-stripe 0.28.3 → 0.28.5

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/connect/payoutWorker.test.ts

@@ -3,7 +3,7 @@ import { afterEach, expect, it, vi } from "vitest";
 import type Stripe from "stripe";
 import { setup, scope, component } from "./payoutExecutionTestHelpers.js";
 import { reconcileRecipientPayout } from "./payoutReconciliation.js";
-import { PayoutWorkerClient } from "./payoutWorker.js";
+import { PayoutWorkerClient, payoutAttemptStatus } from "./payoutWorker.js";
 import { changeBalance } from "../../component/affiliateRecovery/accounting.js";
 afterEach(() => vi.useRealTimers());
 async function worker(amounts?: number[]) {
@@ -143,3 +143,59 @@ it("reports affiliate recovery holds before a fresh attempt without creating a p
   });
   expect(s.provider.payouts.create).not.toHaveBeenCalled();
 });
+
+it.each(["balance_insufficient", "amount_too_small"])(
+  "persists actionable %s rejection and its result time",
+  async (code) => {
+    const s = await worker();
+    s.provider.payouts.create.mockRejectedValueOnce(
+      Object.assign(new Error(code), {
+        type: "StripeInvalidRequestError",
+        code,
+        requestId: "req_rejected",
+      }),
+    );
+    expect(await s.run()).toMatchObject({
+      job: { lastReason: code, lastResultAt: expect.any(Number) },
+      payout: { claim: { status: "rejected", rejection: { code } } },
+    });
+  },
+);
+
+it("does not reuse a prior paid result or timestamp for a newer running generation", async () => {
+  const s = await worker();
+  const result = await s.run();
+  if (result.status !== "completed")
+    throw new Error("Expected completed fixture");
+  const active = {
+    ...result.job,
+    generation: result.job.generation + 1,
+    completedGeneration: result.job.generation,
+    hasOperation: true,
+    operationKey: "new-operation",
+    lastReason: "paid",
+    lastResultAt: 1000,
+    lastAttemptAt: 2000,
+    leaseUntil: 3000,
+  };
+  expect(payoutAttemptStatus(active, 2100)).toEqual({
+    currency: "usd",
+    status: "running",
+    reason: "pending_claim",
+    at: 2000,
+  });
+  expect(payoutAttemptStatus(active, 4000)).toEqual({
+    currency: "usd",
+    status: "reconciling",
+    reason: "pending_claim",
+  });
+});
+it("keeps legacy result times unknown rather than inventing a completion time", async () => {
+  const s = await worker();
+  const result = await s.run();
+  if (result.status !== "completed")
+    throw new Error("Expected completed fixture");
+  expect(
+    payoutAttemptStatus({ ...result.job, lastResultAt: undefined }),
+  ).toEqual({ currency: "usd", status: "paid", reason: "paid" });
+});

package/src/client/connect/payoutWorker.ts

@@ -1,5 +1,8 @@
 import type { Infer } from "convex/values";
-import type { jobDoc } from "../../component/payoutWorker/schema.js";
+import type {
+  jobDoc,
+  attemptStatus,
+} from "../../component/payoutWorker/schema.js";
 import type { policyDoc } from "../../component/payoutPolicy/schema.js";
 import type { Component, RunCtx } from "../helpers.js";
 import { runMutationOrThrow } from "../helpers.js";
@@ -138,7 +141,48 @@ export class PayoutWorkerClient {
       throw error;
     }
     const reason =
-      payout.status === "held" ? payout.reason : payout.claim.status;
+      payout.status === "held"
+        ? payout.reason
+        : (payout.claim.rejection?.code ?? payout.claim.status);
     return { status: "completed", job: await finish(reason), payout };
   }
 }
+
+export type PayoutAttempt = Infer<typeof attemptStatus>;
+/** Current lease and generation take precedence over a prior result. Legacy timestamps remain unknown. */
+export function payoutAttemptStatus(
+  job: PayoutWorkerJob | null,
+  now = Date.now(),
+): PayoutAttempt | null {
+  if (!job || (!job.hasOperation && !job.lastReason)) return null;
+  const completed = job.completedGeneration === job.generation;
+  const running = job.hasOperation && (job.leaseUntil ?? 0) > now;
+  const reason =
+    job.hasOperation && !completed
+      ? "pending_claim"
+      : (job.lastReason ?? "pending_claim");
+  const status = running
+    ? "running"
+    : job.hasOperation
+      ? "reconciling"
+      : ["balance_insufficient", "amount_too_small", "rejected"].includes(
+            reason,
+          )
+        ? "rejected"
+        : reason === "paid"
+          ? "paid"
+          : ["worker_error", "returned"].includes(reason)
+            ? "failed"
+            : "held";
+  const at = running
+    ? job.lastAttemptAt
+    : job.hasOperation && !completed
+      ? undefined
+      : job.lastResultAt;
+  return {
+    currency: job.currency,
+    status,
+    reason,
+    ...(at === undefined ? {} : { at }),
+  };
+}

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,7 @@
+export { payoutAttemptStatus } from "./connect/payoutWorker.js";
+export { attemptStatus as payoutAttemptValidator } from "../component/payoutWorker/schema.js";
+export { holdingExpiry as payoutHoldingExpiryValidator } from "../component/payoutPolicy/schema.js";
+import { expirePayoutPolicy } from "./connect/payoutExpiry.js";
 import {
   previewRecipientPayout,
   type PayoutPreviewOptions,
@@ -570,28 +574,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,6 +47,7 @@ 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";
@@ -132,6 +133,7 @@ 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;