@fantastic.dev/better-stripe 0.11.0 → 0.13.0

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

@@ -0,0 +1,349 @@
+import type Stripe from "stripe";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getProcessingCostContext } from "./processingCosts.js";
+
+const transaction = (
+  id: string,
+  amount: number,
+  fee: number,
+  currency = "usd",
+) => ({
+  id,
+  amount,
+  fee,
+  net: amount - fee,
+  currency,
+  created: 1800000000,
+});
+const charge = {
+  id: "ch_1",
+  payment_intent: "pi_1",
+  amount: 10000,
+  amount_captured: 10000,
+  currency: "usd",
+  disputed: false,
+  amount_refunded: 0,
+  balance_transaction: transaction("txn_charge", 10000, 320),
+};
+const payment = {
+  id: "pi_1",
+  status: "succeeded",
+  currency: "usd",
+  amount_received: 10000,
+  metadata: { sellerId: "store" },
+  latest_charge: charge,
+};
+const raw = {
+  paymentIntents: { retrieve: vi.fn() },
+  balanceTransactions: { retrieve: vi.fn() },
+  refunds: { list: vi.fn() },
+  disputes: { list: vi.fn() },
+};
+const stripe = raw as unknown as Stripe;
+function page<T>(items: T[]) {
+  return (async function* () {
+    for (const item of items) yield item;
+  })();
+}
+const refund = (id: string, amount: number, fee = 0) => ({
+  id,
+  amount,
+  currency: "usd",
+  charge: "ch_1",
+  payment_intent: "pi_1",
+  status: "succeeded",
+  balance_transaction: transaction(`txn_${id}`, -amount, fee),
+  failure_balance_transaction: null,
+});
+const dispute = (
+  status: string,
+  transactions: ReturnType<typeof transaction>[],
+) => ({
+  id: "dp_1",
+  charge: "ch_1",
+  payment_intent: "pi_1",
+  amount: 10000,
+  currency: "usd",
+  status,
+  balance_transactions: transactions,
+});
+beforeEach(() => {
+  vi.resetAllMocks();
+  raw.paymentIntents.retrieve.mockResolvedValue(payment);
+  raw.refunds.list.mockImplementation(() => page([]));
+  raw.disputes.list.mockImplementation(() => page([]));
+});
+describe("authoritative processing-cost context", () => {
+  it("returns signed source-linked provider transactions and integer fees without initiating settlement", async () => {
+    const result = await getProcessingCostContext(stripe, {
+      paymentIntentId: "pi_1",
+    });
+    expect(result).toMatchObject({
+      status: "ready",
+      paymentIntentId: "pi_1",
+      chargeId: "ch_1",
+      currency: "usd",
+      gross: 10000,
+      processingFee: 320,
+      refundFeeAdjustment: 0,
+      disputeFeeAdjustment: 0,
+      netFees: 320,
+      refundedPrincipal: 0,
+      disputedPrincipal: 0,
+      principalReturned: 0,
+      transactions: [
+        {
+          id: "txn_charge",
+          sourceId: "ch_1",
+          sourceType: "charge",
+          amount: 10000,
+          fee: 320,
+          net: 9680,
+          created: 1800000000000,
+        },
+      ],
+    });
+  });
+  it("includes cumulative partial refunds and signed returned processing fees", async () => {
+    raw.refunds.list.mockImplementation(() =>
+      page([refund("re_first", 2000, -64), refund("re_second", 3000, -96)]),
+    );
+    raw.paymentIntents.retrieve.mockResolvedValue({
+      ...payment,
+      latest_charge: { ...charge, amount_refunded: 5000 },
+    });
+    expect(
+      await getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).toMatchObject({
+      status: "ready",
+      refundedPrincipal: 5000,
+      principalReturned: 5000,
+      processingFee: 320,
+      refundFeeAdjustment: -160,
+      netFees: 160,
+    });
+  });
+  it.each(["lost", "needs_response"])(
+    "accounts for %s dispute principal and fees once",
+    async (status) => {
+      raw.disputes.list.mockImplementation(() =>
+        page([dispute(status, [transaction("txn_dispute", -10000, 1500)])]),
+      );
+      raw.paymentIntents.retrieve.mockResolvedValue({
+        ...payment,
+        latest_charge: { ...charge, disputed: true },
+      });
+      expect(
+        await getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+      ).toMatchObject({
+        status: "ready",
+        disputedPrincipal: 10000,
+        principalReturned: 10000,
+        disputeFeeAdjustment: 1500,
+        netFees: 1820,
+      });
+    },
+  );
+  it("handles won disputes and fee credits without retaining principal or assuming all fees return", async () => {
+    raw.disputes.list.mockImplementation(() =>
+      page([
+        dispute("won", [
+          transaction("txn_withdraw", -10000, 1500),
+          transaction("txn_reinstate", 10000, -1000),
+        ]),
+      ]),
+    );
+    expect(
+      await getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).toMatchObject({
+      status: "ready",
+      disputedPrincipal: 0,
+      principalReturned: 0,
+      disputeFeeAdjustment: 500,
+      netFees: 820,
+    });
+  });
+  it("does not double-count principal when refund and dispute observations overlap", async () => {
+    raw.refunds.list.mockImplementation(() =>
+      page([refund("re_partial", 2000)]),
+    );
+    raw.disputes.list.mockImplementation(() =>
+      page([dispute("lost", [transaction("txn_dispute", -10000, 1500)])]),
+    );
+    const result = await getProcessingCostContext(stripe, {
+      paymentIntentId: "pi_1",
+    });
+    expect(result).toMatchObject({
+      status: "ready",
+      refundedPrincipal: 2000,
+      disputedPrincipal: 10000,
+      principalReturned: 10000,
+    });
+    if (result.status === "ready")
+      expect(
+        result.transactions
+          .filter((t) => t.sourceType !== "charge")
+          .reduce((n, t) => n + t.amount, 0),
+      ).toBe(-12000);
+  });
+  it("walks every refund and dispute page rather than using a capped preview", async () => {
+    raw.refunds.list.mockImplementation(() =>
+      page(Array.from({ length: 101 }, (_, i) => refund(`re_${i}`, 10))),
+    );
+    raw.disputes.list.mockImplementation(() =>
+      page(
+        Array.from({ length: 101 }, (_, i) => ({
+          ...dispute("warning_closed", []),
+          id: `dp_${i}`,
+        })),
+      ),
+    );
+    const result = await getProcessingCostContext(stripe, {
+      paymentIntentId: "pi_1",
+    });
+    expect(result).toMatchObject({ status: "ready", refundedPrincipal: 1010 });
+    if (result.status === "ready") {
+      expect(result.refunds).toHaveLength(101);
+      expect(result.disputes).toHaveLength(101);
+      expect(result.transactions).toHaveLength(102);
+    }
+  });
+  it("returns explicit not-ready states for absent fees and pending refunds", async () => {
+    raw.paymentIntents.retrieve.mockResolvedValueOnce({
+      ...payment,
+      latest_charge: { ...charge, balance_transaction: null },
+    });
+    expect(
+      await getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).toMatchObject({
+      status: "not_ready",
+      reason: "charge_transaction_unavailable",
+    });
+    raw.refunds.list.mockImplementation(() =>
+      page([
+        {
+          ...refund("re_pending", 1000),
+          status: "pending",
+          balance_transaction: null,
+        },
+      ]),
+    );
+    expect(
+      await getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).toMatchObject({ status: "not_ready", reason: "refund_pending" });
+  });
+  it("includes a failed refund's reversal rather than counting a returned principal twice", async () => {
+    raw.refunds.list.mockImplementation(() =>
+      page([
+        {
+          ...refund("re_failed", 1000, 10),
+          status: "failed",
+          failure_balance_transaction: transaction("txn_failure", 1000, -10),
+        },
+      ]),
+    );
+    expect(
+      await getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).toMatchObject({
+      status: "ready",
+      refundedPrincipal: 0,
+      refundFeeAdjustment: 0,
+      principalReturned: 0,
+      netFees: 320,
+    });
+  });
+  it("rejects inconsistent source linkage and fractional provider amounts", async () => {
+    raw.refunds.list.mockImplementation(() =>
+      page([{ ...refund("re_other", 1000), charge: "ch_other" }]),
+    );
+    await expect(
+      getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).rejects.toThrow(/belong/);
+    raw.refunds.list.mockImplementation(() =>
+      page([refund("re_bad", 1000, 0.5)]),
+    );
+    await expect(
+      getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).rejects.toThrow(/integer/);
+  });
+  it("never combines amounts in different currencies", async () => {
+    raw.refunds.list.mockImplementation(() =>
+      page([
+        {
+          ...refund("re_fx", 1000),
+          balance_transaction: transaction("txn_fx", -1000, 0, "eur"),
+        },
+      ]),
+    );
+    expect(
+      await getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).toMatchObject({ status: "not_ready", reason: "currency_mismatch" });
+  });
+  it("preserves provider errors instead of returning incomplete cost data", async () => {
+    const error = Object.assign(new Error("Provider unavailable"), {
+      statusCode: 503,
+    });
+    raw.disputes.list.mockImplementation(() =>
+      (async function* () {
+        yield dispute("warning_closed", []);
+        throw error;
+      })(),
+    );
+    await expect(
+      getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+    ).rejects.toBe(error);
+  });
+});
+it("waits for a won dispute's principal reinstatement instead of reporting the old withdrawal as owed", async () => {
+  raw.disputes.list.mockImplementation(() =>
+    page([dispute("won", [transaction("txn_out", -10000, 1500)])]),
+  );
+  expect(
+    await getProcessingCostContext(stripe, { paymentIntentId: "pi_1" }),
+  ).toMatchObject({
+    status: "not_ready",
+    reason: "dispute_reinstatement_unavailable",
+  });
+});
+it("exposes provider fee breakdowns so application fees are not mistaken for processor fees", async () => {
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    latest_charge: {
+      ...charge,
+      balance_transaction: {
+        ...transaction("txn_charge", 10000, 820),
+        fee_details: [
+          {
+            type: "stripe_fee",
+            amount: 320,
+            currency: "usd",
+            application: null,
+            description: "Processing",
+          },
+          {
+            type: "application_fee",
+            amount: 500,
+            currency: "usd",
+            application: "ca_platform",
+            description: "Platform",
+          },
+        ],
+      },
+    },
+  });
+  const result = await getProcessingCostContext(stripe, {
+    paymentIntentId: "pi_1",
+  });
+  expect(result).toMatchObject({
+    status: "ready",
+    processingFee: 820,
+    transactions: [
+      {
+        feeDetails: [
+          { type: "stripe_fee", amount: 320 },
+          { type: "application_fee", amount: 500 },
+        ],
+      },
+    ],
+  });
+});

