@fantastic.dev/better-stripe 0.28.6 → 0.29.0

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.",