@fantastic.dev/better-stripe 0.25.1 → 0.27.0

package/src/client/payoutPolicy.test.ts

@@ -126,6 +126,19 @@ it("persists original provider settings, verifies manual schedule and restores o
   });
   expect((await client.get(ctx, scope))!.mode).toBe("stripe_managed");
 });
+it("replays equivalent threshold objects regardless of transport property order", async () => {
+  const { client, ctx, provider } = await setup();
+  expect((await client.prepare(ctx, options)).status).toBe("prepared");
+  expect(
+    (
+      await client.prepare(ctx, {
+        ...options,
+        thresholds: [{ amount: 1000, currency: "usd" }],
+      })
+    ).status,
+  ).toBe("prepared");
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+});
 it("recovers provider success after a failed persistence write without changing the request", async () => {
   const { client, ctx, provider } = await setup();
   await client.prepare(ctx, options);

package/src/client/payoutPolicy.ts

@@ -1,3 +1,9 @@
+import {
+  previewRecipientPayout,
+  type PayoutPreviewOptions,
+} from "./connect/payoutPreview.js";
+export type * from "./connect/payoutPreview.js";
+export { previewResult as payoutPreviewValidator } from "../component/payoutRelease/preview.js";
 import { PayoutWorkerClient } from "./connect/payoutWorker.js";
 export type * from "./connect/payoutWorker.js";
 import {
@@ -107,6 +113,15 @@ const toProvider = (
 /** Host authenticates owner/policy/consent. Provider I/O stays in this package. */
 export class PayoutPolicyClient {
   readonly worker: PayoutWorkerClient;
+  preview(ctx: RunCtx, opts: PayoutPreviewOptions) {
+    return previewRecipientPayout(
+      this.provider(),
+      this.component,
+      ctx,
+      opts,
+      () => this.verify(ctx, opts),
+    );
+  }
   constructor(
     private readonly component: Component,
     private readonly provider: () => Stripe,
@@ -298,7 +313,10 @@ export class PayoutPolicyClient {
       if (
         prior.mode !== opts.mode ||
         prior.expectedRevision !== opts.expectedRevision ||
-        !equal(prior.thresholds, thresholds) ||
+        !equal(
+          canonicalThresholds(prior.thresholds, prior.mode === "custom"),
+          thresholds,
+        ) ||
         Boolean(prior.adoption) !== Boolean(opts.adoptExistingBalance)
       )
         throw new Error("Payout policy operation identity cannot be reused.");

package/src/component/_generated/api.ts

@@ -56,6 +56,8 @@ 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_queries from "../payoutRelease/queries.js";
 import type * as payoutSnapshots_localState from "../payoutSnapshots/localState.js";
 import type * as payoutSnapshots_mutations from "../payoutSnapshots/mutations.js";
@@ -136,6 +138,8 @@ const fullApi: ApiFromModules<{
   "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/queries": typeof payoutRelease_queries;
   "payoutSnapshots/localState": typeof payoutSnapshots_localState;
   "payoutSnapshots/mutations": typeof payoutSnapshots_mutations;

package/src/component/_generated/component.ts

@@ -3608,6 +3608,48 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        preview: FunctionReference<
+          "query",
+          "internal",
+          {
+            accountId: string;
+            currency: string;
+            expectedRevision: number;
+            independentLiabilities: number;
+            observations: Array<{
+              currency: string;
+              ledgerFingerprint: string;
+              matureNet: number;
+              observedAt: number;
+              pendingCredits: number;
+              stripeTransferId: string;
+              transactionIds: Array<string>;
+            }>;
+            ownerKey: string;
+            providerAvailable: number;
+          },
+          | { amount: 0; reason: string; status: "held" }
+          | {
+              amount: number;
+              confirmedFees: number;
+              currency: string;
+              independentLiabilities: number;
+              matureUnpaid: number;
+              observedAt: number;
+              pendingCredits: number;
+              providerAvailable: number;
+              providerMinimum: null;
+              reason?: string;
+              sources: Array<{
+                matureUnpaid: number;
+                pendingCredits: number;
+                role: "store" | "affiliate" | "other";
+              }>;
+              status: "held" | "qualified";
+              threshold: number;
+            },
+          Name
+        >;
         snapshot: FunctionReference<
           "query",
           "internal",

package/src/component/affiliateRecovery/accounting.ts

@@ -1,5 +1,5 @@
 import type { Doc } from "../_generated/dataModel.js";
-import type { MutationCtx } from "../_generated/server.js";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
 export type Obligation = Omit<
   Doc<"affiliateObligations">,
   "_id" | "_creationTime"
@@ -13,7 +13,7 @@ export const due = (row: Obligation) =>
 export const credit = (row: Obligation) =>
   row.needsReconciliation ? 0 : Math.max(0, netRecovery(row) - target(row));
 export async function balance(
-  ctx: MutationCtx,
+  ctx: MutationCtx | QueryCtx,
   account: string,
   currency: string,
 ) {

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/helpers.ts

@@ -1,6 +1,6 @@
 import type { Infer } from "convex/values";
 import type { transferDocValidator } from "../connect/validators.js";
-import type { MutationCtx } from "../_generated/server.js";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
 import type { Doc } from "../_generated/dataModel.js";
 import { readPolicy, validateScope } from "../payoutPolicy/helpers.js";
 import type { observation } from "./schema.js";
@@ -50,7 +50,7 @@ export async function claimByKey(
   return claim;
 }
 export async function readyPolicy(
-  ctx: MutationCtx,
+  ctx: MutationCtx | QueryCtx,
   args: { accountId: string; ownerKey: string; expectedRevision: number },
 ) {
   const policy = await readPolicy(ctx, args);
@@ -67,7 +67,7 @@ export async function readyPolicy(
 }
 /** Full local account membership is checked under OCC before any reservation. */
 export async function checkSnapshot(
-  ctx: MutationCtx,
+  ctx: MutationCtx | QueryCtx,
   accountId: string,
   observations: Infer<typeof observation>[],
   fresh: boolean,
@@ -126,7 +126,10 @@ export async function checkSnapshot(
   }
   return byId;
 }
-export async function sourceById(ctx: MutationCtx, stripeTransferId: string) {
+export async function sourceById(
+  ctx: MutationCtx | QueryCtx,
+  stripeTransferId: string,
+) {
   return ctx.db
     .query("payoutSourceAllocations")
     .withIndex("by_transfer", (q) => q.eq("stripeTransferId", stripeTransferId))

package/src/component/payoutRelease/mutations.ts

@@ -19,7 +19,7 @@ import {
   validateIdentity,
   add,
 } from "./helpers.js";
-import { planRecipientPayout, type PayoutFundingSource } from "./allocation.js";
+import { readPayoutPlan } from "./planning.js";
 const held = v.object({
   status: v.literal("held"),
   reason: v.union(
@@ -63,10 +63,6 @@ export const claim = mutation({
       return existing;
     }
     const policy = await readyPolicy(ctx, args);
-    const minimum = policy.thresholds.find(
-      (value) => value.currency === args.currency,
-    );
-    if (!minimum) throw new Error("Payout policy currency is not configured.");
     const pending = await ctx.db
       .query("payoutReleaseClaims")
       .withIndex("by_account_status", (q) =>
@@ -81,38 +77,7 @@ export const claim = mutation({
         currency: args.currency,
         providerMinimum: null,
       };
-    const rows = await checkSnapshot(
-      ctx,
-      args.accountId,
-      args.observations,
-      true,
-    );
-    const sources: PayoutFundingSource[] = [];
-    for (const observation of args.observations) {
-      const prior = await sourceById(ctx, observation.stripeTransferId);
-      if (
-        prior &&
-        (prior.accountId !== args.accountId ||
-          prior.ownerKey !== args.ownerKey ||
-          prior.currency !== observation.currency)
-      )
-        throw new Error("Payout source allocation identity changed.");
-      sources.push({
-        ...observation,
-        role: rows.get(observation.stripeTransferId)!.role,
-        paidAmount: prior?.paidAmount ?? 0,
-        reservedAmount: prior?.reservedAmount ?? 0,
-      });
-    }
-    const fees = await readFees(ctx, args);
-    const plan = planRecipientPayout({
-      currency: args.currency,
-      threshold: minimum.amount,
-      providerAvailable: args.providerAvailable,
-      independentLiabilities: args.independentLiabilities,
-      confirmedFees: fees?.amount ?? 0,
-      sources,
-    });
+    const { plan, fees } = await readPayoutPlan(ctx, args, policy);
     if (plan.status === "held") return plan;
     await reserveRecoveryGuard(ctx, args, plan.amount);
     for (const allocation of plan.allocations) {

package/src/component/payoutRelease/planning.ts

@@ -0,0 +1,55 @@
+import type { Infer } from "convex/values";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { policyDoc } from "../payoutPolicy/schema.js";
+import type { observation } from "./observation.js";
+import { checkSnapshot, sourceById } from "./helpers.js";
+import { readFees } from "./fees.js";
+import { planRecipientPayout, type PayoutFundingSource } from "./allocation.js";
+export async function readPayoutPlan(
+  ctx: MutationCtx | QueryCtx,
+  args: {
+    accountId: string;
+    ownerKey: string;
+    currency: string;
+    observations: Infer<typeof observation>[];
+    providerAvailable: number;
+    independentLiabilities: number;
+  },
+  policy: Infer<typeof policyDoc>,
+) {
+  const minimum = policy.thresholds.find((t) => t.currency === args.currency);
+  if (!minimum) throw new Error("Payout policy currency is not configured.");
+  const rows = await checkSnapshot(
+    ctx,
+    args.accountId,
+    args.observations,
+    true,
+  );
+  const sources: PayoutFundingSource[] = [];
+  for (const observation of args.observations) {
+    const prior = await sourceById(ctx, observation.stripeTransferId);
+    if (
+      prior &&
+      (prior.accountId !== args.accountId ||
+        prior.ownerKey !== args.ownerKey ||
+        prior.currency !== observation.currency)
+    )
+      throw new Error("Payout source allocation identity changed.");
+    sources.push({
+      ...observation,
+      role: rows.get(observation.stripeTransferId)!.role,
+      paidAmount: prior?.paidAmount ?? 0,
+      reservedAmount: prior?.reservedAmount ?? 0,
+    });
+  }
+  const fees = await readFees(ctx, args);
+  const plan = planRecipientPayout({
+    currency: args.currency,
+    threshold: minimum.amount,
+    providerAvailable: args.providerAvailable,
+    independentLiabilities: args.independentLiabilities,
+    confirmedFees: fees?.amount ?? 0,
+    sources,
+  });
+  return { plan, sources, fees, threshold: minimum.amount };
+}

package/src/component/payoutRelease/preview.ts

@@ -0,0 +1,118 @@
+import { v } from "convex/values";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { Infer } from "convex/values";
+import { scopeFields } from "../payoutPolicy/schema.js";
+import { observation } from "./observation.js";
+import { readyPolicy, add } from "./helpers.js";
+import { readPayoutPlan } from "./planning.js";
+import { balance } from "../affiliateRecovery/accounting.js";
+export const previewFields = {
+  ...scopeFields,
+  expectedRevision: v.number(),
+  currency: v.string(),
+  providerAvailable: v.number(),
+  independentLiabilities: v.number(),
+  observations: v.array(observation),
+};
+const held = v.object({
+  status: v.literal("held"),
+  reason: v.string(),
+  amount: v.literal(0),
+});
+export const previewResult = v.union(
+  held,
+  v.object({
+    status: v.union(v.literal("held"), v.literal("qualified")),
+    reason: v.optional(v.string()),
+    currency: v.string(),
+    amount: v.number(),
+    threshold: v.number(),
+    providerMinimum: v.null(),
+    matureUnpaid: v.number(),
+    pendingCredits: v.number(),
+    confirmedFees: v.number(),
+    independentLiabilities: v.number(),
+    providerAvailable: v.number(),
+    observedAt: v.number(),
+    sources: v.array(
+      v.object({
+        role: v.union(
+          v.literal("store"),
+          v.literal("affiliate"),
+          v.literal("other"),
+        ),
+        matureUnpaid: v.number(),
+        pendingCredits: v.number(),
+      }),
+    ),
+  }),
+);
+type Args = {
+  [K in keyof typeof previewFields]: Infer<(typeof previewFields)[K]>;
+};
+/** Trusted provider observations, informational only. No reservation or monetary state change. */
+export async function previewPlan(
+  ctx: MutationCtx | QueryCtx,
+  args: Args,
+): Promise<Infer<typeof previewResult>> {
+  const policy = await readyPolicy(ctx, args);
+  const recovery = await balance(ctx, args.accountId, args.currency);
+  if (
+    recovery &&
+    (recovery.outstandingDebt > 0 ||
+      recovery.reservedRecovery > 0 ||
+      recovery.reservedRestoration > 0 ||
+      recovery.activePayoutKey)
+  )
+    return { status: "held", reason: "affiliate_recovery_pending", amount: 0 };
+  const pending = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_account_status", (q) =>
+      q.eq("accountId", args.accountId).eq("status", "reserved"),
+    )
+    .first();
+  if (pending) return { status: "held", reason: "pending_claim", amount: 0 };
+  const {
+    plan,
+    sources: funding,
+    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 };
+  });
+  return {
+    status: plan.status,
+    ...(plan.status === "held" ? { reason: plan.reason } : {}),
+    currency: plan.currency,
+    amount: plan.amount,
+    threshold,
+    providerMinimum: null,
+    matureUnpaid: plan.matureUnpaid,
+    pendingCredits: plan.pendingCredits,
+    confirmedFees: fees?.amount ?? 0,
+    independentLiabilities: args.independentLiabilities,
+    providerAvailable: args.providerAvailable,
+    observedAt: Math.min(
+      Date.now(),
+      ...args.observations.map((o) => o.observedAt),
+    ),
+    sources,
+  };
+}

package/src/component/payoutRelease/queries.ts

@@ -1,3 +1,4 @@
+import { previewFields, previewResult, previewPlan } from "./preview.js";
 import { paginator } from "convex-helpers/server/pagination";
 import schema from "../schema.js";
 import { transferDocValidator } from "../connect/validators.js";
@@ -8,6 +9,11 @@ import { query } from "../_generated/server.js";
 import { identity, claimDoc } from "./schema.js";
 import { validateIdentity } from "./helpers.js";
 import { readPolicy } from "../payoutPolicy/helpers.js";
+export const preview = query({
+  args: previewFields,
+  returns: previewResult,
+  handler: previewPlan,
+});
 export const get = query({
   args: identity,
   returns: v.union(claimDoc, v.null()),

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

@@ -0,0 +1,169 @@
+// @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("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();
+});