@fantastic.dev/better-stripe 0.24.0 → 0.25.0

package/src/component/core/mutations.ts

@@ -1,3 +1,4 @@
+import { assertPayoutResetSafe } from "./resetSafety.js";
 import { v } from "convex/values";
 
 import type { TableNames } from "../_generated/dataModel";
@@ -155,6 +156,7 @@ export const clearAllTables = mutation({
     tables: v.array(v.string()),
   }),
   handler: async (ctx) => {
+    await assertPayoutResetSafe(ctx);
     // Derive table names from the schema definition so the clear list can never
     // drift out of sync when new tables are added.
     const tables = Object.keys(schema.tables) as TableNames[];

package/src/component/core/resetSafety.ts

@@ -0,0 +1,67 @@
+import type { MutationCtx } from "../_generated/server.js";
+/** A database reset cannot erase the only restoration or unresolved-payout record. */
+export async function assertPayoutResetSafe(ctx: MutationCtx) {
+  const [bound, custom, changing, reserved, submitted, pending, transit] =
+    await Promise.all([
+      ctx.db
+        .query("payoutSnapshots")
+        .withIndex("by_read_only", (q) => q.eq("readOnly", false))
+        .first(),
+      ctx.db
+        .query("payoutPolicies")
+        .withIndex("by_mode_status", (q) => q.eq("mode", "custom"))
+        .first(),
+      ctx.db
+        .query("payoutPolicies")
+        .withIndex("by_mode_status", (q) =>
+          q.eq("mode", "stripe_managed").eq("status", "changing"),
+        )
+        .first(),
+      ctx.db
+        .query("payoutReleaseClaims")
+        .withIndex("by_status", (q) => q.eq("status", "reserved"))
+        .first(),
+      ctx.db
+        .query("payoutReleaseClaims")
+        .withIndex("by_status", (q) => q.eq("status", "submitted"))
+        .first(),
+      ctx.db
+        .query("payouts")
+        .withIndex("by_status", (q) => q.eq("status", "pending"))
+        .first(),
+      ctx.db
+        .query("payouts")
+        .withIndex("by_status", (q) => q.eq("status", "in_transit"))
+        .first(),
+    ]);
+  if (bound)
+    throw new Error(
+      "A financially bound payout collection must be resolved before reset.",
+    );
+  if (custom || changing)
+    throw new Error(
+      "Restore and verify payout schedules before reset; restoration records cannot be erased.",
+    );
+  if (reserved || submitted)
+    throw new Error(
+      "Resolve payout claims before reset; unresolved reservations cannot be erased.",
+    );
+  if (pending || transit)
+    throw new Error("Verify in-flight provider payouts before reset.");
+  const affiliateOperations = await Promise.all(
+    (["pending", "unknown"] as const).flatMap((state) => [
+      ctx.db
+        .query("affiliatePayoutReleases")
+        .withIndex("by_state", (q) => q.eq("state", state))
+        .first(),
+      ctx.db
+        .query("affiliateRecoveryOperations")
+        .withIndex("by_state", (q) => q.eq("state", state))
+        .first(),
+    ]),
+  );
+  if (affiliateOperations.some(Boolean))
+    throw new Error(
+      "Resolve pending or unknown affiliate operations before reset.",
+    );
+}

package/src/component/earnings/triggers.ts

@@ -1,3 +1,4 @@
+import { registerPayoutRevisions } from "../payoutSnapshots/revisions.js";
 import { Triggers } from "convex-helpers/server/triggers";
 import {
   customCtx,
@@ -93,4 +94,5 @@ triggers.register("payouts", async (ctx, change) => {
       await ctx.innerDb.patch("payouts", change.id, { totalsRecorded: true });
   }
 });
+registerPayoutRevisions(triggers);
 export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));

package/src/component/payout-reset-safety.test.ts

