@fantastic.dev/better-stripe 0.9.0 → 0.10.1

package/src/client/settlement/allocation.test.ts

@@ -0,0 +1,98 @@
+import { expect, it } from "vitest";
+import { allocateSale } from "./allocation.js";
+it("allocates processing and plan fees before affiliate and collaborators", () => {
+  const result = allocateSale({
+    gross: 10000,
+    processingFee: 320,
+    feeBasisPoints: 900,
+    creatorAccountId: "acct_creator",
+    affiliate: { destinationAccountId: "acct_affiliate", basisPoints: 2000 },
+    collaborators: [{ destinationAccountId: "acct_other", basisPoints: 2500 }],
+  });
+  expect(result).toMatchObject({
+    sellingFee: 900,
+    platformNet: 580,
+    affiliateNet: 1820,
+    creatorNet: 5460,
+    collaboratorNet: 1820,
+  });
+  expect(
+    result.transfers.reduce((n, t) => n + t.amount, 0) + result.sellingFee,
+  ).toBe(result.gross);
+});
+it("caps fixed commissions and applies the processing fee floor", () => {
+  expect(
+    allocateSale({
+      gross: 10000,
+      processingFee: 700,
+      feeBasisPoints: 490,
+      creatorAccountId: "acct_creator",
+      affiliate: { destinationAccountId: "acct_a", fixedAmount: 99999 },
+    }),
+  ).toMatchObject({ affiliateNet: 9300, creatorNet: 0, platformNet: 0 });
+  expect(
+    allocateSale({
+      gross: 12900,
+      processingFee: 404,
+      feeBasisPoints: 490,
+      creatorAccountId: "acct_c",
+      affiliate: { destinationAccountId: "acct_a", basisPoints: 2000 },
+    }),
+  ).toMatchObject({ affiliateNet: 2453, creatorNet: 9815 });
+});
+it("retains rounding residue for the creator and rejects invalid or duplicate shares", () => {
+  const opts = {
+    gross: 101,
+    processingFee: 0,
+    creatorAccountId: "acct_c",
+    collaborators: [
+      { destinationAccountId: "acct_a", basisPoints: 3333 },
+      { destinationAccountId: "acct_b", basisPoints: 3333 },
+    ],
+  };
+  expect(allocateSale(opts)).toMatchObject({
+    creatorNet: 35,
+    collaboratorNet: 66,
+    affiliateNet: 0,
+  });
+  expect(() =>
+    allocateSale({
+      ...opts,
+      collaborators: [{ destinationAccountId: "acct_a", basisPoints: 10001 }],
+    }),
+  ).toThrow();
+  expect(() =>
+    allocateSale({
+      ...opts,
+      collaborators: [opts.collaborators[0], opts.collaborators[0]],
+    }),
+  ).toThrow();
+  expect(() => allocateSale({ ...opts, gross: 1.5 })).toThrow();
+  expect(() =>
+    allocateSale({
+      ...opts,
+      affiliate: {
+        destinationAccountId: "acct_z",
+        fixedAmount: 1,
+        basisPoints: 1,
+      },
+    }),
+  ).toThrow();
+});
+it("supports zero-dollar previews and zero affiliate shares", () => {
+  expect(
+    allocateSale({
+      gross: 0,
+      processingFee: 0,
+      creatorAccountId: "acct_creator",
+    }),
+  ).toMatchObject({ gross: 0, creatorNet: 0, affiliateNet: 0, platformNet: 0 });
+  expect(
+    allocateSale({
+      gross: 100,
+      processingFee: 3,
+      creatorAccountId: "acct_creator",
+      affiliate: { destinationAccountId: "acct_a", basisPoints: 0 },
+    }),
+  ).toMatchObject({ creatorNet: 97, affiliateNet: 0 });
+});

package/src/client/settlement/allocation.ts

