br-utils 0.1.1 → 0.2.0

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

@@ -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