package/src/client/settlement/processingCosts.ts

@@ -0,0 +1,315 @@
+import type Stripe from "stripe";
+
+export type ProcessingCostOptions = {
+  /** Host authorizes the payment and optional connected-account context. */
+  paymentIntentId: string;
+  stripeAccountId?: string;
+};
+export type ProcessingCostTransaction = {
+  id: string;
+  sourceId: string;
+  sourceType: "charge" | "refund" | "refund_failure" | "dispute";
+  currency: string;
+  amount: number;
+  fee: number;
+  net: number;
+  created: number;
+  feeDetails:
+    | {
+        type: string;
+        amount: number;
+        currency: string;
+        application: string | null;
+        description: string | null;
+      }[]
+    | null;
+};
+export type ProcessingCostRecord = {
+  id: string;
+  status: string;
+  amount: number;
+  balanceTransactionIds: string[];
+};
+export type ProcessingCostNotReadyReason =
+  | "payment_not_succeeded"
+  | "charge_unavailable"
+  | "charge_transaction_unavailable"
+  | "refund_transaction_unavailable"
+  | "refund_failure_transaction_unavailable"
+  | "refund_pending"
+  | "dispute_transactions_unavailable"
+  | "dispute_reinstatement_unavailable"
+  | "currency_mismatch";
+export type ProcessingCostContext =
+  | {
+      status: "not_ready";
+      paymentIntentId: string;
+      reason: ProcessingCostNotReadyReason;
+    }
+  | {
+      status: "ready";
+      paymentIntentId: string;
+      chargeId: string;
+      currency: string;
+      gross: number;
+      metadata: Record<string, string>;
+      processingFee: number;
+      refundFeeAdjustment: number;
+      disputeFeeAdjustment: number;
+      netFees: number;
+      refundedPrincipal: number;
+      disputedPrincipal: number;
+      /** Capped economic principal; raw provider debits remain in transactions. */
+      principalReturned: number;
+      refunds: ProcessingCostRecord[];
+      disputes: ProcessingCostRecord[];
+      transactions: ProcessingCostTransaction[];
+    };
+class NotReady extends Error {
+  constructor(readonly reason: ProcessingCostNotReadyReason) {
+    super(reason);
+  }
+}
+const id = (value: string | { id: string } | null) =>
+  typeof value === "string" ? value : value?.id;
+function integer(value: number) {
+  if (!Number.isSafeInteger(value))
+    throw new Error("Processing cost amounts and dates must be safe integers.");
+  return value;
+}
+const sum = (values: number[]) => values.reduce((a, b) => integer(a + b), 0);
+
+/** Authoritative read only. Refunded/disputed charges are valid cost sources. */
+export async function getProcessingCostContext(
+  stripe: Stripe,
+  opts: ProcessingCostOptions,
+): Promise<ProcessingCostContext> {
+  const requestOptions = opts.stripeAccountId
+    ? { stripeAccount: opts.stripeAccountId }
+    : undefined;
+  try {
+    const payment = await stripe.paymentIntents.retrieve(
+      opts.paymentIntentId,
+      { expand: ["latest_charge.balance_transaction"] },
+      requestOptions,
+    );
+    if (payment.status !== "succeeded")
+      throw new NotReady("payment_not_succeeded");
+    const charge = payment.latest_charge;
+    if (!charge || typeof charge === "string")
+      throw new NotReady("charge_unavailable");
+    if (id(charge.payment_intent) !== payment.id)
+      throw new Error("Charge does not belong to the payment.");
+    const currency = payment.currency;
+    if (charge.currency !== currency) throw new NotReady("currency_mismatch");
+    const transactions = new Map<string, ProcessingCostTransaction>();
+    async function add(
+      value: Stripe.BalanceTransaction | string | null,
+      sourceId: string,
+      sourceType: ProcessingCostTransaction["sourceType"],
+      missing: ProcessingCostNotReadyReason,
+    ) {
+      if (!value) throw new NotReady(missing);
+      const tx =
+        typeof value === "string"
+          ? await stripe.balanceTransactions.retrieve(value, {}, requestOptions)
+          : value;
+      if (tx.currency !== currency) throw new NotReady("currency_mismatch");
+      [tx.amount, tx.fee, tx.net].forEach(integer);
+      if (integer(tx.amount - tx.fee) !== tx.net)
+        throw new Error("Provider balance transaction does not reconcile.");
+      const existing = transactions.get(tx.id);
+      if (
+        existing &&
+        (existing.sourceId !== sourceId || existing.sourceType !== sourceType)
+      )
+        throw new Error(
+          "Balance transaction belongs to multiple cost sources.",
+        );
+      const feeDetails =
+        tx.fee_details?.map((detail) => {
+          if (detail.currency !== currency)
+            throw new NotReady("currency_mismatch");
+          return {
+            type: detail.type,
+            amount: integer(detail.amount),
+            currency: detail.currency,
+            application: detail.application,
+            description: detail.description,
+          };
+        }) ?? null;
+      transactions.set(tx.id, {
+        id: tx.id,
+        sourceId,
+        sourceType,
+        currency,
+        amount: tx.amount,
+        fee: tx.fee,
+        net: tx.net,
+        created: integer(tx.created * 1000),
+        feeDetails,
+      });
+      return tx.id;
+    }
+    const chargeTransactionId = await add(
+      charge.balance_transaction,
+      charge.id,
+      "charge",
+      "charge_transaction_unavailable",
+    );
+    const original = transactions.get(chargeTransactionId)!;
+    const gross = integer(payment.amount_received);
+    if (gross < 0 || original.amount !== gross)
+      throw new Error("Payment and processed charge amounts do not reconcile.");
+    const refunds = new Map<string, ProcessingCostRecord>();
+    for await (const refund of stripe.refunds.list(
+      {
+        payment_intent: payment.id,
+        limit: 100,
+        expand: [
+          "data.balance_transaction",
+          "data.failure_balance_transaction",
+        ],
+      },
+      requestOptions,
+    )) {
+      if (
+        id(refund.charge) !== charge.id ||
+        (refund.payment_intent && id(refund.payment_intent) !== payment.id)
+      )
+        throw new Error("Refund does not belong to the payment charge.");
+      if (refund.currency !== currency) throw new NotReady("currency_mismatch");
+      if (!["succeeded", "failed", "canceled"].includes(refund.status ?? ""))
+        throw new NotReady("refund_pending");
+      const amount = integer(refund.amount);
+      if (amount < 0) throw new Error("Refund amount must be nonnegative.");
+      const ids: string[] = [];
+      if (refund.balance_transaction || refund.status === "succeeded")
+        ids.push(
+          await add(
+            refund.balance_transaction,
+            refund.id,
+            "refund",
+            "refund_transaction_unavailable",
+          ),
+        );
+      if (
+        refund.failure_balance_transaction ||
+        (refund.status === "failed" && refund.balance_transaction)
+      )
+        ids.push(
+          await add(
+            refund.failure_balance_transaction ?? null,
+            refund.id,
+            "refund_failure",
+            "refund_failure_transaction_unavailable",
+          ),
+        );
+      refunds.set(refund.id, {
+        id: refund.id,
+        status: refund.status!,
+        amount,
+        balanceTransactionIds: [...new Set(ids)],
+      });
+    }
+    const disputes = new Map<string, ProcessingCostRecord>();
+    for await (const dispute of stripe.disputes.list(
+      { payment_intent: payment.id, limit: 100 },
+      requestOptions,
+    )) {
+      if (
+        id(dispute.charge) !== charge.id ||
+        (dispute.payment_intent && id(dispute.payment_intent) !== payment.id)
+      )
+        throw new Error("Dispute does not belong to the payment charge.");
+      if (dispute.currency !== currency)
+        throw new NotReady("currency_mismatch");
+      if (
+        !dispute.balance_transactions.length &&
+        !dispute.status.startsWith("warning_")
+      )
+        throw new NotReady("dispute_transactions_unavailable");
+      const amount = integer(dispute.amount);
+      if (amount < 0) throw new Error("Dispute amount must be nonnegative.");
+      const ids: string[] = [];
+      for (const tx of dispute.balance_transactions)
+        ids.push(
+          await add(
+            tx,
+            dispute.id,
+            "dispute",
+            "dispute_transactions_unavailable",
+          ),
+        );
+      if (
+        dispute.status === "won" &&
+        sum([...new Set(ids)].map((txId) => transactions.get(txId)!.amount)) < 0
+      )
+        throw new NotReady("dispute_reinstatement_unavailable");
+      disputes.set(dispute.id, {
+        id: dispute.id,
+        status: dispute.status,
+        amount,
+        balanceTransactionIds: [...new Set(ids)],
+      });
+    }
+    const all = [...transactions.values()];
+    const refundFeeAdjustment = sum(
+      all
+        .filter(
+          (tx) =>
+            tx.sourceType === "refund" || tx.sourceType === "refund_failure",
+        )
+        .map((tx) => tx.fee),
+    );
+    const disputeFeeAdjustment = sum(
+      all.filter((tx) => tx.sourceType === "dispute").map((tx) => tx.fee),
+    );
+    const refundedPrincipal = sum(
+      [...refunds.values()]
+        .filter((refund) => refund.status === "succeeded")
+        .map((refund) => refund.amount),
+    );
+    const disputedPrincipal = sum(
+      [...disputes.values()].map((dispute) =>
+        Math.max(
+          0,
+          -sum(
+            dispute.balanceTransactionIds.map(
+              (txId) => transactions.get(txId)!.amount,
+            ),
+          ),
+        ),
+      ),
+    );
+    return {
+      status: "ready",
+      paymentIntentId: payment.id,
+      chargeId: charge.id,
+      currency,
+      gross,
+      metadata: payment.metadata,
+      processingFee: original.fee,
+      refundFeeAdjustment,
+      disputeFeeAdjustment,
+      netFees: sum([original.fee, refundFeeAdjustment, disputeFeeAdjustment]),
+      refundedPrincipal,
+      disputedPrincipal,
+      principalReturned: Math.min(
+        gross,
+        sum([refundedPrincipal, disputedPrincipal]),
+      ),
+      refunds: [...refunds.values()],
+      disputes: [...disputes.values()],
+      transactions: all,
+    };
+  } catch (error) {
+    if (error instanceof NotReady)
+      return {
+        status: "not_ready",
+        paymentIntentId: opts.paymentIntentId,
+        reason: error.reason,
+      };
+    throw error;
+  }
+}