@fantastic.dev/better-stripe 0.24.0 → 0.25.1

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

package/src/component/_generated/api.ts

@@ -27,6 +27,7 @@ import type * as connect_reversalReceipts from "../connect/reversalReceipts.js";
 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_resetSafety from "../core/resetSafety.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";
@@ -56,10 +57,17 @@ import type * as payoutRelease_helpers from "../payoutRelease/helpers.js";
 import type * as payoutRelease_mutations from "../payoutRelease/mutations.js";
 import type * as payoutRelease_observation from "../payoutRelease/observation.js";
 import type * as payoutRelease_queries from "../payoutRelease/queries.js";
+import type * as payoutSnapshots_localState from "../payoutSnapshots/localState.js";
+import type * as payoutSnapshots_mutations from "../payoutSnapshots/mutations.js";
+import type * as payoutSnapshots_revisions from "../payoutSnapshots/revisions.js";
+import type * as payoutSnapshots_scope from "../payoutSnapshots/scope.js";
 import type * as payoutSync_helpers from "../payoutSync/helpers.js";
 import type * as payoutSync_mutations from "../payoutSync/mutations.js";
 import type * as payoutSync_queries from "../payoutSync/queries.js";
 import type * as payoutSync_validators from "../payoutSync/validators.js";
+import type * as payoutWorker_helpers from "../payoutWorker/helpers.js";
+import type * as payoutWorker_mutations from "../payoutWorker/mutations.js";
+import type * as payoutWorker_queries from "../payoutWorker/queries.js";
 import type * as products_mutations from "../products/mutations.js";
 import type * as products_queries from "../products/queries.js";
 import type * as products_validators from "../products/validators.js";
@@ -99,6 +107,7 @@ const fullApi: ApiFromModules<{
   "connect/validators": typeof connect_validators;
   "core/mutations": typeof core_mutations;
   "core/queries": typeof core_queries;
+  "core/resetSafety": typeof core_resetSafety;
   "core/validators": typeof core_validators;
   "costRecovery/claims": typeof costRecovery_claims;
   "costRecovery/completion": typeof costRecovery_completion;
@@ -128,10 +137,17 @@ const fullApi: ApiFromModules<{
   "payoutRelease/mutations": typeof payoutRelease_mutations;
   "payoutRelease/observation": typeof payoutRelease_observation;
   "payoutRelease/queries": typeof payoutRelease_queries;
+  "payoutSnapshots/localState": typeof payoutSnapshots_localState;
+  "payoutSnapshots/mutations": typeof payoutSnapshots_mutations;
+  "payoutSnapshots/revisions": typeof payoutSnapshots_revisions;
+  "payoutSnapshots/scope": typeof payoutSnapshots_scope;
   "payoutSync/helpers": typeof payoutSync_helpers;
   "payoutSync/mutations": typeof payoutSync_mutations;
   "payoutSync/queries": typeof payoutSync_queries;
   "payoutSync/validators": typeof payoutSync_validators;
+  "payoutWorker/helpers": typeof payoutWorker_helpers;
+  "payoutWorker/mutations": typeof payoutWorker_mutations;
+  "payoutWorker/queries": typeof payoutWorker_queries;
   "products/mutations": typeof products_mutations;
   "products/queries": typeof products_queries;
   "products/validators": typeof products_validators;