@fantastic.dev/better-stripe 0.18.0 → 0.20.0

package/src/client/connect/payoutAllocation.test.ts

@@ -0,0 +1,292 @@
+import { describe, expect, it } from "vitest";
+import { planRecipientPayout } from "../../component/payoutRelease/allocation.js";
+
+const source = (id: string, matureNet: number, extra = {}) => ({
+  stripeTransferId: id,
+  currency: "usd",
+  matureNet,
+  paidAmount: 0,
+  reservedAmount: 0,
+  pendingCredits: 0,
+  role: "store" as const,
+  ...extra,
+});
+const options = (
+  sources = [
+    source("tr_creator", 600),
+    source("tr_affiliate", 400, { role: "affiliate" }),
+  ],
+) => ({
+  currency: "usd",
+  threshold: 1000,
+  providerAvailable: 1000,
+  independentLiabilities: 0,
+  sources,
+});
+
+describe("combined recipient payout allocation", () => {
+  it("qualifies creator and affiliate funds together at the exact threshold", () => {
+    expect(planRecipientPayout(options())).toEqual({
+      status: "qualified",
+      currency: "usd",
+      amount: 1000,
+      matureUnpaid: 1000,
+      pendingCredits: 0,
+      providerMinimum: null,
+      allocations: [
+        { stripeTransferId: "tr_affiliate", amount: 400, role: "affiliate" },
+        { stripeTransferId: "tr_creator", amount: 600, role: "store" },
+      ],
+    });
+  });
+  it("keeps the entire combined balance owed below the threshold", () => {
+    expect(
+      planRecipientPayout(options([source("tr_creator", 999)])),
+    ).toMatchObject({
+      status: "held",
+      reason: "below_threshold",
+      matureUnpaid: 999,
+      amount: 0,
+    });
+  });
+  it("releases the full eligible balance above the threshold", () => {
+    expect(
+      planRecipientPayout({
+        ...options([source("tr_creator", 1200)]),
+        providerAvailable: 1500,
+      }),
+    ).toMatchObject({
+      status: "qualified",
+      amount: 1200,
+    });
+  });
+  it("cannot use unrelated available money to qualify a pending source", () => {
+    expect(
+      planRecipientPayout({
+        ...options([source("tr_pending", 0, { pendingCredits: 1500 })]),
+        providerAvailable: 10000,
+      }),
+    ).toMatchObject({
+      status: "held",
+      reason: "below_threshold",
+      matureUnpaid: 0,
+      pendingCredits: 1500,
+    });
+  });
+  it("deducts previously paid and still reserved allocations exactly once", () => {
+    expect(
+      planRecipientPayout(
+        options([
+          source("tr_creator", 2500, { paidAmount: 800, reservedAmount: 700 }),
+        ]),
+      ),
+    ).toMatchObject({
+      status: "qualified",
+      matureUnpaid: 1000,
+      amount: 1000,
+      allocations: [
+        { stripeTransferId: "tr_creator", amount: 1000, role: "store" },
+      ],
+    });
+  });
+  it("carries a refunded paid source as debt against future funds", () => {
+    expect(
+      planRecipientPayout(
+        options([
+          source("tr_refunded", 0, { paidAmount: 600 }),
+          source("tr_new", 1500, { role: "affiliate" }),
+        ]),
+      ),
+    ).toMatchObject({
+      status: "held",
+      reason: "below_threshold",
+      matureUnpaid: 900,
+    });
+    expect(
+      planRecipientPayout(
+        options([
+          source("tr_refunded", 0, { paidAmount: 600 }),
+          source("tr_new", 1600, { role: "affiliate" }),
+        ]),
+      ),
+    ).toMatchObject({
+      status: "qualified",
+      amount: 1000,
+      allocations: [
+        { stripeTransferId: "tr_new", amount: 1000, role: "affiliate" },
+      ],
+    });
+  });
+  it("retains negative fee adjustments without forfeiting unpaid funds", () => {
+    expect(
+      planRecipientPayout(
+        options([source("tr_fee", -30), source("tr_new", 1030)]),
+      ),
+    ).toMatchObject({
+      status: "qualified",
+      amount: 1000,
+      allocations: [
+        { stripeTransferId: "tr_new", amount: 1000, role: "store" },
+      ],
+    });
+  });
+  it("caps release by fresh provider availability after independent liabilities", () => {
+    const result = planRecipientPayout({
+      ...options([source("tr_creator", 2000)]),
+      providerAvailable: 1500,
+      independentLiabilities: 200,
+    });
+    expect(result).toMatchObject({
+      status: "qualified",
+      amount: 1300,
+      matureUnpaid: 2000,
+    });
+    expect(
+      planRecipientPayout({
+        ...options(),
+        providerAvailable: 1000,
+        independentLiabilities: 1,
+      }),
+    ).toMatchObject({
+      status: "held",
+      reason: "insufficient_available",
+      matureUnpaid: 1000,
+    });
+  });
+  it("does not subtract reservations again from an already debited provider balance", () => {
+    expect(
+      planRecipientPayout({
+        ...options([source("tr_creator", 2000, { reservedAmount: 1000 })]),
+        providerAvailable: 1000,
+      }),
+    ).toMatchObject({ status: "qualified", amount: 1000 });
+  });
+  it("isolates currencies, including debts and pending credits", () => {
+    expect(
+      planRecipientPayout(
+        options([
+          source("tr_usd", 1000),
+          source("tr_eur", -5000, { currency: "eur", pendingCredits: 300 }),
+        ]),
+      ),
+    ).toMatchObject({ status: "qualified", amount: 1000, pendingCredits: 0 });
+  });
+  it("uses stable source ordering regardless of observation order", () => {
+    const rows = [source("tr_z", 700), source("tr_a", 800)];
+    const args = { ...options(rows), providerAvailable: 1100 };
+    const first = planRecipientPayout(args);
+    expect(first).toEqual(
+      planRecipientPayout({ ...args, sources: [...rows].reverse() }),
+    );
+    expect(first).toMatchObject({
+      allocations: [
+        { stripeTransferId: "tr_a", amount: 800, role: "store" },
+        { stripeTransferId: "tr_z", amount: 300, role: "store" },
+      ],
+    });
+  });
+  it("preserves signed debt even if there are no current credits", () => {
+    expect(
+      planRecipientPayout(
+        options([source("tr_debt", -50, { paidAmount: 200 })]),
+      ),
+    ).toMatchObject({
+      status: "held",
+      matureUnpaid: -250,
+      amount: 0,
+    });
+  });
+  it("does not invent a numeric provider minimum", () => {
+    expect(
+      planRecipientPayout({
+        ...options([source("tr_small", 1)]),
+        threshold: 1,
+      }),
+    ).toMatchObject({
+      status: "qualified",
+      amount: 1,
+      providerMinimum: null,
+    });
+  });
+  it("rejects duplicate sources rather than counting them twice", () => {
+    awaitInvalid(() =>
+      planRecipientPayout(
+        options([source("tr_same", 600), source("tr_same", 600)]),
+      ),
+    );
+  });
+  it.each([0, -1, 0.5, Number.MAX_SAFE_INTEGER + 1, NaN, Infinity])(
+    "rejects an unsafe threshold %s",
+    (threshold) => {
+      awaitInvalid(() => planRecipientPayout({ ...options(), threshold }));
+    },
+  );
+  it.each(["USD", "us", "", "usd\n"])(
+    "rejects malformed currency %s",
+    (currency) => {
+      awaitInvalid(() => planRecipientPayout({ ...options(), currency }));
+    },
+  );
+  it.each(["paidAmount", "reservedAmount", "pendingCredits"] as const)(
+    "rejects negative source %s",
+    (field) => {
+      awaitInvalid(() =>
+        planRecipientPayout(options([source("tr_bad", 1000, { [field]: -1 })])),
+      );
+    },
+  );
+  it("checks every source, even an otherwise ignored currency", () => {
+    awaitInvalid(() =>
+      planRecipientPayout(
+        options([
+          source("tr_usd", 1000),
+          source("tr_bad", 1.2, { currency: "eur" }),
+        ]),
+      ),
+    );
+  });
+  it.each([NaN, Infinity, 0.1, Number.MAX_SAFE_INTEGER + 1])(
+    "rejects unsafe source money %s",
+    (matureNet) => {
+      awaitInvalid(() =>
+        planRecipientPayout(options([source("tr_bad", matureNet)])),
+      );
+    },
+  );
+  it("rejects arithmetic overflow rather than producing approximate money", () => {
+    awaitInvalid(() =>
+      planRecipientPayout(
+        options([source("tr_a", Number.MAX_SAFE_INTEGER), source("tr_b", 1)]),
+      ),
+    );
+    awaitInvalid(() =>
+      planRecipientPayout(
+        options([source("tr_a", -Number.MAX_SAFE_INTEGER, { paidAmount: 1 })]),
+      ),
+    );
+    awaitInvalid(() =>
+      planRecipientPayout({
+        ...options(),
+        providerAvailable: -Number.MAX_SAFE_INTEGER,
+        independentLiabilities: 1,
+      }),
+    );
+  });
+  it("holds on a negative provider balance without erasing entitlement", () => {
+    expect(
+      planRecipientPayout({ ...options(), providerAvailable: -100 }),
+    ).toMatchObject({
+      status: "held",
+      reason: "insufficient_available",
+      matureUnpaid: 1000,
+    });
+  });
+  it("rejects negative independent liabilities", () => {
+    awaitInvalid(() =>
+      planRecipientPayout({ ...options(), independentLiabilities: -1 }),
+    );
+  });
+});
+function awaitInvalid(action: () => unknown) {
+  expect(action).toThrow(/Invalid|Unsafe|Duplicate/);
+}

