@ckeditor/ckeditor5-ai 48.8.1-alpha.4 → 49.0.0-alpha.1

package/dist/aicore/model/aireply.d.ts

@@ -1,134 +1,142 @@
 /**
- * @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
- */
+* @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/aicore/model/aireply
- * @publicApi
- */
-import { type Locale } from '@ckeditor/ckeditor5-utils';
-import { Element, Document } from '../utils/htmlparser.js';
-import { type AISuggestionContentPartDefinition } from '../utils/getsuggestionpartsfromreply.js';
-import type { AISource } from '../aiconnector.js';
-import type { AIDataIdDocumentSource } from './aicontext.js';
+* @module ai/aicore/model/aireply
+* @publicApi
+*/
+import { type Locale, type ObservableMixinConstructor } from "@ckeditor/ckeditor5-utils";
+import { Element, type Document } from "../utils/htmlparser.js";
+import { type Editor } from "@ckeditor/ckeditor5-core";
+import { type AISuggestionContentPartDefinition } from "../utils/getsuggestionpartsfromreply.js";
+import type { AISource } from "../aiconnector.js";
+declare const _AIReplyBase: ObservableMixinConstructor;
 /**
- * The type of the reply. It can be one of the following:
- *
- * * `modification`: A content change suggestion made by the AI endpoint.
- * * `text`: A generic text response.
- */
-export type AIReplyType = 'modification' | 'text';
-declare const AIReply_base: {
-    new (): import("@ckeditor/ckeditor5-utils").Observable;
-    prototype: import("@ckeditor/ckeditor5-utils").Observable;
-};
+* The type of the reply. It can be one of the following:
+*
+* * `modification`: A content change suggestion made by the AI endpoint.
+* * `text`: A generic text response.
+*/
+export type AIReplyType = "modification" | "text";
 /**
- * Represents a single reply from the AI endpoint.
- *
- * A reply's {@link #content} can be updated using the {@link #appendContent} method.
- */
-export declare class AIReply extends /* #__PURE__ */ AIReply_base {
-    /**
-     * The ID of the reply.
-     */
-    readonly id: string;
-    /**
-     * The ID of the interaction that the reply belongs to.
-     */
-    readonly interactionId: string;
-    /**
-     * The type of the reply.
-     */
-    readonly type: AIReplyType;
-    /**
-     * The content of the reply as received from AI endpoint.
-     *
-     * @observable
-     */
-    content: string;
-    /**
-     * The sources of the reply. Used for web search reply.
-     */
-    sources: Array<AISource>;
-    /**
-     * The parsed content of the reply.
-     *
-     * This property is automatically updated after reply {@link #content} changes. You can add a listener to `replyContentUpdated` event
-     * in order to react to these changes.
-     *
-     * Note, that this property type is not DOM Document, but a simplified version provided by `domhandler` library.
-     */
-    parsedContent: Document;
-    /**
-     * Whether the reply is done. The reply is done once the AI endpoint emitted the last chunk of the content
-     * that matches the reply's type or the reply was interrupted (user stop, error, connection drop).
-     *
-     * See {@link #isComplete} for more information about the reply's completion state.
-     *
-     * @observable
-     */
-    isDone: boolean;
-    /**
-     * Whether the reply finished organically, i.e. the stream ran out of chunks naturally.
-     *
-     * This is `false` while streaming, and also `false` if the reply was stopped or errored before the stream ended.
-     *
-     * See {@link #isDone} for more information.
-     *
-     * @observable
-     */
-    isComplete: boolean;
-    /**
-     * @inheritDoc
-     */
-    constructor({ type, content, isDone, isComplete, interactionId, areActionsDisabled, isFromHistory, documentContextContent, dataIdDocumentSources, documentId, locale, id }: {
-        type: AIReplyType;
-        interactionId: string;
-        areActionsDisabled?: boolean;
-        isFromHistory?: boolean;
-        content?: string;
-        isDone?: boolean;
-        isComplete?: boolean;
-        documentContextContent?: string;
-        dataIdDocumentSources?: ReadonlyMap<string, AIDataIdDocumentSource>;
-        documentId?: string;
-        locale?: Locale;
-        id?: string;
-    });
-    /**
-     * Appends new content to the reply.
-     *
-     * See {@link #content} for more information.
-     */
-    appendContent(content: string): void;
-    /**
-     * Destroys the reply.
-     */
-    destroy(): void;
+* Represents a single reply from the AI endpoint.
+*
+* A reply's {@link #content} can be updated using the {@link #appendContent} method.
+*/
+export declare class AIReply extends _AIReplyBase {
+	/**
+	* The ID of the reply.
+	*/
+	readonly id: string;
+	/**
+	* The ID of the interaction that the reply belongs to.
+	*/
+	readonly interactionId: string;
+	/**
+	* The type of the reply.
+	*/
+	readonly type: AIReplyType;
+	/**
+	* The content of the reply as received from AI endpoint. It stores separate content for each document.
+	*/
+	content: Map<string, string>;
+	/**
+	* The sources of the reply. Used for web search reply.
+	*/
+	sources: Array<AISource>;
+	/**
+	* The parsed content of the reply.
+	*
+	* This property is automatically updated after reply {@link #content} changes. You can add a listener to `replyContentUpdated` event
+	* in order to react to these changes.
+	*
+	* Note, that this property type is not DOM Document, but a simplified version provided by `domhandler` library.
+	*/
+	parsedContent: Map<string, Document>;
+	/**
+	* Whether the reply is done. The reply is done once the AI endpoint emitted the last chunk of the content
+	* that matches the reply's type or the reply was interrupted (user stop, error, connection drop).
+	*
+	* See {@link #isComplete} for more information about the reply's completion state.
+	*
+	* @observable
+	*/
+	isDone: boolean;
+	/**
+	* Whether the reply finished organically, i.e. the stream ran out of chunks naturally.
+	*
+	* This is `false` while streaming, and also `false` if the reply was stopped or errored before the stream ended.
+	*
+	* See {@link #isDone} for more information.
+	*
+	* @observable
+	*/
+	isComplete: boolean;
+	/**
+	* @inheritDoc
+	*/
+	constructor({ type, isDone, isComplete, interactionId, areActionsDisabled, outdatedReasonByDocumentId, isFromHistory, documentContextContent, locale, id, channelsToEditors }: {
+		type: AIReplyType;
+		interactionId: string;
+		channelsToEditors: Map<string, Editor>;
+		areActionsDisabled?: boolean;
+		outdatedReasonByDocumentId?: ReadonlyMap<string, AIReplyChangeGroupOutdatedReason>;
+		isFromHistory?: boolean;
+		isDone?: boolean;
+		isComplete?: boolean;
+		documentContextContent?: Array<{
+			id?: string;
+			content?: string;
+			channelId: string;
+			rootName?: string;
+		}>;
+		locale?: Locale;
+		id?: string;
+	});
+	/**
+	* Appends new content to the reply. Text replies and any plain-text fragments default to the `'text'` bucket;
+	* modification replies route by `documentId` to the per-document buckets in {@link #content}.
+	*/
+	appendContent(content: string, documentId?: string): void;
+	/**
+	* Destroys the reply.
+	*/
+	destroy(): void;
 }
 /**
- * An event emitted by an {@link module:ai/aicore/model/aireply~AIReply} when it's
- * {@link module:ai/aicore/model/aireply~AIReply#content} gets updated or the reply is marked as done.
- *
- * @eventName ~AIReply#replyContentUpdated
- */
+* An event emitted by an {@link module:ai/aicore/model/aireply~AIReply} when it's
+* {@link module:ai/aicore/model/aireply~AIReply#content} gets updated or the reply is marked as done.
+*
+* @eventName ~AIReply#replyContentUpdated
+*/
 export type AIReplyContentUpdatedEvent = {
-    name: 'replyContentUpdated';
-    args: [
-        reply: AIReply,
-        updatedChangeGroups?: Array<AIReplyChangeGroup>
-    ];
+	name: "replyContentUpdated";
+	args: [reply: AIReply, updatedChangeGroups?: Array<AIReplyChangeGroup>];
 };
 export type AIReplyHotNode = {
-    node: Element;
-    id: string;
-    type: AISuggestionContentPartDefinition['type'];
-    anchorId?: string | null;
+	node: Element;
+	id: string;
+	type: AISuggestionContentPartDefinition["type"];
+	anchorId?: string | null;
 };
 export type AIReplyChangeGroup = {
-    readonly changes: Array<AIReplyHotNode>;
-    readonly index: number;
-    state: AIReplyChangeGroupState;
+	readonly changes: Array<AIReplyHotNode>;
+	readonly documentId: string;
+	readonly editor: Editor | undefined;
+	readonly rootName: string;
+	index: number;
+	state: AIReplyChangeGroupState;
+	outdatedReason?: AIReplyChangeGroupOutdatedReason;
 };
-export type AIReplyChangeGroupState = 'pending' | 'accepted' | 'rejected' | 'outdated';
+export type AIReplyChangeGroupState = "pending" | "accepted" | "rejected" | "outdated";
+/**
+* The reason why a change group became {@link ~AIReplyChangeGroupState `'outdated'`}. It selects which
+* tooltip is shown on the "Outdated" pill.
+*
+* - `'content-removed'` - the targeted content was removed, or its root is no longer loaded.
+* - `'editor-removed'` - the target editor is gone or destroyed.
+* - `'session-changed'` - the suggestion was loaded from a previous session, so it can no longer be applied.
+*/
+export type AIReplyChangeGroupOutdatedReason = "content-removed" | "editor-removed" | "session-changed";
 export {};

package/dist/aicore/model/airunresult.d.ts

@@ -0,0 +1,43 @@
+/**
+* @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/aicore/model/airunresult
+* @publicApi
+*/
+import type { AIRunSingleRootResult, AIRunStatus } from "./airunsinglerootresult.js";
+import { type CKEditorError } from "@ckeditor/ckeditor5-utils";
+/**
+* Container returned by any per-root AI run. Wraps one
+* {@link module:ai/aicore/model/airunsinglerootresult~AIRunSingleRootResult} (or feature-specific subclass) per root
+* when the run completes successfully; on whole-run failures (transport / parse errors or abort) the `results` array
+* stays empty and the outcome is described by `status` and `error`.
+*/
+export declare class AIRunResult<SubResultType extends AIRunSingleRootResult = AIRunSingleRootResult> {
+	constructor(results?: Array<SubResultType>);
+	/**
+	* Marks the run as aborted. Reflected via {@link #status}. No-op when the run has already errored — a
+	* concrete error is more informative to the integrator than a subsequent abort.
+	*/
+	abort(): void;
+	/**
+	* Outcome of the whole run — driven explicitly by the runner. Per-root sub-results carry their own
+	* `status` / `error`; consult {@link #results} for per-root outcomes.
+	*/
+	get status(): AIRunStatus;
+	set status(value: AIRunStatus);
+	/**
+	* The error that caused the whole run to fail. Undefined when the run completed successfully or was aborted.
+	*
+	* When the failure originated in the AI service backend, its structured response (for example, an `issues`
+	* list describing which fields failed validation) is available under `error.data.backendData`.
+	*/
+	get error(): Error | undefined;
+	set error(value: CKEditorError);
+	get results(): Array<SubResultType>;
+	/**
+	* Appends one or more per-root sub-results to the multi.
+	*/
+	addResult(...results: Array<SubResultType>): void;
+}

package/dist/aicore/model/airunsinglerootresult.d.ts

@@ -0,0 +1,104 @@
+/**
+* @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/aicore/model/airunsinglerootresult
+* @publicApi
+*/
+import { type Editor } from "@ckeditor/ckeditor5-core";
+import { type CKEditorError } from "@ckeditor/ckeditor5-utils";
+/**
+* The status of an AI run, reported by the {@link module:ai/aicore/model/airunsinglerootresult~AIRunSingleRootResult#status `status`}.
+*/
+export type AIRunStatus = "initialized" | "completed" | "aborted" | "error";
+/**
+* The shape of the data accepted by the {@link module:ai/aicore/model/airunsinglerootresult~AIRunSingleRootResult} constructor.
+*/
+export type AIRunSingleRootResultInput = {
+	/**
+	* The editor that is the source of content for the AI run.
+	*/
+	editor: Editor;
+	/**
+	* Name of the editor root the AI run targets.
+	*/
+	rootName: string;
+	/**
+	* Collaboration channel id captured at the start of the run.
+	*/
+	channelId?: string;
+	/**
+	* AI editing session id captured at the start of the run.
+	*/
+	sessionId: string;
+};
+/**
+* The result of an AI run.
+*/
+export declare class AIRunSingleRootResult {
+	constructor(data: AIRunSingleRootResultInput);
+	/**
+	* Outcome of the run. Anything other than `'completed'` means the run did not finish successfully — see {@link #error} for details.
+	*/
+	get status(): AIRunStatus;
+	/**
+	* The editor the AI run was performed against.
+	*/
+	get editor(): Editor;
+	/**
+	* Name of the editor root the AI run targeted.
+	*/
+	get rootName(): string;
+	/**
+	* Collaboration channel id captured at the start of the run.
+	*/
+	get channelId(): string | undefined;
+	/**
+	* AI editing session id captured at the start of the run.
+	*/
+	get sessionId(): string;
+	/**
+	* Document version captured when the run started. `undefined` until the run starts.
+	*/
+	get documentVersion(): number | undefined;
+	set documentVersion(value: number);
+	/**
+	* The pre-run document snapshot as captured at the time the run started, with `data-id` attributes preserved.
+	* `undefined` until the run starts.
+	*/
+	get contentRawOld(): string | undefined;
+	set contentRawOld(value: string);
+	/**
+	* The post-run document snapshot with all returned suggestions merged in, with `data-id` attributes preserved.
+	* Equals {@link #contentRawOld} when the run produced no suggestions. `undefined` until the run completes.
+	*/
+	get contentRawNew(): string | undefined;
+	set contentRawNew(value: string);
+	/**
+	* The {@link #contentRawOld} with `data-id` attributes stripped. Suitable for surfacing to end-users.
+	*/
+	get contentOld(): string;
+	/**
+	* The {@link #contentRawNew} with `data-id` attributes stripped. Suitable for surfacing to end-users.
+	*/
+	get contentNew(): string;
+	/**
+	* The error that caused the run to fail.
+	*
+	* When the failure originated in the AI service backend, its structured response (for example, an `issues`
+	* list describing which fields failed validation) is available under `error.data.backendData`.
+	*/
+	get error(): Error | undefined;
+	set error(value: CKEditorError | undefined);
+	/**
+	* Whether applying the result dropped the change because it would introduce block structure an inline root cannot
+	* accept. When `true`, the run completed but {@link module:ai/aicore/aigateway~AIGateway#apply} applied nothing.
+	*/
+	get droppedUnsupportedInlineChange(): boolean;
+	set droppedUnsupportedInlineChange(value: boolean);
+	/**
+	* Marks the run as aborted. Reflected via {@link #status}.
+	*/
+	abort(): void;
+}