feat(api): implement server-side pagination on list endpoints

Author: MJ-RWA

backend/src/index.ts

@@ -29,7 +29,6 @@ import {
   softDeleteCampaign,
   reconcileOnChainPledge,
   refundContributor,
-  updateCampaign,
 } from "./services/campaignStore";
 import { checkDbHealth } from "./services/db";
 import { getCampaignHistory } from "./services/eventHistory";
@@ -46,7 +45,6 @@ import {
   parsePledgeListPaginationQuery,
   reconcilePledgePayloadSchema,
   refundPayloadSchema,
-  updateCampaignPayloadSchema,
   zodIssuesToErrorMessage,
   zodIssuesToValidationIssues,
 } from "./validation/schemas";
@@ -245,30 +243,28 @@ app.get("/api/health", (_req: Request, res: Response) => {
 app.get("/api/campaigns", (req: Request, res: Response) => {
   const paginationResult = parseCampaignListPaginationQuery({
     page: req.query.page,
-    limit: req.query.limit,
+    pageSize: req.query.pageSize,
   });
   if (!paginationResult.ok) {
     sendValidationError(paginationResult.issues);
   }
 
-    const filters = parseCampaignListFilters({
-      asset: req.query.asset,
-      status: req.query.status,
-      q: req.query.q,
-      search: req.query.search,
-      includeDeleted: req.query.includeDeleted,
-    });
+  const filters = parseCampaignListFilters({
+    asset: req.query.asset,
+    status: req.query.status,
+    q: req.query.q,
+    search: req.query.search,
+    includeDeleted: req.query.includeDeleted,
+  });
 
   const listOptions: ListCampaignsOptions = {
     searchQuery: filters.searchQuery,
     assetCode: filters.asset,
     status: filters.status,
     includeDeleted: filters.includeDeleted,
+    page: paginationResult.page,
+    limit: paginationResult.pageSize,
   };
-  if (paginationResult.page !== undefined) {
-    listOptions.page = paginationResult.page;
-    listOptions.limit = paginationResult.limit;
-  }
 
   const { campaigns, totalCount } = listCampaigns(listOptions);
 
@@ -280,21 +276,14 @@ app.get("/api/campaigns", (req: Request, res: Response) => {
     filters,
   );
 
-  const page = paginationResult.page ?? 1;
-  const limit = paginationResult.limit ?? totalCount;
-  const totalPages =
-    paginationResult.limit === undefined || limit <= 0
-      ? 1
-      : Math.max(1, Math.ceil(totalCount / limit));
+  const hasMore = paginationResult.page * paginationResult.pageSize < totalCount;
 
   res.json({
     data,
-    pagination: {
-      total: totalCount,
-      page,
-      limit,
-      totalPages,
-    },
+    total: totalCount,
+    page: paginationResult.page,
+    pageSize: paginationResult.pageSize,
+    hasMore,
   });
 });
 

backend/src/services/campaignStore.ts

@@ -348,10 +348,9 @@ export function listCampaigns(
   options?: ListCampaignsOptions,
 ): ListCampaignsResult {
   const db = getDb();
-  const paginate = options?.page !== undefined && options?.limit !== undefined;
   const page = options?.page ?? 1;
-  const limit = options?.limit ?? 10;
-  const offset = paginate ? (page - 1) * limit : 0;
+  const limit = options?.limit ?? 20;
+  const offset = (page - 1) * limit;
 
   const whereClauses: string[] = [];
   const params: any[] = [];
@@ -408,14 +407,8 @@ export function listCampaigns(
     db.prepare(countQuery).get(...params) as { total: number }
   ).total;
 
-  const dataQuery = paginate
-    ? `SELECT * ${baseQuery} ORDER BY created_at DESC LIMIT ? OFFSET ?`
-    : `SELECT * ${baseQuery} ORDER BY created_at DESC`;
-  const rows = (
-    paginate
-      ? db.prepare(dataQuery).all(...params, limit, offset)
-      : db.prepare(dataQuery).all(...params)
-  ) as CampaignRow[];
+  const dataQuery = `SELECT * ${baseQuery} ORDER BY created_at DESC LIMIT ? OFFSET ?`;
+  const rows = db.prepare(dataQuery).all(...params, limit, offset) as CampaignRow[];
 
   return {
     campaigns: rows.map(rowToCampaign),

backend/src/validation/schemas.ts

@@ -161,35 +161,18 @@ function parsePositiveIntegerQueryParam(
 }
 
 /**
- * Parses optional `page` and `limit` for GET /api/campaigns.
- * Omitting both means no pagination (caller lists the full filtered set).
- * Supplying only one is invalid (400).
+ * Parses optional `page` and `pageSize` for GET /api/campaigns.
+ * Defaults: page=1, pageSize=20. Max pageSize=100.
  */
 export function parseCampaignListPaginationQuery(query: {
   page?: unknown;
-  limit?: unknown;
-}): { ok: true; page?: number; limit?: number } | { ok: false; issues: z.core.$ZodIssue[] } {
+  pageSize?: unknown;
+}): { ok: true; page: number; pageSize: number } | { ok: false; issues: z.core.$ZodIssue[] } {
   const pageStr = singleCampaignListQueryParam(query.page);
-  const limitStr = singleCampaignListQueryParam(query.limit);
-
-  if (pageStr === undefined && limitStr === undefined) {
-    return { ok: true };
-  }
-  if (pageStr === undefined || limitStr === undefined) {
-    return {
-      ok: false,
-      issues: [
-        {
-          code: "custom",
-          message: "Pagination requires both page and limit query parameters.",
-          path: pageStr === undefined ? ["page"] : ["limit"],
-        },
-      ],
-    };
-  }
+  const pageSizeStr = singleCampaignListQueryParam(query.pageSize);
 
-  const pageNum = Number(pageStr);
-  const limitNum = Number(limitStr);
+  const pageNum = pageStr ? Number(pageStr) : 1;
+  const pageSizeNum = pageSizeStr ? Number(pageSizeStr) : 20;
   const issues: z.core.$ZodIssue[] = [];
 
   if (!Number.isFinite(pageNum) || !Number.isInteger(pageNum) || pageNum < 1) {
@@ -200,23 +183,23 @@ export function parseCampaignListPaginationQuery(query: {
     });
   }
   if (
-    !Number.isFinite(limitNum) ||
-    !Number.isInteger(limitNum) ||
-    limitNum < 1 ||
-    limitNum > 100
+    !Number.isFinite(pageSizeNum) ||
+    !Number.isInteger(pageSizeNum) ||
+    pageSizeNum < 1 ||
+    pageSizeNum > 100
   ) {
     issues.push({
       code: "custom",
-      message: "limit must be an integer from 1 to 100.",
-      path: ["limit"],
+      message: "pageSize must be an integer from 1 to 100.",
+      path: ["pageSize"],
     });
   }
 
   if (issues.length > 0) {
     return { ok: false, issues };
   }
 
-  return { ok: true, page: pageNum, limit: limitNum };
+  return { ok: true, page: pageNum, pageSize: pageSizeNum };
 }
 
 export function parsePledgeListPaginationQuery(query: {

backend/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ES2020",
-    "module": "commonjs",
-    "moduleResolution": "node",
+    "module": "node16",
+    "moduleResolution": "node16",
     "lib": ["ES2020"],
     "outDir": "./dist",
     "rootDir": "./src",

frontend/src/App.tsx

@@ -25,6 +25,7 @@ import {
   reconcilePledge,
   refundCampaign,
   softDeleteCampaign,
+  CampaignListResponse,
 } from "./services/api";
 import {
   submitFreighterClaim,
@@ -123,6 +124,7 @@ function App() {
   const connectedWallet = freighter.publicKey;
 
   const [campaigns, setCampaigns] = useState<Campaign[]>([]);
+  const [campaignsPagination, setCampaignsPagination] = useState<{ total: number; page: number; pageSize: number; hasMore: boolean }>({ total: 0, page: 1, pageSize: 20, hasMore: false });
   const [issues, setIssues] = useState<OpenIssue[]>([]);
   const [history, setHistory] = useState<CampaignEvent[]>([]);
   const [appConfig, setAppConfig] = useState<AppConfig | null>(null);
@@ -189,16 +191,22 @@ function App() {
     };
   }, [transactionPreview]);
 
-  async function refreshCampaigns(searchQuery: string = '', nextSelectedId?: string | null): Promise<Campaign[]> {
+  async function refreshCampaigns(searchQuery: string = '', nextSelectedId?: string | null, page: number = 1): Promise<Campaign[]> {
     setIsCampaignsLoading(true);
     try {
-      const data = await listCampaigns({ search: searchQuery });
-      setCampaigns(data);
+      const response = await listCampaigns({ search: searchQuery, page, pageSize: 20 });
+      setCampaigns(response.data);
+      setCampaignsPagination({
+        total: response.total,
+        page: response.page,
+        pageSize: response.pageSize,
+        hasMore: response.hasMore,
+      });
 
       const requestedId = nextSelectedId ?? selectedCampaignId;
-      const nextId = requestedId ?? data[0]?.id ?? null;
-      const exists = nextId ? data.some((campaign) => campaign.id === nextId) : false;
-      const resolvedId = exists ? nextId : data[0]?.id ?? null;
+      const nextId = requestedId ?? response.data[0]?.id ?? null;
+      const exists = nextId ? response.data.some((campaign) => campaign.id === nextId) : false;
+      const resolvedId = exists ? nextId : response.data[0]?.id ?? null;
 
       setInvalidUrlCampaignId(requestedId && !exists ? requestedId : null);
       setSelectedCampaignId(resolvedId);
@@ -208,7 +216,7 @@ function App() {
         setHistory([]);
       }
 
-      return data;
+      return response.data;
     } finally {
       setIsCampaignsLoading(false);
     }
@@ -253,7 +261,7 @@ function App() {
       const [configResult, issuesResult, campaignsResult] = await Promise.allSettled([
         getAppConfig(),
         listOpenIssues(),
-        listCampaigns({ search: '' }),
+        listCampaigns({ search: '', page: 1, pageSize: 20 }),
       ]);
 
       if (cancelled) {
@@ -271,12 +279,18 @@ function App() {
       }
 
       if (campaignsResult.status === "fulfilled") {
-        const data = campaignsResult.value;
-        setCampaigns(data);
+        const response = campaignsResult.value;
+        setCampaigns(response.data);
+        setCampaignsPagination({
+          total: response.total,
+          page: response.page,
+          pageSize: response.pageSize,
+          hasMore: response.hasMore,
+        });
 
-        const nextId = requestedCampaignId ?? data[0]?.id ?? null;
-        const exists = nextId ? data.some((campaign) => campaign.id === nextId) : false;
-        const resolvedId = exists ? nextId : data[0]?.id ?? null;
+        const nextId = requestedCampaignId ?? response.data[0]?.id ?? null;
+        const exists = nextId ? response.data.some((campaign) => campaign.id === nextId) : false;
+        const resolvedId = exists ? nextId : response.data[0]?.id ?? null;
 
         setInvalidUrlCampaignId(requestedCampaignId && !exists ? requestedCampaignId : null);
         setSelectedCampaignId(resolvedId);
@@ -633,10 +647,16 @@ function App() {
             selectedCampaignId={selectedCampaignId}
             onSelect={handleSelect}
             onSearchChange={(query) => {
-              void refreshCampaigns(query);
+              void refreshCampaigns(query, undefined, 1);
+            }}
+            onPageChange={(page) => {
+              void refreshCampaigns("", undefined, page);
             }}
             isLoading={isCampaignsLoading || initialLoad}
             invalidUrlCampaignId={invalidUrlCampaignId}
+            currentPage={campaignsPagination.page}
+            hasMore={campaignsPagination.hasMore}
+            totalCampaigns={campaignsPagination.total}
           />
         </ErrorBoundary>
 

frontend/src/components/CampaignsTable.tsx

@@ -1,5 +1,5 @@
 import { LayoutGrid } from "lucide-react";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { useDebounce } from "../hooks/useDebounce";
 import { Campaign, CampaignStatus } from "../types/campaign";
 import { EmptyState } from "./EmptyState";
@@ -28,8 +28,12 @@ interface CampaignsTableProps {
   selectedCampaignId: string | null;
   onSelect: (campaignId: string) => void;
   onSearchChange?: (query: string) => void;
+  onPageChange?: (page: number) => void;
   isLoading?: boolean;
   invalidUrlCampaignId?: string | null;
+  currentPage?: number;
+  hasMore?: boolean;
+  totalCampaigns?: number;
 }
 
 function formatTimestamp(value: number | string): string {
@@ -58,8 +62,13 @@ export function CampaignsTable({
   campaigns,
   selectedCampaignId,
   onSelect,
+  onSearchChange,
+  onPageChange,
   isLoading = false,
   invalidUrlCampaignId = null,
+  currentPage = 1,
+  hasMore = false,
+  totalCampaigns = 0,
 }: CampaignsTableProps) {
   const [assetCode, setAssetCode] = useState("");
   const [statusFilter, setStatusFilter] = useState<StatusFilterValue>("");
@@ -360,6 +369,34 @@ export function CampaignsTable({
           </div>
         </>
       )}
+
+      {totalCampaigns > 0 && (
+        <div className="pagination-controls" style={{ marginTop: "1rem", display: "flex", gap: "1rem", alignItems: "center", justifyContent: "space-between" }}>
+          <div className="muted" style={{ fontSize: "0.875rem" }}>
+            Showing page {currentPage} ({campaigns.length} campaigns, {totalCampaigns} total)
+          </div>
+          <div style={{ display: "flex", gap: "0.5rem" }}>
+            <button
+              className="btn-ghost"
+              type="button"
+              onClick={() => onPageChange?.(currentPage - 1)}
+              disabled={isLoading || currentPage <= 1}
+              aria-label="Previous page"
+            >
+              ← Previous
+            </button>
+            <button
+              className="btn-ghost"
+              type="button"
+              onClick={() => onPageChange?.(currentPage + 1)}
+              disabled={isLoading || !hasMore}
+              aria-label="Next page"
+            >
+              Next →
+            </button>
+          </div>
+        </div>
+      )}
     </section>
   );
 }