@@ -0,0 +1,110 @@
+import type { SplitTransfer } from "../core/fees.js";
+export type SaleAllocationOptions = {
+  gross: number;
+  processingFee: number;
+  /** Inclusive sale fee, with actual Stripe processing as its floor. */
+  feeBasisPoints?: number | null;
+  creatorAccountId: string;
+  affiliate?: {
+    destinationAccountId: string;
+    basisPoints?: number;
+    fixedAmount?: number;
+  };
+  collaborators?: { destinationAccountId: string; basisPoints: number }[];
+};
+export type SaleAllocation = {
+  gross: number;
+  processingFee: number;
+  sellingFee: number;
+  platformNet: number;
+  affiliateNet: number;
+  creatorNet: number;
+  collaboratorNet: number;
+  transfers: SplitTransfer[];
+};
+const basisPoints = (n: number) => {
+  if (!Number.isSafeInteger(n) || n < 0 || n > 10000)
+    throw new Error("Share must be an integer from 0 to 10000 basis points.");
+  return n;
+};
+const units = (n: number) => {
+  if (!Number.isSafeInteger(n) || n < 0)
+    throw new Error(
+      "Amounts must be non-negative safe integer currency units.",
+    );
+  return n;
+};
+const share = (amount: number, rate: number) =>
+  Number((BigInt(amount) * BigInt(basisPoints(rate))) / 10000n);
+/** Pure fee-first allocation. Fixed amounts are minor units of the sale currency. */
+export function allocateSale(opts: SaleAllocationOptions): SaleAllocation {
+  const gross = units(opts.gross),
+    processingFee = units(opts.processingFee);
+  if (processingFee > gross || !opts.creatorAccountId)
+    throw new Error("Invalid gross amount, processing fee or creator account.");
+  const rate = basisPoints(opts.feeBasisPoints ?? 0);
+  const sellingFee = Math.max(
+    processingFee,
+    Number((BigInt(gross) * BigInt(rate) + 5000n) / 10000n),
+  );
+  const net = gross - sellingFee;
+  const affiliate = opts.affiliate;
+  if (
+    affiliate &&
+    (!affiliate.destinationAccountId ||
+      (affiliate.fixedAmount !== undefined &&
+        affiliate.basisPoints !== undefined))
+  )
+    throw new Error(
+      "Choose one affiliate amount or percentage and a destination.",
+    );
+  const affiliateNet = affiliate
+    ? Math.min(
+        net,
+        affiliate.fixedAmount !== undefined
+          ? units(affiliate.fixedAmount)
+          : share(net, affiliate.basisPoints ?? 0),
+      )
+    : 0;
+  const creatorRemainder = net - affiliateNet;
+  const collaborators = opts.collaborators ?? [];
+  if (
+    collaborators.reduce((sum, r) => sum + basisPoints(r.basisPoints), 0) >
+    10000
+  )
+    throw new Error("Collaborator shares exceed the creator remainder.");
+  const seen = new Set<string>();
+  const transfers: SplitTransfer[] = collaborators.map((r) => {
+    if (!r.destinationAccountId || seen.has(r.destinationAccountId))
+      throw new Error("Collaborator destinations must be nonempty and unique.");
+    seen.add(r.destinationAccountId);
+    return {
+      destinationAccountId: r.destinationAccountId,
+      role: "other",
+      amount: share(creatorRemainder, r.basisPoints),
+    };
+  });
+  const collaboratorNet = transfers.reduce((sum, r) => sum + r.amount, 0);
+  const creatorNet = creatorRemainder - collaboratorNet;
+  transfers.unshift({
+    destinationAccountId: opts.creatorAccountId,
+    role: "store",
+    amount: creatorNet,
+  });
+  if (affiliate)
+    transfers.push({
+      destinationAccountId: affiliate.destinationAccountId,
+      role: "affiliate",
+      amount: affiliateNet,
+    });
+  return {
+    gross,
+    processingFee,
+    sellingFee,
+    platformNet: sellingFee - processingFee,
+    affiliateNet,
+    creatorNet,
+    collaboratorNet,
+    transfers,
+  };
+}

package/src/client/settlement/commissions.test.ts

