Merge pull request #299 from devmasalati/feature/analytics-pagination

feat: add pagination support to analytics endpoints

Author: Nathydre

backend/src/__tests__/analyticsService.test.ts

@@ -22,4 +22,56 @@ describe('AnalyticsService', () => {
     expect(dashboard.statusDistribution).toBeDefined();
     expect(Array.isArray(dashboard.insights)).toBe(true);
   });
+
+  describe('getPaginatedMonthlyGrowth', () => {
+    it('returns pagination metadata', async () => {
+      const service = new AnalyticsService();
+      const result = await service.getPaginatedMonthlyGrowth({ page: 1, limit: 5 });
+
+      expect(result).toHaveProperty('data');
+      expect(result).toHaveProperty('pagination');
+      expect(Array.isArray(result.data)).toBe(true);
+
+      const { pagination } = result;
+      expect(pagination.page).toBe(1);
+      expect(pagination.limit).toBe(5);
+      expect(typeof pagination.total).toBe('number');
+      expect(typeof pagination.totalPages).toBe('number');
+      expect(typeof pagination.hasNextPage).toBe('boolean');
+      expect(pagination.hasPreviousPage).toBe(false);
+    });
+
+    it('returns at most `limit` items per page', async () => {
+      const service = new AnalyticsService();
+      const result = await service.getPaginatedMonthlyGrowth({ page: 1, limit: 3 });
+
+      expect(result.data.length).toBeLessThanOrEqual(3);
+    });
+
+    it('returns correct page 2 slice', async () => {
+      const service = new AnalyticsService();
+      const page1 = await service.getPaginatedMonthlyGrowth({ page: 1, limit: 2 });
+      const page2 = await service.getPaginatedMonthlyGrowth({ page: 2, limit: 2 });
+
+      expect(page2.pagination.page).toBe(2);
+      // page 2 items must differ from page 1 items (unless total <= 2)
+      if (page1.pagination.total > 2) {
+        expect(page2.data[0]).not.toEqual(page1.data[0]);
+        expect(page2.pagination.hasPreviousPage).toBe(true);
+      }
+    });
+
+    it('hasNextPage is false on last page', async () => {
+      const service = new AnalyticsService();
+      // Fetch all data in one large page
+      const all = await service.getPaginatedMonthlyGrowth({ page: 1, limit: 1000 });
+      expect(all.pagination.hasNextPage).toBe(false);
+    });
+
+    it('totalPages is at least 1 even when data is empty', async () => {
+      const service = new AnalyticsService();
+      const result = await service.getPaginatedMonthlyGrowth({ page: 1, limit: 12 });
+      expect(result.pagination.totalPages).toBeGreaterThanOrEqual(1);
+    });
+  });
 });

backend/src/routes/analytics.ts

@@ -6,6 +6,7 @@ import {
   sanitizeMeterId,
   sanitizeString,
   sanitizePositiveNumber,
+  sanitizeInteger,
   validationError,
   type ValidationError,
 } from "../utils/sanitize";
