br-utils 0.1.0 → 0.2.0

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
     #################
 
@@ -170,7 +259,7 @@ module BrazilianUtils
       (position - 8).downto(2) { |w| weights << w }
       9.downto(2) { |w| weights << w }
 
-      val = cnpj.chars.zip(weights).sum do |digit, weight|
+      val = cnpj.chars.first(position - 1).zip(weights).sum do |digit, weight|
         digit.to_i * weight
       end % 11
 
@@ -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

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

@@ -0,0 +1,110 @@
+module BrazilianUtils
+  # Utilities for the CNS (Cartão Nacional de Saúde) number: 15 digits,
+  # definitive (starts with 1 or 2) or provisional (starts with 7, 8 or 9).
+  module CNSUtils
+    # @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.weighted_sum(digits, weights)
+      digits.chars.each_with_index.sum { |d, i| d.to_i * weights[i] }
+    end
+
+    private_class_method :weighted_sum
+
+    # @private
+    def self.definitive_valid?(digits)
+      weights = (5..15).to_a.reverse # [15, 14, ..., 5]
+      pis = digits[0, 11]
+
+      sum = weighted_sum(pis, weights)
+      resto = sum % 11
+      dv = 11 - resto
+      dv = 0 if dv == 11
+
+      if dv == 10
+        pis2 = (pis.to_i + 1).to_s.rjust(11, '0')
+        sum2 = weighted_sum(pis2, weights)
+        resto2 = sum2 % 11
+        dv2 = 11 - resto2
+        dv2 = 0 if dv2 >= 10
+        digits == "#{pis2}001#{dv2}"
+      else
+        digits == "#{pis}000#{dv}"
+      end
+    end
+
+    private_class_method :definitive_valid?
+
+    # @private
+    def self.provisional_valid?(digits)
+      weights = (1..15).to_a.reverse # [15, 14, ..., 1]
+      (weighted_sum(digits, weights) % 11).zero?
+    end
+
+    private_class_method :provisional_valid?
+
+    # Validates a CNS number: 15 digits.
+    #
+    # @param value [String, Integer] The bare digits, or the printed
+    #   3-4-4-4 groups split by whitespace, `.`, `-` or `/`.
+    # @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{15}\z/)
+
+      case digits[0]
+      when '1', '2'
+        definitive_valid?(digits)
+      when '7', '8', '9'
+        provisional_valid?(digits)
+      else
+        false
+      end
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Formats a CNS number into 3-4-4-4 groups separated by spaces.
+    #
+    # @param value [String, Integer]
+    # @param options [Hash] `:pad` left-pads with zeros to 15 digits first.
+    # @return [String]
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(15, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, [3, 4, 4, 4], [' ', ' ', ' '])
+    end
+
+    # Removes CNS formatting and keeps only digits, capped to 15 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, 15]
+    end
+  end
+end

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

@@ -161,7 +161,7 @@ module BrazilianUtils
     #
     # @private
     def self.hashdigit(cpf, position)
-      val = cpf.chars.zip(position.downto(2)).sum do |digit, weight|
+      val = cpf.chars.first(position - 1).zip(position.downto(2)).sum do |digit, weight|
         digit.to_i * weight
       end % 11
 
@@ -188,5 +188,18 @@ module BrazilianUtils
     end
 
     private_class_method :hashdigit, :checksum
+
+    # Removes CPF formatting and keeps only digits, capped to 11 digits.
+    #
+    # @param value [String, Integer] A CPF, with or without formatting.
+    # @return [String] The parsed digits.
+    #
+    # @example
+    #   parse("943.895.751-04")  #=> "94389575104"
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 11]
+    end
   end
 end

data/lib/brazilian-utils/credit-card-utils.rb

@@ -0,0 +1,47 @@
+module BrazilianUtils
+  # Utilities for validating a payment card number (credit or debit) by its
+  # structure and Luhn check digit. No brand detection, issuer range
+  # lookup, expiry or CVV check is performed.
+  module CreditCardUtils
+    # Validates a payment card number: 12 to 19 digits and a Luhn check
+    # digit.
+    #
+    # @param value [String, Integer] Whitespace, `.`, `-` and `/` are
+    #   allowed anywhere between the digits; letters make it invalid. Pass
+    #   a large number as a string to avoid floating-point precision loss.
+    # @return [Boolean] A number whose digits are all the same is rejected
+    #   even though it passes Luhn.
+    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,19}\z/)
+      return false if digits.chars.uniq.length == 1
+
+      luhn_valid?(digits)
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # @private
+    def self.luhn_valid?(digits)
+      sum = 0
+      digits.reverse.each_char.with_index do |ch, i|
+        d = ch.to_i
+        if i.odd?
+          d *= 2
+          d -= 9 if d > 9
+        end
+        sum += d
+      end
+      (sum % 10).zero?
+    end
+
+    private_class_method :luhn_valid?
+  end
+end

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