@@ -0,0 +1,103 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import type { Component, RunCtx } from "../helpers.js";
+import { selectCommissionInvoice } from "./commissions.js";
+const ref = (path: string) => ({
+  [Symbol.for("toReferencePath")]: `betterStripe/${path}`,
+});
+const component = {
+  settlement: {
+    commissions: {
+      get: ref("settlement/queries/getCommissionTerm"),
+      claim: ref("settlement/mutations/claimCommissionInvoice"),
+    },
+  },
+} as unknown as Component;
+it("finds the first paid nonzero invoice across provider pages and ignores trial invoices", async () => {
+  const list = vi
+    .fn()
+    .mockResolvedValueOnce({
+      data: [
+        {
+          id: "in_later",
+          amount_paid: 100,
+          status_transitions: { paid_at: 20 },
+          created: 20,
+        },
+        {
+          id: "in_trial",
+          amount_paid: 0,
+          status_transitions: { paid_at: 1 },
+          created: 1,
+        },
+      ],
+      has_more: true,
+    })
+    .mockResolvedValueOnce({
+      data: [
+        {
+          id: "in_first",
+          amount_paid: 100,
+          status_transitions: { paid_at: 10 },
+          created: 2,
+        },
+      ],
+      has_more: false,
+    });
+  const raw = {
+    invoices: {
+      list,
+      retrieve: vi.fn().mockResolvedValue({
+        id: "in_later",
+        status: "paid",
+        amount_paid: 100,
+        parent: { subscription_details: { subscription: "sub_1" } },
+      }),
+    },
+  };
+  const runMutation = vi.fn(async (_ref, args) => ({
+    ...args,
+    eligible: false,
+    replay: false,
+    claimKey: "key",
+  }));
+  const ctx = {
+    runQuery: vi.fn().mockResolvedValue(null),
+    runMutation,
+  } as unknown as RunCtx;
+  await selectCommissionInvoice(raw as unknown as Stripe, component, ctx, {
+    subscriptionId: "sub_1",
+    invoiceId: "in_later",
+    affiliateAccountId: "acct_a",
+    term: "one_time",
+  });
+  expect(runMutation).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      firstPaidInvoiceId: "in_first",
+      term: "one_time",
+    }),
+  );
+  expect(list).toHaveBeenCalledTimes(2);
+});
+it("does not consume a failed or zero-dollar invoice", async () => {
+  const raw = {
+    invoices: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "in_trial",
+        status: "paid",
+        amount_paid: 0,
+        parent: { subscription_details: { subscription: "sub_1" } },
+      }),
+    },
+  };
+  const mutation = vi.fn(),
+    ctx = { runQuery: vi.fn(), runMutation: mutation } as unknown as RunCtx;
+  expect(
+    await selectCommissionInvoice(raw as unknown as Stripe, component, ctx, {
+      subscriptionId: "sub_1",
+      invoiceId: "in_trial",
+    }),
+  ).toMatchObject({ status: "not_payable", eligible: false });
+  expect(mutation).not.toHaveBeenCalled();
+});

package/src/client/settlement/commissions.ts

