@fantastic.dev/better-stripe 0.14.0 → 0.16.0

package/src/component/_generated/component.ts

@@ -882,6 +882,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             arrivalDate?: string;
             currency: string;
+            failureCode?: string;
+            failureMessage?: string;
             metadata?: any;
             method?: string;
             status: "pending" | "paid" | "failed" | "canceled" | "in_transit";
@@ -965,6 +967,41 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               sourceInvoiceId?: string;
               status: "pending" | "paid" | "failed" | "reversed";
               stripeTransferId: string;
+              totalsRecorded?: true;
+            }>;
+          },
+          Name
+        >;
+        getAccountEarningsByCurrency: FunctionReference<
+          "query",
+          "internal",
+          { destinationAccountId: string; previewLimit?: number },
+          {
+            totals: Array<{
+              currency: string;
+              gross: number;
+              net: number;
+              reversed: number;
+              transferCount: number;
+            }>;
+            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
@@ -983,10 +1020,41 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               amount: number;
               arrivalDate?: string;
               currency: string;
+              failureCode?: string;
+              failureMessage?: string;
               metadata?: any;
               method?: string;
               status: "pending" | "paid" | "failed" | "canceled" | "in_transit";
               stripePayoutId: string;
+              totalsRecorded?: true;
+            }>;
+          },
+          Name
+        >;
+        getAccountPayoutsByCurrency: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; previewLimit?: number },
+          {
+            payouts: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId: string;
+              amount: number;
+              arrivalDate?: string;
+              currency: string;
+              failureCode?: string;
+              failureMessage?: string;
+              metadata?: any;
+              method?: string;
+              status: "pending" | "paid" | "failed" | "canceled" | "in_transit";
+              stripePayoutId: string;
+              totalsRecorded?: true;
+            }>;
+            totals: Array<{
+              currency: string;
+              paidOut: number;
+              payoutCount: number;
             }>;
           },
           Name
@@ -1072,10 +1140,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             arrivalDate?: string;
             currency: string;
+            failureCode?: string;
+            failureMessage?: string;
             metadata?: any;
             method?: string;
             status: "pending" | "paid" | "failed" | "canceled" | "in_transit";
             stripePayoutId: string;
+            totalsRecorded?: true;
           } | null,
           Name
         >;
@@ -1090,10 +1161,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             arrivalDate?: string;
             currency: string;
+            failureCode?: string;
+            failureMessage?: string;
             metadata?: any;
             method?: string;
             status: "pending" | "paid" | "failed" | "canceled" | "in_transit";
             stripePayoutId: string;
+            totalsRecorded?: true;
           } | null,
           Name
         >;
@@ -1164,6 +1238,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             sourceInvoiceId?: string;
             status: "pending" | "paid" | "failed" | "reversed";
             stripeTransferId: string;
+            totalsRecorded?: true;
           } | null,
           Name
         >;
@@ -1228,10 +1303,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             amount: number;
             arrivalDate?: string;
             currency: string;
+            failureCode?: string;
+            failureMessage?: string;
             metadata?: any;
             method?: string;
             status: "pending" | "paid" | "failed" | "canceled" | "in_transit";
             stripePayoutId: string;
+            totalsRecorded?: true;
           }>,
           Name
         >;
@@ -1295,6 +1373,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             sourceInvoiceId?: string;
             status: "pending" | "paid" | "failed" | "reversed";
             stripeTransferId: string;
+            totalsRecorded?: true;
           }>,
           Name
         >;
@@ -1319,6 +1398,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             sourceInvoiceId?: string;
             status: "pending" | "paid" | "failed" | "reversed";
             stripeTransferId: string;
+            totalsRecorded?: true;
           }>,
           Name
         >;
@@ -1340,6 +1420,44 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           }>,
           Name
         >;
+        paginatePayouts: FunctionReference<
+          "query",
+          "internal",
+          {
+            accountId: string;
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+            status?: "pending" | "paid" | "failed" | "canceled" | "in_transit";
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId: string;
+              amount: number;
+              arrivalDate?: string;
+              currency: string;
+              failureCode?: string;
+              failureMessage?: string;
+              metadata?: any;
+              method?: string;
+              status: "pending" | "paid" | "failed" | "canceled" | "in_transit";
+              stripePayoutId: string;
+              totalsRecorded?: true;
+            }>;
+            pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+            splitCursor?: string | null;
+          },
+          Name
+        >;
         paginateTransfersByAccount: FunctionReference<
           "query",
           "internal",
