@fantastic.dev/better-stripe 0.22.0 → 0.23.0

package/src/component/payoutPolicy/adoption.ts

@@ -0,0 +1,76 @@
+import type { Infer } from "convex/values";
+import type { MutationCtx } from "../_generated/server.js";
+import type { adoptionProof } from "./schema.js";
+import {
+  add,
+  checkSnapshot,
+  payoutClaimFingerprint,
+  sourceById,
+} from "../payoutRelease/helpers.js";
+import { readFees } from "../payoutRelease/fees.js";
+/** Package-authenticated provider proof, rechecked against all local financial state under OCC. */
+export async function validateAdoption(
+  ctx: MutationCtx,
+  scope: { accountId: string; ownerKey: string },
+  proof: Infer<typeof adoptionProof>,
+) {
+  await checkSnapshot(ctx, scope.accountId, proof.observations, true);
+  const rows = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_account_status", (q) => q.eq("accountId", scope.accountId))
+    .take(101);
+  const expected = new Map(
+    proof.claims.map((c) => [c.operationKey, c.fingerprint]),
+  );
+  if (
+    rows.length > 100 ||
+    expected.size !== proof.claims.length ||
+    rows.length !== expected.size ||
+    rows.some(
+      (c) =>
+        c.ownerKey !== scope.ownerKey ||
+        c.status === "reserved" ||
+        c.status === "submitted" ||
+        expected.get(c.operationKey) !== payoutClaimFingerprint(c),
+    )
+  )
+    throw new Error(
+      "Adoption payout history snapshot changed or is unresolved.",
+    );
+  const owed = new Map<string, number>();
+  for (const o of proof.observations) {
+    const source = await sourceById(ctx, o.stripeTransferId);
+    if (
+      source &&
+      (source.accountId !== scope.accountId ||
+        source.ownerKey !== scope.ownerKey ||
+        source.currency !== o.currency ||
+        source.reservedAmount !== 0)
+    )
+      throw new Error(
+        "Adoption source allocation identity or reservations changed.",
+      );
+    owed.set(
+      o.currency,
+      add(
+        owed.get(o.currency) ?? 0,
+        add(add(o.matureNet, o.pendingCredits), -(source?.paidAmount ?? 0)),
+      ),
+    );
+  }
+  let hasHeld = false;
+  for (const [currency, amount] of owed) {
+    const fees = await readFees(ctx, { ...scope, currency });
+    if (add(amount, -(fees?.amount ?? 0)) > 0) hasHeld = true;
+  }
+  if (
+    proof.oldestHeldAt !== undefined &&
+    (!Number.isSafeInteger(proof.oldestHeldAt) ||
+      proof.oldestHeldAt < 0 ||
+      proof.oldestHeldAt > Date.now())
+  )
+    throw new Error("Invalid adoption holding timestamp.");
+  if (hasHeld && proof.oldestHeldAt === undefined)
+    throw new Error("Adoption holding age is required for unpaid funds.");
+  return proof.oldestHeldAt ?? Date.now();
+}

package/src/component/payoutPolicy/mutations.ts

