br-utils 0.1.1 → 0.2.0

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

@@ -0,0 +1,171 @@
+module BrazilianUtils
+  # Utilities for the matrícula of a certidão de registro civil (art. 473
+  # of the Código Nacional de Normas da Corregedoria Nacional de Justiça):
+  # a 32-digit number grouped as 6-2-2-4-1-5-3-7-2 (registry CNS, acervo,
+  # serviço, ano, tipo do livro, livro, folha, termo, 2 check digits).
+  module CertidaoUtils
+    # Maps the single-digit "tipo do livro" code to its name.
+    BOOK_TYPES = {
+      '1' => 'birth',
+      '2' => 'marriage',
+      '3' => 'religiousMarriage',
+      '4' => 'death',
+      '5' => 'stillbirth',
+      '6' => 'banns',
+      '7' => 'other',
+      '8' => 'emancipation',
+      '9' => 'interdiction'
+    }.freeze
+
+    FIELD_SIZES = [6, 2, 2, 4, 1, 5, 3, 7, 2].freeze
+    FIELD_KEYS = %i[registryCns acervo service year type book page term checkDigits].freeze
+
+    # @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
+
+    # Formats a matrícula into the printed groups (6-2-2-4-1-5-3-7-2),
+    # separated by spaces, applied as far as the digits go.
+    #
+    # @param value [String, Integer]
+    # @param options [Hash] `:pad` left-pads with zeros to 32 digits first.
+    # @return [String]
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(32, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, FIELD_SIZES, [' '] * 8)
+    end
+
+    # Removes the formatting of a certidão matrícula and keeps only
+    # digits, capped to 32 digits.
+    #
+    # @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, 32]
+    end
+
+    # @private
+    #
+    # Computes a single modulus-11 check digit over `base`: the weight
+    # starts at 2 for the rightmost character and increases by 1 moving
+    # left (no cap, no wraparound).
+    def self.check_digit(base)
+      weights = (2...(2 + base.length)).to_a.reverse
+      sum = base.chars.each_with_index.sum { |d, i| d.to_i * weights[i] }
+      remainder = sum % 11
+      remainder < 2 ? 0 : 11 - remainder
+    end
+
+    private_class_method :check_digit
+
+    # @private
+    #
+    # Only digits and the separators {space, '.', '-', '/'} are accepted
+    # anywhere in the string; any other character makes the whole value
+    # invalid. Returns the digits-only string, or nil when the input isn't
+    # a String/Integer or contains a disallowed character.
+    def self.clean_for_validation(value)
+      return nil unless value.is_a?(String) || value.is_a?(Integer)
+
+      raw = value.to_s
+      return nil unless raw.match?(%r{\A[\d\s.\-/]*\z})
+
+      raw.gsub(%r{[\s.\-/]}, '')
+    end
+
+    private_class_method :clean_for_validation
+
+    # @private
+    def self.extract_fields(digits)
+      fields = {}
+      idx = 0
+      FIELD_KEYS.each_with_index do |key, i|
+        size = FIELD_SIZES[i]
+        fields[key] = digits[idx, size]
+        idx += size
+      end
+      fields
+    end
+
+    private_class_method :extract_fields
+
+    # Checks whether a certidão matrícula is structurally valid and its 2
+    # modulus-11 check digits match.
+    #
+    # @param value [String, Integer] The matrícula, bare or separated by
+    #   any mix of space, `.`, `-` or `/`. Any other character (a letter,
+    #   for instance) anywhere in the value makes it invalid.
+    # @param options [Hash] `:accept` an optional Array narrowing which
+    #   book-type codes (as the raw digit string, e.g. `"1"`) or names
+    #   (e.g. `"birth"`) are accepted; defaults to accepting all of 1-9.
+    # @return [Boolean]
+    def self.is_valid(value, options = {})
+      digits = clean_for_validation(value)
+      return false unless digits
+      return false unless digits.match?(/\A\d{32}\z/)
+
+      raw = extract_fields(digits)
+      return false unless raw[:service] == '55'
+      return false unless BOOK_TYPES.key?(raw[:type])
+
+      accept = options[:accept] || options['accept']
+      if accept
+        accepted = Array(accept).map(&:to_s)
+        return false unless accepted.include?(raw[:type]) || accepted.include?(BOOK_TYPES[raw[:type]])
+      end
+
+      base30 = digits[0, 30]
+      dv1 = check_digit(base30)
+      dv2 = check_digit(base30 + dv1.to_s)
+
+      raw[:checkDigits] == "#{dv1}#{dv2}"
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Parses a certidão matrícula into its fields.
+    #
+    # @param value [String, Integer] Same accepted forms as {is_valid}.
+    # @param options [Hash] Same as {is_valid}.
+    # @return [Hash, nil] `nil` whenever {is_valid} would return false;
+    #   otherwise a Hash with `:registryCns`, `:acervo`, `:service`,
+    #   `:year` (Integer), `:type` (the book-type name), `:book`, `:page`,
+    #   `:term` and `:checkDigits`.
+    def self.get_info(value, options = {})
+      return nil unless is_valid(value, options)
+
+      digits = clean_for_validation(value)
+      raw = extract_fields(digits)
+
+      {
+        registryCns: raw[:registryCns],
+        acervo: raw[:acervo],
+        service: raw[:service],
+        year: raw[:year].to_i,
+        type: BOOK_TYPES[raw[:type]],
+        book: raw[:book],
+        page: raw[:page],
+        term: raw[:term],
+        checkDigits: raw[:checkDigits]
+      }
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for the CFOP (Código Fiscal de Operações e Prestações) table,
+  # the consolidated Anexo II of Convênio SINIEF s/nº 1970 in force. Only
+  # operable codes are included (group/subgroup headings are excluded).
+  module CFOPUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'cfop.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # Normalizes a CFOP value to its bare 4 digits, honoring the `N.NNN`
+    # single-separator mask; returns nil for anything else (nothing is
+    # padded, since no CFOP starts with a zero).
+    #
+    # @private
+    def self.normalize(value)
+      return nil if value.nil?
+      return nil unless value.is_a?(String) || value.is_a?(Integer)
+
+      raw = value.to_s.strip
+      return raw if raw.match?(/\A\d{4}\z/)
+
+      m = raw.match(%r{\A(\d)[ .\-/](\d{3})\z})
+      m && "#{m[1]}#{m[2]}"
+    end
+
+    private_class_method :normalize
+
+    # Checks whether a CFOP code exists in the official table (group and
+    # subgroup headings are not operable codes and are rejected).
+    #
+    # @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
+
+    # Looks a CFOP code up and returns its code and description.
+    #
+    # @param value [String, Integer]
+    # @return [Hash, nil]
+    def self.get(value)
+      code = normalize(value)
+      return nil unless code
+
+      description = load_data[code]
+      description && { code: code, description: description }
+    end
+
+    # Removes CFOP formatting and keeps only digits, capped to 4 digits
+    # (nothing is 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, 4]
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for the CNAE-Subclasses 2.3 table (the current subclass
+  # revision of CNAE 2.0), sourced from the IBGE CONCLA API.
+  module CNAEUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'cnae.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 a CNAE value to its bare 7 digits: bare digits (string or
+    # integer) are left-padded with zeros to 7; the `NNNN-N/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(7, '0') if value.is_a?(Integer)
+      return nil unless value.is_a?(String)
+
+      raw = value.strip
+      return raw.rjust(7, '0') if raw.match?(/\A\d+\z/)
+
+      m = raw.match(%r{\A(\d{4})-(\d)/(\d{2})\z})
+      m && "#{m[1]}#{m[2]}#{m[3]}"
+    end
+
+    private_class_method :normalize
+
+    # Formats a CNAE subclass code with the mask `NNNN-N/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 7 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(7, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, [4, 1, 2], ['-', '/'])
+    end
+
+    # Checks whether a CNAE subclass code exists in the 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
+
+    # Looks a CNAE subclass code up and returns its (bare, 7-digit) code
+    # and official description.
+    #
+    # @param value [String, Integer]
+    # @return [Hash, nil]
+    def self.get(value)
+      code = normalize(value)
+      return nil unless code
+
+      description = load_data[code]
+      description && { code: code, description: description }
+    end
+
+    # Removes CNAE formatting and keeps only digits, capped to 7 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, 7]
+    end
+  end
+end

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

@@ -84,5 +84,58 @@ module BrazilianUtils
     end
 
     private_class_method :calculate_first_rest, :check_second_verificator
+
+    # Formats a CNH number as `000000000-00` (9 digits, hyphen, 2 check
+    # digits). The mask is applied as far as the digits go.
+    #
+    # @param value [String, Integer] The value to format.
+    # @param options [Hash] `:pad` left-pads the value with zeros to 11
+    #   digits first.
+    # @return [String]
+    #
+    # @example
+    #   format("00000000119")  #=> "000000001-19"
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(11, '0') if options[:pad] || options['pad']
+      return digits if digits.length <= 9
+
+      "#{digits[0, 9]}-#{digits[9..-1]}"
+    end
+
+    # Removes CNH formatting and keeps only digits, capped to 11 digits.
+    #
+    # @param value [String, Integer]
+    # @return [String]
+    #
+    # @example
+    #   parse("000000001-19")  #=> "00000000119"
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 11]
+    end
+
+    # Generates a valid random CNH number (11 digits, unformatted).
+    #
+    # @return [String]
+    def self.generate
+      loop do
+        base9 = 9.times.map { rand(0..9) }
+        next if base9.uniq.length == 1
+
+        first_rest = calculate_first_rest(base9)
+        first_verificator = first_rest > 9 ? 0 : first_rest
+
+        sum2 = 0
+        9.times { |i| sum2 += base9[i] * (i + 1) }
+        result = sum2 % 11
+        result = (result - 2).negative? ? result + 9 : result - 2 if first_rest > 9
+        second_verificator = result > 9 ? 0 : result
+
+        cnh = "#{base9.join}#{first_verificator}#{second_verificator}"
+        return cnh if valid?(cnh)
+      end
+    end
   end
 end

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

