arcgis 0.1.3

//! Geocoding service client.

use crate::{
    ArcGISClient, GeocodeResponse, LocationType, Result, ReverseGeocodeResponse, SuggestResponse,
};
use tracing::instrument;

/// Client for interacting with an ArcGIS Geocoding Service.
///
/// The geocoding service converts addresses to geographic coordinates (geocoding)
/// and coordinates to addresses (reverse geocoding). It also provides autocomplete
/// suggestions for partial addresses.
///
/// # Example
///
/// ```no_run
/// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient};
///
/// # async fn example() -> arcgis::Result<()> {
/// let auth = ApiKeyAuth::new("YOUR_API_KEY");
/// let client = ArcGISClient::new(auth);
///
/// let geocoder = GeocodeServiceClient::new(
///     "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer",
///     &client,
/// );
///
/// // Geocode an address
/// let candidates = geocoder
///     .find_address_candidates("380 New York St, Redlands, CA 92373")
///     .await?;
///
/// for candidate in candidates.candidates() {
///     println!("{}: {}, {} (score: {})",
///         candidate.address(),
///         candidate.location().x(),
///         candidate.location().y(),
///         candidate.score()
///     );
/// }
/// # Ok(())
/// # }
/// ```
pub struct GeocodeServiceClient<'a> {
    /// Base URL of the geocoding service
    base_url: String,
    /// Reference to the ArcGIS client for HTTP operations
    client: &'a ArcGISClient,
}

