@fantastic.dev/better-stripe 0.21.0 → 0.23.0

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

@@ -0,0 +1,272 @@
+// @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 {
+  transferFingerprint,
+  payoutClaimFingerprint,
+} from "./payoutRelease/helpers.js";
+const modules = import.meta.glob("./**/*.*s");
+const scope = { accountId: "acct_one", ownerKey: "owner" };
+
+async function setup() {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    await ctx.db.insert("payoutPolicies", {
+      ...scope,
+      mode: "stripe_managed",
+      status: "ready",
+      revision: 0,
+      operationKey: "default",
+      country: "US",
+      thresholds: [],
+    });
+    for (const [id, amount, role] of [
+      ["tr_one", 600, "store"],
+      ["tr_two", 400, "affiliate"],
+    ] as const)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: id,
+        amount,
+        currency: "usd",
+        destinationAccountId: scope.accountId,
+        status: "paid",
+        role,
+      });
+  });
+  const rows = await t.run((ctx) => ctx.db.query("transfers").collect());
+  const args = {
+    ...scope,
+    expectedRevision: 0,
+    payout: {
+      stripePayoutId: "po_old",
+      amount: 1000,
+      currency: "usd",
+      created: Math.floor(Date.now() / 1000) - 100,
+      destinationId: "ba_one",
+      status: "paid",
+      debitTransactionId: "txn_debit",
+      debitFee: 30,
+    },
+    allocations: [
+      { stripeTransferId: "tr_one", amount: 600 },
+      { stripeTransferId: "tr_two", amount: 400 },
+    ],
+    observations: rows.map((row) => ({
+      stripeTransferId: row.stripeTransferId,
+      currency: "usd",
+      matureNet: row.amount,
+      pendingCredits: 0,
+      ledgerFingerprint: transferFingerprint(row),
+      observedAt: Date.now(),
+      transactionIds: [`txn_${row.stripeTransferId}`],
+    })),
+  };
+  return { t, args };
+}
+async function importOne(
+  t: ReturnType<typeof convexTest>,
+  args: Awaited<ReturnType<typeof setup>>["args"] & {
+    payout: { returnTransactionId?: string; returnFee?: number };
+  },
+) {
+  const rows = await t.run((ctx) =>
+    ctx.db.query("payoutReleaseClaims").collect(),
+  );
+  const result = await t.mutation(
+    makeFunctionReference<"mutation">(
+      "payoutRelease/mutations:adoptHistoricalBatch",
+    ),
+    {
+      accountId: args.accountId,
+      ownerKey: args.ownerKey,
+      expectedRevision: args.expectedRevision,
+      observations: args.observations,
+      expectedClaims: rows.map((c) => ({
+        operationKey: c.operationKey,
+        fingerprint: payoutClaimFingerprint(c),
+      })),
+      payouts: [{ payout: args.payout, allocations: args.allocations }],
+    },
+  );
+  return result.claims[0];
+}
+
+it("imports historical paid principal and actual fees once", async () => {
+  const { t, args } = await setup();
+  expect(await importOne(t, args)).toMatchObject({
+    historical: true,
+    status: "paid",
+    amount: 1000,
+    providerFee: 30,
+    destinationId: "ba_one",
+  });
+  await importOne(t, args);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toMatchObject([
+    { paidAmount: 600, reservedAmount: 0 },
+    { paidAmount: 400, reservedAmount: 0 },
+  ]);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutFeeBalances").collect()),
+  ).toMatchObject([{ amount: 30 }]);
+});
+it("imports a verified returned payout without recording its principal as paid", async () => {
+  const { t, args } = await setup();
+  expect(
+    await importOne(t, {
+      ...args,
+      payout: {
+        ...args.payout,
+        status: "returned",
+        returnTransactionId: "txn_return",
+        returnFee: -10,
+      },
+    }),
+  ).toMatchObject({ status: "returned", providerFee: 20 });
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toMatchObject([{ paidAmount: 0 }, { paidAmount: 0 }]);
+});
+it("rejects changing source allocations on replay", async () => {
+  const { t, args } = await setup();
+  await importOne(t, args);
+  await expect(
+    importOne(t, {
+      ...args,
+      allocations: [
+        { stripeTransferId: "tr_one", amount: 500 },
+        { stripeTransferId: "tr_two", amount: 500 },
+      ],
+    }),
+  ).rejects.toThrow(/identity|allocation/i);
+});
+it.each([999, 1001, 0, -1, 1.5])(
+  "requires exact positive integer allocations: %s",
+  async (amount) => {
+    const { t, args } = await setup();
+    await expect(
+      importOne(t, {
+        ...args,
+        allocations: [{ stripeTransferId: "tr_one", amount }],
+      }),
+    ).rejects.toThrow();
+    expect(
+      await t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+    ).toEqual([]);
+  },
+);
+it("rejects another owner before any ledger writes", async () => {
+  const { t, args } = await setup();
+  await expect(importOne(t, { ...args, ownerKey: "other" })).rejects.toThrow(
+    /owner/i,
+  );
+});
+it("rejects an incomplete source snapshot", async () => {
+  const { t, args } = await setup();
+  await expect(
+    importOne(t, { ...args, observations: args.observations.slice(0, 1) }),
+  ).rejects.toThrow(/snapshot/i);
+});
+it("requires inactive automatic policy at the observed revision", async () => {
+  const { t, args } = await setup();
+  await expect(importOne(t, { ...args, expectedRevision: 1 })).rejects.toThrow(
+    /revision/i,
+  );
+  await t.run(async (ctx) => {
+    const p = await ctx.db.query("payoutPolicies").first();
+    await ctx.db.patch("payoutPolicies", p!._id, { mode: "custom" });
+  });
+  await expect(importOne(t, args)).rejects.toThrow(/policy/i);
+});
+it("retains historical paid allocations even when a later refund leaves debt", async () => {
+  const { t, args } = await setup();
+  await t.run(async (ctx) => {
+    const row = await ctx.db.query("transfers").first();
+    await ctx.db.patch("transfers", row!._id, { reversedAmount: 500 });
+  });
+  const rows = await t.run((ctx) => ctx.db.query("transfers").collect());
+  const observations = args.observations.map((o) => ({
+    ...o,
+    matureNet: o.stripeTransferId === "tr_one" ? 100 : o.matureNet,
+    ledgerFingerprint: transferFingerprint(
+      rows.find((r) => r.stripeTransferId === o.stripeTransferId)!,
+    ),
+  }));
+  await importOne(t, { ...args, observations });
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toMatchObject([{ paidAmount: 600 }, { paidAmount: 400 }]);
+});
+it("imports a complete historical batch atomically and rejects stale competing mappings", async () => {
+  const { t, args } = await setup();
+  const batch = makeFunctionReference<"mutation">(
+    "payoutRelease/mutations:adoptHistoricalBatch",
+  );
+  const input = {
+    ...scope,
+    expectedRevision: 0,
+    observations: args.observations,
+    expectedClaims: [],
+    payouts: [
+      {
+        payout: {
+          ...args.payout,
+          stripePayoutId: "po_first",
+          amount: 600,
+          debitTransactionId: "txn_first",
+        },
+        allocations: [{ stripeTransferId: "tr_one", amount: 600 }],
+      },
+      {
+        payout: {
+          ...args.payout,
+          stripePayoutId: "po_second",
+          amount: 400,
+          debitTransactionId: "txn_second",
+        },
+        allocations: [{ stripeTransferId: "tr_two", amount: 400 }],
+      },
+    ],
+  };
+  expect(await t.mutation(batch, input)).toMatchObject({
+    claims: [{ amount: 600 }, { amount: 400 }],
+  });
+  await expect(t.mutation(batch, input)).rejects.toThrow(/snapshot|history/i);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toMatchObject([{ paidAmount: 600 }, { paidAmount: 400 }]);
+});
+it("a bad later payout rolls back the entire historical batch", async () => {
+  const { t, args } = await setup();
+  const batch = makeFunctionReference<"mutation">(
+    "payoutRelease/mutations:adoptHistoricalBatch",
+  );
+  await expect(
+    t.mutation(batch, {
+      ...scope,
+      expectedRevision: 0,
+      observations: args.observations,
+      expectedClaims: [],
+      payouts: [
+        { payout: args.payout, allocations: args.allocations },
+        {
+          payout: {
+            ...args.payout,
+            stripePayoutId: "po_bad",
+            debitTransactionId: "txn_bad",
+          },
+          allocations: [],
+        },
+      ],
+    }),
+  ).rejects.toThrow();
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+  ).toEqual([]);
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toEqual([]);
+});