@@ -50,16 +51,46 @@ router.get("/user/:userId", async (req, res) => {
 /**
  * GET /api/analytics/system
  * Get system-wide analytics (admin only)
+ * Query params: page (default 1), limit (default 12)
  */
 router.get("/system", async (req, res) => {
   try {
+    const errors: ValidationError[] = [];
+
+    const rawPage  = sanitizeInteger(req.query.page  ?? '1',  1, 10_000);
+    const rawLimit = sanitizeInteger(req.query.limit ?? '12', 1, 100);
+
+    if (req.query.page  !== undefined && Number.isNaN(rawPage))  errors.push(validationError('page',  'page must be a positive integer (1–10000)'));
+    if (req.query.limit !== undefined && Number.isNaN(rawLimit)) errors.push(validationError('limit', 'limit must be an integer between 1 and 100'));
+    if (errors.length > 0) return res.status(400).json({ success: false, errors });
+
+    const page  = Number.isNaN(rawPage)  ? 1  : rawPage;
+    const limit = Number.isNaN(rawLimit) ? 12 : rawLimit;
+
     // TODO: Add admin authentication check
     const analytics = await analyticsService.generateSystemAnalytics();
 
-    logger.info("System analytics retrieved");
+    // Paginate monthlyGrowth
+    const all = analytics.monthlyGrowth;
+    const total = all.length;
+    const offset = (page - 1) * limit;
+    const pagedGrowth = all.slice(offset, offset + limit);
+
+    logger.info("System analytics retrieved", { page, limit });
     return res.status(200).json({
       success: true,
-      data: analytics,
+      data: {
+        ...analytics,
+        monthlyGrowth: pagedGrowth,
+      },
+      pagination: {
+        page,
+        limit,
+        total,
+        totalPages: Math.max(1, Math.ceil(total / limit)),
+        hasNextPage: offset + limit < total,
+        hasPreviousPage: page > 1,
+      },
       timestamp: new Date().toISOString(),
     });
   } catch (error) {
@@ -71,6 +102,43 @@ router.get("/system", async (req, res) => {
   }
 });
 
+/**
+ * GET /api/analytics/monthly-growth
+ * Get paginated monthly growth data
+ * Query params: page (default 1), limit (default 12)
+ */
+router.get("/monthly-growth", async (req, res) => {
+  try {
+    const errors: ValidationError[] = [];
+
+    const rawPage  = sanitizeInteger(req.query.page  ?? '1',  1, 10_000);
+    const rawLimit = sanitizeInteger(req.query.limit ?? '12', 1, 100);
+
+    if (req.query.page  !== undefined && Number.isNaN(rawPage))  errors.push(validationError('page',  'page must be a positive integer (1–10000)'));
+    if (req.query.limit !== undefined && Number.isNaN(rawLimit)) errors.push(validationError('limit', 'limit must be an integer between 1 and 100'));
+    if (errors.length > 0) return res.status(400).json({ success: false, errors });
+
+    const page  = Number.isNaN(rawPage)  ? 1  : rawPage;
+    const limit = Number.isNaN(rawLimit) ? 12 : rawLimit;
+
+    const result = await analyticsService.getPaginatedMonthlyGrowth({ page, limit });
+
+    logger.info("Monthly growth analytics retrieved", { page, limit });
+    return res.status(200).json({
+      success: true,
+      data: result.data,
+      pagination: result.pagination,
+      timestamp: new Date().toISOString(),
+    });
+  } catch (error) {
+    logger.error("Failed to retrieve monthly growth analytics", { error });
+    return res.status(500).json({
+      success: false,
+      error: "Failed to retrieve monthly growth analytics",
+    });
+  }
+});
+
 /**
  * GET /api/analytics/payments/dashboard
  * Get payment analytics dashboard insights

backend/src/services/analyticsService.ts

@@ -67,6 +67,23 @@ export interface AnalyticsTrendPoint {
   count?: number;
 }
 
+export interface PaginationParams {
+  page: number;
+  limit: number;
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+  };
+}
+
 export interface AnalyticsReport {
   userId: string;
   totalSpendYearly: number;
@@ -528,6 +545,31 @@ export class AnalyticsService {
     );
   }
 
+  /**
+   * Get paginated monthly growth data from system analytics
+   */
+  async getPaginatedMonthlyGrowth(
+    params: PaginationParams,
+  ): Promise<PaginatedResult<AnalyticsTrendPoint>> {
+    const { page, limit } = params;
+    const systemAnalytics = await this.generateSystemAnalytics();
+    const all = systemAnalytics.monthlyGrowth;
+    const total = all.length;
+    const offset = (page - 1) * limit;
+    const data = all.slice(offset, offset + limit);
+    return {
+      data,
+      pagination: {
+        page,
+        limit,
+        total,
+        totalPages: Math.max(1, Math.ceil(total / limit)),
+        hasNextPage: offset + limit < total,
+        hasPreviousPage: page > 1,
+      },
+    };
+  }
+
   /**
    * Legacy method for backward compatibility
    */