refactor: Migrate livechat/users endpoints to OpenAPI with AJV validation

Author: amitb0ra

.changeset/migrate-livechat-users-openapi.md

@@ -0,0 +1,6 @@
+---
+"@rocket.chat/meteor": minor
+"@rocket.chat/rest-typings": minor
+---
+
+Add OpenAPI support for the livechat/users/:type and livechat/users/:type/:_id API endpoints by migrating to chained route definitions with AJV body, query, and response validation.

apps/meteor/app/livechat/imports/server/rest/users.ts

@@ -1,43 +1,139 @@
 import { Users } from '@rocket.chat/models';
-import { isLivechatUsersManagerGETProps, isPOSTLivechatUsersTypeProps } from '@rocket.chat/rest-typings';
-import { check } from 'meteor/check';
+import { ajv, validateBadRequestErrorResponse, validateUnauthorizedErrorResponse, validateForbiddenErrorResponse } from '@rocket.chat/rest-typings';
 
 import { API } from '../../../../api/server';
+import type { ExtractRoutesFromAPI } from '../../../../api/server/ApiClass';
 import { getPaginationItems } from '../../../../api/server/helpers/getPaginationItems';
 import { hasAtLeastOnePermissionAsync } from '../../../../authorization/server/functions/hasPermission';
 import { findAgents, findManagers } from '../../../server/api/lib/users';
 import { addManager, addAgent, removeAgent, removeManager } from '../../../server/lib/omni-users';
 
+// --- Local types and AJV schemas (moved from rest-typings) ---
+
+type LivechatUsersManagerGETLocal = {
+	text?: string;
+	fields?: string;
+	onlyAvailable?: boolean;
+	excludeId?: string;
+	showIdleAgents?: boolean;
+	count?: number;
+	offset?: number;
+	sort?: string;
+	query?: string;
+};
+
+const LivechatUsersManagerGETLocalSchema = {
+	type: 'object',
+	properties: {
+		text: { type: 'string', nullable: true },
+		onlyAvailable: { type: 'boolean', nullable: true },
+		excludeId: { type: 'string', nullable: true },
+		showIdleAgents: { type: 'boolean', nullable: true },
+		count: { type: 'number', nullable: true },
+		offset: { type: 'number', nullable: true },
+		sort: { type: 'string', nullable: true },
+		query: { type: 'string', nullable: true },
+		fields: { type: 'string', nullable: true },
+	},
+	required: [],
+	additionalProperties: false,
+};
+
+const isLivechatUsersManagerGETLocal = ajv.compile<LivechatUsersManagerGETLocal>(LivechatUsersManagerGETLocalSchema);
+
+type POSTLivechatUsersTypeLocal = {
+	username: string;
+};
+
+const POSTLivechatUsersTypeLocalSchema = {
+	type: 'object',
+	properties: {
+		username: { type: 'string' },
+	},
+	required: ['username'],
+	additionalProperties: false,
+};
+
+const isPOSTLivechatUsersTypeLocal = ajv.compile<POSTLivechatUsersTypeLocal>(POSTLivechatUsersTypeLocalSchema);
+
+// --- Response schemas ---
+
+const paginatedUsersResponseSchema = ajv.compile<{
+	users: object[];
+	count: number;
+	offset: number;
+	total: number;
+}>({
+	type: 'object',
+	properties: {
+		// ILivechatAgent is not registered in typia (extends IUser with livechat-specific fields),
+		// so we use { type: 'object' } as a fallback.
+		users: { type: 'array', items: { type: 'object' } },
+		count: { type: 'number' },
+		offset: { type: 'number' },
+		total: { type: 'number' },
+		success: { type: 'boolean', enum: [true] },
+	},
+	required: ['users', 'count', 'offset', 'total', 'success'],
+	additionalProperties: false,
+});
+
+const postUserResponseSchema = ajv.compile<{ user: object }>({
+	type: 'object',
+	properties: {
+		user: { type: 'object' },
+		success: { type: 'boolean', enum: [true] },
+	},
+	required: ['user', 'success'],
+	additionalProperties: false,
+});
+
+const successOnlyResponseSchema = ajv.compile<void>({
+	type: 'object',
+	properties: {
+		success: { type: 'boolean', enum: [true] },
+	},
+	required: ['success'],
+	additionalProperties: false,
+});
+
+const getUserByIdResponseSchema = ajv.compile<{ user: object | null }>({
+	type: 'object',
+	properties: {
+		user: { type: ['object', 'null'] },
+		success: { type: 'boolean', enum: [true] },
+	},
+	required: ['user', 'success'],
+	additionalProperties: false,
+});
+
 const emptyStringArray: string[] = [];
 
