@fantastic.dev/better-stripe 0.20.1 → 0.22.0

package/src/component/_generated/component.ts

@@ -2492,7 +2492,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2504,6 +2508,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             }>;
             operationKey: string;
             ownerKey: string;
+            providerFee?: number;
             rejection?: {
               code: "balance_insufficient" | "amount_too_small";
               requestId: string;
@@ -2536,7 +2541,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2548,6 +2557,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             }>;
             operationKey: string;
             ownerKey: string;
+            providerFee?: number;
             rejection?: {
               code: "balance_insufficient" | "amount_too_small";
               requestId: string;
@@ -2570,6 +2580,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           {
             accountId: string;
             currency: string;
+            destinationId?: string;
             expectedRevision: number;
             independentLiabilities: number;
             observations: Array<{
@@ -2597,7 +2608,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               amount: number;
               attemptedAt?: number;
               currency: string;
+              debitFee?: number;
+              debitTransactionId?: string;
+              destinationId?: string;
               expectedRevision: number;
+              feeRevision?: number;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2609,6 +2624,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               }>;
               operationKey: string;
               ownerKey: string;
+              providerFee?: number;
               rejection?: {
                 code: "balance_insufficient" | "amount_too_small";
                 requestId: string;
@@ -2642,10 +2658,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             accountId: string;
             amount: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
             operationKey: string;
             ownerKey: string;
             providerStatus:
               "pending" | "in_transit" | "paid" | "failed" | "canceled";
+            returnFee?: number;
             returnTransactionId?: string;
             stripePayoutId: string;
           },
@@ -2661,7 +2680,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2673,6 +2696,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             }>;
             operationKey: string;
             ownerKey: string;
+            providerFee?: number;
             rejection?: {
               code: "balance_insufficient" | "amount_too_small";
               requestId: string;
@@ -2711,7 +2735,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2723,6 +2751,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             }>;
             operationKey: string;
             ownerKey: string;
+            providerFee?: number;
             rejection?: {
               code: "balance_insufficient" | "amount_too_small";
               requestId: string;
@@ -2741,6 +2770,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
       queries: {
+        fees: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; currency: string; ownerKey: string },
+          { amount: number; revision: number },
+          Name
+        >;
         get: FunctionReference<
           "query",
           "internal",
@@ -2757,7 +2793,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2769,6 +2809,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             }>;
             operationKey: string;
             ownerKey: string;
+            providerFee?: number;
             rejection?: {
               code: "balance_insufficient" | "amount_too_small";
               requestId: string;
@@ -2815,7 +2856,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               amount: number;
               attemptedAt?: number;
               currency: string;
+              debitFee?: number;
+              debitTransactionId?: string;
+              destinationId?: string;
               expectedRevision: number;
+              feeRevision?: number;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2827,6 +2872,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               }>;
               operationKey: string;
               ownerKey: string;
+              providerFee?: number;
               rejection?: {
                 code: "balance_insufficient" | "amount_too_small";
                 requestId: string;
@@ -2844,6 +2890,78 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        snapshot: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; ownerKey: string },
+          | { reason: "snapshot_limit"; status: "held" }
+          | {
+              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;
+                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;
+              }>;
+              status: "ready";
+              transfers: Array<{
+                _creationTime: number;
+                _id: string;
+                amount: number;
+                currency: string;
+                destinationAccountId: string;
+                metadata?: any;
+                paymentId?: string;
+                reinstatement?: boolean;
+                reversalClaimedAmount?: number;
+                reversalStatus?: "partially_reversed" | "fully_reversed";
+                reversedAmount?: number;
+                role?: "store" | "affiliate" | "other";
+                sourceChargeId?: string;
+                sourceInvoiceId?: string;
+                status: "pending" | "paid" | "failed" | "reversed";
+                stripeTransferId: string;
+                totalsRecorded?: true;
+              }>;
+            },
+          Name
+        >;
       };
     };
     products: {

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

@@ -0,0 +1,224 @@
+// @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">(`payoutRelease/mutations:${name}`);
+const scope = { accountId: "acct_recipient", ownerKey: "user_1" };
+async function setup(amount = 1500) {
+  const t = convexTest(schema, modules);
+  await t.mutation(
+    makeFunctionReference<"mutation">("payoutPolicy/mutations:prepare"),
+    {
+      ...scope,
+      operationKey: "enable",
+      expectedRevision: -1,
+      mode: "custom",
+      thresholds: [{ currency: "usd", amount: 1000 }],
+      country: "US",
+      observedSchedule: { interval: "daily" },
+    },
+  );
+  await t.mutation(
+    makeFunctionReference<"mutation">("payoutPolicy/mutations:confirm"),
+    {
+      ...scope,
+      operationKey: "enable",
+      observedSchedule: { interval: "manual" },
+    },
+  );
+  await t.mutation(
+    makeFunctionReference<"mutation">("connect/mutations:upsertTransfer"),
+    {
+      stripeTransferId: "tr_one",
+      destinationAccountId: scope.accountId,
+      amount,
+      currency: "usd",
+      role: "affiliate",
+      status: "paid",
+    },
+  );
+  const row = (await t.run((ctx) => ctx.db.query("transfers").take(1)))[0];
+  const args = {
+    ...scope,
+    operationKey: "first",
+    expectedRevision: 0,
+    currency: "usd",
+    providerAvailable: 1000,
+    independentLiabilities: 0,
+    observations: [
+      {
+        stripeTransferId: "tr_one",
+        currency: "usd",
+        matureNet: amount,
+        pendingCredits: 0,
+        ledgerFingerprint: transferFingerprint(row),
+        observedAt: Date.now(),
+        transactionIds: ["txn_funding"],
+      },
+    ],
+  };
+  await t.mutation(m("claim"), args);
+  await t.mutation(m("beginAttempt"), {
+    ...scope,
+    operationKey: args.operationKey,
+  });
+  const receipt = {
+    ...scope,
+    operationKey: args.operationKey,
+    stripePayoutId: "po_one",
+    currency: "usd",
+    amount: 1000,
+    providerStatus: "paid",
+    debitTransactionId: "txn_debit",
+    debitFee: 30,
+  };
+  return { t, args, receipt };
+}
+it("books a verified payout fee once and keeps it out of later eligibility", async () => {
+  const { t, args, receipt } = await setup();
+  await t.mutation(m("recordOutcome"), receipt);
+  await t.mutation(m("recordOutcome"), receipt);
+  expect(
+    await t.query(
+      makeFunctionReference<"query">("payoutRelease/queries:fees"),
+      { ...scope, currency: "usd" },
+    ),
+  ).toMatchObject({ amount: 30, revision: 1 });
+  expect(
+    await t.mutation(m("claim"), {
+      ...args,
+      operationKey: "next",
+      providerAvailable: 5000,
+    }),
+  ).toMatchObject({
+    status: "held",
+    matureUnpaid: 470,
+    reason: "below_threshold",
+  });
+});
+it("books only the net non-refundable fee after a verified return, including a negative fee credit", async () => {
+  const { t, args, receipt } = await setup();
+  await t.mutation(m("recordOutcome"), receipt);
+  const returned = {
+    ...receipt,
+    providerStatus: "failed",
+    returnTransactionId: "txn_return",
+    returnFee: -10,
+  };
+  await t.mutation(m("recordOutcome"), returned);
+  await t.mutation(m("recordOutcome"), returned);
+  expect(
+    await t.query(
+      makeFunctionReference<"query">("payoutRelease/queries:fees"),
+      { ...scope, currency: "usd" },
+    ),
+  ).toMatchObject({ amount: 20, revision: 2 });
+  expect(
+    await t.mutation(m("claim"), {
+      ...args,
+      operationKey: "next",
+      providerAvailable: 1500,
+    }),
+  ).toMatchObject({ status: "reserved", amount: 1480 });
+});
+it("does not erase known fees with a stale pending receipt after payout completion", async () => {
+  const { t, receipt } = await setup();
+  await t.mutation(m("recordOutcome"), receipt);
+  await t.mutation(m("recordOutcome"), {
+    ...receipt,
+    providerStatus: "pending",
+    debitFee: 0,
+  });
+  expect(
+    await t.query(
+      makeFunctionReference<"query">("payoutRelease/queries:fees"),
+      { ...scope, currency: "usd" },
+    ),
+  ).toMatchObject({ amount: 30 });
+});
+it("rejects a changed original debit identity or fee", async () => {
+  const { t, receipt } = await setup();
+  await t.mutation(m("recordOutcome"), receipt);
+  for (const changed of [{ debitTransactionId: "txn_other" }, { debitFee: 31 }])
+    await expect(
+      t.mutation(m("recordOutcome"), { ...receipt, ...changed }),
+    ).rejects.toThrow(/receipt|fee/);
+});
+it("invalidates an unattempted claim if a known fee changes after reservation", async () => {
+  const { t, args, receipt } = await setup(3000);
+  await t.mutation(m("recordOutcome"), {
+    ...receipt,
+    providerStatus: "pending",
+    debitFee: 0,
+  });
+  await t.mutation(m("claim"), { ...args, operationKey: "second" });
+  // A verified return adds its actual processing fee.
+  await t.mutation(m("recordOutcome"), {
+    ...receipt,
+    debitFee: 0,
+    providerStatus: "failed",
+    returnTransactionId: "txn_return",
+    returnFee: 30,
+  });
+  await expect(
+    t.mutation(m("beginAttempt"), { ...scope, operationKey: "second" }),
+  ).rejects.toThrow(/fee|revision/);
+});
+it("rejects ambiguous fee pairs and over-credits instead of creating spendable money", async () => {
+  const { t, receipt } = await setup();
+  await expect(
+    t.mutation(m("recordOutcome"), {
+      ...receipt,
+      debitTransactionId: undefined,
+    }),
+  ).rejects.toThrow(/fee|receipt/);
+  await expect(
+    t.mutation(m("recordOutcome"), {
+      ...receipt,
+      providerStatus: "failed",
+      returnTransactionId: "txn_return",
+      returnFee: -31,
+    }),
+  ).rejects.toThrow(/fee/);
+});
+it("can add verified fee evidence to a legacy returned claim without releasing principal twice", async () => {
+  const { t, args, receipt } = await setup();
+  const legacy = {
+    ...scope,
+    operationKey: args.operationKey,
+    stripePayoutId: "po_one",
+    amount: 1000,
+    currency: "usd",
+    providerStatus: "failed",
+    returnTransactionId: "txn_return",
+  };
+  await t.mutation(m("recordOutcome"), legacy);
+  const verified = {
+    ...legacy,
+    debitTransactionId: receipt.debitTransactionId,
+    debitFee: 30,
+    returnFee: -10,
+  };
+  await t.mutation(m("recordOutcome"), verified);
+  await t.mutation(m("recordOutcome"), verified);
+  expect(
+    await t.query(
+      makeFunctionReference<"query">("payoutRelease/queries:fees"),
+      { ...scope, currency: "usd" },
+    ),
+  ).toMatchObject({ amount: 20 });
+  await expect(
+    t.mutation(m("recordOutcome"), { ...verified, returnFee: 0 }),
+  ).rejects.toThrow(/fee|receipt/);
+  expect(
+    await t.mutation(m("claim"), {
+      ...args,
+      operationKey: "next",
+      providerAvailable: 1500,
+    }),
+  ).toMatchObject({ status: "reserved", amount: 1480 });
+});

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/payoutRelease/allocation.ts

@@ -12,6 +12,7 @@ export type PayoutAllocationOptions = {
   threshold: number;
   providerAvailable: number;
   independentLiabilities: number;
+  confirmedFees?: number;
   sources: PayoutFundingSource[];
 };
 export type RecipientPayoutPlan = {
@@ -66,6 +67,7 @@ export function planRecipientPayout(
   if (money(opts.threshold) <= 0) throw new Error("Invalid payout threshold.");
   money(opts.providerAvailable);
   nonnegative(opts.independentLiabilities);
+  nonnegative(opts.confirmedFees ?? 0);
   const seen = new Set<string>();
   for (const source of opts.sources) {
     if (
@@ -107,6 +109,10 @@ export function planRecipientPayout(
     pendingCredits = money(pendingCredits + source.pendingCredits);
     return { source, unpaid };
   });
+  matureUnpaid = money(
+    money(matureUnpaid - (opts.confirmedFees ?? 0)) -
+      opts.independentLiabilities,
+  );
   const totals = {
     currency: opts.currency,
     matureUnpaid,

package/src/component/payoutRelease/fees.ts

@@ -0,0 +1,93 @@
+import type { MutationCtx, QueryCtx } from "../_generated/server.js";
+import type { Doc } from "../_generated/dataModel.js";
+import { addSummaryAmounts as add } from "../earnings/arithmetic.js";
+import { validateScope } from "../payoutPolicy/helpers.js";
+export async function readFees(
+  ctx: QueryCtx | MutationCtx,
+  scope: { accountId: string; ownerKey: string; currency: string },
+) {
+  validateScope(scope);
+  if (scope.currency.length !== 3 || !/^[a-z]{3}$/.test(scope.currency))
+    throw new Error("Invalid payout fee currency.");
+  const row = await ctx.db
+    .query("payoutFeeBalances")
+    .withIndex("by_account_currency", (q) =>
+      q.eq("accountId", scope.accountId).eq("currency", scope.currency),
+    )
+    .unique();
+  if (row && row.ownerKey !== scope.ownerKey)
+    throw new Error("Payout fee owner does not match.");
+  return row;
+}
+/** Atomically book verified debit/return fees along with the provider outcome. */
+export async function recordFees(
+  ctx: MutationCtx,
+  claim: Doc<"payoutReleaseClaims">,
+  proof: { debitTransactionId?: string; debitFee?: number; returnFee?: number },
+  returned: boolean,
+) {
+  if (
+    proof.debitTransactionId === undefined &&
+    proof.debitFee === undefined &&
+    proof.returnFee === undefined
+  )
+    return;
+  if (
+    !proof.debitTransactionId ||
+    !/^txn_\w+$/.test(proof.debitTransactionId) ||
+    proof.debitTransactionId.trim() !== proof.debitTransactionId ||
+    !Number.isSafeInteger(proof.debitFee) ||
+    (returned
+      ? !Number.isSafeInteger(proof.returnFee)
+      : proof.returnFee !== undefined)
+  )
+    throw new Error("Payout fee receipt is incomplete.");
+  if (
+    (claim.debitTransactionId !== undefined &&
+      claim.debitTransactionId !== proof.debitTransactionId) ||
+    (claim.debitFee !== undefined && claim.debitFee !== proof.debitFee)
+  )
+    throw new Error("Original payout fee receipt changed.");
+  const existing = await ctx.db
+    .query("payoutReleaseClaims")
+    .withIndex("by_debit_receipt", (q) =>
+      q.eq("debitTransactionId", proof.debitTransactionId),
+    )
+    .unique();
+  if (existing && existing._id !== claim._id)
+    throw new Error("Payout debit receipt is already allocated.");
+  const fee = add(proof.debitFee!, returned ? proof.returnFee! : 0);
+  if (fee < 0)
+    throw new Error("Payout fee credit requires explicit allocation.");
+  if (
+    claim.status === "returned" &&
+    claim.providerFee !== undefined &&
+    claim.providerFee !== fee
+  )
+    throw new Error("Verified payout return fee receipt changed.");
+  const delta = add(fee, -(claim.providerFee ?? 0));
+  if (delta !== 0) {
+    const balance = await readFees(ctx, claim);
+    const amount = add(balance?.amount ?? 0, delta);
+    if (amount < 0) throw new Error("Payout fee balance underflow.");
+    const revision = add(balance?.revision ?? 0, 1);
+    if (balance)
+      await ctx.db.patch("payoutFeeBalances", balance._id, {
+        amount,
+        revision,
+      });
+    else
+      await ctx.db.insert("payoutFeeBalances", {
+        accountId: claim.accountId,
+        ownerKey: claim.ownerKey,
+        currency: claim.currency,
+        amount,
+        revision,
+      });
+  }
+  await ctx.db.patch("payoutReleaseClaims", claim._id, {
+    debitTransactionId: proof.debitTransactionId,
+    debitFee: proof.debitFee,
+    providerFee: fee,
+  });
+}