@fantastic.dev/better-stripe 0.21.0 → 0.23.0

package/src/component/payoutRelease/adoption.ts

@@ -0,0 +1,262 @@
+import { v, type Infer } from "convex/values";
+import type { MutationCtx } from "../_generated/server.js";
+import { scopeFields } from "../payoutPolicy/schema.js";
+import { readPolicy } from "../payoutPolicy/helpers.js";
+import { observation, allocation } from "./schema.js";
+import {
+  add,
+  checkSnapshot,
+  sourceById,
+  payoutClaimFingerprint,
+} from "./helpers.js";
+import { recordFees } from "./fees.js";
+export const historicalArgs = {
+  ...scopeFields,
+  expectedRevision: v.number(),
+  payout: v.object({
+    stripePayoutId: v.string(),
+    amount: v.number(),
+    currency: v.string(),
+    created: v.number(),
+    destinationId: v.string(),
+    status: v.union(v.literal("paid"), v.literal("returned")),
+    debitTransactionId: v.string(),
+    debitFee: v.number(),
+    returnTransactionId: v.optional(v.string()),
+    returnFee: v.optional(v.number()),
+  }),
+  allocations: v.array(allocation),
+  observations: v.array(observation),
+};
+type Args = {
+  [K in keyof typeof historicalArgs]: Infer<(typeof historicalArgs)[K]>;
+};
+/** Trusted package observations only. Provider history and historical maturity are verified upstream. */
+export async function adoptHistoricalPayout(ctx: MutationCtx, args: Args) {
+  const policy = await readPolicy(ctx, args);
+  if (!policy || policy.revision !== args.expectedRevision)
+    throw new Error("Historical payout policy revision changed.");
+  if (policy.mode !== "stripe_managed" || policy.status !== "ready")
+    throw new Error(
+      "Historical adoption requires an inactive automatic policy.",
+    );
+  const p = args.payout;
+  if (
+    !/^po_\w+$/.test(p.stripePayoutId) ||
+    !/^ba_\w+$/.test(p.destinationId) ||
+    !/^[a-z]{3}$/.test(p.currency) ||
+    !Number.isSafeInteger(p.amount) ||
+    p.amount <= 0 ||
+    !Number.isSafeInteger(p.created) ||
+    p.created < 0 ||
+    p.created * 1000 > Date.now() ||
+    !Number.isSafeInteger(p.created * 1000) ||
+    !/^txn_\w+$/.test(p.debitTransactionId) ||
+    !Number.isSafeInteger(p.debitFee) ||
+    p.debitFee < 0 ||
+    (p.status === "returned"
+      ? !p.returnTransactionId ||
+        !/^txn_\w+$/.test(p.returnTransactionId) ||
+        !Number.isSafeInteger(p.returnFee)
+      : p.returnTransactionId !== undefined || p.returnFee !== undefined)
+  )
+    throw new Error("Invalid historical payout receipt.");
+  const rows = await checkSnapshot(
+    ctx,
+    args.accountId,
+    args.observations,
+    true,
+  );
+  const byObservation = new Map(
+    args.observations.map((o) => [o.stripeTransferId, o]),
+  );
+  const seen = new Set<string>();
+  let total = 0;
+  const allocations = args.allocations
+    .map((a) => {
+      if (
+        !Number.isSafeInteger(a.amount) ||
+        a.amount <= 0 ||
+        seen.has(a.stripeTransferId) ||
+        !rows.has(a.stripeTransferId) ||
+        byObservation.get(a.stripeTransferId)?.currency !== p.currency
+      )
+        throw new Error("Invalid historical source allocation.");
+      seen.add(a.stripeTransferId);
+      total = add(total, a.amount);
+      const role = rows.get(a.stripeTransferId)!.role;
+      return {
+        stripeTransferId: a.stripeTransferId,
+        amount: a.amount,
+        ...(role ? { role } : {}),
+      };
+    })
+    .sort((a, b) => a.stripeTransferId.localeCompare(b.stripeTransferId));
+  if (total !== p.amount)
+    throw new Error(
+      "Historical source allocations do not equal payout principal.",
+    );
+  const operationKey = `bs:historical:${p.stripePayoutId}`;
+  const old = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_provider_payout", (q) =>
+      q.eq("stripePayoutId", p.stripePayoutId),
+    )
+    .unique();
+  if (old) {
+    if (
+      !old.historical ||
+      old.accountId !== args.accountId ||
+      old.ownerKey !== args.ownerKey ||
+      old.operationKey !== operationKey ||
+      old.currency !== p.currency ||
+      old.amount !== p.amount ||
+      old.destinationId !== p.destinationId ||
+      old.attemptedAt !== p.created * 1000 ||
+      old.status !== p.status ||
+      old.debitTransactionId !== p.debitTransactionId ||
+      old.debitFee !== p.debitFee ||
+      old.returnTransactionId !== p.returnTransactionId ||
+      old.providerFee !== add(p.debitFee, p.returnFee ?? 0) ||
+      JSON.stringify(
+        old.allocations.map((a) => [a.stripeTransferId, a.amount, a.role]),
+      ) !==
+        JSON.stringify(
+          allocations.map((a) => [a.stripeTransferId, a.amount, a.role]),
+        )
+    )
+      throw new Error(
+        "Historical payout identity or source allocation changed; reconcile existing outcomes.",
+      );
+    return old;
+  }
+  for (const status of ["reserved", "submitted"] as const) {
+    const unresolved = await ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_account_status", (q) =>
+        q.eq("accountId", args.accountId).eq("status", status),
+      )
+      .first();
+    if (unresolved)
+      throw new Error(
+        "Resolve existing payout attempts before historical adoption.",
+      );
+  }
+  const history = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
+    .take(100);
+  if (history.length >= 100)
+    throw new Error("Historical payout snapshot limit exceeded.");
+  for (const a of allocations) {
+    const source = await sourceById(ctx, a.stripeTransferId);
+    if (
+      source &&
+      (source.accountId !== args.accountId ||
+        source.ownerKey !== args.ownerKey ||
+        source.currency !== p.currency ||
+        source.reservedAmount !== 0)
+    )
+      throw new Error(
+        "Historical source allocation identity or reservations changed.",
+      );
+    const paid = p.status === "paid" ? a.amount : 0;
+    if (source)
+      await ctx.db.patch("payoutSourceAllocations", source._id, {
+        paidAmount: add(source.paidAmount, paid),
+      });
+    else
+      await ctx.db.insert("payoutSourceAllocations", {
+        accountId: args.accountId,
+        ownerKey: args.ownerKey,
+        stripeTransferId: a.stripeTransferId,
+        currency: p.currency,
+        paidAmount: paid,
+        reservedAmount: 0,
+      });
+  }
+  const id = await ctx.db.insert("payoutReleaseClaims", {
+    accountId: args.accountId,
+    ownerKey: args.ownerKey,
+    operationKey,
+    expectedRevision: args.expectedRevision,
+    historical: true,
+    currency: p.currency,
+    amount: p.amount,
+    destinationId: p.destinationId,
+    allocations,
+    observations: args.observations,
+    status: p.status,
+    attemptedAt: p.created * 1000,
+    stripePayoutId: p.stripePayoutId,
+    ...(p.returnTransactionId
+      ? { returnTransactionId: p.returnTransactionId }
+      : {}),
+  });
+  const claim = (await ctx.db.get("payoutReleaseClaims", id))!;
+  await recordFees(
+    ctx,
+    claim,
+    {
+      debitTransactionId: p.debitTransactionId,
+      debitFee: p.debitFee,
+      ...(p.returnFee !== undefined ? { returnFee: p.returnFee } : {}),
+    },
+    p.status === "returned",
+  );
+  return (await ctx.db.get("payoutReleaseClaims", id))!;
+}
+
+export const historicalBatchArgs = {
+  ...scopeFields,
+  expectedRevision: v.number(),
+  observations: v.array(observation),
+  expectedClaims: v.array(
+    v.object({ operationKey: v.string(), fingerprint: v.string() }),
+  ),
+  payouts: v.array(
+    v.object({
+      payout: historicalArgs.payout,
+      allocations: historicalArgs.allocations,
+    }),
+  ),
+};
+type BatchArgs = {
+  [K in keyof typeof historicalBatchArgs]: Infer<
+    (typeof historicalBatchArgs)[K]
+  >;
+};
+export async function adoptHistoricalBatch(ctx: MutationCtx, args: BatchArgs) {
+  if (!args.payouts.length || args.payouts.length > 100)
+    throw new Error("Invalid historical payout batch size.");
+  const rows = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
+    .take(101);
+  const expected = new Map(
+    args.expectedClaims.map((c) => [c.operationKey, c.fingerprint]),
+  );
+  if (
+    rows.length > 100 ||
+    expected.size !== args.expectedClaims.length ||
+    rows.length !== expected.size ||
+    rows.some(
+      (c) =>
+        c.ownerKey !== args.ownerKey ||
+        expected.get(c.operationKey) !== payoutClaimFingerprint(c),
+    )
+  )
+    throw new Error("Historical payout history snapshot changed.");
+  const claims = [];
+  for (const p of args.payouts)
+    claims.push(
+      await adoptHistoricalPayout(ctx, {
+        accountId: args.accountId,
+        ownerKey: args.ownerKey,
+        expectedRevision: args.expectedRevision,
+        observations: args.observations,
+        ...p,
+      }),
+    );
+  return { claims };
+}

