@fantastic.dev/better-stripe 0.9.0 → 0.10.0

package/src/client/webhooks/processors.test.ts

@@ -1,8 +1,4 @@
 // @vitest-environment edge-runtime
-/**
- * Drives Stripe event normalization through processEvent and checks the payloads
- * passed to component mutations, including owner, fee, and trial fields.
- */
 import type Stripe from "stripe";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -12,7 +8,6 @@ import { processEvent } from "./processors.js";
 
 const TO_REF = Symbol.for("toReferencePath");
 
-/** Fake component exposing every query/mutation ref processors.ts resolves. */
 function makeComponent() {
   const refs = (namespace: string, names: string[]) =>
     Object.fromEntries(
@@ -44,12 +39,16 @@ function makeCtx(opts?: { query?: unknown; queryThrows?: boolean }) {
   const runQuery = vi.fn();
   if (opts?.queryThrows) runQuery.mockRejectedValue(new Error("not found"));
   else runQuery.mockResolvedValue(opts?.query ?? null);
-  // `claimReversalSlices` returns the slices the reversal engines execute
-  // (BTS-63). Fake only its storage: the slice math is the REAL shared
-  // computeReversalSlices, applied to this ctx's ledger legs.
+  // Fake claim storage; use the shared reversal sizing math.
   const runMutation = vi.fn(
     async (ref: Record<symbol, string>, args: Record<string, unknown>) => {
       const path = ref?.[TO_REF] ?? "";
+      if (
+        String(path).endsWith(
+          "settlement/mutations/reserveSettlementAllocation",
+        )
+      )
+        return args;
       if (!String(path).endsWith("connect/mutations/claimReversalSlices")) {
         return undefined;
       }
@@ -107,7 +106,9 @@ function makeStripe() {
       update: vi.fn().mockResolvedValue({}),
       retrieve: vi.fn(),
     },
+    charges: { retrieve: vi.fn().mockResolvedValue({ created: 1 }) },
     transfers: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
       create: vi.fn(async (_params: unknown) => ({
         id: `tr_${++trCreateSeq}`,
       })),
@@ -146,7 +147,6 @@ function makeStripe() {
       retrieve: vi.fn(),
       update: vi.fn().mockResolvedValue({}),
     },
-    charges: { retrieve: vi.fn() },
   };
 }
 

package/src/component/_generated/api.ts

@@ -25,6 +25,8 @@ import type * as lib_stripeFactory from "../lib/stripeFactory.js";
 import type * as products_mutations from "../products/mutations.js";
 import type * as products_queries from "../products/queries.js";
 import type * as products_validators from "../products/validators.js";
+import type * as settlement_mutations from "../settlement/mutations.js";
+import type * as settlement_queries from "../settlement/queries.js";
 import type * as webhooks_mutations from "../webhooks/mutations.js";
 import type * as webhooks_queries from "../webhooks/queries.js";
 import type * as webhooks_validators from "../webhooks/validators.js";
@@ -54,6 +56,8 @@ const fullApi: ApiFromModules<{
   "products/mutations": typeof products_mutations;
   "products/queries": typeof products_queries;
   "products/validators": typeof products_validators;
+  "settlement/mutations": typeof settlement_mutations;
+  "settlement/queries": typeof settlement_queries;
   "webhooks/mutations": typeof webhooks_mutations;
   "webhooks/queries": typeof webhooks_queries;
   "webhooks/validators": typeof webhooks_validators;

package/src/component/_generated/component.ts

@@ -1763,6 +1763,106 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    settlement: {
+      mutations: {
+        claimCommissionInvoice: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            affiliateAccountId?: string;
+            firstPaidInvoiceId: string;
+            invoiceId: string;
+            subscriptionId: string;
+            term: "forever" | "one_time";
+          },
+          {
+            claimKey: string;
+            eligible: boolean;
+            firstPaidInvoiceId: string;
+            replay: boolean;
+            term: "forever" | "one_time";
+          },
+          Name
+        >;
+        reserveSettlementAllocation: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            adjustmentAmount?: number;
+            currency: string;
+            gross: number;
+            paymentId?: string;
+            paymentIntentId?: string;
+            platformNet: number;
+            processingFee: number;
+            sourceChargeId: string;
+            sourceInvoiceId?: string;
+            transfers: Array<{
+              amount: number;
+              destinationAccountId: string;
+              role: "store" | "affiliate" | "other";
+            }>;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            adjustmentAmount?: number;
+            currency: string;
+            gross: number;
+            paymentId?: string;
+            paymentIntentId?: string;
+            platformNet: number;
+            processingFee: number;
+            sourceChargeId: string;
+            sourceInvoiceId?: string;
+            transfers: Array<{
+              amount: number;
+              destinationAccountId: string;
+              role: "store" | "affiliate" | "other";
+            }>;
+          },
+          Name
+        >;
+      };
+      queries: {
+        getCommissionTerm: FunctionReference<
+          "query",
+          "internal",
+          { subscriptionId: string },
+          {
+            affiliateAccountId?: string;
+            firstPaidInvoiceId: string;
+            subscriptionId: string;
+            term: "forever" | "one_time";
+          } | null,
+          Name
+        >;
+        getSettlementAllocation: FunctionReference<
+          "query",
+          "internal",
+          { sourceChargeId: string },
+          {
+            _creationTime: number;
+            _id: string;
+            adjustmentAmount?: number;
+            currency: string;
+            gross: number;
+            paymentId?: string;
+            paymentIntentId?: string;
+            platformNet: number;
+            processingFee: number;
+            sourceChargeId: string;
+            sourceInvoiceId?: string;
+            transfers: Array<{
+              amount: number;
+              destinationAccountId: string;
+              role: "store" | "affiliate" | "other";
+            }>;
+          } | null,
+          Name
+        >;
+      };
+    };
     webhooks: {
       mutations: {
         insertWebhookEvent: FunctionReference<

package/src/component/schema.ts

@@ -1,3 +1,8 @@
+import {
+  allocationsTable,
+  commissionTermsTable,
+  commissionDecisionsTable,
+} from "./settlement/schema";
 import { defineSchema } from "convex/server";
 
 import {
@@ -19,6 +24,9 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  settlementAllocations: allocationsTable,
+  commissionTerms: commissionTermsTable,
+  commissionDecisions: commissionDecisionsTable,
   // Core
   accounts: accountsTable,
 

package/src/component/settlement/mutations.ts

@@ -0,0 +1,119 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { allocationFields, commissionFields, termValidator } from "./schema.js";
+const doc = v.object({
+  ...allocationFields,
+  _id: v.id("settlementAllocations"),
+  _creationTime: v.number(),
+});
+export const reserveSettlementAllocation = mutation({
+  args: allocationFields,
+  returns: doc,
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("settlementAllocations")
+      .withIndex("by_source_charge", (q) =>
+        q.eq("sourceChargeId", args.sourceChargeId),
+      )
+      .first();
+    if (existing) {
+      if (
+        existing.currency !== args.currency ||
+        existing.paymentIntentId !== args.paymentIntentId ||
+        existing.sourceInvoiceId !== args.sourceInvoiceId
+      )
+        throw new Error("Settlement source identity cannot change.");
+      return existing;
+    }
+    const adjustment = args.adjustmentAmount ?? 0;
+    const amounts = [
+      args.gross,
+      args.processingFee,
+      args.platformNet,
+      ...args.transfers.map((t) => t.amount),
+    ];
+    const keys = args.transfers.map(
+      (t) => `${t.destinationAccountId}:${t.role}`,
+    );
+    if (
+      !Number.isSafeInteger(adjustment) ||
+      args.processingFee + args.platformNet + adjustment < 0 ||
+      amounts.some((n) => !Number.isSafeInteger(n) || n < 0) ||
+      args.gross <= 0 ||
+      !args.currency ||
+      !args.sourceChargeId ||
+      args.transfers.some((t) => !t.destinationAccountId) ||
+      new Set(keys).size !== keys.length ||
+      args.gross !==
+        args.processingFee +
+          args.platformNet +
+          adjustment +
+          args.transfers.reduce((sum, t) => sum + t.amount, 0)
+    )
+      throw new Error(
+        "Settlement allocation must reconcile in integer currency units with unique recipient legs.",
+      );
+    const id = await ctx.db.insert("settlementAllocations", args);
+    return (await ctx.db.get("settlementAllocations", id))!;
+  },
+});
+export const claimCommissionInvoice = mutation({
+  args: { ...commissionFields, invoiceId: v.string() },
+  returns: v.object({
+    eligible: v.boolean(),
+    term: termValidator,
+    firstPaidInvoiceId: v.string(),
+    claimKey: v.string(),
+    replay: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    let stored = await ctx.db
+      .query("commissionTerms")
+      .withIndex("by_subscription", (q) =>
+        q.eq("subscriptionId", args.subscriptionId),
+      )
+      .first();
+    if (stored && stored.affiliateAccountId !== args.affiliateAccountId)
+      throw new Error("Subscription affiliate identity cannot change.");
+    if (!stored) {
+      const fields = {
+        subscriptionId: args.subscriptionId,
+        term: args.term,
+        affiliateAccountId: args.affiliateAccountId,
+        firstPaidInvoiceId: args.firstPaidInvoiceId,
+      };
+      const id = await ctx.db.insert("commissionTerms", fields);
+      stored = (await ctx.db.get("commissionTerms", id))!;
+    }
+    const existing = await ctx.db
+      .query("commissionDecisions")
+      .withIndex("by_subscription_invoice", (q) =>
+        q
+          .eq("subscriptionId", args.subscriptionId)
+          .eq("invoiceId", args.invoiceId),
+      )
+      .first();
+    const claimKey =
+      existing?.claimKey ??
+      `commission:${args.subscriptionId}:${args.invoiceId}`;
+    const eligible =
+      existing?.eligible ??
+      (!!stored.affiliateAccountId &&
+        (stored.term === "forever" ||
+          args.invoiceId === stored.firstPaidInvoiceId));
+    if (!existing)
+      await ctx.db.insert("commissionDecisions", {
+        subscriptionId: args.subscriptionId,
+        invoiceId: args.invoiceId,
+        eligible,
+        claimKey,
+      });
+    return {
+      eligible,
+      term: stored.term,
+      firstPaidInvoiceId: stored.firstPaidInvoiceId,
+      claimKey,
+      replay: !!existing,
+    };
+  },
+});

package/src/component/settlement/queries.ts

@@ -0,0 +1,38 @@
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { allocationFields, commissionFields } from "./schema.js";
+const doc = v.object({
+  ...allocationFields,
+  _id: v.id("settlementAllocations"),
+  _creationTime: v.number(),
+});
+export const getSettlementAllocation = query({
+  args: { sourceChargeId: v.string() },
+  returns: v.union(doc, v.null()),
+  handler: (ctx, args) =>
+    ctx.db
+      .query("settlementAllocations")
+      .withIndex("by_source_charge", (q) =>
+        q.eq("sourceChargeId", args.sourceChargeId),
+      )
+      .first(),
+});
+export const getCommissionTerm = query({
+  args: { subscriptionId: v.string() },
+  returns: v.union(v.object(commissionFields), v.null()),
+  handler: async (ctx, args) => {
+    const row = await ctx.db
+      .query("commissionTerms")
+      .withIndex("by_subscription", (q) =>
+        q.eq("subscriptionId", args.subscriptionId),
+      )
+      .first();
+    if (!row) return null;
+    return {
+      subscriptionId: row.subscriptionId,
+      term: row.term,
+      affiliateAccountId: row.affiliateAccountId,
+      firstPaidInvoiceId: row.firstPaidInvoiceId,
+    };
+  },
+});

package/src/component/settlement/schema.ts

@@ -0,0 +1,45 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+import { splitRecipientRoleValidator } from "../lib/fees.js";
+export const termValidator = v.union(
+  v.literal("forever"),
+  v.literal("one_time"),
+);
+export const allocationFields = {
+  sourceChargeId: v.string(),
+  paymentIntentId: v.optional(v.string()),
+  sourceInvoiceId: v.optional(v.string()),
+  gross: v.number(),
+  currency: v.string(),
+  processingFee: v.number(),
+  platformNet: v.number(),
+  adjustmentAmount: v.optional(v.number()),
+  paymentId: v.optional(v.string()),
+  transfers: v.array(
+    v.object({
+      destinationAccountId: v.string(),
+      role: splitRecipientRoleValidator,
+      amount: v.number(),
+    }),
+  ),
+};
+export const allocationsTable = defineTable(allocationFields).index(
+  "by_source_charge",
+  ["sourceChargeId"],
+);
+export const commissionFields = {
+  subscriptionId: v.string(),
+  term: termValidator,
+  affiliateAccountId: v.optional(v.string()),
+  firstPaidInvoiceId: v.string(),
+};
+export const commissionTermsTable = defineTable(commissionFields).index(
+  "by_subscription",
+  ["subscriptionId"],
+);
+export const commissionDecisionsTable = defineTable({
+  subscriptionId: v.string(),
+  invoiceId: v.string(),
+  eligible: v.boolean(),
+  claimKey: v.string(),
+}).index("by_subscription_invoice", ["subscriptionId", "invoiceId"]);

package/src/component/settlement-claims.test.ts

@@ -0,0 +1,77 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { expect, it } from "vitest";
+import { api } from "./_generated/api.js";
+import schema from "./schema.js";
+const modules = import.meta.glob("./**/*.*s");
+it("keeps a claimed allocation immutable and isolated per source charge", async () => {
+  const t = convexTest(schema, modules);
+  const opts = {
+    sourceChargeId: "ch_1",
+    paymentIntentId: "pi_1",
+    gross: 100,
+    currency: "usd",
+    processingFee: 3,
+    platformNet: 7,
+    transfers: [
+      { destinationAccountId: "acct_c", amount: 90, role: "store" as const },
+    ],
+  };
+  const first = await t.mutation(
+    api.settlement.mutations.reserveSettlementAllocation,
+    opts,
+  );
+  const replay = await t.mutation(
+    api.settlement.mutations.reserveSettlementAllocation,
+    {
+      ...opts,
+      transfers: [{ ...opts.transfers[0], amount: 80 }],
+      platformNet: 17,
+    },
+  );
+  expect(replay).toEqual(first);
+  await expect(
+    t.mutation(api.settlement.mutations.reserveSettlementAllocation, {
+      ...opts,
+      sourceChargeId: "ch_invalid",
+      gross: 1,
+    }),
+  ).rejects.toThrow();
+});
+it("persists the term, identity and earliest invoice despite replay and term changes", async () => {
+  const t = convexTest(schema, modules);
+  const opts = {
+    subscriptionId: "sub_1",
+    invoiceId: "in_renewal",
+    firstPaidInvoiceId: "in_first",
+    term: "one_time" as const,
+    affiliateAccountId: "acct_a",
+  };
+  expect(
+    await t.mutation(api.settlement.mutations.claimCommissionInvoice, opts),
+  ).toMatchObject({
+    eligible: false,
+    firstPaidInvoiceId: "in_first",
+    term: "one_time",
+    replay: false,
+  });
+  expect(
+    await t.mutation(api.settlement.mutations.claimCommissionInvoice, {
+      ...opts,
+      invoiceId: "in_first",
+      term: "forever",
+    }),
+  ).toMatchObject({ eligible: true, term: "one_time" });
+  expect(
+    await t.mutation(api.settlement.mutations.claimCommissionInvoice, {
+      ...opts,
+      invoiceId: "in_first",
+    }),
+  ).toMatchObject({ eligible: true, replay: true });
+  await expect(
+    t.mutation(api.settlement.mutations.claimCommissionInvoice, {
+      ...opts,
+      affiliateAccountId: "acct_other",
+    }),
+  ).rejects.toThrow();
+});

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

@@ -10,6 +10,7 @@
  * tree rendering without throwing via react-dom/server, the disputes_list vs
  * payment_disputes mount switch, and the headless overrides.
  */
+import * as barrel from "../index.js";
 import { createElement } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -136,8 +137,7 @@ describe("EmbeddedDisputes", () => {
 });
 
 describe("react barrel exports", () => {
-  it("exports ConnectProvider and EmbeddedDisputes", async () => {
-    const barrel = await import("../index.js");
+  it("exports ConnectProvider and EmbeddedDisputes", () => {
     expect(barrel.ConnectProvider).toBe(ConnectProvider);
     expect(barrel.EmbeddedDisputes).toBe(EmbeddedDisputes);
   });

package/src/react/index.payment-element.test.ts

@@ -1,41 +1,26 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi } from "vitest";
+
+const elements = vi.hoisted(() => ({
+  checkout: Symbol("checkout-payment-element"),
+  paymentIntent: Symbol("elements-payment-element"),
+}));
+vi.mock("@stripe/react-stripe-js", async () => ({
+  ...(await vi.importActual<typeof import("@stripe/react-stripe-js")>(
+    "@stripe/react-stripe-js",
+  )),
+  PaymentElement: elements.paymentIntent,
+}));
+vi.mock("@stripe/react-stripe-js/checkout", async () => ({
+  ...(await vi.importActual<typeof import("@stripe/react-stripe-js/checkout")>(
+    "@stripe/react-stripe-js/checkout",
+  )),
+  PaymentElement: elements.checkout,
+}));
+import * as reactExports from "./index.js";
 
 describe("better-stripe/react PaymentElement exports", () => {
-  afterEach(() => {
-    vi.resetModules();
-    vi.doUnmock("@stripe/react-stripe-js");
-    vi.doUnmock("@stripe/react-stripe-js/checkout");
-  });
-
-  it("uses checkout PaymentElement as the default export and keeps the Elements variant aliased", async () => {
-    const checkoutPaymentElement = Symbol("checkout-payment-element");
-    const elementsPaymentElement = Symbol("elements-payment-element");
-
-    vi.doMock("@stripe/react-stripe-js", async () => {
-      const actual = await vi.importActual<
-        typeof import("@stripe/react-stripe-js")
-      >("@stripe/react-stripe-js");
-
-      return {
-        ...actual,
-        PaymentElement: elementsPaymentElement,
-      };
-    });
-
-    vi.doMock("@stripe/react-stripe-js/checkout", async () => {
-      const actual = await vi.importActual<
-        typeof import("@stripe/react-stripe-js/checkout")
-      >("@stripe/react-stripe-js/checkout");
-
-      return {
-        ...actual,
-        PaymentElement: checkoutPaymentElement,
-      };
-    });
-
-    const reactExports = await import("./index.js");
-
-    expect(reactExports.PaymentElement).toBe(checkoutPaymentElement);
-    expect(reactExports.ElementsPaymentElement).toBe(elementsPaymentElement);
+  it("uses checkout PaymentElement as the default export and keeps the Elements variant aliased", () => {
+    expect(reactExports.PaymentElement).toBe(elements.checkout);
+    expect(reactExports.ElementsPaymentElement).toBe(elements.paymentIntent);
   });
 });

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

@@ -83,6 +83,9 @@ it("exposes creation errors and retries without losing the selected integration"
   await userEvent.click(screen.getByRole("button", { name: "Retry" }));
   await screen.findByText("Stripe iframe");
   await waitFor(() => expect(createSession).toHaveBeenCalledTimes(2));
+  expect(createSession.mock.calls[1][0].requestId).toBe(
+    createSession.mock.calls[0][0].requestId,
+  );
 });
 it("rejects missing session secrets and initializes Payment Intents through their own callback", async () => {
   const { unmount } = render(
@@ -116,3 +119,30 @@ it("rejects missing session secrets and initializes Payment Intents through thei
     requestId: expect.any(String),
   });
 });
+
+it("keeps an explicit request identity through rerenders and replaces generated identity for a new order", async () => {
+  const createSession = vi
+    .fn()
+    .mockResolvedValue({ stripeSessionId: "cs_test", clientSecret: "secret" });
+  const props = {
+    mode: "embedded" as const,
+    orderKey: "order_one",
+    publishableKey: "pk_test",
+    returnUrl: "https://app.test/receipt",
+    createSession,
+  };
+  const { rerender } = render(
+    <Checkout {...props} requestId="persisted-order" />,
+  );
+  await screen.findByText("Stripe iframe");
+  expect(createSession.mock.calls[0][0].requestId).toBe("persisted-order");
+  rerender(<Checkout {...props} requestId="persisted-order" />);
+  expect(createSession).toHaveBeenCalledTimes(1);
+  rerender(<Checkout {...props} orderKey="order_two" />);
+  await waitFor(() => expect(createSession).toHaveBeenCalledTimes(2));
+  const second = createSession.mock.calls[1][0].requestId;
+  expect(second).not.toBe("persisted-order");
+  rerender(<Checkout {...props} orderKey="order_three" />);
+  await waitFor(() => expect(createSession).toHaveBeenCalledTimes(3));
+  expect(createSession.mock.calls[2][0].requestId).not.toBe(second);
+});

package/src/react/workflows/Checkout.tsx

@@ -1,5 +1,5 @@
 "use client";
-import type { ReactNode } from "react";
+import { useState, type ReactNode } from "react";
 import { EmbeddedCheckout } from "../components/EmbeddedCheckout.js";
 import { useWorkflowResource } from "./useWorkflowResource.js";
 import {
@@ -36,6 +36,8 @@ type Common = CheckoutFormOptions & {
   publishableKey: string;
   /** Changes when the price, signed-in customer, or referral attribution changes. */
   orderKey: string;
+  /** Optional durable logical-order identity, persisted by the host app. */
+  requestId?: string;
   returnUrl: string;
   onNavigate?: (url: string) => void;
   children?: (state: CheckoutRenderProps) => ReactNode;
@@ -57,11 +59,16 @@ export type CheckoutProps = Common &
   );
 /** All checkout integrations share one unstyled lifecycle. Callbacks must authenticate and validate prices on the server. */
 export function Checkout(props: CheckoutProps) {
-  return <CheckoutBody key={`${props.orderKey}:${props.mode}`} {...props} />;
+  return (
+    <CheckoutBody
+      key={`${props.orderKey}:${props.mode}:${props.requestId ?? ""}`}
+      {...props}
+    />
+  );
 }
 function CheckoutBody(props: CheckoutProps) {
+  const [requestId] = useState(() => props.requestId ?? crypto.randomUUID());
   const state = useWorkflowResource(async () => {
-    const requestId = crypto.randomUUID();
     const result =
       props.mode === "payment-intent"
         ? await props.createPaymentIntent({ requestId })

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

@@ -110,3 +110,36 @@ it("keeps completed payouts out of upcoming and sorts the remaining arrivals", a
   );
   expect(screen.getAllByText("po_paid")).toHaveLength(1);
 });
+it("distinguishes an unavailable account from an empty balance and labels upcoming previews", async () => {
+  const load = vi.fn().mockResolvedValue({
+    status: "not_ready",
+    reason: "account_unavailable",
+    balances: [],
+    upcoming: [],
+    payouts: [],
+    nextCursor: null,
+    upcomingComplete: true,
+  });
+  const { unmount } = render(<Payouts scopeKey="unavailable" load={load} />);
+  expect((await screen.findByRole("alert")).textContent).toContain(
+    "not available",
+  );
+  expect(screen.queryByText("Not scheduled")).toBeNull();
+  unmount();
+  render(
+    <Payouts
+      scopeKey="preview"
+      load={async () => ({
+        status: "ready",
+        balances: [],
+        upcoming: [],
+        payouts: [],
+        nextCursor: null,
+        upcomingComplete: false,
+      })}
+    />,
+  );
+  expect(
+    await screen.findByText(/Upcoming payouts are a bounded preview/),
+  ).toBeTruthy();
+});