@@ -0,0 +1,125 @@
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { isBetterStripeError, throwStripeError } from "../errors.js";
+export type CommissionTerm = "forever" | "one_time";
+export type CommissionSelectionOptions = {
+  subscriptionId: string;
+  invoiceId: string;
+  affiliateAccountId?: string;
+  term?: CommissionTerm;
+  maxHistoryPages?: number;
+};
+export type CommissionDecision = {
+  eligible: boolean;
+  term: CommissionTerm;
+  firstPaidInvoiceId: string;
+  claimKey: string;
+  replay: boolean;
+};
+export type CommissionSelection =
+  | ({ status: "ready" } & CommissionDecision)
+  | { status: "not_payable"; eligible: false; reason: string };
+type Stored = {
+  subscriptionId: string;
+  term: CommissionTerm;
+  affiliateAccountId?: string;
+  firstPaidInvoiceId: string;
+};
+/** Durable selection only. Replay returns the same award key; execute through settleSale. */
+export async function selectCommissionInvoice(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: CommissionSelectionOptions,
+): Promise<CommissionSelection> {
+  try {
+    const invoice = await stripe.invoices.retrieve(opts.invoiceId);
+    const pointer = invoice.parent?.subscription_details?.subscription;
+    if (
+      (typeof pointer === "string" ? pointer : pointer?.id) !==
+      opts.subscriptionId
+    )
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Invoice does not belong to this subscription.",
+      );
+    if (invoice.status !== "paid" || invoice.amount_paid <= 0)
+      return {
+        status: "not_payable",
+        eligible: false,
+        reason: "invoice_not_paid_or_zero",
+      };
+    const stored = (await ctx.runQuery(
+      componentRef(component, "settlement/queries/getCommissionTerm"),
+      { subscriptionId: opts.subscriptionId },
+    )) as Stored | null;
+    let firstPaidInvoiceId = stored?.firstPaidInvoiceId ?? invoice.id;
+    const term = stored?.term ?? opts.term ?? "forever";
+    if (!stored && term === "one_time") {
+      const max = opts.maxHistoryPages ?? 100;
+      if (!Number.isInteger(max) || max < 1 || max > 1000)
+        throwStripeError(
+          "INVALID_CONFIGURATION",
+          "Invalid invoice history page bound.",
+        );
+      let cursor: string | undefined,
+        earliest: number = Infinity,
+        complete = false;
+      for (let i = 0; i < max; i++) {
+        const batch = await stripe.invoices.list({
+          subscription: opts.subscriptionId,
+          status: "paid",
+          limit: 100,
+          starting_after: cursor,
+        });
+        for (const row of batch.data)
+          if (row.amount_paid > 0) {
+            const paid = row.status_transitions.paid_at ?? row.created;
+            if (
+              paid < earliest ||
+              (paid === earliest && row.id < firstPaidInvoiceId)
+            ) {
+              earliest = paid;
+              firstPaidInvoiceId = row.id;
+            }
+          }
+        if (!batch.has_more) {
+          complete = true;
+          break;
+        }
+        const next = batch.data[batch.data.length - 1]?.id;
+        if (!next || next === cursor)
+          throwStripeError(
+            "STRIPE_API_ERROR",
+            "Invoice pagination did not advance.",
+          );
+        cursor = next;
+      }
+      if (!complete || !Number.isFinite(earliest))
+        throwStripeError(
+          "INVALID_CONFIGURATION",
+          "First paid invoice could not be established from complete history.",
+        );
+    }
+    const decision = (await runMutationOrThrow(
+      ctx,
+      componentRef(component, "settlement/mutations/claimCommissionInvoice"),
+      {
+        subscriptionId: opts.subscriptionId,
+        invoiceId: invoice.id,
+        firstPaidInvoiceId,
+        affiliateAccountId: opts.affiliateAccountId,
+        term,
+      },
+    )) as CommissionDecision;
+    return { status: "ready", ...decision };
+  } catch (error) {
+    if (isBetterStripeError(error)) throw error;
+    throwStripeError(
+      "STRIPE_API_ERROR",
+      "Could not select subscription commission invoice.",
+    );
+  }
+}

package/src/client/settlement/execution.test.ts

