@fantastic.dev/better-stripe 0.8.1 → 0.9.0

package/docs/react-workflows.md

@@ -72,6 +72,10 @@ Use `renderForm` on the custom and PaymentIntent modes to render your own email
 input, `paymentElement`, error, and submit button. The preview `form` mode renders
 Stripe's form and does not use that renderer. `children` replaces the outer
 checkout frame and receives `content`, `isLoading`, `error`, and `retry`.
+Respect `state.emailReadOnly` on your email input. Custom Checkout uses the
+email Stripe supplied when the session loaded and skips `updateEmail` for that
+session. Guest sessions without an email collect it before confirmation and
+keep it editable if a payment attempt fails.
 The lower-level `CheckoutElementsForm`, `PaymentIntentForm`, and `CheckoutForm`
 are also exported for an existing client secret.
 
@@ -79,7 +83,14 @@ Only a server-confirmed payment or checkout session should grant access to the
 product. Use `PaymentReceipt` or `CheckoutStatus` with webhook-backed query data;
 a browser return URL alone does not prove payment.
 
-## Headless or Stripe embedded
+## Via API, BetterStripe components, or Stripe embedded
+
+The switch labels are **via API**, **BetterStripe components**, **Stripe embedded**,
+and **Stripe hosted**. BetterStripe components are the unstyled exports from this
+package; Stripe embedded views mount Stripe's Connect UI. The internal mode keys
+remain `headless`, `components`, `embedded`, and `hosted` for compatibility, including
+existing `?example=headless` links. The package's native components accept render
+props so the example can match the API view's cards and layout.
 
 `Account`, `Onboarding`, `Disputes`, `Refunds`, `Earnings`, and `Payouts` accept
 `presentation="embedded"` with Connect session props. Their default headless
@@ -232,3 +243,80 @@ available and pending Stripe balances shown by `Payouts`.
 shared by its account pages and native `Onboarding`. Supply `countries` to limit
 or expand the UI for your platform. This default is not a complete list of
 Stripe-supported countries; your server must validate account eligibility.
+
+## Cursor pagination
+
+Use `useCursorPagination(accountId)` to keep a page number, current cursor, and
+Previous/Next history. Pass `cursor` to your backend's paginated query and call
+`next(result.continueCursor)` only when `result.isDone` is false. Changing the
+scope key resets the history to page 1.
+
+`Pagination` renders unstyled Previous/Next buttons and an announced page number,
+or accepts a render function for your design system. Supply `canPrevious`,
+`canNext`, `isLoading`, `onPrevious`, and `onNext`. Navigation is disabled while
+loading. The example's affiliate sales page uses this with the component query
+`connect.queries.paginateTransfersByAccount`, which returns newest-first cursor
+pages scoped to the recipient account. Earnings totals still use aggregate
+queries independently of pagination.
+
+## Store-plan pricing editor
+
+`PlanPricingEditor` accepts a `plan` with `id`, `name`, `monthlyAmount` in minor
+units, nullable `feeBasisPoints`, and `version`, plus `onSave(update)`. The update
+contains `monthlyAmount`, `feeBasisPoints`, and `expectedVersion`. Blank fees
+mean processing-only. Native fields are unstyled; use the render prop to supply
+your design system. Server-side authorization, fee floors, Stripe Price creation,
+and conflict checks belong in your backend. Existing subscription migration is
+an application policy, not an automatic side effect of this editor.
+
+`PlanPricingEditor` also supports optional `affiliateBasisPoints` on the plan and
+save update, defaulting to 0. Its render state exposes `affiliateShare` and
+`setAffiliateShare`. The native field is labeled Affiliate payout (%), accepts
+0 through 100 with at most two decimal places, and saves integer basis points.
+Omitting the field in an older backend request preserves an existing configured
+rate. The example applies this rate after sale fees and records it with each
+settled sale.
+
+## Product and subscription affiliate-rate editor
+
+`AffiliateRateEditor` accepts `scopeKey`, nullable `affiliateBasisPoints`,
+`effectiveBasisPoints`, `source` of global/store/plan/product/price/none, `version`, and `onSave`.
+Its save update contains nullable `affiliateBasisPoints` and `expectedVersion`.
+Blank input means inherit, zero disables commission, and percentages support
+0 to 100 with two decimal places. Use its native unstyled form or render state
+`percentage`, `setPercentage`, `effectiveLabel`, `save`, `isPending`, `error`,
+and `message` to supply styled controls. The backend must verify ownership and
+resolve price overrides before product overrides and plan defaults. The example
+uses the current subscription price on renewals and preserves settled economics.
+
+## Percentage or fixed affiliate payouts
+
+`AffiliatePayoutEditor` is the unstyled editor used inline by the example's seller
+product and price rows and admin store-plan rows. Supply `scopeKey`, nullable
+`affiliateBasisPoints`, optional nullable `affiliateFixedAmount`, effective values,
+`version`, `currency`, and `onSave`. Fixed amounts are major currency units,
+not cents. The save callback receives both nullable fields and `expectedVersion`;
+only one payout field is non-null. Blank means inherit; explicit zero disables.
+
+The native form includes a number input, `%`/currency-symbol toggle, Save, and X.
+X saves null for both fields to clear the override. `currency` defaults to USD
+and controls the display symbol. A render prop exposes `value`, `mode`, `setValue`,
+`setMode`, `currencySymbol`, `effectiveLabel`, `save`, `clear`, `isPending`, `error`,
+and `message` so applications can supply their own markup. Server code must
+resolve defaults, validate ownership and versions, convert major amounts into
+Stripe minor units, and cap fixed payouts at proceeds after fees. The example
+uses a nominal fixed amount per sale currency; it does not perform FX conversion.
+
+Affiliate payout sources can be `global`, `store`, `plan`, `product`, `price`, or
+`none`. Unset app rules fall back to zero. The example resolves price → product →
+store-wide → plan → platform-wide → 0, and distinguishes explicit zero from null
+inheritance. Both global controls use the same package editor as the row controls.
+
+`AffiliatePayoutEditor` also exposes an optional `affiliateCommissionTerm`
+(`"forever"`, `"one_time"`, or `null` to inherit) and
+`effectiveCommissionTerm`. Its render state includes `term` and `setTerm`, and
+`onSave` receives the selected term together with the payout amount. Clear
+removes both overrides. The example saves the resolved subscription term in
+Stripe metadata at checkout and claims the first paid invoice atomically in its
+Convex ledger; the UI component does not itself create transfers or process
+renewals.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",
@@ -103,12 +103,15 @@
     "@stripe/react-connect-js": "^3.4.4",
     "@stripe/react-stripe-js": "^7.0.0",
     "@stripe/stripe-js": "^10.0.0",
+    "convex-helpers": "^0.1.128",
     "stripe": "~23.0.0"
   },
   "devDependencies": {
     "@convex-dev/eslint-plugin": "^5.0.0",
     "@edge-runtime/vm": "^5.0.0",
     "@fantastic.dev/repo-gates": "^0.4.0",
+    "@shadcn/lint": "0.1.5",
+    "@shadscan/cli": "0.7.0",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
@@ -127,9 +130,7 @@
     "pretty-quick": "^4.2.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.71.1",
-    "vitest": "^5.0.3",
-    "@shadcn/lint": "0.1.5",
-    "@shadscan/cli": "0.7.0"
+    "vitest": "^5.0.3"
   },
   "peerDependencies": {
     "convex": "^1.29.3",

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/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);
+});