/**
* @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/aierrorreporter
* @publicApi
*/
import { ContextPlugin } from "@ckeditor/ckeditor5-core";
import { type AICoreErrorSeverity, type AICoreErrorType } from "./errors/aicoreerror.js";
/**
* Payload of the {@link module:ai/aicore/aierrorreporter~AIErrorSinkErrorEvent} sink event.
*
* Error reporting services serialize only `name`, `message` and `stack` of an `Error`, so everything a
* reported {@link module:ai/aicore/errors/aicoreerror~AICoreError} carries as its own properties is
* flattened here. A subscriber can therefore classify and forward the failure without inspecting the
* error itself.
*/
export interface AIErrorSinkEventData {
	error: unknown;
	component: string;
	/**
	* {@link module:ai/aicore/errors/aicoreerror~AICoreError#code Code} of the reported error, for example
	* `'ai-chat-file-upload-failed'`. `undefined` for errors that are not an `AICoreError`.
	*/
	code?: string;
	/**
	* {@link module:ai/aicore/errors/aicoreerror~AICoreError#type Classification} of the reported error.
	* Use it to skip the failures that are not actionable telemetry: `'user'` (surfaced via UI) and
	* `'network'` (transient). `undefined` for errors that are not an `AICoreError`.
	*/
	type?: AICoreErrorType;
	/**
	* {@link module:ai/aicore/errors/aicoreerror~AICoreError#severity Severity} of the reported error.
	* `undefined` for errors that are not an `AICoreError`.
	*/
	severity?: AICoreErrorSeverity;
	/**
	* Metadata carried by the reported {@link module:ai/aicore/errors/aicoreerror~AICoreError#context error}
	* merged with the catch-site {@link module:ai/aicore/aierrorreporter~AIErrorReporterOptions#context context},
	* the latter winning on key conflicts. `undefined` when neither is present.
	*/
	context?: Record<string, unknown>;
}
/**
* Options accepted by {@link module:ai/aicore/aierrorreporter~AIErrorReporter} report calls.
*/
export interface AIErrorReporterOptions {
	/**
	* Catch-site context (operation labels, interaction/conversation IDs, etc.). Merged over the
	* context of the reported error.
	*/
	context?: Record<string, unknown>;
}
/**
* Event fired by {@link module:ai/aicore/aierrorreporter~AIErrorSink} whenever a non-abort AI
* error is reported.
*/
export interface AIErrorSinkErrorEvent {
	name: "error";
	args: [data: AIErrorSinkEventData];
}
/**
* Centralized event sink for AI-related errors. Thin event emitter — each feature creates its
* own {@link module:ai/aicore/aierrorreporter~AIErrorReporter} via
* {@link module:ai/aicore/aierrorreporter~AIErrorSink#createReporter} and routes failures
* through that.
*/
export declare class AIErrorSink extends ContextPlugin {
	static get pluginName(): "AIErrorSink";
	static override get isOfficialPlugin(): true;
	static override get isPremiumPlugin(): true;
	/**
	* Creates a per-feature {@link module:ai/aicore/aierrorreporter~AIErrorReporter} tagged
	* with the given `component`.
	*
	* ```ts
	* this._reporter = this.editor.plugins.get( AIErrorSink ).createReporter( 'aichat' );
	* this._reporter.logError( err );
	* ```
	*/
	createReporter(component: string): AIErrorReporter;
}
/**
* Per-feature reporter created via {@link
* module:ai/aicore/aierrorreporter~AIErrorSink#createReporter}.
*/
export declare class AIErrorReporter {
	/**
	* Created via {@link module:ai/aicore/aierrorreporter~AIErrorSink#createReporter}.
	*/
	constructor(sink: AIErrorSink, component: string);
	/**
	* Forwards the error to the sink and writes it to the console. Aborts are dropped.
	*/
	logError(error: unknown, options?: AIErrorReporterOptions): void;
	/**
	* Forwards the error to the sink without writing to the console. Aborts are dropped.
	*/
	reportError(error: unknown, options?: AIErrorReporterOptions): void;
}