refactor: enhance API error response validation and accessibility (RocketChat#36574)

Author: ahmed-n-abdeltwab

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

@@ -29,6 +29,8 @@ import {
 	isChatSyncThreadMessagesProps,
 	isChatGetStarredMessagesProps,
 	isChatGetDiscussionsProps,
+	validateBadRequestErrorResponse,
+	validateUnauthorizedErrorResponse,
 } from '@rocket.chat/rest-typings';
 import { escapeRegExp } from '@rocket.chat/string-helpers';
 import { Meteor } from 'meteor/meteor';
@@ -197,35 +199,8 @@ const chatPinMessageEndpoints = API.v1.post(
 		authRequired: true,
 		body: isChatPinMessageProps,
 		response: {
-			400: ajv.compile<{
-				error?: string;
-				errorType?: string;
-				stack?: string;
-				details?: string;
-			}>({
-				type: 'object',
-				properties: {
-					success: { type: 'boolean', enum: [false] },
-					stack: { type: 'string' },
-					error: { type: 'string' },
-					errorType: { type: 'string' },
-					details: { type: 'string' },
-				},
-				required: ['success'],
-				additionalProperties: false,
-			}),
-			401: ajv.compile({
-				type: 'object',
-				properties: {
-					success: { type: 'boolean', enum: [false] },
-					status: { type: 'string' },
-					message: { type: 'string' },
-					error: { type: 'string' },
-					errorType: { type: 'string' },
-				},
-				required: ['success'],
-				additionalProperties: false,
-			}),
+			400: validateBadRequestErrorResponse,
+			401: validateUnauthorizedErrorResponse,
 			200: ajv.compile<{ message: IMessage }>({
 				type: 'object',
 				properties: {

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

@@ -1,6 +1,14 @@
 import type { IOAuthApps } from '@rocket.chat/core-typings';
 import { OAuthApps } from '@rocket.chat/models';
-import { ajv, isUpdateOAuthAppParams, isOauthAppsGetParams, isDeleteOAuthAppParams } from '@rocket.chat/rest-typings';
+import {
+	ajv,
+	isUpdateOAuthAppParams,
+	isOauthAppsGetParams,
+	isDeleteOAuthAppParams,
+	validateUnauthorizedErrorResponse,
+	validateBadRequestErrorResponse,
+	validateForbiddenErrorResponse,
+} from '@rocket.chat/rest-typings';
 
 import { hasPermissionAsync } from '../../../authorization/server/functions/hasPermission';
 import { apiDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
@@ -117,47 +125,9 @@ const oauthAppsCreateEndpoints = API.v1.post(
 		body: isOauthAppsAddParams,
 		permissionsRequired: ['manage-oauth-apps'],
 		response: {
-			400: ajv.compile<{
-				error?: string;
-				errorType?: string;
-				stack?: string;
-				details?: object;
-			}>({
-				type: 'object',
-				properties: {
-					success: { type: 'boolean', enum: [false] },
-					stack: { type: 'string' },
-					error: { type: 'string' },
-					errorType: { type: 'string' },
-					details: { type: 'object' },
-				},
-				required: ['success'],
-				additionalProperties: false,
-			}),
-			401: ajv.compile({
-				type: 'object',
-				properties: {
-					success: { type: 'boolean', enum: [false] },
-					status: { type: 'string' },
-					message: { type: 'string' },
-					error: { type: 'string' },
-					errorType: { type: 'string' },
-				},
-				required: ['success'],
-				additionalProperties: false,
-			}),
-			403: ajv.compile({
-				type: 'object',
-				properties: {
-					success: { type: 'boolean', enum: [false] },
-					status: { type: 'string' },
-					message: { type: 'string' },
-					error: { type: 'string' },
-					errorType: { type: 'string' },
-				},
-				required: ['success'],
-				additionalProperties: false,
-			}),
+			400: validateBadRequestErrorResponse,
+			401: validateUnauthorizedErrorResponse,
+			403: validateForbiddenErrorResponse,
 			200: ajv.compile<{ application: IOAuthApps }>({
 				type: 'object',
 				properties: {

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

@@ -1,7 +1,7 @@
 import { api } from '@rocket.chat/core-services';
 import type { IWebdavAccount, IWebdavAccountIntegration } from '@rocket.chat/core-typings';
 import { WebdavAccounts } from '@rocket.chat/models';
-import { ajv } from '@rocket.chat/rest-typings';
+import { ajv, validateUnauthorizedErrorResponse, validateBadRequestErrorResponse } from '@rocket.chat/rest-typings';
 import type { DeleteResult } from 'mongodb';
 
 import type { ExtractRoutesFromAPI } from '../ApiClass';
@@ -48,20 +48,7 @@ const webdavGetMyAccountsEndpoints = API.v1.get(
 				required: ['success', 'accounts'],
 				additionalProperties: false,
 			}),
-			401: ajv.compile({
-				type: 'object',
-				properties: {
-					message: {
-						type: 'string',
-					},
-					success: {
-						type: 'boolean',
-						description: 'Indicates if the request was successful.',
-					},
-				},
-				required: ['success', 'message'],
-				additionalProperties: false,
-			}),
+			401: validateUnauthorizedErrorResponse,
 		},
 	},
 	async function action() {
@@ -121,37 +108,8 @@ const webdavRemoveAccountEndpoints = API.v1.post(
 				required: ['result', 'success'],
 				additionalProperties: false,
 			}),
-			400: ajv.compile({
-				type: 'object',
-				properties: {
-					errorType: {
-						type: 'string',
-					},
-					error: {
-						type: 'string',
-					},
-					success: {
-						type: 'boolean',
-						description: 'Indicates if the request was successful.',
-					},
-				},
-				required: ['success', 'errorType', 'error'],
-				additionalProperties: false,
-			}),
-			401: ajv.compile({
-				type: 'object',
-				properties: {
-					message: {
-						type: 'string',
-					},
-					success: {
-						type: 'boolean',
-						description: 'Indicates if the request was successful.',
-					},
-				},
-				required: ['success', 'message'],
-				additionalProperties: false,
-			}),
+			400: validateBadRequestErrorResponse,
+			401: validateUnauthorizedErrorResponse,
 		},
 	},
 	async function action() {

packages/rest-typings/src/index.ts

@@ -277,4 +277,4 @@ export * from './v1/banners';
 export * from './default';
 
 // Export the ajv instance for use in other packages
-export { ajv } from './v1/Ajv';
+export * from './v1/Ajv';

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

@@ -21,3 +21,72 @@ ajv.addKeyword({
 	validate: (_schema: unknown, data: unknown): boolean => typeof data === 'string' && !!data.trim(),
 });
 export { ajv };
+
+type BadRequestErrorResponse = {
+	success: false;
+	error?: string;
+	errorType?: string;
+	stack?: string;
+	details?: string | object;
+};
+
+const BadRequestErrorResponseSchema = {
+	type: 'object',
+	properties: {
+		success: { type: 'boolean', enum: [false] },
+		stack: { type: 'string' },
+		error: { type: 'string' },
+		errorType: { type: 'string' },
+		details: { anyOf: [{ type: 'string' }, { type: 'object' }] },
+	},
+	required: ['success'],
+	additionalProperties: false,
+};
+
+export const validateBadRequestErrorResponse = ajv.compile<BadRequestErrorResponse>(BadRequestErrorResponseSchema);
+
+type UnauthorizedErrorResponse = {
+	success: false;
+	status?: string;
+	message?: string;
+	error?: string;
+	errorType?: string;
+};
+
+const UnauthorizedErrorResponseSchema = {
+	type: 'object',
+	properties: {
+		success: { type: 'boolean', enum: [false] },
+		status: { type: 'string' },
+		message: { type: 'string' },
+		error: { type: 'string' },
+		errorType: { type: 'string' },
+	},
+	required: ['success'],
+	additionalProperties: false,
+};
+
+export const validateUnauthorizedErrorResponse = ajv.compile<UnauthorizedErrorResponse>(UnauthorizedErrorResponseSchema);
+
+type ForbiddenErrorResponse = {
+	success: false;
+	status?: string;
+	message?: string;
+	error?: string;
+	errorType?: string;
+};
+
+const ForbiddenErrorResponseSchema = {
+	type: 'object',
+	properties: {
+		success: { type: 'boolean', enum: [false] },
+		status: { type: 'string' },
+		message: { type: 'string' },
+		error: { type: 'string' },
+		errorType: { type: 'string' },
+	},
+	required: ['success'],
+	additionalProperties: false,
+};
+
+export const validateForbiddenErrorResponse = ajv.compile<ForbiddenErrorResponse>(ForbiddenErrorResponseSchema);