@fantastic.dev/better-stripe 0.15.0 → 0.17.0

package/src/client/refund-history.test.ts

@@ -0,0 +1,67 @@
+import { componentsGeneric, type FunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+
+import schema from "../component/schema.js";
+import type { Component, RunCtx } from "./helpers.js";
+import { BetterStripe, type RefundPageOptions } from "./index.js";
+import { initConvexTest } from "./setup.test.js";
+
+const modules = import.meta.glob("../component/**/*.{ts,js,tsx,jsx}");
+
+it("reads multiple conjunctively scoped pages through the public client without provider credentials", async () => {
+  const t = initConvexTest();
+  t.registerComponent("betterStripe", schema, modules);
+  const component = componentsGeneric().betterStripe as unknown as Component;
+  const stripe = new BetterStripe(component, {});
+  const ctx = {
+    runQuery: (
+      ref: FunctionReference<"query">,
+      args: Record<string, unknown>,
+    ) => t.query(ref, args),
+  } as unknown as RunCtx;
+  for (let index = 0; index < 5; index++) {
+    await t.mutation(component.connect.mutations.upsertRefund, {
+      stripeRefundId: `re_${index}`,
+      accountId: index === 4 ? "acct_foreign" : "acct_owner",
+      stripePaymentIntentId: index === 3 ? "pi_foreign" : "pi_original",
+      stripeChargeId: "ch_original",
+      amount: 500,
+      currency: "jpy",
+      status: "succeeded",
+    });
+  }
+  const opts: RefundPageOptions = {
+    stripeAccountId: "acct_owner",
+    stripePaymentIntentId: "pi_original",
+    status: "succeeded",
+    paginationOpts: { numItems: 2, cursor: null },
+  };
+  const first = await stripe.paginateRefunds(ctx, opts);
+  expect(first.page).toHaveLength(2);
+  expect(first.isDone).toBe(false);
+  const last = await stripe.paginateRefunds(ctx, {
+    ...opts,
+    paginationOpts: { numItems: 2, cursor: first.continueCursor },
+  });
+  expect(last.isDone).toBe(true);
+  expect([...first.page, ...last.page]).toHaveLength(3);
+  for (const refund of [...first.page, ...last.page]) {
+    expect(refund).toMatchObject({
+      accountId: "acct_owner",
+      stripePaymentIntentId: "pi_original",
+      stripeChargeId: "ch_original",
+      amount: 500,
+      currency: "jpy",
+      status: "succeeded",
+    });
+  }
+  expect(
+    await stripe.paginateRefunds(ctx, {
+      ...opts,
+      stripeAccountId: "acct_absent",
+    }),
+  ).toMatchObject({ page: [], isDone: true });
+  expect(
+    await stripe.listRefunds(ctx, { stripeAccountId: "acct_owner", limit: 1 }),
+  ).toHaveLength(1);
+});

package/src/client/types/documents.ts

@@ -124,6 +124,8 @@ export type StripeComponentPayout = {
   status: PayoutStatus;
   arrivalDate?: string;
   method?: string;
+  failureCode?: string;
+  failureMessage?: string;
   metadata?: Record<string, unknown>;
 };
 

package/src/client/webhooks/payout-canceled.integration.test.ts

@@ -190,3 +190,28 @@ it.each([
     expect(transport).not.toHaveBeenCalled();
   },
 );
+
+it("persists signed failure details and clears them on a later snapshot", async () => {
+  const f = fixture("payout.failed", "failed");
+  f.event.data.object.failure_code = "account_closed";
+  f.event.data.object.failure_message = "Bank account closed";
+  expect((await f.deliver()).status).toBe(200);
+  const failed = await f.payout();
+  expect(failed).toMatchObject({
+    failureCode: "account_closed",
+    failureMessage: "Bank account closed",
+    accountId: "acct_qa_recipient",
+  });
+  expect((await f.deliver()).body).toMatchObject({ deduplicated: true });
+  expect(await f.payout()).toEqual(failed);
+  f.event.id = "evt_failure_cleared";
+  f.event.type = "payout.updated";
+  f.event.data.object.status = "pending";
+  f.event.data.object.failure_code = null;
+  f.event.data.object.failure_message = null;
+  expect((await f.deliver()).status).toBe(200);
+  const cleared = await f.payout();
+  expect(cleared?._id).toBe(failed?._id);
+  expect(cleared).not.toHaveProperty("failureCode");
+  expect(cleared).not.toHaveProperty("failureMessage");
+});

package/src/client/webhooks/processors.ts

@@ -921,6 +921,8 @@ async function handlePayoutEvent(
       "pending" | "paid" | "failed" | "canceled" | "in_transit",
     arrivalDate: epochToIso(payout.arrival_date),
     method: payout.method ?? undefined,
+    failureCode: payout.failure_code ?? undefined,
+    failureMessage: payout.failure_message ?? undefined,
     metadata: payout.metadata ?? undefined,
   });
 }

