feat: Add OpenAPI Support to Statistics API

.changeset/odd-hounds-develop.md

@@ -0,0 +1,5 @@
+---
+"@fake-scope/fake-pkg": patch
+---
+
+Add OpenAPI support for the Rocket.Chat Statistics 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/stats.ts

@@ -1,30 +1,129 @@
+import type { TelemetryEvents } from '@rocket.chat/core-services';
+import type { IStats } from '@rocket.chat/core-typings';
+import { ajv, validateUnauthorizedErrorResponse, validateBadRequestErrorResponse } from '@rocket.chat/rest-typings';
+
 import { getStatistics, getLastStatistics } from '../../../statistics/server';
 import telemetryEvent from '../../../statistics/server/lib/telemetryEvents';
+import type { ExtractRoutesFromAPI } from '../ApiClass';
 import { API } from '../api';
 import { getPaginationItems } from '../helpers/getPaginationItems';
 
-API.v1.addRoute(
-	'statistics',
-	{ authRequired: true },
-	{
-		async get() {
-			const { refresh = 'false' } = this.queryParams;
+type StatisticsProps = { refresh?: 'true' | 'false' };
+
+const StatisticsSchema = {
+	type: 'object',
+	properties: {
+		refresh: {
+			enum: ['true', 'false'],
+			default: 'false',
+		},
+	},
+	required: [],
+	additionalProperties: false,
+};
+
+const isStatisticsProps = ajv.compile<StatisticsProps>(StatisticsSchema);
+
+type StatisticsListProps = {
+	offset: number;
+	count?: number;
+};
+
+const StatisticsListSchema = {
+	type: 'object',
+	properties: {
+		offset: {
+			type: 'number',
+			default: 0,
+			minimum: 0,
+		},
+		count: {
+			type: 'number',
+			default: 100,
+			minimum: 1,
+		},
+	},
+	required: [],
+	additionalProperties: false,
+};
+
+const isStatisticsListProps = ajv.compile<StatisticsListProps>(StatisticsListSchema);
+
+type OTREnded = { rid: string };
+
+type SlashCommand = { command: string };
+
+type SettingsCounter = { settingsId: string };
 
+type Param = {
+	eventName: TelemetryEvents;
+	timestamp?: number;
+} & (OTREnded | SlashCommand | SettingsCounter);
+
+type TelemetryPayload = {
+	params: Param[];
+};
+
+const statisticsEndpoints = API.v1
+	.get(
+		'statistics',
+		{
+			authRequired: true,
+			query: isStatisticsProps,
+			response: {
+				200: ajv.compile<IStats>({
+					allOf: [
+						{ $ref: '#/components/schemas/IStats' },
+						{
+							type: 'object',
+							properties: {
+								success: { type: 'boolean', enum: [true] },
+							},
+							required: ['success'],
+						},
+					],
+				}),
+				400: validateBadRequestErrorResponse,
+				401: validateUnauthorizedErrorResponse,
+			},
+		},
+		async function action() {
+			const { refresh = 'false' } = this.queryParams;
 			return API.v1.success(
 				await getLastStatistics({
 					userId: this.userId,
 					refresh: refresh === 'true',
 				}),
 			);
 		},
-	},
-);
-
-API.v1.addRoute(
-	'statistics.list',
-	{ authRequired: true },
-	{
-		async get() {
+	)
+	.get(
+		'statistics.list',
+		{
+			authRequired: true,
+			query: isStatisticsListProps,
+			response: {
+				200: ajv.compile<{ statistics: IStats[]; count: number; offset: number; total: number }>({
+					type: 'object',
+					properties: {
+						statistics: {
+							type: 'array',
+							items: { $ref: '#/components/schemas/IStats' },
+							minItems: 0,
+						},
+						count: { type: 'integer', minimum: 1 },
+						offset: { type: 'integer', minimum: 0, default: 0 },
+						total: { type: 'integer', minimum: 1 },
+						success: { type: 'boolean', enum: [true] },
+					},
+					additionalProperties: false,
+					required: ['statistics', 'count', 'offset', 'total', 'success'],
+				}),
+				400: validateBadRequestErrorResponse,
+				401: validateUnauthorizedErrorResponse,
+			},
+		},
+		async function action() {
 			const { offset, count } = await getPaginationItems(this.queryParams);
 			const { sort, fields, query } = await this.parseJsonQuery();
 
@@ -41,14 +140,86 @@ API.v1.addRoute(
 				}),
 			);
 		},
-	},
-);
-
-API.v1.addRoute(
-	'statistics.telemetry',
-	{ authRequired: true },
-	{
-		post() {
+	)
+	.post(
+		'statistics.telemetry',
+		{
+			authRequired: true,
+			body: ajv.compile<TelemetryPayload>({
+				oneOf: [
+					{
+						type: 'object',
+						properties: {
+							eventName: { const: 'otrStats' },
+							rid: { type: 'string' },
+						},
+						required: ['eventName', 'rid'],
+						additionalProperties: false,
+					},
+					{
+						type: 'object',
+						properties: {
+							eventName: { const: 'slashCommandsStats' },
+							command: { type: 'string' },
+						},
+						required: ['eventName', 'command'],
+						additionalProperties: false,
+					},
+					{
+						type: 'object',
+						properties: {
+							eventName: { const: 'updateCounter' },
+							settingsId: { type: 'string' },
+						},
+						required: ['eventName', 'settingsId'],
+						additionalProperties: false,
+					},
+				],
+			}),
+			response: {
+				200: ajv.compile({
+					type: 'object',
+					properties: {
+						success: { type: 'boolean' },
+					},
+					required: ['success'],
+					additionalProperties: false,
+				}),
+				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,
+				}),
+			},
+		},
+		async function action() {
 			const events = this.bodyParams;
 
 			events?.params?.forEach((event) => {
@@ -58,5 +229,11 @@ API.v1.addRoute(
 
 			return API.v1.success();
 		},
-	},
-);
+	);
+
+export type StatisticsEndpoints = ExtractRoutesFromAPI<typeof statisticsEndpoints>;
+
+declare module '@rocket.chat/rest-typings' {
+	// eslint-disable-next-line @typescript-eslint/naming-convention, @typescript-eslint/no-empty-interface
+	interface Endpoints extends StatisticsEndpoints {}
+}

apps/meteor/app/statistics/server/lib/getAppsStatistics.ts

@@ -8,22 +8,22 @@ import { Info } from '../../../utils/rocketchat.info';
 
 type AppsStatistics = {
 	engineVersion: string;
-	totalInstalled: number | false;
-	totalActive: number | false;
-	totalFailed: number | false;
-	totalPrivateApps: number | false;
-	totalPrivateAppsEnabled: number | false;
+	totalInstalled: number;
+	totalActive: number;
+	totalFailed: number;
+	totalPrivateApps: number;
+	totalPrivateAppsEnabled: number;
 };
 
 async function _getAppsStatistics(): Promise<AppsStatistics> {
 	if (!Apps.self?.isInitialized()) {
 		return {
 			engineVersion: Info.marketplaceApiVersion,
-			totalInstalled: false,
-			totalActive: false,
-			totalFailed: false,
-			totalPrivateApps: false,
-			totalPrivateAppsEnabled: false,
+			totalInstalled: 0,
+			totalActive: 0,
+			totalFailed: 0,
+			totalPrivateApps: 0,
+			totalPrivateAppsEnabled: 0,
 		};
 	}
 
@@ -58,7 +58,6 @@ async function _getAppsStatistics(): Promise<AppsStatistics> {
 				}
 			}),
 		);
