@cavi-ai/api-client/core/errors

export declare class ApiClientError extends Error {
    readonly type: ApiClientErrorType | string;
    readonly code: ApiClientErrorCode | string;
    readonly runtime?: RuntimeErrorMetadata;
    constructor(message: string, options?: ApiClientErrorOptions);
}

export declare enum ApiClientErrorCode {
    Unknown = "unknown",
    ValidationFailed = "validation_failed",
    InvalidConfig = "invalid_config",
    InvalidJson = "invalid_json",
    HttpRequestFailed = "http_request_failed",
    GatewayError = "gateway_error",
    RequestFailed = "request_failed",
    Timeout = "timeout",
    Aborted = "aborted",
    SocketError = "socket_error",
    SocketClosed = "socket_closed",
    SocketUnavailable = "socket_unavailable",
    ConnectFailed = "connect_failed",
    BackendUnavailable = "backend_unavailable",
    EndpointNotFound = "endpoint_not_found",
    ProtocolMismatch = "protocol_mismatch",
    AuthRequired = "auth_required",
    AuthForbidden = "auth_forbidden",
    CapabilityUnavailable = "capability_unavailable",
    PermissionDenied = "permission_denied",
    InvalidRequest = "invalid_request",
    Conflict = "conflict",
    RateLimited = "rate_limited",
    TransportUnavailable = "transport_unavailable",
    TransportProtocolError = "transport_protocol_error",
    ServerOverloaded = "server_overloaded"
}

export type ApiClientErrorOptions = {
    type?: ApiClientErrorType | string;
    code?: ApiClientErrorCode | string;
    cause?: unknown;
    runtime?: RuntimeErrorMetadata;
};

export declare enum ApiClientErrorType {
    Unknown = "unknown",
    Validation = "validation",
    Configuration = "configuration",
    Http = "http",
    GatewayHttp = "gateway_http",
    GatewayRpc = "gateway_rpc",
    Transport = "transport",
    Timeout = "timeout",
    Abort = "abort",
    BackendUnavailable = "backend_unavailable",
    Auth = "auth"
}

export declare function getErrorCode(error: unknown): string | undefined;

export declare function getErrorMessage(error: unknown, fallbackMessage?: string): string;

/**
 * HTTP status carried by a typed transport error (`HttpApiError`,
 * `GatewayHttpError`, or any error exposing a numeric `status`). `undefined`
 * for non-HTTP failures (transport, abort, RPC) so callers branch on the value,
 * never on the message string.
 */
export declare function getErrorStatus(error: unknown): number | undefined;

export declare function getErrorType(error: unknown): string | undefined;

export declare function getRuntimeErrorMetadata(error: unknown): RuntimeErrorMetadata | undefined;

export declare function isAbortError(error: unknown): boolean;

/**
 * True when an error is an authentication/authorization failure (HTTP 401/403,
 * or a synthesized `Auth`-typed/`auth_required`/`auth_forbidden` error). Use
 * this to trigger token refresh or re-auth instead of inspecting `.status`
 * inline at every call site.
 */
export declare function isAuthError(error: unknown): boolean;

/**
 * True when an error is a synthesized `EndpointNotFound` failure — the
 * everyday cross-provider branch for a surface a provider declares
 * unsupported (Gemini `getRun`/`cancelRun`, OpenClaw wiki/media).
 */
export declare function isEndpointNotFoundError(error: unknown): boolean;

export type RuntimeErrorMetadata = {
    provider: string;
    transport: string;
    operation: string;
    retryable: boolean;
    retryAfterMs?: number;
    status?: number;
    providerCode?: string;
};

export type SerializedApiClientError = {
    name: string;
    message: string;
    type?: string;
    code?: string;
};

export declare function serializeError(error: unknown, fallbackMessage?: string): SerializedApiClientError;

export declare function stringifyUnknownError(error: unknown): string;

export declare function toError(error: unknown, fallbackMessage?: string): Error;