br-utils 0.1.0 → 0.2.0

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

@@ -0,0 +1,58 @@
+require 'json'
+require_relative 'text-utils'
+
+module BrazilianUtils
+  # Utilities for looking up Brazilian municipalities by IBGE code, sourced
+  # from the IBGE Localidades API (5,571 municipalities).
+  module MunicipalityUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'municipalities.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # @private
+    def self.to_symbolized(row)
+      { code: row['code'], name: row['name'], stateCode: row['stateCode'] }
+    end
+
+    private_class_method :to_symbolized
+
+    # Looks a municipality up by its 7-digit IBGE code.
+    #
+    # @param code [String, Integer]
+    # @return [Hash, nil]
+    def self.get_by_code(code)
+      return nil if code.nil?
+
+      str = code.to_s.gsub(/\D/, '')
+      return nil unless str.length == 7
+
+      row = load_data.find { |r| r['code'] == str }
+      row && to_symbolized(row)
+    end
+
+    # Returns Brazilian municipalities, sorted by name (pt-BR collation).
+    #
+    # @param state_code [String, nil] Only that state's municipalities; when
+    #   omitted, every municipality. An empty or unknown code returns an
+    #   empty list (matching is case-sensitive).
+    # @return [Array<Hash>]
+    def self.list(state_code = nil)
+      rows = load_data
+
+      unless state_code.nil?
+        return [] unless state_code.is_a?(String) && !state_code.empty?
+
+        rows = rows.select { |r| r['stateCode'] == state_code }
+      end
+
+      rows
+        .sort_by { |r| TextUtils.remove_accents(r['name']).downcase }
+        .map { |r| to_symbolized(r) }
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for the NCM (Nomenclatura Comum do Mercosul) table, the
+  # current 8-digit ("leaf") code list published by Siscomex.
+  module NCMUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'ncm.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # @private
+    def self.apply_mask(digits, group_sizes, separators)
+      chunks = []
+      idx = 0
+      group_sizes.each do |size|
+        break if idx >= digits.length
+
+        chunks << digits[idx, size]
+        idx += size
+      end
+      chunks.each_with_index.map { |c, i| i.zero? ? c : "#{separators[i - 1]}#{c}" }.join
+    end
+
+    private_class_method :apply_mask
+
+    # Normalizes an NCM value to its bare 8 digits: bare digits (string or
+    # integer) are left-padded with zeros to 8; the `NNNN.NN.NN` mask is
+    # read as written. Any other string is rejected.
+    #
+    # @private
+    def self.normalize(value)
+      return nil if value.nil?
+      return value.to_s.rjust(8, '0') if value.is_a?(Integer)
+      return nil unless value.is_a?(String)
+
+      raw = value.strip
+      return raw.rjust(8, '0') if raw.match?(/\A\d+\z/)
+
+      m = raw.match(/\A(\d{4})\.(\d{2})\.(\d{2})\z/)
+      m && "#{m[1]}#{m[2]}#{m[3]}"
+    end
+
+    private_class_method :normalize
+
+    # Formats an NCM code with the mask `NNNN.NN.NN`; the mask is applied
+    # as far as the digits go (only the structure changes — use {is_valid}
+    # to check the code).
+    #
+    # @param value [String, Integer]
+    # @param options [Hash] `:pad` left-pads with zeros to 8 digits first.
+    # @return [String] An empty string when there is no digit at all.
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(8, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, [4, 2, 2], ['.', '.'])
+    end
+
+    # Checks whether an NCM code exists in the current table.
+    #
+    # @param value [String, Integer]
+    # @return [Boolean]
+    def self.is_valid(value)
+      code = normalize(value)
+      return false unless code
+
+      load_data.key?(code)
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Removes NCM formatting and keeps only digits, capped to 8 digits
+    # (nothing is left-padded).
+    #
+    # @param value [String, Integer]
+    # @return [String]
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 8]
+    end
+  end
+end

data/lib/brazilian-utils/nfe-key-utils.rb

