@fantastic.dev/better-stripe 0.23.1 → 0.24.0

package/src/component/connect/reversalReceipts.ts

@@ -0,0 +1,147 @@
+import { updateObligation } from "../affiliateRecovery/accounting.js";
+import { v } from "convex/values";
+import type { Doc } from "../_generated/dataModel.js";
+import type { MutationCtx } from "../_generated/server.js";
+import { deriveReversalState } from "../lib/reversals.js";
+
+async function recordCommissionReceipt(
+  ctx: MutationCtx,
+  transfer: Doc<"transfers">,
+  reversedAmount: number,
+  receipt: { stripeReversalId: string; operationId: string; amount: number },
+) {
+  const op = await ctx.db
+    .query("transferReversalOps")
+    .withIndex("by_operation_id", (q) =>
+      q.eq("operationId", receipt.operationId),
+    )
+    .unique();
+  const slice = op?.slices.find(
+    (s) => s.stripeTransferId === transfer.stripeTransferId,
+  );
+  if (
+    transfer.role !== "affiliate" ||
+    !op?.commissionExposure ||
+    !slice ||
+    receipt.amount !== slice.to - slice.from ||
+    reversedAmount !== slice.to ||
+    !receipt.stripeReversalId
+  )
+    throw new Error(
+      "Commission reversal receipt does not match its reserved operation.",
+    );
+  const priorOperationReceipt = await ctx.db
+    .query("affiliateReversalReceipts")
+    .withIndex("by_transfer_operation", (q) =>
+      q
+        .eq("stripeTransferId", transfer.stripeTransferId)
+        .eq("operationId", receipt.operationId),
+    )
+    .unique();
+  if (
+    priorOperationReceipt &&
+    priorOperationReceipt.stripeReversalId !== receipt.stripeReversalId
+  )
+    throw new Error(
+      "Commission operation already has a different reversal receipt.",
+    );
+  const existing = await ctx.db
+    .query("affiliateReversalReceipts")
+    .withIndex("by_receipt", (q) =>
+      q.eq("stripeReversalId", receipt.stripeReversalId),
+    )
+    .unique();
+  if (existing) {
+    if (
+      existing.stripeTransferId !== transfer.stripeTransferId ||
+      existing.operationId !== receipt.operationId ||
+      existing.amount !== receipt.amount
+    )
+      throw new Error("Commission reversal receipt identity cannot change.");
+  } else {
+    await ctx.db.insert("affiliateReversalReceipts", {
+      ...receipt,
+      stripeTransferId: transfer.stripeTransferId,
+    });
+  }
+}
+
+export const recordTransferReversalDefinition = {
+  args: {
+    stripeTransferId: v.string(),
+    reversedAmount: v.number(),
+    receipt: v.optional(
+      v.object({
+        stripeReversalId: v.string(),
+        operationId: v.string(),
+        amount: v.number(),
+      }),
+    ),
+  },
+  returns: v.null(),
+  handler: async (
+    ctx: MutationCtx,
+    args: {
+      stripeTransferId: string;
+      reversedAmount: number;
+      receipt?: {
+        stripeReversalId: string;
+        operationId: string;
+        amount: number;
+      };
+    },
+  ) => {
+    const transfer = await ctx.db
+      .query("transfers")
+      .withIndex("by_stripe_transfer_id", (q) =>
+        q.eq("stripeTransferId", args.stripeTransferId),
+      )
+      .first();
+
+    if (!transfer) {
+      throw new Error(
+        `Cannot record reversal: no transfer found for ${args.stripeTransferId}`,
+      );
+    }
+
+    // `reversedAmount` is a cumulative total (matches Stripe's
+    // `Transfer.amount_reversed`). Keep it monotonic so a stale/out-of-order
+    // event can't shrink it or undo a full reversal.
+    const reversedAmount = Math.max(
+      transfer.reversedAmount ?? 0,
+      args.reversedAmount,
+    );
+    const derived = deriveReversalState(
+      transfer.amount,
+      reversedAmount,
+      transfer.status,
+    );
+
+    if (
+      !Number.isSafeInteger(reversedAmount) ||
+      reversedAmount < 0 ||
+      reversedAmount > transfer.amount
+    )
+      throw new Error("Invalid confirmed transfer reversal amount.");
+    if (args.receipt)
+      await recordCommissionReceipt(
+        ctx,
+        transfer,
+        args.reversedAmount,
+        args.receipt,
+      );
+    await ctx.db.patch("transfers", transfer._id, derived);
+    const obligation = await ctx.db
+      .query("affiliateObligations")
+      .withIndex("by_transfer", (q) =>
+        q.eq("stripeTransferId", args.stripeTransferId),
+      )
+      .unique();
+    if (obligation)
+      await updateObligation(ctx, obligation, {
+        recoveredAmount: reversedAmount,
+      });
+
+    return null;
+  },
+};