package/src/component/_generated/api.ts

@@ -24,6 +24,10 @@ import type * as costRecovery_imports from "../costRecovery/imports.js";
 import type * as costRecovery_mutations from "../costRecovery/mutations.js";
 import type * as costRecovery_queries from "../costRecovery/queries.js";
 import type * as costRecovery_reservations from "../costRecovery/reservations.js";
+import type * as earnings_legacyReads from "../earnings/legacyReads.js";
+import type * as earnings_mutations from "../earnings/mutations.js";
+import type * as earnings_reads from "../earnings/reads.js";
+import type * as earnings_triggers from "../earnings/triggers.js";
 import type * as lib_fees from "../lib/fees.js";
 import type * as lib_idempotency from "../lib/idempotency.js";
 import type * as lib_paymentSeller from "../lib/paymentSeller.js";
@@ -32,6 +36,7 @@ import type * as lib_stripeFactory from "../lib/stripeFactory.js";
 import type * as products_mutations from "../products/mutations.js";
 import type * as products_queries from "../products/queries.js";
 import type * as products_validators from "../products/validators.js";
+import type * as refundHistory_queries from "../refundHistory/queries.js";
 import type * as settlement_mutations from "../settlement/mutations.js";
 import type * as settlement_queries from "../settlement/queries.js";
 import type * as webhooks_mutations from "../webhooks/mutations.js";
@@ -62,6 +67,10 @@ const fullApi: ApiFromModules<{
   "costRecovery/mutations": typeof costRecovery_mutations;
   "costRecovery/queries": typeof costRecovery_queries;
   "costRecovery/reservations": typeof costRecovery_reservations;
+  "earnings/legacyReads": typeof earnings_legacyReads;
+  "earnings/mutations": typeof earnings_mutations;
+  "earnings/reads": typeof earnings_reads;
+  "earnings/triggers": typeof earnings_triggers;
   "lib/fees": typeof lib_fees;
   "lib/idempotency": typeof lib_idempotency;
   "lib/paymentSeller": typeof lib_paymentSeller;
@@ -70,6 +79,7 @@ const fullApi: ApiFromModules<{
   "products/mutations": typeof products_mutations;
   "products/queries": typeof products_queries;
   "products/validators": typeof products_validators;
+  "refundHistory/queries": typeof refundHistory_queries;
   "settlement/mutations": typeof settlement_mutations;
   "settlement/queries": typeof settlement_queries;
   "webhooks/mutations": typeof webhooks_mutations;

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,133 @@ 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
+        >;
+      };
+    };
+    refundHistory: {
+      queries: {
+        paginateRefunds: FunctionReference<
+          "query",
+          "internal",
+          {
+            accountId?: string;
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+            status?:
+              | "pending"
+              | "requires_action"
+              | "succeeded"
+              | "failed"
+              | "canceled";
+            stripePaymentIntentId?: string;
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              accountId?: string;
+              amount: number;
+              currency: string;
+              failureReason?: string;
+              metadata?: any;
+              reason?:
+                | "duplicate"
+                | "fraudulent"
+                | "requested_by_customer"
+                | "expired_uncaptured_charge";
+              status:
+                | "pending"
+                | "requires_action"
+                | "succeeded"
+                | "failed"
+                | "canceled";
+              stripeChargeId?: string;
+              stripePaymentIntentId?: string;
+              stripeRefundId: 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,