@fantastic.dev/better-stripe 0.25.0 → 0.25.1

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

@@ -0,0 +1,168 @@
+// @vitest-environment edge-runtime
+import { afterEach, expect, it, vi } from "vitest";
+import {
+  payoutFixture,
+  observationRef,
+} from "./payoutReconciliationTestHelpers.js";
+afterEach(() => vi.restoreAllMocks());
+it("uses current provider state instead of a signed older pending body and deduplicates replay", async () => {
+  const f = payoutFixture();
+  const observed: string[] = [];
+  const config = {
+    onEvent: async () => {
+      observed.push((await f.row())!.status);
+    },
+  };
+  expect((await f.deliver(config)).status).toBe(200);
+  expect(await f.row()).toMatchObject({
+    status: "paid",
+    accountId: "acct_recipient",
+  });
+  expect(observed).toEqual(["paid"]);
+  expect(f.retrieve).toHaveBeenCalledWith(
+    "po_current",
+    {},
+    { stripeAccount: "acct_recipient" },
+  );
+  expect(await f.deliver(config)).toMatchObject({
+    status: 200,
+    body: { deduplicated: true },
+  });
+  expect(f.retrieve).toHaveBeenCalledTimes(1);
+  expect(observed).toEqual(["paid"]);
+});
+it("holds unavailable provider state without applying the signed body or calling application hooks", async () => {
+  const f = payoutFixture();
+  const onEvent = vi.fn();
+  f.retrieve.mockRejectedValueOnce(new Error("Provider unavailable"));
+  expect((await f.deliver({ onEvent })).status).toBe(500);
+  expect(await f.row()).toBeNull();
+  expect(onEvent).not.toHaveBeenCalled();
+  expect(await f.ledger()).toMatchObject({ status: "failed" });
+  expect((await f.deliver({ onEvent })).status).toBe(200);
+  expect(await f.row()).toMatchObject({ status: "paid" });
+});
+
+it("commits synchronized callbacks with the accepted generation and rolls back callback failures", async () => {
+  let canCommit = false;
+  const f = payoutFixture({
+    payout: {
+      onCreate: async (ctx, doc) => {
+        await ctx.runMutation(observationRef, { status: doc.status });
+        if (!canCommit) throw new Error("Callback failed");
+      },
+      onUpdate: async (ctx, doc, old) => {
+        await ctx.runMutation(observationRef, {
+          status: doc.status,
+          oldStatus: old.status,
+        });
+      },
+    },
+  });
+  expect((await f.deliver()).status).toBe(500);
+  expect(await f.row()).toBeNull();
+  expect(
+    await f.t.run((ctx) => ctx.db.query("observations").collect()),
+  ).toEqual([]);
+  canCommit = true;
+  expect((await f.deliver()).status).toBe(200);
+  expect(await f.row()).toMatchObject({ status: "paid" });
+  expect(
+    await f.t.run((ctx) => ctx.db.query("observations").collect()),
+  ).toHaveLength(1);
+  f.event.id = "evt_same_current";
+  expect((await f.deliver()).status).toBe(200);
+  expect(
+    await f.t.run((ctx) => ctx.db.query("observations").collect()),
+  ).toHaveLength(1);
+  f.set({
+    status: "failed",
+    failure_code: "account_closed",
+    failure_message: "Closed",
+  });
+  f.event.id = "evt_later_failure";
+  expect((await f.deliver()).status).toBe(200);
+  expect(await f.row()).toMatchObject({
+    status: "failed",
+    failureCode: "account_closed",
+  });
+  expect(
+    await f.t.run((ctx) => ctx.db.query("observations").collect()),
+  ).toMatchObject([
+    { status: "paid" },
+    { status: "failed", oldStatus: "paid" },
+  ]);
+});
+
+it("prevents a delayed old provider response from repeating or regressing a synchronized callback", async () => {
+  const f = payoutFixture({
+    payout: {
+      onCreate: async (ctx, doc) => {
+        await ctx.runMutation(observationRef, { status: doc.status });
+      },
+      onUpdate: async (ctx, doc, old) => {
+        await ctx.runMutation(observationRef, {
+          status: doc.status,
+          oldStatus: old.status,
+        });
+      },
+    },
+  });
+  let resolve!: (value: ReturnType<typeof f.current>) => void;
+  const response = new Promise<ReturnType<typeof f.current>>((done) => {
+    resolve = done;
+  });
+  f.retrieve.mockImplementationOnce(async () => (await response) as never);
+  const old = { ...f.current(), status: "pending" as const };
+  const first = f.deliver();
+  await vi.waitFor(() => expect(f.retrieve).toHaveBeenCalledTimes(1));
+  f.event.id = "evt_concurrent_newer";
+  expect((await f.deliver()).status).toBe(200);
+  resolve(old);
+  expect((await first).status).toBe(200);
+  expect(await f.row()).toMatchObject({ status: "paid" });
+  expect(
+    await f.t.run((ctx) => ctx.db.query("observations").collect()),
+  ).toMatchObject([{ status: "paid" }]);
+});
+it("preserves an accepted row when a later provider read fails", async () => {
+  const f = payoutFixture();
+  await f.deliver();
+  const original = await f.row();
+  f.event.id = "evt_provider_unavailable_later";
+  f.retrieve.mockRejectedValueOnce(new Error("Provider unavailable"));
+  expect((await f.deliver()).status).toBe(500);
+  expect(await f.row()).toEqual(original);
+  expect((await f.deliver()).status).toBe(200);
+  expect(await f.row()).toEqual(original);
+});
+it("uses explicit platform scope without adopting metadata or bank account IDs", async () => {
+  const f = payoutFixture();
+  f.event.account = undefined;
+  expect((await f.deliver()).status).toBe(200);
+  expect(await f.row()).toMatchObject({
+    accountId: "platform",
+    status: "paid",
+  });
+  expect(f.retrieve).toHaveBeenCalledWith("po_current", {}, {});
+});
+it("rejects a foreign signed account for an existing payout before any provider read or callback", async () => {
+  const f = payoutFixture();
+  await f.deliver();
+  const original = await f.row();
+  f.event.id = "evt_foreign_account";
+  f.event.account = "acct_foreign";
+  const onEvent = vi.fn();
+  expect((await f.deliver({ onEvent })).status).toBe(500);
+  expect(await f.row()).toEqual(original);
+  expect(f.retrieve).toHaveBeenCalledTimes(1);
+  expect(onEvent).not.toHaveBeenCalled();
+});
+it("rejects a provider response for a different payout without adopting it", async () => {
+  const f = payoutFixture();
+  f.set({ id: "po_foreign" });
+  const onEvent = vi.fn();
+  expect((await f.deliver({ onEvent })).status).toBe(500);
+  expect(await f.row()).toBeNull();
+  expect(onEvent).not.toHaveBeenCalled();
+});

