@fantastic.dev/better-stripe 0.25.0 → 0.26.0

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

@@ -56,6 +56,8 @@ import type * as payoutRelease_fees from "../payoutRelease/fees.js";
 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_planning from "../payoutRelease/planning.js";
+import type * as payoutRelease_preview from "../payoutRelease/preview.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";
@@ -136,6 +138,8 @@ const fullApi: ApiFromModules<{
   "payoutRelease/helpers": typeof payoutRelease_helpers;
   "payoutRelease/mutations": typeof payoutRelease_mutations;
   "payoutRelease/observation": typeof payoutRelease_observation;
+  "payoutRelease/planning": typeof payoutRelease_planning;
+  "payoutRelease/preview": typeof payoutRelease_preview;
   "payoutRelease/queries": typeof payoutRelease_queries;
   "payoutSnapshots/localState": typeof payoutSnapshots_localState;
   "payoutSnapshots/mutations": typeof payoutSnapshots_mutations;

package/src/component/_generated/component.ts

@@ -3608,6 +3608,48 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        preview: FunctionReference<
+          "query",
+          "internal",
+          {
+            accountId: string;
+            currency: string;
+            expectedRevision: number;
+            independentLiabilities: number;
+            observations: Array<{
+              currency: string;
+              ledgerFingerprint: string;
+              matureNet: number;
+              observedAt: number;
+              pendingCredits: number;
+              stripeTransferId: string;
+              transactionIds: Array<string>;
+            }>;
+            ownerKey: string;
+            providerAvailable: number;
+          },
+          | { amount: 0; reason: string; status: "held" }
+          | {
+              amount: number;
+              confirmedFees: number;
+              currency: string;
+              independentLiabilities: number;
+              matureUnpaid: number;
+              observedAt: number;
+              pendingCredits: number;
+              providerAvailable: number;
+              providerMinimum: null;
+              reason?: string;
+              sources: Array<{
+                matureUnpaid: number;
+                pendingCredits: number;
+                role: "store" | "affiliate" | "other";
+              }>;
+              status: "held" | "qualified";
+              threshold: number;
+            },
+          Name
+        >;
         snapshot: FunctionReference<
           "query",
           "internal",

package/src/component/affiliateRecovery/accounting.ts

@@ -1,5 +1,5 @@
 import type { Doc } from "../_generated/dataModel.js";
-import type { MutationCtx } from "../_generated/server.js";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
 export type Obligation = Omit<
   Doc<"affiliateObligations">,
   "_id" | "_creationTime"
@@ -13,7 +13,7 @@ export const due = (row: Obligation) =>
 export const credit = (row: Obligation) =>
   row.needsReconciliation ? 0 : Math.max(0, netRecovery(row) - target(row));
 export async function balance(
-  ctx: MutationCtx,
+  ctx: MutationCtx | QueryCtx,
   account: string,
   currency: string,
 ) {

package/src/component/payoutRelease/helpers.ts

@@ -1,6 +1,6 @@
 import type { Infer } from "convex/values";
 import type { transferDocValidator } from "../connect/validators.js";
-import type { MutationCtx } from "../_generated/server.js";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
 import type { Doc } from "../_generated/dataModel.js";
 import { readPolicy, validateScope } from "../payoutPolicy/helpers.js";
 import type { observation } from "./schema.js";
@@ -50,7 +50,7 @@ export async function claimByKey(
   return claim;
 }
 export async function readyPolicy(
-  ctx: MutationCtx,
+  ctx: MutationCtx | QueryCtx,
   args: { accountId: string; ownerKey: string; expectedRevision: number },
 ) {
   const policy = await readPolicy(ctx, args);
@@ -67,7 +67,7 @@ export async function readyPolicy(
 }
 /** Full local account membership is checked under OCC before any reservation. */
 export async function checkSnapshot(
-  ctx: MutationCtx,
+  ctx: MutationCtx | QueryCtx,
   accountId: string,
   observations: Infer<typeof observation>[],
   fresh: boolean,
@@ -126,7 +126,10 @@ export async function checkSnapshot(
   }
   return byId;
 }
-export async function sourceById(ctx: MutationCtx, stripeTransferId: string) {
+export async function sourceById(
+  ctx: MutationCtx | QueryCtx,
+  stripeTransferId: string,
+) {
   return ctx.db
     .query("payoutSourceAllocations")
     .withIndex("by_transfer", (q) => q.eq("stripeTransferId", stripeTransferId))

package/src/component/payoutRelease/mutations.ts

@@ -19,7 +19,7 @@ import {
   validateIdentity,
   add,
 } from "./helpers.js";
-import { planRecipientPayout, type PayoutFundingSource } from "./allocation.js";
+import { readPayoutPlan } from "./planning.js";
 const held = v.object({
   status: v.literal("held"),
   reason: v.union(
@@ -63,10 +63,6 @@ export const claim = mutation({
       return existing;
     }
     const policy = await readyPolicy(ctx, args);
-    const minimum = policy.thresholds.find(
-      (value) => value.currency === args.currency,
-    );
-    if (!minimum) throw new Error("Payout policy currency is not configured.");
     const pending = await ctx.db
       .query("payoutReleaseClaims")
       .withIndex("by_account_status", (q) =>
@@ -81,38 +77,7 @@ export const claim = mutation({
         currency: args.currency,
         providerMinimum: null,
       };
-    const rows = await checkSnapshot(
-      ctx,
-      args.accountId,
-      args.observations,
-      true,
-    );
-    const sources: PayoutFundingSource[] = [];
-    for (const observation of args.observations) {
-      const prior = await sourceById(ctx, observation.stripeTransferId);
-      if (
-        prior &&
-        (prior.accountId !== args.accountId ||
-          prior.ownerKey !== args.ownerKey ||
-          prior.currency !== observation.currency)
-      )
-        throw new Error("Payout source allocation identity changed.");
-      sources.push({
-        ...observation,
-        role: rows.get(observation.stripeTransferId)!.role,
-        paidAmount: prior?.paidAmount ?? 0,
-        reservedAmount: prior?.reservedAmount ?? 0,
-      });
-    }
-    const fees = await readFees(ctx, args);
-    const plan = planRecipientPayout({
-      currency: args.currency,
-      threshold: minimum.amount,
-      providerAvailable: args.providerAvailable,
-      independentLiabilities: args.independentLiabilities,
-      confirmedFees: fees?.amount ?? 0,
-      sources,
-    });
+    const { plan, fees } = await readPayoutPlan(ctx, args, policy);
     if (plan.status === "held") return plan;
     await reserveRecoveryGuard(ctx, args, plan.amount);
     for (const allocation of plan.allocations) {

package/src/component/payoutRelease/planning.ts

@@ -0,0 +1,55 @@
+import type { Infer } from "convex/values";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { policyDoc } from "../payoutPolicy/schema.js";
+import type { observation } from "./observation.js";
+import { checkSnapshot, sourceById } from "./helpers.js";
+import { readFees } from "./fees.js";
+import { planRecipientPayout, type PayoutFundingSource } from "./allocation.js";
+export async function readPayoutPlan(
+  ctx: MutationCtx | QueryCtx,
+  args: {
+    accountId: string;
+    ownerKey: string;
+    currency: string;
+    observations: Infer<typeof observation>[];
+    providerAvailable: number;
+    independentLiabilities: number;
+  },
+  policy: Infer<typeof policyDoc>,
+) {
+  const minimum = policy.thresholds.find((t) => t.currency === args.currency);
+  if (!minimum) throw new Error("Payout policy currency is not configured.");
+  const rows = await checkSnapshot(
+    ctx,
+    args.accountId,
+    args.observations,
+    true,
+  );
+  const sources: PayoutFundingSource[] = [];
+  for (const observation of args.observations) {
+    const prior = await sourceById(ctx, observation.stripeTransferId);
+    if (
+      prior &&
+      (prior.accountId !== args.accountId ||
+        prior.ownerKey !== args.ownerKey ||
+        prior.currency !== observation.currency)
+    )
+      throw new Error("Payout source allocation identity changed.");
+    sources.push({
+      ...observation,
+      role: rows.get(observation.stripeTransferId)!.role,
+      paidAmount: prior?.paidAmount ?? 0,
+      reservedAmount: prior?.reservedAmount ?? 0,
+    });
+  }
+  const fees = await readFees(ctx, args);
+  const plan = planRecipientPayout({
+    currency: args.currency,
+    threshold: minimum.amount,
+    providerAvailable: args.providerAvailable,
+    independentLiabilities: args.independentLiabilities,
+    confirmedFees: fees?.amount ?? 0,
+    sources,
+  });
+  return { plan, sources, fees, threshold: minimum.amount };
+}

package/src/component/payoutRelease/preview.ts

@@ -0,0 +1,118 @@
+import { v } from "convex/values";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { Infer } from "convex/values";
+import { scopeFields } from "../payoutPolicy/schema.js";
+import { observation } from "./observation.js";
+import { readyPolicy, add } from "./helpers.js";
+import { readPayoutPlan } from "./planning.js";
+import { balance } from "../affiliateRecovery/accounting.js";
+export const previewFields = {
+  ...scopeFields,
+  expectedRevision: v.number(),
+  currency: v.string(),
+  providerAvailable: v.number(),
+  independentLiabilities: v.number(),
+  observations: v.array(observation),
+};
+const held = v.object({
+  status: v.literal("held"),
+  reason: v.string(),
+  amount: v.literal(0),
+});
+export const previewResult = v.union(
+  held,
+  v.object({
+    status: v.union(v.literal("held"), v.literal("qualified")),
+    reason: v.optional(v.string()),
+    currency: v.string(),
+    amount: v.number(),
+    threshold: v.number(),
+    providerMinimum: v.null(),
+    matureUnpaid: v.number(),
+    pendingCredits: v.number(),
+    confirmedFees: v.number(),
+    independentLiabilities: v.number(),
+    providerAvailable: v.number(),
+    observedAt: v.number(),
+    sources: v.array(
+      v.object({
+        role: v.union(
+          v.literal("store"),
+          v.literal("affiliate"),
+          v.literal("other"),
+        ),
+        matureUnpaid: v.number(),
+        pendingCredits: v.number(),
+      }),
+    ),
+  }),
+);
+type Args = {
+  [K in keyof typeof previewFields]: Infer<(typeof previewFields)[K]>;
+};
+/** Trusted provider observations, informational only. No reservation or monetary state change. */
+export async function previewPlan(
+  ctx: MutationCtx | QueryCtx,
+  args: Args,
+): Promise<Infer<typeof previewResult>> {
+  const policy = await readyPolicy(ctx, args);
+  const recovery = await balance(ctx, args.accountId, args.currency);
+  if (
+    recovery &&
+    (recovery.outstandingDebt > 0 ||
+      recovery.reservedRecovery > 0 ||
+      recovery.reservedRestoration > 0 ||
+      recovery.activePayoutKey)
+  )
+    return { status: "held", reason: "affiliate_recovery_pending", amount: 0 };
+  const pending = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_account_status", (q) =>
+      q.eq("accountId", args.accountId).eq("status", "reserved"),
+    )
+    .first();
+  if (pending) return { status: "held", reason: "pending_claim", amount: 0 };
+  const {
+    plan,
+    sources: funding,
+    fees,
+    threshold,
+  } = await readPayoutPlan(ctx, args, policy);
+  const sources = (["store", "affiliate", "other"] as const).map((role) => {
+    let matureUnpaid = 0,
+      pendingCredits = 0;
+    for (const source of funding)
+      if (
+        source.currency === args.currency &&
+        (source.role ?? "other") === role
+      ) {
+        matureUnpaid = add(
+          matureUnpaid,
+          add(
+            add(source.matureNet, -source.paidAmount),
+            -source.reservedAmount,
+          ),
+        );
+        pendingCredits = add(pendingCredits, source.pendingCredits);
+      }
+    return { role, matureUnpaid, pendingCredits };
+  });
+  return {
+    status: plan.status,
+    ...(plan.status === "held" ? { reason: plan.reason } : {}),
+    currency: plan.currency,
+    amount: plan.amount,
+    threshold,
+    providerMinimum: null,
+    matureUnpaid: plan.matureUnpaid,
+    pendingCredits: plan.pendingCredits,
+    confirmedFees: fees?.amount ?? 0,
+    independentLiabilities: args.independentLiabilities,
+    providerAvailable: args.providerAvailable,
+    observedAt: Math.min(
+      Date.now(),
+      ...args.observations.map((o) => o.observedAt),
+    ),
+    sources,
+  };
+}

package/src/component/payoutRelease/queries.ts

@@ -1,3 +1,4 @@
+import { previewFields, previewResult, previewPlan } from "./preview.js";
 import { paginator } from "convex-helpers/server/pagination";
 import schema from "../schema.js";
 import { transferDocValidator } from "../connect/validators.js";
@@ -8,6 +9,11 @@ import { query } from "../_generated/server.js";
 import { identity, claimDoc } from "./schema.js";
 import { validateIdentity } from "./helpers.js";
 import { readPolicy } from "../payoutPolicy/helpers.js";
+export const preview = query({
+  args: previewFields,
+  returns: previewResult,
+  handler: previewPlan,
+});
 export const get = query({
   args: identity,
   returns: v.union(claimDoc, v.null()),