whos_your_daddy_common 0.2.0

//! The `congress_gov` crate contains definitions for interacting with the
//! www.gpo.congress.gov API.

// Custom crates.
use crate::error::Error;

// Public crates.
use reqwest;
use serde::Deserialize;
use serde_xml_rs::from_str;
use std::{collections::VecDeque, env};
use tracing::warn;

/// Name of the environment variable containing the API key for communicating
/// with the Congress.gov API.
pub const ENV_API_KEY: &str = "CONGRESS_GOV_API_KEY";

/// This constant defines the root URL for the Congress.gov API.
pub const ROOT_URL: &str = "https://api.congress.gov/v3";

/// This constant defines the path for requesting Congressional members from.
const MEMBERS_PATH: &str = "/member";

/// This constant defines the URL parameter string for specifying the API key
/// in requests to Congress.gov.
const API_KEY_URL_PARAM: &str = "api_key=";

//==============================================================================
// Message structures
//==============================================================================

/// This structure represents a Congressional member's depiction data from
/// Congress.gov.
#[derive(Clone, Debug, Deserialize)]
pub struct Depiction {
    /// This field contains a URL to where the Congressional member's image
    /// was sourced from.
    #[serde(rename = "attribution")]
    pub attribution: Option<String>,

    /// This field specifies the URL where the Congressional member's image
    /// is hosted.
    #[serde(rename = "imageUrl")]
    pub image_url: Option<String>,
}

/// This struct represents pagination data in responses from Congress.gov.
#[derive(Clone, Debug, Deserialize)]
pub struct Pagination {
    /// This field indicates the number of available records to page through.
    #[serde(rename = "count")]
    pub count: i32,

    /// This field specifies the next page of results available from the API.
    #[serde(rename = "next")]
    pub next: Option<String>,
}

/// This struct represents a Congressional member's single term of service.
#[derive(Clone, Debug, Deserialize)]
pub struct TermItem {
    /// This field indicates where the Congressional member served.
    #[serde(rename = "chamber")]
    pub chamber: String,

    /// This field specifies when the Congressional member's term ended.
    #[serde(rename = "endYear")]
    pub end_year: Option<i32>,

    /// This field specifies when the Congressional member's term began.
    #[serde(rename = "startYear")]
    pub start_year: i32,
}

/// The `Terms` struct contains a list of `TermItem`s.
#[derive(Clone, Debug, Deserialize)]
pub struct Terms {
    /// The terms of service related to a single member.
    pub item: Vec<TermItem>,
}

/// The `Member` struct manages all the information about a single
/// Congressional member.
#[derive(Clone, Debug, Deserialize)]
pub struct Member {
    /// The `bioguide_id` field contains a unique identifier.
    #[serde(rename = "bioguideId")]
    pub bioguide_id: String,

    /// `Depiction` instance for this Congressional member.
    #[serde(rename = "depiction")]
    pub depiction: Option<Depiction>,

    /// The `district` field indicates the Representative's home district, if
    /// applicable.
    #[serde(rename = "district")]
    pub district: Option<i32>,

    /// This is the Congressional member's name.
    #[serde(rename = "name")]
    pub name: String,

    /// This field indicates the member's political party name.
    #[serde(rename = "partyName")]
    pub party_name: String,

    /// This field contains the name of the specific U.S. State where the
    /// Congressional member represents.
    #[serde(rename = "state")]
    pub state: String,

    /// This field contains the member's terms of service.
    #[serde(rename = "terms")]
    pub terms: Terms,

    /// This field indicates the most recent data when this member's record was
    /// updated.
    #[serde(rename = "updateDate")]
    pub update_date: String,

    /// The `url` field contains a URL pointing to the current Congressional
    /// member's record within the congress.gov API.
    #[serde(rename = "url")]
    pub url: String,
}