@@ -0,0 +1,55 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for the CSOSN (Código de Situação da Operação no Simples
+  # Nacional) table (Ajuste SINIEF 07/2005).
+  module CSOSNUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'csosn.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # Checks whether a value is one of the 10 official CSOSN codes.
+    #
+    # A CSOSN has no printed grouping/mask, so a value with any separator
+    # is rejected.
+    #
+    # @param value [String, Integer]
+    # @return [Boolean]
+    def self.is_valid(value)
+      return false if value.nil?
+
+      str = value.to_s.strip
+      return false unless str.match?(/\A\d{3}\z/)
+
+      load_data.any? { |row| row['code'] == str }
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Looks up the description of a CSOSN code.
+    #
+    # @param value [String, Integer]
+    # @return [String, nil]
+    def self.get_description(value)
+      return nil if value.nil?
+
+      str = value.to_s.strip
+      row = load_data.find { |r| r['code'] == str }
+      row && row['description']
+    end
+
+    # Returns all 10 official CSOSN entries.
+    #
+    # @return [Array<Hash>]
+    def self.list
+      load_data.map { |row| { code: row['code'], description: row['description'] } }
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for the CST (Código de Situação Tributária) tables: ICMS
+  # (Tabela A "origem" + Tabela B "tributação"), IPI and PIS/COFINS (which
+  # share a table).
+  module CSTUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'cst.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # @private
+    def self.icms_origins
+      load_data['icmsOrigin']['entries'].map { |e| e['code'] }
+    end
+
+    # @private
+    def self.icms_csts
+      load_data['icmsCst']['entries'].map { |e| e['code'] }
+    end
+
+    # @private
+    def self.ipi_csts
+      load_data['ipiCst']['entries'].map { |e| e['code'] }
+    end
+
+    # @private
+    def self.pis_cofins_csts
+      load_data['pisCofinsCst']['entries'].map { |e| e['code'] }
+    end
+
+    private_class_method :icms_origins, :icms_csts, :ipi_csts, :pis_cofins_csts
+
+    # Checks whether a CST code is valid for a tax.
+    #
+    # @param value [String, Integer] A string or a non-negative integer. The
+    #   3-digit ICMS form (origin + Tabela B code) may have a single
+    #   separator right after the origin digit (e.g. `"1-10"`). A single
+    #   digit is padded to the 3-digit ICMS form; a 2-digit string is
+    #   checked as a Tabela B / IPI / PIS-COFINS code.
+    # @param options [Hash] `:tax` picks the table: `"icms"`, `"ipi"`,
+    #   `"pis"` or `"cofins"` (PIS and COFINS share a table). Omitted or
+    #   unknown, every table is accepted.
+    # @return [Boolean]
+    def self.is_valid(value, options = {})
+      return false if value.nil?
+
+      tax = (options[:tax] || options['tax']).to_s.downcase
+      tax = nil if tax.empty? || !%w[icms ipi pis cofins].include?(tax)
+
+      raw = value.to_s.strip
+      return false if raw.empty?
+
+      three_digit, two_digit = normalize(raw)
+
+      icms_ok = !three_digit.nil? && icms_origins.include?(three_digit[0]) && icms_csts.include?(three_digit[1, 2])
+
+      case tax
+      when 'icms'
+        icms_ok
+      when 'ipi'
+        !two_digit.nil? && ipi_csts.include?(two_digit)
+      when 'pis', 'cofins'
+        !two_digit.nil? && pis_cofins_csts.include?(two_digit)
+      else
+        icms_ok ||
+          (!two_digit.nil? && (icms_csts.include?(two_digit) || ipi_csts.include?(two_digit) || pis_cofins_csts.include?(two_digit)))
+      end
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Normalizes a raw CST value into a candidate 3-digit ICMS form and/or a
+    # candidate 2-digit (Tabela B / IPI / PIS-COFINS) form.
+    #
+    # @return [Array(String, nil), Array(nil, String), Array(nil, nil)]
+    #
+    # @private
+    def self.normalize(raw)
+      case raw
+      when /\A\d\z/
+        [raw.rjust(3, '0'), nil]
+      when /\A\d{3}\z/
+        [raw, nil]
+      when /\A\d[-.]\d{2}\z/
+        [raw[0] + raw[2, 2], nil]
+      when /\A\d{2}\z/
+        [nil, raw]
+      else
+        [nil, nil]
+      end
+    end
+
+    private_class_method :normalize
+  end
+end