import type { ZodError, ZodIssue } from "zod";
/**
 * Standard error codes used across microservices.
 */
export declare const ERROR_CODES: {
    readonly badRequest: "badRequest";
    readonly unauthorized: "unauthorized";
    readonly forbidden: "forbidden";
    readonly notFound: "notFound";
    readonly conflict: "conflict";
    readonly unprocessableEntity: "unprocessableEntity";
    readonly tooManyRequests: "tooManyRequests";
    readonly internal: "internal";
};
export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES] | (string & {});
declare const ERROR_METADATA: {
    readonly badRequest: {
        readonly status: 400;
        readonly title: "Invalid or malformed request";
    };
    readonly unauthorized: {
        readonly status: 401;
        readonly title: "Invalid or missing credentials";
    };
    readonly forbidden: {
        readonly status: 403;
        readonly title: "Access to resource denied";
    };
    readonly notFound: {
        readonly status: 404;
        readonly title: "Resource not found";
    };
    readonly conflict: {
        readonly status: 409;
        readonly title: "Conflict with server state";
    };
    readonly unprocessableEntity: {
        readonly status: 422;
        readonly title: "Request failed validation";
    };
    readonly tooManyRequests: {
        readonly status: 429;
        readonly title: "Request limit exceeded";
    };
    readonly internal: {
        readonly status: 500;
        readonly title: "Internal server error";
    };
};
type Status = (typeof ERROR_METADATA)[keyof typeof ERROR_METADATA]["status"];
export interface ServiceIssue {
    /**
     * - Use {@link ERROR_CODES}
     * – Or pass any custom string (e.g. "invalidPromoCode") for new cases
     */
    code?: ErrorCode;
    /** Details about what caused the issue */
    message?: string | undefined;
    /** Path to issue location */
    path?: Array<string | number>;
    /**
     * Short, reusable summary of the problem (`errors.title`).
     * Keep it concise and localizable (e.g. "Invalid Input").
     */
    title?: string;
    /**
     * HTTP status code (`errors.status` in JSON:API).
     */
    status?: Status;
}
export type ErrorSource = "header" | "parameter" | "pointer";
export type ServiceErrorParams = string | {
    /** Error cause */
    cause?: unknown;
    /** Unique identifier for the issue */
    id?: string;
    /** Array of issues contributing to the error */
    issues: readonly ServiceIssue[];
    /**
     * Source of the error
     *
     * @see {@link https://jsonapi.org/format/#error-objects}
     */
    source?: ErrorSource | undefined;
};
export interface Issue extends ServiceIssue {
    code: Required<ServiceIssue>["code"];
}
/**
 * Error class for service-level errors, convertible to JSON:API errors.
 */
export declare class ServiceError extends Error {
    /**
     * Converts an unknown value to a `ServiceError`. Typically called from `catch` blocks.
     *
     * @param value - The value to convert, which can be any type
     * @returns If the value is already a `ServiceError`, returns it unchanged. Otherwise, convert it
     *          to a `ServiceError`.
     */
    static fromUnknown<E extends ServiceError>(value: E): E;
    static fromUnknown(value: unknown): ServiceError;
    /**
     * Converts a ZodError to a `ServiceError`.
     *
     * @param error - A ZodError
     * @returns The converted `ServiceError`
     */
    static fromZodError(error: ZodError, options?: {
        source?: ErrorSource;
    }): ServiceError;
    /**
     * Merges multiple ServiceErrors into a single ServiceError.
     * Combines all issues from the input errors and uses the highest status code.
     *
     * @param error - The primary error
     * @param errors - Additional ServiceErrors
     * @returns New ServiceError containing all issues from input errors
     */
    static merge<E extends ServiceError>(error: E): E;
    static merge(error: ServiceError, additionalError: ServiceError, ...errors: readonly ServiceError[]): ServiceError;
    static merge(error: unknown, ...errors: readonly unknown[]): ServiceError;
    /**
     * Creates a ServiceError from a JSON:API error object
     * @see {@link https://jsonapi.org/format/#error-objects}
     * @param jsonApiError - JSON:API error object
     * @returns New ServiceError instance
     */
    static fromJsonApi(jsonApiError: {
        errors: Array<{
            id?: string;
            status?: `${Status}`;
            code?: ErrorCode;
            title?: string;
            detail?: string;
            source?: Record<string, string>;
        }>;
    }): ServiceError;
    readonly id: string;
    readonly issues: readonly Issue[];
    readonly status: Status;
    readonly source: ErrorSource;
    /**
     * Creates a new `ServiceError`
     * @param parameters - Issues contributing to the error or a message string
     */
    constructor(parameters: ServiceErrorParams);
    /**
     * Return string representation of the error for logging.
     */
    toString(): string;
    /**
     * Converts the error to JSON:API format
     * @see {@link https://jsonapi.org/format/#error-objects}
     * @returns Object conforming to JSON:API error format
     */
    toJsonApi(): {
        errors: {
            id: string;
            status: string;
            code: ErrorCode;
            title?: string;
            detail?: string;
            source?: {
                [x: string]: string;
            };
        }[];
    };
}
export declare function fromZodIssue(issue: ZodIssue): ServiceIssue;
export {};