@@ -0,0 +1,148 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "./schema.js";
+const modules = import.meta.glob("./**/*.*s");
+const reset = makeFunctionReference<"mutation">(
+  "core/mutations:clearAllTables",
+);
+const scope = { accountId: "acct_one", ownerKey: "owner" };
+it.each(["custom", "changing"])(
+  "retains restoration records for %s payout policy",
+  async (kind) => {
+    const t = convexTest(schema, modules);
+    await t.run((ctx) =>
+      ctx.db.insert("payoutPolicies", {
+        ...scope,
+        revision: 0,
+        mode: kind === "custom" ? "custom" : "stripe_managed",
+        status: kind === "changing" ? "changing" : "ready",
+        operationKey: "control",
+        country: "US",
+        thresholds: [],
+        previousSchedule: { interval: "weekly", weeklyDays: ["monday"] },
+        holdDeadline: Date.now() + 86400000,
+      }),
+    );
+    await expect(t.mutation(reset, {})).rejects.toThrow(/payout.*schedule/i);
+    expect(
+      await t.run((ctx) => ctx.db.query("payoutPolicies").collect()),
+    ).toHaveLength(1);
+  },
+);
+it.each(["reserved", "submitted"])(
+  "retains an unresolved %s payout claim",
+  async (status) => {
+    const t = convexTest(schema, modules);
+    await t.run((ctx) =>
+      ctx.db.insert("payoutReleaseClaims", {
+        ...scope,
+        operationKey: "money",
+        expectedRevision: 0,
+        currency: "usd",
+        amount: 1000,
+        status: status as "reserved" | "submitted",
+        allocations: [{ stripeTransferId: "tr_one", amount: 1000 }],
+        observations: [],
+        attemptedAt: Date.now(),
+      }),
+    );
+    await expect(t.mutation(reset, {})).rejects.toThrow(/payout.*claim/i);
+    expect(
+      await t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+    ).toHaveLength(1);
+  },
+);
+it("retains known in-flight provider payouts", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(
+    makeFunctionReference<"mutation">("connect/mutations:upsertPayout"),
+    {
+      stripePayoutId: "po_one",
+      accountId: scope.accountId,
+      currency: "usd",
+      amount: 1000,
+      status: "pending",
+    },
+  );
+  await expect(t.mutation(reset, {})).rejects.toThrow(/in.flight.*payout/i);
+  expect(await t.run((ctx) => ctx.db.query("payouts").collect())).toHaveLength(
+    1,
+  );
+});
+it("cannot bypass a bound collection through wholesale reset", async () => {
+  const t = convexTest(schema, modules);
+  const h = await t.mutation(
+    makeFunctionReference<"mutation">("payoutSnapshots/mutations:begin"),
+    { ...scope, operationKey: "collection", expectedRevision: -1 },
+  );
+  await t.run((ctx) =>
+    ctx.db.patch("payoutSnapshots", h._id, { readOnly: false }),
+  );
+  await expect(t.mutation(reset, {})).rejects.toThrow(/bound.*collection/i);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSnapshots").collect()),
+  ).toHaveLength(1);
+});
+it.each(["pending", "unknown"] as const)(
+  "retains %s direct affiliate payout attempts",
+  async (state) => {
+    const t = convexTest(schema, modules);
+    await t.run((ctx) =>
+      ctx.db.insert("affiliatePayoutReleases", {
+        affiliateAccountId: scope.accountId,
+        currency: "usd",
+        operationKey: "direct-affiliate",
+        amount: 1000,
+        minimumAmount: 1,
+        createdAt: Date.now(),
+        state,
+      }),
+    );
+    await expect(t.mutation(reset, {})).rejects.toThrow(
+      /affiliate.*operation/i,
+    );
+    expect(
+      await t.run((ctx) => ctx.db.query("affiliatePayoutReleases").collect()),
+    ).toHaveLength(1);
+  },
+);
+it.each(["pending", "unknown"] as const)(
+  "retains %s affiliate recovery attempts",
+  async (state) => {
+    const t = convexTest(schema, modules);
+    await t.run(async (ctx) => {
+      const obligationId = await ctx.db.insert("affiliateObligations", {
+        sourceChargeId: "ch_one",
+        affiliateAccountId: scope.accountId,
+        currency: "usd",
+        chargeAmount: 1000,
+        originalCommission: 100,
+        refundedPrincipal: 1000,
+        disputedPrincipal: 0,
+        lostPrincipal: 0,
+        finalizedAmount: 100,
+        provisionalAmount: 0,
+        recoveredAmount: 0,
+        needsReconciliation: false,
+      });
+      await ctx.db.insert("affiliateRecoveryOperations", {
+        obligationId,
+        kind: "recovery",
+        amount: 100,
+        state,
+        attempted: true,
+        createdAt: Date.now(),
+      });
+    });
+    await expect(t.mutation(reset, {})).rejects.toThrow(
+      /affiliate.*operation/i,
+    );
+    expect(
+      await t.run((ctx) =>
+        ctx.db.query("affiliateRecoveryOperations").collect(),
+      ),
+    ).toHaveLength(1);
+  },
+);

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

