br-utils 0.1.0

data/lib/brazilian-utils/boleto-utils.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module BrazilianUtils
+  module BoletoUtils
+    # Every Digitable Line from Boleto has exactly 47 characters
+    DIGITABLE_LINE_LENGTH = 47
+
+    # Positions to convert digitable line to boleto
+    DIGITABLE_LINE_TO_BOLETO_CONVERT_POSITIONS = [
+      { start: 0, end: 4 },
+      { start: 32, end: 47 },
+      { start: 4, end: 9 },
+      { start: 10, end: 20 },
+      { start: 21, end: 31 }
+    ].freeze
+
+    # Partials to verify with mod10
+    PARTIALS_TO_VERIFY_MOD10 = [
+      { start: 0, end: 9, digit_index: 9 },
+      { start: 10, end: 20, digit_index: 20 },
+      { start: 21, end: 31, digit_index: 31 }
+    ].freeze
+
+    # Mod10 weights
+    MOD10_WEIGHTS = [2, 1].freeze
+
+    # Check digit mod11 position
+    CHECK_DIGIT_MOD11_POSITION = 4
+
+    # Mod11 weights configuration
+    MOD11_WEIGHTS = {
+      initial: 2,
+      end: 9,
+      increment: 1
+    }.freeze
+
+    class << self
+      # Validates if a given Digitable Line is valid.
+      #
+      # @param digitable_line [String] The boleto digitable line to validate
+      # @return [Boolean] true if valid, false otherwise
+      def is_valid(digitable_line)
+        # Extract only numbers from the input
+        digitable_line_numbers = extract_only_numbers(digitable_line)
+
+        return false unless valid_length?(digitable_line_numbers)
+        return false unless validate_digitable_line_partials(digitable_line_numbers)
+
+        validate_mod11_check_digit(digitable_line_numbers)
+      end
+
+      # Alias for is_valid
+      alias valid? is_valid
+
+      private
+
+      # Extract only numeric characters from a string.
+      #
+      # @param str [String] The input string
+      # @return [String] String containing only numeric characters
+      def extract_only_numbers(str)
+        return '' if str.nil?
+
+        str.gsub(/\D/, '')
+      end
+
+      # Validates the string length.
+      #
+      # @param digitable_line [String] The digitable line to check
+      # @return [Boolean] true if length is exactly 47, false otherwise
+      def valid_length?(digitable_line)
+        digitable_line.length == DIGITABLE_LINE_LENGTH
+      end
+
+      # Validates the digitable line partials using mod10.
+      #
+      # @param digitable_line [String] The digitable line to validate
+      # @return [Boolean] true if all partials are valid, false otherwise
+      def validate_digitable_line_partials(digitable_line)
+        PARTIALS_TO_VERIFY_MOD10.all? do |partial|
+          partial_str = digitable_line[partial[:start]...partial[:end]]
+          mod10 = get_mod10(partial_str)
+          digit = digitable_line[partial[:digit_index]].to_i
+          digit == mod10
+        end
+      end
+
+      # Calculate mod10 for a given partial string.
+      #
+      # @param partial [String] The partial string to calculate mod10 for
+      # @return [Integer] The mod10 check digit
+      def get_mod10(partial)
+        sum = 0
+        partial_reversed = partial.reverse
+
+        partial_reversed.each_char.with_index do |char, index|
+          partial_value = char.to_i
+          weight = MOD10_WEIGHTS[index % 2]
+          multiplier = partial_value * weight
+
+          if multiplier > 9
+            sum += 1 + (multiplier % 10)
+          else
+            sum += multiplier
+          end
+        end
+
+        mod10 = sum % 10
+        if mod10 > 0
+          10 - mod10
+        else
+          0
+        end
+      end
+
+      # Validates the mod11 check digit.
+      #
+      # @param digitable_line [String] The digitable line to validate
+      # @return [Boolean] true if mod11 check digit is valid, false otherwise
+      def validate_mod11_check_digit(digitable_line)
+        parsed_digitable_line = parse_digitable_line(digitable_line)
+        
+        # Extract the value before and after the check digit position
+        value = parsed_digitable_line[0...CHECK_DIGIT_MOD11_POSITION] +
+                parsed_digitable_line[(CHECK_DIGIT_MOD11_POSITION + 1)..-1]
+        
+        mod11 = get_mod11(value)
+        mod11_value = parsed_digitable_line[CHECK_DIGIT_MOD11_POSITION].to_i
+
+        mod11_value == mod11
+      end
+
+      # Parse the digitable line by extracting specific positions.
+      #
+      # @param digitable_line [String] The digitable line to parse
+      # @return [String] The parsed digitable line
+      def parse_digitable_line(digitable_line)
+        result = ''
+        DIGITABLE_LINE_TO_BOLETO_CONVERT_POSITIONS.each do |position|
+          result += digitable_line[position[:start]...position[:end]]
+        end
+        result
+      end
+
+      # Calculate mod11 for a given value string.
+      #
+      # @param value [String] The value string to calculate mod11 for
+      # @return [Integer] The mod11 check digit
+      def get_mod11(value)
+        weight = MOD11_WEIGHTS[:initial]
+        sum = 0
+        value_reversed = value.reverse
+
+        value_reversed.each_char do |char|
+          value_value = char.to_i
+          multiplier = value_value * weight
+
+          if weight < MOD11_WEIGHTS[:end]
+            weight += MOD11_WEIGHTS[:increment]
+          else
+            weight = MOD11_WEIGHTS[:initial]
+          end
+
+          sum += multiplier
+        end
+
+        mod11 = sum % 11
+        if mod11 != 0 && mod11 != 1
+          11 - mod11
+        else
+          1
+        end
+      end
+    end
+  end
+end

