pagination for list endpoints && Health Endpoint

api/package.json

@@ -18,6 +18,7 @@
     "@nestjs/platform-socket.io": "^10.4.22",
     "@nestjs/swagger": "^7.4.2",
     "@nestjs/throttler": "^6.5.0",
+    "@nestjs/terminus": "^10.0.0",
     "@nestjs/websockets": "^10.4.22",
     "cache-manager": "^5.7.6",
     "class-transformer": "^0.5.1",

api/src/app.module.ts

@@ -4,7 +4,7 @@ import { ThrottlerGuard, ThrottlerModule } from "@nestjs/throttler"
 import { AdminModule } from "./admin/admin.module"
 import { AuditModule } from "./audit/audit.module"
 import { GatewaysModule } from "./gateways/gateways.module"
-import { HealthController } from "./health/health.controller"
+import { HealthModule } from "./health/health.module"
 import { TagsModule } from "./tags/tags.module"
 
 @Module({
@@ -18,9 +18,9 @@ import { TagsModule } from "./tags/tags.module"
     AdminModule,
     AuditModule,
     GatewaysModule,
+    HealthModule,
     TagsModule,
   ],
-  controllers: [HealthController],
   providers: [
     {
       provide: APP_GUARD,

api/src/audit/admin-audit.controller.ts

@@ -1,15 +1,15 @@
 import { Controller, Get, Query } from "@nestjs/common"
 import { AuditService } from "./audit.service"
+import { PaginationQueryDto } from "../common/dto/pagination.dto"
 
 @Controller("admin/audit-logs")
 export class AdminAuditController {
   constructor(private readonly auditService: AuditService) {}
 
   @Get()
-  findAll(
-    @Query("limit") limit = "100",
-    @Query("offset") offset = "0",
-  ) {
-    return this.auditService.findAll(parseInt(limit), parseInt(offset))
+  async findAll(@Query() query: PaginationQueryDto) {
+    const page = query.page ?? 1
+    const limit = query.limit ?? 20
+    return this.auditService.findAll(page, limit)
   }
 }

api/src/audit/audit.service.ts

@@ -12,11 +12,22 @@ export class AuditService {
     )
   }
 
-  async findAll(limit = 100, offset = 0) {
+  async findAll(page = 1, limit = 20) {
+    const offset = (page - 1) * limit
+    const totalResult = await this.pool.query(
+      "SELECT COUNT(*)::int AS total FROM audit_logs",
+    )
+    const total = totalResult.rows[0]?.total ?? 0
     const { rows } = await this.pool.query(
       "SELECT * FROM audit_logs ORDER BY created_at DESC LIMIT $1 OFFSET $2",
       [limit, offset],
     )
-    return rows
+
+    return {
+      data: rows,
+      total,
+      page,
+      limit,
+    }
   }
 }

api/src/common/dto/pagination.dto.ts

@@ -0,0 +1,35 @@
+import { ApiPropertyOptional } from "@nestjs/swagger"
+import { Type } from "class-transformer"
+import { IsInt, IsOptional, Max, Min } from "class-validator"
+
+export class PaginationQueryDto {
+  @ApiPropertyOptional({
+    description: "Page number to return. 1-indexed.",
+    example: 1,
+    default: 1,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: "page must be an integer" })
+  @Min(1, { message: "page must be >= 1" })
+  page?: number = 1
+
+  @ApiPropertyOptional({
+    description: "Number of items per page. Maximum 100.",
+    example: 20,
+    default: 20,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt({ message: "limit must be an integer" })
+  @Min(1, { message: "limit must be >= 1" })
+  @Max(100, { message: "limit must be <= 100" })
+  limit?: number = 20
+}
+
+export interface PaginatedResult<T> {
+  total: number
+  page: number
+  limit: number
+  data: T[]
+}

api/src/health/database.health-indicator.ts

@@ -0,0 +1,21 @@
+import { HealthCheckError, HealthIndicator, HealthIndicatorResult } from "@nestjs/terminus"
+import { Injectable, OnModuleDestroy } from "@nestjs/common"
+import { Pool } from "pg"
+
+@Injectable()
+export class DatabaseHealthIndicator extends HealthIndicator implements OnModuleDestroy {
+  private readonly pool = new Pool({ connectionString: process.env.DATABASE_URL })
+
+  async isHealthy(key: string): Promise<HealthIndicatorResult> {
+    try {
+      await this.pool.query("SELECT 1")
+      return this.getStatus(key, true)
+    } catch (error) {
+      throw new HealthCheckError("database", error)
+    }
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.pool.end()
+  }
+}

api/src/health/health.controller.ts

@@ -1,5 +1,8 @@
-import { Controller, Get } from "@nestjs/common"
+import { Controller, Get, ServiceUnavailableException } from "@nestjs/common"
 import { ApiOkResponse, ApiOperation, ApiProperty, ApiTags } from "@nestjs/swagger"
+import { HealthCheckService } from "@nestjs/terminus"
+import { SkipThrottle } from "@nestjs/throttler"
+import { DatabaseHealthIndicator } from "./database.health-indicator"
 
 export class HealthCheckResponseDto {
   @ApiProperty({
@@ -19,15 +22,30 @@ export class HealthCheckResponseDto {
 @ApiTags("health")
 @Controller("health")
 export class HealthController {
+  constructor(
+    private readonly healthCheckService: HealthCheckService,
+    private readonly databaseHealthIndicator: DatabaseHealthIndicator,
+  ) {}
+
   @Get()
+  @SkipThrottle()
   @ApiOperation({
     summary: "Liveness probe",
     description:
       "Returns a fixed `ok` status and the current server timestamp. " +
-      "Intended for use by load balancers and orchestrators.",
+      "Also verifies the database connection for liveness checks.",
   })
   @ApiOkResponse({ type: HealthCheckResponseDto })
-  check(): HealthCheckResponseDto {
-    return { status: "ok", timestamp: new Date().toISOString() }
+  async check(): Promise<HealthCheckResponseDto> {
+    try {
+      await this.healthCheckService.check([
+        async () => this.databaseHealthIndicator.isHealthy("database"),
+      ])
+      return { status: "ok", timestamp: new Date().toISOString() }
+    } catch (error) {
+      throw new ServiceUnavailableException(
+        "Database connectivity check failed.",
+      )
+    }
   }
 }

api/src/health/health.module.ts

@@ -0,0 +1,11 @@
+import { Module } from "@nestjs/common"
+import { TerminusModule } from "@nestjs/terminus"
+import { DatabaseHealthIndicator } from "./database.health-indicator"
+import { HealthController } from "./health.controller"
+
+@Module({
+  imports: [TerminusModule],
+  controllers: [HealthController],
+  providers: [DatabaseHealthIndicator],
+})
+export class HealthModule {}

api/src/tags/dto/list-tags.query.dto.ts

@@ -1,22 +1,8 @@
-import { Type } from "class-transformer"
-import { IsInt, IsOptional, Max, Min } from "class-validator"
+import { PaginationQueryDto } from "../../common/dto/pagination.dto"
 
 /**
  * Query parameters for the public `GET /tags` endpoint.
  *
  * `page` is 1-indexed; `limit` is capped at 100 to keep payloads bounded.
  */
-export class ListTagsQueryDto {
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt({ message: "page must be an integer" })
-  @Min(1, { message: "page must be >= 1" })
-  page?: number = 1
-
-  @IsOptional()
-  @Type(() => Number)
-  @IsInt({ message: "limit must be an integer" })
-  @Min(1, { message: "limit must be >= 1" })
-  @Max(100, { message: "limit must be <= 100" })
-  limit?: number = 20
-}
+export class ListTagsQueryDto extends PaginationQueryDto {}

api/src/tags/tags.service.ts

@@ -3,15 +3,12 @@ import {
   Injectable,
   NotFoundException,
 } from "@nestjs/common"
+import { PaginatedResult } from "../common/dto/pagination.dto"
 import { TagsRepository } from "./repository/tags.repository"
 import { slugify } from "./slugify"
 import { Tag } from "./tag.entity"
 
-export interface PagedTags {
-  items: Tag[]
-  page: number
-  limit: number
-  total: number
+export interface PagedTags extends PaginatedResult<Tag> {
   hasMore: boolean
 }
 
@@ -22,7 +19,7 @@ export class TagsService {
   list(page: number, limit: number): PagedTags {
     const { items, total } = this.tags.listPaginated(page, limit)
     return {
-      items,
+      data: items,
       page,
       limit,
       total,