From 8ae1f5fa776d2852b49163718c3a96ff45590d49 Mon Sep 17 00:00:00 2001
From: Mateusz Baginski <cziken58@gmail.com>
Date: Fri, 27 Sep 2024 09:26:28 +0200
Subject: [PATCH] Define API communication format

---
 packages/ckeditor5-core/src/editor/editor.ts  | 187 +++++++++++++++++-
 .../tests/editor/licensecheck.js              |   2 +-
 2 files changed, 185 insertions(+), 4 deletions(-)

diff --git a/packages/ckeditor5-core/src/editor/editor.ts b/packages/ckeditor5-core/src/editor/editor.ts
index c385de96fae..b9afb4e89d9 100644
--- a/packages/ckeditor5-core/src/editor/editor.ts
+++ b/packages/ckeditor5-core/src/editor/editor.ts
@@ -877,10 +877,10 @@ export default abstract class Editor extends /* #__PURE__ */ ObservableMixin() {
 	 */
 	public static ContextWatchdog = ContextWatchdog;
 
-	private _getTelemetryData() {
+	private _getTelemetryData(): EditorTelemetryData {
 		return {
-			editorVersion: globalThis.CKEDITOR_VERSION
-		};
+			version: globalThis.CKEDITOR_VERSION
+		} /* TODO: Remove */ as unknown as EditorTelemetryData;
 	}
 
 	private _showLicenseError( reason: LicenseErrorReason, pluginName?: string ) {
@@ -1015,6 +1015,187 @@ type LicenseErrorReason =
 	'usageLimit' |
 	'distributionChannel';
 
+type EditorTelemetryData = {
+
+	/**
+	 * The editor version.
+	 */
+	version: string;
+
+	/**
+	 * The editor type.
+	 */
+	type: `${ 'Classic' | 'Inline' | 'Decoupled' | 'MultiRoot' }Editor`;
+
+	/**
+	 * The list of plugins used in the editor.
+	 */
+	plugins: Array<PluginTelemetryData>;
+
+	/**
+	 * The configuration of the toolbars used in the editor.
+	 */
+	toolbar: {
+
+		/**
+		 * The normal toolbar configuration used in the editor (if present).
+		 */
+		normal?: ToolbarTelemetryData;
+
+		/**
+		 * The block toolbar configuration used in the editor (if present).
+		 */
+		block?: ToolbarTelemetryData;
+
+		/**
+		 * The balloon toolbar configuration used in the editor (if present).
+		 */
+		balloon?: ToolbarTelemetryData;
+	};
+
+	/**
+	 * The configuration of the context menus used in the editor.
+	 */
+	menuBar: {
+
+		/**
+		 * Check if the editor menu is enabled.
+		 */
+		isVisible: boolean;
+	};
+
+	/**
+	 * The configuration of the language used in the editor.
+	 */
+	language: {
+
+		/**
+		 * The language used in the editor UI.
+		 */
+		ui: string;
+
+		/**
+		 * The language used in the editor content.
+		 */
+		content: string;
+	};
+
+	distribution: {
+
+		/**
+		 * The distribution channel of the editor. It can be for example `sh` or `cloud`.
+		 */
+		channel: string;
+	};
+
+	/**
+	 * Environment and browser information.
+	 */
+	env: EnvTelemetryData;
+
+	/**
+	 * The configuration of the editor integrations.
+	 */
+	integrations: {
+		[integrationName: string]: IntegrationTelemetryData;
+	};
+};
+
+type IntegrationTelemetryData = {
+
+	/**
+	 * The version of the CKEditor integration. e.g. it might be `43.0.0`.
+	 */
+	version: string;
+
+	/**
+	 * The version of the CKEditor framework used in the integration. e.g. for React integration might be `18.0.0`.
+	 */
+	frameworkVersion?: string;
+
+	/**
+	 * Additional data specific to the integration. e.g. for the React integration it might be:
+	 *
+	 * 	* The list of React components or Hooks used in the integration.
+	 * 	* Check if the editor was loaded using CDN injector helpers or was placed as head script manually.
+	 */
+	additionalData?: Record<string, unknown>;
+};
+
+type EnvTelemetryData = {
+
+	/**
+	 * Indicates that the application is running on Macintosh.
+	 */
+	isMac: boolean;
+
+	/**
+	 * Indicates that the application is running on Windows.
+	 */
+	isWindows: boolean;
+
+	/**
+	 * Indicates that the application is running in Firefox (Gecko).
+	 */
+	isGecko: boolean;
+
+	/**
+	 * Indicates that the application is running in Safari.
+	 */
+	isSafari: boolean;
+
+	/**
+	 * Indicates that the application is running in iOS.
+	 */
+	isiOS: boolean;
+
+	/**
+	 * Indicates that the application is running on Android mobile device.
+	 */
+	isAndroid: boolean;
+
+	/**
+	 * Indicates that the application is running in a browser using the Blink engine.
+	 */
+	isBlink: boolean;
+};
+
+type ToolbarTelemetryData = {
+
+	/**
+	 * List of toolbar items without separators and new lines.
+	 */
+	items: Array<string>;
+
+	/**
+	 * Check if `-` line separator was used in the toolbar.
+	 */
+	isMultiline: boolean;
+
+	/**
+	 * Check if toolbar is configured to stop grouping items when it is full.
+	 */
+	shouldNotGroupWhenFull: boolean;
+};
+
+type PluginTelemetryData = {
+
+	/**
+	 * The name of the plugin.
+	 */
+	name: string;
+
+	/**
+	 * Flag indicating whether the plugin is a premium CKEditor 5 plugin or not.
+	 */
+	isPremium: boolean;
+
+	/**
+	 * Flag indicating whether the plugin is an official CKEditor 5 plugin or not.
+	 */
+	isOfficial: boolean;
+};
+
 /**
  * Fired when the {@link module:engine/controller/datacontroller~DataController#event:ready data} and all additional
  * editor components are ready.
diff --git a/packages/ckeditor5-core/tests/editor/licensecheck.js b/packages/ckeditor5-core/tests/editor/licensecheck.js
index 2e29c0c9747..0c07f28c151 100644
--- a/packages/ckeditor5-core/tests/editor/licensecheck.js
+++ b/packages/ckeditor5-core/tests/editor/licensecheck.js
@@ -566,7 +566,7 @@ describe( 'Editor - license check', () => {
 			const sentData = JSON.parse( fetchStub.firstCall.lastArg.body );
 
 			expect( sentData.license ).to.equal( licenseKey );
-			expect( sentData.telemetry ).to.deep.equal( { editorVersion: globalThis.CKEDITOR_VERSION } );
+			expect( sentData.telemetry ).to.deep.equal( { version: globalThis.CKEDITOR_VERSION } );
 		} );
 
 		it( 'should not send any request if license key does not contain a usage endpoint', () => {