@fantastic.dev/better-stripe 0.11.0 → 0.12.0

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;
+  }
+}

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

@@ -0,0 +1,135 @@
+import type Stripe from "stripe";
+import { componentsGeneric } from "convex/server";
+import { expect, it, vi } from "vitest";
+import { BetterStripe } from "../index.js";
+import { getStripeClient, type Component, type RunCtx } from "../helpers.js";
+
+it.each([undefined, "2026-09-30.preview"] as const)(
+  "paginates using the configured version and connected namespace: %s",
+  async (version) => {
+    const key = `sk_test_cost_transport_${crypto.randomUUID()}`;
+    const bs = new BetterStripe(
+      componentsGeneric().betterStripe as unknown as Component,
+      {
+        STRIPE_SECRET_KEY: key,
+        stripeApiVersion: version,
+      },
+    );
+    const calls: {
+      path: string;
+      version: string;
+      account: string;
+      method: string;
+    }[] = [];
+    const sdk = getStripeClient(key, version);
+    const tx = (id: string, amount: number, fee = 0) => ({
+      id,
+      amount,
+      fee,
+      net: amount - fee,
+      currency: "usd",
+      created: 1800000000,
+    });
+    const refund = (id: string) => ({
+      id,
+      amount: 100,
+      status: "succeeded",
+      currency: "usd",
+      charge: "ch_test",
+      payment_intent: "pi_test",
+      balance_transaction: tx(`txn_${id}`, -100),
+    });
+    (
+      sdk as unknown as { _setApiField: (key: string, value: unknown) => void }
+    )._setApiField("httpClient", {
+      getClientName: () => "cost-context-contract",
+      makeRequest: async (
+        ...[, , path, method, headers]: Parameters<
+          ReturnType<typeof Stripe.createNodeHttpClient>["makeRequest"]
+        >
+      ) => {
+        calls.push({
+          path,
+          method,
+          version: String(headers["Stripe-Version"]),
+          account: String(headers["Stripe-Account"]),
+        });
+        const next = path.includes("starting_after");
+        const data = path.includes("/payment_intents/")
+          ? {
+              id: "pi_test",
+              status: "succeeded",
+              currency: "usd",
+              amount_received: 10000,
+              metadata: {},
+              latest_charge: {
+                id: "ch_test",
+                payment_intent: "pi_test",
+                currency: "usd",
+                balance_transaction: tx("txn_charge", 10000, 320),
+              },
+            }
+          : path.includes("/refunds")
+            ? {
+                object: "list",
+                url: "/v1/refunds",
+                has_more: !next,
+                data: [refund(next ? "re_second" : "re_first")],
+              }
+            : {
+                object: "list",
+                url: "/v1/disputes",
+                has_more: !next,
+                data: [
+                  {
+                    id: next ? "dp_second" : "dp_first",
+                    status: "warning_closed",
+                    amount: 100,
+                    currency: "usd",
+                    charge: "ch_test",
+                    payment_intent: "pi_test",
+                    balance_transactions: [],
+                  },
+                ],
+              };
+        return {
+          getStatusCode: () => 200,
+          getHeaders: () => ({}),
+          getRawResponse: () => ({}),
+          toJSON: async () => data,
+          toStream: () => {
+            throw new Error("Unexpected stream");
+          },
+        };
+      },
+    });
+    const ctx = {
+      runQuery: vi.fn(),
+      runMutation: vi.fn(),
+    } as unknown as RunCtx;
+    expect(
+      await bs.getProcessingCostContext(ctx, {
+        paymentIntentId: "pi_test",
+        stripeAccountId: "acct_connected",
+      }),
+    ).toMatchObject({
+      status: "ready",
+      refundedPrincipal: 200,
+      refunds: [{ id: "re_first" }, { id: "re_second" }],
+      disputes: [{ id: "dp_first" }, { id: "dp_second" }],
+    });
+    expect(calls).toHaveLength(5);
+    expect(
+      calls.every(
+        (call) =>
+          call.method === "GET" &&
+          call.version === (version ?? "2026-09-30.endive") &&
+          call.account === "acct_connected",
+      ),
+    ).toBe(true);
+    expect(
+      calls.filter((call) => call.path.includes("starting_after")),
+    ).toHaveLength(2);
+    expect(ctx.runMutation).not.toHaveBeenCalled();
+  },
+);

package/src/client/utils/webhookEndpoints.test.ts