-
 		return {
 			engineVersion: Info.marketplaceApiVersion,
 			totalInstalled,
@@ -71,11 +70,11 @@ async function _getAppsStatistics(): Promise<AppsStatistics> {
 		SystemLogger.error({ msg: 'Exception while getting Apps statistics', err });
 		return {
 			engineVersion: Info.marketplaceApiVersion,
-			totalInstalled: false,
-			totalActive: false,
-			totalFailed: false,
-			totalPrivateApps: false,
-			totalPrivateAppsEnabled: false,
+			totalInstalled: 0,
+			totalActive: 0,
+			totalFailed: 0,
+			totalPrivateApps: 0,
+			totalPrivateAppsEnabled: 0,
 		};
 	}
 }

apps/meteor/app/statistics/server/lib/statistics.ts

@@ -221,9 +221,10 @@ export const statistics = {
 			}),
 		);
 
+		// TODO: the routingAlgorithm is duplicated in L202 & L227
 		// Type of routing algorithm used on omnichannel
 		statistics.routingAlgorithm = settings.get('Livechat_Routing_Method');
-
+		// TODO: the onHoldEnabled is duplicated in L205 & L230
 		// is on-hold active
 		statistics.onHoldEnabled = settings.get('Livechat_allow_manual_on_hold');
 

packages/core-services/src/types/ITelemetryEvent.ts

@@ -2,7 +2,6 @@ type updateCounterDataType = { settingsId: string };
 type slashCommandsDataType = { command: string };
 type otrDataType = { rid: string };
 
-// TODO this is duplicated from /packages/rest-typings/src/v1/statistics.ts
 export type TelemetryMap = { otrStats: otrDataType; slashCommandsStats: slashCommandsDataType; updateCounter: updateCounterDataType };
 export type TelemetryEvents = keyof TelemetryMap;
 

packages/core-typings/src/Ajv.ts

@@ -4,7 +4,9 @@
 import type { IInvite } from './IInvite';
 import type { IMessage } from './IMessage';
 import type { IOAuthApps } from './IOAuthApps';
+import type { IStats } from './IStats';
 import type { IPermission } from './IPermission';
 import type { ISubscription } from './ISubscription';
 
-export const schemas = typia.json.schemas<[ISubscription | IInvite | ICustomSound | IMessage | IOAuthApps | IPermission], '3.0'>();
+export const schemas = typia.json.schemas<[ISubscription | IInvite | ICustomSound | IMessage | IOAuthApps | IPermission | IStats], '3.0'>();
+