@fantastic.dev/better-stripe 0.23.2 → 0.25.0

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-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);
+});