@@ -0,0 +1,76 @@
+module BrazilianUtils
+  # Utilities for the CNO (Cadastro Nacional de Obras), which replaced the
+  # CEI for construction works and kept its numbering/check-digit rule.
+  module CNOUtils
+    WEIGHTS = [7, 4, 1, 8, 5, 2, 1, 6, 3, 7, 4].freeze
+
+    # @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
+
+    # @private
+    def self.check_digit(base)
+      sum = base.chars.each_with_index.sum { |d, i| d.to_i * WEIGHTS[i] }
+      last_two = sum % 100
+      combined = (last_two / 10) + (last_two % 10)
+      (10 - (combined % 10)) % 10
+    end
+
+    private_class_method :check_digit
+
+    # Validates a CNO: same rules as CEIUtils#is_valid.
+    #
+    # @param value [String, Integer]
+    # @return [Boolean]
+    def self.is_valid(value)
+      return false unless value.is_a?(String) || value.is_a?(Integer)
+
+      raw = value.to_s.strip
+      return false unless raw.match?(%r{\A[\d\s.\-/]+\z})
+
+      digits = raw.gsub(%r{[\s.\-/]}, '')
+      return false unless digits.match?(/\A\d{12}\z/)
+      return false if digits.chars.uniq.length == 1
+
+      digits[11].to_i == check_digit(digits[0, 11])
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Formats a CNO with the mask `00.000.00000/00` (the CEI numbering).
+    #
+    # @param value [String, Integer]
+    # @param options [Hash] `:pad` left-pads with zeros to 12 digits first.
+    # @return [String]
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(12, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, [2, 3, 5, 2], ['.', '.', '/'])
+    end
+
+    # Removes CNO formatting and keeps only digits, capped to 12 digits.
+    #
+    # @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, 12]
+    end
+  end
+end

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

