Ryan/enrichment search (#43)

* Add address search capability to us_enrichment_api

- Add address fields (street, city, state, zipcode, freeform) to EnrichmentLookup
- Use /lookup/search/{dataset} path when smarty_key is not provided
- Add validation to require at least one address field for address searches
- Add ValidationError variant to SmartyError
- Add example demonstrating structured and freeform address search
- Add tests for address search functionality

* More settings.

Author: RyanLCox1

.claude/settings.json

@@ -8,5 +8,9 @@
       "Bash(make *)",
       "Bash(cargo *)"
     ]
+  },
+  "attribution": {
+    "commit": "",
+    "pr": ""
   }
 }

Makefile

@@ -53,6 +53,9 @@ us_zipcode_api:
 us_enrichment_api:
 	RUST_LOG=trace cargo run --example us_enrichment_api
 
+us_enrichment_address_search_api:
+	RUST_LOG=trace cargo run --example us_enrichment_address_search_api
+
 examples: international_autocomplete_api international_postal_code_api international_street_api logger us_autocomplete_pro_api us_extract_api us_reverse_geo_api us_street_api us_zipcode_api
 
-.PHONY: clean test dependencies package examples clippy international_autocomplete_api international_postal_code_api international_street_api logger us_autocomplete_pro_api us_extract_api us_reverse_geo_api us_street_api us_zipcode_api us_enrichment_api
+.PHONY: clean test dependencies package examples clippy international_autocomplete_api international_postal_code_api international_street_api logger us_autocomplete_pro_api us_extract_api us_reverse_geo_api us_street_api us_zipcode_api us_enrichment_api us_enrichment_address_search_api

smarty-rust-sdk/examples/us_enrichment_address_search_api.rs

@@ -0,0 +1,74 @@
+use smarty_rust_sdk::sdk::authentication::BasicAuthCredential;
+use smarty_rust_sdk::sdk::options::OptionsBuilder;
+
+use smarty_rust_sdk::us_enrichment_api::client::*;
+use smarty_rust_sdk::us_enrichment_api::lookup::EnrichmentLookup;
+use smarty_rust_sdk::us_enrichment_api::principal::*;
+
+use std::error::Error;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    // Example using structured address fields
+    structured_address_search().await?;
+
+    // Example using freeform address
+    freeform_address_search().await?;
+
+    Ok(())
+}
+
+async fn structured_address_search() -> Result<(), Box<dyn Error>> {
+    println!("=== Structured Address Search ===");
+
+    let mut lookup = EnrichmentLookup::<PrincipalResponse> {
+        street: "56 Union Ave".to_string(),
+        city: "Somerville".to_string(),
+        state: "NJ".to_string(),
+        zipcode: "08876".to_string(),
+        ..Default::default()
+    };
+
+    let authentication = BasicAuthCredential::new(
+        std::env::var("SMARTY_AUTH_ID").expect("Missing SMARTY_AUTH_ID env variable"),
+        std::env::var("SMARTY_AUTH_TOKEN").expect("Missing SMARTY_AUTH_TOKEN env variable"),
+    );
+
+    let options = OptionsBuilder::new(Some(authentication))
+        .with_logging()
+        .build();
+
+    let client = USEnrichmentClient::new(options)?;
+
+    client.send(&mut lookup).await?;
+
+    println!("{}", serde_json::to_string_pretty(&lookup.results)?);
+
+    Ok(())
+}
+
+async fn freeform_address_search() -> Result<(), Box<dyn Error>> {
+    println!("\n=== Freeform Address Search ===");
+
+    let mut lookup = EnrichmentLookup::<PrincipalResponse> {
+        freeform: "56 Union Ave, Somerville, NJ 08876".to_string(),
+        ..Default::default()
+    };
+
+    let authentication = BasicAuthCredential::new(
+        std::env::var("SMARTY_AUTH_ID").expect("Missing SMARTY_AUTH_ID env variable"),
+        std::env::var("SMARTY_AUTH_TOKEN").expect("Missing SMARTY_AUTH_TOKEN env variable"),
+    );
+
+    let options = OptionsBuilder::new(Some(authentication))
+        .with_logging()
+        .build();
+
+    let client = USEnrichmentClient::new(options)?;
+
+    client.send(&mut lookup).await?;
+
+    println!("{}", serde_json::to_string_pretty(&lookup.results)?);
+
+    Ok(())
+}

smarty-rust-sdk/src/sdk/error.rs

