/**
* @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/aireviewgateway
* @publicApi
*/
import { ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
import { AIConnector } from "../aicore/aiconnector.js";
import { AIReviewCoreEditing } from "../aireviewcore/aireviewcoreediting.js";
import { AIReviewModeCheckRegistry } from "./aireviewmodecheckregistry.js";
import { AIEditing } from "../aicore/aiediting.js";
import { type AIRunResult } from "../aicore/model/airunresult.js";
import { type AICheckRunSingleRootResult } from "../aireviewcore/model/aichecksinglerootresult.js";
import { AIGateway, type AIRunBaseOptions, type AIGatewayApplyOptions } from "../aicore/aigateway.js";
import { AICore } from "../aicore/aicore.js";
import { type AIModels } from "../aicore/model/aimodels.js";
import { type AIEditorRoot } from "../aicore/model/aieditorroot.js";
/**
* Review command data.
*/
export interface AIReviewCommandData {
	/**
	* Id of the review command.
	*/
	id: string;
	/**
	* Human-readable command title.
	*/
	title: string;
	/**
	* Human-readable description of what the command does.
	*/
	description: string;
	/**
	* Selectable parameters for parameterized commands (e.g. `length`, `tone`). One of these IDs can be
	* passed as `options.parameterId` when invoking the command.
	*/
	parameters?: Array<{
		id: string;
		label: string;
	}>;
}
/**
* Roots filter shared by both `AIReviewRunOptions` and `AIReviewCustomRunOptions`.
*/
export type AIReviewRootsOption = {
	/**
	* The roots to run the review against. When omitted, every visible root across every editor in the current
	* {@link module:core/context~Context `Context`} is reviewed. When provided, only the listed roots are reviewed;
	* the order of entries in `roots` is treated as a set-membership filter and does not affect the payload order.
	*
	* Each entry's `channelId` must match an editor's `collaboration.channelId`; `rootName` must match a live,
	* visible (non-`$graveyard`) root within that editor.
	*/
	roots?: Array<AIEditorRoot>;
};
export type AIReviewRunOptions = AIReviewRootsOption & {
	/**
	* Id of one of the values in {@link module:ai/aireviewmode/aireviewgateway~AIReviewCommandData#parameters}.
	* Applicable to parameterized commands (e.g. `length`, `tone`), ignored otherwise.
	*/
	parameterId?: string;
};
export type AIReviewCustomRunOptions = AIReviewRootsOption & {
	/**
	* The model that will be used to run the custom command.
	* The IDs of an AI models can be acquired via {@link module:ai/aicore/model/aimodels~AIModels#getAvailableModels}.
	*/
	model?: string;
};
export type AIReviewHeadlessRunOptions = AIReviewRunOptions & AIRunBaseOptions;
export type AIReviewHeadlessCustomRunOptions = AIReviewCustomRunOptions & AIRunBaseOptions;
/**
* Headless, stateless public API for running AI reviews end-to-end.
*
* This plugin can be loaded standalone (without `AIReviewMode` plugin) to expose a programmatic
* review API. It is also transparently loaded by `AIReviewMode` to back the UI-driven flow.
*/
export declare class AIReviewGateway extends ContextPlugin {
	/**
	* @inheritDoc
	*/
	static get pluginName(): "AIReviewGateway";
	/**
	* @inheritDoc
	*/
	static get requires(): PluginDependenciesOf<[AIReviewCoreEditing, AIReviewModeCheckRegistry, AIConnector, AIEditing, AIGateway, AICore]>;
	/**
	* The shared model registry. Exposed here so headless gateways are self-sufficient — integrators can
	* discover and resolve models (`getAvailableModels()`, `getModel()`, `resolveModel()`, …) without
	* reaching for the `AICore` plugin directly.
	*
	* @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.
	*/
	get models(): AIModels;
	/**
	* @inheritDoc
	*/
	static override get isOfficialPlugin(): true;
	/**
	* @inheritDoc
	*/
	static override get isPremiumPlugin(): true;
	/**
	* Returns the list of review commands that can be run with {@link #runReview}.
	*
	* The list combines built-in system checks with any extra checks declared
	* via the {@link module:ai/aireviewmode/aireviewmode~AIReviewModeConfig#extraCommands `ai.review.extraCommands`}
	* configuration.
	*
	* The method returns all review commands regardless of the editor configuration (which affects the UI only), meaning the commands
	* that are not visible in the UI can be still invoked via the {@link module:ai/aireviewmode/aireviewgateway~AIReviewGateway} API.
	*
	* @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.
	*/
	getAllCommands(): Promise<Array<AIReviewCommandData>>;
	/**
	* Runs the given review command against every visible root across every editor in the current
	* {@link module:core/context~Context `Context`} and returns an
	* {@link module:ai/aicore/model/airunresult~AIRunResult} — a container with one
	* {@link module:ai/aireviewcore/model/aichecksinglerootresult~AICheckRunSingleRootResult} per root and whole-run
	* `status` / `error`. Accepts built-in commands and extra commands configured via
	* {@link module:ai/aireviewmode/aireviewmode~AIReviewModeConfig#extraCommands `ai.review.extraCommands`}.
	*
	* To insert or suggest changes back to the editor, pass the returned result to {@link #applyReview}.
	*
	* When the `roots` option is provided, its entries are validated at the call boundary; an entry that does not
	* resolve to a live, visible (non-`$graveyard`) root throws `ai-reviewcoreediting-root-not-found`, and an
	* explicitly empty `roots` array throws `ai-reviewcoreediting-empty-roots`.
	*
	* @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 #getAllCommands}.
	* @param options Optional `parameterId`, `roots` filter, and `signal` to allow aborting the run.
	*/
	runReview(commandId: string, options?: AIReviewHeadlessRunOptions): Promise<AIRunResult<AICheckRunSingleRootResult>>;
	/**
	* Runs the `custom` review command against every visible root across every editor in the current
	* {@link module:core/context~Context `Context`} and returns an
	* {@link module:ai/aicore/model/airunresult~AIRunResult}.
	*
	* The command requires a prompt to run, and optional model ID. The list of available models can be discovered
	* via {@link module:ai/aicore/model/aimodels~AIModels#getAvailableModels}.
	*
	* Analogical to {@link #runReview} but restricted to the `custom` command only.
	*
	* @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` (optional override), `roots` filter, and `signal` to allow aborting the run.
	*/
	runCustomReview(prompt: string, options?: AIReviewHeadlessCustomRunOptions): Promise<AIRunResult<AICheckRunSingleRootResult>>;
	/**
	* Applies a review run result (produced by {@link #runReview} or {@link #runCustomReview}) to the editor content,
	* either as direct changes or as track-changes suggestions. Each per-root sub-result is applied to the root
	* identified by its own `channelId` and `rootName`. Pass `options.roots` to restrict the apply to a subset of
	* roots — the filter is symmetric with the one accepted by {@link #runReview} / {@link #runCustomReview}.
	*
	* By default the apply is stamped with `aiSource: 'review'`; pass `options.aiSource` to override.
	*
	* @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 result The result returned by {@link #runReview} or {@link #runCustomReview}.
	* @param options Apply options forwarded to {@link module:ai/aicore/aigateway~AIGateway#apply}, including the
	* `applyMethod` and an optional `roots` filter.
	*/
	applyReview(result: AIRunResult<AICheckRunSingleRootResult>, options: AIGatewayApplyOptions): void;
}