@fantastic.dev/better-stripe 0.8.1 → 0.10.0

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