@@ -51,6 +51,11 @@ const asStripe = (s: ReturnType<typeof makeStripe>) =>
 const ctx = {} as RunCtx;
 
 describe("event constant exports", () => {
+  it("selects dedicated payout cancellations by default", () => {
+    expect(BETTER_STRIPE_WEBHOOK_EVENTS).toContain("payout.canceled");
+    expect(ALL_BETTER_STRIPE_EVENTS).toContain("payout.canceled");
+  });
+
   it("ALL_BETTER_STRIPE_EVENTS is the concatenation of V1 then V2 events", () => {
     expect(ALL_BETTER_STRIPE_EVENTS).toEqual([
       ...BETTER_STRIPE_WEBHOOK_EVENTS,

package/src/client/utils/webhookEndpoints.ts

@@ -39,6 +39,7 @@ export const BETTER_STRIPE_WEBHOOK_EVENTS = [
   "payout.updated",
   "payout.paid",
   "payout.failed",
+  "payout.canceled",
   // Refunds
   "refund.created",
   "refund.updated",

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

@@ -108,3 +108,12 @@ describe("scheduleAsyncHook — invoice.payment_failed (BTS-33)", () => {
     );
   });
 });
+
+describe("scheduleAsyncHook — payout cancellation", () => {
+  it("does not schedule the paid convenience hook for cancellation", async () => {
+    const whCtx = makeWhCtx({ doc: { status: "canceled" } });
+    await scheduleAsyncHook(whCtx, "payout.canceled", "po_canceled");
+    expect(whCtx.ctx.runQuery).not.toHaveBeenCalled();
+    expect(whCtx.ctx.scheduler?.runAfter).not.toHaveBeenCalled();
+  });
+});

package/src/client/webhooks/payout-canceled.integration.test.ts

@@ -0,0 +1,192 @@
+// @vitest-environment edge-runtime
+import Stripe from "stripe";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+import schema from "../../component/schema.js";
+import { getStripeClient } from "../helpers.js";
+import { components, initConvexTest } from "../setup.test.js";
+import type { RegisterRoutesConfig, StripeWebhookEvent } from "../types.js";
+import { handleWebhookRequest } from "./handler.js";
+
+const modules = import.meta.glob("../../component/**/*.{ts,js,tsx,jsx}");
+const key = "sk_test_payout_cancellation_regression";
+const signingSecret = "whsec_payout_cancellation_regression";
+const payoutRef = components.betterStripe.connect.queries.getPayoutByStripeId;
+const ledgerRef = components.betterStripe.webhooks.queries.getWebhookEvent;
+const transport = vi.fn(async () => {
+  throw new Error("Unexpected provider request in payout regression");
+});
+beforeEach(() => {
+  transport.mockClear();
+  vi.spyOn(
+    getStripeClient(key).getApiField("httpClient"),
+    "makeRequest",
+  ).mockImplementation(transport);
+});
+afterEach(() => vi.restoreAllMocks());
+
+type PayoutEvent = Extract<
+  StripeWebhookEvent,
+  {
+    type:
+      | "payout.created"
+      | "payout.updated"
+      | "payout.paid"
+      | "payout.failed"
+      | "payout.canceled";
+  }
+>;
+
+function fixture(
+  type: PayoutEvent["type"] = "payout.created",
+  status: PayoutEvent["data"]["object"]["status"] = "pending",
+) {
+  const t = initConvexTest();
+  t.registerComponent("betterStripe", schema, modules);
+  const event: PayoutEvent = {
+    id: `evt_qa_${type.replace(".", "_")}`,
+    object: "event" as const,
+    api_version: null,
+    created: 1792010000,
+    pending_webhooks: 1,
+    request: null,
+    type,
+    account: "acct_qa_recipient",
+    livemode: false,
+    data: {
+      object: {
+        id: "po_qa_audit",
+        object: "payout" as const,
+        amount: 1200,
+        application_fee: null,
+        application_fee_amount: null,
+        automatic: true,
+        balance_transaction: null,
+        created: 1792010000,
+        description: null,
+        failure_balance_transaction: null,
+        failure_code: null,
+        failure_message: null,
+        livemode: false,
+        original_payout: null,
+        payout_method: null,
+        reconciliation_status: "not_applicable",
+        reversed_by: null,
+        source_type: "card",
+        statement_descriptor: null,
+        trace_id: null,
+        type: "bank_account",
+        currency: "usd",
+        status,
+        arrival_date: 1792108800,
+        method: "standard",
+        destination: "ba_qa_destination",
+        metadata: { accountId: "acct_untrusted_metadata" },
+      },
+    },
+  };
+  const payout = () => t.query(payoutRef, { stripePayoutId: "po_qa_audit" });
+  const deliver = async (config: RegisterRoutesConfig = {}, tamper = false) => {
+    const body = JSON.stringify(event);
+    const signature = await Stripe.webhooks.generateTestHeaderStringAsync({
+      payload: body,
+      secret: signingSecret,
+    });
+    return t.action(async (ctx) => {
+      const response = await handleWebhookRequest(
+        ctx,
+        new Request("https://example.test/stripe/webhook", {
+          method: "POST",
+          body: tamper ? body.replace("po_qa_audit", "po_tampered") : body,
+          headers: { "stripe-signature": signature },
+        }),
+        components.betterStripe,
+        { stripeSecretKey: key, webhookSecret: signingSecret, ...config },
+      );
+      return { status: response.status, body: await response.json() };
+    });
+  };
+  return { t, event, payout, deliver };
+}
+
+it("reconciles signed cancellation before callbacks and deduplicates replay", async () => {
+  const f = fixture("payout.created", "pending");
+  expect((await f.deliver()).status).toBe(200);
+  const created = await f.payout();
+  expect(created?.status).toBe("pending");
+  f.event.id = "evt_canceled_regression";
+  f.event.type = "payout.canceled";
+  f.event.data.object.status = "canceled";
+  const observed: string[] = [];
+  const paid = vi.fn();
+  const config: RegisterRoutesConfig = {
+    onEvent: async (ctx) => {
+      const row = await ctx.runQuery(payoutRef, {
+        stripePayoutId: "po_qa_audit",
+      });
+      observed.push(`all:${row?.status}`);
+    },
+    events: {
+      "payout.canceled": async (ctx) => {
+        const row = await ctx.runQuery(payoutRef, {
+          stripePayoutId: "po_qa_audit",
+        });
+        observed.push(`canceled:${row?.status}`);
+      },
+      "payout.paid": paid,
+    },
+  };
+  expect((await f.deliver(config)).status).toBe(200);
+  const canceled = await f.payout();
+  expect(canceled).toMatchObject({
+    _id: created?._id,
+    stripePayoutId: "po_qa_audit",
+    accountId: "acct_qa_recipient",
+    amount: 1200,
+    currency: "usd",
+    status: "canceled",
+  });
+  expect(observed).toEqual(["all:canceled", "canceled:canceled"]);
+  expect(await f.deliver(config)).toMatchObject({
+    status: 200,
+    body: { deduplicated: true },
+  });
+  expect(await f.payout()).toEqual(canceled);
+  expect(observed).toEqual(["all:canceled", "canceled:canceled"]);
+  expect(paid).not.toHaveBeenCalled();
+  expect(
+    await f.t.query(ledgerRef, { stripeEventId: f.event.id }),
+  ).toMatchObject({ status: "processed" });
+  expect(transport).not.toHaveBeenCalled();
+});
+
+it("rejects a tampered cancellation before storage or callbacks", async () => {
+  const f = fixture("payout.canceled", "canceled");
+  const onEvent = vi.fn();
+  expect((await f.deliver({ onEvent }, true)).status).toBe(400);
+  expect(await f.payout()).toBeNull();
+  expect(await f.t.query(ledgerRef, { stripeEventId: f.event.id })).toBeNull();
+  expect(onEvent).not.toHaveBeenCalled();
+  expect(transport).not.toHaveBeenCalled();
+});
+
+it.each([
+  ["payout.created", "pending"],
+  ["payout.updated", "in_transit"],
+  ["payout.paid", "paid"],
+  ["payout.failed", "failed"],
+] as const)(
+  "preserves signed %s processing and replay",
+  async (type, status) => {
+    const f = fixture(type, status);
+    expect((await f.deliver()).status).toBe(200);
+    const first = await f.payout();
+    expect(first).toMatchObject({ accountId: "acct_qa_recipient", status });
+    expect(await f.deliver()).toMatchObject({
+      status: 200,
+      body: { deduplicated: true },
+    });
+    expect(await f.payout()).toEqual(first);
+    expect(transport).not.toHaveBeenCalled();
+  },
+);

package/src/client/webhooks/processors.ts

@@ -103,6 +103,7 @@ export async function processEvent(
     case "payout.updated":
     case "payout.paid":
     case "payout.failed":
+    case "payout.canceled":
       await handlePayoutEvent(whCtx, obj as Stripe.Payout, event.account);
       break;
     case "refund.created":