@fantastic.dev/better-stripe 0.24.0 → 0.25.1

package/src/client/connect/payoutWorker.ts

@@ -0,0 +1,144 @@
+import type { Infer } from "convex/values";
+import type { jobDoc } from "../../component/payoutWorker/schema.js";
+import type { policyDoc } from "../../component/payoutPolicy/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import type {
+  PayoutReleaseOptions,
+  PayoutReleaseResult,
+} from "./payoutExecution.js";
+import type {
+  PayoutReconciliationOptions,
+  PayoutReconciliation,
+} from "./payoutReconciliation.js";
+export type PayoutWorkerJob = Infer<typeof jobDoc>;
+export type PayoutWorkerScope = {
+  accountId: string;
+  ownerKey: string;
+  currency: string;
+};
+export type PayoutWorkerOptions = Omit<PayoutReleaseOptions, "operationKey"> & {
+  cadenceMs?: number;
+};
+type PageOptions = { cursor: string | null; numItems: number };
+type Page<T> = { page: T[]; continueCursor: string; isDone: boolean };
+type Held = { status: "held"; reason: string; nextAttemptAt?: number };
+export type PayoutWorkerResult =
+  | Held
+  | { status: "completed"; job: PayoutWorkerJob; payout: PayoutReleaseResult };
+/** Host cron only. No method on this worker represents a customer withdrawal request. */
+export class PayoutWorkerClient {
+  constructor(
+    private readonly component: Component,
+    private readonly release: (
+      ctx: RunCtx,
+      opts: PayoutReleaseOptions,
+    ) => Promise<PayoutReleaseResult>,
+    private readonly reconcile: (
+      ctx: RunCtx,
+      opts: PayoutReconciliationOptions,
+    ) => Promise<PayoutReconciliation>,
+  ) {}
+  get(ctx: RunCtx, scope: PayoutWorkerScope): Promise<PayoutWorkerJob | null> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/get"),
+      {
+        accountId: scope.accountId,
+        ownerKey: scope.ownerKey,
+        currency: scope.currency,
+      },
+    );
+  }
+  policies(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<Infer<typeof policyDoc>>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/policies"),
+      { paginationOpts },
+    );
+  }
+  recovering(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<PayoutWorkerJob>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/recovering"),
+      { paginationOpts },
+    );
+  }
+  changing(
+    ctx: RunCtx,
+    paginationOpts: PageOptions,
+  ): Promise<Page<Infer<typeof policyDoc>>> {
+    return ctx.runQuery(
+      componentRef(this.component, "payoutWorker/queries/changing"),
+      { paginationOpts },
+    );
+  }
+  async run(
+    ctx: RunCtx,
+    opts: PayoutWorkerOptions,
+  ): Promise<PayoutWorkerResult> {
+    if (
+      !Number.isSafeInteger(opts.independentLiabilities) ||
+      opts.independentLiabilities < 0 ||
+      (opts.maxPages !== undefined &&
+        (!Number.isInteger(opts.maxPages) ||
+          opts.maxPages < 1 ||
+          opts.maxPages > 100))
+    )
+      throw new Error("Invalid automatic payout liabilities or page budget.");
+    const scope = {
+      accountId: opts.accountId,
+      ownerKey: opts.ownerKey,
+      currency: opts.currency,
+    };
+    const started = (await runMutationOrThrow(
+      ctx,
+      componentRef(this.component, "payoutWorker/mutations/begin"),
+      {
+        ...scope,
+        cadenceMs: opts.cadenceMs ?? 300000,
+      },
+    )) as
+      Held | { status: "run"; job: PayoutWorkerJob; reconcileOnly: boolean };
+    if (started.status === "held") return started;
+    const operationKey = started.job.operationKey!;
+    const finish = (reason: string) =>
+      runMutationOrThrow(
+        ctx,
+        componentRef(this.component, "payoutWorker/mutations/finish"),
+        { ...scope, operationKey, generation: started.job.generation, reason },
+      ) as Promise<PayoutWorkerJob>;
+    let payout: PayoutReleaseResult;
+    try {
+      payout = started.reconcileOnly
+        ? await this.reconcile(ctx, {
+            ...scope,
+            operationKey,
+            maxPages: opts.maxPages,
+          })
+        : await this.release(ctx, {
+            ...scope,
+            operationKey,
+            independentLiabilities: opts.independentLiabilities,
+            maxPages: opts.maxPages,
+          });
+    } catch (error) {
+      try {
+        await finish("worker_error");
+      } catch (completionError) {
+        throw new AggregateError(
+          [error, completionError],
+          "Payout worker outcome requires reconciliation.",
+        );
+      }
+      throw error;
+    }
+    const reason =
+      payout.status === "held" ? payout.reason : payout.claim.status;
+    return { status: "completed", job: await finish(reason), payout };
+  }
+}

package/src/client/index.ts

