@fantastic.dev/better-stripe 0.19.0 → 0.20.1

package/src/component/payoutRelease/allocation.ts

@@ -0,0 +1,147 @@
+export type PayoutFundingSource = {
+  stripeTransferId: string;
+  currency: string;
+  matureNet: number;
+  paidAmount: number;
+  reservedAmount: number;
+  pendingCredits: number;
+  role?: "store" | "affiliate" | "other";
+};
+export type PayoutAllocationOptions = {
+  currency: string;
+  threshold: number;
+  providerAvailable: number;
+  independentLiabilities: number;
+  sources: PayoutFundingSource[];
+};
+export type RecipientPayoutPlan = {
+  currency: string;
+  matureUnpaid: number;
+  pendingCredits: number;
+  /** Stripe does not expose a reliable numeric floor for every account. */
+  providerMinimum: null;
+} & (
+  | {
+      status: "held";
+      reason: "below_threshold" | "insufficient_available";
+      amount: 0;
+    }
+  | {
+      status: "qualified";
+      amount: number;
+      allocations: {
+        stripeTransferId: string;
+        amount: number;
+        role?: PayoutFundingSource["role"];
+      }[];
+    }
+);
+function money(value: number) {
+  if (!Number.isSafeInteger(value))
+    throw new Error("Unsafe payout arithmetic.");
+  return value;
+}
+function nonnegative(value: number) {
+  if (money(value) < 0) throw new Error("Invalid payout accounting amount.");
+}
+function currency(value: string) {
+  if (value.length !== 3 || !/^[a-z]{3}$/.test(value))
+    throw new Error("Invalid payout currency.");
+}
+/**
+ * Pure allocation step, not authorization to call Stripe. Inputs must be a
+ * complete, verified still-unpaid snapshot for this recipient. Policy controls,
+ * source ownership/maturity, prior payout adoption, independent liabilities and
+ * atomic reservations must be established by the execution boundary.
+ *
+ * Negative source entitlement survives refunds after payout. Pending credits
+ * never qualify. Each source's reservations reduce entitlement; they are not
+ * subtracted again from fresh provider availability, which may already include
+ * the provider debit for those same in-flight payouts.
+ */
+export function planRecipientPayout(
+  opts: PayoutAllocationOptions,
+): RecipientPayoutPlan {
+  currency(opts.currency);
+  if (money(opts.threshold) <= 0) throw new Error("Invalid payout threshold.");
+  money(opts.providerAvailable);
+  nonnegative(opts.independentLiabilities);
+  const seen = new Set<string>();
+  for (const source of opts.sources) {
+    if (
+      !/^tr_\w+$/.test(source.stripeTransferId) ||
+      source.stripeTransferId.trim() !== source.stripeTransferId ||
+      source.stripeTransferId.length > 100
+    )
+      throw new Error("Invalid payout source identity.");
+    if (seen.has(source.stripeTransferId))
+      throw new Error("Duplicate payout source.");
+    seen.add(source.stripeTransferId);
+    currency(source.currency);
+    money(source.matureNet);
+    nonnegative(source.paidAmount);
+    nonnegative(source.reservedAmount);
+    nonnegative(source.pendingCredits);
+    if (
+      source.role !== undefined &&
+      !["store", "affiliate", "other"].includes(source.role)
+    )
+      throw new Error("Invalid payout source role.");
+  }
+  const sources = opts.sources
+    .filter((source) => source.currency === opts.currency)
+    .sort((a, b) =>
+      a.stripeTransferId < b.stripeTransferId
+        ? -1
+        : a.stripeTransferId > b.stripeTransferId
+          ? 1
+          : 0,
+    );
+  let matureUnpaid = 0;
+  let pendingCredits = 0;
+  const credits = sources.map((source) => {
+    const unpaid = money(
+      money(source.matureNet - source.paidAmount) - source.reservedAmount,
+    );
+    matureUnpaid = money(matureUnpaid + unpaid);
+    pendingCredits = money(pendingCredits + source.pendingCredits);
+    return { source, unpaid };
+  });
+  const totals = {
+    currency: opts.currency,
+    matureUnpaid,
+    pendingCredits,
+    providerMinimum: null,
+  };
+  const providerAvailable = money(
+    opts.providerAvailable - opts.independentLiabilities,
+  );
+  if (matureUnpaid < opts.threshold)
+    return { ...totals, status: "held", reason: "below_threshold", amount: 0 };
+  const amount = Math.min(matureUnpaid, providerAvailable);
+  if (amount < opts.threshold)
+    return {
+      ...totals,
+      status: "held",
+      reason: "insufficient_available",
+      amount: 0,
+    };
+  let remaining = amount;
+  const allocations: Extract<
+    RecipientPayoutPlan,
+    { status: "qualified" }
+  >["allocations"] = [];
+  for (const { source, unpaid } of credits) {
+    const allocated = Math.min(Math.max(0, unpaid), remaining);
+    if (allocated) {
+      allocations.push({
+        stripeTransferId: source.stripeTransferId,
+        amount: allocated,
+        ...(source.role === undefined ? {} : { role: source.role }),
+      });
+      remaining = money(remaining - allocated);
+    }
+  }
+  if (remaining !== 0) throw new Error("Invalid payout source allocation.");
+  return { ...totals, status: "qualified", amount, allocations };
+}