package/src/client/webhooks/payoutReconciliation.ts

@@ -0,0 +1,72 @@
+import type Stripe from "stripe";
+import type { Component } from "../helpers.js";
+import type {
+  SyncTriggerCtx,
+  SyncTriggers,
+  StripeComponentPayout,
+} from "../types.js";
+import {
+  preparePayoutSync,
+  type PayoutSyncResult,
+  type PreparedPayoutSync,
+} from "../connect/payoutSync.js";
+import {
+  componentRef,
+  dispatchUpsert,
+  type WebhookContext,
+} from "./helpers.js";
+
+export async function handlePayoutEvent(
+  whCtx: WebhookContext,
+  payout: Stripe.Payout,
+  accountId?: string,
+) {
+  const prepared = await preparePayoutSync(
+    whCtx.stripe,
+    whCtx.component,
+    whCtx.ctx,
+    {
+      stripePayoutId: payout.id,
+      scope:
+        accountId === undefined
+          ? { type: "platform" }
+          : { type: "connected", accountId },
+    },
+  );
+  try {
+    await dispatchUpsert(whCtx, "payoutReconciled", prepared);
+  } catch (error) {
+    await whCtx.ctx.runMutation(
+      componentRef(whCtx.component, "payoutSync/mutations/markUnknown"),
+      {
+        stripePayoutId: prepared.stripePayoutId,
+        accountId: prepared.accountId,
+        generation: prepared.generation,
+      },
+    );
+    throw error;
+  }
+}
+
+/** The host mutation commits the generation and application callback together. */
+export async function reconcilePayoutAndTrigger(
+  component: Component,
+  ctx: SyncTriggerCtx,
+  record: Record<string, unknown>,
+  triggers: SyncTriggers["payout"],
+) {
+  const prepared = record as PreparedPayoutSync;
+  const old = triggers
+    ? ((await ctx.runQuery(
+        componentRef(component, "connect/queries/getPayoutByStripeId"),
+        { stripePayoutId: prepared.stripePayoutId },
+      )) as StripeComponentPayout | null)
+    : null;
+  const result = (await ctx.runMutation(
+    componentRef(component, "payoutSync/mutations/finish"),
+    prepared,
+  )) as PayoutSyncResult;
+  if (result.status !== "accepted" || !result.changed) return;
+  if (old) await triggers?.onUpdate?.(ctx, result.payout, old);
+  else await triggers?.onCreate?.(ctx, result.payout);
+}

