scaleway-rs 0.2.7

//! Client library for the <https://www.scaleway.com/> API which
//! is documented at <https://www.scaleway.com/en/developers/api/>
//!
//! # Example blocking
//! It needs to have the feature "blocking" enabled.
//! ```toml
//! scaleway-rs = { version = "*", features = ["blocking"] }
//! ```
//! ```ignore
//! use scaleway_rs::ScalewayApi;
//! use scaleway_rs::ScalewayError;
//!
//! fn main() -> Result<(), ScalewayError> {
//!     let region = "fr-par-2";
//!     let api = ScalewayApi::new("<KEY>");
//!     
//!     let types = api.get_server_types(region)?;
//!     println!("SERVERTYPES: {:#?}", types);
//!     
//!     let images = api.list_images(region).run()?;
//!     println!("IMAGES: {:#?}", images);
//!     
//!     let instances = api.list_instances(region).order("creation_date_asc").run()?;
//!     println!("INSTANCES: {:#?}", instances);
//!     Ok(())
//! }
//! ```
//!
//! # Example async
//! ```toml
//! scaleway-rs = { version = "*" }
//! ```
//! ```no_run
//! use scaleway_rs::ScalewayApi;
//! use scaleway_rs::ScalewayError;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), ScalewayError> {
//!     let region = "fr-par-2";
//!     let api = ScalewayApi::new("<KEY>");
//!     
//!     let types = api.get_server_types_async(region).await?;
//!     println!("SERVERTYPES: {:#?}", types);
//!     
//!     let images = api.list_images(region).run_async().await?;
//!     println!("IMAGES: {:#?}", images);
//!     
//!     let instances = api
//!         .list_instances(region)
//!         .order("creation_date_asc")
//!         .run_async()
//!         .await?;
//!     println!("INSTANCES: {:#?}", instances);
//!     Ok(())
//! }
//! ```
//! ## Features
//! * "blocking" - enable blocking api
//! * "gzip" - enable gzip in reqwest
//! * "brotli" - enable brotli in reqwest
//! * "deflate" - enable deflate in reqwest

mod api_error;
mod builder;
mod data;
mod scaleway_error;

pub use api_error::{ScalewayApiError, ScalewayApiErrorDetails};
use builder::list_marketplace_image_versions_builder::ScalewayListMarketplaceImageVersionsBuilder;
use data::availability::ScalewayAvailabilityRoot;
use data::instance::ScalewayInstanceRoot;
use data::server_type::ScalewayServerTypeRoot;
use reqwest::header::CONTENT_TYPE;
use serde::Serialize;
use serde_json::json;
use std::collections::HashMap;

pub use builder::{
    add_dns_record_builder::ScalewayAddDnsRecordBuilder,
    create_flexible_ip_builder::ScalewayCreateFlexibleIpBuilder,
    create_instance_builder::ScalewayCreateInstanceBuilder,
    create_project_builder::ScalewayCreateProjectBuilder,
    create_security_group_builder::ScalewayCreateSecurityGroupBuilder,
    create_security_group_rule_builder::ScalewayCreateSecurityGroupRuleBuilder,
    create_ssh_key_builder::ScalewayCreateSSHKeyBuilder,
    create_volume_builder::ScalewayCreateVolumeBuilder,
    list_volumes_builder::ScalewayListVolumesBuilder,
    get_project_builder::ScalewayGetProjectBuilder,
    get_security_group_builder::ScalewayGetSecurityGroupBuilder,
    get_security_group_rule_builder::ScalewayGetSecurityGroupRuleBuilder,
    get_ssh_key_builder::ScalewayGetSSHKeyBuilder,
    list_dns_zones_builder::ScalewayListDnsZonesBuilder,
    list_flexible_ips_builder::ScalewayListFlexibleIpsBuilder,
    list_instance_builder::ScalewayListInstanceBuilder,
    list_instance_images_builder::ScalewayListInstanceImagesBuilder,
    list_marketplace_images_builder::ScalewayListMarketplaceImagesBuilder,
    list_marketplace_local_images_builder::LocalImageListType,
    list_marketplace_local_images_builder::ScalewayListMarketplaceLocalImagesBuilder,
    list_projects_builder::ScalewayListProjectsBuilder,
    list_security_group_rules_builder::ScalewayListSecurityGroupRulesBuilder,
    list_security_groups_builder::ScalewayListSecurityGroupsBuilder,
    list_ssh_keys_builder::ScalewayListSSHKeysBuilder,
    update_dns_record_builder::ScalewayUpdateDnsRecordBuilder,
    update_flexible_ip_builder::ScalewayUpdateFlexibleIpBuilder,
    update_volume_builder::ScalewayUpdateVolumeBuilder,
};
pub use data::dns_record::{DnsRecordType, ScalewayDnsRecord};
pub use data::dns_zone::{DnsZoneOrderBy, DnsZoneStatus, ScalewayDnsZone};
pub use data::architecture::ScalewayArchitecture;
pub use data::flexible_ip::{FlexibleIpType, ScalewayFlexibleIp, ScalewayFlexibleIpServerRef};
pub use data::image::{
    ScalewayImage, ScalewayImageBootscript, ScalewayImageExtraVolume,
    ScalewayImageExtraVolumeServer, ScalewayImageExtraVolumes, ScalewayImageRootVolume,
};
pub use data::instance::{
    BootType, InstanceAction, InstanceOrderBy, ScalewayInstance, ScalewayInstanceLocation,
    ScalewayIpv6, ScalewayMaintenance, ScalewayPlacementGroup, ScalewayPrivateNic,
    ScalewayPublicIP, ScalewaySecurityGroup,
};
pub use data::marketplace_image::{MarketplaceImageOrderBy, ScalewayMarketplaceImage};
pub use data::marketplace_image_version::MarketplaceImageVersionOrderBy;
pub use data::marketplace_local_image::{LocalImageType, MarketplaceLocalImageOrderBy};
pub use data::security_group::{
    ScalewaySecurityGroupDetails, ScalewaySecurityGroupRule, SecurityGroupPolicy,
    SecurityGroupRuleAction, SecurityGroupRuleDirection, SecurityGroupRuleProtocol,
};
pub use data::project::{ProjectOrderBy, ScalewayProject};
pub use data::server_type::ServerType;
pub use data::api_key::ScalewayApiKey;
pub use data::application::ScalewayApplication;
pub use data::user::ScalewayUser;
pub use data::ssh_key::{ScalewaySSHKey, SshKeyOrderBy};
pub use data::user_data::ScalewayUserData;
pub use data::user_data::ScalewayUserDataKeyList;
pub use data::volume::{ScalewayVolume, ScalewayVolumeServerRef};
pub use data::volume_type::{
    ScalewayVolumeType, ScalewayVolumeTypeCapabilities, ScalewayVolumeTypeConstraints,
};
pub use data::zone::Zone;
pub use scaleway_error::ScalewayError;

/// Scaleway API client.
///
/// Wraps the Scaleway HTTP API and exposes typed methods for managing instances,
/// volumes, DNS, SSH keys, projects, flexible IPs, and more.
///
/// Every operation has an async variant (no feature flag required) and an optional
/// blocking variant behind the `"blocking"` Cargo feature.
///
/// # Authentication
///
/// Generate a secret key in the [Scaleway console](https://console.scaleway.com/iam/api-keys)
/// and pass it to [`ScalewayApi::new`]. The key looks like
/// `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
///
/// # Example
///
/// ```no_run
/// use scaleway_rs::ScalewayApi;
///
/// let api = ScalewayApi::new("my-secret-key");
/// ```
#[derive(Clone)]
pub struct ScalewayApi {
    secret_key: String,
}

