@fantastic.dev/better-stripe 0.22.0 → 0.23.0

package/src/component/_generated/component.ts

@@ -2199,11 +2199,41 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         beginAttempt: FunctionReference<
           "mutation",
           "internal",
-          { accountId: string; operationKey: string; ownerKey: string },
+          {
+            accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
+            operationKey: string;
+            ownerKey: string;
+          },
           {
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2249,6 +2279,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2294,6 +2337,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2327,6 +2383,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           "internal",
           {
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             country: string;
             expectedRevision: number;
             mode: "stripe_managed" | "custom";
@@ -2344,6 +2413,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2444,6 +2526,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             _creationTime: number;
             _id: string;
             accountId: string;
+            adoption?: {
+              claims: Array<{ fingerprint: string; operationKey: string }>;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              oldestHeldAt?: number;
+            };
             attempted?: boolean;
             country: string;
             expectedRevision: number;
@@ -2476,6 +2571,94 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
     };
     payoutRelease: {
       mutations: {
+        adoptHistoricalBatch: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            accountId: string;
+            expectedClaims: Array<{
+              fingerprint: string;
+              operationKey: string;
+            }>;
+            expectedRevision: number;
+            observations: Array<{
+              currency: string;
+              ledgerFingerprint: string;
+              matureNet: number;
+              observedAt: number;
+              pendingCredits: number;
+              stripeTransferId: string;
+              transactionIds: Array<string>;
+            }>;
+            ownerKey: string;
+            payouts: Array<{
+              allocations: Array<{
+                amount: number;
+                role?: "store" | "affiliate" | "other";
+                stripeTransferId: string;
+              }>;
+              payout: {
+                amount: number;
+                created: number;
+                currency: string;
+                debitFee: number;
+                debitTransactionId: string;
+                destinationId: string;
+                returnFee?: number;
+                returnTransactionId?: string;
+                status: "paid" | "returned";
+                stripePayoutId: string;
+              };
+            }>;
+          },
+          {
+            claims: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId: string;
+              allocations: Array<{
+                amount: number;
+                role?: "store" | "affiliate" | "other";
+                stripeTransferId: string;
+              }>;
+              amount: number;
+              attemptedAt?: number;
+              currency: string;
+              debitFee?: number;
+              debitTransactionId?: string;
+              destinationId?: string;
+              expectedRevision: number;
+              feeRevision?: number;
+              historical?: boolean;
+              observations: Array<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: Array<string>;
+              }>;
+              operationKey: string;
+              ownerKey: string;
+              providerFee?: number;
+              rejection?: {
+                code: "balance_insufficient" | "amount_too_small";
+                requestId: string;
+              };
+              returnTransactionId?: string;
+              status:
+                | "reserved"
+                | "submitted"
+                | "paid"
+                | "returned"
+                | "canceled"
+                | "rejected";
+              stripePayoutId?: string;
+            }>;
+          },
+          Name
+        >;
         beginAttempt: FunctionReference<
           "mutation",
           "internal",
@@ -2497,6 +2680,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2546,6 +2730,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2613,6 +2798,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               destinationId?: string;
               expectedRevision: number;
               feeRevision?: number;
+              historical?: boolean;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2685,6 +2871,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2740,6 +2927,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2798,6 +2986,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
+            historical?: boolean;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2861,6 +3050,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               destinationId?: string;
               expectedRevision: number;
               feeRevision?: number;
+              historical?: boolean;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2913,6 +3103,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 destinationId?: string;
                 expectedRevision: number;
                 feeRevision?: number;
+                historical?: boolean;
                 observations: Array<{
                   currency: string;
                   ledgerFingerprint: string;

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