@fantastic.dev/better-stripe 0.25.0 → 0.26.0

package/src/client/connect/payoutQualification.ts

@@ -0,0 +1,145 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { Component, RunCtx } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import type {
+  claimDoc,
+  observation,
+} from "../../component/payoutRelease/schema.js";
+import type { transferDocValidator } from "../../component/connect/validators.js";
+import type { policyDoc } from "../../component/payoutPolicy/schema.js";
+import { transferFingerprint } from "../../component/payoutRelease/helpers.js";
+import {
+  getTransferFundingReceipt,
+  type TransferReceiptTransaction,
+} from "./transferReceipt.js";
+import { verifyPayoutHistory } from "./payoutHistory.js";
+import { reconcileRecipientPayout } from "./payoutReconciliation.js";
+type Held = { status: "held"; reason: string };
+type Snapshot =
+  | {
+      status: "ready";
+      transfers: Infer<typeof transferDocValidator>[];
+      claims: Infer<typeof claimDoc>[];
+    }
+  | Held;
+export type PayoutControlVerification = () => Promise<
+  { status: "verified"; policy: Infer<typeof policyDoc> } | { status: string }
+>;
+export type PayoutProofScope = {
+  accountId: string;
+  ownerKey: string;
+  currency: string;
+};
+/** Shared provider qualification. It can reconcile existing receipts, but never creates a bank payout. */
+export async function collectPayoutQualification(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: PayoutProofScope,
+  maxPages: number,
+): Promise<
+  | Held
+  | {
+      status: "verified";
+      observations: Infer<typeof observation>[];
+      destinationId: string;
+      providerAvailable: number;
+      observedAt: number;
+    }
+> {
+  const snapshot = (await ctx.runQuery(
+    componentRef(component, "payoutRelease/queries/snapshot"),
+    { accountId: opts.accountId, ownerKey: opts.ownerKey },
+  )) as Snapshot;
+  if (snapshot.status !== "ready") return snapshot;
+  const banks: string[] = [];
+  let bankCursor: string | undefined;
+  for (let page = 0; ; page++) {
+    if (page >= maxPages)
+      return { status: "held", reason: "bank_history_incomplete" };
+    const batch = await stripe.accounts.listExternalAccounts(opts.accountId, {
+      object: "bank_account",
+      limit: 100,
+      ...(bankCursor ? { starting_after: bankCursor } : {}),
+    });
+    for (const bank of batch.data)
+      if (
+        bank.object === "bank_account" &&
+        bank.currency === opts.currency &&
+        bank.default_for_currency &&
+        bank.status !== "errored"
+      )
+        banks.push(bank.id);
+    if (!batch.has_more) break;
+    const next = batch.data[batch.data.length - 1]?.id;
+    if (!next || next === bankCursor)
+      return { status: "held", reason: "bank_history_incomplete" };
+    bankCursor = next;
+  }
+  if (banks.length !== 1 || !/^ba_\w+$/.test(banks[0]))
+    return { status: "held", reason: "bank_destination_unavailable" };
+  const destinationId = banks[0];
+  const transactions: TransferReceiptTransaction[] = [];
+  for (const claim of snapshot.claims) {
+    if (
+      claim.currency !== opts.currency ||
+      claim.status === "canceled" ||
+      claim.status === "rejected"
+    )
+      continue;
+    if (claim.attemptedAt === undefined)
+      return { status: "held", reason: "pending_claim" };
+    const result = await reconcileRecipientPayout(stripe, component, ctx, {
+      accountId: opts.accountId,
+      ownerKey: opts.ownerKey,
+      operationKey: claim.operationKey,
+      maxPages,
+    });
+    if (result.status !== "updated")
+      return {
+        status: "held" as const,
+        reason:
+          result.status === "held"
+            ? result.reason
+            : "historical_claim_terminal",
+      };
+    for (const t of [result.receipt.debit, result.receipt.credit])
+      if (t)
+        transactions.push({ ...t, sourceId: result.receipt.stripePayoutId });
+  }
+  const observations = [];
+  for (const row of snapshot.transfers) {
+    const receipt = await getTransferFundingReceipt(stripe, component, ctx, {
+      accountId: opts.accountId,
+      stripeTransferId: row.stripeTransferId,
+    });
+    if (receipt.status !== "ready")
+      return { status: "held", reason: receipt.reason };
+    observations.push({
+      stripeTransferId: row.stripeTransferId,
+      currency: receipt.settlementCurrency,
+      matureNet: receipt.matureNet,
+      pendingCredits: receipt.pendingCredits,
+      ledgerFingerprint: transferFingerprint(row),
+      observedAt: receipt.observedAt,
+      transactionIds: receipt.transactions.map((t) => t.id),
+    });
+    if (receipt.settlementCurrency === opts.currency)
+      transactions.push(...receipt.transactions);
+  }
+  const history = await verifyPayoutHistory(stripe, {
+    accountId: opts.accountId,
+    currency: opts.currency,
+    transactions,
+    maxPages,
+  });
+  if (history.status !== "verified") return history;
+  return {
+    status: "verified",
+    observations,
+    destinationId,
+    providerAvailable: history.providerAvailable,
+    observedAt: history.observedAt,
+  };
+}

package/src/client/index.ts

@@ -1,3 +1,4 @@
+import { reconcilePayoutAndTrigger } from "./webhooks/payoutReconciliation.js";
 import { AffiliateRecoveryClient } from "./affiliateRecovery.js";
 export * from "./affiliateRecovery.js";
 import { CheckoutRequestClient } from "./checkoutRequests.js";
@@ -934,12 +935,6 @@ export class BetterStripe extends ReadContractClient {
     return subscriptionsImpl.upsertSubscription(this.component, ctx, opts);
   }
 