impl<'a> ScalewayApi {
    /// Creates a new [`ScalewayApi`] client authenticated with `secret_key`.
    ///
    /// The secret key is shown once when created via the IAM console or API.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-iam-secret-key");
    /// ```
    pub fn new<S>(secret_key: S) -> ScalewayApi
    where
        S: Into<String>,
    {
        ScalewayApi {
            secret_key: secret_key.into(),
        }
    }

    async fn get_async(
        &self,
        url: &str,
        query: Vec<(&'static str, String)>,
    ) -> Result<reqwest::Response, ScalewayError> {
        let client = reqwest::Client::new();
        let resp = client
            .get(url)
            .header("X-Auth-Token", &self.secret_key)
            .query(&query)
            .send()
            .await
            .map_err(|e| ScalewayError::Reqwest(e))?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json().await?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    #[cfg(feature = "blocking")]
    fn get(
        &self,
        url: &str,
        query: Vec<(&'static str, String)>,
    ) -> Result<reqwest::blocking::Response, ScalewayError> {
        let client = reqwest::blocking::Client::new();
        let resp = client
            .get(url)
            .header("X-Auth-Token", &self.secret_key)
            .query(&query)
            .send()?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json()?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    async fn post_async<T>(&self, url: &str, json: T) -> Result<reqwest::Response, ScalewayError>
    where
        T: Serialize + Sized,
    {
        let client = reqwest::Client::new();
        let resp = client
            .post(url)
            .header("X-Auth-Token", &self.secret_key)
            .json(&json)
            .send()
            .await?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json().await?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    #[cfg(feature = "blocking")]
    fn post<T>(&self, url: &str, json: T) -> Result<reqwest::blocking::Response, ScalewayError>
    where
        T: Serialize + Sized,
    {
        let client = reqwest::blocking::Client::new();
        let resp = client
            .post(url)
            .header("X-Auth-Token", &self.secret_key)
            .json(&json)
            .send()?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json()?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    async fn patch_async(
        &self,
        url: &str,
        content: &str,
    ) -> Result<reqwest::Response, ScalewayError> {
        let client = reqwest::Client::new();
        let resp = client
            .patch(url)
            .header(CONTENT_TYPE, "text/plain")
            .header("X-Auth-Token", &self.secret_key)
            .body(content.to_string())
            .send()
            .await?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json().await?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    #[cfg(feature = "blocking")]
    fn patch(
        &self,
        url: &str,
        content: &str,
    ) -> Result<reqwest::blocking::Response, ScalewayError> {
        let client = reqwest::blocking::Client::new();
        let resp = client
            .patch(url)
            .header(CONTENT_TYPE, "text/plain")
            .header("X-Auth-Token", &self.secret_key)
            .body(content.to_string())
            .send()?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json()?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    async fn patch_json_async<T>(
        &self,
        url: &str,
        json: T,
    ) -> Result<reqwest::Response, ScalewayError>
    where
        T: Serialize + Sized,
    {
        let client = reqwest::Client::new();
        let resp = client
            .patch(url)
            .header("X-Auth-Token", &self.secret_key)
            .json(&json)
            .send()
            .await?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json().await?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    #[cfg(feature = "blocking")]
    fn patch_json<T>(
        &self,
        url: &str,
        json: T,
    ) -> Result<reqwest::blocking::Response, ScalewayError>
    where
        T: Serialize + Sized,
    {
        let client = reqwest::blocking::Client::new();
        let resp = client
            .patch(url)
            .header("X-Auth-Token", &self.secret_key)
            .json(&json)
            .send()?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json()?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    async fn delete_async(&self, url: &str) -> Result<reqwest::Response, ScalewayError> {
        let client = reqwest::Client::new();
        let resp = client
            .delete(url)
            .header("X-Auth-Token", &self.secret_key)
            .send()
            .await?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json().await?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    #[cfg(feature = "blocking")]
    fn delete(&self, url: &str) -> Result<reqwest::blocking::Response, ScalewayError> {
        let client = reqwest::blocking::Client::new();
        let resp = client
            .delete(url)
            .header("X-Auth-Token", &self.secret_key)
            .send()?;
        let status = resp.status();
        if status.is_client_error() {
            let result: ScalewayApiError = resp.json()?;
            Err(ScalewayError::Api(result))
        } else {
            Ok(resp.error_for_status()?)
        }
    }

    /// Returns all availability zones as typed [`Zone`] values.
    ///
    /// Pass any returned zone directly to zone-scoped API calls such as
    /// [`list_instances`](Self::list_instances) or [`create_instance`](Self::create_instance).
    ///
    /// To iterate all zones without collecting, use [`Zone::iter`].
    ///
    /// # Example
    ///
    /// ```
    /// use scaleway_rs::ScalewayApi;
    /// let zones = ScalewayApi::az_list();
    /// assert_eq!(zones.len(), 10);
    /// ```
    pub fn az_list() -> Vec<Zone> {
        Zone::iter().collect()
    }

    /// Returns all commercial server types available in `zone` (blocking).
    ///
    /// See [`get_server_types_async`](Self::get_server_types_async) for the async version
    /// and full documentation.
    #[cfg(feature = "blocking")]
    pub fn get_server_types(&self, zone: impl AsRef<str>) -> Result<Vec<ServerType>, ScalewayError> {
        let zone = zone.as_ref();
        let types: Vec<ServerType> = self
            .get(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/products/servers",
                    zone = zone
                ),
                vec![],
            )?
            .json::<ScalewayServerTypeRoot>()?
            .servers
            .servers
            .into_iter()
            .map(|(id, item)| ServerType {
                id,
                location: zone.to_string(),
                alt_names: item.alt_names,
                arch: item.arch,
                ncpus: item.ncpus,
                ram: item.ram,
                gpu: item.gpu,
                monthly_price: item.monthly_price,
                hourly_price: item.hourly_price,
                network: item.network,
            })
            .collect();
        Ok(types)
    }

    /// Returns all commercial server types available in `zone`.
    ///
    /// Each [`ServerType`] includes the type identifier (e.g. `"DEV1-S"`, `"GP1-XS"`),
    /// CPU count, RAM, GPU count, hourly/monthly pricing, and network specs.
    /// Pass the `id` field as `commercial_type` when calling
    /// [`create_instance`](Self::create_instance).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let types = api.get_server_types_async("fr-par-1").await?;
    /// for t in &types {
    ///     println!("{}: {} CPUs, {} MB RAM", t.id, t.ncpus, t.ram / 1_000_000);
    /// }
    /// # Ok(()) }
    /// ```
    pub async fn get_server_types_async(
        &self,
        zone: impl AsRef<str>,
    ) -> Result<Vec<ServerType>, ScalewayError> {
        let zone = zone.as_ref();
        let types: Vec<ServerType> = self
            .get_async(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/products/servers",
                    zone = zone
                ),
                vec![],
            )
            .await?
            .json::<ScalewayServerTypeRoot>()
            .await?
            .servers
            .servers
            .into_iter()
            .map(|(id, item)| ServerType {
                id,
                location: zone.to_string(),
                alt_names: item.alt_names,
                arch: item.arch,
                ncpus: item.ncpus,
                ram: item.ram,
                gpu: item.gpu,
                monthly_price: item.monthly_price,
                hourly_price: item.hourly_price,
                network: item.network,
            })
            .collect();
        Ok(types)
    }

    /// Returns a builder for listing instance images (snapshots/OS images) in `zone`.
    ///
    /// Call `.run()` (blocking) or `.run_async().await` on the returned builder to execute.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let images = api.list_images("fr-par-1").public(true).run_async().await?;
    /// for img in &images {
    ///     println!("{}: {}", img.id, img.name);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn list_images(&self, zone: impl AsRef<str>) -> ScalewayListInstanceImagesBuilder {
        ScalewayListInstanceImagesBuilder::new(self.clone(), zone.as_ref())
    }

    /// Returns a builder for listing instances (servers) in `zone`.
    ///
    /// Call `.run()` (blocking) or `.run_async().await` on the returned builder to execute.
    /// The builder auto-paginates and returns all matching instances.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let instances = api
    ///     .list_instances("fr-par-1")
    ///     .order("creation_date_asc")
    ///     .run_async()
    ///     .await?;
    /// for inst in &instances {
    ///     println!("{}: {}", inst.id, inst.name);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn list_instances(&self, zone: impl AsRef<str>) -> ScalewayListInstanceBuilder {
        ScalewayListInstanceBuilder::new(self.clone(), zone.as_ref())
    }

    /// Returns a builder for listing Marketplace images (public OS images).
    ///
    /// These are the official images available in the Scaleway marketplace (e.g. Ubuntu, Debian).
    /// Call `.run()` (blocking) or `.run_async().await` to fetch all pages.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let images = api.list_marketplace_instances().run_async().await?;
    /// for img in &images {
    ///     println!("{}: {}", img.id, img.name);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn list_marketplace_instances(&self) -> ScalewayListMarketplaceImagesBuilder {
        ScalewayListMarketplaceImagesBuilder::new(self.clone())
    }

    /// Returns a builder for listing available versions of a Marketplace image.
    ///
    /// `image_id` is the UUID of the Marketplace image (obtained via
    /// [`list_marketplace_instances`](Self::list_marketplace_instances)).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let versions = api
    ///     .list_marketplace_instance_versions("ff17d35e-2b69-4ba5-b3a9-d9a9cab12345")
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn list_marketplace_instance_versions(
        &self,
        image_id: &str,
    ) -> ScalewayListMarketplaceImageVersionsBuilder {
        ScalewayListMarketplaceImageVersionsBuilder::new(self.clone(), image_id)
    }

    /// Returns a builder for listing local (zone-specific) images derived from a Marketplace image.
    ///
    /// Use [`LocalImageListType`] to select whether to filter by image ID, image label, or version ID.
    /// Local images provide the zone-specific AMI-like IDs needed when creating an instance.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::{ScalewayApi, LocalImageListType};
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let local_images = api
    ///     .list_marketplace_local_images(LocalImageListType::ByImageLabel("ubuntu_noble".to_string()))
    ///     .zone("fr-par-1")
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn list_marketplace_local_images(
        &self,
        list_type: LocalImageListType,
    ) -> ScalewayListMarketplaceLocalImagesBuilder {
        ScalewayListMarketplaceLocalImagesBuilder::new(self.clone(), list_type)
    }

    /// Returns a builder for creating a new instance (server) in `zone`.
    ///
    /// - `name`: display name for the instance
    /// - `commercial_type`: server type ID (e.g. `"DEV1-S"`, `"GP1-XS"`); obtain valid
    ///   values from [`get_server_types_async`](Self::get_server_types_async)
    ///
    /// Use the builder methods to set optional fields (image, project, security group, tags, etc.),
    /// then call `.run()` or `.run_async().await` to create the instance.
    ///
    /// **Note:** Creating an instance does not start it. Use
    /// [`perform_instance_action_async`](Self::perform_instance_action_async) with [`InstanceAction::Poweron`].
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let instance = api
    ///     .create_instance("fr-par-1", "my-server", "DEV1-S")
    ///     .image("ubuntu_noble")
    ///     .tags(vec!["env:prod".to_string()])
    ///     .run_async()
    ///     .await?;
    /// println!("Created instance: {}", instance.id);
    /// # Ok(()) }
    /// ```
    pub fn create_instance(
        &self,
        zone: impl AsRef<str>,
        name: &str,
        commercial_type: &str,
    ) -> ScalewayCreateInstanceBuilder {
        ScalewayCreateInstanceBuilder::new(self.clone(), zone.as_ref(), name, commercial_type)
    }

    /// Fetches a single instance by ID (blocking).
    ///
    /// See [`get_instance_async`](Self::get_instance_async) for the async version and full docs.
    #[cfg(feature = "blocking")]
    pub fn get_instance(
        &self,
        zone: impl AsRef<str>,
        server_id: &str,
    ) -> Result<ScalewayInstance, ScalewayError> {
        let zone = zone.as_ref();
        Ok(self
            .get(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}",
                    zone = zone,
                    server_id = server_id
                ),
                vec![],
            )?
            .json::<ScalewayInstanceRoot>()?
            .server)
    }

    /// Fetches a single instance by ID.
    ///
    /// Returns the full [`ScalewayInstance`] with current state, IP addresses, volumes, etc.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let inst = api.get_instance_async("fr-par-1", "abc12345-...").await?;
    /// println!("State: {}", inst.state);
    /// # Ok(()) }
    /// ```
    pub async fn get_instance_async(
        &self,
        zone: impl AsRef<str>,
        server_id: &str,
    ) -> Result<ScalewayInstance, ScalewayError> {
        let zone = zone.as_ref();
        Ok(self
            .get_async(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}",
                    zone = zone,
                    server_id = server_id
                ),
                vec![],
            )
            .await?
            .json::<ScalewayInstanceRoot>()
            .await?
            .server)
    }

    /// Deletes an instance (blocking). See [`delete_instance_async`](Self::delete_instance_async).
    #[cfg(feature = "blocking")]
    pub fn delete_instance(&self, zone: impl AsRef<str>, server_id: &str) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}",
            zone = zone,
            server_id = server_id
        ))?
        .error_for_status()?;
        Ok(())
    }

    /// Permanently deletes an instance.
    ///
    /// The instance must be stopped (`"stopped"` state) before deletion. Attached volumes are
    /// **not** deleted automatically; delete them separately with
    /// [`delete_volume_async`](Self::delete_volume_async).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_instance_async("fr-par-1", "abc12345-...").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_instance_async(
        &self,
        zone: impl AsRef<str>,
        server_id: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete_async(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}",
            zone = zone,
            server_id = server_id
        ))
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Performs a lifecycle action on an instance (blocking).
    ///
    /// See [`perform_instance_action_async`](Self::perform_instance_action_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn perform_instance_action(
        &self,
        zone: impl AsRef<str>,
        server_id: &str,
        action: InstanceAction,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.post(
            &format!(
                "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/action",
                zone = zone,
                server_id = server_id
            ),
            json!({"action": action}),
        )?
        .error_for_status()?;
        Ok(())
    }

    /// Performs a lifecycle action on an instance.
    ///
    /// # Actions
    ///
    /// | Variant | Description |
    /// |---------|-------------|
    /// | [`Poweron`](InstanceAction::Poweron) | Start a stopped instance |
    /// | [`Poweroff`](InstanceAction::Poweroff) | Fully stop and release the hypervisor slot |
    /// | [`StopInPlace`](InstanceAction::StopInPlace) | Soft stop, keeps the hypervisor slot and IP |
    /// | [`Reboot`](InstanceAction::Reboot) | Stop then restart |
    /// | [`Backup`](InstanceAction::Backup) | Snapshot all volumes into a new image |
    /// | [`Terminate`](InstanceAction::Terminate) | Delete the instance and its local volumes |
    /// | [`EnableRoutedIp`](InstanceAction::EnableRoutedIp) | Migrate to the routed-IP network stack |
    ///
    /// > **Note:** `Terminate` deletes `l_ssd` and scratch volumes but only detaches `sbs_volume` volumes.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::{ScalewayApi, InstanceAction};
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.perform_instance_action_async("fr-par-1", "abc12345-...", InstanceAction::Poweron).await?;
    /// # Ok(()) }
    /// ```
    pub async fn perform_instance_action_async(
        &self,
        zone: impl AsRef<str>,
        server_id: &str,
        action: InstanceAction,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.post_async(
            &format!(
                "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/action",
                zone = zone,
                server_id = server_id
            ),
            json!({"action": action}),
        )
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Returns server-type availability in `zone` (blocking).
    ///
    /// See [`list_availability_async`](Self::list_availability_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn list_availability(&self, zone: impl AsRef<str>) -> Result<HashMap<String, bool>, ScalewayError> {
        let zone = zone.as_ref();
        let servers = self
            .get(
                &format!(
                "https://api.scaleway.com/instance/v1/zones/{zone}/products/servers/availability",
                zone = zone
            ),
                vec![],
            )?
            .json::<ScalewayAvailabilityRoot>()?
            .servers
            .servers
            .into_iter()
            .map(|(id, available)| (id, available.availability == "available"))
            .collect();
        Ok(servers)
    }

    /// Returns the real-time availability of each server type in `zone`.
    ///
    /// The returned map is keyed by commercial type (e.g. `"DEV1-S"`) and the value is
    /// `true` when instances of that type can be created right now.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let avail = api.list_availability_async("fr-par-1").await?;
    /// for (kind, available) in &avail {
    ///     if *available {
    ///         println!("{} is available", kind);
    ///     }
    /// }
    /// # Ok(()) }
    /// ```
    pub async fn list_availability_async(
        &self,
        zone: impl AsRef<str>,
    ) -> Result<HashMap<String, bool>, ScalewayError> {
        let zone = zone.as_ref();
        let servers = self
            .get_async(
                &format!(
                "https://api.scaleway.com/instance/v1/zones/{zone}/products/servers/availability",
                zone = zone
            ),
                vec![],
            )
            .await?
            .json::<ScalewayAvailabilityRoot>()
            .await?
            .servers
            .servers
            .into_iter()
            .map(|(id, available)| (id, available.availability == "available"))
            .collect();
        Ok(servers)
    }

    /// Lists user-data keys set on an instance (blocking).
    ///
    /// See [`list_userdata_keys_async`](Self::list_userdata_keys_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn list_userdata_keys(
        &self,
        zone: impl AsRef<str>,
        machine_id: &str,
    ) -> Result<Vec<String>, ScalewayError> {
        let zone = zone.as_ref();
        let user_data = self
            .get(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/user_data",
                    zone = zone,
                    server_id = machine_id,
            ),
                vec![],
            )?
            .json::<ScalewayUserDataKeyList>()?
            .user_data;
        Ok(user_data)
    }

    /// Lists all user-data keys set on an instance.
    ///
    /// User data is arbitrary key/value metadata attached to an instance that can be read
    /// from within the instance via the metadata API. Retrieve the value for a key with
    /// [`get_userdata_async`](Self::get_userdata_async).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let keys = api.list_userdata_keys_async("fr-par-1", "abc12345-...").await?;
    /// println!("{:?}", keys); // e.g. ["cloud-init", "my-key"]
    /// # Ok(()) }
    /// ```
    pub async fn list_userdata_keys_async(
        &self,
        zone: impl AsRef<str>,
        machine_id: &str,
    ) -> Result<Vec<String>, ScalewayError> {
        let zone = zone.as_ref();
        let user_data = self
            .get_async(
                &format!(
                "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/user_data",
                zone = zone,
                server_id = machine_id,
            ),
                vec![],
            )
            .await?
            .json::<ScalewayUserDataKeyList>()
            .await?
            .user_data;
        Ok(user_data)
    }

    /// Retrieves the value of a single user-data key on an instance (blocking).
    ///
    /// See [`get_userdata_async`](Self::get_userdata_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn get_userdata(
        &self,
        zone: impl AsRef<str>,
        machine_id: &str,
        key: &str,
    ) -> Result<ScalewayUserData, ScalewayError> {
        let zone = zone.as_ref();
        let servers = self
            .get(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}",
                    zone = zone,
                    server_id = machine_id,
                    key = key,
            ),
                vec![],
            )?
            .json::<ScalewayUserData>()?;
        Ok(servers)
    }

    /// Retrieves the value of a single user-data key on an instance.
    ///
    /// Use [`list_userdata_keys_async`](Self::list_userdata_keys_async) to discover available keys.
    /// Set values with [`set_userdata_async`](Self::set_userdata_async).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let data = api.get_userdata_async("fr-par-1", "abc12345-...", "cloud-init").await?;
    /// # Ok(()) }
    /// ```
    pub async fn get_userdata_async(
        &self,
        zone: impl AsRef<str>,
        machine_id: &str,
        key: &str,
    ) -> Result<ScalewayUserData, ScalewayError> {
        let zone = zone.as_ref();
        let user_data = self
            .get_async(
                &format!(
                "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}",
                zone = zone,
                server_id = machine_id,
                key = key,
            ),
                vec![],
            )
            .await?
            .json::<ScalewayUserData>()
            .await?;
        Ok(user_data)
    }

    /// Sets a user-data key on an instance (blocking).
    ///
    /// See [`set_userdata_async`](Self::set_userdata_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn set_userdata(
        &self,
        zone: impl AsRef<str>,
        machine_id: &str,
        key: &str,
        value: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self
            .patch(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}",
                    zone = zone,
                    server_id = machine_id,
                    key = key,
            ), value)?
            .error_for_status()?;
        Ok(())
    }

    /// Sets (creates or overwrites) a user-data key on an instance.
    ///
    /// User data values are plain text. The `cloud-init` key is special — its value is
    /// executed as a cloud-init script on first boot.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.set_userdata_async("fr-par-1", "abc12345-...", "env", "production").await?;
    /// # Ok(()) }
    /// ```
    pub async fn set_userdata_async(
        &self,
        zone: impl AsRef<str>,
        machine_id: &str,
        key: &str,
        value: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self
            .patch_async(
                &format!(
                "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}",
                zone = zone,
                server_id = machine_id,
                key = key,
            ), value)
            .await?.error_for_status()?;
        Ok(())
    }

    /// Deletes a user-data key from an instance (blocking).
    ///
    /// See [`delete_userdata_async`](Self::delete_userdata_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn delete_userdata(
        &self,
        zone: impl AsRef<str>,
        machine_id: &str,
        key: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}",
            zone = zone,
            server_id = machine_id,
            key = key,
        ))?
        .error_for_status()?;
        Ok(())
    }

    /// Deletes a user-data key from an instance.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_userdata_async("fr-par-1", "abc12345-...", "env").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_userdata_async(
        &self,
        zone: impl AsRef<str>,
        machine_id: &str,
        key: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete_async(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/servers/{server_id}/user_data/{key}",
            zone = zone,
            server_id = machine_id,
            key = key,
        ))
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Returns the volume types available in the given zone.
    ///
    /// Volume type availability varies by zone. Use the `id` field of each returned
    /// [`ScalewayVolumeType`] as the `volume_type` argument to [`create_volume`](Self::create_volume).
    #[cfg(feature = "blocking")]
    pub fn list_volume_types(&self, zone: impl AsRef<str>) -> Result<Vec<ScalewayVolumeType>, ScalewayError> {
        let zone = zone.as_ref();
        use data::volume_type::ScalewayVolumeTypeRoot;
        let types = self
            .get(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/products/volumes",
                    zone = zone
                ),
                vec![],
            )?
            .json::<ScalewayVolumeTypeRoot>()?
            .volumes
            .into_iter()
            .map(|(id, item)| ScalewayVolumeType {
                id,
                display_name: item.display_name,
                capabilities: item.capabilities,
                constraints: item.constraints,
            })
            .collect();
        Ok(types)
    }

    /// Returns the volume types available in the given zone.
    ///
    /// Volume type availability varies by zone. Use the `id` field of each returned
    /// [`ScalewayVolumeType`] as the `volume_type` argument to [`create_volume`](Self::create_volume).
    pub async fn list_volume_types_async(
        &self,
        zone: impl AsRef<str>,
    ) -> Result<Vec<ScalewayVolumeType>, ScalewayError> {
        let zone = zone.as_ref();
        use data::volume_type::ScalewayVolumeTypeRoot;
        let types = self
            .get_async(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/products/volumes",
                    zone = zone
                ),
                vec![],
            )
            .await?
            .json::<ScalewayVolumeTypeRoot>()
            .await?
            .volumes
            .into_iter()
            .map(|(id, item)| ScalewayVolumeType {
                id,
                display_name: item.display_name,
                capabilities: item.capabilities,
                constraints: item.constraints,
            })
            .collect();
        Ok(types)
    }

    /// Returns a builder for listing block volumes in `zone`.
    ///
    /// The builder auto-paginates. Use filter methods (`.volume_type()`, `.project()`, etc.)
    /// before calling `.run()` or `.run_async().await`.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let volumes = api.list_volumes("fr-par-1").run_async().await?;
    /// for v in &volumes {
    ///     println!("{}: {} bytes", v.name, v.size);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn list_volumes(&self, zone: impl AsRef<str>) -> ScalewayListVolumesBuilder {
        ScalewayListVolumesBuilder::new(self.clone(), zone.as_ref())
    }

    /// Fetches a single block volume by ID (blocking).
    ///
    /// See [`get_volume_async`](Self::get_volume_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn get_volume(&self, zone: impl AsRef<str>, volume_id: &str) -> Result<ScalewayVolume, ScalewayError> {
        let zone = zone.as_ref();
        use data::volume::ScalewayVolumeRoot;
        Ok(self
            .get(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}",
                    zone = zone,
                    volume_id = volume_id
                ),
                vec![],
            )?
            .json::<ScalewayVolumeRoot>()?
            .volume)
    }

    /// Fetches a single block volume by ID.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let vol = api.get_volume_async("fr-par-1", "vol-uuid-...").await?;
    /// println!("{}: {} bytes", vol.name, vol.size);
    /// # Ok(()) }
    /// ```
    pub async fn get_volume_async(
        &self,
        zone: impl AsRef<str>,
        volume_id: &str,
    ) -> Result<ScalewayVolume, ScalewayError> {
        let zone = zone.as_ref();
        use data::volume::ScalewayVolumeRoot;
        Ok(self
            .get_async(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}",
                    zone = zone,
                    volume_id = volume_id
                ),
                vec![],
            )
            .await?
            .json::<ScalewayVolumeRoot>()
            .await?
            .volume)
    }

    /// Creates a new block volume in the given zone.
    ///
    /// `size` is in bytes. `volume_type` must be supported in the target zone — use
    /// [`list_volume_types_async`](Self::list_volume_types_async) to discover available types and
    /// their minimum/maximum size constraints.
    pub fn create_volume(
        &self,
        zone: impl AsRef<str>,
        name: &str,
        size: u64,
        volume_type: &str,
    ) -> ScalewayCreateVolumeBuilder {
        ScalewayCreateVolumeBuilder::new(self.clone(), zone.as_ref(), name, size, volume_type)
    }

    /// Returns a builder for updating a block volume's name, size, or tags.
    ///
    /// Volume size can only be increased, not reduced. Call `.run()` or `.run_async().await`
    /// to apply the changes.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let vol = api
    ///     .update_volume("fr-par-1", "vol-uuid-...")
    ///     .name("my-data-volume")
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn update_volume(&self, zone: impl AsRef<str>, volume_id: &str) -> ScalewayUpdateVolumeBuilder {
        ScalewayUpdateVolumeBuilder::new(self.clone(), zone.as_ref(), volume_id)
    }

    /// Permanently deletes a block volume (blocking).
    ///
    /// See [`delete_volume_async`](Self::delete_volume_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn delete_volume(&self, zone: impl AsRef<str>, volume_id: &str) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}",
            zone = zone,
            volume_id = volume_id,
        ))?
        .error_for_status()?;
        Ok(())
    }

    /// Permanently deletes a block volume.
    ///
    /// The volume must be detached from any instance before deletion.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_volume_async("fr-par-1", "vol-uuid-...").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_volume_async(
        &self,
        zone: impl AsRef<str>,
        volume_id: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete_async(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/volumes/{volume_id}",
            zone = zone,
            volume_id = volume_id,
        ))
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Deletes a security group (blocking).
    ///
    /// See [`delete_securitygroup_async`](Self::delete_securitygroup_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn delete_securitygroup(
        &self,
        zone: impl AsRef<str>,
        security_group_id: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/security_groups/{security_group_id}",
            zone = zone,
            security_group_id = security_group_id,
        ))?
        .error_for_status()?;
        Ok(())
    }

    /// Permanently deletes a security group.
    ///
    /// The group must not be attached to any instance. Remove all rules first or they
    /// will be deleted along with the group.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_securitygroup_async("fr-par-1", "sg-uuid-...").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_securitygroup_async(
        &self,
        zone: impl AsRef<str>,
        security_group_id: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete_async(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/security_groups/{security_group_id}",
            zone = zone,
            security_group_id = security_group_id,
        ))
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Returns a builder for listing security groups in `zone`.
    ///
    /// Auto-paginates. Filter by name, project, tags, etc. via builder methods.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let groups = api.list_security_groups("fr-par-1").run_async().await?;
    /// # Ok(()) }
    /// ```
    pub fn list_security_groups(&self, zone: impl AsRef<str>) -> ScalewayListSecurityGroupsBuilder {
        ScalewayListSecurityGroupsBuilder::new(self.clone(), zone.as_ref())
    }

    /// Returns a builder for fetching a single security group by ID.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let sg = api.get_security_group("fr-par-1", "sg-uuid-...").run_async().await?;
    /// # Ok(()) }
    /// ```
    pub fn get_security_group(
        &self,
        zone: impl AsRef<str>,
        security_group_id: &str,
    ) -> ScalewayGetSecurityGroupBuilder {
        ScalewayGetSecurityGroupBuilder::new(self.clone(), zone.as_ref(), security_group_id)
    }

    /// Returns a builder for creating a new security group in `zone`.
    ///
    /// - `name`: display name
    /// - `stateful`: when `true`, the group tracks connection state; this is the recommended
    ///   setting for most use-cases
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::{ScalewayApi, SecurityGroupPolicy};
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let sg = api
    ///     .create_security_group("fr-par-1", "web-sg", true)
    ///     .description("Allow HTTP/HTTPS inbound")
    ///     .inbound_default_policy(SecurityGroupPolicy::Drop)
    ///     .run_async()
    ///     .await?;
    /// println!("Created: {}", sg.id);
    /// # Ok(()) }
    /// ```
    pub fn create_security_group(
        &self,
        zone: impl AsRef<str>,
        name: &str,
        stateful: bool,
    ) -> ScalewayCreateSecurityGroupBuilder {
        ScalewayCreateSecurityGroupBuilder::new(self.clone(), zone.as_ref(), name, stateful)
    }

    /// Returns a builder for listing all rules in a security group.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let rules = api
    ///     .list_security_group_rules("fr-par-1", "sg-uuid-...")
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn list_security_group_rules(
        &self,
        zone: impl AsRef<str>,
        security_group_id: &str,
    ) -> ScalewayListSecurityGroupRulesBuilder {
        ScalewayListSecurityGroupRulesBuilder::new(self.clone(), zone.as_ref(), security_group_id)
    }

    /// Returns a builder for fetching a single security group rule by ID.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let rule = api
    ///     .get_security_group_rule("fr-par-1", "sg-uuid-...", "rule-uuid-...")
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn get_security_group_rule(
        &self,
        zone: impl AsRef<str>,
        security_group_id: &str,
        rule_id: &str,
    ) -> ScalewayGetSecurityGroupRuleBuilder {
        ScalewayGetSecurityGroupRuleBuilder::new(self.clone(), zone.as_ref(), security_group_id, rule_id)
    }

    /// Returns a builder for creating a new rule in a security group.
    ///
    /// - `ip_range`: CIDR notation (e.g. `"0.0.0.0/0"` or `"10.0.0.0/8"`)
    /// - `protocol`: [`SecurityGroupRuleProtocol`] — `TCP`, `UDP`, `ICMP`, or `ANY`
    /// - `direction`: [`SecurityGroupRuleDirection`] — `Inbound` or `Outbound`
    /// - `action`: [`SecurityGroupRuleAction`] — `Accept` or `Drop`
    ///
    /// Use `.dest_port_from()` / `.dest_port_to()` to restrict the port range.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::{
    ///     ScalewayApi, SecurityGroupRuleProtocol,
    ///     SecurityGroupRuleDirection, SecurityGroupRuleAction,
    /// };
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// // Allow inbound TCP on port 443 from anywhere
    /// let rule = api
    ///     .create_security_group_rule(
    ///         "fr-par-1", "sg-uuid-...", "0.0.0.0/0",
    ///         SecurityGroupRuleProtocol::Tcp,
    ///         SecurityGroupRuleDirection::Inbound,
    ///         SecurityGroupRuleAction::Accept,
    ///     )
    ///     .dest_port_from(443)
    ///     .dest_port_to(443)
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn create_security_group_rule(
        &self,
        zone: impl AsRef<str>,
        security_group_id: &str,
        ip_range: &str,
        protocol: SecurityGroupRuleProtocol,
        direction: SecurityGroupRuleDirection,
        action: SecurityGroupRuleAction,
    ) -> ScalewayCreateSecurityGroupRuleBuilder {
        ScalewayCreateSecurityGroupRuleBuilder::new(
            self.clone(),
            zone.as_ref(),
            security_group_id,
            ip_range,
            protocol,
            direction,
            action,
        )
    }

    /// Deletes a security group rule (blocking).
    ///
    /// See [`delete_security_group_rule_async`](Self::delete_security_group_rule_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn delete_security_group_rule(
        &self,
        zone: impl AsRef<str>,
        security_group_id: &str,
        rule_id: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/security_groups/{sg_id}/rules/{rule_id}",
            zone = zone,
            sg_id = security_group_id,
            rule_id = rule_id,
        ))?
        .error_for_status()?;
        Ok(())
    }

    /// Permanently deletes a rule from a security group.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_security_group_rule_async("fr-par-1", "sg-uuid-...", "rule-uuid-...").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_security_group_rule_async(
        &self,
        zone: impl AsRef<str>,
        security_group_id: &str,
        rule_id: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete_async(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/security_groups/{sg_id}/rules/{rule_id}",
            zone = zone,
            sg_id = security_group_id,
            rule_id = rule_id,
        ))
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Returns a builder for listing SSH keys in the account.
    ///
    /// SSH keys are global (not zone-scoped). Use filter methods to narrow results.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let keys = api.list_ssh_keys().run_async().await?;
    /// for k in &keys {
    ///     println!("{}: {}", k.id, k.name);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn list_ssh_keys(&self) -> ScalewayListSSHKeysBuilder {
        ScalewayListSSHKeysBuilder::new(self.clone())
    }

    /// Returns a builder for fetching a single SSH key by ID.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let key = api.get_ssh_key("key-uuid-...").run_async().await?;
    /// # Ok(()) }
    /// ```
    pub fn get_ssh_key(&self, ssh_key_id: &str) -> ScalewayGetSSHKeyBuilder {
        ScalewayGetSSHKeyBuilder::new(self.clone(), ssh_key_id)
    }

    /// Fetches an IAM API key by its access key (blocking).
    ///
    /// See [`get_api_key_async`](Self::get_api_key_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn get_api_key(&self, access_key: &str) -> Result<ScalewayApiKey, ScalewayError> {
        Ok(self
            .get(
                &format!(
                    "https://api.scaleway.com/iam/v1alpha1/api-keys/{access_key}",
                    access_key = access_key
                ),
                vec![],
            )?
            .json::<ScalewayApiKey>()?)
    }

    /// Fetches an IAM API key by its access key identifier.
    ///
    /// The `access_key` is the short alphanumeric key (not the secret). Returns metadata
    /// such as creation date, expiry, and associated application/user.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let key = api.get_api_key_async("SCWXXXXXXXXXXXXXXXX").await?;
    /// println!("Created: {}", key.created_at);
    /// # Ok(()) }
    /// ```
    pub async fn get_api_key_async(
        &self,
        access_key: &str,
    ) -> Result<ScalewayApiKey, ScalewayError> {
        Ok(self
            .get_async(
                &format!(
                    "https://api.scaleway.com/iam/v1alpha1/api-keys/{access_key}",
                    access_key = access_key
                ),
                vec![],
            )
            .await?
            .json::<ScalewayApiKey>()
            .await?)
    }

    /// Returns a builder for adding a new SSH public key to the account.
    ///
    /// - `name`: a human-readable label for the key
    /// - `public_key`: the full OpenSSH public key string (e.g. `"ssh-rsa AAAA... user@host"`)
    ///
    /// Once added, the key can be injected into new instances automatically.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let key = api
    ///     .create_ssh_key("my-laptop", "ssh-rsa AAAAB3Nza... user@laptop")
    ///     .run_async()
    ///     .await?;
    /// println!("Added key: {}", key.id);
    /// # Ok(()) }
    /// ```
    pub fn create_ssh_key(&self, name: &str, public_key: &str) -> ScalewayCreateSSHKeyBuilder {
        ScalewayCreateSSHKeyBuilder::new(self.clone(), name, public_key)
    }

    /// Permanently deletes an SSH key (blocking).
    ///
    /// See [`delete_ssh_key_async`](Self::delete_ssh_key_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn delete_ssh_key(&self, ssh_key_id: &str) -> Result<(), ScalewayError> {
        self.delete(&format!(
            "https://api.scaleway.com/iam/v1alpha1/ssh-keys/{ssh_key_id}",
            ssh_key_id = ssh_key_id,
        ))?
        .error_for_status()?;
        Ok(())
    }

    /// Permanently deletes an SSH key from the account.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_ssh_key_async("key-uuid-...").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_ssh_key_async(&self, ssh_key_id: &str) -> Result<(), ScalewayError> {
        self.delete_async(&format!(
            "https://api.scaleway.com/iam/v1alpha1/ssh-keys/{ssh_key_id}",
            ssh_key_id = ssh_key_id,
        ))
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Returns a builder for listing Scaleway projects in the organization.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let projects = api.list_projects().run_async().await?;
    /// for p in &projects {
    ///     println!("{}: {}", p.id, p.name);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn list_projects(&self) -> ScalewayListProjectsBuilder {
        ScalewayListProjectsBuilder::new(self.clone())
    }

    /// Returns a builder for fetching a single project by ID.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let project = api.get_project("proj-uuid-...").run_async().await?;
    /// # Ok(()) }
    /// ```
    pub fn get_project(&self, project_id: &str) -> ScalewayGetProjectBuilder {
        ScalewayGetProjectBuilder::new(self.clone(), project_id)
    }

    /// Returns a builder for creating a new project in the organization.
    ///
    /// - `name`: display name for the project
    /// - `organization_id`: UUID of the organization to create the project in
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let project = api
    ///     .create_project("staging", "org-uuid-...")
    ///     .description("Staging environment")
    ///     .run_async()
    ///     .await?;
    /// println!("Created project: {}", project.id);
    /// # Ok(()) }
    /// ```
    pub fn create_project(
        &self,
        name: &str,
        organization_id: &str,
    ) -> ScalewayCreateProjectBuilder {
        ScalewayCreateProjectBuilder::new(self.clone(), name, organization_id)
    }

    /// Permanently deletes a project (blocking).
    ///
    /// See [`delete_project_async`](Self::delete_project_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn delete_project(&self, project_id: &str) -> Result<(), ScalewayError> {
        self.delete(&format!(
            "https://api.scaleway.com/account/v3/projects/{project_id}",
            project_id = project_id,
        ))?
        .error_for_status()?;
        Ok(())
    }

    /// Permanently deletes a project.
    ///
    /// All resources within the project must be deleted before the project itself can be removed.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_project_async("proj-uuid-...").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_project_async(&self, project_id: &str) -> Result<(), ScalewayError> {
        self.delete_async(&format!(
            "https://api.scaleway.com/account/v3/projects/{project_id}",
            project_id = project_id,
        ))
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Fetches an IAM application by ID (blocking).
    ///
    /// See [`get_application_async`](Self::get_application_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn get_application(
        &self,
        application_id: &str,
    ) -> Result<ScalewayApplication, ScalewayError> {
        Ok(self
            .get(
                &format!(
                    "https://api.scaleway.com/iam/v1alpha1/applications/{application_id}",
                    application_id = application_id
                ),
                vec![],
            )?
            .json::<ScalewayApplication>()?)
    }

    /// Fetches an IAM application by its UUID.
    ///
    /// IAM applications are non-human principals (service accounts) used for programmatic
    /// access. They can have API keys and policies attached.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let app = api.get_application_async("app-uuid-...").await?;
    /// println!("{}: {}", app.id, app.name);
    /// # Ok(()) }
    /// ```
    pub async fn get_application_async(
        &self,
        application_id: &str,
    ) -> Result<ScalewayApplication, ScalewayError> {
        Ok(self
            .get_async(
                &format!(
                    "https://api.scaleway.com/iam/v1alpha1/applications/{application_id}",
                    application_id = application_id
                ),
                vec![],
            )
            .await?
            .json::<ScalewayApplication>()
            .await?)
    }

    /// Fetches an IAM user by ID (blocking).
    ///
    /// See [`get_user_async`](Self::get_user_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn get_user(&self, user_id: &str) -> Result<ScalewayUser, ScalewayError> {
        Ok(self
            .get(
                &format!(
                    "https://api.scaleway.com/iam/v1alpha1/users/{user_id}",
                    user_id = user_id
                ),
                vec![],
            )?
            .json::<ScalewayUser>()?)
    }

    /// Fetches an IAM user by their UUID.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let user = api.get_user_async("user-uuid-...").await?;
    /// println!("{}", user.email);
    /// # Ok(()) }
    /// ```
    pub async fn get_user_async(&self, user_id: &str) -> Result<ScalewayUser, ScalewayError> {
        Ok(self
            .get_async(
                &format!(
                    "https://api.scaleway.com/iam/v1alpha1/users/{user_id}",
                    user_id = user_id
                ),
                vec![],
            )
            .await?
            .json::<ScalewayUser>()
            .await?)
    }

    /// Returns a builder for allocating a new flexible (public) IP in `zone`.
    ///
    /// `ip_type` controls whether this is a routed IPv4 (`FlexibleIpType::RoutedIpv4`) or NAT IP.
    /// The allocated IP can be attached to an instance at creation time or later.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::{ScalewayApi, FlexibleIpType};
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let ip = api
    ///     .create_flexible_ip("fr-par-1", FlexibleIpType::RoutedIpv4)
    ///     .run_async()
    ///     .await?;
    /// println!("Allocated: {}", ip.address);
    /// # Ok(()) }
    /// ```
    pub fn create_flexible_ip(&self, zone: impl AsRef<str>, ip_type: FlexibleIpType) -> ScalewayCreateFlexibleIpBuilder {
        ScalewayCreateFlexibleIpBuilder::new(self.clone(), zone.as_ref(), ip_type)
    }

    /// Returns a builder for listing flexible IPs in `zone`.
    ///
    /// Auto-paginates. Filter by server, project, tags, etc.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let ips = api.list_flexible_ips("fr-par-1").run_async().await?;
    /// for ip in &ips {
    ///     println!("{}", ip.address);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn list_flexible_ips(&self, zone: impl AsRef<str>) -> ScalewayListFlexibleIpsBuilder {
        ScalewayListFlexibleIpsBuilder::new(self.clone(), zone.as_ref())
    }

    /// Returns a builder for updating a flexible IP's reverse DNS, tags, or attached server.
    ///
    /// Pass an empty string to `.server("")` to detach the IP from its current instance.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let ip = api
    ///     .update_flexible_ip("fr-par-1", "ip-uuid-...")
    ///     .reverse("my-server.example.com")
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn update_flexible_ip(
        &self,
        zone: impl AsRef<str>,
        ip_id: &str,
    ) -> ScalewayUpdateFlexibleIpBuilder {
        ScalewayUpdateFlexibleIpBuilder::new(self.clone(), zone.as_ref(), ip_id)
    }

    /// Fetches a single flexible IP by ID (blocking).
    ///
    /// See [`get_flexible_ip_async`](Self::get_flexible_ip_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn get_flexible_ip(
        &self,
        zone: impl AsRef<str>,
        ip_id: &str,
    ) -> Result<ScalewayFlexibleIp, ScalewayError> {
        let zone = zone.as_ref();
        use data::flexible_ip::ScalewayFlexibleIpRoot;
        Ok(self
            .get(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/ips/{ip_id}",
                    zone = zone,
                    ip_id = ip_id
                ),
                vec![],
            )?
            .json::<ScalewayFlexibleIpRoot>()?
            .ip)
    }

    /// Fetches a single flexible IP by its UUID.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let ip = api.get_flexible_ip_async("fr-par-1", "ip-uuid-...").await?;
    /// println!("{}", ip.address);
    /// # Ok(()) }
    /// ```
    pub async fn get_flexible_ip_async(
        &self,
        zone: impl AsRef<str>,
        ip_id: &str,
    ) -> Result<ScalewayFlexibleIp, ScalewayError> {
        let zone = zone.as_ref();
        use data::flexible_ip::ScalewayFlexibleIpRoot;
        Ok(self
            .get_async(
                &format!(
                    "https://api.scaleway.com/instance/v1/zones/{zone}/ips/{ip_id}",
                    zone = zone,
                    ip_id = ip_id
                ),
                vec![],
            )
            .await?
            .json::<ScalewayFlexibleIpRoot>()
            .await?
            .ip)
    }

    /// Releases a flexible IP back to the pool (blocking).
    ///
    /// See [`delete_flexible_ip_async`](Self::delete_flexible_ip_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn delete_flexible_ip(&self, zone: impl AsRef<str>, ip_id: &str) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/ips/{ip_id}",
            zone = zone,
            ip_id = ip_id
        ))?
        .error_for_status()?;
        Ok(())
    }

    /// Releases a flexible IP, returning it to the Scaleway IP pool.
    ///
    /// The IP must be detached from any instance before deletion.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_flexible_ip_async("fr-par-1", "ip-uuid-...").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_flexible_ip_async(
        &self,
        zone: impl AsRef<str>,
        ip_id: &str,
    ) -> Result<(), ScalewayError> {
        let zone = zone.as_ref();
        self.delete_async(&format!(
            "https://api.scaleway.com/instance/v1/zones/{zone}/ips/{ip_id}",
            zone = zone,
            ip_id = ip_id
        ))
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Returns a builder for listing DNS zones in the account.
    ///
    /// Auto-paginates. Filter by domain, project, organization, or status.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let zones = api.list_dns_zones().domain("example.com").run_async().await?;
    /// for zone in &zones {
    ///     println!("{}", zone.domain);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn list_dns_zones(&self) -> ScalewayListDnsZonesBuilder {
        ScalewayListDnsZonesBuilder::new(self.clone())
    }

    /// Lists all DNS records in a zone, auto-paginating (blocking).
    ///
    /// See [`list_dns_records_async`](Self::list_dns_records_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn list_dns_records(&self, dns_zone: impl AsRef<str>) -> Result<Vec<ScalewayDnsRecord>, ScalewayError> {
        let dns_zone = dns_zone.as_ref();
        use data::dns_record::ScalewayDnsRecordsRoot;
        let mut list = vec![];
        let mut page = 1u32;
        loop {
            let result = self
                .get(
                    &format!(
                        "https://api.scaleway.com/domain/v2beta1/dns-zones/{dns_zone}/records",
                        dns_zone = dns_zone
                    ),
                    vec![("page", page.to_string()), ("page_size", "100".to_string())],
                )?
                .json::<ScalewayDnsRecordsRoot>()?;
            if result.records.is_empty() {
                break;
            }
            list.extend(result.records);
            page += 1;
        }
        Ok(list)
    }

    /// Lists all DNS records in a zone, fetching all pages automatically.
    ///
    /// `dns_zone` is the zone name such as `"example.com"` or `"sub.example.com"`.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let records = api.list_dns_records_async("example.com").await?;
    /// for r in &records {
    ///     println!("{} {} {}", r.name, r.r#type, r.data);
    /// }
    /// # Ok(()) }
    /// ```
    pub async fn list_dns_records_async(
        &self,
        dns_zone: impl AsRef<str>,
    ) -> Result<Vec<ScalewayDnsRecord>, ScalewayError> {
        let dns_zone = dns_zone.as_ref();
        use data::dns_record::ScalewayDnsRecordsRoot;
        let mut list = vec![];
        let mut page = 1u32;
        loop {
            let result = self
                .get_async(
                    &format!(
                        "https://api.scaleway.com/domain/v2beta1/dns-zones/{dns_zone}/records",
                        dns_zone = dns_zone
                    ),
                    vec![("page", page.to_string()), ("page_size", "100".to_string())],
                )
                .await?
                .json::<ScalewayDnsRecordsRoot>()
                .await?;
            if result.records.is_empty() {
                break;
            }
            list.extend(result.records);
            page += 1;
        }
        Ok(list)
    }

    /// Deletes a single DNS record by ID (blocking).
    ///
    /// See [`delete_dns_record_async`](Self::delete_dns_record_async) for full docs.
    #[cfg(feature = "blocking")]
    pub fn delete_dns_record(&self, dns_zone: impl AsRef<str>, record_id: &str) -> Result<(), ScalewayError> {
        let dns_zone = dns_zone.as_ref();
        #[derive(serde::Serialize)]
        struct DeleteChange { delete: DeleteById }
        #[derive(serde::Serialize)]
        struct DeleteById { id: String }
        #[derive(serde::Serialize)]
        struct DeleteRequest { changes: Vec<DeleteChange> }

        self.post(
            &format!(
                "https://api.scaleway.com/domain/v2beta1/dns-zones/{dns_zone}/records",
                dns_zone = dns_zone
            ),
            DeleteRequest {
                changes: vec![DeleteChange { delete: DeleteById { id: record_id.to_string() } }],
            },
        )?
        .error_for_status()?;
        Ok(())
    }

    /// Deletes a single DNS record from a zone.
    ///
    /// `record_id` is the UUID of the record returned by [`list_dns_records_async`](Self::list_dns_records_async).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::ScalewayApi;
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// api.delete_dns_record_async("example.com", "record-uuid-...").await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete_dns_record_async(
        &self,
        dns_zone: impl AsRef<str>,
        record_id: &str,
    ) -> Result<(), ScalewayError> {
        let dns_zone = dns_zone.as_ref();
        #[derive(serde::Serialize)]
        struct DeleteChange { delete: DeleteById }
        #[derive(serde::Serialize)]
        struct DeleteById { id: String }
        #[derive(serde::Serialize)]
        struct DeleteRequest { changes: Vec<DeleteChange> }

        self.post_async(
            &format!(
                "https://api.scaleway.com/domain/v2beta1/dns-zones/{dns_zone}/records",
                dns_zone = dns_zone
            ),
            DeleteRequest {
                changes: vec![DeleteChange { delete: DeleteById { id: record_id.to_string() } }],
            },
        )
        .await?
        .error_for_status()?;
        Ok(())
    }

    /// Returns a builder for adding a new DNS record to a zone.
    ///
    /// - `dns_zone`: the zone name (e.g. `"example.com"`)
    /// - `name`: record name relative to the zone (use `"@"` for the zone apex, `"www"` for `www.example.com`)
    /// - `record_type`: [`DnsRecordType`] variant (A, AAAA, CNAME, MX, TXT, etc.)
    /// - `data`: the record value (e.g. an IP address for A records, a hostname for CNAME)
    ///
    /// Optionally set TTL, priority (for MX), and a comment via builder methods.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::{ScalewayApi, DnsRecordType};
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// // Add an A record: www.example.com → 1.2.3.4
    /// let records = api
    ///     .add_dns_record("example.com", "www", DnsRecordType::A, "1.2.3.4")
    ///     .ttl(3600)
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn add_dns_record(
        &self,
        dns_zone: impl AsRef<str>,
        name: &str,
        record_type: DnsRecordType,
        data: &str,
    ) -> ScalewayAddDnsRecordBuilder {
        ScalewayAddDnsRecordBuilder::new(self.clone(), dns_zone.as_ref(), name, record_type, data)
    }

    /// Returns a builder for updating an existing DNS record in place.
    ///
    /// Identifies the record to replace by `record_id` (UUID from [`list_dns_records_async`](Self::list_dns_records_async)).
    /// The new name, type, and data replace the old values entirely.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # #[tokio::main] async fn main() -> Result<(), scaleway_rs::ScalewayError> {
    /// use scaleway_rs::{ScalewayApi, DnsRecordType};
    ///
    /// let api = ScalewayApi::new("your-secret-key");
    /// let records = api
    ///     .update_dns_record("example.com", "record-uuid-...", "www", DnsRecordType::A, "5.6.7.8")
    ///     .ttl(300)
    ///     .run_async()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn update_dns_record(
        &self,
        dns_zone: impl AsRef<str>,
        record_id: &str,
        name: &str,
        record_type: DnsRecordType,
        data: &str,
    ) -> ScalewayUpdateDnsRecordBuilder {
        ScalewayUpdateDnsRecordBuilder::new(self.clone(), dns_zone.as_ref(), record_id, name, record_type, data)
    }
}