docs: v2 rolling window and authentication

apps/api/v2/src/ee/bookings/2024-08-13/outputs/cancel-booking.output.ts

@@ -10,7 +10,12 @@ import {
   RecurringBookingOutput_2024_08_13,
 } from "@calcom/platform-types";
 
-@ApiExtraModels(BookingOutput_2024_08_13, RecurringBookingOutput_2024_08_13)
+@ApiExtraModels(
+  BookingOutput_2024_08_13,
+  RecurringBookingOutput_2024_08_13,
+  GetSeatedBookingOutput_2024_08_13,
+  GetRecurringSeatedBookingOutput_2024_08_13
+)
 export class CancelBookingOutput_2024_08_13 {
   @ApiProperty({ example: SUCCESS_STATUS, enum: [SUCCESS_STATUS, ERROR_STATUS] })
   @IsEnum([SUCCESS_STATUS, ERROR_STATUS])

apps/api/v2/src/ee/bookings/2024-08-13/outputs/create-booking.output.ts

@@ -10,7 +10,12 @@ import {
   CreateRecurringSeatedBookingOutput_2024_08_13,
 } from "@calcom/platform-types";
 
-@ApiExtraModels(BookingOutput_2024_08_13, RecurringBookingOutput_2024_08_13)
+@ApiExtraModels(
+  BookingOutput_2024_08_13,
+  RecurringBookingOutput_2024_08_13,
+  CreateSeatedBookingOutput_2024_08_13,
+  CreateRecurringSeatedBookingOutput_2024_08_13
+)
 export class CreateBookingOutput_2024_08_13 {
   @ApiProperty({ example: SUCCESS_STATUS, enum: [SUCCESS_STATUS, ERROR_STATUS] })
   @IsEnum([SUCCESS_STATUS, ERROR_STATUS])
@@ -21,6 +26,8 @@ export class CreateBookingOutput_2024_08_13 {
     oneOf: [
       { $ref: getSchemaPath(BookingOutput_2024_08_13) },
       { type: "array", items: { $ref: getSchemaPath(RecurringBookingOutput_2024_08_13) } },
+      { $ref: getSchemaPath(CreateSeatedBookingOutput_2024_08_13) },
+      { type: "array", items: { $ref: getSchemaPath(CreateRecurringSeatedBookingOutput_2024_08_13) } },
     ],
     description:
       "Booking data, which can be either a BookingOutput object or an array of RecurringBookingOutput objects",

apps/api/v2/src/ee/bookings/2024-08-13/outputs/reschedule-booking.output.ts

@@ -12,7 +12,12 @@ import {
   RecurringBookingOutput_2024_08_13,
 } from "@calcom/platform-types";
 
-@ApiExtraModels(BookingOutput_2024_08_13, RecurringBookingOutput_2024_08_13)
+@ApiExtraModels(
+  BookingOutput_2024_08_13,
+  RecurringBookingOutput_2024_08_13,
+  CreateSeatedBookingOutput_2024_08_13,
+  CreateRecurringSeatedBookingOutput_2024_08_13
+)
 export class RescheduleBookingOutput_2024_08_13 {
   @ApiProperty({ example: SUCCESS_STATUS, enum: [SUCCESS_STATUS, ERROR_STATUS] })
   @IsEnum([SUCCESS_STATUS, ERROR_STATUS])

apps/api/v2/src/modules/oauth-clients/controllers/oauth-client-users/oauth-client-users.controller.ts

@@ -162,7 +162,11 @@ export class OAuthClientUsersController {
 
   @Post("/:userId/force-refresh")
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({ summary: "Force refresh tokens" })
+  @ApiOperation({
+    summary: "Force refresh tokens",
+    description: `If you have lost managed user access or refresh token, then you can get new ones by using OAuth credentials.
+    Each access token is valid for 60 minutes and each refresh token for 1 year. Make sure to store them later in your database, for example, by updating the User model to have \`calAccessToken\` and \`calRefreshToken\` columns.`,
+  })
   @MembershipRoles([MembershipRole.ADMIN, MembershipRole.OWNER])
   async forceRefresh(
     @Param("userId") userId: number,

apps/api/v2/src/modules/oauth-clients/controllers/oauth-flow/oauth-flow.controller.ts

@@ -30,6 +30,7 @@ import {
   ApiExcludeEndpoint as DocsExcludeEndpoint,
   ApiBadRequestResponse as DocsBadRequestResponse,
   ApiHeader as DocsHeader,
+  ApiOperation,
 } from "@nestjs/swagger";
 import { Response as ExpressResponse } from "express";
 
@@ -39,7 +40,6 @@ import { SUCCESS_STATUS, X_CAL_SECRET_KEY } from "@calcom/platform-constants";
   path: "/v2/oauth/:clientId",
   version: API_VERSIONS_VALUES,
 })
-@DocsTags("OAuth")
 export class OAuthFlowController {
   constructor(
     private readonly oauthClientRepository: OAuthClientRepository,
@@ -115,13 +115,18 @@ export class OAuthFlowController {
   @Post("/refresh")
   @HttpCode(HttpStatus.OK)
   @UseGuards(ApiAuthGuard)
-  @DocsTags("Managed users")
+  @DocsTags("Platform / Managed Users")
   @DocsHeader({
     name: X_CAL_SECRET_KEY,
     description: "OAuth client secret key.",
     required: true,
   })
-  async refreshAccessToken(
+  @ApiOperation({
+    summary: "Refresh managed user tokens",
+    description: `If managed user access token is expired then get a new one using this endpoint. Each access token is valid for 60 minutes and 
+    each refresh token for 1 year. Make sure to store them later in your database, for example, by updating the User model to have \`calAccessToken\` and \`calRefreshToken\` columns.`,
+  })
+  async refreshTokens(
     @Param("clientId") clientId: string,
     @Headers(X_CAL_SECRET_KEY) secretKey: string,
     @Body() body: RefreshTokenInput