impl Member {
    /// The `split_name` method takes the `name` field in the referenced
    /// `Member` struct and splits it into its component strings.
    ///
    /// # Returns
    /// This function returns a `Result` variant:
    /// - `Ok()` containing a tuple of the name components (first, middle,
    ///   last).
    /// - `Err()` describing the error.
    pub fn split_name(&self) -> Result<(String, Option<String>, String), Error> {
        let first_name: &str;
        let middle_name: Option<String>;

        // Check for last name comma separateor.
        if !self.name.contains(",") {
            return Err(Error::NameSplitError(format!(
                "The name {0} is not in the expected format",
                self.name
            )));
        }

        let mut parts: VecDeque<&str> = self.name.split(',').collect();

        if parts.len() < 2 {
            return Err(Error::NameSplitError(format!(
                "The name {0} did not split into the expected number of segments",
                self.name
            )));
        }

        let last_name_option = parts.pop_front();
        let second_segment_option = parts.pop_front();

        let last_name: &str = match last_name_option {
            Some(last) => last,
            None => {
                return Err(Error::NameSplitError(String::from(
                    "Failed to obtain the last name.",
                )));
            }
        };

        //======================================================================
        // Parse the first and middle names.
        let second_segment = match second_segment_option {
            Some(second_segment) => second_segment.trim_start(),
            None => {
                return Err(Error::NameSplitError(format!(
                    "The name {0} did not contain a first or middle name",
                    self.name
                )));
            }
        };

        if second_segment.contains(' ') {
            let space_index = second_segment.find(' ').unwrap();

            let (first, middle) = second_segment.split_at(space_index);

            first_name = first;

            middle_name = if middle.is_empty() {
                None
            } else {
                Some(String::from(middle))
            };
        } else {
            first_name = second_segment;
            middle_name = None;
        }

        //======================================================================
        // Final validation.
        if first_name.is_empty() {
            Err(Error::NameSplitError(String::from(
                "Failed to parse the first name segment.",
            )))
        } else if last_name.is_empty() {
            Err(Error::NameSplitError(String::from(
                "Failed to parse the last name segment.",
            )))
        } else {
            Ok((
                String::from(first_name),
                middle_name,
                String::from(last_name),
            ))
        }
    } // end split_name
}

/// This structure represents legislation information (count and URL) from
/// Congress.gov.
#[derive(Clone, Debug, Deserialize)]
pub struct LegislationInfo {
    /// This field contains the count of legislation items.
    #[serde(rename = "count")]
    pub count: i32,

    /// This field contains the URL to the legislation endpoint.
    #[serde(rename = "url")]
    pub url: String,
}

/// This structure represents a Congressional member's leadership position.
#[derive(Clone, Debug, Deserialize)]
pub struct Leadership {
    /// This field indicates the Congress number for this leadership position.
    #[serde(rename = "congress")]
    pub congress: i32,

    /// This field specifies the type of leadership position.
    #[serde(rename = "type")]
    pub leadership_type: String,
}

/// This structure represents a Congressional member's party history.
#[derive(Clone, Debug, Deserialize)]
pub struct PartyHistory {
    /// This field contains the party abbreviation (e.g., "D", "R").
    #[serde(rename = "partyAbbreviation")]
    pub party_abbreviation: String,

    /// This field contains the full party name.
    #[serde(rename = "partyName")]
    pub party_name: String,

    /// This field indicates the year when the member joined this party.
    #[serde(rename = "startYear")]
    pub start_year: i32,
}

/// This structure represents a Congressional member's expanded term of service.
#[derive(Clone, Debug, Deserialize)]
pub struct TermFull {
    /// This field indicates where the Congressional member served.
    #[serde(rename = "chamber")]
    pub chamber: String,

    /// This field indicates the Congress number for this term.
    #[serde(rename = "congress")]
    pub congress: i32,

    /// This field specifies when the Congressional member's term ended.
    #[serde(rename = "endYear")]
    pub end_year: Option<i32>,

    /// This field specifies the type of member (e.g., "Senator", "Representative").
    #[serde(rename = "memberType")]
    pub member_type: String,