@@ -0,0 +1,125 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "./schema.js";
+const modules = import.meta.glob("./**/*.*s");
+const m = (name: string) =>
+  makeFunctionReference<"mutation">(`connect/mutations:${name}`);
+const transfer = (id = "tr_one", extra = {}) => ({
+  stripeTransferId: id,
+  destinationAccountId: "acct_one",
+  amount: 1000,
+  currency: "usd",
+  role: "affiliate",
+  status: "paid",
+  sourceChargeId: "ch_one",
+  ...extra,
+});
+const test = () => convexTest(schema, modules);
+const revision = (t: ReturnType<typeof test>, accountId = "acct_one") =>
+  t.run((ctx) =>
+    ctx.db
+      .query("payoutFinancialRevisions")
+      .withIndex("by_account", (q) => q.eq("accountId", accountId))
+      .unique(),
+  );
+it("records new positive funding without invalidating older risk-fenced snapshots", async () => {
+  const t = test();
+  await t.mutation(m("upsertTransfer"), transfer());
+  expect(await revision(t)).toMatchObject({ revision: 1, riskRevision: 0 });
+  await t.mutation(m("upsertTransfer"), transfer("tr_two"));
+  expect(await revision(t)).toMatchObject({ revision: 2, riskRevision: 0 });
+});
+it("does not invalidate snapshots for replay or metadata-only changes", async () => {
+  const t = test();
+  await t.mutation(m("upsertTransfer"), transfer());
+  await t.mutation(
+    m("upsertTransfer"),
+    transfer("tr_one", { metadata: { note: "cosmetic" } }),
+  );
+  expect(await revision(t)).toMatchObject({ revision: 1, riskRevision: 0 });
+});
+it("invalidates risk when a refund/reversal reduces source funding", async () => {
+  const t = test();
+  await t.mutation(m("upsertTransfer"), transfer());
+  await t.mutation(m("recordTransferReversal"), {
+    stripeTransferId: "tr_one",
+    reversedAmount: 100,
+  });
+  expect(await revision(t)).toMatchObject({ revision: 2, riskRevision: 1 });
+  await t.mutation(m("recordTransferReversal"), {
+    stripeTransferId: "tr_one",
+    reversedAmount: 100,
+  });
+  expect(await revision(t)).toMatchObject({ revision: 2, riskRevision: 1 });
+});
+it("reserved reversals invalidate risk before Stripe I/O", async () => {
+  const t = test();
+  await t.mutation(m("upsertTransfer"), transfer());
+  await t.mutation(m("claimReversalSlices"), {
+    operationId: "refund-one",
+    sourceChargeId: "ch_one",
+    mode: { kind: "fraction", chargeAmount: 1000, amountRefunded: 500 },
+  });
+  expect(await revision(t)).toMatchObject({ revision: 2, riskRevision: 1 });
+});
+it("a moved source invalidates both account scopes", async () => {
+  const t = test();
+  await t.mutation(m("upsertTransfer"), transfer());
+  await t.mutation(
+    m("upsertTransfer"),
+    transfer("tr_one", { destinationAccountId: "acct_other" }),
+  );
+  expect(await revision(t)).toMatchObject({ revision: 2, riskRevision: 1 });
+  expect(await revision(t, "acct_other")).toMatchObject({
+    revision: 1,
+    riskRevision: 1,
+  });
+});
+it("concurrent independent source inserts cannot lose revision updates", async () => {
+  const t = test();
+  await Promise.all([
+    t.mutation(m("upsertTransfer"), transfer("tr_one")),
+    t.mutation(m("upsertTransfer"), transfer("tr_two")),
+  ]);
+  expect(await revision(t)).toMatchObject({ revision: 2, riskRevision: 0 });
+});
+it("provider payout outcomes invalidate account cash risk", async () => {
+  const t = test();
+  await t.mutation(m("upsertPayout"), {
+    stripePayoutId: "po_one",
+    accountId: "acct_one",
+    amount: 1000,
+    currency: "usd",
+    status: "pending",
+    arrivalDate: new Date().toISOString(),
+  });
+  expect(await revision(t)).toMatchObject({ revision: 1, riskRevision: 1 });
+});
+it("records an ordered account risk journal for incremental repair", async () => {
+  const t = test();
+  await t.mutation(m("upsertTransfer"), transfer());
+  await t.mutation(m("recordTransferReversal"), {
+    stripeTransferId: "tr_one",
+    reversedAmount: 100,
+  });
+  const events = await t.run((ctx) =>
+    ctx.db.query("payoutRiskEvents").collect(),
+  );
+  expect(events).toMatchObject([
+    { accountId: "acct_one", riskRevision: 1, kind: "transfer", key: "tr_one" },
+  ]);
+});
+it("positive writes leave the isolated risk fence unchanged", async () => {
+  const t = test();
+  await t.mutation(m("upsertTransfer"), transfer());
+  const first = await t.run((ctx) =>
+    ctx.db.query("payoutRiskRevisions").collect(),
+  );
+  expect(first).toMatchObject([{ accountId: "acct_one", riskRevision: 0 }]);
+  await t.mutation(m("upsertTransfer"), transfer("tr_two"));
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutRiskRevisions").collect()),
+  ).toEqual(first);
+});