zephyr-agent/dist/lib/errors/zephyr-error.d.ts

Zephyr plugin agent

import { type FindTemplates } from 'zephyr-edge-contract';
import { type ZeErrorCode, type ZeErrorCodes, type ZeErrorKeys, ZeErrors, type ZeErrorType } from './codes.js';
/** Options to construct {@linkcode ZephyrError}. */
export type ZephyrErrorOpts<T extends ZeErrorType> = {
    cause?: unknown;
    data?: Record<string, unknown>;
    operation?: ZephyrErrorOperation;
    reason?: ZeErrorCodes;
} & Record<FindTemplates<T['message']>, string | number | boolean>;
/** Stable initialization operations exposed to users and automated recovery tooling. */
export type ZephyrErrorOperation = 'resolve-git-metadata' | 'get-user-info' | 'get-application-config' | 'create-build-id';
export declare const docsUrl = "https://docs.zephyr-cloud.io/errors";
export declare const discordUrl = "https://zephyr-cloud.io/discord";
/**
 * ZephyrError is the base class for every error thrown by our builder plugins.
 *
 * Some messages have templates that mus be replaced with the `data` object. Use `{{
 * example }}` or `{{ example = value }}` to have a default value
 *
 * It's a subclass of Error, so it can be used in try/catch blocks.
 */
export declare class ZephyrError<K extends ZeErrorKeys, T extends (typeof ZeErrors)[K] = (typeof ZeErrors)[K]> extends Error {
    readonly code: ZeErrorCode<K>;
    /** Additional data to be used in the error message */
    data?: Record<string, unknown>;
    /** Data used when templating the message */
    readonly template?: Omit<ZephyrErrorOpts<T>, 'cause' | 'data' | 'operation' | 'reason'>;
    /** The deployment operation that failed. */
    operation?: ZephyrErrorOperation;
    /** The stable error code identifying the actionable failure reason. */
    reason: ZeErrorCodes;
    /**
     * Indicates the specific original cause of the error.
     *
     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
     */
    readonly cause?: unknown;
    /**
     * Returns {@linkcode cause} if it's a `ZephyrError`, otherwise creates a new
     * `ZephyrError` for the provided type.
     */
    constructor(type: T, opts?: ZephyrErrorOpts<T>);
    /** Checks if the given error is a ZephyrError and optionally matches the given code. */
    static is<K extends ZeErrorKeys>(err: unknown, codeOrType?: (typeof ZeErrors)[K]): err is ZephyrError<K>;
    /** Add stable operation context without replacing an existing public error code. */
    static withContext(error: unknown, operation: ZephyrErrorOperation): ZephyrError<ZeErrorKeys>;
    /** Formats a Zephyr error code. */
    static toZeCode<K extends ZeErrorKeys>({ id, kind }: (typeof ZeErrors)[K]): ZeErrorCode<K>;
    /**
     * Parses a Zephyr error code into a ZeErrorType.
     *
     * Returns {@linkcode ZeErrors.ERR_UNKNOWN} if the code could not be resolved.
     */
    static fromZeCode(code: ZeErrorCodes): ZeErrorType;
    static format(error: unknown): string;
    /** Return the same bounded, redacted representation used by persisted error logs. */
    toJSON(): unknown;
}
//# sourceMappingURL=zephyr-error.d.ts.map