@fantastic.dev/better-stripe 0.26.0 → 0.28.0

package/src/component/_generated/api.ts

@@ -52,12 +52,14 @@ 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_fees from "../payoutRelease/fees.js";
 import type * as payoutRelease_helpers from "../payoutRelease/helpers.js";
 import type * as payoutRelease_mutations from "../payoutRelease/mutations.js";
 import type * as payoutRelease_observation from "../payoutRelease/observation.js";
 import type * as payoutRelease_planning from "../payoutRelease/planning.js";
 import type * as payoutRelease_preview from "../payoutRelease/preview.js";
+import type * as payoutRelease_progress from "../payoutRelease/progress.js";
 import type * as payoutRelease_queries from "../payoutRelease/queries.js";
 import type * as payoutSnapshots_localState from "../payoutSnapshots/localState.js";
 import type * as payoutSnapshots_mutations from "../payoutSnapshots/mutations.js";
@@ -134,12 +136,14 @@ const fullApi: ApiFromModules<{
   "payoutPolicy/queries": typeof payoutPolicy_queries;
   "payoutRelease/adoption": typeof payoutRelease_adoption;
   "payoutRelease/allocation": typeof payoutRelease_allocation;
+  "payoutRelease/allocationTotals": typeof payoutRelease_allocationTotals;
   "payoutRelease/fees": typeof payoutRelease_fees;
   "payoutRelease/helpers": typeof payoutRelease_helpers;
   "payoutRelease/mutations": typeof payoutRelease_mutations;
   "payoutRelease/observation": typeof payoutRelease_observation;
   "payoutRelease/planning": typeof payoutRelease_planning;
   "payoutRelease/preview": typeof payoutRelease_preview;
+  "payoutRelease/progress": typeof payoutRelease_progress;
   "payoutRelease/queries": typeof payoutRelease_queries;
   "payoutSnapshots/localState": typeof payoutSnapshots_localState;
   "payoutSnapshots/mutations": typeof payoutSnapshots_mutations;

package/src/component/_generated/component.ts

@@ -3630,6 +3630,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           | { amount: 0; reason: string; status: "held" }
           | {
+              accounting?: {
+                carriedForwardAmount: number;
+                releasedAmount: number;
+                reservedAmount: number;
+                withheldAmount: number;
+              };
               amount: number;
               confirmedFees: number;
               currency: string;
@@ -3643,6 +3649,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               sources: Array<{
                 matureUnpaid: number;
                 pendingCredits: number;
+                releasedAmount?: number;
+                reservedAmount?: number;
                 role: "store" | "affiliate" | "other";
               }>;
               status: "held" | "qualified";

package/src/component/payoutPolicy/helpers.ts

@@ -55,7 +55,9 @@ export function canonicalThresholds(
     )
   )
     throw new Error("Invalid custom payout thresholds.");
-  return [...values].sort((a, b) => a.currency.localeCompare(b.currency));
+  return values
+    .map(({ currency, amount }) => ({ currency, amount }))
+    .sort((a, b) => a.currency.localeCompare(b.currency));
 }
 export function validateScope(scope: { accountId: string; ownerKey: string }) {
   if (

package/src/component/payoutPolicy/mutations.ts

@@ -52,7 +52,10 @@ export const prepare = mutation({
         old.country !== args.country ||
         old.observedAt !== args.observedAt ||
         Boolean(old.adoption) !== Boolean(args.adoption) ||
-        !same(old.thresholds, args.thresholds) ||
+        !same(
+          canonicalThresholds(old.thresholds, old.mode === "custom"),
+          args.thresholds,
+        ) ||
         !same(old.observedSchedule, args.observedSchedule)
       )
         throw new Error("Payout policy operation identity cannot be reused.");

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/react/workflows/PayoutProgress.test.tsx

@@ -0,0 +1,208 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import type { PayoutPreview } from "../../client/payoutPolicy.js";
+import { PayoutProgress } from "./PayoutProgress.js";
+afterEach(cleanup);
+const policy = {
+  mode: "custom" as const,
+  status: "ready" as const,
+  thresholds: [{ currency: "usd", amount: 1000 }],
+  holdDeadline: 1900000000000,
+};
+const preview: PayoutPreview = {
+  status: "held",
+  reason: "below_threshold",
+  amount: 0,
+  currency: "usd",
+  threshold: 1000,
+  providerMinimum: null,
+  matureUnpaid: 999,
+  pendingCredits: 200,
+  confirmedFees: 0,
+  independentLiabilities: 0,
+  providerAvailable: 999,
+  observedAt: 1800000000000,
+  sources: [
+    { role: "store", matureUnpaid: 599, pendingCredits: 200 },
+    { role: "affiliate", matureUnpaid: 400, pendingCredits: 0 },
+    { role: "other", matureUnpaid: 0, pendingCredits: 0 },
+  ],
+};
+it("shows one combined minimum, pending settlement and source contributions", () => {
+  render(<PayoutProgress policy={policy} preview={preview} currency="usd" />);
+  expect(screen.getByRole("progressbar").getAttribute("max")).toBe("1000");
+  expect(screen.getByRole("progressbar").getAttribute("value")).toBe("999");
+  expect(screen.getByText("$9.99")).toBeTruthy();
+  expect(screen.getByText("$5.99")).toBeTruthy();
+  expect(screen.getByText("$4.00")).toBeTruthy();
+  expect(screen.getByText(/Below-minimum funds remain owed/)).toBeTruthy();
+  expect(
+    screen.queryByRole("button", { name: /withdraw|pay out/i }),
+  ).toBeNull();
+});
+it("does not invent zero balances or progress for an unavailable assessment", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      currency="usd"
+      preview={{
+        status: "held",
+        reason: "unallocated_history",
+        amount: 0,
+      }}
+    />,
+  );
+  expect(screen.getByRole("status").textContent).toContain("reconciliation");
+  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");
+  expect(screen.getByText(/numeric amount is unavailable/)).toBeTruthy();
+  expect(screen.queryByRole("progressbar")).toBeNull();
+  expect(screen.queryByText("$1.00")).toBeNull();
+});
+it("does not reuse a prior assessment while the schedule change is pending", () => {
+  render(
+    <PayoutProgress
+      policy={{ ...policy, status: "changing" }}
+      preview={preview}
+      currency="usd"
+    />,
+  );
+  expect(screen.getByRole("status").textContent).toContain("being verified");
+  expect(screen.queryByRole("progressbar")).toBeNull();
+});
+it("preserves negative entitlement while clamping only the visual progress", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      preview={{ ...preview, matureUnpaid: -100 }}
+      currency="usd"
+    />,
+  );
+  expect(screen.getByText("-$1.00")).toBeTruthy();
+  expect(screen.getByRole("progressbar").getAttribute("value")).toBe("0");
+});
+it("distinguishes the next worker attempt from a bank arrival date", () => {
+  render(
+    <PayoutProgress
+      policy={policy}
+      preview={preview}
+      currency="usd"
+      nextAttemptAt={1800000000000}
+      timeZone="UTC"
+    />,
+  );
+  expect(screen.getByText(/Next automatic attempt:/).textContent).toContain(
+    "not a bank arrival date",
+  );
+  expect(screen.getByText(/Custom holding deadline:/)).toBeTruthy();
+});
+it("rejects another currency or changed threshold instead of displaying mixed progress", () => {
+  expect(() =>
+    render(<PayoutProgress policy={policy} preview={preview} currency="eur" />),
+  ).toThrow("does not match");
+  expect(() =>
+    render(
+      <PayoutProgress
+        policy={{ ...policy, thresholds: [{ currency: "usd", amount: 2000 }] }}
+        preview={preview}
+        currency="usd"
+      />,
+    ),
+  ).toThrow("does not match");
+});
+it("exposes the same financial state for translated host cards", () => {
+  render(
+    <PayoutProgress policy={policy} preview={preview} currency="usd">
+      {(state) => (
+        <article data-testid="custom">
+          {state.status}{" "}
+          {
+            state.metrics.find((metric) => metric.key === "qualifying")
+              ?.formattedValue
+          }
+        </article>
+      )}
+    </PayoutProgress>,
+  );
+  expect(screen.getByTestId("custom").textContent).toBe("assessed $9.99");
+  expect(screen.queryByText("Source contributions")).toBeNull();
+});
+it.each([1000, 1100])(
+  "shows a qualifying combined assessment at %i without separate category minimums",
+  (total) => {
+    render(
+      <PayoutProgress
+        policy={policy}
+        currency="usd"
+        preview={{
+          ...preview,
+          status: "qualified",
+          reason: undefined,
+          amount: total,
+          matureUnpaid: total,
+          sources: [
+            { role: "store", matureUnpaid: total - 400, pendingCredits: 0 },
+            { role: "affiliate", matureUnpaid: 400, pendingCredits: 0 },
+          ],
+        }}
+      />,
+    );
+    expect(screen.getByRole("status").textContent).toContain("qualif");
+    expect(screen.getAllByRole("progressbar")).toHaveLength(1);
+    expect(screen.getByRole("progressbar").getAttribute("value")).toBe("1000");
+  },
+);
+it("does not display a former custom holding deadline for Stripe-managed payouts", () => {
+  render(
+    <PayoutProgress
+      policy={{ ...policy, mode: "stripe_managed" }}
+      currency="usd"
+      preview={preview}
+    />,
+  );
+  expect(screen.queryByText(/Custom holding deadline:/)).toBeNull();
+});

