@fantastic.dev/better-stripe 0.8.0 → 0.9.0

package/src/component/_generated/component.ts

@@ -611,6 +611,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -1339,6 +1340,46 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           }>,
           Name
         >;
+        paginateTransfersByAccount: FunctionReference<
+          "query",
+          "internal",
+          {
+            destinationAccountId: string;
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              amount: number;
+              currency: string;
+              destinationAccountId: string;
+              metadata?: any;
+              paymentId?: string;
+              reinstatement?: boolean;
+              reversalClaimedAmount?: number;
+              reversalStatus?: "partially_reversed" | "fully_reversed";
+              reversedAmount?: number;
+              role?: "store" | "affiliate" | "other";
+              sourceChargeId?: string;
+              sourceInvoiceId?: string;
+              status: "pending" | "paid" | "failed" | "reversed";
+              stripeTransferId: string;
+            }>;
+            pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+            splitCursor?: string | null;
+          },
+          Name
+        >;
       };
     };
     core: {

package/src/component/connect/queries.ts

@@ -1,4 +1,10 @@
 import { v } from "convex/values";
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
 
 import type { Doc } from "../_generated/dataModel";
 import { query } from "../_generated/server";
@@ -343,6 +349,23 @@ export const listTransfersByAccount = query({
   },
 });
 