    /// This field specifies when the Congressional member's term began.
    #[serde(rename = "startYear")]
    pub start_year: i32,

    /// This field contains the state code (e.g., "VT").
    #[serde(rename = "stateCode")]
    pub state_code: String,

    /// This field contains the full state name.
    #[serde(rename = "stateName")]
    pub state_name: String,
}

/// The `MemberFull` struct manages all the expanded information about a single
/// Congressional member from Congress.gov.
#[derive(Clone, Debug, Deserialize)]
pub struct MemberFull {
    /// The `bioguide_id` field contains a unique identifier.
    #[serde(rename = "bioguideId")]
    pub bioguide_id: String,

    /// This field contains the member's birth year.
    #[serde(rename = "birthYear")]
    pub birth_year: Option<String>,

    /// This field contains information about legislation the member has cosponsored.
    #[serde(rename = "cosponsoredLegislation")]
    pub cosponsored_legislation: Option<LegislationInfo>,

    /// `Depiction` instance for this Congressional member.
    #[serde(rename = "depiction")]
    pub depiction: Option<Depiction>,

    /// This field contains the member's name in direct order (e.g., "Patrick J. Leahy").
    #[serde(rename = "directOrderName")]
    pub direct_order_name: String,

    /// This field contains the member's first name.
    #[serde(rename = "firstName")]
    pub first_name: String,

    /// This field contains the member's honorific (e.g., "Mr.", "Mrs.", "Ms.").
    #[serde(rename = "honorificName")]
    pub honorific_name: Option<String>,

    /// This field contains the member's name in inverted order (e.g., "Leahy, Patrick J.").
    #[serde(rename = "invertedOrderName")]
    pub inverted_order_name: String,

    /// This field contains the member's last name.
    #[serde(rename = "lastName")]
    pub last_name: String,

    /// This field contains a list of leadership positions held by the member.
    #[serde(rename = "leadership")]
    pub leadership: Option<Vec<Leadership>>,

    /// This field contains the member's party history.
    #[serde(rename = "partyHistory")]
    pub party_history: Vec<PartyHistory>,

    /// This field contains information about legislation the member has sponsored.
    #[serde(rename = "sponsoredLegislation")]
    pub sponsored_legislation: Option<LegislationInfo>,

    /// This field contains the name of the specific U.S. State where the
    /// Congressional member represents.
    #[serde(rename = "state")]
    pub state: String,

    /// This field contains the member's terms of service in expanded format.
    #[serde(rename = "terms")]
    pub terms: Vec<TermFull>,

    /// This field indicates the most recent data when this member's record was
    /// updated.
    #[serde(rename = "updateDate")]
    pub update_date: String,
}

impl MemberFull {
    /// The `split_direct_order_name` method takes the `direct_order_name` field
    /// in the referenced `MemberFull` struct and splits it into its component
    /// strings (first, middle, last).
    ///
    /// # Returns
    /// This function returns a `Result` variant:
    /// - `Ok()` containing a tuple of the name components (first, middle, last).
    /// - `Err()` describing the error.
    pub fn split_direct_order_name(&self) -> Result<(String, Option<String>, String), Error> {
        let parts: Vec<&str> = self.direct_order_name.split_whitespace().collect();

        match parts.len() {
            0 => Err(Error::NameSplitError(format!(
                "The name {0} did not contain any segments",
                self.direct_order_name
            ))),
            1 => Err(Error::NameSplitError(format!(
                "The name {0} only contains one segment, expected at least first and last name",
                self.direct_order_name
            ))),
            2 => Ok((parts[0].to_string(), None, parts[1].to_string())),
            _ => {
                let first = parts[0].to_string();
                let last = parts[parts.len() - 1].to_string();
                let middle_parts: Vec<&str> = parts[1..parts.len() - 1].to_vec();
                let middle_str = middle_parts.join(" ").trim().to_string();

                if middle_str.is_empty() {
                    Ok((first, None, last))
                } else {
                    Ok((first, Some(middle_str), last))
                }
            }
        }
    }
}