package/src/component/payout-policy-adoption.test.ts

@@ -0,0 +1,131 @@
+// @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 { transferFingerprint } from "./payoutRelease/helpers.js";
+const modules = import.meta.glob("./**/*.*s");
+const m = (name: string) =>
+  makeFunctionReference<"mutation">(`payoutPolicy/mutations:${name}`);
+const scope = { accountId: "acct_one", ownerKey: "owner" };
+async function setup(country = "US") {
+  const t = convexTest(schema, modules);
+  await t.mutation(m("prepare"), {
+    ...scope,
+    operationKey: "default",
+    expectedRevision: -1,
+    mode: "stripe_managed",
+    thresholds: [],
+    country,
+    observedSchedule: { interval: "weekly", weeklyDays: ["monday"] },
+  });
+  await t.mutation(m("confirm"), {
+    ...scope,
+    operationKey: "default",
+    observedSchedule: { interval: "weekly", weeklyDays: ["monday"] },
+  });
+  const row = await t.run(async (ctx) => {
+    const id = await ctx.db.insert("transfers", {
+      stripeTransferId: "tr_one",
+      destinationAccountId: scope.accountId,
+      amount: 1000,
+      currency: "usd",
+      status: "paid",
+      role: "store",
+    });
+    return (await ctx.db.get("transfers", id))!;
+  });
+  const proof = {
+    observations: [
+      {
+        stripeTransferId: row.stripeTransferId,
+        currency: "usd",
+        matureNet: 1000,
+        pendingCredits: 0,
+        ledgerFingerprint: transferFingerprint(row),
+        observedAt: Date.now(),
+        transactionIds: ["txn_one"],
+      },
+    ],
+    claims: [],
+    oldestHeldAt: Date.now() - 20 * 86400000,
+  };
+  const args = {
+    ...scope,
+    operationKey: "custom",
+    expectedRevision: 0,
+    mode: "custom",
+    thresholds: [{ currency: "usd", amount: 1000 }],
+    country,
+    observedSchedule: { interval: "weekly", weeklyDays: ["monday"] },
+    adoption: proof,
+  };
+  return { t, args, proof, row };
+}
+it("anchors funded activation to the oldest held money rather than activation time", async () => {
+  const { t, args, proof } = await setup();
+  await t.mutation(m("prepare"), args);
+  const p = await t.run((ctx) => ctx.db.query("payoutPolicies").first());
+  expect(p!.holdDeadline).toBe(proof.oldestHeldAt + 730 * 86400000);
+});
+it("rejects already-expired holding periods before changing policy", async () => {
+  const { t, args } = await setup("TH");
+  await expect(t.mutation(m("prepare"), args)).rejects.toThrow(
+    /holding|deadline/i,
+  );
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutPolicies").first()),
+  ).toMatchObject({ mode: "stripe_managed", status: "ready", revision: 0 });
+});
+it("requires fresh adoption proof before a delayed provider attempt", async () => {
+  const { t, args } = await setup();
+  await t.mutation(m("prepare"), args);
+  await expect(
+    t.mutation(m("beginAttempt"), { ...scope, operationKey: "custom" }),
+  ).rejects.toThrow(/adoption/i);
+});
+it("rejects changed source state before marking the provider attempt", async () => {
+  const { t, args, proof, row } = await setup();
+  await t.mutation(m("prepare"), args);
+  await t.run((ctx) =>
+    ctx.db.patch("transfers", row._id, { reversedAmount: 10 }),
+  );
+  await expect(
+    t.mutation(m("beginAttempt"), {
+      ...scope,
+      operationKey: "custom",
+      adoption: proof,
+    }),
+  ).rejects.toThrow(/snapshot/i);
+  expect(
+    await t.run((ctx) =>
+      ctx.db
+        .query("payoutPolicyOperations")
+        .withIndex("by_operation", (q) => q.eq("operationKey", "custom"))
+        .unique(),
+    ),
+  ).not.toHaveProperty("attempted");
+});
+it("fresh checks cannot extend the stored holding deadline", async () => {
+  const { t, args, proof } = await setup();
+  await t.mutation(m("prepare"), args);
+  await t.mutation(m("beginAttempt"), {
+    ...scope,
+    operationKey: "custom",
+    adoption: { ...proof, oldestHeldAt: Date.now() - 86400000 },
+  });
+  expect(
+    await t.run((ctx) => ctx.db.query("payoutPolicies").first()),
+  ).toMatchObject({ holdDeadline: proof.oldestHeldAt + 730 * 86400000 });
+});
+it("cannot confirm funded adoption without the fresh checked attempt marker", async () => {
+  const { t, args } = await setup();
+  await t.mutation(m("prepare"), args);
+  await expect(
+    t.mutation(m("confirm"), {
+      ...scope,
+      operationKey: "custom",
+      observedSchedule: { interval: "manual" },
+    }),
+  ).rejects.toThrow(/attempt/i);
+});