@@ -0,0 +1,186 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import type { Component, RunCtx } from "../helpers.js";
+import { executeResolvedTransfers } from "./execution.js";
+const TO_REF = Symbol.for("toReferencePath");
+const ref = (path: string) => ({ [TO_REF]: `betterStripe/${path}` });
+const component = {
+  settlement: {
+    claims: {
+      reserve: ref("settlement/mutations/reserveSettlementAllocation"),
+    },
+  },
+  connect: {
+    queries: {
+      listTransfersByCharge: ref("connect/queries/listTransfersByCharge"),
+    },
+    mutations: { upsertTransfer: ref("connect/mutations/upsertTransfer") },
+  },
+} as unknown as Component;
+it("recovers provider success after a ledger failure even without an idempotency cache", async () => {
+  let claimed: unknown;
+  const ledger: unknown[] = [],
+    provider: Record<string, unknown>[] = [];
+  let fail = true;
+  const runMutation = vi.fn(
+    async (r: Record<symbol, string>, args: Record<string, unknown>) => {
+      if (r[TO_REF].endsWith("/reserveSettlementAllocation"))
+        return claimed ?? (claimed = { ...args });
+      if (fail) {
+        fail = false;
+        throw new Error("ledger unavailable");
+      }
+      ledger.push(args);
+    },
+  );
+  const ctx = {
+    runMutation,
+    runQuery: vi.fn(async () => ledger),
+  } as unknown as RunCtx;
+  const raw = {
+    charges: { retrieve: vi.fn().mockResolvedValue({ created: 1 }) },
+    transfers: {
+      list: vi.fn(async () => ({ data: provider, has_more: false })),
+      create: vi.fn(async (args) => {
+        const transfer = {
+          id: `tr_${provider.length}`,
+          destination: args.destination,
+          ...args,
+        };
+        provider.push(transfer);
+        return transfer;
+      }),
+    },
+  };
+  const opts = {
+    sourceChargeId: "ch_1",
+    gross: 100,
+    currency: "usd",
+    processingFee: 3,
+    platformNet: 7,
+    transfers: [
+      { destinationAccountId: "acct_c", role: "store" as const, amount: 80 },
+      {
+        destinationAccountId: "acct_a",
+        role: "affiliate" as const,
+        amount: 10,
+      },
+    ],
+  };
+  await expect(
+    executeResolvedTransfers(raw as unknown as Stripe, component, ctx, opts),
+  ).rejects.toThrow("ledger unavailable");
+  const result = await executeResolvedTransfers(
+    raw as unknown as Stripe,
+    component,
+    ctx,
+    {
+      ...opts,
+      platformNet: 17,
+      transfers: [{ ...opts.transfers[0], amount: 70 }, opts.transfers[1]],
+    },
+  );
+  expect(raw.transfers.create).toHaveBeenCalledTimes(2);
+  expect(result.transfers.map((t) => t.amount)).toEqual([80, 10]);
+  expect(ledger).toHaveLength(2);
+  await executeResolvedTransfers(
+    raw as unknown as Stripe,
+    component,
+    ctx,
+    opts,
+  );
+  expect(raw.transfers.create).toHaveBeenCalledTimes(2);
+});
+it("recovers an orphaned original leg for refund/dispute clawback without creating more transfers", async () => {
+  const { recoverSettlementTransfers } = await import("./reconciliation.js");
+  const claim = {
+    sourceChargeId: "ch_refund",
+    gross: 100,
+    currency: "usd",
+    processingFee: 3,
+    platformNet: 7,
+    transfers: [
+      { destinationAccountId: "acct_c", role: "store" as const, amount: 90 },
+    ],
+  };
+  const provider = {
+    id: "tr_orphan",
+    destination: "acct_c",
+    amount: 90,
+    currency: "usd",
+    source_transaction: "ch_refund",
+    amount_reversed: 20,
+    metadata: { bsSourceCharge: "ch_refund", bsRole: "store" },
+  };
+  const raw = {
+    transfers: {
+      list: vi.fn().mockResolvedValue({ data: [provider], has_more: false }),
+      create: vi.fn(),
+    },
+  };
+  const runMutation = vi.fn(),
+    ctx = {
+      runQuery: vi.fn().mockResolvedValue(claim),
+      runMutation,
+    } as unknown as RunCtx;
+  await recoverSettlementTransfers(
+    raw as unknown as Stripe,
+    component,
+    ctx,
+    "ch_refund",
+  );
+  expect(runMutation).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      stripeTransferId: "tr_orphan",
+      sourceChargeId: "ch_refund",
+      amount: 90,
+      reversedAmount: 20,
+    }),
+  );
+  expect(raw.transfers.create).not.toHaveBeenCalled();
+});
+it("finds legacy transfers without a transfer group before issuing a new request", async () => {
+  const legacy = {
+    id: "tr_legacy",
+    destination: "acct_c",
+    amount: 90,
+    currency: "usd",
+    source_transaction: "ch_old",
+    metadata: { bsSourceCharge: "ch_old", bsRole: "store" },
+  };
+  const raw = {
+    charges: { retrieve: vi.fn().mockResolvedValue({ created: 1 }) },
+    transfers: {
+      list: vi.fn(async (params: { transfer_group?: string }) => ({
+        data: params.transfer_group ? [] : [legacy],
+        has_more: false,
+      })),
+      create: vi.fn().mockResolvedValue({ id: "tr_duplicate" }),
+    },
+  };
+  const opts = {
+    sourceChargeId: "ch_old",
+    gross: 100,
+    currency: "usd",
+    processingFee: 3,
+    platformNet: 7,
+    transfers: [
+      { destinationAccountId: "acct_c", role: "store" as const, amount: 90 },
+    ],
+  };
+  const ctx = {
+    runQuery: vi.fn().mockResolvedValue([]),
+    runMutation: vi.fn(async (r: Record<symbol, string>, args: unknown) =>
+      r[TO_REF].endsWith("reserveSettlementAllocation") ? args : null,
+    ),
+  } as unknown as RunCtx;
+  const result = await executeResolvedTransfers(
+    raw as unknown as Stripe,
+    component,
+    ctx,
+    opts,
+  );
+  expect(result.executedTransfers[0].stripeTransferId).toBe("tr_legacy");
+  expect(raw.transfers.create).not.toHaveBeenCalled();
+});