@@ -1,5 +1,8 @@
+import { reconcilePayoutAndTrigger } from "./webhooks/payoutReconciliation.js";
 import { AffiliateRecoveryClient } from "./affiliateRecovery.js";
 export * from "./affiliateRecovery.js";
+import { CheckoutRequestClient } from "./checkoutRequests.js";
+export type { PreparedCheckoutSession } from "./billing/preparedCheckout.js";
 import * as payoutSyncImpl from "./connect/payoutSync.js";
 export type {
   PayoutSyncOptions,
@@ -680,6 +683,14 @@ export class BetterStripe extends ReadContractClient {
   }
 
   // CHECKOUT METHODS
+  get checkoutRequests() {
+    return new CheckoutRequestClient(
+      this.component,
+      () => this.stripe(),
+      (fee) => this.resolveFee(fee),
+      this._statementDescriptorSuffix,
+    );
+  }
 
   async createCheckoutSession(ctx: RunCtx, opts: CreateCheckoutSessionOptions) {
     const { fee, ...rest } = opts;
@@ -699,27 +710,6 @@ export class BetterStripe extends ReadContractClient {
     );
   }
 
-  async getCheckoutSession(
-    ctx: RunCtx,
-    opts: { sessionId: string },
-  ): Promise<StripeComponentCheckoutSession | null> {
-    return checkoutImpl.getCheckoutSession(this.component, ctx, opts);
-  }
-
-  async getCheckoutSessionByStripeId(
-    ctx: RunCtx,
-    opts: { stripeSessionId: string },
-  ): Promise<StripeComponentCheckoutSession | null> {
-    return checkoutImpl.getCheckoutSessionByStripeId(this.component, ctx, opts);
-  }
-
-  async listCheckoutSessionsByUser(
-    ctx: RunCtx,
-    opts: { userId: string; status?: string },
-  ): Promise<StripeComponentCheckoutSession[]> {
-    return checkoutImpl.listCheckoutSessionsByUser(this.component, ctx, opts);
-  }
-
   async upsertCheckoutSession(
     ctx: RunCtx,
     opts: {
@@ -945,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?: {
@@ -1786,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,12 @@
+import { PayoutWorkerClient } from "./connect/payoutWorker.js";
+export type * from "./connect/payoutWorker.js";
+import {
+  collectPayoutSnapshot,
+  discardPayoutSnapshot,
+  type PayoutCollectionOptions,
+  type PayoutCollectionScope,
+} from "./connect/payoutCollection.js";
+export type * from "./connect/payoutCollection.js";
 import { collectAdoptionProof } from "./connect/payoutActivationProof.js";
 import {
   adoptRecipientPayouts,
@@ -97,10 +106,26 @@ const toProvider = (
 });
 /** Host authenticates owner/policy/consent. Provider I/O stays in this package. */
 export class PayoutPolicyClient {
+  readonly worker: PayoutWorkerClient;
   constructor(
     private readonly component: Component,
     private readonly provider: () => Stripe,
-  ) {}
+  ) {
+    this.worker = new PayoutWorkerClient(
+      component,
+      (ctx, opts) => this.release(ctx, opts),
+      (ctx, opts) => this.reconcilePayout(ctx, opts),
+    );
+  }
+  collectSnapshot(ctx: RunCtx, opts: PayoutCollectionOptions) {
+    return collectPayoutSnapshot(this.component, ctx, opts);
+  }
+  discardSnapshot(
+    ctx: RunCtx,
+    opts: PayoutCollectionScope & { batchSize?: number },
+  ) {
+    return discardPayoutSnapshot(this.component, ctx, opts);
+  }
   adoptPayouts(ctx: RunCtx, opts: PayoutAdoptionOptions) {
     return adoptRecipientPayouts(this.provider(), this.component, ctx, opts);
   }

package/src/client/readContracts.ts

@@ -1,9 +1,12 @@
+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";
 import type { Component, RunCtx } from "./helpers.js";
 import type { PayoutStatus } from "../component/connect/validators.js";
 import type {
+  StripeComponentCheckoutSession,
   StripeComponentPayout,
   StripeComponentProduct,
   StripeComponentPrice,
@@ -52,6 +55,31 @@ export class ReadContractClient {
     );
   }
 
+  async getCheckoutSession(
+    ctx: RunCtx,
+    opts: { sessionId: string },
+  ): Promise<StripeComponentCheckoutSession | null> {
+    return checkoutImpl.getCheckoutSession(this.component, ctx, opts);
+  }
+
+  async getCheckoutSessionByStripeId(
+    ctx: RunCtx,
+    opts: { stripeSessionId: string },
+  ): Promise<StripeComponentCheckoutSession | null> {
+    return checkoutImpl.getCheckoutSessionByStripeId(this.component, ctx, opts);
+  }
+
+  async listCheckoutSessionsByUser(
+    ctx: RunCtx,
+    opts: { userId: string; status?: string },
+  ): Promise<StripeComponentCheckoutSession[]> {
+    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);
+}