package/src/component/payoutRelease/helpers.ts

@@ -166,3 +166,24 @@ export async function moveAllocations(
     });
   }
 }
+
+/** Stable financial identity for historical adoption and activation snapshots. */
+export function payoutClaimFingerprint(c: Doc<"payoutReleaseClaims">) {
+  return JSON.stringify([
+    c.accountId,
+    c.ownerKey,
+    c.operationKey,
+    c.historical ?? false,
+    c.currency,
+    c.amount,
+    c.status,
+    c.attemptedAt,
+    c.stripePayoutId,
+    c.destinationId,
+    c.debitTransactionId,
+    c.debitFee,
+    c.providerFee,
+    c.returnTransactionId,
+    c.allocations.map((a) => [a.stripeTransferId, a.amount, a.role]),
+  ]);
+}

package/src/component/payoutRelease/mutations.ts

@@ -1,3 +1,7 @@
+import {
+  historicalBatchArgs,
+  adoptHistoricalBatch as importHistoricalBatch,
+} from "./adoption.js";
 import { readFees, recordFees } from "./fees.js";
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
@@ -31,6 +35,7 @@ export const claim = mutation({
     ...identity,
     expectedRevision: v.number(),
     currency: v.string(),
+    destinationId: v.optional(v.string()),
     providerAvailable: v.number(),
     independentLiabilities: v.number(),
     observations: v.array(observation),
@@ -38,11 +43,17 @@ export const claim = mutation({
   returns: v.union(claimDoc, held),
   handler: async (ctx, args) => {
     validateIdentity(args);
+    if (
+      args.destinationId !== undefined &&
+      !/^ba_\w+$/.test(args.destinationId)
+    )
+      throw new Error("Invalid payout bank destination.");
     const existing = await claimByKey(ctx, args);
     if (existing) {
       if (
         existing.currency !== args.currency ||
-        existing.expectedRevision !== args.expectedRevision
+        existing.expectedRevision !== args.expectedRevision ||
+        existing.destinationId !== args.destinationId
       )
         throw new Error("Payout claim identity cannot be reused.");
       return existing;
@@ -122,6 +133,7 @@ export const claim = mutation({
       expectedRevision: args.expectedRevision,
       currency: args.currency,
       amount: plan.amount,
+      ...(args.destinationId ? { destinationId: args.destinationId } : {}),
       allocations: plan.allocations,
       observations: args.observations,
       feeRevision: fees?.revision ?? 0,
@@ -324,3 +336,9 @@ export const recordRejection = mutation({
     return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
   },
 });
+
+export const adoptHistoricalBatch = mutation({
+  args: historicalBatchArgs,
+  returns: v.object({ claims: v.array(claimDoc) }),
+  handler: importHistoricalBatch,
+});

package/src/component/payoutRelease/observation.ts

@@ -0,0 +1,10 @@
+import { v } from "convex/values";
+export const observation = v.object({
+  stripeTransferId: v.string(),
+  currency: v.string(),
+  matureNet: v.number(),
+  pendingCredits: v.number(),
+  ledgerFingerprint: v.string(),
+  observedAt: v.number(),
+  transactionIds: v.array(v.string()),
+});

package/src/component/payoutRelease/queries.ts

@@ -1,3 +1,4 @@
+import { transferDocValidator } from "../connect/validators.js";
 import { readFees } from "./fees.js";
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
@@ -65,3 +66,37 @@ export const fees = query({
     return { amount: balance?.amount ?? 0, revision: balance?.revision ?? 0 };
   },
 });
+
+/** Complete bounded input for package qualification. Partial membership never qualifies. */
+export const snapshot = query({
+  args: { accountId: v.string(), ownerKey: v.string() },
+  returns: v.union(
+    v.object({
+      status: v.literal("held"),
+      reason: v.literal("snapshot_limit"),
+    }),
+    v.object({
+      status: v.literal("ready"),
+      transfers: v.array(transferDocValidator),
+      claims: v.array(claimDoc),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    await readPolicy(ctx, args);
+    const transfers = await ctx.db
+      .query("transfers")
+      .withIndex("by_destination_account_id", (q) =>
+        q.eq("destinationAccountId", args.accountId),
+      )
+      .take(101);
+    const claims = await ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
+      .take(101);
+    if (transfers.length > 100 || claims.length > 100)
+      return { status: "held" as const, reason: "snapshot_limit" as const };
+    if (claims.some((c) => c.ownerKey !== args.ownerKey))
+      throw new Error("Payout history owner does not match.");
+    return { status: "ready" as const, transfers, claims };
+  },
+});

package/src/component/payoutRelease/schema.ts

@@ -1,15 +1,8 @@
 import { defineTable } from "convex/server";
 import { v } from "convex/values";
 import { scopeFields } from "../payoutPolicy/schema.js";
-export const observation = v.object({
-  stripeTransferId: v.string(),
-  currency: v.string(),
-  matureNet: v.number(),
-  pendingCredits: v.number(),
-  ledgerFingerprint: v.string(),
-  observedAt: v.number(),
-  transactionIds: v.array(v.string()),
-});
+import { observation } from "./observation.js";
+export { observation } from "./observation.js";
 export const allocation = v.object({
   stripeTransferId: v.string(),
   amount: v.number(),
@@ -19,10 +12,12 @@ export const allocation = v.object({
 });
 export const claimFields = {
   ...scopeFields,
+  historical: v.optional(v.boolean()),
   operationKey: v.string(),
   expectedRevision: v.number(),
   currency: v.string(),
   amount: v.number(),
+  destinationId: v.optional(v.string()),
   allocations: v.array(allocation),
   observations: v.array(observation),
   status: v.union(