@ckeditor/ckeditor5-ai/src/aiassistant/adapters/aitextadapter.d.ts

AI features for CKEditor 5.

/**
 * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
 * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
 */
/**
 * @module ai/aiassistant/adapters/aitextadapter
 * @publicApi
 */
import { Plugin } from 'ckeditor5/src/core.js';
import { AIAdapter } from './aiadapter.js';
/**
 * Abstract base class for AI adapters that perform text-related requests.
 *
 * Concrete AI text adapter implementation plugin, after loaded by the editor, will set itself as
 * {@link module:ai/aiassistant/adapters/aiadapter~AIAdapter#textAdapter `AIAdapter#textAdapter`}.
 *
 * Then, features making text-related AI requests will use that concrete adapter through
 * {@link module:ai/aiassistant/adapters/aitextadapter~AITextAdapter#makeRequest `AIAdapter#textAdapter#makeRequest()`}.
 *
 * You can create your own adapter that may connect to any model by extending this abstract class.
 */
export declare abstract class AITextAdapter extends Plugin {
    /**
     * Abort controller instance.
     *
     * It is used by {@link ~AITextAdapter#abort `abort()`}.
     *
     * It should be passed to the mechanism that performs the request (e.g. `fetch()`).
     */
    abortController: AbortController;
    /**
     * @inheritDoc
     */
    static get requires(): readonly [typeof AIAdapter];
    /**
     * @inheritDoc
     */
    init(): void;
    /**
     * The method that stops the current request and then recreates the abort controller instance.
     *
     * It should be called when the currently processed request should be aborted (e.g. when the user closes the UI as the request is
     * processed).
     */
    abort(): void;
    /**
     * Makes the AI request to the AI API service and processes the response from the service.
     *
     * Internally, it uses {@link ~AITextAdapter#sendRequest `sendRequest()`}.
     *
     * If you are creating a custom adapter, implement `sendRequest()` rather than extending this method.
     *
     * Implements basic error handling for errors thrown by `sendRequest()`:
     *
     * * {@link module:ai/aiassistant/adapters/aiadapter~AIRequestError `AIRequestError`} is re-thrown, and it is expected
     * to be handled by the feature that made the request (e.g. by displaying some error notification).
     * * {@link module:utils/ckeditorerror~CKEditorError `CKEditorError`} is unexpected, is logged to the console, and re-thrown.
     * * `'AbortError'` is expected and is silenced. It is thrown when the request is aborted and does not need to be handled.
     *
     * @returns A Promise that resolves with the AI-generated response.
     */
    makeRequest(requestData: AITextAdapterRequestData): Promise<void>;
    /**
     * Abstract method.
     *
     * Creates the request using provided `requestData`. Makes the request to the AI service endpoint. Handles the AI service response.
     *
     * If you want to extend an existing adapter, you can overload this method to do some additional processing or make an external call.
     *
     * If you want to create a custom adapter, the main logic related to making and handling the request should be implemented here.
     * Make sure to properly implement {@link ~AITextAdapterRequestData#onData `onData()`} callback handling.
     */
    abstract sendRequest(requestData: AITextAdapterRequestData): Promise<void>;
}
export type AITextAdapterRequestData = {
    /**
     * The user's query.
     */
    query: string;
    /**
     * The context on which the query is used.
     *
     * May be empty. In such case, it is assumed that the user wanted to create new textual content.
     */
    context: string;
    /**
     * A callback that is called whenever the data received by the adapter is updated.
     *
     * If the adapter does not use streaming, and receives the whole answer at once, it should call `onData()` once, when the data is
     * received.
     *
     * If the adapter uses streaming, the adapter should internally build the whole received data and fire `onData()` callback with the
     * full update data each time. For example, if during streaming, the adapter receives following chunks: `'<p>T'`, `'his is an'`, and
     * `' example</p>'`, then it should fire `onData()` with: `'<p>T'`, `'<p>This is an'`, and `'<p>This is an example</p>'`.
     */
    onData: AITextAdapterDataCallback;
    /**
     * ID of the performed action. This is a unique ID for each feature and each action that triggers the AI request.
     *
     * The main role for `actionId` is to distinguish which feature made the call. The action ID can be used in extended and custom adapters
     * to customize the request.
     *
     * Each AI feature describes what action IDs it creates and uses. For example, the AI Assistant feature uses `actionId` values like
     * `'aiAssistant:custom'`, or `'aiAssistant:command:improveWriting'`.
     */
    actionId: string;
};
/**
 * Object with headers to set in the request to the AI service.
 *
 * If the provided value is an `object`, it is simply used as provided.
 *
 * If the provided value is a function, it should be a function that returns a `Promise` which resolves with the headers object.
 * This way, you can perform an authorization request to your application and receive the authorization token (and also implement
 * any custom logic on the back-end side). The headers object is then used to make the actual call to the AI service.
 *
 * The function is passed {@link module:ai/aiassistant/adapters/aitextadapter~AITextAdapterRequestData#actionId `actionId`}
 * parameter to make it possible to further customize the headers.
 *
 * If the function fails for any reason, the promise should be rejected. In this case, a feature that made the request should display
 * an error notification.
 */
export type AIRequestHeaders = Record<string, string> | ((actionId: string) => Promise<Record<string, string>>);
/**
 * Additional configuration parameters for the AI request. Use it to customize how the AI service generates responses.
 *
 * See the reference for the AI service of your choice to learn what parameters can be used with that service or model.
 *
 * If the provided value is an `object`, it is passed to the request as provided.
 *
 * If the provided value is a function, it should be a function that returns a `Promise` which resolves with the request parameters
 * object. This gives you more flexibility to provide parameters for the AI model.
 *
 * The function is passed {@link module:ai/aiassistant/adapters/aitextadapter~AITextAdapterRequestData#actionId `actionId`}
 * parameter to make it possible to further customize the parameters.
 *
 * If the function fails for any reason, the promise should be rejected. In this case, the feature that made the request should display
 * an error notification.
 */
export type AIRequestParameters = Record<string, any> | ((actionId: string) => Promise<Record<string, any>>);
/**
 * Callback called each time the AI text adapter receives data.
 *
 * @param content The received data.
 */
export type AITextAdapterDataCallback = (content: string) => any;