package/src/component/payout-release-snapshot.test.ts

@@ -0,0 +1,57 @@
+// @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 snapshot = makeFunctionReference<"query">(
+  "payoutRelease/queries:snapshot",
+);
+const scope = { accountId: "acct_recipient", ownerKey: "owner" };
+async function setup(count = 2) {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    await ctx.db.insert("payoutPolicies", {
+      ...scope,
+      mode: "custom",
+      status: "ready",
+      revision: 0,
+      operationKey: "enable",
+      thresholds: [{ currency: "usd", amount: 1000 }],
+      country: "US",
+      previousSchedule: { interval: "daily" },
+      holdDeadline: Date.now() + 86400000,
+    });
+    for (let i = 0; i < count; i++)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: `tr_${i}`,
+        destinationAccountId: scope.accountId,
+        amount: 500,
+        currency: "usd",
+        status: "paid",
+        role: i % 2 ? "affiliate" : "store",
+      });
+  });
+  return t;
+}
+it("returns complete source membership and historical claims for the owned account", async () => {
+  const t = await setup();
+  expect(await t.query(snapshot, scope)).toMatchObject({
+    status: "ready",
+    transfers: [{ stripeTransferId: "tr_0" }, { stripeTransferId: "tr_1" }],
+    claims: [],
+  });
+});
+it("holds an account exceeding the atomic claim bound rather than qualifying a partial page", async () => {
+  const t = await setup(101);
+  expect(await t.query(snapshot, scope)).toEqual({
+    status: "held",
+    reason: "snapshot_limit",
+  });
+});
+it("rejects another owner", async () => {
+  const t = await setup();
+  await expect(
+    t.query(snapshot, { ...scope, ownerKey: "other" }),
+  ).rejects.toThrow(/owner/i);
+});

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(),