@fantastic.dev/better-stripe 0.20.1 → 0.22.0

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";
@@ -30,6 +31,7 @@ export const claim = mutation({
     ...identity,
     expectedRevision: v.number(),
     currency: v.string(),
+    destinationId: v.optional(v.string()),
     providerAvailable: v.number(),
     independentLiabilities: v.number(),
     observations: v.array(observation),
@@ -37,11 +39,17 @@ export const claim = mutation({
   returns: v.union(claimDoc, held),
   handler: async (ctx, args) => {
     validateIdentity(args);
+    if (
+      args.destinationId !== undefined &&
+      !/^ba_\w+$/.test(args.destinationId)
+    )
+      throw new Error("Invalid payout bank destination.");
     const existing = await claimByKey(ctx, args);
     if (existing) {
       if (
         existing.currency !== args.currency ||
-        existing.expectedRevision !== args.expectedRevision
+        existing.expectedRevision !== args.expectedRevision ||
+        existing.destinationId !== args.destinationId
       )
         throw new Error("Payout claim identity cannot be reused.");
       return existing;
@@ -88,11 +96,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;
@@ -119,8 +129,10 @@ export const claim = mutation({
       expectedRevision: args.expectedRevision,
       currency: args.currency,
       amount: plan.amount,
+      ...(args.destinationId ? { destinationId: args.destinationId } : {}),
       allocations: plan.allocations,
       observations: args.observations,
+      feeRevision: fees?.revision ?? 0,
       status: "reserved",
     });
     return (await ctx.db.get("payoutReleaseClaims", id))!;
@@ -135,6 +147,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 +190,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 +244,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,5 @@
+import { transferDocValidator } from "../connect/validators.js";
+import { readFees } from "./fees.js";
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 import { query } from "../_generated/server.js";
@@ -54,3 +56,47 @@ 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 };
+  },
+});
+
+/** Complete bounded input for package qualification. Partial membership never qualifies. */
+export const snapshot = query({
+  args: { accountId: v.string(), ownerKey: v.string() },
+  returns: v.union(
+    v.object({
+      status: v.literal("held"),
+      reason: v.literal("snapshot_limit"),
+    }),
+    v.object({
+      status: v.literal("ready"),
+      transfers: v.array(transferDocValidator),
+      claims: v.array(claimDoc),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    await readPolicy(ctx, args);
+    const transfers = await ctx.db
+      .query("transfers")
+      .withIndex("by_destination_account_id", (q) =>
+        q.eq("destinationAccountId", args.accountId),
+      )
+      .take(101);
+    const claims = await ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
+      .take(101);
+    if (transfers.length > 100 || claims.length > 100)
+      return { status: "held" as const, reason: "snapshot_limit" as const };
+    if (claims.some((c) => c.ownerKey !== args.ownerKey))
+      throw new Error("Payout history owner does not match.");
+    return { status: "ready" as const, transfers, claims };
+  },
+});

package/src/component/payoutRelease/schema.ts

@@ -23,6 +23,7 @@ export const claimFields = {
   expectedRevision: v.number(),
   currency: v.string(),
   amount: v.number(),
+  destinationId: v.optional(v.string()),
   allocations: v.array(allocation),
   observations: v.array(observation),
   status: v.union(
@@ -36,6 +37,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 +60,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 +73,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,