ev_lib 0.6.4

//! `types` — shared domain TypeObjects (mirrors `@evinvest/types`).
//!
//! Zero runtime deps, wasm-safe, no I/O. Each type is a branded newtype with a
//! validating constructor and formatting/display methods.
//!
//! # Types
//!
//! - [`PhoneNumber`] — E.164 phone number: `+` followed by 7–15 digits with a
//!   known country-code prefix (ITU-T zones 1–9). Construct with
//!   [`PhoneNumber::from`] (validating), [`PhoneNumber::from_unchecked`] (trusted
//!   source), or [`PhoneNumber::parse_input`] (forgiving user input).
//! - [`Branded`] — the generic newtype pattern reusable for future types (Email,
//!   Currency, …).

use core::fmt;

// ── Branded ────────────────────────────────────────────────────────────────────

const COUNTRY_CODES: &[&str] = &[
	// Zone 1 — North American Numbering Plan
	"1", // Zone 2 — Africa
	"20", "211", "212", "213", "216", "218", "220", "221", "222", "223", "224", "225", "226", "227", "228", "229", "230", "231", "232", "233", "234", "235", "236", "237", "238", "239",
	"240", "241", "242", "243", "244", "245", "246", "247", "248", "249", "250", "251", "252", "253", "254", "255", "256", "257", "258", "260", "261", "262", "263", "264", "265", "266",
	"267", "268", "269", // Zone 3 — Europe
	"30", "31", "32", "33", "34", "350", "351", "352", "353", "354", "355", "356", "357", "358", "359", // Zone 4 — Europe (cont.)
	"36", "370", "371", "372", "373", "374", "375", "376", "377", "378", "379", "380", "381", "382", "383", "385", "386", "387", "389", "40", "41", "42", "43", "44", "45", "46", "47", "48",
	"49", // Zone 5 — South/Latin America
	"500", "501", "502", "503", "504", "505", "506", "507", "508", "509", "51", "52", "53", "54", "55", "56", "57", "58", "590", "591", "592", "593", "594", "595", "596", "597", "598",
	"599", // Zone 6 — Southeast Asia / Oceania
	"60", "61", "62", "63", "64", "65", "66", "670", "672", "673", "674", "675", "676", "677", "678", "679", "680", "681", "682", "683", "685", "686", "687", "688", "689", "690", "691",
	"692", // Zone 7 — Russia, Kazakhstan
	"7",   // Zone 8 — East Asia / Special services
	"81", "82", "83", "84", "850", "852", "853", "855", "856", "86", "870", "872", "873", "874", "878", "879", "880", "881", "882", "883", "886", "888",
	// Zone 9 — West/South Asia
	"90", "91", "92", "93", "94", "95", "960", "961", "962", "963", "964", "965", "966", "967", "968", "969", "970", "971", "972", "973", "974", "975", "976", "977", "979", "98", "992",
	"993", "994", "995", "996", "998",
];
/// A branded wrapper — zero-overhead newtype with a compile-time phantom tag.
///
/// Use this to create distinct, incompatible types from the same underlying
/// representation (e.g. `Branded<String, PhoneNumberTag>` vs
/// `Branded<String, EmailTag>`).
///
/// # Example
///
/// ```
/// use ev_lib::types::Branded;
///
/// struct EmailTag;
/// type Email = Branded<String, EmailTag>;
///
/// let email = Email::new("a@b.com".into());
/// assert_eq!(email.as_inner(), "a@b.com");
/// ```
#[repr(transparent)]
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct Branded<T, B> {
	value: T,
	_brand: core::marker::PhantomData<B>,
}

impl<T, B> Branded<T, B> {
	/// Wrap a value without validation. The brand provides type safety at
	/// compile time; the caller is responsible for any runtime invariants.
	pub const fn new(value: T) -> Self {
		Self {
			value,
			_brand: core::marker::PhantomData,
		}
	}

	/// Recover the underlying value.
	pub fn into_inner(self) -> T {
		self.value
	}

	/// Borrow the underlying value.
	pub fn as_inner(&self) -> &T {
		&self.value
	}
}

// ── PhoneNumber ────────────────────────────────────────────────────────────────

/// Brand tag for [`PhoneNumber`].
pub struct PhoneNumberTag;