package/src/client/connect/transferReceipt.pagination.test.ts

@@ -0,0 +1,209 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import type { Component, RunCtx } from "../helpers.js";
+import { getTransferFundingReceipt } from "./transferReceipt.js";
+const symbol = Symbol.for("toReferencePath");
+const component = {
+  connect: {
+    queries: {
+      getTransferByStripeId: {
+        [symbol]: "betterStripe/connect/queries/getTransferByStripeId",
+      },
+    },
+  },
+} as unknown as Component;
+const ledger = {
+  stripeTransferId: "tr_1",
+  destinationAccountId: "acct_owner",
+  amount: 1000,
+  currency: "usd",
+  status: "paid",
+};
+const tx = (id: string, amount: number, source = "py_1") => ({
+  id,
+  source,
+  amount,
+  net: amount,
+  fee: 0,
+  currency: "usd",
+  created: 1,
+  available_on: 2,
+  status: "available",
+  type: amount > 0 ? "payment" : "adjustment",
+  exchange_rate: null,
+});
+function setup() {
+  const ctx = {
+    runQuery: vi.fn().mockResolvedValue(ledger),
+  } as unknown as RunCtx;
+  const provider = {
+    transfers: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "tr_1",
+        destination: "acct_owner",
+        destination_payment: "py_1",
+        source_transaction: null,
+        amount: 1000,
+        amount_reversed: 0,
+        currency: "usd",
+      }),
+      listReversals: vi.fn().mockResolvedValue({ data: [], has_more: false }),
+    },
+    charges: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "py_1",
+        source_transfer: "tr_1",
+        amount: 1000,
+        currency: "usd",
+        paid: true,
+        status: "succeeded",
+        balance_transaction: "txn_credit",
+      }),
+    },
+    refunds: { retrieve: vi.fn() },
+    balanceTransactions: {
+      list: vi
+        .fn()
+        .mockResolvedValue({ data: [tx("txn_credit", 1000)], has_more: false }),
+    },
+  };
+  return {
+    ctx,
+    provider,
+    run: (extra: object = {}) =>
+      getTransferFundingReceipt(provider as unknown as Stripe, component, ctx, {
+        accountId: "acct_owner",
+        stripeTransferId: "tr_1",
+        ...extra,
+      }),
+  };
+}
+it("reads all 205 source receipts instead of truncating at the first provider page", async () => {
+  const { provider, run } = setup();
+  const rows = [
+    tx("txn_credit", 1000),
+    ...Array.from({ length: 204 }, (_, i) => tx(`txn_fee_${i}`, -1)),
+  ];
+  provider.balanceTransactions.list.mockImplementation(
+    async (args: { starting_after?: string }) => {
+      const start = args.starting_after
+        ? rows.findIndex((t) => t.id === args.starting_after) + 1
+        : 0;
+      return {
+        data: rows.slice(start, start + 100),
+        has_more: start + 100 < rows.length,
+      };
+    },
+  );
+  const result = await run();
+  expect(result).toMatchObject({
+    status: "ready",
+    totalNet: 796,
+    matureNet: 796,
+    pendingCredits: 0,
+  });
+  if (result.status === "ready") expect(result.transactions).toHaveLength(205);
+  expect(provider.balanceTransactions.list).toHaveBeenCalledTimes(3);
+  const limited = await run({ maxRequests: 6 });
+  expect(limited).toMatchObject({
+    status: "not_ready",
+    reason: "history_incomplete",
+  });
+  expect(limited).not.toHaveProperty("totalNet");
+});
+it("does not publish a source snapshot if its authoritative ledger changed during the read", async () => {
+  const { ctx, run } = setup();
+  (ctx.runQuery as ReturnType<typeof vi.fn>)
+    .mockReset()
+    .mockResolvedValueOnce(ledger)
+    .mockResolvedValueOnce({ ...ledger, reversedAmount: 1 });
+  expect(await run()).toMatchObject({
+    status: "not_ready",
+    reason: "ledger_changed",
+  });
+});
+it("propagates genuine provider failures and detects aggregate overflow", async () => {
+  const { provider, run } = setup();
+  provider.charges.retrieve.mockRejectedValueOnce(
+    new Error("provider unavailable"),
+  );
+  await expect(run()).rejects.toThrow("provider unavailable");
+  provider.balanceTransactions.list.mockResolvedValue({
+    data: [
+      tx("txn_credit", 1000),
+      { ...tx("txn_extra", Number.MAX_SAFE_INTEGER), type: "adjustment" },
+    ],
+    has_more: false,
+  });
+  await expect(run()).rejects.toThrow("safe integers");
+});
+it("never uses a pending fee credit to qualify a fully returned mature transfer", async () => {
+  const { ctx, provider, run } = setup();
+  (ctx.runQuery as ReturnType<typeof vi.fn>).mockResolvedValue({
+    ...ledger,
+    reversedAmount: 1000,
+  });
+  provider.transfers.retrieve.mockResolvedValue({
+    id: "tr_1",
+    destination: "acct_owner",
+    destination_payment: "py_1",
+    source_transaction: null,
+    amount: 1000,
+    amount_reversed: 1000,
+    currency: "usd",
+  });
+  provider.transfers.listReversals.mockResolvedValue({
+    data: [
+      {
+        id: "trr_1",
+        transfer: "tr_1",
+        amount: 1000,
+        currency: "usd",
+        destination_payment_refund: "pyr_1",
+      },
+    ],
+    has_more: false,
+  } as never);
+  provider.refunds.retrieve.mockResolvedValue({
+    id: "pyr_1",
+    charge: "py_1",
+    amount: 1000,
+    currency: "usd",
+    status: "succeeded",
+    balance_transaction: "txn_debit",
+  });
+  provider.balanceTransactions.list.mockImplementation(
+    async (args: { source: string }) => ({
+      data:
+        args.source === "py_1"
+          ? [
+              tx("txn_credit", 1000),
+              { ...tx("txn_fee_credit", 100), status: "pending" },
+            ]
+          : [{ ...tx("txn_debit", -1000, "pyr_1"), status: "pending" }],
+      has_more: false,
+    }),
+  );
+  expect(await run()).toMatchObject({
+    status: "ready",
+    totalNet: 100,
+    matureNet: 0,
+    pendingCredits: 100,
+  });
+});
+it("preserves an already available debit while its original credit is pending", async () => {
+  const { provider, run } = setup();
+  provider.balanceTransactions.list.mockResolvedValue({
+    data: [
+      { ...tx("txn_credit", 1000), status: "pending" },
+      tx("txn_fee", -200),
+    ],
+    has_more: false,
+  });
+  expect(await run()).toMatchObject({
+    status: "ready",
+    totalNet: 800,
+    matureNet: -200,
+    pendingCredits: 1000,
+  });
+});