billdogeng 1.0.0-beta.1

//! Error type for the BilldogEng SDK.

use std::fmt;

/// Error returned when an API request ultimately fails (after retries) or the
/// client is misconfigured.
#[derive(Debug, Clone)]
pub struct BilldogEngError {
    /// Human-readable message.
    pub message: String,
    /// HTTP status code, or `0` for network/timeout/config failures.
    pub status: u16,
    /// Machine-readable error code from the API envelope, if any.
    pub code: Option<String>,
    /// Raw response body (parsed if JSON, else text), if any.
    pub body: Option<serde_json::Value>,
}

impl BilldogEngError {
    /// Construct an error with a message and status.
    pub fn new(message: impl Into<String>, status: u16) -> Self {
        Self {
            message: message.into(),
            status,
            code: None,
            body: None,
        }
    }

    /// Attach a machine-readable code.
    pub fn with_code(mut self, code: Option<String>) -> Self {
        self.code = code;
        self
    }

    /// Attach a raw body.
    pub fn with_body(mut self, body: Option<serde_json::Value>) -> Self {
        self.body = body;
        self
    }

    /// Whether this error is safe to retry (transient).
    pub fn is_retryable(&self) -> bool {
        is_retryable_status(self.status)
    }
}

impl fmt::Display for BilldogEngError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "BilldogEngError(status={}): {}", self.status, self.message)
    }
}

impl std::error::Error for BilldogEngError {}

/// Status codes that are safe to retry (transient): network (0), 408, 429, 5xx.
pub fn is_retryable_status(status: u16) -> bool {
    status == 0 || status == 408 || status == 429 || (500..=599).contains(&status)
}

/// Convenience result alias.
pub type Result<T> = std::result::Result<T, BilldogEngError>;