/// An E.164 phone number, validated at construction time.
///
/// Canonical form: `+<country code><subscriber number>`, e.g. `+12345678901`.
/// No spaces, hyphens, or other separators — just `+` and digits.
pub type PhoneNumber = Branded<String, PhoneNumberTag>;

/// Validation error returned by [`PhoneNumber::validate`] and
/// [`PhoneNumber::from`].
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum PhoneNumberError {
	/// Input was empty.
	Empty,
	/// Must start with `+`.
	NoPlusPrefix,
	/// Only digits allowed after the `+`.
	NonDigitChars,
	/// Too few digits after `+` (minimum 7).
	TooShort { actual: usize },
	/// Too many digits after `+` (maximum 15).
	TooLong { actual: usize },
	/// Country code prefix is not in the known set.
	InvalidCountryCode,
}

impl PhoneNumberError {
	/// Machine-readable code — stable across versions.
	pub fn code(&self) -> &'static str {
		match self {
			Self::Empty => "empty",
			Self::NoPlusPrefix => "no_plus_prefix",
			Self::NonDigitChars => "non_digit_chars",
			Self::TooShort { .. } => "too_short",
			Self::TooLong { .. } => "too_long",
			Self::InvalidCountryCode => "invalid_country_code",
		}
	}
}

impl fmt::Display for PhoneNumberError {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		match self {
			Self::Empty => f.write_str("Phone number must not be empty"),
			Self::NoPlusPrefix => f.write_str("Phone number must start with +"),
			Self::NonDigitChars => f.write_str("Phone number must contain only digits after the +"),
			Self::TooShort { actual } => write!(f, "Phone number must have at least 7 digits (has {actual})"),
			Self::TooLong { actual } => write!(f, "Phone number must have at most 15 digits (has {actual})"),
			Self::InvalidCountryCode => f.write_str("Unknown country code"),
		}
	}
}

impl PhoneNumber {
	/// Maximum digits after the `+` (ITU-T E.164 limit).
	pub const MAX_DIGITS: usize = 15;
	/// Minimum digits after the `+`.
	pub const MIN_DIGITS: usize = 7;

	// -- Construction ---------------------------------------------------------------

	/// Validate and construct a `PhoneNumber`.
	///
	/// Returns [`PhoneNumberError`] on invalid input. Use
	/// [`PhoneNumber::from_unchecked`] to skip validation for trusted sources.
	pub fn from(value: String) -> Result<Self, PhoneNumberError> {
		Self::validate(&value)?;
		Ok(Self::from_unchecked(value))
	}

	/// Construct a `PhoneNumber` from a trusted source without validation.
	///
	/// The caller guarantees the value is a valid E.164 string. Use this when
	/// deserialising from a database or an already-validated API response —
	/// never on user input.
	pub fn from_unchecked(value: String) -> Self {
		Self::new(value)
	}

	/// Recover the underlying E.164 string.
	pub fn as_str(&self) -> &str {
		self.as_inner()
	}

	// -- Validation ----------------------------------------------------------------

	/// Validate without constructing. Returns `Ok(())` or a structured error.
	///
	/// Rules:
	/// 1. Non-empty
	/// 2. Must start with `+`
	/// 3. Only digits after `+`
	/// 4. 7–15 digits after `+`
	/// 5. Country code must be in the known ITU-T range (1–3 digits)
	pub fn validate(value: &str) -> Result<(), PhoneNumberError> {
		if value.is_empty() {
			return Err(PhoneNumberError::Empty);
		}
		if !value.starts_with('+') {
			return Err(PhoneNumberError::NoPlusPrefix);
		}
		let digits = &value[1..];
		if digits.is_empty() || !digits.chars().all(|c| c.is_ascii_digit()) {
			return Err(PhoneNumberError::NonDigitChars);
		}
		let n = digits.len();
		if n < Self::MIN_DIGITS {
			return Err(PhoneNumberError::TooShort { actual: n });
		}
		if n > Self::MAX_DIGITS {
			return Err(PhoneNumberError::TooLong { actual: n });
		}
		if !is_valid_country_code(digits) {
			return Err(PhoneNumberError::InvalidCountryCode);
		}
		Ok(())
	}

	/// Runtime type guard — returns `true` when `value` is a valid E.164 string.
	pub fn is_phone_number(value: &str) -> bool {
		Self::validate(value).is_ok()
	}

	// -- Formatting ----------------------------------------------------------------