-API.v1.addRoute(
-	'livechat/users/:type',
-	{
-		authRequired: true,
-		permissionsRequired: {
-			'POST': ['view-livechat-manager'],
-			'*': emptyStringArray,
+const livechatUsersEndpoints = API.v1
+	.get(
+		'livechat/users/:type',
+		{
+			authRequired: true,
+			permissionsRequired: emptyStringArray,
+			query: isLivechatUsersManagerGETLocal,
+			response: {
+				200: paginatedUsersResponseSchema,
+				400: validateBadRequestErrorResponse,
+				401: validateUnauthorizedErrorResponse,
+				403: validateForbiddenErrorResponse,
+			},
 		},
-		validateParams: {
-			GET: isLivechatUsersManagerGETProps,
-			POST: isPOSTLivechatUsersTypeProps,
-		},
-	},
-	{
-		async get() {
-			check(this.urlParams, {
-				type: String,
-			});
+		async function action() {
 			const { offset, count } = await getPaginationItems(this.queryParams);
 			const { sort } = await this.parseJsonQuery();
 			const { text } = this.queryParams;
 
 			if (this.urlParams.type === 'agent') {
 				if (!(await hasAtLeastOnePermissionAsync(this.userId, ['transfer-livechat-guest', 'edit-omnichannel-contact']))) {
-					return API.v1.forbidden();
+					return API.v1.forbidden('error-not-authorized');
 				}
 
-				const { onlyAvailable, excludeId, showIdleAgents } = this.queryParams;
+				const { onlyAvailable = false, excludeId, showIdleAgents } = this.queryParams;
 				return API.v1.success(
 					await findAgents({
 						text,
@@ -54,7 +150,7 @@ API.v1.addRoute(
 			}
 			if (this.urlParams.type === 'manager') {
 				if (!(await hasAtLeastOnePermissionAsync(this.userId, ['view-livechat-manager']))) {
-					return API.v1.forbidden();
+					return API.v1.forbidden('error-not-authorized');
 				}
 
 				return API.v1.success(
@@ -70,7 +166,21 @@ API.v1.addRoute(
 			}
 			throw new Error('Invalid type');
 		},
-		async post() {
+	)
+	.post(
+		'livechat/users/:type',
+		{
+			authRequired: true,
+			permissionsRequired: ['view-livechat-manager'],
+			body: isPOSTLivechatUsersTypeLocal,
+			response: {
+				200: postUserResponseSchema,
+				400: validateBadRequestErrorResponse,
+				401: validateUnauthorizedErrorResponse,
+				403: validateForbiddenErrorResponse,
+			},
+		},
+		async function action() {
 			if (this.urlParams.type === 'agent') {
 				const user = await addAgent(this.bodyParams.username);
 				if (user) {
@@ -87,14 +197,21 @@ API.v1.addRoute(
 
 			return API.v1.failure();
 		},
-	},
-);
-
-API.v1.addRoute(
-	'livechat/users/:type/:_id',
-	{ authRequired: true, permissionsRequired: ['view-livechat-manager'] },
-	{
-		async get() {
+	)
+	.get(
+		'livechat/users/:type/:_id',
+		{
+			authRequired: true,
+			permissionsRequired: ['view-livechat-manager'],
+			query: undefined,
+			response: {
+				200: getUserByIdResponseSchema,
+				400: validateBadRequestErrorResponse,
+				401: validateUnauthorizedErrorResponse,
+				403: validateForbiddenErrorResponse,
+			},
+		},
+		async function action() {
 			if (!['agent', 'manager'].includes(this.urlParams.type)) {
 				throw new Error('Invalid type');
 			}
@@ -107,7 +224,21 @@ API.v1.addRoute(
 			// TODO: throw error instead of returning null
 			return API.v1.success({ user });
 		},
-		async delete() {
+	)
+	.delete(
+		'livechat/users/:type/:_id',
+		{
+			authRequired: true,
+			permissionsRequired: ['view-livechat-manager'],
+			query: undefined,
+			response: {
+				200: successOnlyResponseSchema,
+				400: validateBadRequestErrorResponse,
+				401: validateUnauthorizedErrorResponse,
+				403: validateForbiddenErrorResponse,
+			},
+		},
+		async function action() {
 			if (this.urlParams.type === 'agent') {
 				if (await removeAgent(this.urlParams._id)) {
 					return API.v1.success();
@@ -120,7 +251,15 @@ API.v1.addRoute(
 				throw new Error('Invalid type');
 			}
 
-			return API.v1.failure();
+			return API.v1.failure('error-removing-user');
 		},
-	},
-);
+	);
+
+// --- Type augmentation ---
+
+type LivechatUsersEndpoints = ExtractRoutesFromAPI<typeof livechatUsersEndpoints>;
+
+declare module '@rocket.chat/rest-typings' {
+	// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-empty-interface
+	interface Endpoints extends LivechatUsersEndpoints {}
+}