data/lib/brazilian-utils/cep-utils.rb

@@ -0,0 +1,330 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
+module BrazilianUtils
+  # Custom exceptions for CEP operations
+  class InvalidCEP < StandardError; end
+  class CEPNotFound < StandardError; end
+
+  # Brazilian states enum
+  module UF
+    STATES = {
+      'AC' => 'Acre',
+      'AL' => 'Alagoas',
+      'AP' => 'Amapá',
+      'AM' => 'Amazonas',
+      'BA' => 'Bahia',
+      'CE' => 'Ceará',
+      'DF' => 'Distrito Federal',
+      'ES' => 'Espírito Santo',
+      'GO' => 'Goiás',
+      'MA' => 'Maranhão',
+      'MT' => 'Mato Grosso',
+      'MS' => 'Mato Grosso do Sul',
+      'MG' => 'Minas Gerais',
+      'PA' => 'Pará',
+      'PB' => 'Paraíba',
+      'PR' => 'Paraná',
+      'PE' => 'Pernambuco',
+      'PI' => 'Piauí',
+      'RJ' => 'Rio de Janeiro',
+      'RN' => 'Rio Grande do Norte',
+      'RS' => 'Rio Grande do Sul',
+      'RO' => 'Rondônia',
+      'RR' => 'Roraima',
+      'SC' => 'Santa Catarina',
+      'SP' => 'São Paulo',
+      'SE' => 'Sergipe',
+      'TO' => 'Tocantins'
+    }.freeze
+
+    def self.valid?(uf)
+      STATES.key?(uf.to_s.upcase)
+    end
+
+    def self.name_from_code(code)
+      STATES[code.to_s.upcase]
+    end
+
+    def self.code_from_name(name)
+      STATES.key(name)
+    end
+  end
+
+  # Address structure
+  Address = Struct.new(
+    :cep,
+    :logradouro,
+    :complemento,
+    :bairro,
+    :localidade,
+    :uf,
+    :ibge,
+    :gia,
+    :ddd,
+    :siafi,
+    keyword_init: true
+  )
+
+  module CEPUtils
+    # FORMATTING
+    ############
+
+    # Removes specific symbols from a given CEP (Postal Code).
+    #
+    # This function takes a CEP (Postal Code) as input and removes all occurrences
+    # of the '.' and '-' characters from it.
+    #
+    # @param dirty [String] The input CEP (Postal Code) containing symbols to be removed.
+    # @return [String] A new string with the specified symbols removed.
+    #
+    # @example
+    #   remove_symbols("123-45.678.9")  #=> "123456789"
+    #   remove_symbols("abc.xyz")       #=> "abcxyz"
+    def self.remove_symbols(dirty)
+      return '' unless dirty
+
+      dirty.to_s.delete('.-')
+    end
+
+    # Formats a Brazilian CEP (Postal Code) into a standard format.
+    #
+    # This function takes a CEP (Postal Code) as input and, if it is a valid
+    # 8-digit CEP, formats it into the standard "12345-678" format.
+    #
+    # @param cep [String] The input CEP (Postal Code) to be formatted.
+    # @return [String, nil] The formatted CEP in the "12345-678" format if it's valid,
+    #   nil if it's not valid.
+    #
+    # @example
+    #   format_cep("12345678")  #=> "12345-678"
+    #   format_cep("12345")     #=> nil
+    def self.format_cep(cep)
+      return nil unless valid?(cep)
+
+      "#{cep[0..4]}-#{cep[5..7]}"
+    end
+
+    # OPERATIONS
+    ############
+
+    # Checks if a CEP (Postal Code) is valid.
+    #
+    # To be considered valid, the input must be a string containing exactly 8
+    # digits.
+    # This function does not verify if the CEP is a real postal code; it only
+    # validates the format of the string.
+    #
+    # @param cep [String] The string containing the CEP to be checked.
+    # @return [Boolean] true if the CEP is valid (8 digits), false otherwise.
+    #
+    # @example
+    #   valid?("12345678")  #=> true
+    #   valid?("12345")     #=> false
+    #   valid?("abcdefgh")  #=> false
+    #
+    # @see https://en.wikipedia.org/wiki/Código_de_Endereçamento_Postal
+    def self.valid?(cep)
+      return false unless cep.is_a?(String)
+
+      cep.length == 8 && cep.match?(/^\d{8}$/)
+    end
+
+    # Generates a random 8-digit CEP (Postal Code) number as a string.
+    #
+    # @return [String] A randomly generated 8-digit number.
+    #
+    # @example
+    #   generate()  #=> "12345678"
+    def self.generate
+      8.times.map { rand(10) }.join
+    end
+
+    # API OPERATIONS
+    ################
+
+    # Fetches address information from a given CEP (Postal Code) using the ViaCEP API.
+    #
+    # @param cep [String] The CEP (Postal Code) to be used in the search.
+    # @param raise_exceptions [Boolean] Whether to raise exceptions when the CEP
+    #   is invalid or not found. Defaults to false.
+    #
+    # @raise [InvalidCEP] When the input CEP is invalid.
+    # @raise [CEPNotFound] When the input CEP is not found.
+    #
+    # @return [Address, nil] An Address object containing the address information
+    #   if the CEP is found, nil otherwise.
+    #
+    # @example
+    #   get_address_from_cep("01310100")
+    #   #=> #<Address cep="01310-100", logradouro="Avenida Paulista", ...>
+    #
+    #   get_address_from_cep("abcdefg")  #=> nil
+    #
+    #   get_address_from_cep("abcdefg", true)
+    #   #=> InvalidCEP: CEP 'abcdefg' is invalid.
+    #
+    #   get_address_from_cep("00000000", true)
+    #   #=> CEPNotFound: 00000000
+    #
+    # @see https://viacep.com.br/
+    def self.get_address_from_cep(cep, raise_exceptions: false)
+      base_api_url = 'https://viacep.com.br/ws/%s/json/'
+
+      clean_cep = remove_symbols(cep)
+      cep_is_valid = valid?(clean_cep)
+
+      unless cep_is_valid
+        raise InvalidCEP, "CEP '#{cep}' is invalid." if raise_exceptions
+
+        return nil
+      end
+
+      begin
+        uri = URI.parse(format(base_api_url, clean_cep))
+        response = Net::HTTP.get_response(uri)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise CEPNotFound, cep if raise_exceptions
+
+          return nil
+        end
+
+        data = JSON.parse(response.body)
+
+        if data['erro']
+          raise CEPNotFound, cep if raise_exceptions
+
+          return nil
+        end
+
+        Address.new(
+          cep: data['cep'],
+          logradouro: data['logradouro'],
+          complemento: data['complemento'],
+          bairro: data['bairro'],
+          localidade: data['localidade'],
+          uf: data['uf'],
+          ibge: data['ibge'],
+          gia: data['gia'],
+          ddd: data['ddd'],
+          siafi: data['siafi']
+        )
+      rescue StandardError => e
+        raise CEPNotFound, cep if raise_exceptions
+
+        nil
+      end
+    end
+
+    # Fetches CEP (Postal Code) options from a given address using the ViaCEP API.
+    #
+    # @param federal_unit [String] The two-letter abbreviation of the Brazilian state.
+    # @param city [String] The name of the city.
+    # @param street [String] The name (or substring) of the street.
+    # @param raise_exceptions [Boolean] Whether to raise exceptions when the address
+    #   is invalid or not found. Defaults to false.
+    #
+    # @raise [ArgumentError] When the input UF is invalid.
+    # @raise [CEPNotFound] When the input address is not found.
+    #
+    # @return [Array<Address>, nil] An array of Address objects containing the address
+    #   information if the address is found, nil otherwise.
+    #
+    # @example
+    #   get_cep_information_from_address("SP", "São Paulo", "Avenida Paulista")
+    #   #=> [#<Address cep="01310-100", logradouro="Avenida Paulista", ...>, ...]
+    #
+    #   get_cep_information_from_address("A", "Example", "Rua Example")  #=> nil
+    #
+    #   get_cep_information_from_address("XX", "Example", "Example", true)
+    #   #=> ArgumentError: Invalid UF: XX
+    #
+    #   get_cep_information_from_address("SP", "Example", "Example", true)
+    #   #=> CEPNotFound: SP - Example - Example
+    #
+    # @see https://viacep.com.br/
+    def self.get_cep_information_from_address(federal_unit, city, street, raise_exceptions: false)
+      base_api_url = 'https://viacep.com.br/ws/%s/%s/%s/json/'
+
+      # Validate UF
+      uf_code = federal_unit.to_s.upcase
+      uf_name = UF.name_from_code(uf_code)
+
+      unless uf_name || UF.code_from_name(federal_unit)
+        if raise_exceptions
+          raise ArgumentError, "Invalid UF: #{federal_unit}"
+        end
+
+        return nil
+      end
+
+      # Use state name if code was provided
+      uf_to_use = uf_name ? federal_unit : UF.code_from_name(federal_unit)
+
+      # Normalize and encode city and street (remove accents and encode spaces)
+      parsed_city = normalize_string(city)
+      parsed_street = normalize_string(street)
+
+      begin
+        uri = URI.parse(format(base_api_url, uf_to_use, parsed_city, parsed_street))
+        response = Net::HTTP.get_response(uri)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          if raise_exceptions
+            raise CEPNotFound, "#{federal_unit} - #{city} - #{street}"
+          end
+
+          return nil
+        end
+
+        data = JSON.parse(response.body)
+
+        if data.empty?
+          if raise_exceptions
+            raise CEPNotFound, "#{federal_unit} - #{city} - #{street}"
+          end
+
+          return nil
+        end
+
+        data.map do |address_data|
+          Address.new(
+            cep: address_data['cep'],
+            logradouro: address_data['logradouro'],
+            complemento: address_data['complemento'],
+            bairro: address_data['bairro'],
+            localidade: address_data['localidade'],
+            uf: address_data['uf'],
+            ibge: address_data['ibge'],
+            gia: address_data['gia'],
+            ddd: address_data['ddd'],
+            siafi: address_data['siafi']
+          )
+        end
+      rescue JSON::ParserError, StandardError => e
+        if raise_exceptions
+          raise CEPNotFound, "#{federal_unit} - #{city} - #{street}"
+        end
+
+        nil
+      end
+    end
+
+    private
+
+    # Normalizes a string by removing accents and encoding spaces for URL
+    def self.normalize_string(str)
+      require 'unicode_normalize/normalize'
+
+      str.to_s
+         .unicode_normalize(:nfd)
+         .encode('ASCII', undef: :replace, replace: '')
+         .gsub(' ', '%20')
+    rescue StandardError
+      # Fallback if unicode_normalize is not available
+      str.to_s.gsub(' ', '%20')
+    end
+  end
+end