package/src/react/workflows/PayoutProgress.tsx

@@ -0,0 +1,108 @@
+"use client";
+import { useMemo } from "react";
+import {
+  payoutProgressState,
+  type PayoutProgressProps,
+} from "./payout-progress-state.js";
+export type {
+  PayoutProgressMetric,
+  PayoutProgressProps,
+  PayoutProgressState,
+} from "./payout-progress-state.js";
+/** Unstyled, read-only progress. A preview never authorizes or requests a payout. */
+export function PayoutProgress(props: PayoutProgressProps) {
+  const { currency, locale = "en-US", timeZone, className, children } = props;
+  const state = payoutProgressState(props);
+  const formatter = useMemo(
+    () =>
+      new Intl.DateTimeFormat(locale, {
+        dateStyle: "medium",
+        timeStyle: "short",
+        timeZone,
+      }),
+    [locale, timeZone],
+  );
+  if (children) return <>{children(state)}</>;
+  const date = (value: number) => formatter.format(value);
+  return (
+    <section className={className} data-better-stripe="payout-progress">
+      <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.progress && (
+        <progress
+          aria-label="Combined payout minimum"
+          value={state.progress.value}
+          max={state.progress.max}
+        />
+      )}
+      {state.metrics.length > 0 && (
+        <dl>
+          {state.metrics.map((metric) => (
+            <div key={metric.key}>
+              <dt>{metric.label}</dt>
+              <dd>{metric.formattedValue}</dd>
+            </div>
+          ))}
+        </dl>
+      )}
+      {state.sources.length > 0 && (
+        <>
+          <p>
+            All categories contribute to one minimum. Source amounts are before
+            shared costs and obligations. Pending funds do not qualify.
+          </p>
+          <table>
+            <caption>Source contributions</caption>
+            <thead>
+              <tr>
+                <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>
+              {state.sources.map((source) => (
+                <tr key={source.role}>
+                  <th scope="row">
+                    {source.role === "store"
+                      ? "Store"
+                      : source.role === "affiliate"
+                        ? "Affiliate"
+                        : "Other"}
+                  </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
+          bank arrival date.
+        </p>
+      )}
+      {state.holdDeadline !== null && (
+        <p>Custom holding deadline: {date(state.holdDeadline)}</p>
+      )}
+      {state.observedAt !== null && <p>Assessed: {date(state.observedAt)}</p>}
+    </section>
+  );
+}