/// The `MembersMessage` represents the HTTP response we expect to receive from
/// congress.gov after a successful request.
#[derive(Clone, Debug, Deserialize)]
pub struct MembersMessage {
    /// The `members` field is a list of Congressional Member objects from
    /// the server.
    #[serde(rename = "members")]
    pub members: Vec<Member>,

    /// The `pagination` field contains a data to page through Congressional
    /// member data on the server.
    #[serde(rename = "pagination")]
    pub pagination: Pagination,
}

/// The `MemberFullMessage` represents the HTTP response we expect to receive from
/// congress.gov after a successful request for a single member's full details.
#[derive(Clone, Debug, Deserialize)]
pub struct MemberFullMessage {
    /// The `member` field contains the full details of a single Congressional Member.
    #[serde(rename = "member")]
    pub member: MemberFull,
}

/// The `get_members` function sends a request to the congress.gov server for
/// Congressional members.
///
/// # Parameters
/// ## `offset`
/// The `offset` parameter specifies the number of entries within the server to
/// skip over.  An offset of 0 will begin with the first record.
///
/// ## `limit`
/// The `limit` parameter specifies the maximum number of member records to
/// respond with.
///
/// # Returns
/// This function returns a Result variant:
/// - `Ok()` a `MembersMessage` struct.
/// - `Err()` describing the error.
pub async fn get_members(offset: i32, limit: i32) -> Result<MembersMessage, Error> {
    let api_key = match env::var(ENV_API_KEY) {
        Ok(key) => key,
        Err(e) => return Err(Error::CongressGovApiKeyError(e.to_string())),
    };

    let url = format!(
        "{ROOT_URL}{MEMBERS_PATH}?{API_KEY_URL_PARAM}{api_key}&offset={offset}&limit={limit}"
    );

    match reqwest::get(url).await {
        Ok(response) => {

            match response.text().await {
                Ok(body) => {

                    match serde_json::from_str::<MembersMessage>(&body) {
                        Ok(member_struct) => Ok(member_struct),
                        Err(e) => {
                            Err(Error::CongressGovResponseError(
                                format!(
                                    "{}\nFailed to deserialize the response body into a MembersMessage structure: {}",
                                    body,
                                    e
                                )
                            ))
                        },
                    }
                },
                Err(e) => Err(Error::CongressGovResponseError(e.to_string())),
            }
        },
        Err(e) => Err(Error::CongressGovHttpGetError(e.to_string())),
    }
} // get_members

/// The `get_all_members` function retrieves all Congressional members from
/// congress.gov.
///
/// # Returns
/// This function returns a Result variant:
/// - `Ok()` a vector of `Member` structs for each Member received from the
///   server.
/// - `Err()` describing the error.
pub async fn get_all_members() -> Result<Vec<Member>, Error> {
    let api_key = match env::var(ENV_API_KEY) {
        Ok(key) => key,
        Err(e) => return Err(Error::CongressGovApiKeyError(e.to_string())),
    };

    // The first request will just retrieve the default number of members,
    // then we can check the pagination data in the response to figure out
    // how many members to request in the next message to get the rest of the
    // members.
    let url = format!("{ROOT_URL}{MEMBERS_PATH}?{API_KEY_URL_PARAM}{api_key}&offset=0");

    let (mut members, remaining_members): (Vec<Member>, i32) = match reqwest::get(url).await {
        Ok(response) => match response.text().await {
            Ok(body) => match serde_json::from_str::<MembersMessage>(&body) {
                Ok(member_struct) => {
                    let received_member_count: i32 = member_struct.members.len() as i32;
                    let remaining_count: i32 =
                        member_struct.pagination.count - received_member_count;

                    (member_struct.members, remaining_count)
                }
                Err(e) => {
                    return Err(Error::CongressGovResponseError(
                                format!(
                                    "{}\nFailed to deserialize the response body into a MembersMessage structure: {}",
                                    body,
                                    e
                                )
                            ));
                }
            },
            Err(e) => return Err(Error::CongressGovResponseError(e.to_string())),
        },
        Err(e) => return Err(Error::CongressGovHttpGetError(e.to_string())),
    };

    let offset = members.len();

    // Now request all the remaining members.
    let url = format!(
        "{ROOT_URL}{MEMBERS_PATH}?{API_KEY_URL_PARAM}{api_key}&offset={offset}&limit={remaining_members}"
    );

    match reqwest::get(url).await {
        Ok(response) => match response.text().await {
            Ok(body) => match serde_json::from_str::<MembersMessage>(&body) {
                Ok(mut member_struct) => {
                    members.append(&mut member_struct.members);

                    Ok(members)
                }
                Err(e) => {
                    Err(Error::CongressGovResponseError(
                                format!(
                                    "{}\nFailed to deserialize the response body into a MembersMessage structure: {}",
                                    body,
                                    e
                                )
                            ))
                }
            },
            Err(e) => Err(Error::CongressGovResponseError(e.to_string())),
        },
        Err(e) => Err(Error::CongressGovHttpGetError(e.to_string())),
    }
}

