pix-brcode-parser 0.1.0

//! # PIX BR Code Parser
//!
//! Uma biblioteca Rust para análise e validação de códigos QR PIX (BR Code) brasileiros 
//! seguindo o padrão EMV QRCPS (QR Code Payment System).
//!
//! ## Características
//!
//! - Análise de códigos QR PIX estáticos e dinâmicos
//! - Validação de conformidade com EMV QRCPS
//! - Validação de checksum CRC16
//! - API ergonômica com structs tipadas
//! - Suporte opcional ao serde para serialização
//! - Análise zero-allocation para aplicações críticas de performance
//! - Geração de códigos QR PIX
//! - Classificação automática de tipos de chave PIX
//!
//! ## Início Rápido
//!
//! ### Analisando um Código PIX
//!
//! ```rust
//! use pix_brcode_parser::{parse_brcode, BRCodeError};
//!
//! let qr_string = "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***630436D9";
//! 
//! match parse_brcode(qr_string) {
//!     Ok(brcode) => {
//!         println!("✅ Código PIX válido!");
//!         println!("Chave PIX: {}", brcode.merchant_account_info.pix_key);
//!         println!("Tipo da Chave: {:?}", brcode.pix_key_type());
//!         println!("Comerciante: {}", brcode.merchant_name);
//!         println!("Cidade: {}", brcode.merchant_city);
//!         
//!         if let Some(amount) = &brcode.transaction_amount {
//!             println!("Valor: R$ {}", amount);
//!         } else {
//!             println!("Valor: A ser definido pelo usuário");
//!         }
//!     }
//!     Err(e) => eprintln!("❌ Erro ao analisar código PIX: {}", e),
//! }
//! ```
//!
//! ### Gerando um Código PIX
//!
//! ```rust
//! use pix_brcode_parser::{BRCode, MerchantAccountInfo, generate_brcode};
//!
//! let brcode = BRCode {
//!     payload_format_indicator: "01".to_string(),
//!     point_of_initiation_method: Some("11".to_string()), // Estático
//!     merchant_account_info: MerchantAccountInfo {
//!         gui: "br.gov.bcb.pix".to_string(),
//!         pix_key: "user@example.com".to_string(),
//!         description: Some("Pagamento por serviços".to_string()),
//!         url: None,
//!     },
//!     merchant_category_code: "0000".to_string(),
//!     transaction_currency: "986".to_string(), // BRL
//!     transaction_amount: Some("25.50".to_string()),
//!     country_code: "BR".to_string(),
//!     merchant_name: "ACME CORP".to_string(),
//!     merchant_city: "SAO PAULO".to_string(),
//!     additional_data: None,
//!     crc16: String::new(), // Será calculado automaticamente
//! };
//! 
//! match generate_brcode(&brcode) {
//!     Ok(qr_string) => {
//!         println!("Código QR gerado: {}", qr_string);
//!     }
//!     Err(e) => {
//!         eprintln!("Erro ao gerar código: {}", e);
//!     }
//! }
//! ```
//!
//! ### Tipos de Chave PIX
//!
//! ```rust
//! use pix_brcode_parser::{classify_pix_key, PixKeyType};
//!
//! // Diferentes tipos de chave PIX suportados
//! assert_eq!(classify_pix_key("123e4567-e89b-12d3-a456-426614174000"), PixKeyType::Uuid);
//! assert_eq!(classify_pix_key("usuario@exemplo.com"), PixKeyType::Email);
//! assert_eq!(classify_pix_key("+5511999999999"), PixKeyType::Phone);
//! assert_eq!(classify_pix_key("12345678901"), PixKeyType::Cpf);
//! assert_eq!(classify_pix_key("12345678000195"), PixKeyType::Cnpj);
//! ```
//!
//! ## Tratamento de Erros
//!
//! ```rust
//! use pix_brcode_parser::{parse_brcode, BRCodeError};
//!
//! match parse_brcode("codigo_invalido") {
//!     Err(BRCodeError::InvalidChecksum) => {
//!         println!("Checksum inválido - código pode estar corrompido");
//!     }
//!     Err(BRCodeError::InvalidGui(gui)) => {
//!         println!("GUI inválido: esperado 'br.gov.bcb.pix', encontrado: {}", gui);
//!     }
//!     Err(BRCodeError::MissingField(field)) => {
//!         println!("Campo obrigatório ausente: {}", field);
//!     }
//!     _ => {}
//! }
//! ```
//!
//! ## Validações
//!
//! Esta biblioteca implementa todas as validações necessárias:
//!
//! - **Checksum CRC16**: Validação completa usando CRC-16/CCITT-FALSE
//! - **GUI PIX**: Deve ser "br.gov.bcb.pix"
//! - **Código da Moeda**: Deve ser "986" (Real Brasileiro)  
//! - **Código do País**: Deve ser "BR"
//! - **Limites de Campo**: Nome do comerciante (25 chars), cidade (15 chars)
//! - **Formato da Chave PIX**: Validação de caracteres e formato

pub mod error;
pub mod parser;
pub mod types;
pub mod validation;

pub use error::BRCodeError;
pub use parser::{parse_brcode, generate_brcode};
pub use types::*;
pub use validation::validate_crc16;

/// Parse a PIX BR Code string into a structured format
pub fn parse(input: &str) -> Result<BRCode, BRCodeError> {
    parse_brcode(input)
}

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

    #[test]
    fn test_valid_static_pix_qr() {
        let qr = "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***630436D9";
        let result = parse_brcode(qr);
        assert!(result.is_ok());
    }

    #[test]
    fn test_invalid_crc() {
        let qr = "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***6304ABCD";
        let result = parse_brcode(qr);
        assert!(matches!(result, Err(BRCodeError::InvalidChecksum)));
    }
}