feat(api,frontend): add X-Total-Count header, implement server-side sorting, add skeleton screens, and improve logging

- Issue #240: Add X-Total-Count header to paginated endpoints (GET /api/campaigns, GET /api/campaigns/:id/pledges)
  - X-Total-Count header exposes total item count for pagination UI
  - Header added to CORS Access-Control-Expose-Headers
  - Works for both cache HIT and MISS cases

- Issue #241: Replace console.log/console.error with structured logger
  - Replaced startup banner console.log calls with logInfo
  - Maintains no-console ESLint rule compliance

- Issue #242: Add server-side ?sort and ?order query parameters
  - Replace old sort fields (newest, percentFunded, totalPledged) with new ones (createdAt, pledgedAmount, targetAmount)
  - Support sorting by deadline, pledgedAmount, createdAt, targetAmount
  - Default sorting: createdAt desc
  - Return 400 error for invalid sort fields
  - Updated both backend campaignStore and frontend components

- Issue #245: Add loading skeleton screens for campaign list
  - Created SkeletonCard component with animate-pulse animation
  - Renders 6 skeleton cards during initial load
  - Improved perceived performance during data fetch
  - Added accessibility attributes (aria-busy, aria-label)

Resolves #240
Resolves #241
Resolves #242
Resolves #245

Author: silhilston

backend/src/index.ts

@@ -102,6 +102,7 @@ app.use(
       }
     },
     credentials: true,
+    exposedHeaders: ['X-Total-Count', 'X-RateLimit-Limit', 'X-RateLimit-Remaining', 'X-RateLimit-Reset', 'Retry-After'],
   }),
 );
 