impl<'a> GeocodeServiceClient<'a> {
    /// Creates a new Geocoding Service client.
    ///
    /// # Arguments
    ///
    /// * `base_url` - The base URL of the geocoding service
    /// * `client` - Reference to an authenticated ArcGIS client
    ///
    /// # Example
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient};
    ///
    /// let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// let client = ArcGISClient::new(auth);
    ///
    /// // World Geocoding Service
    /// let geocoder = GeocodeServiceClient::new(
    ///     "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer",
    ///     &client,
    /// );
    /// ```
    #[instrument(skip(base_url, client))]
    pub fn new(base_url: impl Into<String>, client: &'a ArcGISClient) -> Self {
        let base_url = base_url.into();
        tracing::debug!(base_url = %base_url, "Creating GeocodeServiceClient");
        Self { base_url, client }
    }

    /// Finds address candidates for a given address string.
    ///
    /// This performs forward geocoding - converting an address to coordinates.
    ///
    /// # Arguments
    ///
    /// * `address` - The address to geocode (single-line format)
    ///
    /// # Example
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient};
    ///
    /// # async fn example() -> arcgis::Result<()> {
    /// # let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// # let client = ArcGISClient::new(auth);
    /// # let geocoder = GeocodeServiceClient::new("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", &client);
    /// let response = geocoder
    ///     .find_address_candidates("1600 Pennsylvania Ave NW, Washington, DC")
    ///     .await?;
    ///
    /// if let Some(best_match) = response.candidates().first() {
    ///     println!("Location: {}, {}",
    ///         best_match.location().x(),
    ///         best_match.location().y()
    ///     );
    /// }
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip(self, address), fields(base_url = %self.base_url))]
    pub async fn find_address_candidates(
        &self,
        address: impl Into<String>,
    ) -> Result<GeocodeResponse> {
        let address = address.into();
        tracing::debug!(address = %address, "Finding address candidates");

        let url = format!("{}/findAddressCandidates", self.base_url);

        tracing::debug!(url = %url, "Sending findAddressCandidates request");

        let mut request = self.client.http().get(&url).query(&[
            ("SingleLine", address.as_str()),
            ("f", "json"),
            ("outFields", "*"),
            ("maxLocations", "50"),
        ]);

        if let Some(token) = self.client.get_token_if_required().await? {
            request = request.query(&[("token", token)]);
        }

        let response = request.send().await?;

        let status = response.status();
        if !status.is_success() {
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|e| format!("Failed to read error: {}", e));
            tracing::error!(status = %status, error = %error_text, "findAddressCandidates failed");
            return Err(crate::Error::from(crate::ErrorKind::Api {
                code: status.as_u16() as i32,
                message: format!("HTTP {}: {}", status, error_text),
            }));
        }

        let geocode_response: GeocodeResponse = response.json().await?;

        tracing::info!(
            candidate_count = geocode_response.candidates().len(),
            "findAddressCandidates completed"
        );

        Ok(geocode_response)
    }

    /// Finds address candidates with advanced options.
    ///
    /// # Arguments
    ///
    /// * `address` - The address to geocode
    /// * `max_locations` - Maximum number of candidates to return (default: 50)
    /// * `location_type` - Type of location to return (rooftop or street)
    ///
    /// # Example
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient, LocationType};
    ///
    /// # async fn example() -> arcgis::Result<()> {
    /// # let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// # let client = ArcGISClient::new(auth);
    /// # let geocoder = GeocodeServiceClient::new("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", &client);
    /// let response = geocoder
    ///     .find_address_candidates_with_options(
    ///         "Starbucks, Seattle",
    ///         Some(10),
    ///         Some(LocationType::Street),
    ///     )
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip(self, address), fields(base_url = %self.base_url))]
    pub async fn find_address_candidates_with_options(
        &self,
        address: impl Into<String>,
        max_locations: Option<u32>,
        location_type: Option<LocationType>,
    ) -> Result<GeocodeResponse> {
        let address = address.into();
        tracing::debug!(address = %address, "Finding address candidates with options");

        let url = format!("{}/findAddressCandidates", self.base_url);

        let max_locs = max_locations.unwrap_or(50).to_string();
        let mut params = vec![
            ("SingleLine", address.as_str()),
            ("f", "json"),
            ("outFields", "*"),
            ("maxLocations", max_locs.as_str()),
        ];

        let loc_type_str;
        if let Some(lt) = location_type {
            loc_type_str = match lt {
                LocationType::Rooftop => "rooftop",
                LocationType::Street => "street",
            };
            params.push(("locationType", loc_type_str));
        }

        tracing::debug!(url = %url, "Sending findAddressCandidates request");

        let mut request = self.client.http().get(&url).query(&params);

        if let Some(token) = self.client.get_token_if_required().await? {
            request = request.query(&[("token", token)]);
        }

        let response = request.send().await?;

        let status = response.status();
        if !status.is_success() {
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|e| format!("Failed to read error: {}", e));
            tracing::error!(status = %status, error = %error_text, "findAddressCandidates failed");
            return Err(crate::Error::from(crate::ErrorKind::Api {
                code: status.as_u16() as i32,
                message: format!("HTTP {}: {}", status, error_text),
            }));
        }

        let geocode_response: GeocodeResponse = response.json().await?;

        tracing::info!(
            candidate_count = geocode_response.candidates().len(),
            "findAddressCandidates completed"
        );

        Ok(geocode_response)
    }

    /// Finds address candidates with custom spatial reference.
    ///
    /// This extends the basic `find_address_candidates` operation by allowing you to
    /// specify the output spatial reference for the returned coordinates.
    ///
    /// # Arguments
    ///
    /// * `address` - The address to geocode
    /// * `out_sr` - The WKID of the desired output spatial reference
    ///
    /// # Example
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient};
    ///
    /// # async fn example() -> arcgis::Result<()> {
    /// let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// let client = ArcGISClient::new(auth);
    /// let geocoder = GeocodeServiceClient::new("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", &client);
    ///
    /// // Geocode with Web Mercator output (WKID: 3857)
    /// let result = geocoder
    ///     .find_address_candidates_with_sr("380 New York St, Redlands, CA", 3857)
    ///     .await?;
    ///
    /// // Geocode with State Plane California Zone 6 (WKID: 2230)
    /// let result_sp = geocoder
    ///     .find_address_candidates_with_sr("380 New York St, Redlands, CA", 2230)
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip(self, address), fields(out_sr = out_sr))]
    pub async fn find_address_candidates_with_sr(
        &self,
        address: impl Into<String>,
        out_sr: i32,
    ) -> Result<GeocodeResponse> {
        let address = address.into();
        tracing::debug!(address = %address, out_sr = out_sr, "Finding address candidates with custom SR");

        let url = format!("{}/findAddressCandidates", self.base_url);

        tracing::debug!(url = %url, "Sending findAddressCandidates request");

        let mut request = self.client.http().get(&url).query(&[
            ("SingleLine", address.as_str()),
            ("outSR", out_sr.to_string().as_str()),
            ("f", "json"),
            ("outFields", "*"),
            ("maxLocations", "50"),
        ]);

        if let Some(token) = self.client.get_token_if_required().await? {
            request = request.query(&[("token", token)]);
        }

        let response = request.send().await?;

        let status = response.status();
        if !status.is_success() {
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|e| format!("Failed to read error: {}", e));
            tracing::error!(status = %status, error = %error_text, "findAddressCandidates with SR failed");
            return Err(crate::Error::from(crate::ErrorKind::Api {
                code: status.as_u16() as i32,
                message: format!("HTTP {}: {}", status, error_text),
            }));
        }

        let geocode_response: GeocodeResponse = response.json().await?;

        tracing::info!(
            candidate_count = geocode_response.candidates().len(),
            out_sr = out_sr,
            "findAddressCandidates with SR completed"
        );

        Ok(geocode_response)
    }

    /// Reverse geocodes a point to an address, with output in the same spatial reference.
    ///
    /// # Type Safety
    ///
    /// The spatial reference is encoded in the type system via the `ProjectedPoint` trait.
    /// The method automatically uses the correct WKID from the type, preventing runtime errors
    /// from incorrect spatial reference usage.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient, Wgs84Point, WebMercatorPoint};
    ///
    /// # async fn example() -> arcgis::Result<()> {
    /// # let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// # let client = ArcGISClient::new(auth);
    /// let geocoder = GeocodeServiceClient::new("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", &client);
    ///
    /// // ✅ WGS84 input → WGS84 output
    /// let wgs84 = Wgs84Point::new(-117.195, 34.056);
    /// let response = geocoder.reverse_geocode(&wgs84).await?;
    /// // response.location() is in WGS84
    ///
    /// // ✅ Web Mercator input → Web Mercator output
    /// let web_merc = WebMercatorPoint::new(-13046213.0, 4036389.0);
    /// let response = geocoder.reverse_geocode(&web_merc).await?;
    /// // response.location() is in Web Mercator
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip(self, location), fields(
        base_url = %self.base_url,
        input_wkid = P::WKID,
        input_sr = P::NAME
    ))]
    pub async fn reverse_geocode<P: crate::ProjectedPoint>(
        &self,
        location: &P,
    ) -> Result<ReverseGeocodeResponse> {
        self.reverse_geocode_to::<P, P>(location).await
    }

    /// Reverse geocodes a point with explicit input and output spatial references.
    ///
    /// # Type Parameters
    ///
    /// * `In` - Input coordinate system (derived from location type)
    /// * `Out` - Output coordinate system (specified explicitly)
    ///
    /// # Type Safety
    ///
    /// Both input and output spatial references are encoded in the type system.
    /// The compiler ensures you can't accidentally mix coordinate systems.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient, Wgs84Point, WebMercatorPoint};
    ///
    /// # async fn example() -> arcgis::Result<()> {
    /// # let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// # let client = ArcGISClient::new(auth);
    /// let geocoder = GeocodeServiceClient::new("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", &client);
    ///
    /// // ✅ WGS84 input → Web Mercator output
    /// let wgs84 = Wgs84Point::new(-117.195, 34.056);
    /// let response = geocoder
    ///     .reverse_geocode_to::<_, WebMercatorPoint>(&wgs84)
    ///     .await?;
    /// // response.location() is in Web Mercator
    ///
    /// // ✅ Web Mercator input → WGS84 output
    /// let web_merc = WebMercatorPoint::new(-13046213.0, 4036389.0);
    /// let response = geocoder
    ///     .reverse_geocode_to::<_, Wgs84Point>(&web_merc)
    ///     .await?;
    /// // response.location() is in WGS84
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip(self, location), fields(
        base_url = %self.base_url,
        input_wkid = In::WKID,
        output_wkid = Out::WKID
    ))]
    pub async fn reverse_geocode_to<In: crate::ProjectedPoint, Out: crate::ProjectedPoint>(
        &self,
        location: &In,
    ) -> Result<ReverseGeocodeResponse> {
        tracing::debug!(
            input_sr = In::NAME,
            output_sr = Out::NAME,
            "Reverse geocoding with spatial reference conversion"
        );

        let url = format!("{}/reverseGeocode", self.base_url);

        // Use JSON format to support any input spatial reference
        let location_param = location.to_location_json();

        let mut request = self.client.http().get(&url).query(&[
            ("location", location_param.as_str()),
            ("outSR", Out::WKID.to_string().as_str()),
            ("f", "json"),
        ]);

        if let Some(token) = self.client.get_token_if_required().await? {
            request = request.query(&[("token", token)]);
        }

        let response = request.send().await?;

        let status = response.status();
        if !status.is_success() {
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|e| format!("Failed to read error: {}", e));
            tracing::error!(status = %status, error = %error_text, "reverseGeocode failed");
            return Err(crate::Error::from(crate::ErrorKind::Api {
                code: status.as_u16() as i32,
                message: format!("HTTP {}: {}", status, error_text),
            }));
        }

        let reverse_response: ReverseGeocodeResponse = response.json().await?;

        tracing::info!(
            address = ?reverse_response.address().match_addr(),
            input_sr = In::NAME,
            output_sr = Out::NAME,
            "reverseGeocode completed"
        );

        Ok(reverse_response)
    }

    /// Gets autocomplete suggestions for partial address input.
    ///
    /// This is useful for implementing search-as-you-type functionality.
    /// The magic key from suggestions can be used with `find_address_candidates`
    /// for faster geocoding.
    ///
    /// # Arguments
    ///
    /// * `text` - Partial address or place name
    ///
    /// # Example
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient};
    ///
    /// # async fn example() -> arcgis::Result<()> {
    /// # let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// # let client = ArcGISClient::new(auth);
    /// # let geocoder = GeocodeServiceClient::new("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", &client);
    /// let suggestions = geocoder.suggest("380 New York").await?;
    ///
    /// for suggestion in suggestions.suggestions() {
    ///     println!("{} (key: {})", suggestion.text(), suggestion.magic_key());
    /// }
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip(self, text), fields(base_url = %self.base_url))]
    pub async fn suggest(&self, text: impl Into<String>) -> Result<SuggestResponse> {
        let text = text.into();
        tracing::debug!(text = %text, "Getting autocomplete suggestions");

        let url = format!("{}/suggest", self.base_url);

        tracing::debug!(url = %url, "Sending suggest request");

        let mut request = self
            .client
            .http()
            .get(&url)
            .query(&[("text", text.as_str()), ("f", "json")]);

        if let Some(token) = self.client.get_token_if_required().await? {
            request = request.query(&[("token", token)]);
        }

        let response = request.send().await?;

        let status = response.status();
        if !status.is_success() {
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|e| format!("Failed to read error: {}", e));
            tracing::error!(status = %status, error = %error_text, "suggest failed");
            return Err(crate::Error::from(crate::ErrorKind::Api {
                code: status.as_u16() as i32,
                message: format!("HTTP {}: {}", status, error_text),
            }));
        }

        let suggest_response: SuggestResponse = response.json().await?;

        tracing::info!(
            suggestion_count = suggest_response.suggestions().len(),
            "suggest completed"
        );

        Ok(suggest_response)
    }

    /// Gets autocomplete suggestions filtered by category.
    ///
    /// This method extends the basic `suggest` operation by allowing you to filter
    /// results by location category (e.g., "Address", "City", "POI").
    ///
    /// # Arguments
    ///
    /// * `text` - The partial address text to get suggestions for
    /// * `category` - The category to filter by (e.g., "Address", "City", "POI")
    ///
    /// # Example
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient, Category};
    ///
    /// # async fn example() -> arcgis::Result<()> {
    /// let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// let client = ArcGISClient::new(auth);
    /// let geocoder = GeocodeServiceClient::new("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", &client);
    ///
    /// // Get suggestions for POIs only
    /// let poi_suggestions = geocoder
    ///     .suggest_with_category("Starbucks", Category::Poi)
    ///     .await?;
    ///
    /// // Get suggestions for food establishments only
    /// let food_suggestions = geocoder
    ///     .suggest_with_category("Pizza", Category::Food)
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip(self, text, category), fields(text_len = text.as_ref().len()))]
    pub async fn suggest_with_category(
        &self,
        text: impl Into<String> + AsRef<str>,
        category: crate::Category,
    ) -> Result<SuggestResponse> {
        let text = text.into();
        tracing::debug!(text = %text, category = ?category, "Getting category-filtered suggestions");

        let url = format!("{}/suggest", self.base_url);

        tracing::debug!(url = %url, "Sending suggest request with category filter");

        let mut request = self.client.http().get(&url).query(&[
            ("text", text.as_str()),
            ("category", category.as_str()),
            ("f", "json"),
        ]);

        if let Some(token) = self.client.get_token_if_required().await? {
            request = request.query(&[("token", token)]);
        }

        let response = request.send().await?;

        let status = response.status();
        if !status.is_success() {
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|e| format!("Failed to read error: {}", e));
            tracing::error!(status = %status, error = %error_text, "suggest with category failed");
            return Err(crate::Error::from(crate::ErrorKind::Api {
                code: status.as_u16() as i32,
                message: format!("HTTP {}: {}", status, error_text),
            }));
        }

        let suggest_response: SuggestResponse = response.json().await?;

        tracing::info!(
            suggestion_count = suggest_response.suggestions().len(),
            category = ?category,
            "suggest with category completed"
        );

        Ok(suggest_response)
    }

    /// Geocodes multiple addresses in a single batch request.
    ///
    /// This is more efficient than geocoding addresses individually when you have
    /// many addresses to process. The batch size is typically limited to 1000 addresses.
    ///
    /// # Arguments
    ///
    /// * `addresses` - Vector of addresses to geocode
    ///
    /// # Example
    ///
    /// ```no_run
    /// use arcgis::{ApiKeyAuth, ArcGISClient, GeocodeServiceClient, BatchGeocodeRecord};
    ///
    /// # async fn example() -> arcgis::Result<()> {
    /// # let auth = ApiKeyAuth::new("YOUR_API_KEY");
    /// # let client = ArcGISClient::new(auth);
    /// # let geocoder = GeocodeServiceClient::new("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer", &client);
    /// let addresses = vec![
    ///     BatchGeocodeRecord::with_single_line(1, "380 New York St, Redlands, CA 92373"),
    ///     BatchGeocodeRecord::with_single_line(2, "1 World Way, Los Angeles, CA 90045"),
    /// ];
    ///
    /// let results = geocoder.geocode_addresses(addresses).await?;
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(skip(self, addresses), fields(count = addresses.len()))]
    pub async fn geocode_addresses(
        &self,
        addresses: Vec<crate::BatchGeocodeRecord>,
    ) -> Result<crate::BatchGeocodeResponse> {
        tracing::debug!("Batch geocoding addresses");

        let url = format!("{}/geocodeAddresses", self.base_url);

        // Format records with attributes wrapper as required by API
        let records: Vec<serde_json::Value> = addresses
            .iter()
            .map(|addr| {
                serde_json::json!({
                    "attributes": addr
                })
            })
            .collect();

        let addresses_json = serde_json::json!({
            "records": records
        });

        tracing::debug!(url = %url, count = addresses.len(), "Sending geocodeAddresses request");

        let addresses_str = addresses_json.to_string();
        let mut form = vec![("addresses", addresses_str.as_str()), ("f", "json")];

        // Add token if required by auth provider
        let token_opt = self.client.get_token_if_required().await?;
        let token_str;
        if let Some(token) = token_opt {
            token_str = token;
            form.push(("token", token_str.as_str()));
        }

        let response = self.client.http().post(&url).form(&form).send().await?;

        let status = response.status();
        if !status.is_success() {
            let error_text = response
                .text()
                .await
                .unwrap_or_else(|e| format!("Failed to read error: {}", e));
            tracing::error!(status = %status, error = %error_text, "geocodeAddresses failed");
            return Err(crate::Error::from(crate::ErrorKind::Api {
                code: status.as_u16() as i32,
                message: format!("HTTP {}: {}", status, error_text),
            }));
        }

        let batch_response: crate::BatchGeocodeResponse = response.json().await?;

        tracing::info!(
            location_count = batch_response.locations().len(),
            "geocodeAddresses completed"
        );

        Ok(batch_response)
    }
}