feat: api v2 POST booking attendees endpoint (calcom#27759)

* feat: add booking attendee endpoint

* chore: add attendee added email for add guests handler

* cleanup

* fix: restore BookingPbacGuard to prevent IDOR vulnerability in booking attendees endpoint

Co-Authored-By: unknown <>

* chore: implement review feedback, add a core service for booking attendees endpoint

* chore: implement PR feedback

* fix: dont reuse add guests handler instead add logic to add attendee function

* fix: revert previous changes

* chore: implement cubic feedback

* fix: e2e tests

* fix: e2e tests

* fix: remove convertTRPCErrorToErrorWithCode not needed

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: Ryukemeister

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

@@ -1,9 +1,12 @@
+import { Module } from "@nestjs/common";
+import { BookingAttendeesController_2024_08_13 } from "@/ee/bookings/2024-08-13/controllers/booking-attendees.controller";
 import { BookingGuestsController_2024_08_13 } from "@/ee/bookings/2024-08-13/controllers/booking-guests.controller";
 import { BookingLocationController_2024_08_13 } from "@/ee/bookings/2024-08-13/controllers/booking-location.controller";
 import { BookingsController_2024_08_13 } from "@/ee/bookings/2024-08-13/controllers/bookings.controller";
 import { BookingPbacGuard } from "@/ee/bookings/2024-08-13/guards/booking-pbac.guard";
 import { BookingReferencesRepository_2024_08_13 } from "@/ee/bookings/2024-08-13/repositories/booking-references.repository";
 import { BookingsRepository_2024_08_13 } from "@/ee/bookings/2024-08-13/repositories/bookings.repository";
+import { BookingAttendeesService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/booking-attendees.service";
 import { BookingGuestsService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/booking-guests.service";
 import { BookingLocationService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/booking-location.service";
 import { BookingReferencesService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/booking-references.service";
@@ -12,17 +15,18 @@ import { CalVideoOutputService } from "@/ee/bookings/2024-08-13/services/cal-vid
 import { CalVideoService } from "@/ee/bookings/2024-08-13/services/cal-video.service";
 import { ErrorsBookingsService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/errors.service";
 import { InputBookingsService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/input.service";
-import { OutputBookingReferencesService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/output-booking-references.service";
 import { OutputBookingsService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/output.service";
+import { OutputBookingReferencesService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/output-booking-references.service";
 import { PlatformBookingsService } from "@/ee/bookings/shared/platform-bookings.service";
 import { CalendarsRepository } from "@/ee/calendars/calendars.repository";
-import { CalendarsCacheService } from "@/ee/calendars/services/calendars-cache.service";
 import { CalendarsService } from "@/ee/calendars/services/calendars.service";
+import { CalendarsCacheService } from "@/ee/calendars/services/calendars-cache.service";
 import { EventTypesModule_2024_04_15 } from "@/ee/event-types/event-types_2024_04_15/event-types.module";
 import { EventTypesModule_2024_06_14 } from "@/ee/event-types/event-types_2024_06_14/event-types.module";
 import { EventTypesRepository_2024_06_14 } from "@/ee/event-types/event-types_2024_06_14/event-types.repository";
 import { OutputEventTypesService_2024_06_14 } from "@/ee/event-types/event-types_2024_06_14/services/output-event-types.service";
 import { SchedulesModule_2024_04_15 } from "@/ee/schedules/schedules_2024_04_15/schedules.module";
+import { BookingEventHandlerModule } from "@/lib/modules/booking-event-handler.module";
 import { InstantBookingModule } from "@/lib/modules/instant-booking.module";
 import { RecurringBookingModule } from "@/lib/modules/recurring-booking.module";
 import { RegularBookingModule } from "@/lib/modules/regular-booking.module";
@@ -50,8 +54,6 @@ import { TeamsModule } from "@/modules/teams/teams/teams.module";
 import { TokensModule } from "@/modules/tokens/tokens.module";
 import { TokensRepository } from "@/modules/tokens/tokens.repository";
 import { UsersModule } from "@/modules/users/users.module";
-import { Module } from "@nestjs/common";
-import { BookingEventHandlerModule } from "@/lib/modules/booking-event-handler.module";
 
 @Module({
   imports: [
@@ -81,6 +83,7 @@ import { BookingEventHandlerModule } from "@/lib/modules/booking-event-handler.m
     OAuthClientRepository,
     OAuthClientUsersService,
     BookingsService_2024_08_13,
+    BookingAttendeesService_2024_08_13,
     BookingGuestsService_2024_08_13,
     InputBookingsService_2024_08_13,
     OutputBookingsService_2024_08_13,
@@ -110,6 +113,7 @@ import { BookingEventHandlerModule } from "@/lib/modules/booking-event-handler.m
   ],
   controllers: [
     BookingsController_2024_08_13,
+    BookingAttendeesController_2024_08_13,
     BookingGuestsController_2024_08_13,
     BookingLocationController_2024_08_13,
   ],

apps/api/v2/src/ee/bookings/2024-08-13/controllers/booking-attendees.controller.ts

@@ -0,0 +1,71 @@
+import { BOOKING_WRITE, SUCCESS_STATUS } from "@calcom/platform-constants";
+import { AddAttendeeInput_2024_08_13 } from "@calcom/platform-types";
+import { Body, Controller, HttpCode, HttpStatus, Param, Post, UseGuards } from "@nestjs/common";
+import { ApiHeader, ApiOperation, ApiTags as DocsTags } from "@nestjs/swagger";
+import { BookingPbacGuard } from "@/ee/bookings/2024-08-13/guards/booking-pbac.guard";
+import { BookingUidGuard } from "@/ee/bookings/2024-08-13/guards/booking-uid.guard";
+import { AddAttendeeOutput_2024_08_13 } from "@/ee/bookings/2024-08-13/outputs/add-attendee.output";
+import { BookingAttendeesService_2024_08_13 } from "@/ee/bookings/2024-08-13/services/booking-attendees.service";
+import { VERSION_2024_08_13, VERSION_2024_08_13_VALUE } from "@/lib/api-versions";
+import { API_KEY_OR_ACCESS_TOKEN_HEADER } from "@/lib/docs/headers";
+import { Throttle } from "@/lib/endpoint-throttler-decorator";
+import { GetUser } from "@/modules/auth/decorators/get-user/get-user.decorator";
+import { Permissions } from "@/modules/auth/decorators/permissions/permissions.decorator";
+import { ApiAuthGuard } from "@/modules/auth/guards/api-auth/api-auth.guard";
+import { PermissionsGuard } from "@/modules/auth/guards/permissions/permissions.guard";
+import { ApiAuthGuardUser } from "@/modules/auth/strategies/api-auth/api-auth.strategy";
+
+@Controller({
+  path: "/v2/bookings/:bookingUid/attendees",
+  version: VERSION_2024_08_13_VALUE,
+})
+@UseGuards(PermissionsGuard)
+@DocsTags("Bookings / Attendees")
+@ApiHeader({
+  name: "cal-api-version",
+  description: `Must be set to ${VERSION_2024_08_13}. This header is required as this endpoint does not exist in older API versions.`,
+  example: VERSION_2024_08_13,
+  required: true,
+})
+export class BookingAttendeesController_2024_08_13 {
+  constructor(private readonly bookingAttendeesService: BookingAttendeesService_2024_08_13) {}
+
+  @Post("/")
+  @HttpCode(HttpStatus.CREATED)
+  @Permissions([BOOKING_WRITE])
+  @UseGuards(ApiAuthGuard, BookingUidGuard, BookingPbacGuard)
+  @Throttle({
+    limit: 5,
+    ttl: 60000,
+    blockDuration: 60000,
+    name: "booking_attendees_add",
+  })
+  @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
+  @ApiOperation({
+    summary: "Add an attendee to a booking",
+    description: `Add a new attendee to an existing booking by its UID.
+
+      **Side effects:**
+      - The booking's attendee list is updated in the database
+      - The calendar event is updated on connected calendars (Google Calendar, Outlook, etc.) to include the new attendee
+      - An email notification is sent to the new attendee with the booking details
+
+      **Permissions:**
+      - The authenticated user must be either the booking organizer, an existing attendee, or have the \`booking.update\` permission for the team
+
+      <Note>The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error.</Note>
+      `,
+  })
+  async addAttendee(
+    @Param("bookingUid") bookingUid: string,
+    @Body() body: AddAttendeeInput_2024_08_13,
+    @GetUser() user: ApiAuthGuardUser
+  ): Promise<AddAttendeeOutput_2024_08_13> {
+    const attendee = await this.bookingAttendeesService.addAttendee(bookingUid, body, user);
+
+    return {
+      status: SUCCESS_STATUS,
+      data: attendee,
+    };
+  }
+}