@@ -234,10 +235,15 @@ export function parseCampaignListFilters(query: {
   sort?: CampaignSortField;
   order?: SortOrder;
 } {
-  const VALID_SORT_FIELDS: CampaignSortField[] = ['newest', 'deadline', 'percentFunded', 'totalPledged'];
+  const VALID_SORT_FIELDS: CampaignSortField[] = ['createdAt', 'deadline', 'pledgedAmount', 'targetAmount'];
   const VALID_ORDERS: SortOrder[] = ['asc', 'desc'];
   const rawSort = normalizeQueryValue(query.sort);
   const rawOrder = normalizeQueryValue(query.order);
+
+  if (rawSort && !VALID_SORT_FIELDS.includes(rawSort as CampaignSortField)) {
+    throw new AppError(`Invalid sort field: ${rawSort}. Supported fields: ${VALID_SORT_FIELDS.join(', ')}`, 400, 'INVALID_SORT_FIELD');
+  }
+
   return {
     asset: normalizeAssetFilter(query.asset),
     status: normalizeStatusFilter(query.status),
@@ -351,8 +357,10 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
 
   const cached = getCampaignCacheEntry(cacheKey);
   if (cached) {
+    const cachedData = JSON.parse(cached);
     res.setHeader('Cache-Control', 'max-age=5');
     res.setHeader('X-Cache', 'HIT');
+    res.setHeader('X-Total-Count', String(cachedData.pagination.total));
     res.setHeader('Content-Type', 'application/json');
     res.send(cached);
     return;
@@ -401,6 +409,7 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
 
   res.setHeader('Cache-Control', 'max-age=5');
   res.setHeader('X-Cache', 'MISS');
+  res.setHeader('X-Total-Count', String(totalCount));
   res.setHeader('Content-Type', 'application/json');
   res.send(responseBody);
 });
@@ -447,6 +456,7 @@ app.get('/api/campaigns/:id/pledges', (req: Request, res: Response) => {
     Math.ceil(totalCount / paginationResult.limit),
   );
 
+  res.setHeader('X-Total-Count', String(totalCount));
   res.json({
     data: pledges,
     pagination: {
@@ -763,17 +773,12 @@ function printStartupBanner(): void {
   const dbPath = process.env.DB_PATH || path.join(__dirname, '..', '..', 'data', 'campaigns.db');
   const nodeEnv = process.env.NODE_ENV || 'development';
 
-  /* eslint-disable no-console */
-  console.log('');
-  console.log('╔════════════════════════════════════════════════════════════╗');
-  console.log('║         Stellar Goal Vault Backend - Starting Up          ║');
-  console.log('╠════════════════════════════════════════════════════════════╣');
-  console.log(`║  Port:           ${config.port.toString().padEnd(42)}║`);
-  console.log(`║  Environment:    ${nodeEnv.padEnd(42)}║`);
-  console.log(`║  Database Path:  ${dbPath.padEnd(42)}║`);
-  console.log('╚════════════════════════════════════════════════════════════╝');
-  console.log('');
-  /* eslint-enable no-console */
+  logInfo('startup_banner', {
+    message: 'Stellar Goal Vault Backend - Starting Up',
+    port: config.port,
+    environment: nodeEnv,
+    databasePath: dbPath,
+  }, config.logLevel);
 }
 
 export function configureHttpServer(server: Server): Server {

backend/src/services/campaignStore.ts

@@ -273,7 +273,7 @@ export function calculateProgress(campaign: CampaignRecord, at = nowInSeconds())
   };
 }
 
-export type CampaignSortField = 'newest' | 'deadline' | 'percentFunded' | 'totalPledged';
+export type CampaignSortField = 'createdAt' | 'deadline' | 'pledgedAmount' | 'targetAmount';
 export type SortOrder = 'asc' | 'desc';
 
 export interface ListCampaignsOptions {
@@ -411,21 +411,21 @@ export function listCampaigns(options?: ListCampaignsOptions): ListCampaignsResu
   const totalCount = (db.prepare(countQuery).get(...params) as { total: number }).total;
 
   // Build ORDER BY clause from sort options
-  const sortField = options?.sort ?? 'newest';
+  const sortField = options?.sort ?? 'createdAt';
   const sortOrder = options?.order ?? 'desc';
   const orderDir = sortOrder === 'asc' ? 'ASC' : 'DESC';
   let orderByClause: string;
   switch (sortField) {
     case 'deadline':
-      orderByClause = `campaigns.deadline ${sortOrder === 'desc' ? 'DESC' : 'ASC'}`;
+      orderByClause = `campaigns.deadline ${orderDir}`;
       break;
-    case 'percentFunded':
-      orderByClause = `(CAST(campaigns.pledged_amount AS REAL) / CAST(campaigns.target_amount AS REAL)) ${orderDir}`;
-      break;
-    case 'totalPledged':
+    case 'pledgedAmount':
       orderByClause = `campaigns.pledged_amount ${orderDir}`;
       break;
-    case 'newest':
+    case 'targetAmount':
+      orderByClause = `campaigns.target_amount ${orderDir}`;
+      break;
+    case 'createdAt':
     default:
       orderByClause = `campaigns.created_at ${orderDir}`;
       break;

frontend/src/components/CampaignsTable.tsx

@@ -13,6 +13,7 @@ import {
 import { SearchInput } from "./SearchInput";
 import { SortDropdown, SortOption } from "./SortDropdown";
 import { AddressAvatar } from "./AddressAvatar";
+import { SkeletonCard } from "./SkeletonCard";
 import { useWindowVirtualizer } from "@tanstack/react-virtual";
 import { useMediaQuery } from "../hooks/useMediaQuery";
 
@@ -74,11 +75,11 @@ export function CampaignsTable({
   invalidUrlCampaignId = null,
 }: CampaignsTableProps) {
   const [searchParams, setSearchParams] = useSearchParams();
-  const urlSort = (searchParams.get('sort') as SortOption | null) ?? 'newest';
+  const urlSort = (searchParams.get('sort') as SortOption | null) ?? 'createdAt';
   const urlOrder = (searchParams.get('order') as 'asc' | 'desc' | null) ?? 'desc';
   const urlStatus = (searchParams.get('status') as StatusFilterValue | null) ?? '';
-  const VALID_SORTS: SortOption[] = ['newest', 'deadline', 'percentFunded', 'totalPledged'];
-  const sortBy: SortOption = VALID_SORTS.includes(urlSort) ? urlSort : 'newest';
+  const VALID_SORTS: SortOption[] = ['createdAt', 'deadline', 'pledgedAmount', 'targetAmount'];
+  const sortBy: SortOption = VALID_SORTS.includes(urlSort) ? urlSort : 'createdAt';
   const [assetCode, setAssetCode] = useState("");
   const [statusFilter, setStatusFilter] = useState<StatusFilterValue>(urlStatus);
   const [searchQuery, setSearchQuery] = useState("");
@@ -147,6 +148,7 @@ export function CampaignsTable({
   }, [hasMore, onLoadMore]);
 
   const isEmpty = campaigns.length === 0;
+  const SKELETON_COUNT = 6;
 
   const assetOptions = useMemo(
     () => getDistinctAssetCodes(campaigns),
@@ -196,6 +198,11 @@ export function CampaignsTable({
           <h2>Campaign board</h2>
           <p className="muted">Loading campaigns...</p>
         </div>
+        <div className="cards-only" aria-busy="true" aria-label="Loading campaigns">
+          {Array.from({ length: SKELETON_COUNT }).map((_, index) => (
+            <SkeletonCard key={`skeleton-${index}`} />
+          ))}
+        </div>
       </section>
     );
   }

frontend/src/components/SkeletonCard.tsx

@@ -0,0 +1,34 @@
+export function SkeletonCard() {
+  return (
+    <article className="campaign-card animate-pulse">
+      <div className="campaign-card-main">
+        <div className="campaign-card-header">
+          <div className="h-6 bg-gray-300 rounded w-3/4 mb-2"></div>
+          <div className="h-6 bg-gray-300 rounded w-1/4"></div>
+        </div>
+        <div
+          className="campaign-creator mono"
+          style={{
+            display: "flex",
+            alignItems: "center",
+            gap: 10,
+            marginBottom: 12,
+          }}
+        >
+          <div className="h-6 w-6 bg-gray-300 rounded-full"></div>
+          <div className="h-6 bg-gray-300 rounded flex-1"></div>
+        </div>
+        <div className="campaign-progress">
+          <div className="h-4 bg-gray-300 rounded w-full mb-2"></div>
+          <div className="h-4 bg-gray-300 rounded w-1/2"></div>
+        </div>
+        <div className="campaign-meta">
+          <div className="h-4 bg-gray-300 rounded w-1/3"></div>
+        </div>
+      </div>
+      <div className="campaign-card-actions">
+        <div className="h-10 bg-gray-300 rounded w-full"></div>
+      </div>
+    </article>
+  );
+}

frontend/src/components/SortDropdown.tsx

@@ -1,4 +1,4 @@
-export type SortOption = 'newest' | 'deadline' | 'percentFunded' | 'totalPledged';
+export type SortOption = 'createdAt' | 'deadline' | 'pledgedAmount' | 'targetAmount';
 
 export interface SortDropdownProps {
   value: SortOption;
@@ -16,10 +16,10 @@ export function SortDropdown({ value, onChange, disabled = false }: SortDropdown
       className="control-select"
       style={{ cursor: disabled ? 'not-allowed' : 'pointer', opacity: disabled ? 0.55 : 1 }}
     >
-      <option value="newest">Newest</option>
+      <option value="createdAt">Created At</option>
       <option value="deadline">Deadline</option>
-      <option value="percentFunded">Percent Funded</option>
-      <option value="totalPledged">Total Pledged</option>
+      <option value="pledgedAmount">Pledged Amount</option>
+      <option value="targetAmount">Target Amount</option>
     </select>
   );
 }

frontend/src/components/campaignsTableUtils.ts

@@ -75,7 +75,7 @@ export function applyFilters(
  * This ensures the selected campaign state is preserved during sorting.
  *
  * @param campaigns - Array of campaigns to sort
- * @param sortBy - Sort option (newest, deadline, percentFunded, totalPledged)
+ * @param sortBy - Sort option (createdAt, deadline, pledgedAmount, targetAmount)
  * @returns Sorted array of campaigns
  */
 export function sortCampaigns(campaigns: Campaign[], sortBy: SortOption): Campaign[] {
@@ -86,7 +86,7 @@ export function sortCampaigns(campaigns: Campaign[], sortBy: SortOption): Campai
     let comparison = 0;
 
     switch (sortBy) {
-      case 'newest':
+      case 'createdAt':
         // Sort by createdAt descending (newest first)
         comparison = b.createdAt - a.createdAt;
         break;
@@ -96,16 +96,16 @@ export function sortCampaigns(campaigns: Campaign[], sortBy: SortOption): Campai
         comparison = a.deadline - b.deadline;
         break;
 
-      case 'percentFunded':
-        // Sort by percentFunded descending (highest first)
-        comparison = b.progress.percentFunded - a.progress.percentFunded;
-        break;
-
-      case 'totalPledged':
+      case 'pledgedAmount':
         // Sort by pledgedAmount descending (largest first)
         comparison = b.pledgedAmount - a.pledgedAmount;
         break;
 
+      case 'targetAmount':
+        // Sort by targetAmount descending (largest first)
+        comparison = b.targetAmount - a.targetAmount;
+        break;
+
       default:
         // No sorting for unknown options
         comparison = 0;