fix: api v2 calendars/busy-times docs

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

@@ -116,6 +116,23 @@ export class CalendarsController {
     description:
       "Get busy times from a calendar. Example request URL is `https://api.cal.com/v2/calendars/busy-times?timeZone=Europe%2FMadrid&dateFrom=2024-12-18&dateTo=2024-12-18&calendarsToLoad[0][credentialId]=135&calendarsToLoad[0][externalId]=skrauciz%40gmail.com`. Note: loggedInUsersTz is deprecated, use timeZone instead.",
   })
+  @ApiQuery({
+    name: "calendarsToLoad",
+    required: true,
+    description:
+      "An array of Calendar objects representing the calendars to be loaded. Use bracket notation in the URL, e.g.: calendarsToLoad[0][credentialId]=135&calendarsToLoad[0][externalId]=email@example.com",
+    schema: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          credentialId: { type: "number", example: 135 },
+          externalId: { type: "string", example: "email@example.com" },
+        },
+        required: ["credentialId", "externalId"],
+      },
+    },
+  })
   async getBusyTimes(
     @Query() queryParams: CalendarBusyTimesInput,
     @GetUser() user: UserWithProfile

docs/api-reference/v2/openapi.json

@@ -9326,6 +9326,73 @@
         "tags": ["Bookings"]
       }
     },
+    "/v2/bookings/by-seat/{seatUid}": {
+      "get": {
+        "operationId": "BookingsController_2024_08_13_getBookingBySeatUid",
+        "summary": "Get a booking by seat UID",
+        "description": "Get a seated booking by its seat reference UID. This is useful when you have a seatUid from a seated booking and want to retrieve the full booking details.\n\n      If you are fetching a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n      you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n      <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>\n      ",
+        "parameters": [
+          {
+            "name": "cal-api-version",
+            "in": "header",
+            "description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "default": "2024-08-13"
+            }
+          },
+          {
+            "name": "seatUid",
+            "required": true,
+            "in": "path",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "Authorization",
+            "in": "header",
+            "description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "x-cal-secret-key",
+            "in": "header",
+            "description": "For platform customers - OAuth client secret key",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "x-cal-client-id",
+            "in": "header",
+            "description": "For platform customers - OAuth client ID",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetBookingOutput_2024_08_13"
+                }
+              }
+            }
+          }
+        },
+        "tags": ["Bookings"]
+      }
+    },
     "/v2/bookings/{bookingUid}": {
       "get": {
         "operationId": "BookingsController_2024_08_13_getBooking",
@@ -10432,7 +10499,7 @@
           },
           {
             "name": "dateFrom",
-            "required": false,
+            "required": true,
             "in": "query",
             "description": "The starting date for the busy times query",
             "schema": {
@@ -10442,7 +10509,7 @@
           },
           {
             "name": "dateTo",
-            "required": false,
+            "required": true,
             "in": "query",
             "description": "The ending date for the busy times query",
             "schema": {
@@ -10451,19 +10518,26 @@
             }
           },
           {
-            "name": "credentialId",
-            "in": "query",
+            "name": "calendarsToLoad",
             "required": true,
-            "schema": {
-              "type": "number"
-            }
-          },
-          {
-            "name": "externalId",
             "in": "query",
-            "required": true,
+            "description": "An array of Calendar objects representing the calendars to be loaded. Use bracket notation in the URL, e.g.: calendarsToLoad[0][credentialId]=135&calendarsToLoad[0][externalId]=email@example.com",
             "schema": {
-              "type": "string"
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "credentialId": {
+                    "type": "number",
+                    "example": 135
+                  },
+                  "externalId": {
+                    "type": "string",
+                    "example": "email@example.com"
+                  }
+                },
+                "required": ["credentialId", "externalId"]
+              }
             }
           },
           {

packages/platform/types/calendars/inputs/busy-times.input.ts

@@ -1,4 +1,4 @@
-import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { ApiHideProperty, ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
 import { Transform, Type } from "class-transformer";
 import {
   IsArray,
@@ -41,11 +41,11 @@ function ValidateTimezoneRequired(
 export class Calendar {
   @Transform(({ value }: { value: string }) => value && parseInt(value, 10))
   @IsNumber()
-  @ApiProperty()
+  @ApiHideProperty()
   credentialId!: number;
 
   @IsString()
-  @ApiProperty()
+  @ApiHideProperty()
   externalId!: string;
 }
 
@@ -73,7 +73,6 @@ export class CalendarBusyTimesInput {
   timeZone?: string;
 
   @ApiProperty({
-    required: false,
     description: "The starting date for the busy times query",
     example: "2023-10-01",
   })
@@ -82,20 +81,14 @@ export class CalendarBusyTimesInput {
   dateFrom!: string;
 
   @ApiProperty({
-    required: false,
     description: "The ending date for the busy times query",
     example: "2023-10-31",
   })
   @IsString()
   @IsDateString()
   dateTo!: string;
 
-  @ApiProperty({
-    type: [Calendar],
-    required: true,
-    description: "An array of Calendar objects representing the calendars to be loaded",
-    example: `[{ credentialId: "1", externalId: "AQgtJE7RnHEeyisVq2ENs2gAAAgEGAAAACgtJE7RnHEeyisVq2ENs2gAAAhSDAAAA" }, { credentialId: "2", externalId: "AQM7RnHEeyisVq2ENs2gAAAhFDBBBBB" }]`,
-  })
+  @ApiHideProperty()
   @IsArray()
   @ValidateNested({ each: true })
   @Type(() => Calendar)