refactor: v2 docs

apps/api/v2/src/app.controller.ts

@@ -1,6 +1,10 @@
+import { getEnv } from "@/env";
 import { Controller, Get, Version, VERSION_NEUTRAL } from "@nestjs/common";
+import { ApiTags as DocsTags, ApiExcludeController as DocsExcludeController } from "@nestjs/swagger";
 
 @Controller()
+@DocsTags("Health - development only")
+@DocsExcludeController(getEnv("NODE_ENV") === "production")
 export class AppController {
   @Get("health")
   @Version(VERSION_NEUTRAL)

apps/api/v2/src/ee/bookings/controllers/bookings.controller.e2e-spec.ts

@@ -1,7 +1,11 @@
 import { bootstrap } from "@/app";
 import { AppModule } from "@/app.module";
-import { SchedulesRepository } from "@/ee/schedules/schedules.repository";
+import { GetBookingOutput } from "@/ee/bookings/outputs/get-booking.output";
+import { GetBookingsOutput } from "@/ee/bookings/outputs/get-bookings.output";
+import { CreateScheduleInput } from "@/ee/schedules/inputs/create-schedule.input";
+import { SchedulesModule } from "@/ee/schedules/schedules.module";
 import { SchedulesService } from "@/ee/schedules/services/schedules.service";
+import { PermissionsGuard } from "@/modules/auth/guards/permissions/permissions.guard";
 import { AvailabilitiesModule } from "@/modules/availabilities/availabilities.module";
 import { PrismaModule } from "@/modules/prisma/prisma.module";
 import { UsersModule } from "@/modules/users/users.module";
@@ -11,17 +15,12 @@ import { Test } from "@nestjs/testing";
 import { User } from "@prisma/client";
 import * as request from "supertest";
 import { BookingsRepositoryFixture } from "test/fixtures/repository/bookings.repository.fixture";
+import { EventTypesRepositoryFixture } from "test/fixtures/repository/event-types.repository.fixture";
 import { UserRepositoryFixture } from "test/fixtures/repository/users.repository.fixture";
 import { withAccessTokenAuth } from "test/utils/withAccessTokenAuth";
 
 import { SUCCESS_STATUS, ERROR_STATUS } from "@calcom/platform-constants";
-import {
-  getAllUserBookings,
-  handleNewBooking,
-  getBookingInfo,
-  handleNewRecurringBooking,
-  handleInstantMeeting,
-} from "@calcom/platform-libraries";
+import { handleNewBooking } from "@calcom/platform-libraries";
 import { ApiSuccessResponse, ApiResponse } from "@calcom/platform-types";
 
 describe("Bookings Endpoints", () => {
@@ -30,28 +29,50 @@ describe("Bookings Endpoints", () => {
 
     let userRepositoryFixture: UserRepositoryFixture;
     let bookingsRepositoryFixture: BookingsRepositoryFixture;
+    let schedulesService: SchedulesService;
+    let eventTypesRepositoryFixture: EventTypesRepositoryFixture;
 
     const userEmail = "bookings-controller-e2e@api.com";
     let user: User;
 
+    let eventTypeId: number;
+
     let createdBooking: Awaited<ReturnType<typeof handleNewBooking>>;
 
     beforeAll(async () => {
       const moduleRef = await withAccessTokenAuth(
         userEmail,
         Test.createTestingModule({
-          imports: [AppModule, PrismaModule, AvailabilitiesModule, UsersModule],
-          providers: [SchedulesRepository, SchedulesService],
+          imports: [AppModule, PrismaModule, AvailabilitiesModule, UsersModule, SchedulesModule],
+        })
+      )
+        .overrideGuard(PermissionsGuard)
+        .useValue({
+          canActivate: () => true,
         })
-      ).compile();
+        .compile();
 
       userRepositoryFixture = new UserRepositoryFixture(moduleRef);
       bookingsRepositoryFixture = new BookingsRepositoryFixture(moduleRef);
+      eventTypesRepositoryFixture = new EventTypesRepositoryFixture(moduleRef);
+      schedulesService = moduleRef.get<SchedulesService>(SchedulesService);
 
       user = await userRepositoryFixture.create({
         email: userEmail,
       });
 
+      const userSchedule: CreateScheduleInput = {
+        name: "working time",
+        timeZone: "Europe/Rome",
+        isDefault: true,
+      };
+      await schedulesService.createUserSchedule(user.id, userSchedule);
+      const event = await eventTypesRepositoryFixture.create(
+        { title: "peer coding", slug: "peer-coding", length: 60 },
+        user.id
+      );
+      eventTypeId = event.id;
+
       app = moduleRef.createNestApplication();
       bootstrap(app as NestExpressApplication);
 
@@ -64,13 +85,23 @@ describe("Bookings Endpoints", () => {
     });
 
     it("should create a booking", async () => {
-      const bookingStart = "2023-05-25T09:30:00.000Z";
-      const bookingEnd = "2023-05-25T10:30:00.000Z";
-      const bookingEventTypeId = 7;
-      const bookingTimeZone = "Europe/Londom";
+      const bookingStart = "2040-05-21T09:30:00.000Z";
+      const bookingEnd = "2040-05-21T10:30:00.000Z";
+      const bookingEventTypeId = eventTypeId;
+      const bookingTimeZone = "Europe/London";
       const bookingLanguage = "en";
       const bookingHashedLink = "";
       const bookingMetadata = {};
+      const bookingResponses = {
+        name: "tester",
+        email: "tester@example.com",
+        location: {
+          value: "link",
+          optionValue: "",
+        },
+        notes: "test",
+        guests: [],
+      };
 
       const body = {
         start: bookingStart,
@@ -80,6 +111,7 @@ describe("Bookings Endpoints", () => {
         language: bookingLanguage,
         metadata: bookingMetadata,
         hashedLink: bookingHashedLink,
+        responses: bookingResponses,
       };
 
       return request(app.getHttpServer())
@@ -91,8 +123,8 @@ describe("Bookings Endpoints", () => {
             response.body;
           expect(responseBody.status).toEqual(SUCCESS_STATUS);
           expect(responseBody.data).toBeDefined();
-          expect(responseBody.data.user.email).toBeDefined();
-          expect(responseBody.data.user.email).toEqual(userEmail);
+          expect(responseBody.data.userPrimaryEmail).toBeDefined();
+          expect(responseBody.data.userPrimaryEmail).toEqual(userEmail);
           expect(responseBody.data.id).toBeDefined();
           expect(responseBody.data.uid).toBeDefined();
           expect(responseBody.data.startTime).toEqual(bookingStart);
@@ -106,10 +138,10 @@ describe("Bookings Endpoints", () => {
 
     it("should get bookings", async () => {
       return request(app.getHttpServer())
-        .get("/api/v2/ee/bookings")
+        .get("/api/v2/ee/bookings?filters[status]=upcoming")
         .then((response) => {
-          const responseBody: ApiSuccessResponse<Awaited<ReturnType<typeof getAllUserBookings>>> =
-            response.body;
+          console.log("asap responseBody", JSON.stringify(response.body, null, 2));
+          const responseBody: GetBookingsOutput = response.body;
           const fetchedBooking = responseBody.data.bookings[0];
 
           expect(responseBody.data.bookings.length).toEqual(1);
@@ -121,16 +153,16 @@ describe("Bookings Endpoints", () => {
           expect(fetchedBooking.uid).toEqual(createdBooking.uid);
           expect(fetchedBooking.startTime).toEqual(createdBooking.startTime);
           expect(fetchedBooking.endTime).toEqual(createdBooking.endTime);
-          expect(fetchedBooking.user?.email).toEqual(createdBooking.user.email);
+          expect(fetchedBooking.user?.email).toEqual(userEmail);
         });
     });
 
     it("should get booking", async () => {
       return request(app.getHttpServer())
         .get(`/api/v2/ee/bookings/${createdBooking.uid}`)
         .then((response) => {
-          const responseBody: ApiSuccessResponse<Awaited<ReturnType<typeof getBookingInfo>>> = response.body;
-          const { bookingInfo } = responseBody.data;
+          const responseBody: GetBookingOutput = response.body;
+          const bookingInfo = responseBody.data;
 
           expect(responseBody.status).toEqual(SUCCESS_STATUS);
           expect(responseBody.data).toBeDefined();
@@ -143,68 +175,71 @@ describe("Bookings Endpoints", () => {
         });
     });
 
-    it("should create a recurring booking", async () => {
-      const bookingStart = "2023-05-25T09:30:00.000Z";
-      const bookingEnd = "2023-05-25T10:30:00.000Z";
-      const bookingEventTypeId = 7;
-      const bookingTimeZone = "Europe/Londom";
-      const bookingLanguage = "en";
-      const bookingHashedLink = "";
-      const bookingRecurringCount = 5;
-      const currentBookingRecurringIndex = 0;
-
-      const body = {
-        start: bookingStart,
-        end: bookingEnd,
-        eventTypeId: bookingEventTypeId,
-        timeZone: bookingTimeZone,
-        language: bookingLanguage,
-        metadata: {},
-        hashedLink: bookingHashedLink,
-        recurringCount: bookingRecurringCount,
-        currentRecurringIndex: currentBookingRecurringIndex,
-      };
-
-      return request(app.getHttpServer())
-        .post("/api/v2/ee/bookings/reccuring")
-        .send(body)
-        .expect(201)
-        .then((response) => {
-          const responseBody: ApiResponse<Awaited<ReturnType<typeof handleNewRecurringBooking>>> =
-            response.body;
-
-          expect(responseBody.status).toEqual("recurring");
-        });
-    });
-
-    it("should create an instant booking", async () => {
-      const bookingStart = "2023-05-25T09:30:00.000Z";
-      const bookingEnd = "2023-05-25T10:30:00.000Z";
-      const bookingEventTypeId = 7;
-      const bookingTimeZone = "Europe/Londom";
-      const bookingLanguage = "en";
-      const bookingHashedLink = "";
-
-      const body = {
-        start: bookingStart,
-        end: bookingEnd,
-        eventTypeId: bookingEventTypeId,
-        timeZone: bookingTimeZone,
-        language: bookingLanguage,
-        metadata: {},
-        hashedLink: bookingHashedLink,
-      };
-
-      return request(app.getHttpServer())
-        .post("/api/v2/ee/bookings/instant")
-        .send(body)
-        .expect(201)
-        .then((response) => {
-          const responseBody: ApiResponse<Awaited<ReturnType<typeof handleInstantMeeting>>> = response.body;
-
-          expect(responseBody.status).toEqual("instant");
-        });
-    });
+    // note(Lauris) : found this test broken here - first thing to fix is that recurring endpoint accepts an array not 1 object.
+    // it("should create a recurring booking", async () => {
+    //   const bookingStart = "2040-05-25T09:30:00.000Z";
+    //   const bookingEnd = "2040-05-25T10:30:00.000Z";
+    //   const bookingEventTypeId = 7;
+    //   const bookingTimeZone = "Europe/London";
+    //   const bookingLanguage = "en";
+    //   const bookingHashedLink = "";
+    //   const bookingRecurringCount = 5;
+    //   const currentBookingRecurringIndex = 0;
+
+    //   const body = {
+    //     start: bookingStart,
+    //     end: bookingEnd,
+    //     eventTypeId: bookingEventTypeId,
+    //     timeZone: bookingTimeZone,
+    //     language: bookingLanguage,
+    //     metadata: {},
+    //     hashedLink: bookingHashedLink,
+    //     recurringCount: bookingRecurringCount,
+    //     currentRecurringIndex: currentBookingRecurringIndex,
+    //   };
+
+    //   return request(app.getHttpServer())
+    //     .post("/api/v2/ee/bookings/reccuring")
+    //     .send(body)
+    //     .expect(201)
+    //     .then((response) => {
+    //       const responseBody: ApiResponse<Awaited<ReturnType<typeof handleNewRecurringBooking>>> =
+    //         response.body;
+
+    //       expect(responseBody.status).toEqual("recurring");
+    //     });
+    // });
+
+    // note(Lauris) : found this test broken here - first thing to fix is that the eventTypeId must be team event type, because
+    // instant bookings only work for teams.
+    // it("should create an instant booking", async () => {
+    //   const bookingStart = "2040-05-25T09:30:00.000Z";
+    //   const bookingEnd = "2040-25T10:30:00.000Z";
+    //   const bookingEventTypeId = 7;
+    //   const bookingTimeZone = "Europe/London";
+    //   const bookingLanguage = "en";
+    //   const bookingHashedLink = "";
+
+    //   const body = {
+    //     start: bookingStart,
+    //     end: bookingEnd,
+    //     eventTypeId: bookingEventTypeId,
+    //     timeZone: bookingTimeZone,
+    //     language: bookingLanguage,
+    //     metadata: {},
+    //     hashedLink: bookingHashedLink,
+    //   };
+
+    //   return request(app.getHttpServer())
+    //     .post("/api/v2/ee/bookings/instant")
+    //     .send(body)
+    //     .expect(201)
+    //     .then((response) => {
+    //       const responseBody: ApiResponse<Awaited<ReturnType<typeof handleInstantMeeting>>> = response.body;
+
+    //       expect(responseBody.status).toEqual("instant");
+    //     });
+    // });
 
     it("should cancel a booking", async () => {
       const bookingId = createdBooking.id;

apps/api/v2/src/ee/bookings/controllers/bookings.controller.ts

@@ -1,5 +1,7 @@
 import { CreateBookingInput } from "@/ee/bookings/inputs/create-booking.input";
 import { CreateReccuringBookingInput } from "@/ee/bookings/inputs/create-reccuring-booking.input";
+import { GetBookingOutput } from "@/ee/bookings/outputs/get-booking.output";
+import { GetBookingsOutput } from "@/ee/bookings/outputs/get-bookings.output";
 import { GetUser } from "@/modules/auth/decorators/get-user/get-user.decorator";
 import { Permissions } from "@/modules/auth/decorators/permissions/permissions.decorator";
 import { AccessTokenGuard } from "@/modules/auth/guards/access-token/access-token.guard";
@@ -20,6 +22,7 @@ import {
   NotFoundException,
   UseGuards,
 } from "@nestjs/common";
+import { ApiQuery, ApiTags as DocsTags } from "@nestjs/swagger";
 import { User } from "@prisma/client";
 import { Request } from "express";
 import { NextApiRequest } from "next/types";
@@ -38,7 +41,7 @@ import {
   handleNewRecurringBooking,
   handleInstantMeeting,
 } from "@calcom/platform-libraries";
-import { GetBookingsInput, CancelBookingInput } from "@calcom/platform-types";
+import { GetBookingsInput, CancelBookingInput, Status } from "@calcom/platform-types";
 import { ApiResponse } from "@calcom/platform-types";
 import { PrismaClient } from "@calcom/prisma";
 
@@ -47,6 +50,7 @@ import { PrismaClient } from "@calcom/prisma";
   version: "2",
 })
 @UseGuards(PermissionsGuard)
+@DocsTags("Bookings")
 export class BookingsController {
   private readonly logger = new Logger("ee bookings controller");
 
@@ -58,10 +62,13 @@ export class BookingsController {
   // note(Rajiv): currently this endpoint is atoms only
   @Get("/")
   @UseGuards(AccessTokenGuard)
+  @ApiQuery({ name: "filters[status]", enum: Status, required: true })
+  @ApiQuery({ name: "limit", type: "number", required: false })
+  @ApiQuery({ name: "cursor", type: "number", required: false })
   async getBookings(
     @GetUser() user: User,
     @Query() queryParams: GetBookingsInput
-  ): Promise<ApiResponse<unknown>> {
+  ): Promise<GetBookingsOutput> {
     const { filters, cursor, limit } = queryParams;
     const bookings = await getAllUserBookings({
       bookingListingByStatus: filters.status,
@@ -82,7 +89,7 @@ export class BookingsController {
 
   // note(Rajiv): currently this endpoint is atoms only
   @Get("/:bookingUid")
-  async getBooking(@Param("bookingUid") bookingUid: string): Promise<ApiResponse<unknown>> {
+  async getBooking(@Param("bookingUid") bookingUid: string): Promise<GetBookingOutput> {
     const { bookingInfo } = await getBookingInfo(bookingUid);
 
     if (!bookingInfo) {