@@ -120,34 +120,123 @@ module BrazilianUtils
     # validates the format of the string.
     #
     # @param cnpj [String] The CNPJ to be validated, a 14-digit string
+    #   (v1, numeric) or a 14-character alphanumeric string (v2, when
+    #   `version: 2` is given).
+    # @param version [Integer] `1` (default) validates the classic
+    #   all-numeric CNPJ; `2` validates the alphanumeric CNPJ introduced by
+    #   IN RFB 2.119.
     # @return [Boolean] true if the checksum digits match the base number, false otherwise.
     #
     # @example
-    #   valid?("03560714000142")   #=> true
-    #   valid?("00111222000133")   #=> false
-    def self.valid?(cnpj)
-      cnpj.is_a?(String) && validate(cnpj)
+    #   valid?("03560714000142")           #=> true
+    #   valid?("00111222000133")           #=> false
+    #   valid?("12ABC34501DE35", version: 2)
+    def self.valid?(cnpj, version: 1)
+      return false unless cnpj.is_a?(String)
+
+      version.to_i == 2 ? valid_v2?(cnpj) : validate(cnpj)
     end
 
     # Generates a random valid CNPJ digit string.
     #
-    # An optional branch number parameter can be given; it defaults to 1.
+    # An optional branch number parameter can be given; it defaults to 1
+    # (v1) or a random branch 1-9999 (v2, when not given).
     #
-    # @param branch [Integer] An optional branch number to be included in the CNPJ.
+    # @param branch [Integer, nil] An optional branch number to be included
+    #   in the CNPJ.
+    # @param version [Integer] `1` (default) generates the classic
+    #   all-numeric CNPJ; `2` generates the alphanumeric CNPJ.
     # @return [String] A randomly generated valid CNPJ string.
     #
     # @example