/// The `get_all_detailed_members` function retrieves all Congressional members
/// from congress.gov and then fetches the full detailed information for each
/// member by requesting individual member data using their bioguideId.
///
/// # Returns
/// This function returns a Result variant:
/// - `Ok()` a vector of `MemberFull` structs containing detailed information
///   for each Member received from the server.
/// - `Err()` describing the error.
pub async fn get_all_detailed_members() -> Result<Vec<MemberFull>, Error> {
    // First, get all members from the /member endpoint
    let members = get_all_members().await?;

    let api_key = match env::var(ENV_API_KEY) {
        Ok(key) => key,
        Err(e) => return Err(Error::CongressGovApiKeyError(e.to_string())),
    };

    let mut detailed_members = Vec::new();

    // For each member, request their full details by appending bioguideId to /member
    for member in members {
        let url = format!(
            "{ROOT_URL}{MEMBERS_PATH}/{bioguide_id}?{API_KEY_URL_PARAM}{api_key}",
            bioguide_id = member.bioguide_id
        );

        match reqwest::get(&url).await {
            Ok(response) => match response.text().await {
                Ok(body) => match serde_json::from_str::<MemberFullMessage>(&body) {
                    Ok(member_full_message) => {
                        detailed_members.push(member_full_message.member);
                    }
                    Err(_) => {
                        // If we failed to deserialize the response from JSON,
                        // try XML.
                        warn!("Failed to deserialize the response body for member {} from JSON, attempting XML.", member.bioguide_id);

                        match from_str::<MemberFullMessage>(&body) {
                            Ok(member_full) => {
                                detailed_members.push(member_full.member);
                            }
                            Err(e) => {
                                return Err(Error::CongressGovResponseError(format!(
                                    "{}\nFailed to deserialize the response body for member {} into a MemberFullMessage structure: {}",
                                    body,
                                    member.bioguide_id,
                                    e
                                )));
                            }
                        }
                    }
                },
                Err(e) => {
                    return Err(Error::CongressGovResponseError(format!(
                        "Failed to read response body for member {}: {}",
                        member.bioguide_id, e
                    )));
                }
            },
            Err(e) => {
                return Err(Error::CongressGovHttpGetError(format!(
                    "Failed to fetch detailed data for member {}: {}",
                    member.bioguide_id, e
                )));
            }
        }
    }

    Ok(detailed_members)
}

