@fantastic.dev/better-stripe 0.25.1 → 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/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/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()),