-    #   generate()        #=> "30180536000105"
-    #   generate(1234)    #=> "01745284123455"
-    def self.generate(branch: 1)
-      branch = branch % 10_000
-      branch = 1 if branch.zero?
-      branch_str = branch.to_s.rjust(4, '0')
+    #   generate()               #=> "30180536000105"
+    #   generate(branch: 1234)   #=> "01745284123455"
+    #   generate(version: 2)     #=> "12ABC34501DE35"
+    def self.generate(branch: nil, version: 1)
+      return generate_v2(branch) if version.to_i == 2
+
+      branch_num = branch.nil? ? 1 : branch % 10_000
+      branch_num = 1 if branch_num.zero?
+      branch_str = branch_num.to_s.rjust(4, '0')
       base = format('%08d', rand(100_000_000)) + branch_str
 
       base + checksum(base)
     end
 
+    # V2 (ALPHANUMERIC, IN RFB 2.119)
+    #################################
+
+    # Characters usable in the alphanumeric CNPJ's base (positions 0-11).
+    V2_CHARSET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'.freeze
+
+    V2_WEIGHTS_DV1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].freeze
+    V2_WEIGHTS_DV2 = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].freeze
+
+    # Maps a base-36 character (`0`-`9`, `A`-`Z`) to its numeric value for
+    # the v2 checksum: `'0'`..`'9'` -> 0..9, `'A'`..`'Z'` -> 17..42 (its
+    # ASCII code minus 48).
+    #
+    # @private
+    def self.v2_char_value(char)
+      char.ord - 48
+    end
+
+    private_class_method :v2_char_value
+
+    # Computes a single modulus-11 check digit over `chars` (a String of
+    # `0`-`9`/`A`-`Z` characters) using the given per-position weights.
+    #
+    # @private
+    def self.v2_hashdigit(chars, weights)
+      sum = chars.chars.each_with_index.sum { |c, i| v2_char_value(c) * weights[i] }
+      mod = sum % 11
+      mod < 2 ? 0 : 11 - mod
+    end
+
+    private_class_method :v2_hashdigit
+
+    # Validates a 14-character alphanumeric CNPJ (case-insensitive).
+    #
+    # @param cnpj [String]
+    # @return [Boolean]
+    #
+    # @private
+    def self.valid_v2?(cnpj)
+      upper = cnpj.to_s.upcase
+      return false unless upper.match?(/\A[0-9A-Z]{14}\z/)
+
+      dv1 = v2_hashdigit(upper[0, 12], V2_WEIGHTS_DV1)
+      return false unless dv1 == v2_char_value(upper[12])
+
+      dv2 = v2_hashdigit(upper[0, 13], V2_WEIGHTS_DV2)
+      dv2 == v2_char_value(upper[13])
+    end
+
+    private_class_method :valid_v2?
+
+    # Generates a random valid alphanumeric (v2) CNPJ.
+    #
+    # @param branch [Integer, nil] An optional branch number (1-9999); a
+    #   random one is used when not given.
+    # @return [String]
+    #
+    # @private
+    def self.generate_v2(branch = nil)
+      branch_num = branch.nil? ? rand(1..9999) : branch % 10_000
+      branch_num = 1 if branch_num.zero?
+      branch_str = branch_num.to_s.rjust(4, '0')
+
+      base8 = Array.new(8) { V2_CHARSET[rand(V2_CHARSET.length)] }.join
+      base12 = base8 + branch_str
+
+      dv1 = v2_hashdigit(base12, V2_WEIGHTS_DV1)
+      dv2 = v2_hashdigit(base12 + dv1.to_s, V2_WEIGHTS_DV2)
+
+      "#{base12}#{dv1}#{dv2}"
+    end
+
+    private_class_method :generate_v2
+
     # PRIVATE METHODS
     #################
 
@@ -198,5 +287,29 @@ module BrazilianUtils
     end
 
     private_class_method :hashdigit, :checksum
+
+    # Removes CNPJ formatting and returns the normalized value, capped to 14
+    # characters.
+    #
+    # @param value [String, Integer] A CNPJ, with or without formatting.
+    # @param options [Hash] `:version` `1` (default) keeps digits only; `2`
+    #   keeps letters and digits, upper-cased (the alphanumeric CNPJ format).
+    # @return [String] The parsed value.
+    #
+    # @example
+    #   parse("46.843.485/0001-86")  #=> "46843485000186"
+    def self.parse(value, options = {})
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      version = (options[:version] || options['version'] || 1).to_i
+
+      cleaned = if version == 2
+                  value.to_s.gsub(/[^a-zA-Z0-9]/, '').upcase
+                else
+                  value.to_s.gsub(/\D/, '')
+                end
+
+      cleaned[0, 14]
+    end
   end
 end