data/lib/brazilian-utils/cnh-utils.rb

@@ -0,0 +1,88 @@
+module BrazilianUtils
+  module CNHUtils
+    # Validates the registration number for the Brazilian CNH (Carteira Nacional de Habilitação)
+    # that was created in 2022.
+    #
+    # Previous versions of the CNH are not supported in this version.
+    # This function checks if the given CNH is valid based on the format and allowed characters,
+    # verifying the verification digits.
+    #
+    # @param cnh [String] CNH string (symbols will be ignored).
+    # @return [Boolean] true if CNH has a valid format, false otherwise.
+    #
+    # @example
+    #   valid?("12345678901")      #=> false
+    #   valid?("A2C45678901")      #=> false
+    #   valid?("98765432100")      #=> true
+    #   valid?("987654321-00")     #=> true
+    def self.valid?(cnh)
+      return false unless cnh
+
+      # Clean the input and check for numbers only
+      clean_cnh = cnh.to_s.gsub(/\D/, '')
+
+      return false if clean_cnh.empty?
+      return false if clean_cnh.length != 11
+
+      # Reject sequences as "00000000000", "11111111111", etc.
+      return false if clean_cnh == clean_cnh[0] * 11
+
+      # Cast digits to array of integers
+      digits = clean_cnh.chars.map(&:to_i)
+      first_verificator = digits[9]
+      second_verificator = digits[10]
+
+      # Check the 10th digit
+      return false unless check_first_verificator(digits, first_verificator)
+
+      # Check the 11th digit
+      check_second_verificator(digits, second_verificator, first_verificator)
+    end
+
+    # Generates the first verification digit and uses it to verify the 10th digit of the CNH
+    #
+    # @param digits [Array<Integer>] Array of CNH digits
+    # @param first_verificator [Integer] The first verification digit (10th digit)
+    # @return [Boolean] true if the first verificator is valid
+    #
+    # @private
+    def self.check_first_verificator(digits, first_verificator)
+      sum = 0
+      9.times do |i|
+        sum += digits[i] * (9 - i)
+      end
+
+      sum = sum % 11
+      result = sum > 9 ? 0 : sum
+
+      result == first_verificator
+    end
+
+    # Generates the second verification digit and uses it to verify the 11th digit of the CNH
+    #
+    # @param digits [Array<Integer>] Array of CNH digits
+    # @param second_verificator [Integer] The second verification digit (11th digit)
+    # @param first_verificator [Integer] The first verification digit (10th digit)
+    # @return [Boolean] true if the second verificator is valid
+    #
+    # @private
+    def self.check_second_verificator(digits, second_verificator, first_verificator)
+      sum = 0
+      9.times do |i|
+        sum += digits[i] * (i + 1)
+      end
+
+      result = sum % 11
+
+      if first_verificator > 9
+        result = (result - 2).negative? ? result + 9 : result - 2
+      end
+
+      result = 0 if result > 9
+
+      result == second_verificator
+    end
+
+    private_class_method :check_first_verificator, :check_second_verificator
+  end
+end