@@ -1,6 +1,8 @@
+import { validateAdoption } from "./adoption.js";
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
 import {
+  adoptionProof,
   prepareFields,
   operationDoc,
   scopeFields,
@@ -49,6 +51,7 @@ export const prepare = mutation({
         old.mode !== args.mode ||
         old.country !== args.country ||
         old.observedAt !== args.observedAt ||
+        Boolean(old.adoption) !== Boolean(args.adoption) ||
         !same(old.thresholds, args.thresholds) ||
         !same(old.observedSchedule, args.observedSchedule)
       )
@@ -84,6 +87,17 @@ export const prepare = mutation({
       args.observedSchedule.interval === "manual"
     )
       throw new Error("An existing manual schedule requires migration.");
+    let adoptedDeadline: number | undefined;
+    if (args.adoption) {
+      if (args.mode !== "custom" || policy?.mode !== "stripe_managed")
+        throw new Error(
+          "Adoption requires an owned automatic policy before custom activation.",
+        );
+      const anchor = await validateAdoption(ctx, args, args.adoption);
+      adoptedDeadline = anchor + days * 86400000;
+      if (adoptedDeadline <= Date.now())
+        throw new Error("Adoption holding deadline has already expired.");
+    }
     const previousSchedule =
       policy?.mode === "custom"
         ? policy.previousSchedule!
@@ -111,6 +125,7 @@ export const prepare = mutation({
       country: args.country,
       previousSchedule,
       holdDeadline:
+        adoptedDeadline ??
         policy?.holdDeadline ??
         (args.mode === "custom"
           ? (args.observedAt ?? Date.now()) + days * 86400000
@@ -139,6 +154,10 @@ export const confirm = mutation({
     if (!same(canonicalSchedule(args.observedSchedule), op.targetSchedule))
       throw new Error("Provider payout schedule was not confirmed.");
     if (op.status === "complete") return op;
+    if (op.adoption && !op.attempted)
+      throw new Error(
+        "Funded adoption requires a verified provider attempt before confirmation.",
+      );
     if (op.status === "canceled")
       throw new Error("Payout policy operation was canceled.");
     if (
@@ -162,7 +181,11 @@ export const confirm = mutation({
   },
 });
 export const beginAttempt = mutation({
-  args: { ...scopeFields, operationKey: v.string() },
+  args: {
+    ...scopeFields,
+    operationKey: v.string(),
+    adoption: v.optional(adoptionProof),
+  },
   returns: operationDoc,
   handler: async (ctx, args) => {
     const policy = await readPolicy(ctx, args);
@@ -179,8 +202,28 @@ export const beginAttempt = mutation({
       policy.status !== "changing"
     )
       throw new Error("Payout policy operation is not pending.");
-    if (!op.attempted)
-      await ctx.db.patch("payoutPolicyOperations", op._id, { attempted: true });
+    if (!op.attempted) {
+      if (Boolean(op.adoption) !== Boolean(args.adoption))
+        throw new Error(
+          "A fresh adoption proof is required for this operation.",
+        );
+      if (args.adoption) {
+        const anchor = await validateAdoption(ctx, args, args.adoption);
+        const deadline = Math.min(
+          policy.holdDeadline!,
+          anchor + holdingDays(op.country) * 86400000,
+        );
+        if (deadline <= Date.now())
+          throw new Error("Adoption holding deadline has already expired.");
+        await ctx.db.patch("payoutPolicies", policy._id, {
+          holdDeadline: deadline,
+        });
+      }
+      await ctx.db.patch("payoutPolicyOperations", op._id, {
+        attempted: true,
+        ...(args.adoption ? { adoption: args.adoption } : {}),
+      });
+    }
     return (await ctx.db.get("payoutPolicyOperations", op._id))!;
   },
 });

package/src/component/payoutPolicy/schema.ts

@@ -1,3 +1,4 @@
+import { observation } from "../payoutRelease/observation.js";
 import { defineTable } from "convex/server";
 import { v } from "convex/values";
 export const scopeFields = { accountId: v.string(), ownerKey: v.string() };
@@ -15,7 +16,15 @@ export const mode = v.union(v.literal("stripe_managed"), v.literal("custom"));
 export const thresholds = v.array(
   v.object({ currency: v.string(), amount: v.number() }),
 );
+export const adoptionProof = v.object({
+  observations: v.array(observation),
+  claims: v.array(
+    v.object({ operationKey: v.string(), fingerprint: v.string() }),
+  ),
+  oldestHeldAt: v.optional(v.number()),
+});
 export const prepareFields = {
+  adoption: v.optional(adoptionProof),
   ...scopeFields,
   operationKey: v.string(),
   expectedRevision: v.number(),

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";
@@ -332,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/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,6 +12,7 @@ export const allocation = v.object({
 });
 export const claimFields = {
   ...scopeFields,
+  historical: v.optional(v.boolean()),
   operationKey: v.string(),
   expectedRevision: v.number(),
   currency: v.string(),