package/src/component/payoutRelease/helpers.ts

@@ -0,0 +1,168 @@
+import type { Infer } from "convex/values";
+import type { transferDocValidator } from "../connect/validators.js";
+import type { MutationCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+import { readPolicy, validateScope } from "../payoutPolicy/helpers.js";
+import type { observation } from "./schema.js";
+import { addSummaryAmounts } from "../earnings/arithmetic.js";
+export const add = addSummaryAmounts;
+export function transferFingerprint(t: Infer<typeof transferDocValidator>) {
+  return JSON.stringify([
+    t.stripeTransferId,
+    t.destinationAccountId,
+    t.sourceChargeId,
+    t.amount,
+    t.currency,
+    t.role,
+    t.status,
+    t.reversedAmount ?? 0,
+    t.reversalClaimedAmount ?? 0,
+    t.reinstatement ?? false,
+  ]);
+}
+export function validateIdentity(args: {
+  accountId: string;
+  ownerKey: string;
+  operationKey: string;
+}) {
+  validateScope(args);
+  if (
+    !args.operationKey.trim() ||
+    args.operationKey.length > 180 ||
+    /[\r\n]/.test(args.operationKey)
+  )
+    throw new Error("Invalid payout claim identity.");
+}
+export async function claimByKey(
+  ctx: MutationCtx,
+  args: { accountId: string; ownerKey: string; operationKey: string },
+) {
+  validateIdentity(args);
+  const claim = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_operation", (q) => q.eq("operationKey", args.operationKey))
+    .unique();
+  if (
+    claim &&
+    (claim.accountId !== args.accountId || claim.ownerKey !== args.ownerKey)
+  )
+    throw new Error("Payout claim identity does not match.");
+  return claim;
+}
+export async function readyPolicy(
+  ctx: MutationCtx,
+  args: { accountId: string; ownerKey: string; expectedRevision: number },
+) {
+  const policy = await readPolicy(ctx, args);
+  if (
+    !Number.isSafeInteger(args.expectedRevision) ||
+    policy?.revision !== args.expectedRevision ||
+    policy.mode !== "custom" ||
+    policy.status !== "ready" ||
+    !policy.holdDeadline ||
+    policy.holdDeadline <= Date.now()
+  )
+    throw new Error("Payout policy is not ready at this revision.");
+  return policy;
+}
+/** Full local account membership is checked under OCC before any reservation. */
+export async function checkSnapshot(
+  ctx: MutationCtx,
+  accountId: string,
+  observations: Infer<typeof observation>[],
+  fresh: boolean,
+) {
+  const rows = await ctx.db
+    .query("transfers")
+    .withIndex("by_destination_account_id", (q) =>
+      q.eq("destinationAccountId", accountId),
+    )
+    .take(101);
+  if (
+    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);
+  if (
+    allocated.length > 100 ||
+    allocated.some((source) => !byId.has(source.stripeTransferId))
+  )
+    throw new Error("Payout source allocation snapshot is incomplete.");
+  const receiptIds = new Set<string>();
+  for (const o of observations) {
+    const row = byId.get(o.stripeTransferId);
+    if (
+      !row ||
+      transferFingerprint(row) !== o.ledgerFingerprint ||
+      (row.status !== "paid" && row.status !== "reversed") ||
+      (row.reversalClaimedAmount ?? 0) > (row.reversedAmount ?? 0)
+    )
+      throw new Error("Payout source snapshot changed or is not ready.");
+    if (
+      fresh &&
+      (!Number.isSafeInteger(o.observedAt) ||
+        o.observedAt > Date.now() ||
+        o.observedAt < Date.now() - 30000)
+    )
+      throw new Error("Payout source observation is stale or in the future.");
+    if (
+      !o.transactionIds.length ||
+      o.transactionIds.length > 1000 ||
+      new Set(o.transactionIds).size !== o.transactionIds.length ||
+      o.transactionIds.some((id) => !/^txn_\w+$/.test(id) || id.trim() !== id)
+    )
+      throw new Error("Invalid payout source receipt identities.");
+    for (const id of o.transactionIds) {
+      if (receiptIds.has(id))
+        throw new Error("Duplicate payout source receipt.");
+      receiptIds.add(id);
+    }
+  }
+  return byId;
+}
+export async function sourceById(ctx: MutationCtx, stripeTransferId: string) {
+  return ctx.db
+    .query("payoutSourceAllocations")
+    .withIndex("by_transfer", (q) => q.eq("stripeTransferId", stripeTransferId))
+    .unique();
+}
+export async function moveAllocations(
+  ctx: MutationCtx,
+  claim: Doc<"payoutReleaseClaims">,
+  transition: "pay" | "release" | "return",
+) {
+  for (const allocation of claim.allocations) {
+    const source = await sourceById(ctx, allocation.stripeTransferId);
+    if (
+      !source ||
+      source.accountId !== claim.accountId ||
+      source.ownerKey !== claim.ownerKey ||
+      source.currency !== claim.currency
+    )
+      throw new Error("Payout source allocation identity changed.");
+    const reservedAmount = add(
+      source.reservedAmount,
+      transition === "return" ? 0 : -allocation.amount,
+    );
+    const paidAmount = add(
+      source.paidAmount,
+      transition === "pay"
+        ? allocation.amount
+        : transition === "return"
+          ? -allocation.amount
+          : 0,
+    );
+    if (reservedAmount < 0 || paidAmount < 0)
+      throw new Error("Payout source allocation underflow.");
+    await ctx.db.patch("payoutSourceAllocations", source._id, {
+      reservedAmount,
+      paidAmount,
+    });
+  }
+}

package/src/component/payoutRelease/mutations.ts

@@ -0,0 +1,309 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import { identity, observation, claimDoc } from "./schema.js";
+import {
+  claimByKey,
+  readyPolicy,
+  checkSnapshot,
+  sourceById,
+  moveAllocations,
+  validateIdentity,
+  add,
+} from "./helpers.js";
+import { planRecipientPayout, type PayoutFundingSource } from "./allocation.js";
+const held = v.object({
+  status: v.literal("held"),
+  reason: v.union(
+    v.literal("below_threshold"),
+    v.literal("insufficient_available"),
+    v.literal("pending_claim"),
+  ),
+  amount: v.literal(0),
+  matureUnpaid: v.optional(v.number()),
+  pendingCredits: v.optional(v.number()),
+  currency: v.string(),
+  providerMinimum: v.null(),
+});
+/** Trusted server package boundary only: provider observations are verified upstream. Not a Stripe executor. */
+export const claim = mutation({
+  args: {
+    ...identity,
+    expectedRevision: v.number(),
+    currency: v.string(),
+    providerAvailable: v.number(),
+    independentLiabilities: v.number(),
+    observations: v.array(observation),
+  },
+  returns: v.union(claimDoc, held),
+  handler: async (ctx, args) => {
+    validateIdentity(args);
+    const existing = await claimByKey(ctx, args);
+    if (existing) {
+      if (
+        existing.currency !== args.currency ||
+        existing.expectedRevision !== args.expectedRevision
+      )
+        throw new Error("Payout claim identity cannot be reused.");
+      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) =>
+        q.eq("accountId", args.accountId).eq("status", "reserved"),
+      )
+      .first();
+    if (pending)
+      return {
+        status: "held" as const,
+        reason: "pending_claim" as const,
+        amount: 0 as const,
+        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 plan = planRecipientPayout({
+      currency: args.currency,
+      threshold: minimum.amount,
+      providerAvailable: args.providerAvailable,
+      independentLiabilities: args.independentLiabilities,
+      sources,
+    });
+    if (plan.status === "held") return plan;
+    for (const allocation of plan.allocations) {
+      const prior = await sourceById(ctx, allocation.stripeTransferId);
+      if (prior)
+        await ctx.db.patch("payoutSourceAllocations", prior._id, {
+          reservedAmount: add(prior.reservedAmount, allocation.amount),
+        });
+      else
+        await ctx.db.insert("payoutSourceAllocations", {
+          accountId: args.accountId,
+          ownerKey: args.ownerKey,
+          stripeTransferId: allocation.stripeTransferId,
+          currency: args.currency,
+          paidAmount: 0,
+          reservedAmount: allocation.amount,
+        });
+    }
+    const id = await ctx.db.insert("payoutReleaseClaims", {
+      accountId: args.accountId,
+      ownerKey: args.ownerKey,
+      operationKey: args.operationKey,
+      expectedRevision: args.expectedRevision,
+      currency: args.currency,
+      amount: plan.amount,
+      allocations: plan.allocations,
+      observations: args.observations,
+      status: "reserved",
+    });
+    return (await ctx.db.get("payoutReleaseClaims", id))!;
+  },
+});
+export const beginAttempt = mutation({
+  args: identity,
+  returns: claimDoc,
+  handler: async (ctx, args) => {
+    const claim = await claimByKey(ctx, args);
+    if (!claim || claim.status !== "reserved")
+      throw new Error("Payout claim is not reserved.");
+    if (claim.attemptedAt !== undefined) return claim;
+    await readyPolicy(ctx, claim);
+    await checkSnapshot(ctx, claim.accountId, claim.observations, true);
+    await ctx.db.patch("payoutReleaseClaims", claim._id, {
+      attemptedAt: Date.now(),
+    });
+    return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
+  },
+});
+export const cancelUnattempted = mutation({
+  args: identity,
+  returns: claimDoc,
+  handler: async (ctx, args) => {
+    const claim = await claimByKey(ctx, args);
+    if (
+      !claim ||
+      claim.attemptedAt !== undefined ||
+      (claim.status !== "reserved" && claim.status !== "canceled")
+    )
+      throw new Error("An attempted payout claim cannot be canceled.");
+    if (claim.status === "canceled") return claim;
+    await moveAllocations(ctx, claim, "release");
+    await ctx.db.patch("payoutReleaseClaims", claim._id, {
+      status: "canceled",
+    });
+    return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
+  },
+});
+export const recordOutcome = mutation({
+  args: {
+    ...identity,
+    stripePayoutId: v.string(),
+    amount: v.number(),
+    currency: v.string(),
+    providerStatus: v.union(
+      v.literal("pending"),
+      v.literal("in_transit"),
+      v.literal("paid"),
+      v.literal("failed"),
+      v.literal("canceled"),
+    ),
+    returnTransactionId: v.optional(v.string()),
+  },
+  returns: claimDoc,
+  handler: async (ctx, args) => {
+    const claim = await claimByKey(ctx, args);
+    if (
+      !claim ||
+      claim.attemptedAt === undefined ||
+      claim.status === "canceled" ||
+      claim.status === "rejected"
+    )
+      throw new Error("Payout receipt has no attempted claim.");
+    if (
+      !/^po_\w+$/.test(args.stripePayoutId) ||
+      args.stripePayoutId.trim() !== args.stripePayoutId ||
+      args.currency !== claim.currency ||
+      args.amount !== claim.amount ||
+      (claim.stripePayoutId !== undefined &&
+        claim.stripePayoutId !== args.stripePayoutId)
+    )
+      throw new Error("Payout receipt identity or amount does not match.");
+    const adopted = await ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_provider_payout", (q) =>
+        q.eq("stripePayoutId", args.stripePayoutId),
+      )
+      .unique();
+    if (adopted && adopted._id !== claim._id)
+      throw new Error("Payout receipt identity is already allocated.");
+    if (
+      args.returnTransactionId !== undefined &&
+      (!/^txn_\w+$/.test(args.returnTransactionId) ||
+        args.returnTransactionId.trim() !== args.returnTransactionId)
+    )
+      throw new Error("Invalid payout return receipt identity.");
+    const returned =
+      (args.providerStatus === "failed" ||
+        args.providerStatus === "canceled") &&
+      args.returnTransactionId !== undefined;
+    if (returned) {
+      const adoptedReturn = await ctx.db
+        .query("payoutReleaseClaims")
+        .withIndex("by_return_receipt", (q) =>
+          q.eq("returnTransactionId", args.returnTransactionId),
+        )
+        .unique();
+      if (adoptedReturn && adoptedReturn._id !== claim._id)
+        throw new Error("Payout return receipt is already allocated.");
+    }
+    if (claim.status === "returned") {
+      if (returned && args.returnTransactionId !== claim.returnTransactionId)
+        throw new Error("Payout return receipt identity changed.");
+      return claim;
+    }
+    if (returned) {
+      await moveAllocations(
+        ctx,
+        claim,
+        claim.status === "paid" ? "return" : "release",
+      );
+      await ctx.db.patch("payoutReleaseClaims", claim._id, {
+        status: "returned",
+        stripePayoutId: args.stripePayoutId,
+        returnTransactionId: args.returnTransactionId,
+      });
+    } else if (args.providerStatus === "paid" && claim.status !== "paid") {
+      await moveAllocations(ctx, claim, "pay");
+      await ctx.db.patch("payoutReleaseClaims", claim._id, {
+        status: "paid",
+        stripePayoutId: args.stripePayoutId,
+      });
+    } else if (claim.status !== "paid") {
+      await ctx.db.patch("payoutReleaseClaims", claim._id, {
+        status: "submitted",
+        stripePayoutId: args.stripePayoutId,
+      });
+    }
+    return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
+  },
+});
+
+/** Only a verified, no-object rejection within the original idempotency window. */
+export const recordRejection = mutation({
+  args: {
+    ...identity,
+    requestId: v.string(),
+    code: v.union(
+      v.literal("balance_insufficient"),
+      v.literal("amount_too_small"),
+    ),
+  },
+  returns: claimDoc,
+  handler: async (ctx, args) => {
+    const claim = await claimByKey(ctx, args);
+    if (
+      !claim ||
+      !/^req_\w+$/.test(args.requestId) ||
+      args.requestId.trim() !== args.requestId
+    )
+      throw new Error("Invalid payout rejection receipt.");
+    if (claim.status === "rejected") {
+      if (
+        claim.rejection?.requestId !== args.requestId ||
+        claim.rejection.code !== args.code
+      )
+        throw new Error("Payout rejection receipt identity changed.");
+      return claim;
+    }
+    if (
+      claim.status !== "reserved" ||
+      claim.stripePayoutId ||
+      claim.attemptedAt === undefined ||
+      Date.now() - claim.attemptedAt >= 23 * 60 * 60 * 1000
+    )
+      throw new Error(
+        "An accepted or uncertain expired payout attempt cannot be released as a rejection.",
+      );
+    const adoptedRejection = await ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_rejection_request", (q) =>
+        q.eq("rejection.requestId", args.requestId),
+      )
+      .unique();
+    if (adoptedRejection && adoptedRejection._id !== claim._id)
+      throw new Error("Payout rejection receipt is already allocated.");
+    await moveAllocations(ctx, claim, "release");
+    await ctx.db.patch("payoutReleaseClaims", claim._id, {
+      status: "rejected",
+      rejection: { requestId: args.requestId, code: args.code },
+    });
+    return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
+  },
+});

