feat: Add OpenAPI Support to dm.delete/im.delete API (#36677)

Author: ahmed-n-abdeltwab

.changeset/shy-vans-juggle.md

@@ -0,0 +1,6 @@
+---
+"@rocket.chat/meteor": patch
+"@rocket.chat/rest-typings": patch
+---
+
+Add OpenAPI support for the Rocket.Chat dm.delete/im.delete API endpoints by migrating to a modern chained route definition syntax and utilizing shared AJV schemas for validation to enhance API documentation and ensure type safety through response validation.

apps/meteor/app/api/server/v1/im.ts

@@ -4,7 +4,9 @@
 import type { IMessage, IRoom, ISubscription, IUser } from '@rocket.chat/core-typings';
 import { Subscriptions, Uploads, Messages, Rooms, Users } from '@rocket.chat/models';
 import {
-	isDmDeleteProps,
+	ajv,
+	validateUnauthorizedErrorResponse,
+	validateBadRequestErrorResponse,
 	isDmFileProps,
 	isDmMemberProps,
 	isDmMessagesProps,
@@ -26,7 +28,9 @@ import { getRoomByNameOrIdWithOptionToJoin } from '../../../lib/server/functions
 import { getChannelHistory } from '../../../lib/server/methods/getChannelHistory';
 import { settings } from '../../../settings/server';
 import { normalizeMessagesForUser } from '../../../utils/server/lib/normalizeMessagesForUser';
+import type { ExtractRoutesFromAPI } from '../ApiClass';
 import { API } from '../api';
+import type { TypedAction } from '../definition';
 import { addUserToFileObj } from '../helpers/addUserToFileObj';
 import { composeRoomWithLastMessage } from '../helpers/composeRoomWithLastMessage';
 import { getPaginationItems } from '../helpers/getPaginationItems';
@@ -87,28 +91,78 @@ API.v1.addRoute(
 	},
 );
 
-API.v1.addRoute(
-	['dm.delete', 'im.delete'],
-	{
-		authRequired: true,
-		validateParams: isDmDeleteProps,
+type DmDeleteProps =
+	| {
+			roomId: string;
+	  }
+	| {
+			username: string;
+	  };
+
+const isDmDeleteProps = ajv.compile<DmDeleteProps>({
+	oneOf: [
+		{
+			type: 'object',
+			properties: {
+				roomId: {
+					type: 'string',
+				},
+			},
+			required: ['roomId'],
+			additionalProperties: false,
+		},
+		{
+			type: 'object',
+			properties: {
+				username: {
+					type: 'string',
+				},
+			},
+			required: ['username'],
+			additionalProperties: false,
+		},
+	],
+});
+
+const dmDeleteEndpointsProps = {
+	authRequired: true,
+	body: isDmDeleteProps,
+	response: {
+		400: validateBadRequestErrorResponse,
+		401: validateUnauthorizedErrorResponse,
+		200: ajv.compile<void>({
+			type: 'object',
+			properties: {
+				success: {
+					type: 'boolean',
+					enum: [true],
+				},
+			},
+			required: ['success'],
+			additionalProperties: false,
+		}),
 	},
-	{
-		async post() {
-			const { room } = await findDirectMessageRoom(this.bodyParams, this.userId);
+} as const;
 
-			const canAccess =
-				(await canAccessRoomIdAsync(room._id, this.userId)) || (await hasPermissionAsync(this.userId, 'view-room-administration'));
-			if (!canAccess) {
-				throw new Meteor.Error('error-not-allowed', 'Not allowed');
-			}
+const dmDeleteAction = <Path extends string>(_path: Path): TypedAction<typeof dmDeleteEndpointsProps, Path> =>
+	async function action() {
+		const { room } = await findDirectMessageRoom(this.bodyParams, this.userId);
 
-			await eraseRoom(room._id, this.userId);
+		const canAccess =
+			(await canAccessRoomIdAsync(room._id, this.userId)) || (await hasPermissionAsync(this.userId, 'view-room-administration'));
 
-			return API.v1.success();
-		},
-	},
-);
+		if (!canAccess) {
+			throw new Meteor.Error('error-not-allowed', 'Not allowed');
+		}
+
+		await eraseRoom(room._id, this.userId);
+
+		return API.v1.success();
+	};
+
+const dmEndpoints = API.v1
+	.post('im.delete', dmDeleteEndpointsProps, dmDeleteAction('im.delete'))
+	.post('dm.delete', dmDeleteEndpointsProps, dmDeleteAction('dm.delete'));
 
 API.v1.addRoute(
 	['dm.close', 'im.close'],
@@ -589,3 +643,10 @@ API.v1.addRoute(
 		},
 	},
 );
+
+export type DmEndpoints = ExtractRoutesFromAPI<typeof dmEndpoints>;
+
+declare module '@rocket.chat/rest-typings' {
+	// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-empty-interface
+	interface Endpoints extends DmEndpoints {}
+}

packages/rest-typings/src/v1/dm/DmDeleteProps.ts

@@ -2,7 +2,6 @@ import type { ImEndpoints } from './im';
 
 export type DmEndpoints = {
 	'/v1/dm.create': ImEndpoints['/v1/im.create'];
-	'/v1/dm.delete': ImEndpoints['/v1/im.delete'];
 	'/v1/dm.close': ImEndpoints['/v1/im.close'];
 	'/v1/dm.counters': ImEndpoints['/v1/im.counters'];
 	'/v1/dm.files': ImEndpoints['/v1/im.files'];

packages/rest-typings/src/v1/dm/dm.ts

@@ -2,7 +2,6 @@ import type { IMessage, IRoom, IUser, IUploadWithUser } from '@rocket.chat/core-
 
 import type { DmCloseProps } from './DmCloseProps';
 import type { DmCreateProps } from './DmCreateProps';
-import type { DmDeleteProps } from './DmDeleteProps';
 import type { DmFileProps } from './DmFileProps';
 import type { DmHistoryProps } from './DmHistoryProps';
 import type { DmLeaveProps } from './DmLeaveProps';
@@ -17,9 +16,6 @@ export type ImEndpoints = {
 			room: IRoom & { rid: IRoom['_id'] };
 		};
 	};
-	'/v1/im.delete': {
-		POST: (params: DmDeleteProps) => void;
-	};
 	'/v1/im.close': {
 		POST: (params: DmCloseProps) => void;
 	};

packages/rest-typings/src/v1/dm/im.ts

@@ -1,7 +1,6 @@
 export * from './dm';
 export * from './im';
 export * from './DmCreateProps';
-export * from './DmDeleteProps';
 export * from './DmFileProps';
 export * from './DmMembersProps';
 export * from './DmMessagesProps';