@@ -0,0 +1,158 @@
+require_relative 'state-utils'
+
+module BrazilianUtils
+  # Utilities for the 44-digit DF-e (Documento Fiscal eletrônico) access
+  # key shared by NF-e, NFC-e, CT-e, MDF-e, CT-e OS, GTV-e, BP-e, NF3e and
+  # NFCom.
+  #
+  # @note For NFCom and NF3e (models 62 and 66) the numeric code (`cNF`)
+  #   field is 7 digits rather than 8, which shifts the rest of the key;
+  #   no test case exercised these two models, so {get_info} always uses
+  #   the general 8-digit layout. Its `code`/`model` fields for a 62/66 key
+  #   should be treated as unverified.
+  module NfeKeyUtils
+    LENGTH = 44
+
+    ID_PREFIXES = %w[NFCom NF3e NFe CTe MDFe BPe].freeze
+
+    VALID_MODELS = %w[55 65 57 58 67 64 63 66 62].freeze
+
+    # @private
+    def self.apply_mask(digits, group_size)
+      digits.chars.each_slice(group_size).map(&:join).join(' ')
+    end
+
+    private_class_method :apply_mask
+
+    # @private
+    def self.strip_id_prefix(raw)
+      prefix = ID_PREFIXES.find { |p| raw.start_with?(p) }
+      prefix ? raw[prefix.length..-1] : raw
+    end
+
+    private_class_method :strip_id_prefix
+
+    # Removes the formatting of a DF-e access key and keeps only digits,
+    # capped to 44 digits. The XML `Id` prefixes are stripped first.
+    #
+    # @param value [String, Integer]
+    # @return [String]
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      raw = strip_id_prefix(value.to_s)
+      raw.gsub(/\D/, '')[0, LENGTH]
+    end
+
+    # Formats a DF-e access key into groups of 4 digits separated by
+    # spaces. Does not validate (use {is_valid}).
+    #
+    # @param value [String]
+    # @param options [Hash] `:pad` left-pads with zeros to 44 digits first.
+    # @return [String]
+    def self.format(value, options = {})
+      raw = value.is_a?(String) ? strip_id_prefix(value) : value.to_s
+      digits = raw.gsub(/\D/, '')
+      digits = digits.rjust(LENGTH, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, 4)
+    end
+
+    # @private
+    def self.normalize(value)
+      return nil unless value.is_a?(String)
+
+      raw = strip_id_prefix(value.strip)
+      return nil if raw.empty?
+
+      digits = raw.gsub(%r{[\s.\-/]}, '')
+      digits.match?(/\A\d{#{LENGTH}}\z/) ? digits : nil
+    end
+
+    private_class_method :normalize
+
+    # @private
+    def self.check_digit(base43)
+      weights = []
+      w = 2
+      base43.length.times do
+        weights << w
+        w = w == 9 ? 2 : w + 1
+      end
+      weights.reverse!
+
+      sum = base43.chars.each_with_index.sum { |d, i| d.to_i * weights[i] }
+      r = sum % 11
+      r < 2 ? 0 : 11 - r
+    end
+
+    private_class_method :check_digit
+
+    # @private
+    def self.cnf_ok?(cnf, nnf)
+      return false if cnf.chars.uniq.length == 1
+      return false if cnf.to_i == nnf.to_i
+
+      digits = cnf.chars.map(&:to_i)
+      ascending = digits.each_cons(2).all? { |a, b| b == (a + 1) % 10 }
+      descending = digits.each_cons(2).all? { |a, b| b == (a - 1) % 10 }
+
+      !(ascending || descending)
+    end
+
+    private_class_method :cnf_ok?
+
+    # Validates a 44-digit DF-e access key.
+    #
+    # @param value [String]
+    # @return [Boolean]
+    def self.is_valid(value)
+      digits = normalize(value)
+      return false unless digits
+
+      cuf = digits[0, 2]
+      model = digits[20, 2]
+      nnf = digits[25, 9]
+      tpemis = digits[34, 1]
+      cnf = digits[35, 8]
+      cdv = digits[43, 1]
+
+      return false unless StateUtils.get_by_ibge_code(cuf)
+      return false unless VALID_MODELS.include?(model)
+      return false unless tpemis.match?(/\A[1-9]\z/)
+      return false if nnf.to_i.zero?
+      return false if %w[55 65].include?(model) && !cnf_ok?(cnf, nnf)
+
+      cdv.to_i == check_digit(digits[0, 43])
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Parses a DF-e access key into its fields.
+    #
+    # @param value [String]
+    # @return [Hash, nil] `nil` whenever {is_valid} would return false.
+    def self.get_info(value)
+      return nil unless is_valid(value)
+
+      digits = normalize(value)
+      state = StateUtils.get_by_ibge_code(digits[0, 2])
+
+      {
+        stateCode: state[:code],
+        year: 2000 + digits[2, 2].to_i,
+        month: digits[4, 2].to_i,
+        taxId: digits[6, 14],
+        model: digits[20, 2],
+        series: digits[22, 3].to_i,
+        number: digits[25, 9].to_i,
+        emissionType: digits[34, 1].to_i,
+        code: digits[35, 8],
+        checkDigit: digits[43, 1].to_i
+      }
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module BrazilianUtils
+  # Utilities for writing numbers in Brazilian Portuguese cardinal words
+  # ("por extenso"), e.g. `1235` becomes `"mil duzentos e trinta e cinco"`.
+  module NumberUtils
+    MAX_ABS_VALUE = 999_999_999_999_999
+
+    FEMININE_GENDERS = %i[feminine feminino f].freeze
+
+    # Writes an integer in Brazilian Portuguese cardinal words.
+    #
+    # @param value [Numeric] The number to convert. Accepts integers from
+    #   -999,999,999,999,999 to 999,999,999,999,999; a non-integer is
+    #   truncated toward zero.
+    # @param options [Hash] `:gender` (`:masculine`, default, or
+    #   `:feminine`) agrees "um/uma", "dois/duas" and the hundreds.
+    # @return [String] The textual representation, or an empty string for a
+    #   value outside the supported range or not finite.
+    #
+    # @example
+    #   convert_to_words(1235)     #=> "mil duzentos e trinta e cinco"
+    #   convert_to_words(100)      #=> "cem"
+    #   convert_to_words(-3)       #=> "menos três"
+    #   convert_to_words(2, gender: :feminine) #=> "duas"
+    def self.convert_to_words(value, options = {})
+      return '' unless value.is_a?(Numeric)
+      return '' if value.respond_to?(:finite?) && !value.finite?
+
+      int_value = value.to_i
+      return '' if int_value.abs > MAX_ABS_VALUE
+
+      gender = (options[:gender] || options['gender'] || :masculine).to_sym
+      negative = int_value.negative?
+      words = number_to_words(int_value.abs, gender)
+      negative ? "menos #{words}" : words
+    end
+
+    # @private
+    def self.number_to_words(number, gender = :masculine)
+      return 'zero' if number.zero?
+
+      scales = ['', 'mil', 'milhão', 'bilhão', 'trilhão']
+      scales_plural = ['', 'mil', 'milhões', 'bilhões', 'trilhões']
+
+      groups = []
+      temp = number
+      while temp > 0
+        groups << temp % 1000
+        temp /= 1000
+      end
+
+      parts = []
+      groups.each_with_index do |group, index|
+        next if group.zero?
+
+        group_text = convert_group(group, gender)
+        scale_name = group == 1 ? scales[index] : scales_plural[index]
+
+        parts << if scale_name.empty?
+                   group_text
+                 elsif index == 1 && group == 1
+                   scale_name
+                 else
+                   "#{group_text} #{scale_name}"
+                 end
+      end
+
+      parts.reverse!
+      return parts.first if parts.length == 1
+
+      final_group = groups.find { |g| !g.zero? }
+      last = parts.pop
+      separator = (final_group < 100 || (final_group % 100).zero?) ? ' e ' : ' '
+      "#{parts.join(' ')}#{separator}#{last}"
+    end
+
+    private_class_method :number_to_words
+
+    # @private
+    def self.convert_group(number, gender = :masculine)
+      feminine = FEMININE_GENDERS.include?(gender)
+
+      ones = %w[zero um dois três quatro cinco seis sete oito nove]
+      ones_fem = %w[zero uma duas três quatro cinco seis sete oito nove]
+      tens = %w[dez onze doze treze quatorze quinze dezesseis dezessete dezoito dezenove]
+      tens_multiples = %w[_ _ vinte trinta quarenta cinquenta sessenta setenta oitenta noventa]
+      hundreds_m = %w[
+        _ cento duzentos trezentos quatrocentos quinhentos seiscentos setecentos oitocentos novecentos
+      ]
+      hundreds_f = %w[
+        _ cento duzentas trezentas quatrocentas quinhentas seiscentas setecentas oitocentas novecentas
+      ]
+
+      ones_words = feminine ? ones_fem : ones
+      hundreds = feminine ? hundreds_f : hundreds_m
+
+      return ones_words[number] if number < 10
+      return tens[number - 10] if number < 20
+
+      if number < 100
+        tens_digit = number / 10
+        ones_digit = number % 10
+        return tens_multiples[tens_digit] if ones_digit.zero?
+
+        return "#{tens_multiples[tens_digit]} e #{ones_words[ones_digit]}"
+      end
+
+      hundreds_digit = number / 100
+      remainder = number % 100
+
+      if number == 100
+        'cem'
+      elsif remainder.zero?
+        hundreds[hundreds_digit]
+      else
+        "#{hundreds[hundreds_digit]} e #{convert_group(remainder, gender)}"
+      end
+    end
+
+    private_class_method :convert_group
+  end
+end

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

@@ -0,0 +1,65 @@
+module BrazilianUtils
+  # Utilities for formatting, validating and generating Brazilian passport
+  # numbers: 2 letters followed by 6 digits. There is no check digit.
+  module PassportUtils
+    # Removes the formatting symbols (`-`, `.`, `/` and whitespace),
+    # keeping everything else.
+    #
+    # @param value [String]
+    # @return [String]
+    def self.remove_symbols(value)
+      return '' unless value.is_a?(String)
+
+      value.gsub(%r{[-./\s]}, '')
+    end
+
+    # Removes every non-alphanumeric character from a passport number,
+    # upper-cases it and caps it to 8 characters.
+    #
+    # @param value [String]
+    # @return [String]
+    #
+    # @example
+    #   parse("Ab123456")     #=> "AB123456"
+    #   parse(" AB 123 456 ") #=> "AB123456"
+    def self.parse(value)
+      return '' unless value.is_a?(String)
+
+      value.gsub(/[^a-zA-Z0-9]/, '').upcase[0, 8]
+    end
+
+    # Formats a passport number: the same operation as {parse}.
+    #
+    # @param value [String]
+    # @return [String]
+    def self.format(value)
+      parse(value)
+    end
+
+    # Validates a Brazilian passport number: 2 letters followed by 6
+    # digits, after removing non-alphanumeric characters.
+    #
+    # @param value [String, Integer]
+    # @return [Boolean]
+    def self.is_valid(value)
+      return false unless value.is_a?(String) || value.is_a?(Integer)
+
+      cleaned = value.to_s.gsub(/[^a-zA-Z0-9]/, '')
+      cleaned.match?(/\A[A-Za-z]{2}\d{6}\z/)
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Generates a random valid passport number: 2 uppercase letters
+    # followed by 6 digits.
+    #
+    # @return [String]
+    def self.generate
+      letters = 2.times.map { ('A'..'Z').to_a.sample }.join
+      digits = 6.times.map { rand(0..9) }.join
+      "#{letters}#{digits}"
+    end
+  end
+end