chore: deprecation api (#29347)

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

@@ -34,6 +34,7 @@ import { parseJsonQuery } from './helpers/parseJsonQuery';
 import { Logger } from '../../logger/server';
 import { getUserInfo } from './helpers/getUserInfo';
 import { hasPermissionAsync } from '../../authorization/server/functions/hasPermission';
+import { apiDeprecationLogger } from '../../lib/server/lib/deprecationWarningLogger';
 
 const logger = new Logger('API');
 
@@ -177,10 +178,7 @@ export class APIClass<TBasePath extends string = ''> extends Restivus {
 	}
 
 	async parseJsonQuery(this: PartialThis) {
-		// eslint-disable-next-line @typescript-eslint/no-this-alias
-		const self = this;
-
-		return parseJsonQuery(this.request.route, self.userId, self.queryParams, self.logger, self.queryFields, self.queryOperations);
+		return parseJsonQuery(this);
 	}
 
 	public addAuthMethod(func: (this: PartialThis, ...args: any[]) => any): void {
@@ -581,6 +579,10 @@ export class APIClass<TBasePath extends string = ''> extends Restivus {
 						};
 
 						try {
+							if (options.deprecationVersion) {
+								apiDeprecationLogger.endpoint(this.request.route, options.deprecationVersion, this.response);
+							}
+
 							await api.enforceRateLimit(objectForRateLimitMatch, this.request, this.response, this.userId);
 
 							if (_options.validateParams) {

apps/meteor/app/api/server/definition.ts

@@ -95,6 +95,7 @@ export type Options = (
 ) & {
 	validateParams?: ValidateFunction | { [key in Method]?: ValidateFunction };
 	authOrAnonRequired?: true;
+	deprecationVersion?: string;
 };
 
 export type PartialThis = {

apps/meteor/app/api/server/helpers/parseJsonQuery.ts

@@ -4,37 +4,30 @@ import ejson from 'ejson';
 import { isValidQuery } from '../lib/isValidQuery';
 import { clean } from '../lib/cleanQuery';
 import { API } from '../api';
-import type { Logger } from '../../../logger/server';
 import { hasPermissionAsync } from '../../../authorization/server/functions/hasPermission';
+import { apiDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
+import type { PartialThis } from '../definition';
 
 const pathAllowConf = {
 	'/api/v1/users.list': ['$or', '$regex', '$and'],
 	'def': ['$or', '$and', '$regex'],
 };
 
-const warnFields =
-	process.env.NODE_ENV !== 'production' || process.env.SHOW_WARNINGS === 'true'
-		? (...rest: any): void => {
-				console.warn(...rest, new Error().stack);
-		  }
-		: new Function();
-
-export async function parseJsonQuery(
-	route: string,
-	userId: string,
-	params: {
-		query?: string;
-		sort?: string;
-		fields?: string;
-	},
-	logger: Logger,
-	queryFields?: string[],
-	queryOperations?: string[],
-): Promise<{
+export async function parseJsonQuery(api: PartialThis): Promise<{
 	sort: Record<string, 1 | -1>;
 	fields: Record<string, 0 | 1>;
 	query: Record<string, unknown>;
 }> {
+	const {
+		request: { route },
+		userId,
+		queryParams: params,
+		logger,
+		queryFields,
+		queryOperations,
+		response,
+	} = api;
+
 	let sort;
 	if (params.sort) {
 		try {
@@ -56,7 +49,7 @@ export async function parseJsonQuery(
 
 	let fields: Record<string, 0 | 1> | undefined;
 	if (params.fields) {
-		warnFields('attribute fields is deprecated');
+		apiDeprecationLogger.parameter(route, 'fields', '7.0.0', response);
 		try {
 			fields = JSON.parse(params.fields) as Record<string, 0 | 1>;
 
@@ -107,7 +100,7 @@ export async function parseJsonQuery(
 
 	let query: Record<string, any> = {};
 	if (params.query) {
-		warnFields('attribute query is deprecated');
+		apiDeprecationLogger.parameter(route, 'query', '7.0.0', response);
 
 		try {
 			query = ejson.parse(params.query);

apps/meteor/app/api/server/index.ts

@@ -1,5 +1,4 @@
 import './helpers/composeRoomWithLastMessage';
-import './helpers/deprecationWarning';
 import './helpers/getLoggedInUser';
 import './helpers/getPaginationItems';
 import './helpers/getUserFromParams';

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

@@ -4,7 +4,7 @@ import { OAuthApps } from '@rocket.chat/models';
 import { hasPermissionAsync } from '../../../authorization/server/functions/hasPermission';
 import { API } from '../api';
 import { addOAuthApp } from '../../../oauth2-server-config/server/admin/functions/addOAuthApp';
-import { deprecationWarning } from '../helpers/deprecationWarning';
+import { apiDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
 
 API.v1.addRoute(
 	'oauth-apps.list',
@@ -32,16 +32,11 @@ API.v1.addRoute(
 			if (!oauthApp) {
 				return API.v1.failure('OAuth app not found.');
 			}
+
 			if ('appId' in this.queryParams) {
-				return API.v1.success(
-					deprecationWarning({
-						endpoint: 'oauth-apps.get',
-						warningMessage: ({ versionWillBeRemoved, endpoint }) =>
-							`appId get parameter from "${endpoint}" is deprecated and will be removed after version ${versionWillBeRemoved}. Use _id instead.`,
-						response: { oauthApp },
-					}),
-				);
+				apiDeprecationLogger.parameter(this.request.route, 'appId', '7.0.0', this.response);
 			}
+
 			return API.v1.success({
 				oauthApp,
 			});

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

@@ -67,7 +67,7 @@ API.v1.addRoute(
 					return API.v1.failure('error-invalid-role-properties');
 				}
 
-				apiDeprecationLogger.warn(`Assigning roles by name is deprecated and will be removed on the next major release of Rocket.Chat`);
+				apiDeprecationLogger.parameter(this.request.route, 'roleName', '7.0.0', this.response);
 			}
 
 			const role = roleId ? await Roles.findOneById(roleId) : await Roles.findOneByIdOrName(roleName as string);
@@ -123,7 +123,14 @@ API.v1.addRoute(
 					throw new Meteor.Error('error-invalid-roleId');
 				}
 
-				apiDeprecationLogger.warn(`Querying roles by name is deprecated and will be removed on the next major release of Rocket.Chat`);
+				apiDeprecationLogger.deprecatedParameterUsage(
+					this.request.route,
+					'role',
+					'7.0.0',
+					this.response,
+					({ parameter, endpoint, version }) =>
+						`Querying \`${parameter}\` by name is deprecated in ${endpoint} and will be removed on the removed on version ${version}`,
+				);
 			}
 
 			const { cursor, totalCount } = await getUsersInRolePaginated(roleData._id, roomId, {
@@ -198,7 +205,7 @@ API.v1.addRoute(
 					return API.v1.failure('error-invalid-role-properties');
 				}
 
-				apiDeprecationLogger.warn(`Unassigning roles by name is deprecated and will be removed on the next major release of Rocket.Chat`);
+				apiDeprecationLogger.parameter(this.request.route, 'roleName', '7.0.0', this.response);
 			}
 
 			const user = await Users.findOneByUsername(username);

apps/meteor/app/assets/server/assets.ts

@@ -434,7 +434,7 @@ declare module '@rocket.chat/ui-contexts' {
 Meteor.methods<ServerMethods>({
 	async refreshClients() {
 		const uid = Meteor.userId();
-		methodDeprecationLogger.warn('refreshClients will be deprecated in future versions of Rocket.Chat');
+		methodDeprecationLogger.method('refreshClients', '7.0.0');
 
 		if (!uid) {
 			throw new Meteor.Error('error-invalid-user', 'Invalid user', {

apps/meteor/app/authorization/server/methods/addUserToRole.ts

@@ -6,7 +6,7 @@ import type { ServerMethods } from '@rocket.chat/ui-contexts';
 
 import { settings } from '../../../settings/server';
 import { hasPermissionAsync } from '../functions/hasPermission';
-import { apiDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
+import { methodDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
 
 declare module '@rocket.chat/ui-contexts' {
 	// eslint-disable-next-line @typescript-eslint/naming-convention
@@ -41,8 +41,12 @@ Meteor.methods<ServerMethods>({
 					method: 'authorization:addUserToRole',
 				});
 			}
-
-			apiDeprecationLogger.warn(`Calling authorization:addUserToRole with role names will be deprecated in future versions of Rocket.Chat`);
+			methodDeprecationLogger.deprecatedParameterUsage(
+				'authorization:addUserToRole',
+				'role',
+				'7.0.0',
+				({ parameter, method, version }) => `Calling ${method} with \`${parameter}\` names is deprecated and will be removed ${version}`,
+			);
 		}
 
 		if (role._id === 'admin' && !(await hasPermissionAsync(userId, 'assign-admin-role'))) {

apps/meteor/app/authorization/server/methods/deleteRole.ts

@@ -5,7 +5,7 @@ import type { ServerMethods } from '@rocket.chat/ui-contexts';
 import type { DeleteResult } from 'mongodb';
 
 import { hasPermissionAsync } from '../functions/hasPermission';
-import { apiDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
+import { methodDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
 
 declare module '@rocket.chat/ui-contexts' {
 	// eslint-disable-next-line @typescript-eslint/naming-convention
@@ -42,7 +42,12 @@ Meteor.methods<ServerMethods>({
 				});
 			}
 
-			apiDeprecationLogger.warn(`Calling authorization:deleteRole with role names will be deprecated in future versions of Rocket.Chat`);
+			methodDeprecationLogger.deprecatedParameterUsage(
+				'authorization:deleteRole',
+				'role',
+				'7.0.0',
+				({ parameter, method, version }) => `Calling ${method} with ${parameter} names is deprecated and will be removed ${version}`,
+			);
 		}
 
 		if (role.protected) {

apps/meteor/app/authorization/server/methods/removeUserFromRole.ts

@@ -6,7 +6,7 @@ import type { ServerMethods } from '@rocket.chat/ui-contexts';
 
 import { settings } from '../../../settings/server';
 import { hasPermissionAsync } from '../functions/hasPermission';
-import { apiDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
+import { methodDeprecationLogger } from '../../../lib/server/lib/deprecationWarningLogger';
 
 declare module '@rocket.chat/ui-contexts' {
 	// eslint-disable-next-line @typescript-eslint/naming-convention
@@ -41,8 +41,11 @@ Meteor.methods<ServerMethods>({
 				});
 			}
 
-			apiDeprecationLogger.warn(
-				`Calling authorization:removeUserFromRole with role names will be deprecated in future versions of Rocket.Chat`,
+			methodDeprecationLogger.deprecatedParameterUsage(
+				'authorization:removeUserFromRole',
+				'role',
+				'7.0.0',
+				({ parameter, method, version }) => `Calling ${method} with ${parameter} names is deprecated and will be removed ${version}`,
 			);
 		}
 

apps/meteor/app/emoji-custom/server/methods/listEmojiCustom.ts

@@ -15,7 +15,7 @@ declare module '@rocket.chat/ui-contexts' {
 
 Meteor.methods<ServerMethods>({
 	async listEmojiCustom(options = {}) {
-		methodDeprecationLogger.warn('listEmojiCustom will be removed in future versions of Rocket.Chat');
+		methodDeprecationLogger.method('listEmojiCustom', '7.0.0');
 
 		const user = await Meteor.userAsync();