//! Policy builder trait definition.

use crate::error::LastIDError;
use crate::types::CredentialPolicyRequest;

/// Common interface for all policy builders.
///
/// This trait enables polymorphism across different credential types while
/// maintaining compile-time type safety through the type-state pattern.
///
/// # Type-State Pattern
///
/// Policy builders use phantom types to track whether required fields have been
/// set:
/// - `PolicyBuilder<Incomplete>` - Missing required fields, cannot build
/// - `PolicyBuilder<Complete>` - All required fields set, can build
///
/// Only `Complete` state implements this trait.
///
/// # Example
///
/// ```rust,no_run
/// use lastid_sdk::policies::BaseCredentialPolicy;
/// use lastid_sdk::PolicyBuilder;
///
/// // Type-safe: only complete policies can be used
/// let policy =
///     BaseCredentialPolicy::new().with_callback("https://example.com");
///
/// // This compiles because with_callback() returns Complete state
/// let request = policy.to_request().unwrap();
/// ```
pub trait PolicyBuilder {
    /// Get the credential type string.
    ///
    /// Returns the credential type identifier used in IDP requests.
    fn credential_type(&self) -> &'static str;

    /// Build the credential policy request.
    ///
    /// Consumes the builder and produces a serializable request.
    ///
    /// # Errors
    ///
    /// Returns `LastIDError::PolicyValidation` if runtime validation fails.
    #[must_use = "this method consumes the policy and returns a request that should be used"]
    fn to_request(self) -> Result<CredentialPolicyRequest, LastIDError>;
}
