@ckeditor/ckeditor5-ai/dist/aicore/aiconnector.d.ts

AI features for CKEditor 5.

/**
 * @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
 */
import { type Editor, type Context, ContextPlugin } from '@ckeditor/ckeditor5-core';
import { CloudServices } from '@ckeditor/ckeditor5-cloud-services';
import { type AIContextItemRequestData, type AIContextItemType } from './model/aicontext.js';
import { type AICapabilitiesRequestData } from './model/aicapabilities.js';
import type { AIActionsNames } from '../aiactions/aiactions.js';
/**
 * A plugin that handles communication with the AI API.
 */
export declare class AIConnector extends ContextPlugin {
    /**
     * @inheritDoc
     */
    static get requires(): readonly [typeof CloudServices];
    /**
     * @inheritDoc
     */
    static get pluginName(): "AIConnector";
    /**
     * @inheritDoc
     */
    static get isOfficialPlugin(): true;
    /**
     * @inheritDoc
     */
    static get isPremiumPlugin(): true;
    constructor(context: Context | Editor);
    /**
     * @inheritDoc
     */
    init(): void;
    /**
     * Creates a new conversation session with the AI API.
     */
    startConversation(id: string, group: string): AIConversationStartRequest;
    /**
     * Sends a request to the AI API '/conversations/{conversationId}/messages' endpoint and returns a response stream reader.
     */
    queryAssistant({ message, conversationId, parts, capabilities, model, attributes }: AIConnectorQueryAssistantData): AIConnectorQueryAssistantRequest;
    /**
     * Sends a request to the /actions/custom/calls endpoint and returns a response stream reader.
     */
    executeCustomAction({ content, message, model, outputFormat }: AIConnectorExecuteCustomActionData): AIConnectorRequest;
    /**
     * Sends a request to the /actions/system/{actionName}/calls endpoint and returns a response stream reader.
     */
    executeAction({ actionName, content, args }: AIConnectorExecuteActionData): AIConnectorRequest;
    /**
     * Uploads a file to the AI API for a specific conversation.
     */
    uploadFile(conversationId: string, file: File, attributes?: {
        resourceId: string;
        label: string;
    }): AIUploadRequest;
    /**
     * Fetches a specific document by its ID from a conversation.
     */
    fetchDocument(conversationId: string, documentId: string): AIFetchDocumentRequest;
    /**
     * Gets a document from the AI API for a specific conversation.
     */
    uploadDocument(conversationId: string, content: string, attributes?: Record<string, unknown>): AIUploadRequest;
    /**
     * Uploads multiple documents to the AI API for a specific conversation in a single batch request.
     *
     * The endpoint returns an array of replies in the same order as the input documents.
     */
    uploadDocuments(conversationId: string, documents: Array<AIUploadDocumentData>): AIBatchUploadRequest;
    /**
     * Fetches multiple documents by their IDs from a conversation in a single batch request.
     */
    fetchDocuments(conversationId: string, documentIds: Array<string>): AIBatchFetchDocumentsRequest;
    /**
     * Fetches the list of conversations from the AI API.
     */
    fetchConversations(group: string, params?: AIFetchConversationsParams): AIFetchConversationsRequest;
    /**
     * Deletes a conversation by its ID.
     */
    deleteConversation(id: string): AIDeleteConversationRequest;
    /**
     * Updates the title and pinned status of a conversation by its ID.
     */
    updateConversation(id: string, updates: {
        title?: string;
        pinned?: boolean;
    }): AIUpdateConversationRequest;
    /**
     * Fetches a specific conversation by its ID.
     */
    fetchConversation(id: string): AIGetConversationRequest;
    /**
     * Fetches messages for a specific conversation by its ID.
     */
    fetchConversationMessages(conversationId: string): AIGetConversationMessagesRequest;
    /**
     * Uploads a URL to the AI API for a specific conversation.
     */
    uploadUrl(conversationId: string, url: string, attributes?: {
        resourceId: string;
        label: string;
    }): AIUploadRequest;
    /**
     * Returns a list of available AI models.
     *
     * @param language Language code (e.g., 'en', 'pl') to request localized model descriptions. Defaults to 'en'.
     */
    getModels(language?: string): AIModelRequest;
    /**
     * Deletes a file from a conversation.
     */
    deleteFile(conversationId: string, fileId: string): AIDeleteFileRequest;
    /**
     * Deletes a document from a conversation.
     */
    deleteDocument(conversationId: string, documentId: string): AIDeleteDocumentRequest;
    /**
     * Deletes a web resource from a conversation.
     */
    deleteWebResource(conversationId: string, webResourceId: string): AIDeleteWebResourceRequest;
    /**
     * Sends a request to the AI API '/reviews/system/{reviewName}/calls' endpoint and returns a response stream reader.
     */
    callSystemReview({ reviewName, content, args }: AIConnectorSystemReviewData): AIConnectorRequest;
    /**
     * Sends a request to the AI API '/reviews/custom/calls' endpoint and returns a response stream reader.
     */
    callCustomReview({ content, prompt, model }: AIConnectorCustomReviewData): AIConnectorRequest;
    upsertAIChatRating(conversationId: string, messageId: string, rating: AIRating): AIUpdateRating;
    upsertAIActionRating(actionName: string, callId: string, rating: AIRating): AIUpdateRating;
    upsertCustomAIActionRating(callId: string, rating: AIRating): AIUpdateRating;
    upsertAIReviewRating(reviewName: string, callId: string, rating: AIRating, dataId?: string): AIUpdateRating;
    upsertCustomAIReviewRating(callId: string, rating: AIRating, dataId?: string): AIUpdateRating;
}
export type AIGenericRequest = {
    request: Promise<Response>;
    abortController: AbortController;
};
export type AIConversationStartReply = {
    id: string;
};
export type AIConversationStartRequest = {
    getConversation: () => Promise<AIConversationStartReply>;
    abortController: AbortController;
};
export type AIMessageEventError = {
    event: 'error';
    data: Record<string, never>;
};
export type AIMessageEventMessageMetadata = {
    event: 'message-metadata';
    data: {
        messageId: string;
    };
};
export type AIMessageEventActionMetadata = {
    event: 'action-metadata';
    data: {
        callId: string;
    };
};
export type AIMessageEventConversationTitle = {
    event: 'conversation-title';
    data: {
        conversationTitle: string;
    };
};
export type AIMessageEventSource = {
    event: 'source';
    data: {
        source: AISource;
    };
};
export type AIMessageEventWebSearch = {
    event: 'web-search';
    data: Record<string, never>;
};
export type AIMessageEventReasoning = {
    event: 'reasoning';
    data: Record<string, never>;
};
export type AIMessageEventTextDelta = {
    event: 'text-delta';
    data: {
        textDelta: string;
    };
};
export type AIMessageEventModificationDelta = {
    event: 'modification-delta';
    data: {
        id: string;
        textDelta: string;
        documentId: string;
    };
};
export type AIMessageEventMcpToolNotification = {
    event: 'mcp-tool-notification';
    data: {
        toolName: string;
        data: Record<string, any>;
    };
};
export type AIMessageEventMcpToolResult = {
    event: 'mcp-tool-result';
    data: {
        toolName: string;
        result: string;
    };
};
export type AIMessageEventMcpToolResultData = {
    data?: Record<string, any>;
    attributes?: Record<string, any>;
};
export type AIMessageEvent = AIMessageEventError | AIMessageEventMessageMetadata | AIMessageEventActionMetadata | AIMessageEventConversationTitle | AIMessageEventSource | AIMessageEventWebSearch | AIMessageEventReasoning | AIMessageEventTextDelta | AIMessageEventModificationDelta | AIMessageEventMcpToolResult | AIMessageEventMcpToolNotification;
export type AIEventSourceMessageParsed = {
    event: string;
    id?: string;
    data: Record<string, any>;
};
export type AIConnectorReply = AsyncGenerator<AIEventSourceMessageParsed, void, undefined>;
export type AIConnectorRequest = {
    getStream: () => Promise<AIConnectorReply>;
    abortController: AbortController;
};
export type AIConnectorQueryAssistantReply = AsyncGenerator<AIMessageEvent, void, undefined>;
export type AIConnectorQueryAssistantRequest = {
    getStream: () => Promise<AIConnectorQueryAssistantReply>;
    abortController: AbortController;
};
export type AIConnectorQueryAssistantData = {
    message: string;
    conversationId: string;
    parts: Array<AIContextItemRequestData>;
    capabilities: AICapabilitiesRequestData | undefined;
    model: string;
    attributes?: Record<string, unknown>;
};
export type AIFetchDocumentReply = {
    id: string;
    content: string;
    attributes?: {
        version: number;
        sessionId: string | null;
        channelId?: string;
        rootName?: string;
    };
    name?: string;
    description?: string;
};
export type AIUploadDocumentData = {
    content: string | undefined;
    version: number;
    sessionId: string | null;
    channelId: string;
    rootName: string;
    selections: Array<{
        start: number;
        end: number;
        htmlFragment: string;
    }>;
    name?: string;
    description?: string;
};
export type AIBatchFetchDocumentsReply = Array<AIFetchDocumentReply>;
export type AIBatchFetchDocumentsRequest = {
    getDocuments: () => Promise<AIBatchFetchDocumentsReply>;
    abortController: AbortController;
};
export type AIFetchDocumentRequest = {
    getDocument: () => Promise<AIFetchDocumentReply>;
    abortController: AbortController;
};
export type AIUploadReply = {
    id: string;
};
export type AIUploadRequest = {
    getId: () => Promise<AIUploadReply>;
    abortController: AbortController;
};
export type AIBatchUploadReply = Array<{
    id: string;
}>;
export type AIBatchUploadRequest = {
    getIds: () => Promise<AIBatchUploadReply>;
    abortController: AbortController;
};
export type AIConversationItem = {
    id: string;
    title: string;
    createdAt: string;
    updatedAt?: string;
    pinned: boolean;
};
export type AIFetchConversationsParams = {
    limit?: number;
    sortBy?: 'createdAt' | 'updatedAt';
    order?: 'desc' | 'asc';
    excludeEmpty?: boolean;
};
export type AIFetchConversationsRequest = {
    getConversations: () => Promise<Array<AIConversationItem>>;
    abortController: AbortController;
};
export type AIUpdateConversationRequest = {
    getResult: () => Promise<{
        title?: string;
        pinned?: boolean;
    }>;
    abortController: AbortController;
};
export type AIDeleteConversationRequest = {
    execute: () => Promise<void>;
    abortController: AbortController;
};
export type AIUserMessage = {
    capabilities: Record<string, any>;
    content: Array<AIUserMessageContent>;
    prompt: string;
    model: string;
    id: string;
    role: 'user';
    attributes: Record<string, any>;
};
export type AIUserMessageContent = {
    id: string;
    type: AIContextItemType;
    content: string;
    mcpServerName: string;
    toolName?: string;
    data?: Record<string, any>;
    name?: string;
    url?: string;
    attributes?: {
        resourceId: string;
        label: string;
    };
};
/**
 * Represents a source used in AI responses (e.g., web search results).
 */