package/src/component/connect/schema.ts

@@ -90,9 +90,9 @@ export const transfersTable = defineTable({
  * delivery replays byte-identical Stripe requests instead of recomputing
  * amounts from mutable ledger state.
  */
-export const transferReversalOpsTable = defineTable(
-  transferReversalOpFields,
-).index("by_operation_id", ["operationId"]);
+export const transferReversalOpsTable = defineTable(transferReversalOpFields)
+  .index("by_operation_id", ["operationId"])
+  .index("by_source_charge", ["sourceChargeId"]);
 
 /**
  * Disputes (chargebacks). Same indexing strategy as refunds.

package/src/component/connect/validators.ts

@@ -1,3 +1,4 @@
+import { commissionExposureValidator } from "../settlement/clawbackSchema.js";
 import { type Infer, v } from "convex/values";
 
 import { feeRoutingFields, splitRecipientRoleValidator } from "../lib/fees";
@@ -305,6 +306,7 @@ export const transferReversalOpFields = {
   operationId: v.string(),
   sourceChargeId: v.string(),
   slices: v.array(reversalSliceValidator),
+  commissionExposure: v.optional(commissionExposureValidator),
 };
 
 /** Full `transferReversalOps` document, including system fields. */

package/src/component/payout-recovery-integration.test.ts

@@ -0,0 +1,172 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "./schema.js";
+import { changeBalance } from "./affiliateRecovery/accounting.js";
+import { transferFingerprint } from "./payoutRelease/helpers.js";
+const modules = import.meta.glob("./**/*.*s");
+const m = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutRelease/mutations:${name}`);
+const pm = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutPolicy/mutations:${name}`);
+const scope = { accountId: "acct_recipient", ownerKey: "user_1" };
+const transfer = (
+  stripeTransferId: string,
+  amount: number,
+  role = "store",
+) => ({
+  stripeTransferId,
+  destinationAccountId: scope.accountId,
+  amount,
+  currency: "usd",
+  status: "paid",
+  role,
+});
+async function setup() {
+  const t = convexTest(schema, modules);
+  await t.mutation(pm("prepare"), {
+    ...scope,
+    operationKey: "enable",
+    expectedRevision: -1,
+    mode: "custom",
+    thresholds: [{ currency: "usd", amount: 1000 }],
+    country: "US",
+    observedSchedule: { interval: "daily" },
+  });
+  await t.mutation(pm("confirm"), {
+    ...scope,
+    operationKey: "enable",
+    observedSchedule: { interval: "manual" },
+  });
+  for (const row of [
+    transfer("tr_creator", 600),
+    transfer("tr_affiliate", 400, "affiliate"),
+  ])
+    await t.mutation(
+      makeFunctionReference<"mutation">("connect/mutations:upsertTransfer"),
+      row,
+    );
+  const rows = await t.run(async (ctx) => ctx.db.query("transfers").take(10));
+  const args = {
+    ...scope,
+    operationKey: "release-1",
+    expectedRevision: 0,
+    currency: "usd",
+    providerAvailable: 1000,
+    independentLiabilities: 0,
+    observations: rows.map((row) => ({
+      stripeTransferId: row.stripeTransferId,
+      matureNet: row.amount,
+      pendingCredits: 0,
+      currency: row.currency,
+      ledgerFingerprint: transferFingerprint(row),
+      observedAt: Date.now(),
+      transactionIds: [`txn_${row.stripeTransferId}`],
+    })),
+  };
+  return { t, args };
+}
+it("blocks combined payouts on affiliate debt in the payout currency", async () => {
+  const { t, args } = await setup();
+  await t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  await expect(t.mutation(m("claim"), args)).rejects.toThrow(/recovery/);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+  ).toEqual([]);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toEqual([]);
+});
+
+it("keeps independent currency debts out of a verified payout", async () => {
+  const { t, args } = await setup();
+  await t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "eur", { outstandingDebt: 100 }),
+  );
+  expect(await t.mutation(m("claim"), args)).toMatchObject({
+    status: "reserved",
+    amount: 1000,
+  });
+});
+
+it("shares one reservation between direct and combined payout paths", async () => {
+  const { t, args } = await setup();
+  await t.run((ctx) => changeBalance(ctx, scope.accountId, "usd", {}));
+  const direct = () =>
+    t.mutation(
+      makeFunctionReference<"mutation">(
+        "affiliatePayouts/mutations:reservePayout",
+      ),
+      {
+        affiliateAccountId: scope.accountId,
+        currency: "usd",
+        amount: 1000,
+        minimumAmount: 1,
+        operationKey: "direct",
+        now: Date.now(),
+      },
+    );
+  const outcomes = await Promise.allSettled([
+    t.mutation(m("claim"), args),
+    direct(),
+  ]);
+  expect(
+    outcomes.filter((result) => result.status === "fulfilled"),
+  ).toHaveLength(1);
+  expect(
+    outcomes.filter((result) => result.status === "rejected"),
+  ).toHaveLength(1);
+});
+
+it("rechecks new debt immediately before the provider attempt and permits safe cancellation", async () => {
+  const { t, args } = await setup();
+  await t.mutation(m("claim"), args);
+  await t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  const identity = { ...scope, operationKey: args.operationKey };
+  await expect(t.mutation(m("beginAttempt"), identity)).rejects.toThrow(
+    /recovery/,
+  );
+  await t.mutation(m("cancelUnattempted"), identity);
+  expect(
+    await t.run((ctx) => ctx.db.query("affiliateRecoveryBalances").first()),
+  ).toMatchObject({
+    outstandingDebt: 100,
+    pendingPayoutAmount: 0,
+  });
+});
+
+it("holds unknown payout attempts until a verified receipt, without erasing later debt", async () => {
+  const { t, args } = await setup();
+  await t.mutation(m("claim"), args);
+  const identity = { ...scope, operationKey: args.operationKey };
+  await t.mutation(m("beginAttempt"), identity);
+  await t.run((ctx) =>
+    changeBalance(ctx, scope.accountId, "usd", { outstandingDebt: 100 }),
+  );
+  const before = await t.run((ctx) =>
+    ctx.db.query("affiliateRecoveryBalances").first(),
+  );
+  expect(before?.activePayoutKey).toBe(
+    `bs:recipient-payout:${args.operationKey}`,
+  );
+  await expect(t.mutation(m("cancelUnattempted"), identity)).rejects.toThrow(
+    /attempt/,
+  );
+  await t.mutation(m("recordOutcome"), {
+    ...identity,
+    stripePayoutId: "po_verified",
+    amount: 1000,
+    currency: "usd",
+    providerStatus: "pending",
+  });
+  const after = await t.run((ctx) =>
+    ctx.db.query("affiliateRecoveryBalances").first(),
+  );
+  expect(after?.activePayoutKey).toBeUndefined();
+  expect(after?.outstandingDebt).toBe(100);
+});

