@fantastic.dev/better-stripe 0.10.2 → 0.12.0

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":

package/src/component/_generated/api.ts

@@ -17,6 +17,12 @@ import type * as connect_validators from "../connect/validators.js";
 import type * as core_mutations from "../core/mutations.js";
 import type * as core_queries from "../core/queries.js";
 import type * as core_validators from "../core/validators.js";
+import type * as costRecovery_claims from "../costRecovery/claims.js";
+import type * as costRecovery_completion from "../costRecovery/completion.js";
+import type * as costRecovery_helpers from "../costRecovery/helpers.js";
+import type * as costRecovery_mutations from "../costRecovery/mutations.js";
+import type * as costRecovery_queries from "../costRecovery/queries.js";
+import type * as costRecovery_reservations from "../costRecovery/reservations.js";
 import type * as lib_fees from "../lib/fees.js";
 import type * as lib_idempotency from "../lib/idempotency.js";
 import type * as lib_paymentSeller from "../lib/paymentSeller.js";
@@ -48,6 +54,12 @@ const fullApi: ApiFromModules<{
   "core/mutations": typeof core_mutations;
   "core/queries": typeof core_queries;
   "core/validators": typeof core_validators;
+  "costRecovery/claims": typeof costRecovery_claims;
+  "costRecovery/completion": typeof costRecovery_completion;
+  "costRecovery/helpers": typeof costRecovery_helpers;
+  "costRecovery/mutations": typeof costRecovery_mutations;
+  "costRecovery/queries": typeof costRecovery_queries;
+  "costRecovery/reservations": typeof costRecovery_reservations;
   "lib/fees": typeof lib_fees;
   "lib/idempotency": typeof lib_idempotency;
   "lib/paymentSeller": typeof lib_paymentSeller;