export type AISource = {
    type: 'url';
    id: string;
    url: string;
    title: string;
    favicon: string;
};
export type AIAssistantMessage = {
    content: Array<{
        id: string;
        type: 'text' | 'modification' | 'mcp-tool-result';
        content: string;
        toolName?: string;
    } | AISource>;
    id: string;
    role: 'assistant';
};
export type AIConversationMessage = AIUserMessage | AIAssistantMessage;
export type AIGetConversationReply = {
    id: string;
    model: string;
    title: string;
    pinned: boolean;
};
export type AIGetConversationRequest = {
    getConversation: () => Promise<AIGetConversationReply>;
    abortController: AbortController;
};
export type AIGetConversationMessagesRequest = {
    getMessages: () => Promise<Array<AIConversationMessage>>;
    abortController: AbortController;
};
export type AIModelData = {
    id: string;
    name: string;
    provider: string;
    description: string;
    recommended: boolean;
    capabilities: {
        webSearch: {
            enabled: boolean;
        };
        reasoning: {
            enabled: boolean;
        };
    };
};
export type AIModelRequest = {
    list: () => Promise<{
        items: Array<AIModelData>;
    }>;
    abortController: AbortController;
};
export type AIDeleteFileRequest = {
    execute: () => Promise<void>;
    abortController: AbortController;
};
export type AIDeleteDocumentRequest = {
    execute: () => Promise<void>;
    abortController: AbortController;
};
export type AIDeleteWebResourceRequest = {
    execute: () => Promise<void>;
    abortController: AbortController;
};
export type AIConnectorExecuteCustomActionData = {
    content: string;
    message: string;
    model: string;
    outputFormat: 'plainText' | 'html';
};
export type AIConnectorExecuteActionData = {
    actionName: AIActionsNames;
    content: string;
    args?: {
        language?: string;
    };
};
export type AIConnectorSystemReviewData = {
    reviewName: string;
    content: string;
    args?: {
        language?: string;
    };
};
export type AIConnectorCustomReviewData = {
    content: string;
    prompt: string;
    model: string;
};
export type AIUpdateRating = {
    execute: () => Promise<void>;
    abortController: AbortController;
};
export type AIRating = {
    positiveCount: number;
    totalCount: number;
    modificationId?: string;
};