	/// Format for human display: `+1 234 567 8901`.
	///
	/// Groups national digits left-to-right in chunks of 3, with the
	/// rightmost group getting the remainder. The separator defaults to
	/// a space.
	///
	/// This is a generic heuristic — a correct per-country formatter would
	/// require a full numbering-plan database. The output is always a
	/// readable, dialable string.
	pub fn format(&self, separator: &str) -> String {
		let raw = self.as_str();
		let digits = &raw[1..]; // skip '+'
		let Some(cc_len) = country_code_len(digits) else { return raw.to_owned() };
		let national = &digits[cc_len..];
		let n = national.len();
		let num_full = n / 3;
		let remainder = n % 3;

		let mut out = String::with_capacity(raw.len() + n / 3 + 2);
		out.push('+');
		out.push_str(&digits[..cc_len]);
		if n == 0 {
			return out;
		}
		out.push_str(separator);

		if num_full <= 1 {
			out.push_str(national);
		} else if remainder == 0 {
			for i in 0..num_full {
				if i > 0 {
					out.push_str(separator);
				}
				out.push_str(&national[i * 3..(i + 1) * 3]);
			}
		} else {
			for i in 0..num_full - 1 {
				if i > 0 {
					out.push_str(separator);
				}
				out.push_str(&national[i * 3..(i + 1) * 3]);
			}
			out.push_str(separator);
			out.push_str(&national[(num_full - 1) * 3..]);
		}
		out
	}

	/// Format for dialing from a local line — the `+` is replaced with the
	/// local international prefix (default `00`). `00 1 234 567 8901`
	pub fn format_local(&self, prefix: &str, separator: &str) -> String {
		let international = Self::format(self, separator);
		let mut out = String::with_capacity(prefix.len() + international.len());
		out.push_str(prefix);
		out.push_str(separator);
		out.push_str(&international[1..]); // skip '+'
		out
	}

	// -- User-input parsing --------------------------------------------------------

	/// Parse loosely-formatted user input into a `PhoneNumber`.
	///
	/// Strips common formatting characters (spaces, hyphens, dots, parentheses),
	/// ensures a leading `+`, and validates. Returns `None` on invalid input.
	pub fn parse_input(raw: &str) -> Option<Self> {
		let stripped: String = raw.chars().filter(|c| !matches!(c, ' ' | '-' | '.' | '(' | ')')).collect();
		let normalised = if stripped.starts_with('+') { stripped } else { format!("+{stripped}") };
		Self::validate(&normalised).ok()?;
		Some(Self::from_unchecked(normalised))
	}
}

impl fmt::Display for PhoneNumber {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		f.write_str(self.as_str())
	}
}

// ── Country-code table ─────────────────────────────────────────────────────────

// Country codes (1–3 digits, ITU-T zones 1–9). Tried longest-first so
// e.g. "1242" (Bahamas) matches before "1" (NANP).

/// Returns the country code length in `digits` (a string of ASCII digits), or
/// `None` if no known country code matches.
fn country_code_len(digits: &str) -> Option<usize> {
	for &len in &[3u8, 2, 1] {
		if digits.len() >= len as usize {
			let prefix = &digits[..len as usize];
			if COUNTRY_CODES.contains(&prefix) {
				return Some(len as usize);
			}
		}
	}
	None
}

fn is_valid_country_code(digits: &str) -> bool {
	country_code_len(digits).is_some()
}

