Merge pull request #52 from okekefrancis112/creator

feat: add safe integer parser for query params

Author: Chucks1093

src/modules/creator/creator.controller.ts

@@ -1,35 +1,43 @@
 // src/modules/creator/creator.controller.ts
 import { Request, Response } from 'express';
+import { ZodError } from 'zod';
+import { z } from 'zod';
 import {
    sendPaginatedSuccess,
    sendError,
+   sendValidationError,
    ErrorCode,
 } from '../../utils/api-response.utils';
 import { getPaginatedCreators } from './creator.service';
 import { parseCreatorSortOptions } from './creator.utils';
+import { safeIntParam } from '../../utils/query.utils';
 import {
-   validatePageSize,
-   PageSizeExceededError,
-} from '../../utils/pagination-guard.utils';
+   DEFAULT_PAGE,
+   DEFAULT_PAGE_SIZE,
+   MIN_PAGE_SIZE,
+   MAX_PAGE_SIZE,
+} from '../../constants/pagination.constants';
+
+const LegacyCreatorQuerySchema = z.object({
+   page: safeIntParam({
+      defaultValue: DEFAULT_PAGE,
+      min: MIN_PAGE_SIZE,
+      max: Number.MAX_SAFE_INTEGER,
+      label: 'Page',
+   }),
+   limit: safeIntParam({
+      defaultValue: DEFAULT_PAGE_SIZE,
+      min: MIN_PAGE_SIZE,
+      max: MAX_PAGE_SIZE,
+      label: 'Limit',
+   }),
+   sortBy: z.string().optional(),
+   sortOrder: z.string().optional(),
+});
 
 export async function listCreators(req: Request, res: Response) {
    try {
-      const page = parseInt(req.query.page as string) || 1;
-      const limitInput = parseInt(req.query.limit as string) || 10;
-      const sortBy = req.query.sortBy as string;
-      const sortOrder = req.query.sortOrder as string;
-
-      if (page < 1) {
-         return sendError(
-            res,
-            400,
-            ErrorCode.VALIDATION_ERROR,
-            'Invalid pagination parameters'
-         );
-      }
-
-      // Validate page size using the reusable guard
-      const limit = validatePageSize(limitInput);
+      const { page, limit, sortBy, sortOrder } = LegacyCreatorQuerySchema.parse(req.query);
 
       const sort = parseCreatorSortOptions(sortBy, sortOrder);
 
@@ -47,8 +55,12 @@ export async function listCreators(req: Request, res: Response) {
          'Creators retrieved successfully'
       );
    } catch (error) {
-      if (error instanceof PageSizeExceededError) {
-         return sendError(res, 400, ErrorCode.VALIDATION_ERROR, error.message);
+      if (error instanceof ZodError) {
+         const details = error.errors.map(err => ({
+            field: err.path.join('.'),
+            message: err.message,
+         }));
+         return sendValidationError(res, 'Invalid query parameters', details);
       }
       console.error('Error listing creators:', error);
       return sendError(

src/modules/creators/creators.controllers.ts

@@ -5,6 +5,7 @@ import {
    serializeCreatorList,
    CreatorListResponse,
 } from './creators.serializers';
+import { mapPublicCreatorStats } from './creators.stats';
 import {
    sendSuccess,
    sendValidationError,
@@ -48,3 +49,38 @@ export const httpListCreators: AsyncController = async (req, res, next) => {
       next(error);
    }
 };
+
+/**
+ * Controller for GET /api/v1/creators/:id/stats
+ *
+ * Returns public stats for a specific creator.
+ * Validates creator ID and applies caching via middleware.
+ */
+export const httpGetCreatorStats: AsyncController = async (req, res, next) => {
+   try {
+      const { id } = req.params;
+
+      // Validate creator ID format (basic validation)
+      if (!id || typeof id !== 'string') {
+         return sendValidationError(res, 'Invalid creator ID', [
+            { field: 'id', message: 'Creator ID must be a valid string' },
+         ]);
+      }
+
+      // TODO: Fetch actual creator metrics from database/service
+      // For now, return placeholder data
+      const placeholderMetrics = {
+         holderCount: 0,
+         totalSupply: 0,
+         totalVolume: 0,
+         lastActivityAt: undefined,
+      };
+
+      // Serialize using the public stats mapper
+      const stats = mapPublicCreatorStats(placeholderMetrics);
+
+      sendSuccess(res, stats);
+   } catch (error) {
+      next(error);
+   }
+};

src/modules/creators/creators.schemas.ts

@@ -3,9 +3,12 @@ import {
    CREATOR_LIST_SORT_OPTIONS,
    CREATOR_LIST_SORT_ORDERS,
 } from './creators.sort';
+import { safeIntParam } from '../../utils/query.utils';
 import {
-   MAX_PAGE_SIZE,
+   DEFAULT_PAGE_SIZE,
+   DEFAULT_OFFSET,
    MIN_PAGE_SIZE,
+   MAX_PAGE_SIZE,
 } from '../../constants/pagination.constants';
 
 /**
@@ -19,22 +22,18 @@ import {
  */
 export const CreatorListQuerySchema = z.object({
    // Pagination
-   limit: z
-      .string()
-      .optional()
-      .default('20')
-      .transform(val => parseInt(val, 10))
-      .refine(val => val >= MIN_PAGE_SIZE && val <= MAX_PAGE_SIZE, {
-         message: `Limit must be between ${MIN_PAGE_SIZE} and ${MAX_PAGE_SIZE}`,
-      }),
-   offset: z
-      .string()
-      .optional()
-      .default('0')
-      .transform(val => parseInt(val, 10))
-      .refine(val => val >= 0, {
-         message: 'Offset must be non-negative',
-      }),
+   limit: safeIntParam({
+      defaultValue: DEFAULT_PAGE_SIZE,
+      min: MIN_PAGE_SIZE,
+      max: MAX_PAGE_SIZE,
+      label: 'Limit',
+   }),
+   offset: safeIntParam({
+      defaultValue: DEFAULT_OFFSET,
+      min: 0,
+      max: Number.MAX_SAFE_INTEGER,
+      label: 'Offset',
+   }),
 
    // Sorting
    sort: z.enum(CREATOR_LIST_SORT_OPTIONS).optional().default('createdAt'),

src/modules/creators/creators.stats.ts

@@ -1,8 +1,21 @@
 // src/modules/creators/creators.stats.ts
-// Helper for formatting public creator stats in API responses.
+// Mapper for shaping public creator stats in API responses.
 
 import { CreatorMetrics } from '../../types/profile.types';
 
+/**
+ * Public field names exposed by the stats mapper.
+ * Single source of truth for what gets included in public stats responses.
+ */
+export const CREATOR_STATS_FIELDS = [
+    'holderCount',
+    'totalSupply',
+    'totalVolume',
+    'lastActivityAt',
+] as const;
+
+export type CreatorStatsField = (typeof CREATOR_STATS_FIELDS)[number];
+
 /**
  * Public-facing creator stats shape.
  *
@@ -17,27 +30,45 @@ export interface PublicCreatorStats {
 }
 
 /**
- * Format a CreatorMetrics object into a public stats response.
+ * Maps each public stats field to its corresponding internal CreatorMetrics key.
+ * Currently 1:1, but the indirection lets internal field names change
+ * without breaking the public API contract.
+ *
+ * Uses `as const satisfies` to retain literal types for type-safe indexing
+ * while enforcing that all public fields map to valid CreatorMetrics keys.
+ */
+const CREATOR_STATS_FIELD_MAP = {
+    holderCount: 'holderCount',
+    totalSupply: 'totalSupply',
+    totalVolume: 'totalVolume',
+    lastActivityAt: 'lastActivityAt',
+} as const satisfies Record<CreatorStatsField, keyof CreatorMetrics>;
+
+/**
+ * Map a CreatorMetrics object into a public stats response.
  *
- * Centralizes the public stats shape so all creator endpoints
- * return a consistent structure.
+ * Uses CREATOR_STATS_FIELD_MAP to build the output, ensuring only
+ * mapped fields are included. Optional fields are omitted when undefined.
  *
  * @param metrics - Internal creator metrics
  * @returns Public stats object safe for API responses
  *
  * @example
- * serializePublicCreatorStats({ holderCount: 10, totalSupply: 100, totalVolume: 500 })
+ * mapPublicCreatorStats({ holderCount: 10, totalSupply: 100, totalVolume: 500 })
  * // => { holderCount: 10, totalSupply: 100, totalVolume: 500 }
  */
-export function serializePublicCreatorStats(
+export function mapPublicCreatorStats(
     metrics: CreatorMetrics
 ): PublicCreatorStats {
     return {
-        holderCount: metrics.holderCount,
-        totalSupply: metrics.totalSupply,
-        totalVolume: metrics.totalVolume,
-        ...(metrics.lastActivityAt !== undefined
-            ? { lastActivityAt: metrics.lastActivityAt }
+        holderCount: metrics[CREATOR_STATS_FIELD_MAP.holderCount],
+        totalSupply: metrics[CREATOR_STATS_FIELD_MAP.totalSupply],
+        totalVolume: metrics[CREATOR_STATS_FIELD_MAP.totalVolume],
+        ...(metrics[CREATOR_STATS_FIELD_MAP.lastActivityAt] !== undefined
+            ? {
+                  lastActivityAt:
+                      metrics[CREATOR_STATS_FIELD_MAP.lastActivityAt],
+              }
             : {}),
     };
 }

src/utils/query.utils.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+/**
+ * Creates a Zod schema for safely parsing an integer query parameter.
+ *
+ * Accepts a string (as Express delivers query params), applies a default,
+ * converts to integer, and validates within [min, max].
+ * Non-numeric strings resolve to NaN, which fails the bounds refine.
+ */
+export function safeIntParam(options: {
+   defaultValue: number;
+   min: number;
+   max: number;
+   label: string;
+}) {
+   const { defaultValue, min, max, label } = options;
+
+   return z
+      .string()
+      .optional()
+      .default(String(defaultValue))
+      .transform(val => parseInt(val, 10))
+      .refine(val => !Number.isNaN(val) && val >= min && val <= max, {
+         message: `${label} must be an integer between ${min} and ${max}`,
+      });
+}