/**
* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
*/
/**
* @module ai/aireviewmode/aireviewmode
* @publicApi
*/
import { ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
import { AIReviewModeUI } from "./aireviewmodeui.js";
import { AIReviewCoreEditing } from "../aireviewcore/aireviewcoreediting.js";
import { AIReviewModeController } from "./aireviewmodecontroller.js";
import { type AIReviewCommandData, type AIReviewCustomRunOptions, AIReviewGateway, type AIReviewRunOptions } from "./aireviewgateway.js";
import { type AIContextRef } from "../aicore/model/aicontextref.js";
/**
* The AI Review Mode feature.
*
* The Review feature provides users with AI-powered quality assurance for their content by automatically running commands
* for grammar, style, tone, and more.
*
* Learn more about AI features in CKEditor in the {@glink features/ai/ckeditor-ai-overview AI Overview} documentation.
*/
export declare class AIReviewMode extends ContextPlugin {
	/**
	* @inheritDoc
	*/
	static get requires(): PluginDependenciesOf<[AIReviewModeController, AIReviewModeUI, AIReviewCoreEditing, AIReviewGateway]>;
	/**
	* @inheritDoc
	*/
	static get pluginName(): "AIReviewMode";
	/**
	* @inheritDoc
	*/
	static override get isOfficialPlugin(): true;
	/**
	* @inheritDoc
	*/
	static override get isPremiumPlugin(): true;
	/**
	* Launches a review command on the UI — the programmatic equivalent of clicking a command in the review panel.
	*
	* Unlike the headless {@link module:ai/aireviewmode/aireviewgateway~AIReviewGateway} API, this method drives
	* the full UI-driven flow.
	*
	* Preconditions:
	* - The command must be available in the UI. Not available commands or unknown IDs throw `ai-reviewmode-unknown-command`.
	* - The `commandId` must point at a built-in system command or an extra command configured via
	* {@link module:ai/aireviewmode/aireviewmode~AIReviewModeConfig#extraCommands `ai.review.extraCommands`}.
	* The built-in `custom` command throws `ai-reviewmode-not-a-system-command`. Use {@link #startCustomReview} instead
	* to run the `custom` command.
	*
	* The returned promise resolves once the review run is dispatched to the controller. The command itself continues
	* to run asynchronously and the UI reflects its progress. Stream-phase failures surface via the existing UI error
	* views, not via this promise.
	*
	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
	* without the standard deprecation policy. Check the changelog for migration guidance.
	* @param commandId Id of a command returned by {@link #getAvailableCommands}.
	* @param options Optional `parameterId` (for parameterized system commands like `length` or `tone`).
	*/
	startReview(commandId: string, options?: AIReviewRunOptions): Promise<void>;
	/**
	* Launches the built-in `custom` review command on the UI — the programmatic equivalent of clicking the
	* `custom` command (and submitting the prompt modal) in the review panel.
	*
	* Analogical to {@link #startReview}, but restricted to the built-in `custom` command only.
	*
	* Preconditions:
	* - The `custom` command must be available in the UI. If not, the method throws `ai-reviewmode-unknown-command`.
	* - A model must be resolvable from `options.model` or the command's default. Otherwise the method throws
	* `ai-reviewmode-missing-custom-command-model`. Use {@link module:ai/aicore/model/aimodels~AIModels#getAvailableModels}
	* for valid model IDs.
	*
	* The returned promise resolves once the review run is dispatched to the controller. The command itself
	* continues to run asynchronously and the UI reflects its progress. Stream-phase failures surface via
	* the existing UI error views, not via this promise.
	*
	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
	* without the standard deprecation policy. Check the changelog for migration guidance.
	* @param prompt The prompt to run the `custom` command with.
	* @param options Optional `model` to run command with this specific model, instead of the default one.
	* Use {@link module:ai/aicore/model/aimodels~AIModels#getAvailableModels} for valid model IDs.
	*/
	startCustomReview(prompt: string, options?: AIReviewCustomRunOptions): Promise<void>;
	/**
	* Returns the list of review commands that can be run via {@link #startReview} and are visible in the UI.
	* The list will include `custom` command if it's available (meaning {@link #startCustomReview} can be used).
	*
	* The list combines built-in system commands with any extra commands declared
	* via the {@link module:ai/aireviewmode/aireviewmode~AIReviewModeConfig#extraCommands `ai.review.extraCommands`} configuration.
	*
	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
	* without the standard deprecation policy. Check the changelog for migration guidance.
	*/
	getAvailableCommands(): Array<AIReviewCommandData>;
}
export interface AIReviewModeConfig {
	/**
	* List of IDs of review commands that will be available in the AI Review feature UI. If not set, all available
	* predefined commands will be used. The order of IDs defines the order of commands in the UI.
	*
	* The list of all predefined commands, used by default:
	* - `custom`
	* - `correctness`
	* - `clarity`
	* - `readability`
	* - `length`
	* - `tone`
	*
	* The commands can be used selectively and rearranged with this configuration option. For example:
	*
	* ```ts
	* ClassicEditor
	* 	.create( {
	* 		ai: {
	* 			review: {
	* 				availableCommands: [
	* 					'length', 'tone', 'clarity', 'readability'
	* 				]
	* 			}
	* 		}
	* 	} )
	* 	.then( ... )
	* 	.catch( ... );
	* ```
	*
	* @default [ 'custom', 'correctness', 'clarity', 'readability', 'length', 'tone' ]
	*/
	availableCommands?: Array<string>;
	/**
	* List of extra review commands that can be added to the AI Review feature.
	*
	* Keep in mind that each command should have a unique ID that does not collide with predefined commands.
	* The `custom` command ID is reserved and cannot be used as an ID for extra command.
	*
	* To add a command and expose it in the UI, first a command definition needs to be provided:
	*
	* ```ts
	* ClassicEditor
	* 	.create( {
	* 		ai: {
	* 			review: {
	* 				extraCommands: [
	* 					{
	* 						id: 'improve-captions',
	* 						label: 'Improve Captions',
	* 						description: 'Improve image captions in the document.',
	* 						prompt: 'Suggest improvements for the image captions in the document.',
	* 					},
	* 					{
	* 						id: 'expand-abbreviations',
	* 						label: 'Expand Abbreviations',
	* 						description: 'Expand abbreviations in the document.',
	* 						prompt: 'Suggest expansions for abbreviations in the document.',
	* 						model: 'gpt-5-2' // Optional, if not set, default model will be used.
	* 					},
	* 					{
	* 						id: 'style-guide',
	* 						label: 'Style Guide',
	* 						description: 'Check the document against the style guide.',
	* 						context: { id: 'style-guide', promptId: 'review-rules' }
	* 					}
	* 				]
	* 			}
	* 		}
	* 	} )
	* 	.then( ... )
	* 	.catch( ... );
	* ```
	*
	* Then if {@link #availableCommands} is not set, the extra commands will be added to the end of the list of available
	* commands and visible in the UI by default. Otherwise, the extra commands need to be explicitly added to the list
	* of available commands to be exposed in the UI:
	*
	* ```ts
	* ClassicEditor
	* 	.create( {
	* 		ai: {
	* 			review: {
	* 				extraCommands: [ ... ],
	* 				availableCommands: [
	* 					'custom', 'correctness', 'clarity', 'readability', 'length', 'tone', 'improve-captions', 'expand-abbreviations'
	* 				]
	* 			}
	* 		}
	* 	} )
	* 	.then( ... )
	* 	.catch( ... );
	* ```
	*/
	extraCommands?: Array<AIReviewCustomCommand>;
}
/**
* An extra review command definition.
*
* The command needs a prompt source, provided in one of three ways:
*
* * an inline `prompt` string - sent as the prompt,
* * a `context` reference - the referenced context drives the command (for example through a prompt it contains),
* * both - the inline `prompt` is used and the `context` is attached as additional reference material (for example a file).
*
* The `model` property is optional. If not specified, the default model is used.
*
* ```ts
* {
*	id: 'improve-captions',
*	label: 'Improve Captions',
*	description: 'Improve image captions in the document.',
*	prompt: 'Suggest improvements for the image captions in the document.'
* }
* ```
*
* The same command using a `context` reference instead of an inline `prompt`:
*
* ```ts
* {
*	id: 'improve-captions',
*	label: 'Improve Captions',
*	description: 'Improve image captions in the document.',
*	context: { id: 'style-guide', promptId: 'improve-captions' }
* }
* ```
*
* An inline `prompt` combined with a `context` that attaches a single file as reference material:
*
* ```ts
* {
*	id: 'improve-captions',
*	label: 'Improve Captions',
*	description: 'Improve image captions in the document.',
*	prompt: 'Suggest improvements for the image captions in the document.',
*	context: { id: 'style-guide', fileId: 'caption-examples' }
* }
* ```
*/
export type AIReviewCustomCommand = {
	id: string;
	label: string;
	description: string;
	model?: string;
	/**
	* The prompt to be sent to the AI model when the command is executed.
	*
	* At least one prompt source is required: an inline `prompt`, a `context` that carries a prompt (a whole context
	* or a `promptId` reference), or both. A `context` that references only a single file (`fileId`) cannot drive the
	* command on its own and must be combined with an inline `prompt`.
	*/
	readonly prompt?: string;
	/**
	* A context reference attached to the command.
	*
	* When no inline `prompt` is provided, the referenced context drives the command (a whole context or a `promptId`
	* reference). When combined with an inline `prompt`, it is attached as additional reference material (for example
	* a single file).
	*
	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
	* without the standard deprecation policy. Check the changelog for migration guidance.
	*/
	readonly context?: AIContextRef;
};