package/src/client/webhooks/payoutReconciliationTestHelpers.ts

@@ -0,0 +1,135 @@
+// @vitest-environment edge-runtime
+import Stripe from "stripe";
+import { vi } from "vitest";
+import schema from "../../component/schema.js";
+import { convexTest } from "convex-test";
+import {
+  defineSchema,
+  defineTable,
+  makeFunctionReference,
+  internalMutationGeneric,
+} from "convex/server";
+import { v } from "convex/values";
+import { BetterStripe } from "../index.js";
+import { components } from "../setup.test.js";
+import { getStripeClient } from "../helpers.js";
+import type {
+  SyncTriggers,
+  RegisterRoutesConfig,
+  WebhookHandlerRefs,
+} from "../types.js";
+import { handleWebhookRequest } from "./handler.js";
+export const observationRef = makeFunctionReference<
+  "mutation",
+  { status: string; oldStatus?: string },
+  null
+>("payoutHost:recordObservation");
+const modules = import.meta.glob("../../component/**/*.{ts,js,tsx,jsx}");
+const key = "sk_test_signed_authoritative_payout";
+const secret = "whsec_signed_authoritative_payout";
+export function payoutFixture(triggers?: SyncTriggers) {
+  const handlers = new BetterStripe(components.betterStripe, {
+    triggers,
+  }).webhookHandlers();
+  const t = convexTest(
+    defineSchema({
+      observations: defineTable({
+        status: v.string(),
+        oldStatus: v.optional(v.string()),
+      }),
+    }),
+    {
+      "./_generated/server.ts": () =>
+        import("../../component/_generated/server.js"),
+      "./payoutHost.ts": async () => ({
+        ...handlers,
+        recordObservation: internalMutationGeneric({
+          args: { status: v.string(), oldStatus: v.optional(v.string()) },
+          returns: v.null(),
+          handler: async (ctx, args) => {
+            await ctx.db.insert("observations", args);
+            return null;
+          },
+        }),
+      }),
+    },
+  );
+  t.registerComponent("betterStripe", schema, modules);
+  const webhooks: WebhookHandlerRefs | undefined = triggers
+    ? {
+        syncWebhook: makeFunctionReference<"mutation">(
+          "payoutHost:syncWebhook",
+        ) as unknown as WebhookHandlerRefs["syncWebhook"],
+        asyncWebhook: makeFunctionReference<"action">(
+          "payoutHost:asyncWebhook",
+        ) as unknown as WebhookHandlerRefs["asyncWebhook"],
+      }
+    : undefined;
+  let current = {
+    id: "po_current",
+    object: "payout",
+    amount: 1200,
+    currency: "usd",
+    status: "paid",
+    arrival_date: 1792108800,
+    automatic: true,
+    method: "standard",
+    failure_code: null,
+    failure_message: null,
+    metadata: { accountId: "acct_untrusted" },
+  } as unknown as Stripe.Payout;
+  const retrieve = vi
+    .spyOn(getStripeClient(key).payouts, "retrieve")
+    .mockImplementation(
+      async () => ({ ...current }) as Stripe.Response<Stripe.Payout>,
+    );
+  const event = {
+    id: "evt_payout_first",
+    object: "event",
+    type: "payout.updated",
+    created: 1792010000,
+    livemode: false,
+    account: "acct_recipient" as string | undefined,
+    data: { object: { ...current, status: "pending" } },
+  };
+  const row = () =>
+    t.query(components.betterStripe.connect.queries.getPayoutByStripeId, {
+      stripePayoutId: "po_current",
+    });
+  const ledger = () =>
+    t.query(components.betterStripe.webhooks.queries.getWebhookEvent, {
+      stripeEventId: event.id,
+    });
+  const deliver = async (config: RegisterRoutesConfig = {}) => {
+    const body = JSON.stringify(event);
+    const signature = await Stripe.webhooks.generateTestHeaderStringAsync({
+      payload: body,
+      secret,
+    });
+    return t.action(async (ctx) => {
+      const response = await handleWebhookRequest(
+        ctx,
+        new Request("https://example.test/stripe/webhook", {
+          method: "POST",
+          body,
+          headers: { "stripe-signature": signature },
+        }),
+        components.betterStripe,
+        { stripeSecretKey: key, webhookSecret: secret, webhooks, ...config },
+      );
+      return { status: response.status, body: await response.json() };
+    });
+  };
+  return {
+    t,
+    event,
+    deliver,
+    row,
+    ledger,
+    retrieve,
+    current: () => ({ ...current }),
+    set: (patch: Partial<Stripe.Payout>) => {
+      current = { ...current, ...patch };
+    },
+  };
+}

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

