@fantastic.dev/better-stripe 0.16.0 → 0.17.0

package/src/client/connect/refunds.ts

@@ -1,4 +1,5 @@
 import type Stripe from "stripe";
+import type { PaginationOptions, PaginationResult } from "convex/server";
 
 import type { RefundStatus } from "../../component/connect/validators.js";
 import { throwStripeError } from "../errors.js";
@@ -12,6 +13,33 @@ import { type RefundActor, isRefundAuthorized } from "./refundActor.js";
 
 export type { RefundActor } from "./refundActor.js";
 
+export type RefundListOptions = {
+  stripeAccountId?: string;
+  stripePaymentIntentId?: string;
+  status?: RefundStatus;
+  limit?: number;
+};
+
+export type RefundPageOptions = Omit<RefundListOptions, "limit"> & {
+  paginationOpts: PaginationOptions;
+};
+
+/** The host must authenticate/authorize scopes before exposing this reactive reader. */
+export async function paginateRefunds(
+  component: Component,
+  ctx: RunCtx,
+  opts: RefundPageOptions,
+): Promise<PaginationResult<StripeComponentRefund>> {
+  const { stripeAccountId, ...rest } = opts;
+  return await ctx.runQuery(
+    componentRef(component, "refundHistory/queries/paginateRefunds"),
+    {
+      ...rest,
+      ...(stripeAccountId !== undefined ? { accountId: stripeAccountId } : {}),
+    },
+  );
+}
+
 // =============================================================================
 // Refund methods
 // =============================================================================

package/src/client/index.ts

@@ -79,7 +79,6 @@ import type { ComponentApi } from "../component/_generated/component.js";
 import type {
   DisputeStatus,
   PayoutStatus,
-  RefundStatus,
 } from "../component/connect/validators.js";
 import type { SplitRecipient } from "../component/lib/fees.js";
 import * as checkoutImpl from "./billing/checkout.js";
@@ -89,6 +88,7 @@ import * as disputesImpl from "./connect/disputes.js";
 import * as paymentMethodsImpl from "./connect/paymentMethods.js";
 import * as payoutsImpl from "./connect/payouts.js";
 import * as refundsImpl from "./connect/refunds.js";
+export type { RefundPageOptions } from "./connect/refunds.js";
 import * as transfersImpl from "./connect/transfers.js";
 import * as accountLinksImpl from "./core/accountLinks.js";
 import * as accountsImpl from "./core/accounts.js";
