@fantastic.dev/better-stripe 0.28.5 → 0.29.0

package/src/component/payoutRelease/helpers.ts

@@ -71,24 +71,30 @@ export async function checkSnapshot(
   accountId: string,
   observations: Infer<typeof observation>[],
   fresh: boolean,
+  freshCurrency?: string,
+  membership?: Map<string, Doc<"transfers">>,
 ) {
-  const rows = await ctx.db
-    .query("transfers")
-    .withIndex("by_destination_account_id", (q) =>
-      q.eq("destinationAccountId", accountId),
-    )
-    .take(101);
+  const rows = membership
+    ? [...membership.values()]
+    : await ctx.db
+        .query("transfers")
+        .withIndex("by_destination_account_id", (q) =>
+          q.eq("destinationAccountId", accountId),
+        )
+        .take(101);
   if (
-    rows.length > 100 ||
+    (!membership && rows.length > 100) ||
     observations.length !== rows.length ||
     new Set(observations.map((o) => o.stripeTransferId)).size !== rows.length
   )
     throw new Error("Payout source snapshot is incomplete or duplicated.");
   const byId = new Map(rows.map((row) => [row.stripeTransferId, row]));
-  const allocated = await ctx.db
-    .query("payoutSourceAllocations")
-    .withIndex("by_account", (q) => q.eq("accountId", accountId))
-    .take(101);
+  const allocated = membership
+    ? []
+    : await ctx.db
+        .query("payoutSourceAllocations")
+        .withIndex("by_account", (q) => q.eq("accountId", accountId))
+        .take(101);
   if (
     allocated.length > 100 ||
     allocated.some((source) => !byId.has(source.stripeTransferId))
@@ -106,6 +112,7 @@ export async function checkSnapshot(
       throw new Error("Payout source snapshot changed or is not ready.");
     if (
       fresh &&
+      (freshCurrency === undefined || o.currency === freshCurrency) &&
       (!Number.isSafeInteger(o.observedAt) ||
         o.observedAt > Date.now() ||
         o.observedAt < Date.now() - 30000)
@@ -177,6 +184,9 @@ export function payoutClaimFingerprint(c: Doc<"payoutReleaseClaims">) {
     c.ownerKey,
     c.operationKey,
     c.historical ?? false,
+    c.snapshotId,
+    c.liabilityRevision,
+    c.independentLiabilities,
     c.currency,
     c.amount,
     c.status,

package/src/component/payoutRelease/mutations.ts

@@ -1,3 +1,8 @@
+import {
+  collectedSources,
+  bindCollection,
+  retireCollection,
+} from "../payoutSnapshots/financial.js";
 import {
   reserveRecoveryGuard,
   releaseRecoveryGuard,
@@ -43,6 +48,8 @@ export const claim = mutation({
     providerAvailable: v.number(),
     independentLiabilities: v.number(),
     observations: v.array(observation),
+    snapshotId: v.optional(v.id("payoutSnapshots")),
+    liabilityRevision: v.optional(v.number()),
   },
   returns: v.union(claimDoc, held),
   handler: async (ctx, args) => {
@@ -106,10 +113,17 @@ export const claim = mutation({
       ...(args.destinationId ? { destinationId: args.destinationId } : {}),
       allocations: plan.allocations,
       observations: args.observations,
+      independentLiabilities: args.independentLiabilities,
+      ...(args.snapshotId ? { snapshotId: args.snapshotId } : {}),
+      ...(args.liabilityRevision === undefined
+        ? {}
+        : { liabilityRevision: args.liabilityRevision }),
       feeRevision: fees?.revision ?? 0,
       status: "reserved",
     });
-    return (await ctx.db.get("payoutReleaseClaims", id))!;
+    const claim = (await ctx.db.get("payoutReleaseClaims", id))!;
+    await bindCollection(ctx, claim);
+    return claim;
   },
 });
 export const beginAttempt = mutation({
@@ -124,11 +138,19 @@ export const beginAttempt = mutation({
     const feeRevision = (await readFees(ctx, claim))?.revision ?? 0;
     if (feeRevision !== (claim.feeRevision ?? 0))
       throw new Error("Payout fee revision changed after reservation.");
-    await checkSnapshot(ctx, claim.accountId, claim.observations, true);
+    await checkSnapshot(
+      ctx,
+      claim.accountId,
+      claim.observations,
+      true,
+      claim.currency,
+      await collectedSources(ctx, claim, claim.observations),
+    );
     await reserveRecoveryGuard(ctx, claim, claim.amount);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       attemptedAt: Date.now(),
     });
+    await retireCollection(ctx, claim);
     return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
   },
 });
@@ -145,6 +167,7 @@ export const cancelUnattempted = mutation({
       throw new Error("An attempted payout claim cannot be canceled.");
     if (claim.status === "canceled") return claim;
     await moveAllocations(ctx, claim, "release");
+    await retireCollection(ctx, claim);
     await releaseRecoveryGuard(ctx, claim);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       status: "canceled",

package/src/component/payoutRelease/planning.ts

@@ -1,3 +1,5 @@
+import { collectedSources } from "../payoutSnapshots/financial.js";
+import type { Id } from "../_generated/dataModel.js";
 import type { Infer } from "convex/values";
 import type { MutationCtx, QueryCtx } from "../_generated/server.js";
 import type { policyDoc } from "../payoutPolicy/schema.js";
@@ -14,6 +16,9 @@ export async function readPayoutPlan(
     ownerKey: string;
     currency: string;
     observations: Infer<typeof observation>[];
+    snapshotId?: Id<"payoutSnapshots">;
+    operationKey?: string;
+    liabilityRevision?: number;
     providerAvailable: number;
     independentLiabilities: number;
   },
@@ -26,6 +31,8 @@ export async function readPayoutPlan(
     args.accountId,
     args.observations,
     true,
+    args.currency,
+    await collectedSources(ctx, args, args.observations),
   );
   const sources: PayoutFundingSource[] = [];
   for (const observation of args.observations) {
@@ -45,7 +52,7 @@ export async function readPayoutPlan(
     });
   }
   const fees = await readFees(ctx, args);
-  await assertAllocationTotals(ctx, args, sources);
+  if (!args.snapshotId) await assertAllocationTotals(ctx, args, sources);
   const minimumWaived = waiveApplicationMinimum(policy, Date.now());
   const plan = planRecipientPayout({
     currency: args.currency,

package/src/component/payoutRelease/preview.ts

@@ -14,6 +14,8 @@ export const previewFields = {
   providerAvailable: v.number(),
   independentLiabilities: v.number(),
   observations: v.array(observation),
+  snapshotId: v.optional(v.id("payoutSnapshots")),
+  liabilityRevision: v.optional(v.number()),
 };
 const held = v.object({
   status: v.literal("held"),
@@ -106,7 +108,9 @@ export async function previewPlan(
     providerAvailable: args.providerAvailable,
     observedAt: Math.min(
       Date.now(),
-      ...args.observations.map((o) => o.observedAt),
+      ...args.observations
+        .filter((o) => o.currency === args.currency)
+        .map((o) => o.observedAt),
     ),
     ...progress,
   };

package/src/component/payoutRelease/schema.ts

@@ -13,6 +13,9 @@ export const allocation = v.object({
 export const claimFields = {
   ...scopeFields,
   historical: v.optional(v.boolean()),
+  snapshotId: v.optional(v.id("payoutSnapshots")),
+  liabilityRevision: v.optional(v.number()),
+  independentLiabilities: v.optional(v.number()),
   operationKey: v.string(),
   expectedRevision: v.number(),
   currency: v.string(),

package/src/component/payoutSnapshots/financial.ts

@@ -0,0 +1,121 @@
+import { assertLiabilityVersion } from "./liabilities.js";
+import type { Infer } from "convex/values";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { Id, Doc } from "../_generated/dataModel.js";
+import type { observation } from "../payoutRelease/schema.js";
+import { readPolicy } from "../payoutPolicy/helpers.js";
+import { riskRevision } from "./revisions.js";
+export type CollectionScope = {
+  accountId: string;
+  ownerKey: string;
+  snapshotId?: Id<"payoutSnapshots">;
+  operationKey?: string;
+  liabilityRevision?: number;
+};
+/** The complete collector baseline is checked again under the claim's OCC transaction. */
+export async function collectedSources(
+  ctx: QueryCtx | MutationCtx,
+  scope: CollectionScope,
+  observations: Infer<typeof observation>[],
+) {
+  if (!scope.snapshotId) {
+    await assertLiabilityVersion(ctx, scope);
+    return undefined;
+  }
+  const h = await ctx.db.get("payoutSnapshots", scope.snapshotId);
+  const policy = await readPolicy(ctx, scope);
+  if (
+    !h ||
+    h.accountId !== scope.accountId ||
+    h.ownerKey !== scope.ownerKey ||
+    h.phase !== "local_ready" ||
+    h.expiresAt <= Date.now() ||
+    h.expectedRevision !== policy?.revision ||
+    h.policyMode !== policy?.mode ||
+    h.policyOperationKey !== policy?.operationKey ||
+    (!h.readOnly && h.boundOperationKey !== scope.operationKey) ||
+    (await riskRevision(ctx, scope.accountId)) !==
+      (h.readOnly ? h.riskRevision : h.boundRiskRevision)
+  )
+    throw new Error("Financial payout collection changed or is unavailable.");
+  if (h.readOnly) await assertLiabilityVersion(ctx, scope);
+  if (
+    observations.length !== h.sourceCount ||
+    new Set(observations.map((o) => o.stripeTransferId)).size !== h.sourceCount
+  )
+    throw new Error("Financial payout collection membership is incomplete.");
+  const rows = new Map<string, Doc<"transfers">>();
+  for (const o of observations) {
+    const cached = await ctx.db
+      .query("payoutSnapshotSources")
+      .withIndex("by_snapshot_transfer", (q) =>
+        q.eq("snapshotId", h._id).eq("stripeTransferId", o.stripeTransferId),
+      )
+      .unique();
+    const row = await ctx.db
+      .query("transfers")
+      .withIndex("by_stripe_transfer_id", (q) =>
+        q.eq("stripeTransferId", o.stripeTransferId),
+      )
+      .unique();
+    if (
+      !cached ||
+      !row ||
+      cached.needsCheck ||
+      cached.ledgerFingerprint !== o.ledgerFingerprint ||
+      cached.expectedPaid !== cached.paidAmount ||
+      cached.expectedReserved !== cached.reservedAmount
+    )
+      throw new Error("Financial payout collection source changed.");
+    if (h.readOnly) {
+      const allocation = await ctx.db
+        .query("payoutSourceAllocations")
+        .withIndex("by_transfer", (q) =>
+          q.eq("stripeTransferId", o.stripeTransferId),
+        )
+        .unique();
+      if (
+        (allocation?.paidAmount ?? 0) !== cached.paidAmount ||
+        (allocation?.reservedAmount ?? 0) !== cached.reservedAmount ||
+        (allocation &&
+          (allocation.accountId !== scope.accountId ||
+            allocation.ownerKey !== scope.ownerKey ||
+            allocation.currency !== o.currency))
+      )
+        throw new Error("Financial payout collection allocation changed.");
+    }
+    rows.set(o.stripeTransferId, row);
+  }
+  return rows;
+}
+export async function bindCollection(
+  ctx: MutationCtx,
+  claim: Doc<"payoutReleaseClaims">,
+) {
+  if (!claim.snapshotId) return;
+  await ctx.db.patch("payoutSnapshots", claim.snapshotId, {
+    readOnly: false,
+    boundOperationKey: claim.operationKey,
+    boundRiskRevision: await riskRevision(ctx, claim.accountId),
+  });
+}
+/** The immutable claim retains all financial proof; only its disposable cache becomes discardable. */
+export async function retireCollection(
+  ctx: MutationCtx,
+  claim: Doc<"payoutReleaseClaims">,
+) {
+  if (!claim.snapshotId) return;
+  const h = await ctx.db.get("payoutSnapshots", claim.snapshotId);
+  if (!h || h.readOnly) return;
+  if (
+    h.accountId !== claim.accountId ||
+    h.ownerKey !== claim.ownerKey ||
+    h.boundOperationKey !== claim.operationKey
+  )
+    throw new Error("Financial payout collection binding changed.");
+  await ctx.db.patch("payoutSnapshots", h._id, {
+    readOnly: true,
+    phase: "invalidated",
+    reason: "financial_consumed",
+  });
+}

package/src/component/payoutSnapshots/liabilities.ts

@@ -0,0 +1,25 @@
+import type { QueryCtx, MutationCtx } from "../_generated/server.js";
+import { riskRevision } from "./revisions.js";
+/** Recovery-backed recipients must carry the version captured with their authorized amount. */
+export async function assertLiabilityVersion(
+  ctx: QueryCtx | MutationCtx,
+  scope: { accountId: string; liabilityRevision?: number },
+) {
+  if (scope.liabilityRevision === undefined) {
+    const recovery = await ctx.db
+      .query("recoveryBalances")
+      .withIndex("by_scope", (q) => q.eq("accountId", scope.accountId))
+      .first();
+    if (recovery)
+      throw new Error(
+        "A versioned recovery liability quote is required before payout qualification.",
+      );
+    return;
+  }
+  if (
+    !Number.isSafeInteger(scope.liabilityRevision) ||
+    scope.liabilityRevision < 0 ||
+    scope.liabilityRevision !== (await riskRevision(ctx, scope.accountId))
+  )
+    throw new Error("Payout liability version changed; resolve a fresh quote.");
+}

package/src/component/payoutSnapshots/localState.ts

@@ -171,9 +171,13 @@ export async function cacheClaim(
   }
   if (total !== row.amount || total <= 0)
     throw new CollectionError("allocation_amount_mismatch");
-  for (const a of row.allocations)
-    if (!(await sourceCache(ctx, h, a.stripeTransferId)))
-      await cacheSource(ctx, h, a.stripeTransferId, counts);
+  for (const a of row.allocations) {
+    const source =
+      (await sourceCache(ctx, h, a.stripeTransferId)) ??
+      (await cacheSource(ctx, h, a.stripeTransferId, counts));
+    if ((source.allocationCurrency ?? source.currency) !== row.currency)
+      throw new CollectionError("allocation_currency_changed");
+  }
   const old = await ctx.db
     .query("payoutSnapshotClaims")
     .withIndex("by_snapshot_operation", (q) =>

package/src/component/payoutSnapshots/mutations.ts

@@ -183,6 +183,8 @@ export const advance = mutation({
             await cacheSource(ctx, h, event.key, counts);
           else if (event.kind === "claim")
             await cacheClaim(ctx, h, event.key, counts);
+          else if (event.kind === "liability")
+            throw new CollectionError("liability_changed");
           else if (event.kind === "fee")
             await cacheFee(ctx, h, event.key, counts);
           else patch.providerChanged = true;

package/src/component/payoutSnapshots/queries.ts

@@ -0,0 +1,102 @@
+import { v } from "convex/values";
+import { paginationOptsValidator } from "convex/server";
+import { paginator } from "convex-helpers/server/pagination";
+import { query } from "../_generated/server.js";
+import schema from "../schema.js";
+import { identity } from "./scope.js";
+import { snapshotDoc } from "./schema.js";
+import { ownedSnapshot } from "./localState.js";
+import { riskRevision } from "./revisions.js";
+import { transferDocValidator } from "../connect/validators.js";
+import { claimDoc } from "../payoutRelease/schema.js";
+import {
+  transferFingerprint,
+  payoutClaimFingerprint,
+} from "../payoutRelease/helpers.js";
+export const get = query({
+  args: identity,
+  returns: v.union(snapshotDoc, v.null()),
+  handler: ownedSnapshot,
+});
+const args = { ...identity, paginationOpts: paginationOptsValidator };
+const pageFields = { continueCursor: v.string(), isDone: v.boolean() };
+export const sources = query({
+  args,
+  returns: v.object({ ...pageFields, page: v.array(transferDocValidator) }),
+  handler: async (ctx, args) => {
+    const h = await ownedSnapshot(ctx, args);
+    if (
+      !h ||
+      !h.readOnly ||
+      h.phase !== "local_ready" ||
+      h.expiresAt <= Date.now() ||
+      (await riskRevision(ctx, h.accountId)) !== h.riskRevision
+    )
+      throw new Error(
+        "Payout collection is not ready for provider verification.",
+      );
+    if (
+      !Number.isInteger(args.paginationOpts.numItems) ||
+      args.paginationOpts.numItems < 1 ||
+      args.paginationOpts.numItems > 25
+    )
+      throw new Error("Invalid collection page.");
+    const page = await paginator(ctx.db, schema)
+      .query("payoutSnapshotSources")
+      .withIndex("by_snapshot", (q) => q.eq("snapshotId", h._id))
+      .paginate(args.paginationOpts);
+    const rows = [];
+    for (const cached of page.page) {
+      const row = await ctx.db
+        .query("transfers")
+        .withIndex("by_stripe_transfer_id", (q) =>
+          q.eq("stripeTransferId", cached.stripeTransferId),
+        )
+        .unique();
+      if (!row || transferFingerprint(row) !== cached.ledgerFingerprint)
+        throw new Error("Payout collection source changed.");
+      rows.push(row);
+    }
+    return { ...page, page: rows };
+  },
+});
+export const claims = query({
+  args,
+  returns: v.object({ ...pageFields, page: v.array(claimDoc) }),
+  handler: async (ctx, args) => {
+    const h = await ownedSnapshot(ctx, args);
+    if (
+      !h ||
+      !h.readOnly ||
+      h.phase !== "local_ready" ||
+      h.expiresAt <= Date.now() ||
+      (await riskRevision(ctx, h.accountId)) !== h.riskRevision
+    )
+      throw new Error(
+        "Payout collection is not ready for provider verification.",
+      );
+    if (
+      !Number.isInteger(args.paginationOpts.numItems) ||
+      args.paginationOpts.numItems < 1 ||
+      args.paginationOpts.numItems > 25
+    )
+      throw new Error("Invalid collection page.");
+    const page = await paginator(ctx.db, schema)
+      .query("payoutSnapshotClaims")
+      .withIndex("by_snapshot", (q) => q.eq("snapshotId", h._id))
+      .paginate(args.paginationOpts);
+    const rows = [];
+    for (const cached of page.page) {
+      const row = await ctx.db
+        .query("payoutReleaseClaims")
+        .withIndex("by_operation", (q) =>
+          q.eq("operationKey", cached.operationKey),
+        )
+        .unique();
+      if (!row || payoutClaimFingerprint(row) !== cached.fingerprint)
+        throw new Error("Payout collection claim changed.");
+      rows.push(row);
+    }
+    return { ...page, page: rows };
+  },
+});

package/src/component/payoutSnapshots/revisions.ts

@@ -120,6 +120,32 @@ function payoutFingerprint(p: Doc<"payouts">) {
 }
 /** Funding, payout claims and allocations commit with their revision counters. */
 export function registerPayoutRevisions(triggers: Triggers<DataModel>) {
+  triggers.register("recoveryBalances", async (ctx, change) => {
+    const fingerprint = (row: Doc<"recoveryBalances"> | null) =>
+      row
+        ? JSON.stringify([
+            row.accountId,
+            row.scopeKey,
+            row.currency,
+            row.amountDue,
+            row.collectedAmount,
+          ])
+        : null;
+    if (fingerprint(change.oldDoc) === fingerprint(change.newDoc)) return;
+    for (const account of new Set([
+      change.oldDoc?.accountId,
+      change.newDoc?.accountId,
+    ]))
+      if (account)
+        await bump(
+          ctx,
+          account,
+          true,
+          "liability",
+          (change.newDoc ?? change.oldDoc)!.scopeKey,
+          change.newDoc === null,
+        );
+  });
   triggers.register("transfers", async (ctx, change) => {
     if (
       change.oldDoc &&

package/src/component/payoutSnapshots/schema.ts

@@ -11,6 +11,7 @@ export const riskKind = v.union(
   v.literal("allocation"),
   v.literal("claim"),
   v.literal("fee"),
+  v.literal("liability"),
 );
 export const riskEventsTable = defineTable({
   accountId: v.string(),
@@ -32,6 +33,8 @@ export const collectionPhase = v.union(
 );
 export const snapshotFields = {
   readOnly: v.boolean(),
+  boundOperationKey: v.optional(v.string()),
+  boundRiskRevision: v.optional(v.number()),
   accountId: v.string(),
   ownerKey: v.string(),
   operationKey: v.string(),

package/src/component/payoutWorker/mutations.ts

@@ -180,7 +180,9 @@ export const finish = mutation({
     if (claim && claim.currency !== job.currency)
       throw new Error("Worker payout currency changed.");
     const retain =
-      claim?.status === "reserved" || claim?.status === "submitted";
+      args.reason === "collection_pending" ||
+      claim?.status === "reserved" ||
+      claim?.status === "submitted";
     await ctx.db.patch("payoutWorkerJobs", job._id, {
       operationKey: retain ? job.operationKey : undefined,
       hasOperation: retain,

package/src/react/workflows/payout-attempt-state.ts

@@ -18,6 +18,12 @@ const messages: Record<string, string> = {
     "No payout was requested because the supported available Stripe balance is insufficient.",
   schedule_drift:
     "Payout scheduling changed outside the application. Contact platform support to verify controls.",
+  collection_pending:
+    "Complete payout history is still being collected. This collection has not requested a new bank payout; the automatic worker will resume the same collection.",
+  collection_invalidated:
+    "Payout history changed during collection. A fresh assessment is required before funds can qualify.",
+  collection_requires_action:
+    "This account requires a server action to collect its complete payout history.",
   snapshot_limit:
     "History reconciliation is incomplete. No payout was requested from a partial balance.",
   policy_inactive:

package/src/react/workflows/payout-progress-state.ts

@@ -94,6 +94,12 @@ const reasons: Record<string, string> = {
   observations_stale: "Provider observations expired. Refresh the assessment.",
   expired:
     "The custom holding deadline has passed. Eligibility is unavailable until the payout schedule is restored and verified.",
+  collection_pending:
+    "Complete payout history is still being collected. This collection has not requested a new bank payout; the automatic worker will resume the same collection.",
+  collection_invalidated:
+    "Payout history changed during collection. A fresh assessment is required before funds can qualify.",
+  collection_requires_action:
+    "This account requires a server action to collect its complete payout history.",
   snapshot_limit:
     "This account needs continued history reconciliation before eligibility can be assessed.",
   policy_changed: "Payout settings changed. Refresh the assessment.",