/// The `get_full_member` function requests the full congress.gov record about
/// the `Member` indicated by the given `bioguide_id` parameter.
///
/// # Parameters
/// ## `bioguide_id`
/// The `String` identifier of the congressional member to request the full
/// information.
///
/// # Returns
/// This function returns a Result variant:
/// - `Ok()` containing the `MemberFull` data on the requested congressional
///   member.
/// - `Err()` describing the error.
pub async fn get_full_member(bioguide_id: String) -> Result<MemberFull, Error> {
    let api_key = match env::var(ENV_API_KEY) {
        Ok(key) => key,
        Err(e) => return Err(Error::CongressGovApiKeyError(e.to_string())),
    };

    let url = format!("{ROOT_URL}{MEMBERS_PATH}/{bioguide_id}?{API_KEY_URL_PARAM}{api_key}");

    match reqwest::get(&url).await {
        Ok(response) => match response.text().await {
            Ok(body) => match serde_json::from_str::<MemberFullMessage>(&body) {
                Ok(member_full_message) => Ok(member_full_message.member),
                Err(_) => {
                    // If we failed to deserialize the response from JSON,
                    // try XML.
                    warn!("Failed to deserialize the response body for member {} from JSON, attempting XML.", bioguide_id);

                    match from_str::<MemberFullMessage>(&body) {
                        Ok(member_full) => {
                            Ok(member_full.member)
                        }
                        Err(e) => {
                            Err(Error::CongressGovResponseError(format!(
                                "{}\nFailed to deserialize the response body for member {} into a MemberFullMessage structure: {}",
                                body,
                                bioguide_id,
                                e
                            )))
                        }
                    }
                }
            },
            Err(e) => Err(Error::CongressGovResponseError(format!(
                "Failed to read response body for member {}: {}",
                bioguide_id, e
            ))),
        },
        Err(e) => Err(Error::CongressGovHttpGetError(format!(
            "Failed to fetch detailed data for member {}: {}",
            bioguide_id, e
        ))),
    }
} // end get_full_member

#[cfg(test)]
mod tests {
    use super::*;

    /// Test that `get_all_members` completes without errors when a valid API key is set.
    #[tokio::test]
    async fn test_get_all_members_success() {
        // This test assumes CONGRESS_GOV_API_KEY is set in the environment.
        // If it's not set, the test will fail, which is expected behavior.
        let result = get_all_members().await;

        if let Err(e) = &result {
            println!("{e}");
        }

        // Verify that no errors occurred
        assert!(
            result.is_ok(),
            "get_all_members should succeed with a valid API key"
        );

        // Verify that we got some members back
        if let Ok(members) = result {
            println!("Received {0} members.", members.len());
            assert!(
                !members.is_empty(),
                "get_all_members should return at least one member"
            );
        }
    }

    /// Helper function to create a minimal `MemberFull` instance for testing.
    /// Only the `direct_order_name` field is set; all other fields use default/empty values.
    fn create_test_member_full(direct_order_name: &str) -> MemberFull {
        MemberFull {
            bioguide_id: String::from("T000000"),
            birth_year: None,
            cosponsored_legislation: Some(LegislationInfo {
                count: 0,
                url: String::from(""),
            }),
            depiction: None,
            direct_order_name: String::from(direct_order_name),
            first_name: String::from(""),
            honorific_name: None,
            inverted_order_name: String::from(""),
            last_name: String::from(""),
            leadership: Some(Vec::new()),
            party_history: Vec::new(),
            sponsored_legislation: Some(LegislationInfo {
                count: 0,
                url: String::from(""),
            }),
            state: String::from(""),
            terms: Vec::new(),
            update_date: String::from(""),
        }
    }

    /// Test that `split_direct_order_name` returns an error for an empty string.
    #[test]
    fn test_split_direct_order_name_empty() {
        let member = create_test_member_full("");
        let result = member.split_direct_order_name();

        assert!(result.is_err(), "Empty string should return an error");
        if let Err(Error::NameSplitError(msg)) = result {
            assert!(
                msg.contains("did not contain any segments"),
                "Error message should mention no segments"
            );
        } else {
            panic!("Expected NameSplitError, got different error");
        }
    }

