@fantastic.dev/better-stripe 0.20.1 → 0.21.0

package/src/component/_generated/component.ts

@@ -2492,7 +2492,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2504,6 +2507,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 +2540,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2548,6 +2555,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;
@@ -2597,7 +2605,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               amount: number;
               attemptedAt?: number;
               currency: string;
+              debitFee?: number;
+              debitTransactionId?: string;
               expectedRevision: number;
+              feeRevision?: number;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2609,6 +2620,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 +2654,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 +2676,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2673,6 +2691,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 +2730,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2723,6 +2745,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 +2764,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 +2787,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             attemptedAt?: number;
             currency: string;
+            debitFee?: number;
+            debitTransactionId?: string;
             expectedRevision: number;
+            feeRevision?: number;
             observations: Array<{
               currency: string;
               ledgerFingerprint: string;
@@ -2769,6 +2802,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 +2849,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               amount: number;
               attemptedAt?: number;
               currency: string;
+              debitFee?: number;
+              debitTransactionId?: string;
               expectedRevision: number;
+              feeRevision?: number;
               observations: Array<{
                 currency: string;
                 ledgerFingerprint: string;
@@ -2827,6 +2864,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;

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

package/src/component/payoutRelease/mutations.ts

@@ -1,3 +1,4 @@
+import { readFees, recordFees } from "./fees.js";
 import { v } from "convex/values";
 import { mutation } from "../_generated/server.js";
 import { identity, observation, claimDoc } from "./schema.js";
@@ -88,11 +89,13 @@ export const claim = mutation({
         reservedAmount: prior?.reservedAmount ?? 0,
       });
     }
+    const fees = await readFees(ctx, args);
     const plan = planRecipientPayout({
       currency: args.currency,
       threshold: minimum.amount,
       providerAvailable: args.providerAvailable,
       independentLiabilities: args.independentLiabilities,
+      confirmedFees: fees?.amount ?? 0,
       sources,
     });
     if (plan.status === "held") return plan;
@@ -121,6 +124,7 @@ export const claim = mutation({
       amount: plan.amount,
       allocations: plan.allocations,
       observations: args.observations,
+      feeRevision: fees?.revision ?? 0,
       status: "reserved",
     });
     return (await ctx.db.get("payoutReleaseClaims", id))!;
@@ -135,6 +139,9 @@ export const beginAttempt = mutation({
       throw new Error("Payout claim is not reserved.");
     if (claim.attemptedAt !== undefined) return claim;
     await readyPolicy(ctx, claim);
+    const feeRevision = (await readFees(ctx, claim))?.revision ?? 0;
+    if (feeRevision !== (claim.feeRevision ?? 0))
+      throw new Error("Payout fee revision changed after reservation.");
     await checkSnapshot(ctx, claim.accountId, claim.observations, true);
     await ctx.db.patch("payoutReleaseClaims", claim._id, {
       attemptedAt: Date.now(),
@@ -175,6 +182,9 @@ export const recordOutcome = mutation({
       v.literal("canceled"),
     ),
     returnTransactionId: v.optional(v.string()),
+    debitTransactionId: v.optional(v.string()),
+    debitFee: v.optional(v.number()),
+    returnFee: v.optional(v.number()),
   },
   returns: claimDoc,
   handler: async (ctx, args) => {
@@ -226,8 +236,15 @@ export const recordOutcome = mutation({
     if (claim.status === "returned") {
       if (returned && args.returnTransactionId !== claim.returnTransactionId)
         throw new Error("Payout return receipt identity changed.");
+      if (returned) {
+        await recordFees(ctx, claim, args, true);
+        return (await ctx.db.get("payoutReleaseClaims", claim._id))!;
+      }
       return claim;
     }
+    if (claim.status === "paid" && args.providerStatus !== "paid" && !returned)
+      return claim;
+    await recordFees(ctx, claim, args, returned);
     if (returned) {
       await moveAllocations(
         ctx,

package/src/component/payoutRelease/queries.ts

@@ -1,3 +1,4 @@
+import { readFees } from "./fees.js";
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 import { query } from "../_generated/server.js";
@@ -54,3 +55,13 @@ export const pending = query({
     };
   },
 });
+
+export const fees = query({
+  args: { accountId: v.string(), ownerKey: v.string(), currency: v.string() },
+  returns: v.object({ amount: v.number(), revision: v.number() }),
+  handler: async (ctx, args) => {
+    await readPolicy(ctx, args);
+    const balance = await readFees(ctx, args);
+    return { amount: balance?.amount ?? 0, revision: balance?.revision ?? 0 };
+  },
+});

package/src/component/payoutRelease/schema.ts

@@ -36,6 +36,10 @@ export const claimFields = {
   attemptedAt: v.optional(v.number()),
   stripePayoutId: v.optional(v.string()),
   returnTransactionId: v.optional(v.string()),
+  feeRevision: v.optional(v.number()),
+  debitTransactionId: v.optional(v.string()),
+  debitFee: v.optional(v.number()),
+  providerFee: v.optional(v.number()),
   rejection: v.optional(
     v.object({
       requestId: v.string(),
@@ -55,6 +59,7 @@ export const claimsTable = defineTable(claimFields)
   .index("by_operation", ["operationKey"])
   .index("by_account_status", ["accountId", "status"])
   .index("by_provider_payout", ["stripePayoutId"])
+  .index("by_debit_receipt", ["debitTransactionId"])
   .index("by_return_receipt", ["returnTransactionId"])
   .index("by_rejection_request", ["rejection.requestId"]);
 export const sourcesTable = defineTable({
@@ -67,3 +72,10 @@ export const sourcesTable = defineTable({
   .index("by_transfer", ["stripeTransferId"])
   .index("by_account", ["accountId"]);
 export const identity = { ...scopeFields, operationKey: v.string() };
+
+export const feeBalancesTable = defineTable({
+  ...scopeFields,
+  currency: v.string(),
+  amount: v.number(),
+  revision: v.number(),
+}).index("by_account_currency", ["accountId", "currency"]);

package/src/component/schema.ts

@@ -1,4 +1,5 @@
 import {
+  feeBalancesTable as payoutFeeBalancesTable,
   claimsTable as payoutReleaseClaimsTable,
   sourcesTable as payoutSourceAllocationsTable,
 } from "./payoutRelease/schema.js";
@@ -36,6 +37,7 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  payoutFeeBalances: payoutFeeBalancesTable,
   payoutReleaseClaims: payoutReleaseClaimsTable,
   payoutSourceAllocations: payoutSourceAllocationsTable,
   payoutPolicies: policiesTable,