@fantastic.dev/better-stripe 0.27.0 → 0.28.1

package/src/component/payout-component-pagination.test.ts

@@ -0,0 +1,212 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { expect, it } from "vitest";
+import type {
+  DefaultFunctionArgs,
+  RegisteredQuery,
+  RegisteredMutation,
+} from "convex/server";
+import type { MutationCtx } from "./_generated/server.js";
+import { componentDb } from "../testing/component-db.js";
+import schema from "./schema.js";
+import { policies, changing, recovering } from "./payoutWorker/queries.js";
+import { due } from "./payoutPolicy/queries.js";
+import { pendingPayouts } from "./affiliatePayouts/queries.js";
+import { listClaims } from "./costRecovery/queries.js";
+import { begin, advance } from "./payoutSnapshots/mutations.js";
+const modules = import.meta.glob("./**/*.*s");
+function handler<Args extends DefaultFunctionArgs, Result>(
+  fn:
+    | RegisteredQuery<"public", Args, Result>
+    | RegisteredMutation<"public", Args, Result>,
+) {
+  const run = (
+    fn as unknown as { _handler: (ctx: MutationCtx, args: Args) => Result }
+  )._handler;
+  return (ctx: MutationCtx, args: Args) =>
+    run({ ...ctx, db: componentDb(ctx.db) }, args);
+}
+const options = { numItems: 1, cursor: null };
+const policy = {
+  ownerKey: "owner",
+  mode: "custom" as const,
+  status: "ready" as const,
+  revision: 0,
+  operationKey: "enable",
+  country: "US",
+  thresholds: [{ currency: "usd", amount: 1000 }],
+  holdDeadline: Date.now() - 1,
+};
+it("pages ready, changing and expired policies across the deployed component boundary", async () => {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    for (let i = 0; i < 3; i++)
+      await ctx.db.insert("payoutPolicies", {
+        ...policy,
+        accountId: `acct_${i}`,
+      });
+    await ctx.db.insert("payoutPolicies", {
+      ...policy,
+      accountId: "acct_changing",
+      status: "changing",
+    });
+    await ctx.db.insert("payoutPolicies", {
+      ...policy,
+      accountId: "acct_default",
+      mode: "stripe_managed",
+      holdDeadline: undefined,
+    });
+    const accounts: string[] = [];
+    let cursor: string | null = null;
+    for (let i = 0; i < 6; i++) {
+      const p = await handler(policies)(ctx, {
+        paginationOpts: { ...options, cursor },
+      });
+      accounts.push(...p.page.map((row) => row.accountId));
+      cursor = p.continueCursor;
+      if (p.isDone) break;
+    }
+    expect(accounts).toEqual(["acct_0", "acct_1", "acct_2"]);
+    const changePage = await handler(changing)(ctx, {
+      paginationOpts: options,
+    });
+    expect(changePage.page).toMatchObject([{ accountId: "acct_changing" }]);
+    expect(
+      await handler(changing)(ctx, {
+        paginationOpts: { ...options, cursor: changePage.continueCursor },
+      }),
+    ).toMatchObject({ page: [], isDone: true });
+    const expired: string[] = [];
+    cursor = null;
+    for (let i = 0; i < 6; i++) {
+      const p = await handler(due)(ctx, {
+        now: Date.now(),
+        paginationOpts: { ...options, cursor },
+      });
+      expired.push(...p.page.map((row) => row.accountId));
+      cursor = p.continueCursor;
+      if (p.isDone) break;
+    }
+    expect(expired).toEqual(["acct_0", "acct_1", "acct_2", "acct_changing"]);
+  });
+});
+it("pages only due unresolved worker operations", async () => {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    const base = {
+      accountId: "acct_one",
+      ownerKey: "owner",
+      currency: "usd",
+      generation: 1,
+      sequence: 1,
+      cadenceMs: 60000,
+      nextAttemptAt: Date.now() - 1,
+      hasOperation: true,
+    };
+    for (let i = 0; i < 3; i++)
+      await ctx.db.insert("payoutWorkerJobs", {
+        ...base,
+        accountId: `acct_${i}`,
+      });
+    await ctx.db.insert("payoutWorkerJobs", {
+      ...base,
+      accountId: "acct_future",
+      nextAttemptAt: Date.now() + 86400000,
+    });
+    await ctx.db.insert("payoutWorkerJobs", {
+      ...base,
+      accountId: "acct_idle",
+      hasOperation: false,
+    });
+    const accounts: string[] = [];
+    let cursor: string | null = null;
+    for (let i = 0; i < 6; i++) {
+      const p = await handler(recovering)(ctx, {
+        paginationOpts: { ...options, cursor },
+      });
+      accounts.push(...p.page.map((row) => row.accountId));
+      cursor = p.continueCursor;
+      if (p.isDone) break;
+    }
+    expect(accounts).toEqual(["acct_0", "acct_1", "acct_2"]);
+  });
+});
+it("reads affiliate reconciliation and seller cost history without native pagination", async () => {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    expect(
+      await handler(pendingPayouts)(ctx, {
+        state: "unknown",
+        paginationOpts: options,
+      }),
+    ).toMatchObject({ page: [], isDone: true });
+    expect(
+      await handler(listClaims)(ctx, {
+        accountId: "acct_one",
+        scopeKey: "store_one",
+        currency: "usd",
+        paginationOpts: options,
+      }),
+    ).toMatchObject({ page: [], isDone: true });
+  });
+});
+it("continues every local collection phase across bounded component-compatible pages", async () => {
+  const t = convexTest(schema, modules);
+  const scope = {
+    accountId: "acct_one",
+    ownerKey: "owner",
+    operationKey: "collect",
+  };
+  await t.run(async (ctx) => {
+    for (let i = 0; i < 31; i++)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: `tr_${i}`,
+        destinationAccountId: scope.accountId,
+        amount: 1000,
+        currency: "usd",
+        role: "store",
+        status: "paid",
+      });
+    await ctx.db.insert("payoutSourceAllocations", {
+      accountId: scope.accountId,
+      ownerKey: scope.ownerKey,
+      stripeTransferId: "tr_0",
+      currency: "usd",
+      paidAmount: 10,
+      reservedAmount: 0,
+    });
+    await ctx.db.insert("payoutFeeBalances", {
+      accountId: scope.accountId,
+      ownerKey: scope.ownerKey,
+      currency: "usd",
+      amount: 2,
+      revision: 0,
+    });
+    await ctx.db.insert("payoutReleaseClaims", {
+      ...scope,
+      operationKey: "previous",
+      expectedRevision: 0,
+      currency: "usd",
+      amount: 10,
+      status: "paid",
+      stripePayoutId: "po_previous",
+      allocations: [{ stripeTransferId: "tr_0", amount: 10, role: "store" }],
+      observations: [],
+    });
+    let state = await handler(begin)(ctx, { ...scope, expectedRevision: -1 });
+    for (let i = 0; i < 30 && state.phase !== "local_ready"; i++)
+      state = await handler(advance)(ctx, {
+        ...scope,
+        expectedStep: state.step,
+        batchSize: 5,
+      });
+    expect(state).toMatchObject({
+      phase: "local_ready",
+      sourceCount: 31,
+      allocationCount: 1,
+      claimCount: 1,
+      feeCount: 1,
+      readOnly: true,
+    });
+  });
+});