@@ -1374,6 +1492,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               sourceInvoiceId?: string;
               status: "pending" | "paid" | "failed" | "reversed";
               stripeTransferId: string;
+              totalsRecorded?: true;
             }>;
             pageStatus?: "SplitRecommended" | "SplitRequired" | null;
             splitCursor?: string | null;
@@ -2064,6 +2183,17 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    earnings: {
+      mutations: {
+        backfillCurrencyTotals: FunctionReference<
+          "mutation",
+          "internal",
+          { cursor: string | null; kind: "earnings" | "payouts" },
+          { continueCursor: string; isDone: boolean },
+          Name
+        >;
+      };
+    };
     products: {
       mutations: {
         upsertPrice: FunctionReference<
@@ -2233,6 +2363,77 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           }>,
           Name
         >;
+        paginatePrices: FunctionReference<
+          "query",
+          "internal",
+          {
+            active?: boolean;
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+            productId?: string;
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              active: boolean;
+              currency: string;
+              interval?: "day" | "week" | "month" | "year";
+              intervalCount?: number;
+              metadata?: any;
+              nickname?: string;
+              productId: string;
+              stripePriceId: string;
+              stripeProductId: string;
+              type: "one_time" | "recurring";
+              unitAmount: number;
+            }>;
+            pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+            splitCursor?: string | null;
+          },
+          Name
+        >;
+        paginateProducts: FunctionReference<
+          "query",
+          "internal",
+          {
+            accountId?: string;
+            active?: boolean;
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId?: string;
+              active: boolean;
+              description?: string;
+              metadata?: any;
+              name: string;
+              stripeProductId: string;
+            }>;
+            pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+            splitCursor?: string | null;
+          },
+          Name
+        >;
       };
     };
     settlement: {

package/src/component/connect/mutations.ts

@@ -1,7 +1,7 @@
 import { v } from "convex/values";
 
 import type { Doc, Id } from "../_generated/dataModel";
-import { mutation } from "../_generated/server";
+import { mutation } from "../earnings/triggers.js";
 import { feeRoutingFields } from "../lib/fees";
 import { computeReversalSlices, deriveReversalState } from "../lib/reversals";
 import { paymentSeller } from "../lib/paymentSeller";
@@ -121,6 +121,8 @@ export const upsertPayout = mutation({
     status: payoutStatusValidator,
     arrivalDate: v.optional(v.string()),
     method: v.optional(v.string()),
+    failureCode: v.optional(v.string()),
+    failureMessage: v.optional(v.string()),
     metadata: v.optional(v.any()),
   },
   returns: v.null(),
@@ -133,7 +135,11 @@ export const upsertPayout = mutation({
       .first();
 
     if (existing) {
-      await ctx.db.patch("payouts", existing._id, args);
+      await ctx.db.patch("payouts", existing._id, {
+        ...args,
+        failureCode: args.failureCode,
+        failureMessage: args.failureMessage,
+      });
     } else {
       await ctx.db.insert("payouts", args);
     }
@@ -142,9 +148,7 @@ export const upsertPayout = mutation({
   },
 });
 
-// =============================================================================
 // REFUND MUTATIONS
-// =============================================================================
 
 export const upsertRefund = mutation({
   args: refundFields,
@@ -283,9 +287,7 @@ export const recordPaymentFeeRefund = mutation({
   },
 });
 
-// =============================================================================
 // DISPUTE MUTATIONS
-// =============================================================================
 
 export const upsertDispute = mutation({
   args: disputeFields,
@@ -311,9 +313,7 @@ export const upsertDispute = mutation({
   },
 });
 
-// =============================================================================
 // TRANSFER MUTATIONS (ledger — BTS-12)
-// =============================================================================
 
 export const upsertTransfer = mutation({
   args: transferFields,

package/src/component/connect/queries.ts

@@ -1,3 +1,8 @@
+import {
+  getAccountEarnings as getAccountEarningsLegacy,
+  getAccountPayouts as getAccountPayoutsLegacy,
+} from "../earnings/legacyReads.js";
+import { currencyTotals, previewSize } from "../earnings/reads.js";
 import { v } from "convex/values";
 import { paginator } from "convex-helpers/server/pagination";
 import schema from "../schema.js";
@@ -21,9 +26,7 @@ import {
   wedgedReversalClaimValidator,
 } from "./validators";
 
-// =============================================================================
 // PAYMENT QUERIES
-// =============================================================================
 
 export const getPaymentByStripeId = query({
   args: { stripePaymentIntentId: v.string() },
@@ -38,9 +41,7 @@ export const getPaymentByStripeId = query({
   },
 });
 
-// =============================================================================
 // PAYOUT QUERIES
-// =============================================================================
 
 export const getPayout = query({
   args: { payoutId: v.id("payouts") },
@@ -111,9 +112,7 @@ export const listPayouts = query({
   },
 });
 
-// =============================================================================
 // REFUND QUERIES
-// =============================================================================
 
 export const getRefundByStripeId = query({
   args: { stripeRefundId: v.string() },
@@ -196,9 +195,7 @@ export const listRefunds = query({
   },
 });
 
-// =============================================================================
 // DISPUTE QUERIES
-// =============================================================================
 
 export const getDisputeByStripeId = query({
   args: { stripeDisputeId: v.string() },
@@ -279,9 +276,7 @@ export const listDisputes = query({
   },
 });
 
-// =============================================================================
 // TRANSFER QUERIES (ledger — BTS-12)
-// =============================================================================
 
 export const getTransferByStripeId = query({
   args: { stripeTransferId: v.string() },
@@ -366,9 +361,7 @@ export const paginateTransfersByAccount = query({
       .paginate(args.paginationOpts),
 });
 
-// =============================================================================
 // REVERSAL-CLAIM RECLAIM (BTS-74) — ops diagnostics for wedged legs
-// =============================================================================
 
 /**
  * Fetch one reversal operation's claim record (BTS-63/74) by its id, or null.
@@ -447,9 +440,7 @@ export const listWedgedReversalClaims = query({
   },
 });
 
-// =============================================================================
 // EARNINGS AGGREGATES (BTS-64)
-// =============================================================================
 //
 // The row-list queries above `.take(50)`, so summing their rows client-side
 // (as the earnings hooks did) silently understated totals for accounts with
@@ -479,27 +470,7 @@ export const getAccountEarnings = query({
     transferCount: v.number(),
     transfers: v.array(transferDocValidator),
   }),
-  handler: async (ctx, args) => {
-    const previewLimit = args.previewLimit ?? 50;
-    let gross = 0;
-    let reversed = 0;
-    let transferCount = 0;
-    const transfers: Doc<"transfers">[] = [];
-
-    for await (const tr of ctx.db
-      .query("transfers")
-      .withIndex("by_destination_account_id", (q) =>
-        q.eq("destinationAccountId", args.destinationAccountId),
-      )
-      .order("desc")) {
-      gross += tr.amount;
-      reversed += tr.reversedAmount ?? 0;
-      transferCount += 1;
-      if (transfers.length < previewLimit) transfers.push(tr);
-    }
-
-    return { gross, reversed, transferCount, transfers };
-  },
+  handler: getAccountEarningsLegacy,
 });
 
 /**
@@ -515,20 +486,111 @@ export const getAccountPayouts = query({
     payoutCount: v.number(),
     payouts: v.array(payoutDocValidator),
   }),
-  handler: async (ctx, args) => {
-    const previewLimit = args.previewLimit ?? 50;
-    let paidOut = 0;
-    let payoutCount = 0;
-    const payouts: Doc<"payouts">[] = [];
+  handler: getAccountPayoutsLegacy,
+});
 
-    for await (const p of ctx.db
-      .query("payouts")
-      .withIndex("by_account_id", (q) => q.eq("accountId", args.accountId))) {
-      payoutCount += 1;
-      if (p.status === "paid") paidOut += p.amount;
-      if (payouts.length < previewLimit) payouts.push(p);
-    }
+/** Reactive, account-scoped history. A page is never a financial total. */
+export const paginatePayouts = query({
+  args: {
+    accountId: v.string(),
+    status: v.optional(payoutStatusValidator),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(payoutDocValidator),
+  handler: (ctx, args) => {
+    if (
+      !Number.isInteger(args.paginationOpts.numItems) ||
+      args.paginationOpts.numItems < 1 ||
+      args.paginationOpts.numItems > 100
+    )
+      throw new Error("Page size must be an integer from 1 to 100");
+    const rows = paginator(ctx.db, schema).query("payouts");
+    const scoped =
+      args.status === undefined
+        ? rows.withIndex("by_account_id", (q) =>
+            q.eq("accountId", args.accountId),
+          )
+        : rows.withIndex("by_account_status", (q) =>
+            q.eq("accountId", args.accountId).eq("status", args.status!),
+          );
+    return scoped.order("desc").paginate({
+      ...args.paginationOpts,
+      maximumRowsRead: 200,
+      maximumBytesRead: 1_000_000,
+    });
+  },
+});
 
-    return { paidOut, payoutCount, payouts };
+export const getAccountEarningsByCurrency = query({
+  args: {
+    destinationAccountId: v.string(),
+    previewLimit: v.optional(v.number()),
+  },
+  returns: v.object({
+    totals: v.array(
+      v.object({
+        currency: v.string(),
+        gross: v.number(),
+        reversed: v.number(),
+        net: v.number(),
+        transferCount: v.number(),
+      }),
+    ),
+    transfers: v.array(transferDocValidator),
+  }),
+  handler: async (ctx, args) => {
+    const limit = previewSize(args.previewLimit);
+    const rows = await currencyTotals(
+      ctx,
+      args.destinationAccountId,
+      "earnings",
+    );
+    const transfers = await ctx.db
+      .query("transfers")
+      .withIndex("by_destination_account_id", (q) =>
+        q.eq("destinationAccountId", args.destinationAccountId),
+      )
+      .order("desc")
+      .take(limit);
+    return {
+      totals: rows.map((r) => ({
+        currency: r.currency,
+        gross: r.gross,
+        reversed: r.reversed,
+        net: r.gross - r.reversed,
+        transferCount: r.count,
+      })),
+      transfers,
+    };
+  },
+});
+export const getAccountPayoutsByCurrency = query({
+  args: { accountId: v.string(), previewLimit: v.optional(v.number()) },
+  returns: v.object({
+    totals: v.array(
+      v.object({
+        currency: v.string(),
+        paidOut: v.number(),
+        payoutCount: v.number(),
+      }),
+    ),
+    payouts: v.array(payoutDocValidator),
+  }),
+  handler: async (ctx, args) => {
+    const limit = previewSize(args.previewLimit);
+    const rows = await currencyTotals(ctx, args.accountId, "payouts");
+    const payouts = await ctx.db
+      .query("payouts")
+      .withIndex("by_account_id", (q) => q.eq("accountId", args.accountId))
+      .order("desc")
+      .take(limit);
+    return {
+      totals: rows.map((r) => ({
+        currency: r.currency,
+        paidOut: r.paidOut,
+        payoutCount: r.count,
+      })),
+      payouts,
+    };
   },
 });

package/src/component/connect/schema.ts

@@ -1,3 +1,4 @@
+import { v } from "convex/values";
 import { defineTable } from "convex/server";
 
 import {
@@ -22,10 +23,14 @@ export const paymentsTable = defineTable(paymentFields)
 /**
  * Payouts to V2 accounts (marketplace).
  */
-export const payoutsTable = defineTable(payoutFields)
+export const payoutsTable = defineTable({
+  ...payoutFields,
+  totalsRecorded: v.optional(v.literal(true)),
+})
   .index("by_stripe_payout_id", ["stripePayoutId"])
   .index("by_account_id", ["accountId"])
   .index("by_status", ["status"])
+  .index("by_account_totals_recorded", ["accountId", "totalsRecorded"])
   .index("by_account_status", ["accountId", "status"]);
 
 /**
@@ -63,6 +68,10 @@ export const transfersTable = defineTable({
   ...transferPersistedFields,
 })
   .index("by_stripe_transfer_id", ["stripeTransferId"])
+  .index("by_account_totals_recorded", [
+    "destinationAccountId",
+    "totalsRecorded",
+  ])
   .index("by_destination_account_id", ["destinationAccountId"])
   .index("by_source_charge_id", ["sourceChargeId"]);
 

package/src/component/connect/validators.ts

@@ -72,6 +72,8 @@ export const payoutFields = {
   status: payoutStatusValidator,
   arrivalDate: v.optional(v.string()),
   method: v.optional(v.string()),
+  failureCode: v.optional(v.string()),
+  failureMessage: v.optional(v.string()),
   metadata: v.optional(v.any()),
 };
 
@@ -80,6 +82,7 @@ export const payoutDocValidator = v.object({
   _id: v.id("payouts"),
   _creationTime: v.number(),
   ...payoutFields,
+  totalsRecorded: v.optional(v.literal(true)),
 });
 
 // =============================================================================
@@ -266,6 +269,7 @@ export const transferFields = {
  * redelivered base payload must not clobber an in-flight reversal claim.
  */
 export const transferPersistedFields = {
+  totalsRecorded: v.optional(v.literal(true)),
   /**
    * Reversal claim frontier (BTS-63): the highest cumulative reversal amount
    * reserved by `claimReversalSlices` before money moves. Always ≥