    /// Test that `split_direct_order_name` returns an error for a single name part.
    #[test]
    fn test_split_direct_order_name_single_part() {
        let member = create_test_member_full("John");
        let result = member.split_direct_order_name();

        assert!(result.is_err(), "Single name part should return an error");
        if let Err(Error::NameSplitError(msg)) = result {
            assert!(
                msg.contains("only contains one segment"),
                "Error message should mention one segment"
            );
        } else {
            panic!("Expected NameSplitError, got different error");
        }
    }

    /// Test that `split_direct_order_name` correctly splits a first and last name (2 parts).
    #[test]
    fn test_split_direct_order_name_two_parts() {
        let member = create_test_member_full("John Doe");
        let result = member.split_direct_order_name();

        assert!(result.is_ok(), "Two-part name should succeed");
        let (first, middle, last) = result.unwrap();
        assert_eq!(first, "John");
        assert_eq!(middle, None);
        assert_eq!(last, "Doe");
    }

    /// Test that `split_direct_order_name` correctly splits a first, middle, and last name (3 parts).
    #[test]
    fn test_split_direct_order_name_three_parts() {
        let member = create_test_member_full("John Michael Doe");
        let result = member.split_direct_order_name();

        assert!(result.is_ok(), "Three-part name should succeed");
        let (first, middle, last) = result.unwrap();
        assert_eq!(first, "John");
        assert_eq!(middle, Some(String::from("Michael")));
        assert_eq!(last, "Doe");
    }

    /// Test that `split_direct_order_name` correctly handles multiple middle names (4+ parts).
    #[test]
    fn test_split_direct_order_name_multiple_middle() {
        let member = create_test_member_full("John Michael James Doe");
        let result = member.split_direct_order_name();

        assert!(
            result.is_ok(),
            "Name with multiple middle names should succeed"
        );
        let (first, middle, last) = result.unwrap();
        assert_eq!(first, "John");
        assert_eq!(middle, Some(String::from("Michael James")));
        assert_eq!(last, "Doe");
    }

    /// Test that `split_direct_order_name` correctly handles names with extra whitespace.
    #[test]
    fn test_split_direct_order_name_extra_whitespace() {
        let member = create_test_member_full("  John   Michael   Doe  ");
        let result = member.split_direct_order_name();

        assert!(result.is_ok(), "Name with extra whitespace should succeed");
        let (first, middle, last) = result.unwrap();
        assert_eq!(first, "John");
        assert_eq!(middle, Some(String::from("Michael")));
        assert_eq!(last, "Doe");
    }

    /// Test that `split_direct_order_name` correctly handles a name with only spaces.
    #[test]
    fn test_split_direct_order_name_only_spaces() {
        let member = create_test_member_full("   ");
        let result = member.split_direct_order_name();

        assert!(
            result.is_err(),
            "Name with only spaces should return an error"
        );
        if let Err(Error::NameSplitError(msg)) = result {
            assert!(
                msg.contains("did not contain any segments"),
                "Error message should mention no segments"
            );
        } else {
            panic!("Expected NameSplitError, got different error");
        }
    }

    /// Test that `split_direct_order_name` correctly handles a real-world example.
    #[test]
    fn test_split_direct_order_name_real_world_example() {
        // Example from the documentation: "Patrick J. Leahy"
        let member = create_test_member_full("Patrick J. Leahy");
        let result = member.split_direct_order_name();

        assert!(result.is_ok(), "Real-world example should succeed");
        let (first, middle, last) = result.unwrap();
        assert_eq!(first, "Patrick");
        assert_eq!(middle, Some(String::from("J.")));
        assert_eq!(last, "Leahy");
    }

    /// Test that `split_direct_order_name` correctly handles a name with many middle parts.
    #[test]
    fn test_split_direct_order_name_many_parts() {
        let member = create_test_member_full("John A B C D E Smith");
        let result = member.split_direct_order_name();

        assert!(result.is_ok(), "Name with many parts should succeed");
        let (first, middle, last) = result.unwrap();
        assert_eq!(first, "John");
        assert_eq!(middle, Some(String::from("A B C D E")));
        assert_eq!(last, "Smith");
    }
}