package/src/component/payout-sync.test.ts

@@ -0,0 +1,117 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it, vi } from "vitest";
+import schema from "./schema.js";
+const modules = import.meta.glob("./**/*.*s");
+const scope = { stripePayoutId: "po_one", accountId: "acct_owner" };
+const payout = {
+  ...scope,
+  amount: 500,
+  currency: "jpy",
+  status: "paid" as const,
+  arrivalDate: "1970-01-01T00:03:20.000Z",
+  method: "standard",
+  metadata: {},
+};
+const mutation = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutSync/mutations:${name}`);
+async function setup() {
+  const t = convexTest(schema, modules);
+  const generation = await t.mutation(mutation("begin"), scope);
+  return { t, args: { ...scope, generation, payout } };
+}
+it("replays a committed generation without changing its acceptance time or financial row", async () => {
+  vi.useFakeTimers();
+  try {
+    vi.setSystemTime(1000);
+    const { t, args } = await setup();
+    const first = await t.mutation(mutation("finish"), args);
+    const oldRow = await t.run((ctx) => ctx.db.query("payouts").unique());
+    vi.setSystemTime(2000);
+    expect(await t.mutation(mutation("finish"), args)).toMatchObject({
+      ...first,
+      changed: false,
+    });
+    expect(
+      await t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+    ).toMatchObject({ acceptedAt: 1000 });
+    expect(await t.run((ctx) => ctx.db.query("payouts").unique())).toEqual(
+      oldRow,
+    );
+  } finally {
+    vi.useRealTimers();
+  }
+});
+it("rejects replacing the accepted snapshot under the same generation", async () => {
+  const { t, args } = await setup();
+  await t.mutation(mutation("finish"), args);
+  await expect(
+    t.mutation(mutation("finish"), {
+      ...args,
+      payout: { ...payout, status: "pending" },
+    }),
+  ).rejects.toThrow("An accepted payout observation cannot be replaced.");
+  expect(await t.run((ctx) => ctx.db.query("payouts").unique())).toMatchObject({
+    status: "paid",
+  });
+});
+it("ignores stale completion and stale unknown markers before any financial write", async () => {
+  const { t, args } = await setup();
+  const generation = await t.mutation(mutation("begin"), scope);
+  expect(await t.mutation(mutation("finish"), args)).toMatchObject({
+    status: "superseded",
+  });
+  await t.mutation(mutation("markUnknown"), {
+    ...scope,
+    generation: args.generation,
+  });
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+  ).toMatchObject({ status: "pending", generation });
+  expect(await t.run((ctx) => ctx.db.query("payouts").collect())).toEqual([]);
+  await t.mutation(mutation("finish"), { ...args, generation });
+  await t.mutation(mutation("markUnknown"), { ...scope, generation });
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+  ).toMatchObject({ status: "accepted" });
+});
+it.each([{ stripePayoutId: "po_foreign" }, { accountId: "acct_foreign" }])(
+  "rejects snapshot identity mismatch %j atomically",
+  async (patch) => {
+    const { t, args } = await setup();
+    await expect(
+      t.mutation(mutation("finish"), {
+        ...args,
+        payout: { ...payout, ...patch },
+      }),
+    ).rejects.toThrow(
+      "Payout synchronization snapshot identity does not match.",
+    );
+    expect(await t.run((ctx) => ctx.db.query("payouts").collect())).toEqual([]);
+    expect(
+      await t.run((ctx) => ctx.db.query("currencyTotals").collect()),
+    ).toEqual([]);
+  },
+);
+it("rejects a foreign claim lookup and generation overflow without changing the claim", async () => {
+  const { t } = await setup();
+  await expect(
+    t.query(makeFunctionReference<"query">("payoutSync/queries:get"), {
+      ...scope,
+      accountId: "acct_foreign",
+    }),
+  ).rejects.toThrow("Payout synchronization account does not match.");
+  await t.run(async (ctx) => {
+    const row = await ctx.db.query("payoutSyncClaims").unique();
+    await ctx.db.patch("payoutSyncClaims", row!._id, {
+      generation: Number.MAX_SAFE_INTEGER,
+    });
+  });
+  await expect(t.mutation(mutation("begin"), scope)).rejects.toThrow(
+    "Payout synchronization generation exhausted.",
+  );
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSyncClaims").unique()),
+  ).toMatchObject({ generation: Number.MAX_SAFE_INTEGER });
+});

package/src/component/payoutRelease/mutations.ts

@@ -1,3 +1,7 @@
+import {
+  reserveRecoveryGuard,
+  releaseRecoveryGuard,
+} from "../affiliatePayouts/recipientGuard.js";
 import {
   historicalBatchArgs,
   adoptHistoricalBatch as importHistoricalBatch,
@@ -110,6 +114,7 @@ export const claim = mutation({
       sources,
     });
     if (plan.status === "held") return plan;
+    await reserveRecoveryGuard(ctx, args, plan.amount);
     for (const allocation of plan.allocations) {
       const prior = await sourceById(ctx, allocation.stripeTransferId);
       if (prior)
@@ -155,6 +160,7 @@ export const beginAttempt = mutation({
     if (feeRevision !== (claim.feeRevision ?? 0))
       throw new Error("Payout fee revision changed after reservation.");
     await checkSnapshot(ctx, claim.accountId, claim.observations, true);
+    await reserveRecoveryGuard(ctx, claim, claim.amount);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       attemptedAt: Date.now(),
     });
@@ -174,6 +180,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 releaseRecoveryGuard(ctx, claim);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       status: "canceled",
     });
@@ -257,6 +264,7 @@ export const recordOutcome = mutation({
     if (claim.status === "paid" && args.providerStatus !== "paid" && !returned)
       return claim;
     await recordFees(ctx, claim, args, returned);
+    await releaseRecoveryGuard(ctx, claim);
     if (returned) {
       await moveAllocations(
         ctx,
@@ -329,6 +337,7 @@ export const recordRejection = mutation({
     if (adoptedRejection && adoptedRejection._id !== claim._id)
       throw new Error("Payout rejection receipt is already allocated.");
     await moveAllocations(ctx, claim, "release");
+    await releaseRecoveryGuard(ctx, claim);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       status: "rejected",
       rejection: { requestId: args.requestId, code: args.code },

package/src/component/payoutRelease/queries.ts

@@ -1,3 +1,5 @@
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
 import { transferDocValidator } from "../connect/validators.js";
 import { readFees } from "./fees.js";
 import { paginationOptsValidator } from "convex/server";
@@ -43,7 +45,7 @@ export const pending = query({
       args.paginationOpts.numItems > 100
     )
       throw new Error("Invalid payout claim page.");
-    const result = await ctx.db
+    const result = await paginator(ctx.db, schema)
       .query("payoutReleaseClaims")
       .withIndex("by_account_status", (q) =>
         q.eq("accountId", args.accountId).eq("status", "reserved"),

package/src/component/payoutSync/helpers.ts

@@ -0,0 +1,86 @@
+import type { Infer } from "convex/values";
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+import { generateIdempotencyKey } from "../lib/idempotency.js";
+import type { snapshot } from "./validators.js";
+export function validateIdentity(args: {
+  stripePayoutId: string;
+  accountId: string;
+}) {
+  if (
+    !/^po_[A-Za-z0-9_]+$/.test(args.stripePayoutId) ||
+    args.stripePayoutId.length > 255 ||
+    (args.accountId !== "platform" &&
+      !/^acct_[A-Za-z0-9_]+$/.test(args.accountId)) ||
+    args.accountId.length > 255
+  )
+    throw new Error("Invalid payout synchronization identity.");
+}
+export async function claimByPayout(
+  ctx: QueryCtx | MutationCtx,
+  args: { stripePayoutId: string; accountId: string },
+) {
+  validateIdentity(args);
+  const claim = await ctx.db
+    .query("payoutSyncClaims")
+    .withIndex("by_stripe_payout_id", (q) =>
+      q.eq("stripePayoutId", args.stripePayoutId),
+    )
+    .unique();
+  if (claim && claim.accountId !== args.accountId)
+    throw new Error("Payout synchronization account does not match.");
+  return claim;
+}
+export async function payoutById(
+  ctx: QueryCtx | MutationCtx,
+  args: { stripePayoutId: string; accountId: string },
+) {
+  const payout = await ctx.db
+    .query("payouts")
+    .withIndex("by_stripe_payout_id", (q) =>
+      q.eq("stripePayoutId", args.stripePayoutId),
+    )
+    .unique();
+  if (payout && payout.accountId !== args.accountId)
+    throw new Error("Existing payout account does not match.");
+  return payout;
+}
+export function validateSnapshot(p: Infer<typeof snapshot>) {
+  validateIdentity(p);
+  if (
+    !Number.isSafeInteger(p.amount) ||
+    p.amount <= 0 ||
+    !/^[a-z]{3}$/.test(p.currency) ||
+    (p.method !== undefined && !["standard", "instant"].includes(p.method))
+  )
+    throw new Error("Invalid payout synchronization money or method.");
+  if (
+    p.arrivalDate !== undefined &&
+    (!Number.isFinite(Date.parse(p.arrivalDate)) ||
+      new Date(p.arrivalDate).toISOString() !== p.arrivalDate)
+  )
+    throw new Error("Invalid payout arrival date.");
+  if (
+    (p.failureCode !== undefined && p.failureCode.length > 255) ||
+    (p.failureMessage !== undefined && p.failureMessage.length > 4096)
+  )
+    throw new Error("Invalid payout failure detail.");
+}
+export async function fingerprint(p: Infer<typeof snapshot> | Doc<"payouts">) {
+  return generateIdempotencyKey("payout-sync", {
+    snapshot: [
+      p.stripePayoutId,
+      p.accountId,
+      p.amount,
+      p.currency,
+      p.status,
+      p.arrivalDate,
+      p.method,
+      p.failureCode,
+      p.failureMessage,
+      Object.entries(p.metadata ?? {}).sort(([a], [b]) =>
+        a < b ? -1 : a > b ? 1 : 0,
+      ),
+    ],
+  });
+}