@@ -12,4 +12,6 @@ pub enum SmartyError {
     Parse(#[from] url::ParseError),
     #[error("http error")]
     HttpError { code: StatusCode, detail: String },
+    #[error("validation error: {0}")]
+    ValidationError(String),
 }

smarty-rust-sdk/src/us_enrichment_api/client.rs

@@ -1,3 +1,5 @@
+use std::borrow::Cow;
+
 use crate::sdk::client::Client;
 use crate::sdk::error::SmartyError;
 use crate::sdk::options::Options;
@@ -26,12 +28,23 @@ impl USEnrichmentClient {
         &self,
         lookup: &mut EnrichmentLookup<R>,
     ) -> Result<(), SmartyError> {
+        // Validate that address search has at least one address field
+        if lookup.is_address_search() && !lookup.has_address_fields() {
+            return Err(SmartyError::ValidationError(
+                "address search requires at least one address field (street, city, state, zipcode, or freeform)".to_string()
+            ));
+        }
+
         let mut url = self.client.url.clone();
-        url = url.join(&format!(
-            "/lookup/{}/{}",
-            lookup.smarty_key,
-            R::lookup_type()
-        ))?;
+
+        // Use "search" path for address-based lookups, smarty_key for key-based lookups
+        let key_or_search: Cow<str> = if lookup.is_address_search() {
+            "search".into()
+        } else {
+            lookup.smarty_key.to_string().into()
+        };
+
+        url = url.join(&format!("/lookup/{}/{}", key_or_search, R::lookup_type()))?;
 
         let mut req = self.client.reqwest_client.request(Method::GET, url);
 

smarty-rust-sdk/src/us_enrichment_api/lookup.rs

@@ -9,6 +9,13 @@ pub struct EnrichmentLookup<R: EnrichmentResponse> {
     pub etag: String,
     pub features: String,
     pub results: Vec<R>,
+
+    // Address search fields (used when smarty_key is not provided)
+    pub street: String,
+    pub city: String,
+    pub state: String,
+    pub zipcode: String,
+    pub freeform: String,
 }
 
 impl<R: EnrichmentResponse> EnrichmentLookup<R> {
@@ -21,9 +28,28 @@ impl<R: EnrichmentResponse> EnrichmentLookup<R> {
             has_param("include".to_string(), self.include),
             has_param("exclude".to_string(), self.exclude),
             has_param("features".to_string(), self.features),
+            has_param("street".to_string(), self.street),
+            has_param("city".to_string(), self.city),
+            has_param("state".to_string(), self.state),
+            has_param("zipcode".to_string(), self.zipcode),
+            has_param("freeform".to_string(), self.freeform),
         ]
         .into_iter()
         .flatten()
         .collect()
     }
+
+    /// Returns true if this is an address search lookup (no smarty_key provided)
+    pub fn is_address_search(&self) -> bool {
+        self.smarty_key == 0
+    }
+
+    /// Returns true if any address fields are populated
+    pub fn has_address_fields(&self) -> bool {
+        !self.street.is_empty()
+            || !self.city.is_empty()
+            || !self.state.is_empty()
+            || !self.zipcode.is_empty()
+            || !self.freeform.is_empty()
+    }
 }

smarty-rust-sdk/src/us_enrichment_api/mod.rs

@@ -55,4 +55,112 @@ mod tests {
 
         assert_eq!(lookup.into_param_array(), expected_params);
     }
+
+    #[test]
+    fn address_search_lookup_test() {
+        let lookup: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            street: "123 Main St".to_string(),
+            city: "Phoenix".to_string(),
+            state: "AZ".to_string(),
+            zipcode: "85001".to_string(),
+            ..Default::default()
+        };
+
+        assert!(lookup.is_address_search());
+
+        let expected_params = vec![
+            ("street".to_string(), "123 Main St".to_string()),
+            ("city".to_string(), "Phoenix".to_string()),
+            ("state".to_string(), "AZ".to_string()),
+            ("zipcode".to_string(), "85001".to_string()),
+        ];
+
+        assert_eq!(lookup.into_param_array(), expected_params);
+    }
+
+    #[test]
+    fn freeform_address_search_test() {
+        let lookup: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            freeform: "123 Main St, Phoenix, AZ 85001".to_string(),
+            ..Default::default()
+        };
+
+        assert!(lookup.is_address_search());
+
+        let expected_params = vec![
+            ("freeform".to_string(), "123 Main St, Phoenix, AZ 85001".to_string()),
+        ];
+
+        assert_eq!(lookup.into_param_array(), expected_params);
+    }
+
+    #[test]
+    fn smarty_key_lookup_is_not_address_search() {
+        let lookup: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            smarty_key: 123456789,
+            ..Default::default()
+        };
+
+        assert!(!lookup.is_address_search());
+    }
+
+    #[test]
+    fn has_address_fields_returns_true_when_any_field_set() {
+        let lookup_street: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            street: "123 Main St".to_string(),
+            ..Default::default()
+        };
+        assert!(lookup_street.has_address_fields());
+
+        let lookup_city: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            city: "Phoenix".to_string(),
+            ..Default::default()
+        };
+        assert!(lookup_city.has_address_fields());
+
+        let lookup_state: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            state: "AZ".to_string(),
+            ..Default::default()
+        };
+        assert!(lookup_state.has_address_fields());
+
+        let lookup_zipcode: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            zipcode: "85001".to_string(),
+            ..Default::default()
+        };
+        assert!(lookup_zipcode.has_address_fields());
+
+        let lookup_freeform: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            freeform: "123 Main St, Phoenix, AZ".to_string(),
+            ..Default::default()
+        };
+        assert!(lookup_freeform.has_address_fields());
+    }
+
+    #[test]
+    fn has_address_fields_returns_false_when_no_fields_set() {
+        let lookup: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            smarty_key: 123456789,
+            ..Default::default()
+        };
+        assert!(!lookup.has_address_fields());
+
+        let empty_lookup: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup::default();
+        assert!(!empty_lookup.has_address_fields());
+    }
+
+    #[test]
+    fn smarty_key_takes_precedence_over_address_fields() {
+        // When both smarty_key and address fields are provided, smarty_key lookup is used
+        let lookup: EnrichmentLookup<PrincipalResponse> = EnrichmentLookup {
+            smarty_key: 123456789,
+            street: "123 Main St".to_string(),
+            city: "Phoenix".to_string(),
+            ..Default::default()
+        };
+
+        assert!(!lookup.is_address_search());
+        assert!(lookup.has_address_fields());
+    }
+
 }