+/** Newest transfers for a recipient, with bounded cursor pagination. */
+export const paginateTransfersByAccount = query({
+  args: {
+    destinationAccountId: v.string(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(transferDocValidator),
+  handler: (ctx, args) =>
+    paginator(ctx.db, schema)
+      .query("transfers")
+      .withIndex("by_destination_account_id", (q) =>
+        q.eq("destinationAccountId", args.destinationAccountId),
+      )
+      .order("desc")
+      .paginate(args.paginationOpts),
+});
+
 // =============================================================================
 // REVERSAL-CLAIM RECLAIM (BTS-74) — ops diagnostics for wedged legs
 // =============================================================================
@@ -442,7 +465,7 @@ export const listWedgedReversalClaims = query({
  * Exact earnings totals for one connected account (BTS-64): `gross` (sum of all
  * transfer amounts, incl. reinstatements — the earnings view) and `reversed`
  * (sum of all `reversedAmount`), iterated to completion so totals are never
- * capped. `transfers` is a bounded preview (`previewLimit ?? 50` rows) for
+ * capped. `transfers` is a newest-first bounded preview (`previewLimit ?? 50` rows) for
  * drill-down; use `gross`/`reversed`/`transferCount` for the money figures.
  */
 export const getAccountEarnings = query({
@@ -467,7 +490,8 @@ export const getAccountEarnings = query({
       .query("transfers")
       .withIndex("by_destination_account_id", (q) =>
         q.eq("destinationAccountId", args.destinationAccountId),
-      )) {
+      )
+      .order("desc")) {
       gross += tr.amount;
       reversed += tr.reversedAmount ?? 0;
       transferCount += 1;

package/src/component/earnings-totals.test.ts

@@ -50,6 +50,18 @@ describe("getAccountEarnings — exact totals past the 50-row cap (BTS-64)", ()
     expect(result.transferCount).toBe(120);
     // The preview is still bounded (drill-down rows), but the totals are exact.
     expect(result.transfers.length).toBe(50);
+    expect(result.transfers[0].stripeTransferId).toBe("tr_big_119");
+    expect(
+      result.transfers.some((row) => row.stripeTransferId === "tr_big_0"),
+    ).toBe(false);
+    const newest = await t.query(api.connect.queries.getAccountEarnings, {
+      destinationAccountId: "acct_big",
+      previewLimit: 1,
+    });
+    expect(newest.transfers.map((row) => row.stripeTransferId)).toEqual([
+      "tr_big_119",
+    ]);
+    expect(newest.gross).toBe(12000);
   });
 
   it("returns exact totals and all rows for a small account (regression)", async () => {
@@ -208,6 +220,7 @@ describe("aggregate read-limit failures (BTS-116)", () => {
       "Too many documents read in a single function execution",
     );
     const rows = {
+      order: () => rows,
       async *[Symbol.asyncIterator]() {
         yield { amount: 100, reversedAmount: 10, status: "paid" };
         throw readLimit;

package/src/component/transfers.test.ts

@@ -469,3 +469,51 @@ describe("claimReversalSlices (BTS-63)", () => {
     expect(rival.slices).toEqual([]);
   });
 });
+
+it("paginates an account's newest transfers beyond 50 without duplicates or other accounts", async () => {
+  const t = convexTest(schema, modules);
+  for (let i = 0; i < 57; i++) {
+    await t.mutation(api.connect.mutations.upsertTransfer, {
+      stripeTransferId: `tr_page_${i}`,
+      destinationAccountId: "acct_pages",
+      amount: 100,
+      currency: "usd",
+      status: "paid",
+    });
+  }
+  await t.mutation(api.connect.mutations.upsertTransfer, {
+    stripeTransferId: "tr_foreign",
+    destinationAccountId: "acct_other",
+    amount: 200,
+    currency: "usd",
+    status: "paid",
+  });
+  let cursor: string | null = null;
+  const ids: string[] = [];
+  const sizes: number[] = [];
+  for (;;) {
+    const result: {
+      page: { stripeTransferId: string }[];
+      isDone: boolean;
+      continueCursor: string;
+    } = await t.query(api.connect.queries.paginateTransfersByAccount, {
+      destinationAccountId: "acct_pages",
+      paginationOpts: { numItems: 10, cursor },
+    });
+    sizes.push(result.page.length);
+    ids.push(...result.page.map((row) => row.stripeTransferId));
+    if (result.isDone) break;
+    cursor = result.continueCursor;
+  }
+  expect(sizes).toEqual([10, 10, 10, 10, 10, 7]);
+  expect(ids).toEqual(
+    Array.from({ length: 57 }, (_, i) => `tr_page_${56 - i}`),
+  );
+  expect(new Set(ids).size).toBe(57);
+  const empty = await t.query(api.connect.queries.paginateTransfersByAccount, {
+    destinationAccountId: "acct_empty",
+    paginationOpts: { numItems: 10, cursor: null },
+  });
+  expect(empty.page).toEqual([]);
+  expect(empty.isDone).toBe(true);
+});

package/src/react/components/DisputeDetail.tsx

@@ -5,6 +5,11 @@ import type { ReactNode } from "react";
 import type { DisputeWithCountdown } from "../hooks/useDisputeWithCountdown.js";
 import { formatPrice } from "../lib/price-helpers.js";
 
+/** Stripe only accepts responses while the dispute requires one. */
+export function canRespondToDispute(status: string | undefined) {
+  return status === "needs_response" || status === "warning_needs_response";
+}
+
 export type DisputeDetailRenderProps = {
   dispute: DisputeWithCountdown;
   /** Formatted dispute amount, e.g. "$120.50". */
@@ -26,6 +31,7 @@ export type DisputeDetailProps = {
   dueLabel?: string;
   overdueLabel?: string;
   noDeadlineLabel?: string;
+  responseClosedLabel?: string;
   /** Field captions in the default rendering. */
   labels?: {
     amount?: string;
@@ -53,6 +59,7 @@ export function DisputeDetail({
   dueLabel = "Evidence due in {days} days",
   overdueLabel = "Evidence overdue",
   noDeadlineLabel = "No evidence deadline",
+  responseClosedLabel = "Evidence submission closed",
   labels,
   locale,
   className,
@@ -70,11 +77,13 @@ export function DisputeDetail({
   }
 
   const { countdown } = dispute;
-  const countdownMessage = countdown.isOverdue
-    ? overdueLabel
-    : countdown.daysRemaining !== undefined
-      ? dueLabel.replace("{days}", String(countdown.daysRemaining))
-      : noDeadlineLabel;
+  const countdownMessage = !canRespondToDispute(dispute.status)
+    ? responseClosedLabel
+    : countdown.isOverdue
+      ? overdueLabel
+      : countdown.daysRemaining !== undefined
+        ? dueLabel.replace("{days}", String(countdown.daysRemaining))
+        : noDeadlineLabel;
 
   const renderProps: DisputeDetailRenderProps = {
     dispute,

package/src/react/components/DisputesList.render.test.tsx

@@ -242,3 +242,24 @@ describe("DisputesList", () => {
     expect(html).not.toContain("No disputes");
   });
 });
+it.each(["won", "lost", "under_review"] as const)(
+  "hides stale evidence deadlines for %s disputes",
+  (status) => {
+    const html = renderToStaticMarkup(
+      createElement(DisputesList, {
+        disputes: [
+          makeDispute({
+            status,
+            countdown: {
+              dueBy: "2030-01-01T00:00:00Z",
+              daysRemaining: 9,
+              isOverdue: false,
+            },
+          }),
+        ],
+      }),
+    );
+    expect(html).toContain(status);
+    expect(html).not.toContain("Evidence due in");
+  },
+);

package/src/react/components/DisputesList.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import type { ReactNode } from "react";
+import { canRespondToDispute } from "./DisputeDetail.js";
 
 import type { StripeComponentDispute } from "../types.js";
 import type { DisputeEvidenceCountdown } from "../hooks/useDisputeWithCountdown.js";
@@ -78,7 +79,7 @@ export function DisputesList({
 
   const badgeTextFor = (row: DisputesListRow): string | undefined => {
     const countdown = row.countdown;
-    if (!countdown?.dueBy) return undefined;
+    if (!canRespondToDispute(row.status) || !countdown?.dueBy) return undefined;
     if (countdown.isOverdue) return overdueLabel;
     return dueLabel.replace("{days}", String(countdown.daysRemaining));
   };

package/src/react/components/EvidenceForm.render.test.tsx

@@ -79,8 +79,7 @@ describe("EvidenceForm", () => {
     expect(args.evidence).toEqual({
       product_description: allFields.productDescription,
       access_activity_log: allFields.accessActivity,
-      uncategorized_text: allFields.additionalInfo,
-      customer_communication: allFields.customerCommunication,
+      uncategorized_text: `${allFields.additionalInfo}\n\nCustomer communication:\n${allFields.customerCommunication}`,
     });
     // Stripe's dispute-update `submit` DEFAULTS TO TRUE when omitted, so a
     // draft must send an explicit false — omission would submit to the bank.

package/src/react/index.ts

@@ -163,7 +163,10 @@ export type {
   DisputesListRow,
   DisputesListRowContext,
 } from "./components/DisputesList.js";
-export { DisputeDetail } from "./components/DisputeDetail.js";
+export {
+  DisputeDetail,
+  canRespondToDispute,
+} from "./components/DisputeDetail.js";
 export type {
   DisputeDetailProps,
   DisputeDetailRenderProps,

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

@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { AffiliatePayoutEditor } from "./AffiliatePayoutEditor.js";
+afterEach(cleanup);
+it("saves either a percentage or a currency amount and clears inheritance", async () => {
+  const save = vi.fn().mockResolvedValue(undefined);
+  render(
+    <AffiliatePayoutEditor
+      scopeKey="price"
+      affiliateBasisPoints={null}
+      effectiveBasisPoints={2000}
+      version={0}
+      currency="eur"
+      onSave={save}
+    />,
+  );
+  const input = screen.getByLabelText("Affiliate payout");
+  await userEvent.type(input, "12.5");
+  await userEvent.click(screen.getByRole("button", { name: "Save" }));
+  expect(save).toHaveBeenLastCalledWith({
+    affiliateBasisPoints: 1250,
+    affiliateFixedAmount: null,
+    affiliateCommissionTerm: null,
+    expectedVersion: 0,
+  });
+  await userEvent.click(
+    screen.getByRole("button", { name: "Fixed amount in EUR" }),
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Save" }));
+  expect(save).toHaveBeenLastCalledWith({
+    affiliateBasisPoints: null,
+    affiliateFixedAmount: 12.5,
+    affiliateCommissionTerm: null,
+    expectedVersion: 0,
+  });
+  await userEvent.click(
+    screen.getByRole("button", { name: "Clear affiliate payout" }),
+  );
+  expect(save).toHaveBeenLastCalledWith({
+    affiliateBasisPoints: null,
+    affiliateFixedAmount: null,
+    affiliateCommissionTerm: null,
+    expectedVersion: 0,
+  });
+  expect((input as HTMLInputElement).value).toBe("");
+});
+it("rejects excessive percentages and invalid decimals", async () => {
+  const save = vi.fn();
+  render(
+    <AffiliatePayoutEditor
+      scopeKey="product"
+      affiliateBasisPoints={null}
+      effectiveBasisPoints={2000}
+      version={0}
+      onSave={save}
+    />,
+  );
+  await userEvent.type(screen.getByLabelText("Affiliate payout"), "101");
+  await userEvent.click(screen.getByRole("button", { name: "Save" }));
+  expect(screen.getByRole("alert").textContent).toMatch(/100/);
+  expect(save).not.toHaveBeenCalled();
+});
+it("saves a one-time subscription commission and clears its term to inheritance", async () => {
+  const save = vi.fn().mockResolvedValue(undefined);
+  render(
+    <AffiliatePayoutEditor
+      scopeKey="term"
+      affiliateBasisPoints={1000}
+      effectiveBasisPoints={1000}
+      version={0}
+      onSave={save}
+    />,
+  );
+  await userEvent.selectOptions(
+    screen.getByLabelText("Commission term"),
+    "one_time",
+  );
+  await userEvent.click(screen.getByRole("button", { name: "Save" }));
+  expect(save).toHaveBeenLastCalledWith(
+    expect.objectContaining({ affiliateCommissionTerm: "one_time" }),
+  );
+  await userEvent.click(
+    screen.getByRole("button", { name: "Clear affiliate payout" }),
+  );
+  expect(save).toHaveBeenLastCalledWith(
+    expect.objectContaining({ affiliateCommissionTerm: null }),
+  );
+});

package/src/react/workflows/AffiliatePayoutEditor.tsx

@@ -0,0 +1,201 @@
+"use client";
+import { useId, useMemo, useState, type ReactNode } from "react";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+export type AffiliateCommissionTerm = "forever" | "one_time";
+export type AffiliatePayoutUpdate = {
+  affiliateCommissionTerm?: AffiliateCommissionTerm | null;
+  affiliateBasisPoints: number | null;
+  /** Major units of the sale currency, for example 5 means EUR 5 on a EUR sale. */
+  affiliateFixedAmount: number | null;
+  expectedVersion: number;
+};
+export type AffiliatePayoutEditorState = {
+  term: AffiliateCommissionTerm | "inherit";
+  setTerm: (term: AffiliateCommissionTerm | "inherit") => void;
+  value: string;
+  mode: "percentage" | "fixed";
+  currencySymbol: string;
+  setValue: (value: string) => void;
+  setMode: (mode: "percentage" | "fixed") => void;
+  effectiveLabel: string;
+  save: () => Promise<unknown>;
+  clear: () => Promise<unknown>;
+  isPending: boolean;
+  error: string | null;
+  message: string | undefined;
+};
+export type AffiliatePayoutEditorProps = {
+  scopeKey: string;
+  affiliateCommissionTerm?: AffiliateCommissionTerm | null;
+  affiliateBasisPoints: number | null;
+  affiliateFixedAmount?: number | null;
+  effectiveCommissionTerm?: AffiliateCommissionTerm;
+  effectiveBasisPoints: number;
+  effectiveFixedAmount?: number | null;
+  source?: "plan" | "product" | "price" | "store" | "global" | "none";
+  currency?: string;
+  version: number;
+  onSave: (update: AffiliatePayoutUpdate) => Promise<unknown>;
+  children?: (state: AffiliatePayoutEditorState) => ReactNode;
+};
+function initialFields(props: AffiliatePayoutEditorProps) {
+  return {
+    scope: `${props.scopeKey}:${props.version}`,
+    term: props.affiliateCommissionTerm ?? ("inherit" as const),
+    mode:
+      props.affiliateFixedAmount != null
+        ? ("fixed" as const)
+        : ("percentage" as const),
+    value:
+      props.affiliateFixedAmount != null
+        ? String(props.affiliateFixedAmount)
+        : props.affiliateBasisPoints == null
+          ? ""
+          : String(props.affiliateBasisPoints / 100),
+  };
+}
+/** Unstyled inline payout editor. Clear saves inheritance; explicit zero disables payouts. */
+export function AffiliatePayoutEditor(props: AffiliatePayoutEditorProps) {
+  const id = useId();
+  const currency = (props.currency ?? "usd").toUpperCase();
+  const formatter = useMemo(
+    () =>
+      new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency,
+        currencyDisplay: "narrowSymbol",
+      }),
+    [currency],
+  );
+  const currencySymbol =
+    formatter.formatToParts(0).find((part) => part.type === "currency")
+      ?.value ?? currency;
+  const scope = `${props.scopeKey}:${props.version}`;
+  const initial = initialFields(props);
+  const [fields, setFields] = useState(initial);
+  if (fields.scope !== scope) setFields(initial);
+  const action = useWorkflowAction(async (clear = false) => {
+    const value = clear ? "" : fields.value.trim();
+    const amount = value === "" ? null : Number(value);
+    if (
+      amount !== null &&
+      (!/^\d+(\.\d{1,2})?$/.test(value) ||
+        !Number.isSafeInteger(Math.round(amount * 100)) ||
+        amount < 0 ||
+        (fields.mode === "percentage" && amount > 100))
+    )
+      throw new Error(
+        "Enter a non-negative amount with at most two decimals, or a percentage from 0 to 100.",
+      );
+    await props.onSave({
+      affiliateCommissionTerm:
+        clear || fields.term === "inherit" ? null : fields.term,
+      affiliateBasisPoints:
+        fields.mode === "percentage" && amount !== null
+          ? Math.round(amount * 100)
+          : null,
+      affiliateFixedAmount: fields.mode === "fixed" ? amount : null,
+      expectedVersion: props.version,
+    });
+    if (clear)
+      setFields((previous) =>
+        previous.scope === scope
+          ? { ...previous, value: "", term: "inherit" }
+          : previous,
+      );
+    return clear
+      ? "Affiliate payout cleared. Using the inherited default."
+      : "Affiliate payout saved.";
+  }, props.scopeKey);
+  const state: AffiliatePayoutEditorState = {
+    ...fields,
+    currencySymbol,
+    setTerm: (term) => setFields((previous) => ({ ...previous, term })),
+    setValue: (value) => setFields((previous) => ({ ...previous, value })),
+    setMode: (mode) => setFields((previous) => ({ ...previous, mode })),
+    effectiveLabel: `Commission term: ${(props.effectiveCommissionTerm ?? "forever") === "forever" ? "Forever" : "One-time"}. Effective payout: ${props.effectiveFixedAmount != null ? formatter.format(props.effectiveFixedAmount) : `${props.effectiveBasisPoints / 100}%`}${props.source && props.source !== "none" ? ` from ${props.source === "plan" ? "store plan" : props.source}` : ""}.`,
+    save: () => action.run(false),
+    clear: () => action.run(true),
+    isPending: action.isPending,
+    error: action.error,
+    message: action.result,
+  };
+  if (props.children) return <>{props.children(state)}</>;
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        void state.save();
+      }}
+    >
+      <label htmlFor={id}>Affiliate payout</label>
+      <input
+        id={id}
+        inputMode="decimal"
+        value={state.value}
+        disabled={state.isPending}
+        onChange={(event) => state.setValue(event.target.value)}
+      />
+      <button
+        type="button"
+        aria-label="Percentage"
+        aria-pressed={state.mode === "percentage"}
+        disabled={state.isPending}
+        onClick={() => state.setMode("percentage")}
+      >
+        %
+      </button>
+      <button
+        type="button"
+        aria-label={`Fixed amount in ${currency}`}
+        aria-pressed={state.mode === "fixed"}
+        disabled={state.isPending}
+        onClick={() => state.setMode("fixed")}
+      >
+        {currencySymbol}
+      </button>
+      <label htmlFor={`${id}-term`}>Commission term</label>
+      <select
+        id={`${id}-term`}
+        value={state.term}
+        disabled={state.isPending}
+        onChange={(event) =>
+          state.setTerm(
+            event.target.value as AffiliateCommissionTerm | "inherit",
+          )
+        }
+      >
+        <option value="inherit">Inherited term</option>
+        <option value="forever">Forever</option>
+        <option value="one_time">One-time</option>
+      </select>
+      <button type="submit" disabled={state.isPending}>
+        Save
+      </button>
+      <button
+        type="button"
+        aria-label="Clear affiliate payout"
+        disabled={state.isPending}
+        onClick={() => void state.clear()}
+      >
+        <svg
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          aria-hidden="true"
+        >
+          <path d="M18 6 6 18M6 6l12 12" />
+        </svg>
+      </button>
+      <p>
+        {state.effectiveLabel} Blank inherits the default. Fixed payouts are
+        capped at proceeds after fees.
+      </p>
+      {state.error && <p role="alert">{state.error}</p>}
+      {state.message && <p role="status">{state.message}</p>}
+    </form>
+  );
+}

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

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, expect, it, vi } from "vitest";
+import { AffiliateRateEditor } from "./AffiliateRateEditor.js";
+afterEach(cleanup);
+it("saves a percentage, clears to inherit, and rejects invalid decimals", async () => {
+  const save = vi.fn().mockResolvedValue(undefined);
+  render(
+    <AffiliateRateEditor
+      scopeKey="price"
+      affiliateBasisPoints={null}
+      effectiveBasisPoints={2000}
+      source="plan"
+      version={0}
+      onSave={save}
+    />,
+  );
+  const input = screen.getByLabelText("Affiliate payout (%)");
+  await userEvent.type(input, "12.5");
+  await userEvent.click(screen.getByRole("button", { name: "Save payout" }));
+  expect(save).toHaveBeenLastCalledWith({
+    affiliateBasisPoints: 1250,
+    expectedVersion: 0,
+  });
+  await userEvent.clear(input);
+  await userEvent.click(screen.getByRole("button", { name: "Save payout" }));
+  expect(save).toHaveBeenLastCalledWith({
+    affiliateBasisPoints: null,
+    expectedVersion: 0,
+  });
+  await userEvent.type(input, "100.001");
+  await userEvent.click(screen.getByRole("button", { name: "Save payout" }));
+  expect(save).toHaveBeenCalledTimes(2);
+  expect(screen.getByRole("alert").textContent).toMatch(/percentage/i);
+});