feat: v2 managed organizations pagination (calcom#21359)

* feat: getPagination helper

* refactor: bookings use getPagination helper

* feat: getPagination helper

* refactor: group pagination inputs and outputs in types/pagination

* feat: paginated managed orgs

* fix tests

* swagger

Author: supalarry

apps/api/v2/src/ee/bookings/2024-08-13/services/bookings.service.ts

@@ -5,6 +5,7 @@ import { InputBookingsService_2024_08_13 } from "@/ee/bookings/2024-08-13/servic
 import { OutputBookingsService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/output.service";
 import { PlatformBookingsService } from "@/ee/bookings/shared/platform-bookings.service";
 import { EventTypesRepository_2024_06_14 } from "@/ee/event-types/event-types_2024_06_14/event-types.repository";
+import { getPagination } from "@/lib/pagination/pagination";
 import { BillingService } from "@/modules/billing/services/billing.service";
 import { BookingSeatRepository } from "@/modules/booking-seat/booking-seat.repository";
 import { KyselyReadService } from "@/modules/kysely/kysely-read.service";
@@ -538,10 +539,13 @@ export class BookingsService_2024_08_13 {
       queryParams.attendeeEmail = await this.getAttendeeEmail(queryParams.attendeeEmail, user);
     }
 
+    const skip = Math.abs(queryParams?.skip ?? 0);
+    const take = Math.abs(queryParams?.take ?? 100);
+
     const fetchedBookings: { bookings: { id: number }[]; totalCount: number } = await getAllUserBookings({
       bookingListingByStatus: queryParams.status || [],
-      skip: queryParams.skip ?? 0,
-      take: queryParams.take ?? 100,
+      skip,
+      take,
       filters: {
         ...this.inputService.transformGetBookingsFilters(queryParams),
         ...(userIds?.length ? { userIds } : {}),
@@ -594,28 +598,11 @@ export class BookingsService_2024_08_13 {
       }
     }
 
-    const skip = Math.abs(queryParams?.skip ?? 0);
-    const take = Math.abs(queryParams?.take ?? 100);
-    const itemsPerPage = take;
-    const totalPages = itemsPerPage !== 0 ? Math.ceil(fetchedBookings.totalCount / itemsPerPage) : 0;
-    const currentPage = Math.floor(skip / itemsPerPage) + 1;
-    const hasNextPage = skip + itemsPerPage < fetchedBookings.totalCount;
-    const hasPreviousPage = skip > 0;
+    const pagination = getPagination({ skip, take, totalCount: fetchedBookings.totalCount });
+
     return {
       bookings: formattedBookings,
-      pagination: {
-        totalItems: fetchedBookings.totalCount,
-        // clamp remainingItems between 0 and totalCount
-        remainingItems: Math.min(
-          Math.max(fetchedBookings.totalCount - (skip + take), 0),
-          fetchedBookings.totalCount
-        ),
-        itemsPerPage: itemsPerPage,
-        currentPage: currentPage,
-        totalPages: totalPages,
-        hasNextPage: hasNextPage,
-        hasPreviousPage: hasPreviousPage,
-      },
+      pagination,
     };
   }
 

apps/api/v2/src/lib/pagination/pagination.spec.ts

@@ -0,0 +1,101 @@
+import { getPagination, clamp } from "./pagination";
+
+describe("getPagination", () => {
+  it("handles the first page correctly", () => {
+    const pagination = getPagination({ skip: 0, take: 10, totalCount: 35 });
+    expect(pagination).toEqual({
+      returnedItems: 10,
+      totalItems: 35,
+      itemsPerPage: 10,
+      remainingItems: 25,
+      currentPage: 1,
+      totalPages: 4,
+      hasNextPage: true,
+      hasPreviousPage: false,
+    });
+  });
+
+  it("handles a middle page correctly", () => {
+    const pagination = getPagination({ skip: 10, take: 10, totalCount: 35 });
+    expect(pagination).toEqual({
+      returnedItems: 10,
+      totalItems: 35,
+      itemsPerPage: 10,
+      remainingItems: 15,
+      currentPage: 2,
+      totalPages: 4,
+      hasNextPage: true,
+      hasPreviousPage: true,
+    });
+  });
+
+  it("handles the last page when it is not completely full", () => {
+    const pagination = getPagination({ skip: 30, take: 10, totalCount: 35 });
+    expect(pagination).toEqual({
+      returnedItems: 5,
+      totalItems: 35,
+      itemsPerPage: 10,
+      remainingItems: 0,
+      currentPage: 4,
+      totalPages: 4,
+      hasNextPage: false,
+      hasPreviousPage: true,
+    });
+  });
+
+  it("clamps skip values that exceed the total item count", () => {
+    const pagination = getPagination({ skip: 40, take: 10, totalCount: 35 });
+    expect(pagination).toEqual({
+      returnedItems: 0,
+      totalItems: 35,
+      itemsPerPage: 10,
+      remainingItems: 0,
+      currentPage: 4,
+      totalPages: 4,
+      hasNextPage: false,
+      hasPreviousPage: true,
+    });
+  });
+
+  it("works when itemsPerPage (take) is zero", () => {
+    const pagination = getPagination({ skip: 0, take: 0, totalCount: 35 });
+    expect(pagination).toEqual({
+      returnedItems: 0,
+      totalItems: 35,
+      itemsPerPage: 0,
+      remainingItems: 35,
+      currentPage: 0,
+      totalPages: 0,
+      hasNextPage: true,
+      hasPreviousPage: false,
+    });
+  });
+
+  it("works when the collection is empty", () => {
+    const pagination = getPagination({ skip: 0, take: 10, totalCount: 0 });
+    expect(pagination).toEqual({
+      returnedItems: 0,
+      totalItems: 0,
+      itemsPerPage: 10,
+      remainingItems: 0,
+      currentPage: 0,
+      totalPages: 0,
+      hasNextPage: false,
+      hasPreviousPage: false,
+    });
+  });
+});
+
+describe("clamp", () => {
+  it("returns the value unchanged when it is inside the range", () => {
+    expect(clamp({ value: 5, min: 1, max: 10 })).toBe(5);
+  });
+
+  it("clamps values below the minimum", () => {
+    expect(clamp({ value: -3, min: 0, max: 10 })).toBe(0);
+  });
+
+  it("clamps values above the maximum", () => {
+    expect(clamp({ value: 42, min: 0, max: 10 })).toBe(10);
+  });
+});

apps/api/v2/src/lib/pagination/pagination.ts

@@ -0,0 +1,78 @@
+import { PaginationMetaDto } from "@calcom/platform-types";
+
+type Pagination = {
+  skip: number;
+  take: number;
+  totalCount: number;
+};
+
+export function getPagination(pagination: Pagination): PaginationMetaDto {
+  const { skip, take, totalCount } = pagination;
+
+  const safeSkip = clamp({ value: skip, min: 0, max: totalCount });
+  const itemsPerPage = take;
+  const remainingItems = getRemainingItems(safeSkip, itemsPerPage, totalCount);
+  const totalPages = getTotalPages(itemsPerPage, totalCount);
+  const currentPage = getCurrentPage(safeSkip, itemsPerPage, totalPages);
+  const hasNextPage = getHasNextPage(safeSkip, itemsPerPage, totalCount);
+  const hasPreviousPage = getHasPreviousPage(safeSkip);
+  const returnedItems = getReturnedItems(safeSkip, itemsPerPage, totalCount);
+
+  return {
+    returnedItems,
+    totalItems: totalCount,
+    itemsPerPage,
+    remainingItems,
+    currentPage,
+    totalPages,
+    hasNextPage,
+    hasPreviousPage,
+  };
+}
+
+function getRemainingItems(skip: number, itemsPerPage: number, totalCount: number) {
+  return clamp({
+    value: totalCount - (skip + itemsPerPage),
+    min: 0,
+    max: totalCount,
+  });
+}
+
+function getTotalPages(itemsPerPage: number, totalCount: number) {
+  return itemsPerPage !== 0 ? Math.ceil(totalCount / itemsPerPage) : 0;
+}
+
+function getCurrentPage(skip: number, itemsPerPage: number, totalPages: number) {
+  const rawCurrentPage = Math.floor(skip / itemsPerPage) + 1;
+  if (totalPages === 0) {
+    return 0;
+  }
+  return clamp({ value: rawCurrentPage, min: 1, max: totalPages });
+}
+
+function getHasNextPage(skip: number, itemsPerPage: number, totalCount: number) {
+  return skip + itemsPerPage < totalCount;
+}
+
+function getHasPreviousPage(skip: number) {
+  return skip > 0;
+}
+
+function getReturnedItems(skip: number, itemsPerPage: number, totalCount: number) {
+  const remaining = totalCount - skip;
+  return clamp({
+    value: remaining,
+    min: 0,
+    max: itemsPerPage,
+  });
+}
+
+type ClampArgs = {
+  value: number;
+  min: number;
+  max: number;
+};
+
+export function clamp({ value, min, max }: ClampArgs): number {
+  return Math.max(min, Math.min(value, max));
+}

apps/api/v2/src/modules/organizations/organizations/managed-organizations.repository.ts

@@ -2,6 +2,7 @@ import { PrismaReadService } from "@/modules/prisma/prisma-read.service";
 import { PrismaWriteService } from "@/modules/prisma/prisma-write.service";
 import { Injectable } from "@nestjs/common";
 
+import { SkipTakePagination } from "@calcom/platform-types";
 import { Prisma } from "@calcom/prisma/client";
 
 @Injectable()
@@ -34,11 +35,26 @@ export class ManagedOrganizationsRepository {
     });
   }
 
-  async getByManagerOrganizationId(managerOrganizationId: number) {
-    return this.dbRead.prisma.managedOrganization.findMany({
-      where: {
-        managerOrganizationId,
-      },
-    });
+  async getByManagerOrganizationIdPaginated(managerOrganizationId: number, pagination: SkipTakePagination) {
+    const { skip, take } = pagination;
+
+    const where: Prisma.ManagedOrganizationWhereInput = {
+      managerOrganizationId,
+    };
+
+    const [totalItems, linkRows] = await this.dbRead.prisma.$transaction([
+      this.dbRead.prisma.managedOrganization.count({ where }),
+      this.dbRead.prisma.managedOrganization.findMany({
+        where,
+        skip,
+        take,
+        orderBy: { managedOrganizationId: "asc" },
+        include: { managedOrganization: true },
+      }),
+    ]);
+
+    const items = linkRows.map((l) => l.managedOrganization);
+
+    return { totalItems, items };
   }
 }

apps/api/v2/src/modules/organizations/organizations/organizations-organizations.controller.e2e-spec.ts

@@ -7,6 +7,7 @@ import { CreateOAuthClientResponseDto } from "@/modules/oauth-clients/controller
 import { GetOAuthClientResponseDto } from "@/modules/oauth-clients/controllers/oauth-clients/responses/GetOAuthClientResponse.dto";
 import { CreateOrganizationInput } from "@/modules/organizations/organizations/inputs/create-managed-organization.input";
 import { UpdateOrganizationInput } from "@/modules/organizations/organizations/inputs/update-managed-organization.input";
+import { GetManagedOrganizationsOutput } from "@/modules/organizations/organizations/outputs/get-managed-organizations.output";
 import {
   ManagedOrganizationWithApiKeyOutput,
   ManagedOrganizationOutput,
@@ -304,14 +305,22 @@ describe("Organizations Organizations Endpoints", () => {
       .set("Authorization", `Bearer ${managerOrgAdminApiKey}`)
       .expect(200)
       .then(async (response) => {
-        const responseBody: ApiSuccessResponse<ManagedOrganizationOutput[]> = response.body;
+        const responseBody: GetManagedOrganizationsOutput = response.body;
         expect(responseBody.status).toEqual(SUCCESS_STATUS);
         const responseManagedOrgs = responseBody.data;
         expect(responseManagedOrgs?.length).toEqual(1);
         const responseManagedOrg = responseManagedOrgs[0];
         expect(responseManagedOrg?.id).toBeDefined();
         expect(responseManagedOrg?.name).toEqual(managedOrg.name);
         expect(responseManagedOrg?.metadata).toEqual(managedOrg.metadata);
+
+        expect(responseBody.pagination).toBeDefined();
+        expect(responseBody.pagination.totalItems).toEqual(1);
+        expect(responseBody.pagination.remainingItems).toEqual(0);
+        expect(responseBody.pagination.returnedItems).toEqual(1);
+        expect(responseBody.pagination.itemsPerPage).toEqual(250);
+        expect(responseBody.pagination.currentPage).toEqual(1);
+        expect(responseBody.pagination.totalPages).toEqual(1);
       });
   });
 

apps/api/v2/src/modules/organizations/organizations/organizations-organizations.controller.ts

@@ -28,10 +28,12 @@ import {
   HttpCode,
   HttpStatus,
   Delete,
+  Query,
 } from "@nestjs/common";
 import { ApiHeader, ApiOperation, ApiTags as DocsTags } from "@nestjs/swagger";
 
 import { SUCCESS_STATUS } from "@calcom/platform-constants";
+import { SkipTakePagination } from "@calcom/platform-types";
 
 const SCALE = "SCALE";
 
@@ -99,14 +101,15 @@ export class OrganizationsOrganizationsController {
       "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
   })
   async getOrganizations(
-    @Param("orgId", ParseIntPipe) managerOrganizationId: number
+    @Param("orgId", ParseIntPipe) managerOrganizationId: number,
+    @Query() queryPagination: SkipTakePagination
   ): Promise<GetManagedOrganizationsOutput> {
-    const organizations = await this.managedOrganizationsService.getManagedOrganizations(
-      managerOrganizationId
-    );
+    const { organizations, pagination: responsePagination } =
+      await this.managedOrganizationsService.getManagedOrganizations(managerOrganizationId, queryPagination);
     return {
       status: SUCCESS_STATUS,
       data: organizations,
+      pagination: responsePagination,
     };
   }
 

apps/api/v2/src/modules/organizations/organizations/outputs/get-managed-organizations.output.ts

@@ -4,6 +4,7 @@ import { Expose, Type } from "class-transformer";
 import { IsEnum, ValidateNested } from "class-validator";
 
 import { ERROR_STATUS, SUCCESS_STATUS } from "@calcom/platform-constants";
+import { PaginationMetaDto } from "@calcom/platform-types";
 
 export class GetManagedOrganizationsOutput {
   @ApiProperty({ example: SUCCESS_STATUS, enum: [SUCCESS_STATUS, ERROR_STATUS] })
@@ -17,4 +18,9 @@ export class GetManagedOrganizationsOutput {
   @ValidateNested({ each: true })
   @Type(() => ManagedOrganizationOutput)
   data!: ManagedOrganizationOutput[];
+
+  @ApiProperty({ type: () => PaginationMetaDto })
+  @Type(() => PaginationMetaDto)
+  @ValidateNested()
+  pagination!: PaginationMetaDto;
 }