@minecraft/creator-tools/lib/core/ErrorService.d.ts

Minecraft Creator Tools command line and libraries.

export declare enum ErrorKind {
    reactRender = "reactRender",
    windowError = "windowError",
    unhandledRejection = "unhandledRejection",
    electronMain = "electronMain"
}
export declare enum ErrorSeverity {
    /** Render-time error — the React subtree is broken; show full-screen overlay. */
    fatal = "fatal",
    /** UI is still functional — show a dismissible dialog. */
    recoverable = "recoverable"
}
export interface CapturedError {
    /** Unique id assigned by report(). */
    id: number;
    kind: ErrorKind;
    severity: ErrorSeverity;
    /** Short human-readable summary. */
    message: string;
    /** Full stack trace if available. */
    stack?: string;
    /** React component stack (only populated for reactRender errors). */
    componentStack?: string;
    /** Origin description (e.g. URL, file:line) when available. */
    source?: string;
    /** When the error was first observed by the service. */
    timestamp: Date;
    /**
     * Optional triage tag assigned by a categorizer. Used to bucket errors in
     * telemetry (e.g. "monaco-internal-known", "translation-extension-dom",
     * "browser-too-old") so we can filter dashboards without dropping signal.
     * Categorized errors still flow to telemetry — they're just easier to triage.
     */
    category?: string;
}
/** Predicate returning true to suppress an error (i.e. don't surface it to the user). */
export type ErrorFilter = (error: CapturedError) => boolean;
/**
 * Returns a category string to tag the error, or undefined to leave it untagged.
 * Categorizers run before filters; both the category and the captured error
 * still flow to telemetry. Use a categorizer when you want to bucket noise
 * for triage without losing signal — use addFilter only for truly pathological
 * cases that we cannot diagnose or fix (cross-origin "Script error.", DOM
 * mutations from translation extensions, etc.).
 */
export type ErrorCategorizer = (error: CapturedError) => string | undefined;
/**
 * Optional input to report(). The service fills in id and timestamp.
 */
export type ReportableError = Omit<CapturedError, "id" | "timestamp"> & {
    id?: number;
    timestamp?: Date;
};
declare class ErrorServiceImpl {
    private _nextId;
    private _errors;
    private _filters;
    private _categorizers;
    private _saveAllHandler?;
    private _isReporting;
    private _onErrorReported;
    private _onErrorsCleared;
    /** Fires whenever a new error makes it past the filters. */
    get onErrorReported(): import("ste-events").IEvent<ErrorServiceImpl, CapturedError>;
    /** Fires when dismissAll() is called. */
    get onErrorsCleared(): import("ste-events").IEvent<ErrorServiceImpl, void>;
    /** All errors captured this session, in arrival order (most recent last). */
    get errors(): readonly CapturedError[];
    /** Whether this host has any UI surface that could show the overlay. */
    get isUiHost(): boolean;
    /** Register a predicate that returns true to suppress matching errors. */
    addFilter(filter: ErrorFilter): void;
    /**
     * Register a categorizer that tags matching errors with a triage label.
     * Tagged errors still flow to telemetry; the category is forwarded as the
     * `errorCode` property so dashboards can group by it.
     */
    addCategorizer(categorizer: ErrorCategorizer): void;
    /** Register the function the overlay should call when the user clicks "Save all". */
    setSaveAllHandler(handler: (() => Promise<void>) | undefined): void;
    /** Whether a save handler is currently registered (used to enable/disable button). */
    get hasSaveAllHandler(): boolean;
    /**
     * Run the registered save-all handler. Always resolves; never throws into the caller.
     * Returns true on success, false on failure (with the error swallowed and logged).
     */
    runSaveAll(): Promise<boolean>;
    /**
     * Record an error and notify subscribers. Returns the captured error (with id +
     * timestamp filled in) or undefined if it was suppressed by a filter.
     */
    report(input: ReportableError): CapturedError | undefined;
    /** Remove a single error from the list. */
    dismiss(id: number): void;
    /** Clear every captured error. */
    dismissAll(): void;
    /**
     * Build a rich text payload suitable for the "Report this error" clipboard
     * action. Includes app version + host so issue reports are self-contained.
     */
    formatForReport(error: CapturedError): string;
    /**
     * Build a URL that opens a prefilled GitHub issue against the public Minecraft
     * Creator Tools repo. The body is composed as a Markdown report with
     * collapsed <details> sections for the long stack traces. The total URL is
     * truncated to a safe length (~7.5 KB) because most browsers and GitHub
     * itself cap query strings around 8 KB — if the report is longer, we trim the
     * stack and append a notice telling the user to paste the full report (which
     * the overlay copies to the clipboard at the same time) into the issue body.
     */
    buildGitHubIssueUrl(error: CapturedError): string;
}
declare const ErrorService: ErrorServiceImpl;
export default ErrorService;