@@ -1360,16 +1360,15 @@ export class BetterStripe extends ReadContractClient {
 
   async listRefunds(
     ctx: RunCtx,
-    opts?: {
-      stripeAccountId?: string;
-      stripePaymentIntentId?: string;
-      status?: RefundStatus;
-      limit?: number;
-    },
+    opts?: refundsImpl.RefundListOptions,
   ): Promise<StripeComponentRefund[]> {
     return refundsImpl.listRefunds(this.component, ctx, opts);
   }
 
+  paginateRefunds(ctx: RunCtx, opts: refundsImpl.RefundPageOptions) {
+    return refundsImpl.paginateRefunds(this.component, ctx, opts);
+  }
+
   // DISPUTE METHODS
 
   async getDisputeByStripeId(

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/component/_generated/api.ts

@@ -36,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";
@@ -78,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

@@ -2436,6 +2436,62 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    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: {
       mutations: {
         claimCommissionInvoice: FunctionReference<

package/src/component/connect/schema.ts

@@ -54,6 +54,15 @@ export const refundsTable = defineTable(refundFields)
   .index("by_account_id", ["accountId"])
   .index("by_status", ["status"])
   .index("by_account_id_and_status", ["accountId", "status"])
+  .index("by_account_id_and_stripe_payment_intent_id", [
+    "accountId",
+    "stripePaymentIntentId",
+  ])
+  .index("by_account_id_and_stripe_payment_intent_id_and_status", [
+    "accountId",
+    "stripePaymentIntentId",
+    "status",
+  ])
   .index("by_payment_intent_id_and_status", [
     "stripePaymentIntentId",
     "status",

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

@@ -0,0 +1,198 @@
+import { convexTest } from "convex-test";
+import { afterEach, expect, it, vi } from "vitest";
+
+import { api } from "./_generated/api.js";
+import schema from "./schema.js";
+
+const modules = import.meta.glob("./**/*.*s");
+const paginate = api.refundHistory.queries.paginateRefunds;
+afterEach(() => vi.useRealTimers());
+const rows = [
+  {
+    stripeRefundId: "re_a1",
+    accountId: "acct_a",
+    stripePaymentIntentId: "pi_a",
+    status: "succeeded",
+    currency: "jpy",
+    amount: 500,
+  },
+  {
+    stripeRefundId: "re_a2",
+    accountId: "acct_a",
+    stripePaymentIntentId: "pi_a",
+    status: "pending",
+    currency: "isk",
+    amount: 500,
+  },
+  {
+    stripeRefundId: "re_a3",
+    accountId: "acct_a",
+    stripePaymentIntentId: "pi_b",
+    status: "succeeded",
+    currency: "usd",
+    amount: 100,
+  },
+  {
+    stripeRefundId: "re_b1",
+    accountId: "acct_b",
+    stripePaymentIntentId: "pi_a",
+    status: "succeeded",
+    currency: "eur",
+    amount: 200,
+  },
+  {
+    stripeRefundId: "re_b2",
+    accountId: "acct_b",
+    stripePaymentIntentId: "pi_only_b",
+    status: "failed",
+    currency: "usd",
+    amount: 300,
+  },
+] as const;
+
+async function fixture() {
+  const t = convexTest(schema, modules);
+  vi.useFakeTimers();
+  for (const [index, row] of rows.entries()) {
+    vi.setSystemTime(1800000000000 + index * 1000);
+    await t.mutation(api.connect.mutations.upsertRefund, {
+      ...row,
+      stripeChargeId: `ch_${index}`,
+    });
+  }
+  return t;
+}
+
+it("walks every original refund over bounded newest-first pages and replays a cursor", async () => {
+  const t = await fixture();
+  const first = await t.query(paginate, {
+    paginationOpts: { numItems: 2, cursor: null },
+  });
+  expect(
+    first.page.map((row: { stripeRefundId: string }) => row.stripeRefundId),
+  ).toEqual(["re_b2", "re_b1"]);
+  expect(first.isDone).toBe(false);
+  const args = {
+    paginationOpts: { numItems: 2, cursor: first.continueCursor },
+  };
+  const second = await t.query(paginate, args);
+  expect(await t.query(paginate, args)).toEqual(second);
+  const last = await t.query(paginate, {
+    paginationOpts: { numItems: 2, cursor: second.continueCursor },
+  });
+  expect(last.isDone).toBe(true);
+  expect(
+    [...first.page, ...second.page, ...last.page].map((row) => ({
+      stripeRefundId: row.stripeRefundId,
+      accountId: row.accountId,
+      stripePaymentIntentId: row.stripePaymentIntentId,
+      status: row.status,
+      currency: row.currency,
+      amount: row.amount,
+    })),
+  ).toEqual([...rows].reverse());
+  expect(last.page[0].stripeChargeId).toBe("ch_0");
+});
+
+it.each([
+  [{ accountId: "acct_a" }, ["re_a3", "re_a2", "re_a1"]],
+  [{ stripePaymentIntentId: "pi_a" }, ["re_b1", "re_a2", "re_a1"]],
+  [{ status: "succeeded" }, ["re_b1", "re_a3", "re_a1"]],
+  [{ accountId: "acct_a", status: "succeeded" }, ["re_a3", "re_a1"]],
+  [{ stripePaymentIntentId: "pi_a", status: "succeeded" }, ["re_b1", "re_a1"]],
+  [{ accountId: "acct_a", stripePaymentIntentId: "pi_a" }, ["re_a2", "re_a1"]],
+  [
+    { accountId: "acct_a", stripePaymentIntentId: "pi_a", status: "succeeded" },
+    ["re_a1"],
+  ],
+  [{ accountId: "acct_a", stripePaymentIntentId: "pi_only_b" }, []],
+  [
+    {
+      accountId: "acct_a",
+      stripePaymentIntentId: "pi_only_b",
+      status: "failed",
+    },
+    [],
+  ],
+] as const)(
+  "applies every supplied scope conjunctively: %j",
+  async (scope, expected) => {
+    const t = await fixture();
+    const result = await t.query(paginate, {
+      ...scope,
+      paginationOpts: { numItems: 100, cursor: null },
+    });
+    expect(
+      result.page.map((row: { stripeRefundId: string }) => row.stripeRefundId),
+    ).toEqual(expected);
+    expect(result.isDone).toBe(true);
+  },
+);
+
+it.each([0, -1, 1.5, 101, Number.NaN, Number.POSITIVE_INFINITY])(
+  "rejects invalid page size %s",
+  async (numItems) => {
+    const t = convexTest(schema, modules);
+    await expect(
+      t.query(paginate, { paginationOpts: { numItems, cursor: null } }),
+    ).rejects.toThrow(/page size/i);
+  },
+);
+
+it("returns a completed empty page on empty history", async () => {
+  const t = convexTest(schema, modules);
+  expect(
+    await t.query(paginate, { paginationOpts: { numItems: 1, cursor: null } }),
+  ).toMatchObject({
+    page: [],
+    isDone: true,
+    continueCursor: expect.any(String),
+  });
+});
+
+it("pins reactive refund ranges and splits growth before bounded read limits", async () => {
+  const t = await fixture();
+  const scope = { accountId: "acct_a" };
+  const first = await t.query(paginate, {
+    ...scope,
+    paginationOpts: { numItems: 2, cursor: null },
+  });
+  const second = await t.query(paginate, {
+    ...scope,
+    paginationOpts: { numItems: 2, cursor: first.continueCursor },
+  });
+  vi.setSystemTime(1800000010000);
+  await t.mutation(api.connect.mutations.upsertRefund, {
+    stripeRefundId: "re_new",
+    ...scope,
+    amount: 500,
+    currency: "jpy",
+    status: "pending",
+  });
+  const paginationOpts = {
+    numItems: 2,
+    cursor: null,
+    endCursor: first.continueCursor,
+  };
+  const pinned = await t.query(paginate, { ...scope, paginationOpts });
+  expect(pinned.page).toHaveLength(3);
+  expect(
+    new Set([...pinned.page, ...second.page].map((row) => row.stripeRefundId))
+      .size,
+  ).toBe(4);
+  for (let index = 0; index < 205; index++) {
+    vi.setSystemTime(1800000020000 + index * 1000);
+    await t.mutation(api.connect.mutations.upsertRefund, {
+      stripeRefundId: `re_growth_${index}`,
+      ...scope,
+      amount: 500,
+      currency: "jpy",
+      status: "succeeded",
+    });
+  }
+  const grown = await t.query(paginate, { ...scope, paginationOpts });
+  expect(grown.page).toHaveLength(200);
+  expect(grown.pageStatus).toBe("SplitRequired");
+  expect(grown.splitCursor).toBeTruthy();
+  expect(grown.page.every((row) => row.accountId === "acct_a")).toBe(true);
+});

package/src/component/refundHistory/queries.ts

@@ -0,0 +1,99 @@
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
+import { v } from "convex/values";
+import { paginator } from "convex-helpers/server/pagination";
+
+import { query, type QueryCtx } from "../_generated/server.js";
+import schema from "../schema.js";
+import {
+  refundDocValidator,
+  refundStatusValidator,
+  type RefundStatus,
+} from "../connect/validators.js";
+
+/** Host-authorized scopes are conjunctive; use the package React pagination binding. */
+export const paginateRefunds = query({
+  args: {
+    accountId: v.optional(v.string()),
+    stripePaymentIntentId: v.optional(v.string()),
+    status: v.optional(refundStatusValidator),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(refundDocValidator),
+  handler: (ctx, args) => {
+    const { paginationOpts } = args;
+    if (
+      !Number.isSafeInteger(paginationOpts.numItems) ||
+      paginationOpts.numItems < 1 ||
+      paginationOpts.numItems > 100
+    )
+      throw new Error(
+        "Refund history page size must be an integer from 1 to 100",
+      );
+    return scopedRefunds(ctx, args)
+      .order("desc")
+      .paginate({
+        ...paginationOpts,
+        maximumRowsRead: 200,
+        maximumBytesRead: 1_000_000,
+      });
+  },
+});
+
+function scopedRefunds(
+  ctx: QueryCtx,
+  args: {
+    accountId?: string;
+    stripePaymentIntentId?: string;
+    status?: RefundStatus;
+  },
+) {
+  const { accountId, stripePaymentIntentId, status } = args;
+  const refunds = paginator(ctx.db, schema).query("refunds");
+  if (
+    accountId !== undefined &&
+    stripePaymentIntentId !== undefined &&
+    status === undefined
+  )
+    return refunds.withIndex(
+      "by_account_id_and_stripe_payment_intent_id",
+      (q) =>
+        q
+          .eq("accountId", accountId)
+          .eq("stripePaymentIntentId", stripePaymentIntentId),
+    );
+  if (
+    accountId !== undefined &&
+    stripePaymentIntentId !== undefined &&
+    status !== undefined
+  )
+    return refunds.withIndex(
+      "by_account_id_and_stripe_payment_intent_id_and_status",
+      (q) =>
+        q
+          .eq("accountId", accountId)
+          .eq("stripePaymentIntentId", stripePaymentIntentId)
+          .eq("status", status),
+    );
+  if (accountId !== undefined && status !== undefined)
+    return refunds.withIndex("by_account_id_and_status", (q) =>
+      q.eq("accountId", accountId).eq("status", status),
+    );
+  if (stripePaymentIntentId !== undefined && status !== undefined)
+    return refunds.withIndex("by_payment_intent_id_and_status", (q) =>
+      q.eq("stripePaymentIntentId", stripePaymentIntentId).eq("status", status),
+    );
+  if (accountId !== undefined)
+    return refunds.withIndex("by_account_id", (q) =>
+      q.eq("accountId", accountId),
+    );
+  if (stripePaymentIntentId !== undefined)
+    return refunds.withIndex("by_stripe_payment_intent_id", (q) =>
+      q.eq("stripePaymentIntentId", stripePaymentIntentId),
+    );
+  if (status !== undefined)
+    return refunds.withIndex("by_status", (q) => q.eq("status", status));
+  return refunds;
+}

package/src/react/workflows/Costs.test.tsx

@@ -39,3 +39,24 @@ it("renders chargeback economics and explicitly handles missing charge links", (
   expect(screen.getByText("$80.00")).toBeTruthy();
   expect(screen.getByText("No transfer rows found.")).toBeTruthy();
 });
+it("distinguishes reserved recovery from money already collected", () => {
+  render(
+    <CostRecovery
+      rows={[
+        {
+          paymentIntentId: "pi_reserved",
+          amountDue: 1000,
+          collectedAmount: 400,
+          invoicedAmount: 999,
+          reservedAmount: 300,
+          outstanding: 300,
+          currency: "usd",
+        },
+      ]}
+    />,
+  );
+  expect(screen.getByText("Collected")).toBeTruthy();
+  expect(screen.getByText("Reserved")).toBeTruthy();
+  expect(screen.queryByText("$9.99")).toBeNull();
+  expect(screen.getAllByText("$3.00")).toHaveLength(2);
+});

package/src/react/workflows/Costs.tsx

@@ -10,24 +10,30 @@ export type CostRecoveryRow = {
   amountDue: number;
   collectedAmount: number;
   invoicedAmount: number;
+  reservedAmount?: number;
   outstanding: number;
   currency: string;
 };
 export function CostRecovery(props: ResourceCollectionProps<CostRecoveryRow>) {
+  const reserved = props.rows?.some((row) => row.reservedAmount !== undefined);
   const columns: WorkflowColumn<CostRecoveryRow>[] = [
     { id: "payment", label: "Payment", cell: (row) => row.paymentIntentId },
     ...(
       [
         ["amountDue", "Total cost"],
-        ["collectedAmount", "Deducted from earnings"],
-        ["invoicedAmount", "Added to invoice"],
+        ["collectedAmount", reserved ? "Collected" : "Deducted from earnings"],
+        [
+          reserved ? "reservedAmount" : "invoicedAmount",
+          reserved ? "Reserved" : "Added to invoice",
+        ],
         ["outstanding", "Outstanding"],
       ] as const
     ).map(([field, label]) => ({
       id: field,
       label,
       align: "end" as const,
-      cell: (row: CostRecoveryRow) => formatPrice(row[field], row.currency),
+      cell: (row: CostRecoveryRow) =>
+        formatPrice(row[field] ?? row.invoicedAmount, row.currency),
     })),
   ];
   return (