package/src/component/payoutPolicy/queries.ts

@@ -1,3 +1,5 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 import { query } from "../_generated/server.js";
@@ -41,7 +43,7 @@ export const due = query({
       args.paginationOpts.numItems > 100
     )
       throw new Error("Invalid payout policy due page.");
-    const page = await ctx.db
+    const page = await paginator(ctx.db, schema)
       .query("payoutPolicies")
       .withIndex("by_deadline", (q) =>
         q.gt("holdDeadline", 0).lte("holdDeadline", args.now),

package/src/component/payoutRelease/allocationTotals.ts

@@ -0,0 +1,56 @@
+import type { QueryCtx, MutationCtx } from "../_generated/server.js";
+import type { PayoutFundingSource } from "./allocation.js";
+import { add } from "./helpers.js";
+/** Match the maintained source rollups to all persisted claims before using them as financial facts. */
+export async function assertAllocationTotals(
+  ctx: QueryCtx | MutationCtx,
+  scope: { accountId: string; ownerKey: string },
+  sources: PayoutFundingSource[],
+) {
+  const claims = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_account_status", (q) => q.eq("accountId", scope.accountId))
+    .take(101);
+  if (claims.length > 100)
+    throw new Error("Payout claim snapshot is incomplete.");
+  const totals = new Map(
+    sources.map((source) => [
+      source.stripeTransferId,
+      { source, paid: 0, reserved: 0 },
+    ]),
+  );
+  for (const claim of claims) {
+    if (claim.ownerKey !== scope.ownerKey)
+      throw new Error("Payout claim owner does not match.");
+    let allocated = 0;
+    const seen = new Set<string>();
+    for (const allocation of claim.allocations) {
+      const total = totals.get(allocation.stripeTransferId);
+      if (
+        !total ||
+        total.source.currency !== claim.currency ||
+        seen.has(allocation.stripeTransferId) ||
+        !Number.isSafeInteger(allocation.amount) ||
+        allocation.amount <= 0
+      )
+        throw new Error("Payout claim allocation provenance is invalid.");
+      seen.add(allocation.stripeTransferId);
+      allocated = add(allocated, allocation.amount);
+      if (claim.status === "paid")
+        total.paid = add(total.paid, allocation.amount);
+      if (claim.status === "reserved" || claim.status === "submitted")
+        total.reserved = add(total.reserved, allocation.amount);
+    }
+    if (
+      !Number.isSafeInteger(claim.amount) ||
+      claim.amount <= 0 ||
+      allocated !== claim.amount
+    )
+      throw new Error("Payout claim allocation principal does not match.");
+  }
+  for (const { source, paid, reserved } of totals.values())
+    if (source.paidAmount !== paid || source.reservedAmount !== reserved)
+      throw new Error(
+        "Payout allocation totals do not match persisted claims.",
+      );
+}

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 { assertAllocationTotals } from "./allocationTotals.js";
 export async function readPayoutPlan(
   ctx: MutationCtx | QueryCtx,
   args: {
@@ -43,6 +44,7 @@ export async function readPayoutPlan(
     });
   }
   const fees = await readFees(ctx, args);
+  await assertAllocationTotals(ctx, args, sources);
   const plan = planRecipientPayout({
     currency: args.currency,
     threshold: minimum.amount,

package/src/component/payoutRelease/preview.ts

@@ -6,6 +6,7 @@ import { observation } from "./observation.js";
 import { readyPolicy, add } from "./helpers.js";
 import { readPayoutPlan } from "./planning.js";
 import { balance } from "../affiliateRecovery/accounting.js";
+import { progressAccounting, summarizePayoutProgress } from "./progress.js";
 export const previewFields = {
   ...scopeFields,
   expectedRevision: v.number(),
@@ -34,6 +35,7 @@ export const previewResult = v.union(
     independentLiabilities: v.number(),
     providerAvailable: v.number(),
     observedAt: v.number(),
+    accounting: v.optional(progressAccounting),
     sources: v.array(
       v.object({
         role: v.union(
@@ -43,6 +45,8 @@ export const previewResult = v.union(
         ),
         matureUnpaid: v.number(),
         pendingCredits: v.number(),
+        releasedAmount: v.optional(v.number()),
+        reservedAmount: v.optional(v.number()),
       }),
     ),
   }),
@@ -78,25 +82,11 @@ export async function previewPlan(
     fees,
     threshold,
   } = await readPayoutPlan(ctx, args, policy);
-  const sources = (["store", "affiliate", "other"] as const).map((role) => {
-    let matureUnpaid = 0,
-      pendingCredits = 0;
-    for (const source of funding)
-      if (
-        source.currency === args.currency &&
-        (source.role ?? "other") === role
-      ) {
-        matureUnpaid = add(
-          matureUnpaid,
-          add(
-            add(source.matureNet, -source.paidAmount),
-            -source.reservedAmount,
-          ),
-        );
-        pendingCredits = add(pendingCredits, source.pendingCredits);
-      }
-    return { role, matureUnpaid, pendingCredits };
-  });
+  const progress = summarizePayoutProgress(
+    plan,
+    funding,
+    add(fees?.amount ?? 0, args.independentLiabilities),
+  );
   return {
     status: plan.status,
     ...(plan.status === "held" ? { reason: plan.reason } : {}),
@@ -113,6 +103,6 @@ export async function previewPlan(
       Date.now(),
       ...args.observations.map((o) => o.observedAt),
     ),
-    sources,
+    ...progress,
   };
 }

package/src/component/payoutRelease/progress.test.ts

@@ -0,0 +1,63 @@
+import { expect, it } from "vitest";
+import { planRecipientPayout } from "./allocation.js";
+import { summarizePayoutProgress } from "./progress.js";
+it("keeps paid, reserved, mature and pending amounts in their own currency", () => {
+  const sources = [
+    {
+      stripeTransferId: "tr_usd",
+      currency: "usd",
+      role: "store" as const,
+      matureNet: 1000,
+      paidAmount: 0,
+      reservedAmount: 0,
+      pendingCredits: 0,
+    },
+    {
+      stripeTransferId: "tr_eur",
+      currency: "eur",
+      role: "affiliate" as const,
+      matureNet: 7000,
+      paidAmount: 2000,
+      reservedAmount: 500,
+      pendingCredits: 999,
+    },
+  ];
+  const plan = planRecipientPayout({
+    currency: "usd",
+    threshold: 1000,
+    providerAvailable: 1000,
+    independentLiabilities: 0,
+    sources,
+  });
+  expect(summarizePayoutProgress(plan, sources, 0)).toEqual({
+    accounting: {
+      carriedForwardAmount: 0,
+      withheldAmount: 0,
+      releasedAmount: 0,
+      reservedAmount: 0,
+    },
+    sources: [
+      {
+        role: "store",
+        matureUnpaid: 1000,
+        pendingCredits: 0,
+        releasedAmount: 0,
+        reservedAmount: 0,
+      },
+      {
+        role: "affiliate",
+        matureUnpaid: 0,
+        pendingCredits: 0,
+        releasedAmount: 0,
+        reservedAmount: 0,
+      },
+      {
+        role: "other",
+        matureUnpaid: 0,
+        pendingCredits: 0,
+        releasedAmount: 0,
+        reservedAmount: 0,
+      },
+    ],
+  });
+});

package/src/component/payoutRelease/progress.ts

@@ -0,0 +1,56 @@
+import { v } from "convex/values";
+import type { PayoutFundingSource, RecipientPayoutPlan } from "./allocation.js";
+import { add } from "./helpers.js";
+export const progressAccounting = v.object({
+  carriedForwardAmount: v.number(),
+  withheldAmount: v.number(),
+  reservedAmount: v.number(),
+  releasedAmount: v.number(),
+});
+/** Inputs have passed allocation validation. Shared costs are never attributed to a source category. */
+export function summarizePayoutProgress(
+  plan: RecipientPayoutPlan,
+  funding: PayoutFundingSource[],
+  costs: number,
+) {
+  const sources = (["store", "affiliate", "other"] as const).map((role) => {
+    let matureUnpaid = 0,
+      pendingCredits = 0,
+      releasedAmount = 0,
+      reservedAmount = 0;
+    for (const source of funding)
+      if (
+        source.currency === plan.currency &&
+        (source.role ?? "other") === role
+      ) {
+        matureUnpaid = add(
+          matureUnpaid,
+          add(
+            add(source.matureNet, -source.paidAmount),
+            -source.reservedAmount,
+          ),
+        );
+        pendingCredits = add(pendingCredits, source.pendingCredits);
+        releasedAmount = add(releasedAmount, source.paidAmount);
+        reservedAmount = add(reservedAmount, source.reservedAmount);
+      }
+    return {
+      role,
+      matureUnpaid,
+      pendingCredits,
+      releasedAmount,
+      reservedAmount,
+    };
+  });
+  const total = (field: "matureUnpaid" | "releasedAmount" | "reservedAmount") =>
+    sources.reduce((sum, source) => add(sum, source[field]), 0);
+  return {
+    sources,
+    accounting: {
+      carriedForwardAmount: Math.max(0, add(plan.matureUnpaid, -plan.amount)),
+      withheldAmount: Math.min(Math.max(0, total("matureUnpaid")), costs),
+      reservedAmount: total("reservedAmount"),
+      releasedAmount: total("releasedAmount"),
+    },
+  };
+}

package/src/component/payoutSnapshots/mutations.ts

@@ -1,3 +1,5 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
 import { v } from "convex/values";
 import { mutation } from "../earnings/triggers.js";
 import { readPolicy } from "../payoutPolicy/helpers.js";
@@ -119,7 +121,7 @@ export const advance = mutation({
     const patch: Partial<Snapshot> = { step: h.step + 1 };
     try {
       if (h.phase === "sources") {
-        const page = await ctx.db
+        const page = await paginator(ctx.db, schema)
           .query("transfers")
           .withIndex("by_destination_account_id", (q) =>
             q
@@ -132,7 +134,7 @@ export const advance = mutation({
         patch.sourceCursor = page.continueCursor;
         patch.phase = page.isDone ? "allocations" : "sources";
       } else if (h.phase === "allocations") {
-        const page = await ctx.db
+        const page = await paginator(ctx.db, schema)
           .query("payoutSourceAllocations")
           .withIndex("by_account", (q) => q.eq("accountId", h!.accountId))
           .paginate({ cursor: h.allocationCursor ?? null, numItems: batch });
@@ -141,7 +143,7 @@ export const advance = mutation({
         patch.allocationCursor = page.continueCursor;
         patch.phase = page.isDone ? "fees" : "allocations";
       } else if (h.phase === "fees") {
-        const page = await ctx.db
+        const page = await paginator(ctx.db, schema)
           .query("payoutFeeBalances")
           .withIndex("by_account_currency", (q) =>
             q.eq("accountId", h!.accountId),
@@ -152,7 +154,7 @@ export const advance = mutation({
         patch.feeCursor = page.continueCursor;
         patch.phase = page.isDone ? "claims" : "fees";
       } else if (h.phase === "claims") {
-        const page = await ctx.db
+        const page = await paginator(ctx.db, schema)
           .query("payoutReleaseClaims")
           .withIndex("by_account_status", (q) =>
             q.eq("accountId", h!.accountId),

package/src/component/payoutWorker/queries.ts

@@ -1,3 +1,5 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 import { query } from "../_generated/server.js";
@@ -18,7 +20,7 @@ export const policies = query({
   }),
   handler: async (ctx, args) => {
     pageSize(args.paginationOpts.numItems);
-    const p = await ctx.db
+    const p = await paginator(ctx.db, schema)
       .query("payoutPolicies")
       .withIndex("by_mode_status", (q) =>
         q.eq("mode", "custom").eq("status", "ready"),
@@ -36,7 +38,7 @@ export const changing = query({
   }),
   handler: async (ctx, args) => {
     pageSize(args.paginationOpts.numItems);
-    const p = await ctx.db
+    const p = await paginator(ctx.db, schema)
       .query("payoutPolicies")
       .withIndex("by_status", (q) => q.eq("status", "changing"))
       .paginate(args.paginationOpts);
@@ -53,7 +55,7 @@ export const recovering = query({
   }),
   handler: async (ctx, args) => {
     pageSize(args.paginationOpts.numItems);
-    const p = await ctx.db
+    const p = await paginator(ctx.db, schema)
       .query("payoutWorkerJobs")
       .withIndex("by_operation_pending", (q) =>
         q.eq("hasOperation", true).lte("nextAttemptAt", Date.now()),

package/src/react/workflows/PayoutProgress.test.tsx

@@ -57,6 +57,45 @@ it("does not invent zero balances or progress for an unavailable assessment", ()
   expect(screen.queryByRole("progressbar")).toBeNull();
   expect(screen.queryByText("$0.00")).toBeNull();
 });
+it("shows verified carry forward, withholding, in-flight and paid totals separately", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      currency="usd"
+      preview={{
+        ...preview,
+        matureUnpaid: 899,
+        independentLiabilities: 100,
+        accounting: {
+          carriedForwardAmount: 899,
+          withheldAmount: 100,
+          reservedAmount: 200,
+          releasedAmount: 1000,
+        },
+        sources: [
+          { ...preview.sources[0], reservedAmount: 100, releasedAmount: 600 },
+          { ...preview.sources[1], reservedAmount: 100, releasedAmount: 400 },
+          { ...preview.sources[2], reservedAmount: 0, releasedAmount: 0 },
+        ],
+      }}
+    />,
+  );
+  for (const [label, value] of [
+    ["Carried forward", "$8.99"],
+    ["Withheld for costs", "$1.00"],
+    ["Payouts in progress", "$2.00"],
+    ["Paid out, net of returns", "$10.00"],
+  ])
+    expect(screen.getByText(label).nextElementSibling?.textContent).toBe(value);
+  expect(screen.getByRole("columnheader", { name: "Paid out" })).toBeTruthy();
+  expect(screen.getByRole("columnheader", { name: "In flight" })).toBeTruthy();
+});
+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();
+  expect(screen.queryByText("Paid out, net of returns")).toBeNull();
+  expect(screen.queryByRole("columnheader", { name: "Paid out" })).toBeNull();
+});
 it("keeps Stripe-managed defaults distinct from a custom application minimum", () => {
   render(<PayoutProgress policy={null} currency="usd" />);
   expect(screen.getByRole("status").textContent).toContain("Stripe manages");

package/src/react/workflows/PayoutProgress.tsx

@@ -59,6 +59,8 @@ export function PayoutProgress(props: PayoutProgressProps) {
                 <th scope="col">Source</th>
                 <th scope="col">Mature unpaid</th>
                 <th scope="col">Pending settlement</th>
+                {state.accounting && <th scope="col">In flight</th>}
+                {state.accounting && <th scope="col">Paid out</th>}
               </tr>
             </thead>
             <tbody>
@@ -73,12 +75,24 @@ export function PayoutProgress(props: PayoutProgressProps) {
                   </th>
                   <td>{source.matureLabel}</td>
                   <td>{source.pendingLabel}</td>
+                  {state.accounting && (
+                    <td>{source.reservedLabel ?? "Not assessed"}</td>
+                  )}
+                  {state.accounting && (
+                    <td>{source.releasedLabel ?? "Not assessed"}</td>
+                  )}
                 </tr>
               ))}
             </tbody>
           </table>
         </>
       )}
+      {state.accounting && (
+        <p>
+          Carried-forward funds remain owed. In-flight payouts are separate from
+          completed payouts. Paid-out amounts exclude returned payouts.
+        </p>
+      )}
       {state.nextAttemptAt !== null && (
         <p>
           Next automatic attempt: {date(state.nextAttemptAt)}. This is not a