-  async getTrialStatus(ctx: RunCtx, opts: { subscriptionId: string }) {
-    return subscriptionsImpl.getTrialStatus(this.component, ctx, opts);
-  }
-
-  // INVOICE METHODS
-
   async listInvoices(
     ctx: RunCtx,
     opts?: {
@@ -1775,6 +1770,8 @@ export class BetterStripe extends ReadContractClient {
           splitCreateUpdate(triggers?.payment?.onCreate, undefined),
           record,
         ),
+      payoutReconciled: (ctx, record) =>
+        reconcilePayoutAndTrigger(component, ctx, record, triggers?.payout),
       payoutUpserted: (ctx, record) =>
         runUpsertAndTrigger<StripeComponentPayout>(
           ctx,

package/src/client/payoutPolicy.ts

@@ -1,3 +1,8 @@
+import {
+  previewRecipientPayout,
+  type PayoutPreviewOptions,
+} from "./connect/payoutPreview.js";
+export type * from "./connect/payoutPreview.js";
 import { PayoutWorkerClient } from "./connect/payoutWorker.js";
 export type * from "./connect/payoutWorker.js";
 import {
@@ -107,6 +112,15 @@ const toProvider = (
 /** Host authenticates owner/policy/consent. Provider I/O stays in this package. */
 export class PayoutPolicyClient {
   readonly worker: PayoutWorkerClient;
+  preview(ctx: RunCtx, opts: PayoutPreviewOptions) {
+    return previewRecipientPayout(
+      this.provider(),
+      this.component,
+      ctx,
+      opts,
+      () => this.verify(ctx, opts),
+    );
+  }
   constructor(
     private readonly component: Component,
     private readonly provider: () => Stripe,

package/src/client/readContracts.ts

@@ -1,4 +1,5 @@
 import * as checkoutImpl from "./billing/checkout.js";
+import * as subscriptionsImpl from "./billing/subscriptions.js";
 import * as payoutsImpl from "./connect/payouts.js";
 import type { ComponentApi } from "../component/_generated/component.js";
 import type { PaginationOptions, PaginationResult } from "convex/server";
@@ -75,6 +76,10 @@ export class ReadContractClient {
     return checkoutImpl.listCheckoutSessionsByUser(this.component, ctx, opts);
   }
 
+  async getTrialStatus(ctx: RunCtx, opts: { subscriptionId: string }) {
+    return subscriptionsImpl.getTrialStatus(this.component, ctx, opts);
+  }
+
   async getPayout(ctx: RunCtx, opts: { payoutId: string }) {
     return payoutsImpl.getPayout(this.component, ctx, opts);
   }

package/src/client/types/triggers.ts

@@ -243,6 +243,7 @@ export type TriggerDispatcherName =
   | "invoiceUpserted"
   | "paymentUpserted"
   | "payoutUpserted"
+  | "payoutReconciled"
   | "refundUpserted"
   | "disputeUpserted";
 

package/src/client/webhooks/helpers.ts

@@ -207,6 +207,7 @@ export const DISPATCHER_UPSERT_PATHS: Record<TriggerDispatcherName, string> = {
   invoiceUpserted: "billing/mutations/upsertInvoice",
   paymentUpserted: "connect/mutations/upsertPayment",
   payoutUpserted: "connect/mutations/upsertPayout",
+  payoutReconciled: "payoutSync/mutations/finish",
   refundUpserted: "connect/mutations/upsertRefund",
   disputeUpserted: "connect/mutations/upsertDispute",
 };

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

@@ -85,6 +85,11 @@ function fixture(
       },
     },
   };
+  const retrieve = vi
+    .spyOn(getStripeClient(key).payouts, "retrieve")
+    .mockImplementation(
+      async () => ({ ...event.data.object }) as Stripe.Response<Stripe.Payout>,
+    );
   const payout = () => t.query(payoutRef, { stripePayoutId: "po_qa_audit" });
   const deliver = async (config: RegisterRoutesConfig = {}, tamper = false) => {
     const body = JSON.stringify(event);
@@ -106,7 +111,7 @@ function fixture(
       return { status: response.status, body: await response.json() };
     });
   };
-  return { t, event, payout, deliver };
+  return { t, event, payout, deliver, retrieve };
 }
 
 it("reconciles signed cancellation before callbacks and deduplicates replay", async () => {
@@ -158,6 +163,7 @@ it("reconciles signed cancellation before callbacks and deduplicates replay", as
     await f.t.query(ledgerRef, { stripeEventId: f.event.id }),
   ).toMatchObject({ status: "processed" });
   expect(transport).not.toHaveBeenCalled();
+  expect(f.retrieve).toHaveBeenCalledTimes(2);
 });
 
 it("rejects a tampered cancellation before storage or callbacks", async () => {
@@ -167,6 +173,7 @@ it("rejects a tampered cancellation before storage or callbacks", async () => {
   expect(await f.payout()).toBeNull();
   expect(await f.t.query(ledgerRef, { stripeEventId: f.event.id })).toBeNull();
   expect(onEvent).not.toHaveBeenCalled();
+  expect(f.retrieve).not.toHaveBeenCalled();
   expect(transport).not.toHaveBeenCalled();
 });
 
@@ -188,6 +195,12 @@ it.each([
     });
     expect(await f.payout()).toEqual(first);
     expect(transport).not.toHaveBeenCalled();
+    expect(f.retrieve).toHaveBeenCalledOnce();
+    expect(f.retrieve).toHaveBeenCalledWith(
+      "po_qa_audit",
+      {},
+      { stripeAccount: "acct_qa_recipient" },
+    );
   },
 );
 

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