Merge pull request #422 from Abdullahi-Code9/fix/anomaly-pagination-issue-247

fix(anomaly): align response envelope pagination structure and handle invalid shipmentId (#247)

Author: kingksjo

docs/swagger.yaml

@@ -2991,6 +2991,252 @@ paths:
         '403':
           $ref: '#/components/responses/Forbidden'
 
+  /api/settlements/{id}:
+    get:
+      summary: Get payments history (legacy — prefer /api/settlements)
+      description: Returns settlement records for the authenticated user's organization. Both `/api/payments` and `/api/settlements` resolve to the same router.
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [Pending, Escrowed, Released, Failed, Disputed]
+          description: Filter payments by status.
+        - in: query
+          name: cursor
+      summary: Get settlement detail
+      description: Returns full settlement detail including escrowRelease subdocument.
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+          description: Settlement ObjectId.
+      responses:
+        '200':
+          description: Settlement retrieved successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Settlement'
+                  meta:
+                    type: object
+                    properties:
+                      total:
+                        type: integer
+                      hasMore:
+                        type: boolean
+                      nextCursor:
+                        type: string
+                        nullable: true
+                    $ref: '#/components/schemas/Settlement'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Settlement not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/settlements/{id}/dispute:
+    post:
+      summary: Dispute a settlement
+      description: |
+        Transitions the settlement status to `Disputed` and records dispute metadata
+        (`disputedAt`, `disputeReason`, `additionalNotes`) in `escrowRelease`.
+        Restricted to ADMIN and MANAGER roles.
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+          description: Settlement ObjectId.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - reason
+              properties:
+                reason:
+                  type: string
+                  minLength: 1
+                  description: Reason for the dispute.
+                notes:
+                  type: string
+                  description: Optional additional context.
+      responses:
+        '200':
+          description: Settlement disputed successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+                  data:
+                    $ref: '#/components/schemas/Settlement'
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: Forbidden — VIEWER role cannot dispute
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Settlement not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/settlements:
+    get:
+      summary: List settlements
+      description: Returns settlement records for the authenticated user's organization (cursor-paginated).
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [Pending, Escrowed, Released, Failed, Disputed]
+          description: Filter by status.
+        - in: query
+          name: cursor
+          schema:
+            type: string
+          description: Cursor for next-page pagination.
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: Settlements retrieved successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Settlement'
+                  meta:
+                    type: object
+                    properties:
+                      total:
+                        type: integer
+                      hasMore:
+                        type: boolean
+                      nextCursor:
+                        type: string
+                        nullable: true
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /api/settlements/summary:
+    get:
+      summary: Get settlement summary with sparkline
+      description: |
+        Returns aggregated settlement totals and a per-day sparkline array for the chosen period.
+        Results are cached in Redis for 5 minutes.
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: query
+          name: period
+          schema:
+            type: string
+            enum: [week, month, quarter]
+            default: week
+          description: Aggregation window. `week`=7 days, `month`=30 days, `quarter`=90 days.
+      responses:
+        '200':
+          description: Summary retrieved successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+                  data:
+                    type: object
+                    properties:
+                      totalReleased:
+                        type: number
+                        description: Sum of released settlement amounts in the period.
+                      totalInEscrow:
+                        type: number
+                        description: Sum of escrowed settlement amounts in the period.
+                      totalPending:
+                        type: number
+                        description: Sum of pending settlement amounts in the period.
+                      sparkline:
+                        type: array
+                        items:
+                          type: number
+                        description: One entry per day in the period (released amounts per day).
+                      period:
+                        type: string
+                        enum: [week, month, quarter]
+        '400':
+          description: Invalid period value
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
   /api/settlements/{id}:
     get:
       summary: Get settlement detail

src/app.ts

@@ -8,6 +8,7 @@ import YAML from 'yamljs';
 import { requestId } from './shared/middleware/requestId.js';
 import { notFound } from './shared/middleware/notFound.js';
 import { errorMiddleware } from './shared/http/errorMiddleware.js';
+import { standardLimiter, loginLimiter, strictLimiter, otpLimiter } from './shared/middleware/rateLimiter.js';
 import {
   standardLimiter,
   loginLimiter,

src/config/index.ts

@@ -14,6 +14,8 @@ export const config = {
   allowedOrigins,
   redisUrl: env.REDIS_URL,
   corsOrigin: env.CORS_ORIGIN,
+
+  // SMTP (email)
   frontendUrl: env.FRONTEND_URL,
   smtp: {
     host: env.SMTP_HOST,
@@ -46,5 +48,10 @@ export const config = {
   sorobanRpcUrl: env.SOROBAN_RPC_URL,
   escrowContractId: env.ESCROW_CONTRACT_ID,
   sentryDsn: env.SENTRY_DSN,
+
+  // Frontend
+  frontendUrl: env.FRONTEND_URL,
+
+  sendgridApiKey: env.SENDGRID_API_KEY,
   totpEncryptionKey: env.TOTP_ENCRYPTION_KEY,
 } as const;

src/env.ts

@@ -68,6 +68,9 @@ const EnvSchema = z.object({
   // Frontend
   FRONTEND_URL: z.string().url('FRONTEND_URL must be a valid URL').default('http://localhost:3000'),
 
+  // Email (additional)
+  SMTP_FROM: z.string().email('SMTP_FROM must be a valid email').optional(),
+  SENDGRID_API_KEY: z.string().optional(),
   // TOTP 2FA — AES-256 encryption key for TOTP secrets stored in MongoDB.
   // Must be exactly 32 bytes (64 hex characters). Generate with:
   //   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

src/modules/payments/payments.controller.ts

@@ -110,6 +110,7 @@ export const updatePaymentStatusController = asyncHandler(
 );
 
 /**
+ * GET /api/settlements/:id — full settlement detail including escrowRelease.
  * GET settlement detail including escrow/release fields.
  * Requires authentication. Used by `GET /:id` on the payments/settlements router.
  *
@@ -127,6 +128,8 @@ export const getSettlementByIdController = asyncHandler(
 );
 
 /**
+ * POST /api/settlements/:id/dispute — transition status to DISPUTED.
+ * Restricted to ADMIN / MANAGER at route level.
  * Transitions a settlement to DISPUTED with a required reason.
  * Requires auth and ADMIN / MANAGER.
  *
@@ -148,6 +151,7 @@ export const disputeSettlementController = asyncHandler(
 );
 
 /**
+ * GET /api/settlements/summary — aggregated totals + sparkline.
  * Returns aggregated settlement totals and sparkline for a period.
  * Requires authentication.
  *
@@ -160,6 +164,10 @@ export const disputeSettlementController = asyncHandler(
 export const getSettlementSummaryController = asyncHandler(
   async (req: Request, res: Response): Promise<void> => {
     const period = (req.query as Record<string, string>).period ?? 'week';
+    const summary = await getSettlementSummaryService(
+      req.user?.organizationId ?? '',
+      period
+    );
     const summary = await getSettlementSummaryService(req.user?.organizationId ?? '', period);
     sendResponse(res, 200, true, 'Settlement summary retrieved successfully', summary);
   }

src/modules/payments/payments.service.ts

@@ -197,3 +197,34 @@ export async function disputeSettlementService(id: string, input: DisputeSettlem
 
   return augmentPayment(updated);
 }
+
+/**
+ * Transitions a settlement to DISPUTED status, recording dispute metadata.
+ * Only ADMIN/MANAGER should be permitted to call this (enforced at route level).
+ * @param {string} id - Settlement ObjectId.
+ * @param {DisputeSettlementInput} input - Dispute reason and optional notes.
+ * @returns {Promise<unknown>} Updated settlement document.
+ * @throws {AppError} 404 when settlement not found.
+ */
+export async function disputeSettlementService(id: string, input: DisputeSettlementInput) {
+  const payment = await paymentsRepo.getPaymentById(id);
+  if (!payment) {
+    throw new AppError(404, 'Settlement not found', ErrorCodes.PAYMENT_NOT_FOUND);
+  }
+
+  const updated = await paymentsRepo.disputePayment(id, input.reason, input.notes);
+  if (!updated) {
+    throw new AppError(500, 'Failed to dispute settlement', ErrorCodes.INTERNAL_ERROR);
+  }
+
+  emitPaymentStatusChange(updated.shipmentId.toString(), {
+    paymentId: updated._id.toString(),
+    shipmentId: updated.shipmentId.toString(),
+    oldStatus: payment.status,
+    newStatus: updated.status,
+    amount: updated.amount,
+    timestamp: new Date().toISOString(),
+  });
+
+  return augmentPayment(updated);
+}

src/modules/payments/payments.validation.ts

@@ -95,6 +95,11 @@ export const DisputeSettlementBodySchema = z.object({
   notes: z.string().optional(),
 });
 
+export const DisputeSettlementBodySchema = z.object({
+  reason: z.string().min(1, 'Reason is required'),
+  notes: z.string().optional(),
+});
+
 export type CreatePaymentInput = z.infer<typeof CreatePaymentBodySchema>;
 export type UpdatePaymentStatusInput = z.infer<typeof UpdatePaymentStatusBodySchema>;
 export type GetPaymentsQuery = z.infer<typeof GetPaymentsQuerySchema>;

src/modules/telemetry/telemetryThreshold.service.ts

@@ -55,9 +55,15 @@ export async function updateOrgTelemetryThresholdsService(
   };
 }
 
+import mongoose from 'mongoose';
+
 export async function resolveTelemetryThresholdsForShipment(
   shipmentId: string
 ): Promise<TelemetryThresholds> {
+  if (!shipmentId || !mongoose.Types.ObjectId.isValid(shipmentId)) {
+    return mergeWithDefaults(undefined);
+  }
+
   const shipment = await Shipment.findById(shipmentId)
     .select({ enterpriseId: 1, offChainMetadata: 1 })
     .lean<{