@@ -96,6 +96,7 @@ type MockReversal = {
 
 function makeStripe() {
   return {
+    payouts: { retrieve: vi.fn() },
     refunds: {
       list: vi.fn(() =>
         (async function* () {
@@ -791,63 +792,77 @@ describe("processEvent — payments (status collapse)", () => {
 });
 
 describe("processEvent — payouts", () => {
-  it("scopes connected payouts to the event account instead of the external bank", async () => {
+  function context(id: string, status = "paid") {
     const whCtx = makeWhCtx();
-    const payoutEvent = event("payout.paid", {
-      id: "po_connected",
-      destination: "ba_bank",
+    whCtx.ctx.runMutation.mockResolvedValue(1 as never);
+    whCtx.stripe.payouts.retrieve.mockResolvedValue({
+      id,
       amount: 5000,
       currency: "usd",
-      status: "paid",
+      status,
       arrival_date: 1700000000,
-      metadata: {},
+      automatic: true,
+      method: "standard",
+      metadata: { accountId: "acct_untrusted" },
+    });
+    return whCtx;
+  }
+  it("scopes connected provider reads to the signed event account", async () => {
+    const whCtx = context("po_connected");
+    const payoutEvent = event("payout.paid", {
+      id: "po_connected",
+      destination: "ba_bank",
+      metadata: { accountId: "acct_untrusted" },
     });
     payoutEvent.account = "acct_store";
     await processEvent(whCtx, payoutEvent);
-    expect(dispatchedPayload(whCtx.ctx).data.accountId).toBe("acct_store");
+    expect(whCtx.stripe.payouts.retrieve).toHaveBeenCalledWith(
+      "po_connected",
+      {},
+      { stripeAccount: "acct_store" },
+    );
+    expect(dispatchedPayload(whCtx.ctx, 1).data).toMatchObject({
+      accountId: "acct_store",
+      generation: 1,
+      payout: { status: "paid", accountId: "acct_store" },
+    });
   });
-
-  it("normalizes a payout, taking destination as a string id", async () => {
-    const whCtx = makeWhCtx();
+  it("uses explicit platform scope instead of a bank destination or metadata account", async () => {
+    const whCtx = context("po_1");
     await processEvent(
       whCtx,
       event("payout.paid", {
         id: "po_1",
         destination: "ba_123",
-        amount: 5000,
-        currency: "usd",
-        status: "paid",
-        arrival_date: 1700000000,
-        method: "standard",
-        metadata: {},
+        status: "pending",
+        metadata: { accountId: "acct_forged" },
       }),
     );
-    const { path, data } = dispatchedPayload(whCtx.ctx);
-    expect(path).toBe("betterStripe/connect/mutations/upsertPayout");
+    const { path, data } = dispatchedPayload(whCtx.ctx, 1);
+    expect(path).toBe("betterStripe/payoutSync/mutations/finish");
     expect(data).toMatchObject({
       stripePayoutId: "po_1",
-      accountId: "ba_123",
-      amount: 5000,
-      status: "paid",
-      method: "standard",
+      accountId: "platform",
+      generation: 1,
+      payout: { status: "paid", amount: 5000, accountId: "platform" },
     });
+    expect(whCtx.stripe.payouts.retrieve).toHaveBeenCalledWith("po_1", {}, {});
   });
-
-  it("falls back to an empty-string accountId for an expanded destination without id", async () => {
-    const whCtx = makeWhCtx();
+  it("ignores malformed stale event fields when the current platform payout is valid", async () => {
+    const whCtx = context("po_2", "failed");
     await processEvent(
       whCtx,
       event("payout.failed", {
         id: "po_2",
         destination: {},
-        amount: 100,
-        currency: "usd",
-        status: "failed",
         arrival_date: null,
         metadata: {},
       }),
     );
-    expect(dispatchedPayload(whCtx.ctx).data.accountId).toBe("");
+    expect(dispatchedPayload(whCtx.ctx, 1).data).toMatchObject({
+      accountId: "platform",
+      payout: { status: "failed", arrivalDate: "2023-11-14T22:13:20.000Z" },
+    });
   });
 });
 

package/src/client/webhooks/processors.ts

@@ -1,3 +1,4 @@
+import { handlePayoutEvent } from "./payoutReconciliation.js";
 import { reconcileDisputeMoney } from "./disputeRecovery.js";
 import { successfulRefundPrincipal } from "../connect/refundPrincipal.js";
 import { subscriptionRouting } from "../billing/subscriptionRouting.js";
@@ -900,33 +901,6 @@ async function upsertPaymentFromStripe(
   });
 }
 
-async function handlePayoutEvent(
-  whCtx: WebhookContext,
-  payout: Stripe.Payout,
-  connectedAccountId?: string,
-): Promise<void> {
-  await dispatchUpsert(whCtx, "payoutUpserted", {
-    stripePayoutId: payout.id,
-    accountId:
-      connectedAccountId ??
-      (payout.metadata?.accountId?.startsWith("acct_")
-        ? payout.metadata.accountId
-        : undefined) ??
-      (typeof payout.destination === "string"
-        ? payout.destination
-        : (payout.destination?.id ?? "")),
-    amount: payout.amount,
-    currency: payout.currency,
-    status: payout.status as
-      "pending" | "paid" | "failed" | "canceled" | "in_transit",
-    arrivalDate: epochToIso(payout.arrival_date),
-    method: payout.method ?? undefined,
-    failureCode: payout.failure_code ?? undefined,
-    failureMessage: payout.failure_message ?? undefined,
-    metadata: payout.metadata ?? undefined,
-  });
-}
-
 // Stripe types Refund.status as `string | null`; clamp to the documented union.
 const REFUND_STATUSES = new Set([
   "pending",