package/src/component/payoutRelease/queries.ts

@@ -0,0 +1,56 @@
+import { paginationOptsValidator } from "convex/server";
+import { v } from "convex/values";
+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 get = query({
+  args: identity,
+  returns: v.union(claimDoc, v.null()),
+  handler: async (ctx, args) => {
+    validateIdentity(args);
+    await readPolicy(ctx, args);
+    const claim = await ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_operation", (q) => q.eq("operationKey", args.operationKey))
+      .unique();
+    if (
+      claim &&
+      (claim.accountId !== args.accountId || claim.ownerKey !== args.ownerKey)
+    )
+      throw new Error("Payout claim identity does not match.");
+    return claim;
+  },
+});
+export const pending = query({
+  args: {
+    accountId: v.string(),
+    ownerKey: v.string(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: v.object({
+    page: v.array(claimDoc),
+    continueCursor: v.string(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    await readPolicy(ctx, args);
+    if (
+      !Number.isInteger(args.paginationOpts.numItems) ||
+      args.paginationOpts.numItems < 1 ||
+      args.paginationOpts.numItems > 100
+    )
+      throw new Error("Invalid payout claim page.");
+    const result = await ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_account_status", (q) =>
+        q.eq("accountId", args.accountId).eq("status", "reserved"),
+      )
+      .paginate(args.paginationOpts);
+    return {
+      page: result.page,
+      continueCursor: result.continueCursor,
+      isDone: result.isDone,
+    };
+  },
+});