// ── Tests ──────────────────────────────────────────────────────────────────────

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

	// -- validate --

	#[test]
	fn accepts_valid_e164_numbers() {
		let cases = [
			"+12345678901",   // US
			"+442012345678",  // UK
			"+8613812345678", // China
			"+79161234567",   // Russia
			"+85212345678",   // Hong Kong (3-digit cc)
			"+12421234567",   // Bahamas (4-digit cc starting with 1)
		];
		for raw in cases {
			assert!(PhoneNumber::validate(raw).is_ok(), "should accept {raw}");
		}
	}

	#[test]
	fn rejects_empty() {
		let err = PhoneNumber::validate("").unwrap_err();
		assert_eq!(err.code(), "empty");
	}

	#[test]
	fn rejects_no_plus() {
		let err = PhoneNumber::validate("12345678901").unwrap_err();
		assert_eq!(err.code(), "no_plus_prefix");
	}

	#[test]
	fn rejects_spaces_in_canonical_form() {
		let err = PhoneNumber::validate("+1 234 567 8901").unwrap_err();
		assert_eq!(err.code(), "non_digit_chars");
	}

	#[test]
	fn rejects_parentheses_and_hyphens() {
		assert!(PhoneNumber::validate("+1(234)5678901").is_err());
		assert!(PhoneNumber::validate("+1-234-567-8901").is_err());
	}

	#[test]
	fn rejects_too_short() {
		let err = PhoneNumber::validate("+123456").unwrap_err();
		assert_eq!(err.code(), "too_short");
	}

	#[test]
	fn rejects_too_long() {
		let err = PhoneNumber::validate("+1234567890123456").unwrap_err();
		assert_eq!(err.code(), "too_long");
	}

	#[test]
	fn rejects_unknown_country_code() {
		let err = PhoneNumber::validate("+9991234567").unwrap_err();
		assert_eq!(err.code(), "invalid_country_code");
	}

	#[test]
	fn boundary_min_7() {
		assert!(PhoneNumber::validate("+7123456").is_ok()); // 1-digit cc + 6 national
	}

	#[test]
	fn boundary_max_15() {
		assert!(PhoneNumber::validate("+123456789012345").is_ok()); // cc 1 + 14 digits
	}

	// -- from / from_unchecked --

	#[test]
	fn from_constructs_valid() {
		let pn = PhoneNumber::from("+12345678901".into()).unwrap();
		assert_eq!(pn.as_str(), "+12345678901");
	}

	#[test]
	fn from_rejects_invalid() {
		assert!(PhoneNumber::from("bad".into()).is_err());
	}

	#[test]
	fn from_unchecked_skips_validation() {
		let pn = PhoneNumber::from_unchecked(String::new());
		assert_eq!(pn.as_str(), "");
	}

	// -- is_phone_number --

	#[test]
	fn is_phone_number_type_guard() {
		assert!(PhoneNumber::is_phone_number("+12345678901"));
		assert!(!PhoneNumber::is_phone_number(""));
		assert!(!PhoneNumber::is_phone_number("+1"));
	}

	// -- format --

	#[test]
	fn format_us() {
		let pn = PhoneNumber::from("+12345678901".into()).unwrap();
		assert_eq!(pn.format(" "), "+1 234 567 8901");
	}

	#[test]
	fn format_uk() {
		let pn = PhoneNumber::from("+442012345678".into()).unwrap();
		assert_eq!(pn.format(" "), "+44 201 234 5678");
	}

	#[test]
	fn format_custom_separator() {
		let pn = PhoneNumber::from("+12345678901".into()).unwrap();
		assert_eq!(pn.format("-"), "+1-234-567-8901");
	}

	// -- format_local --

	#[test]
	fn format_local_default() {
		let pn = PhoneNumber::from("+12345678901".into()).unwrap();
		assert_eq!(pn.format_local("00", " "), "00 1 234 567 8901");
	}

	// -- parse_input --

	#[test]
	fn parse_input_strips_spaces() {
		let pn = PhoneNumber::parse_input("+1 234 567 8901").unwrap();
		assert_eq!(pn.as_str(), "+12345678901");
	}

	#[test]
	fn parse_input_strips_hyphens_and_adds_plus() {
		let pn = PhoneNumber::parse_input("1-234-567-8901").unwrap();
		assert_eq!(pn.as_str(), "+12345678901");
	}

	#[test]
	fn parse_input_strips_parentheses() {
		let pn = PhoneNumber::parse_input("+1 (234) 567-8901").unwrap();
		assert_eq!(pn.as_str(), "+12345678901");
	}

	#[test]
	fn parse_input_returns_none_for_invalid() {
		assert!(PhoneNumber::parse_input("short").is_none());
		assert!(PhoneNumber::parse_input("").is_none());
	}

	// -- Display --

	#[test]
	fn display_returns_canonical_e164() {
		let pn = PhoneNumber::from("+12345678901".into()).unwrap();
		assert_eq!(format!("{pn}"), "+12345678901");
	}

	// -- Branded --

	#[test]
	fn branded_round_trip() {
		struct EmailTag;
		type Email = Branded<String, EmailTag>;
		let email = Email::new("a@b.com".into());
		assert_eq!(email.as_inner(), "a@b.com");
		assert_eq!(email.into_inner(), "a@b.com");
	}
}