br-utils 0.1.0 → 0.2.0

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

@@ -97,7 +97,8 @@ module BrazilianUtils
       return false unless pis.is_a?(String)
       return false unless pis.length == 11
       return false unless pis.match?(/^\d+$/)
-      
+      return false if pis.chars.uniq.length == 1 # e.g. "00000000000", "99999999999"
+
       pis[-1] == checksum(pis[0..9]).to_s
     end
 
@@ -147,5 +148,19 @@ module BrazilianUtils
     end
 
     private_class_method :checksum
+
+    # Removes PIS formatting and keeps only digits, capped to 11 digits.
+    #
+    # @param value [String, Integer] A PIS, with or without formatting.
+    # @return [String] The digits-only value, capped to 11 characters.
+    #
+    # @example
+    #   parse("123.45678.90-1")  #=> "12345678901"
+    #   parse("12345678901123")  #=> "12345678901"
+    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/pix-key-utils.rb

@@ -0,0 +1,70 @@
+require_relative 'cpf-utils'
+require_relative 'cnpj-utils'
+require_relative 'phone-utils'
+
+module BrazilianUtils
+  # Utilities for identifying and validating a Pix key (DICT key formats):
+  # a CPF, a CNPJ, an email, a Brazilian mobile phone or a random EVP key.
+  module PixKeyUtils
+    UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i.freeze
+    EMAIL_REGEX = /\A[^\s@]+@[^\s@]+\.[^\s@]+\z/.freeze
+    MAX_EMAIL_LENGTH = 77
+
+    # Identifies a Pix key and normalizes it to the canonical form the
+    # DICT expects inside a BR Code.
+    #
+    # @param value [String]
+    # @return [Hash, nil] `{ type:, value: }`, or nil when `value` is not a
+    #   valid Pix key.
+    def self.get_info(value)
+      return nil unless value.is_a?(String)
+
+      str = value.strip
+      return nil if str.empty?
+
+      return { type: 'evp', value: str.downcase } if UUID_REGEX.match?(str)
+
+      if str.include?('@')
+        return nil if str.length > MAX_EMAIL_LENGTH
+        return nil unless EMAIL_REGEX.match?(str)
+
+        return { type: 'email', value: str.downcase }
+      end
+
+      if str.start_with?('+') || str.include?('(')
+        digits = PhoneUtils.parse(str)
+        return nil unless PhoneUtils.is_valid_mobile(digits)
+
+        return { type: 'phone', value: "+55#{digits}" }
+      end
+
+      digits = str.gsub(/\D/, '')
+      case digits.length
+      when 11
+        CPFUtils.valid?(digits) ? { type: 'cpf', value: digits } : nil
+      when 14
+        CNPJUtils.valid?(digits) ? { type: 'cnpj', value: digits } : nil
+      end
+    end
+
+    # Checks whether a value is a valid Pix key.
+    #
+    # @param value [String]
+    # @param options [Hash] `:types` restricts the accepted key types
+    #   (`%w[cpf cnpj email phone evp]`); an empty list rejects everything.
+    # @return [Boolean]
+    def self.is_valid(value, options = {})
+      info = get_info(value)
+      return false unless info
+
+      types = options[:types] || options['types']
+      return true if types.nil?
+
+      types.map(&:to_s).include?(info[:type])
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+  end
+end

data/lib/brazilian-utils/pix-payload-utils.rb

@@ -0,0 +1,253 @@
+require_relative 'text-utils'
+require_relative 'pix-key-utils'
+
+module BrazilianUtils
+  # Utilities for the Pix "BR Code" payload: the EMV-derived TLV (tag-
+  # length-value) QR code format defined by the Banco Central's Manual de
+  # Padrões para Iniciação do Pix.
+  module PixPayloadUtils
+    PIX_GUI = 'br.gov.bcb.pix'
+
+    # @private
+    def self.crc16(str)
+      crc = 0xFFFF
+      str.each_byte do |byte|
+        crc ^= (byte << 8)
+        8.times do
+          crc = (crc & 0x8000).zero? ? (crc << 1) & 0xFFFF : ((crc << 1) ^ 0x1021) & 0xFFFF
+        end
+      end
+      crc
+    end
+
+    private_class_method :crc16
+
+    # Parses a flat TLV string into an ordered list of `[id, value]` pairs.
+    #
+    # @return [Array<Array(String, String)>, nil] nil when malformed.
+    #
+    # @private
+    def self.parse_tlv(str)
+      fields = []
+      pos = 0
+
+      while pos < str.length
+        return nil if pos + 4 > str.length
+
+        id = str[pos, 2]
+        len_str = str[pos + 2, 2]
+        return nil unless id.match?(/\A\d{2}\z/) && len_str.match?(/\A\d{2}\z/)
+
+        len = len_str.to_i
+        value = str[pos + 4, len]
+        return nil if value.nil? || value.length != len
+
+        fields << [id, value]
+        pos += 4 + len
+      end
+
+      fields
+    end
+
+    private_class_method :parse_tlv
+
+    # @private
+    def self.find_pix_merchant_account_info(fields)
+      fields.each do |id, value|
+        next unless ('26'..'51').cover?(id)
+
+        nested = parse_tlv(value)
+        next unless nested
+
+        gui = nested.find { |nid, _| nid == '00' }
+        next unless gui && gui[1].downcase == PIX_GUI
+
+        return nested
+      end
+      nil
+    end
+
+    private_class_method :find_pix_merchant_account_info
+
+    # @private
+    def self.validated_fields(value)
+      return nil unless value.is_a?(String) && !value.empty?
+      return nil if value.length < 4
+
+      crc_declared = value[-4..-1]
+      return nil unless crc_declared.match?(/\A[0-9A-Fa-f]{4}\z/)
+      return nil unless format('%04X', crc16(value[0...-4])) == crc_declared.upcase
+
+      fields = parse_tlv(value)
+      return nil unless fields
+      return nil unless fields.last && fields.last[0] == '63' && fields.last[1].length == 4
+
+      by_id = {}
+      fields.each { |id, v| (by_id[id] ||= []) << v }
+
+      return nil unless by_id['00'] == ['01']
+      return nil unless by_id['52']&.first&.match?(/\A\d{4}\z/)
+      return nil unless by_id['53']&.first
+      return nil unless by_id['58']&.first == 'BR'
+      return nil unless by_id['59']&.first&.length&.between?(1, 99)
+      return nil unless by_id['60']&.first&.length&.between?(1, 99)
+
+      poi = by_id['01']&.first
+      return nil if poi && !%w[11 12].include?(poi)
+
+      merchant_account = find_pix_merchant_account_info(fields)
+      return nil unless merchant_account
+
+      key_entry = merchant_account.find { |id, _| id == '01' }
+      url_entry = merchant_account.find { |id, _| id == '25' }
+      return nil if key_entry.nil? == url_entry.nil?
+
+      amount = by_id['54']&.first
+      return nil if amount && !(amount.to_f > 0)
+
+      { fields: fields, by_id: by_id, poi: poi, key_entry: key_entry, url_entry: url_entry }
+    end
+
+    private_class_method :validated_fields
+
+    # Validates a Pix BR Code payload (the key itself is not checked; use
+    # `PixKeyUtils.is_valid`).
+    #
+    # @param value [String]
+    # @return [Boolean]
+    def self.is_valid(value)
+      !validated_fields(value).nil?
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Parses a Pix BR Code payload into its fields.
+    #
+    # @param value [String]
+    # @return [Hash, nil] nil for anything {is_valid} rejects.
+    def self.get_info(value)
+      parsed = validated_fields(value)
+      return nil unless parsed
+
+      by_id = parsed[:by_id]
+      has_psp_location = !parsed[:url_entry].nil?
+      point_of_initiation = (parsed[:poi] == '12' || has_psp_location) ? 'dynamic' : 'static'
+
+      info = {
+        merchantName: by_id['59'].first,
+        merchantCity: by_id['60'].first,
+        pointOfInitiation: point_of_initiation
+      }
+
+      if has_psp_location
+        info[:url] = parsed[:url_entry][1]
+      else
+        info[:key] = parsed[:key_entry][1]
+
+        unless has_psp_location
+          amount = by_id['54']&.first
+          info[:amount] = amount.to_f if amount
+
+          additional = by_id['62']&.first
+          if additional
+            nested = parse_tlv(additional)
+            txid_entry = nested&.find { |id, _| id == '05' }
+            info[:txid] = txid_entry[1] if txid_entry && txid_entry[1] != '***'
+          end
+        end
+      end
+
+      info
+    end
+
+    # @private
+    def self.tlv(id, value)
+      "#{id}#{value.length.to_s.rjust(2, '0')}#{value}"
+    end
+
+    private_class_method :tlv
+
+    # Generates a Pix BR Code payload.
+    #
+    # @param params [Hash] Exactly one of `:key` (static) or `:url`
+    #   (dynamic) must be given, plus `:merchantName` and `:merchantCity`,
+    #   and optionally `:amount`, `:txid` and `:description`.
+    # @return [String, nil] nil when the parameters are invalid or
+    #   contradictory (e.g. both/neither `:key` and `:url` given).
+    #
+    # @note This has no acceptance test cases in the contract; it has only
+    #   been self-verified (a generated payload passes {is_valid} and
+    #   round-trips through {get_info}), not cross-checked against a
+    #   reference implementation's own test suite.
+    def self.generate(params)
+      return nil unless params.is_a?(Hash)
+
+      key = params[:key] || params['key']
+      url = params[:url] || params['url']
+      return nil if key.nil? == url.nil?
+
+      merchant_name = params[:merchantName] || params['merchantName']
+      merchant_city = params[:merchantCity] || params['merchantCity']
+      return nil unless merchant_name.is_a?(String) && merchant_city.is_a?(String)
+      return nil if merchant_name.empty? || merchant_city.empty?
+
+      amount = params[:amount] || params['amount']
+      txid = params[:txid] || params['txid'] || '***'
+      description = params[:description] || params['description']
+
+      clean_url = nil
+      key_info = nil
+
+      if url
+        return nil unless url.is_a?(String)
+        return nil if amount || (params[:txid] || params['txid'])
+
+        clean_url = url.sub(%r{\Ahttps?://}, '')
+        return nil if clean_url.empty? || clean_url.length > 77
+      else
+        key_info = PixKeyUtils.get_info(key)
+        return nil unless key_info
+      end
+
+      amount_str = nil
+      if amount
+        return nil if amount.to_s.match?(/\.\d{3,}/)
+
+        amount_str = format('%.2f', amount.to_f)
+        return nil unless amount_str.to_f.positive?
+      end
+
+      return nil unless txid == '***' || txid.match?(/\A[A-Za-z0-9]{1,25}\z/)
+
+      name = TextUtils.remove_accents(merchant_name)[0, 25]
+      city = TextUtils.remove_accents(merchant_city)[0, 15]
+
+      merchant_account_value = tlv('00', PIX_GUI) + (url ? tlv('25', clean_url) : tlv('01', key_info[:value]))
+
+      fields = []
+      fields << tlv('00', '01')
+      fields << tlv('01', url ? '12' : '11')
+      fields << tlv('26', merchant_account_value)
+      fields << tlv('52', '0000')
+      fields << tlv('53', '986')
+      fields << tlv('54', amount_str) if amount_str && !url
+      fields << tlv('58', 'BR')
+      fields << tlv('59', name)
+      fields << tlv('60', city)
+
+      unless url
+        additional = tlv('05', txid)
+        if description
+          desc = TextUtils.remove_accents(description)[0, 99]
+          additional += tlv('02', desc) unless desc.empty?
+        end
+        fields << tlv('62', additional)
+      end
+
+      payload_without_crc = fields.join + '6304'
+      payload_without_crc + format('%04X', crc16(payload_without_crc))
+    end
+  end
+end

data/lib/brazilian-utils/registro-profissional-utils.rb

@@ -0,0 +1,112 @@
+module BrazilianUtils
+  # Utilities for checking the *structure* of a professional council
+  # registration number (OAB, CRM, CRO, CRP or CRC). This never validates a
+  # check digit — none of these councils publish one — only the digit
+  # count and the UF.
+  #
+  # @note There were no acceptance test cases available in the contract for
+  #   this function; this implementation follows the prose description as
+  #   closely as possible but has not been cross-checked against a
+  #   reference implementation's test suite.
+  module RegistroProfissionalUtils
+    UFS = %w[
+      AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO
+    ].freeze
+
+    # Checks the structure of a professional council registration number.
+    #
+    # @param params [Hash] `:value` (the registration string), `:council`
+    #   (`"OAB"`, `"CRM"`, `"CRO"`, `"CRP"` or `"CRC"`) and an optional
+    #   `:state` (the expected UF).
+    # @return [Boolean]
+    def self.is_valid(params)
+      return false unless params.is_a?(Hash)
+
+      value = params[:value] || params['value']
+      council = (params[:council] || params['council']).to_s.upcase
+      expected_state = params[:state] || params['state']
+
+      return false unless value.is_a?(String)
+
+      case council
+      when 'OAB', 'CRM'
+        valid_oab_crm?(value, expected_state)
+      when 'CRO'
+        valid_cro?(value, expected_state)
+      when 'CRP'
+        valid_crp?(value)
+      when 'CRC'
+        valid_crc?(value, expected_state)
+      else
+        false
+      end
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # @private
+    def self.matches_expected_state?(uf, expected_state)
+      expected_state.nil? || expected_state.to_s.upcase == uf
+    end
+
+    private_class_method :matches_expected_state?
+
+    # OAB and CRM: 4 to 6 digits plus the UF (`123456/SP`, `123456-SP`).
+    #
+    # @private
+    def self.valid_oab_crm?(value, expected_state)
+      m = value.strip.match(%r{\A(\d{4,6})[/-]([A-Za-z]{2})\z})
+      return false unless m
+
+      uf = m[2].upcase
+      UFS.include?(uf) && matches_expected_state?(uf, expected_state)
+    end
+
+    private_class_method :valid_oab_crm?
+
+    # CRO: 3 to 6 digits plus the UF.
+    #
+    # @private
+    def self.valid_cro?(value, expected_state)
+      m = value.strip.match(%r{\A(\d{3,6})[/-]([A-Za-z]{2})\z})
+      return false unless m
+
+      uf = m[2].upcase
+      UFS.include?(uf) && matches_expected_state?(uf, expected_state)
+    end
+
+    private_class_method :valid_cro?
+
+    # CRP: a 2-digit regional code (01-24) plus 4 to 6 digits
+    # (`06/12345`); the expected state is ignored.
+    #
+    # @private
+    def self.valid_crp?(value)
+      m = value.strip.match(%r{\A(\d{2})[/-](\d{4,6})\z})
+      return false unless m
+
+      m[1].to_i.between?(1, 24)
+    end
+
+    private_class_method :valid_crp?
+
+    # CRC: UF, 6 digits, registration type (`O` or `P`) and a digit
+    # (`SP-123456/O-3`), optionally a transfer suffix (`T-MG` or `S-MG`).
+    #
+    # @private
+    def self.valid_crc?(value, expected_state)
+      m = value.strip.match(%r{\A([A-Za-z]{2})-(\d{6})/([OoPp])-(\d)(?:\s+[TtSs]-([A-Za-z]{2}))?\z})
+      return false unless m
+
+      uf = m[1].upcase
+      return false unless UFS.include?(uf)
+      return false if m[5] && !UFS.include?(m[5].upcase)
+
+      matches_expected_state?(uf, expected_state)
+    end
+
+    private_class_method :valid_crc?
+  end
+end

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

@@ -109,5 +109,19 @@ module BrazilianUtils
     end
 
     private_class_method :calculate_renavam_dv
+
+    # Generates a valid random RENAVAM (11 digits: 10 base digits plus the
+    # check digit), unformatted.
+    #
+    # @return [String]
+    def self.generate
+      loop do
+        base = 10.times.map { rand(0..9) }.join
+        next if base.chars.uniq.length == 1
+
+        renavam = base + calculate_renavam_dv(base).to_s
+        return renavam if is_valid_renavam(renavam)
+      end
+    end
   end
 end

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

@@ -0,0 +1,105 @@
+require 'json'
+require_relative 'text-utils'
+
+module BrazilianUtils
+  # Utilities for looking up Brazil's 27 federative units (states + the
+  # Distrito Federal): code (sigla), name, region and IBGE code, sourced
+  # from the IBGE Localidades API.
+  module StateUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'states.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # @private
+    def self.normalize_name(name)
+      TextUtils.remove_accents(name.to_s).downcase.strip.gsub(/\s+/, ' ')
+    end
+
+    private_class_method :normalize_name
+
+    # @private
+    def self.to_symbolized(row)
+      {
+        code: row['code'],
+        name: row['name'],
+        regionCode: row['regionCode'],
+        regionName: row['regionName'],
+        ibgeCode: row['ibgeCode']
+      }
+    end
+
+    private_class_method :to_symbolized
+
+    # Returns the 27 Brazilian federative units, sorted by name (pt-BR
+    # collation, approximated by comparing accent-stripped names).
+    #
+    # @return [Array<Hash>] Each entry has `:code`, `:name`, `:regionCode`,
+    #   `:regionName` and `:ibgeCode`.
+    def self.list
+      load_data
+        .sort_by { |row| normalize_name(row['name']) }
+        .map { |row| to_symbolized(row) }
+    end
+
+    # Returns the state whose 2-digit IBGE code (cUF) matches `code`.
+    #
+    # @param code [String, Integer]
+    # @return [Hash, nil]
+    def self.get_by_ibge_code(code)
+      return nil if code.nil?
+
+      str = code.to_s.strip
+      return nil unless str.match?(/\A\d+\z/)
+
+      row = load_data.find { |r| r['ibgeCode'] == str.to_i }
+      row && to_symbolized(row)
+    end
+
+    # Returns the two-letter code (sigla) of a state from its full name.
+    #
+    # @param name [String]
+    # @return [String, nil]
+    def self.get_code_by_name(name)
+      return nil unless name.is_a?(String)
+
+      normalized = normalize_name(name)
+      return nil if normalized.empty?
+
+      row = load_data.find { |r| normalize_name(r['name']) == normalized }
+      row && row['code']
+    end
+
+    # Returns the full name of a state from its two-letter code (sigla).
+    #
+    # @param code [String]
+    # @return [String, nil]
+    def self.get_name_by_code(code)
+      return nil unless code.is_a?(String)
+
+      normalized = code.strip.upcase
+      return nil if normalized.empty?
+
+      row = load_data.find { |r| r['code'] == normalized }
+      row && row['name']
+    end
+
+    # Returns the IANA time zone of a state (the zone of its capital).
+    #
+    # @param state_code [String]
+    # @return [String, nil]
+    def self.get_timezone(state_code)
+      return nil unless state_code.is_a?(String)
+
+      normalized = state_code.strip.upcase
+      return nil if normalized.empty?
+
+      row = load_data.find { |r| r['code'] == normalized }
+      row && row['timezone']
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module BrazilianUtils
+  # General-purpose text helpers used across the other domains (and useful
+  # on their own) for handling names, company names and addresses written in
+  # Brazilian Portuguese.
+  module TextUtils
+    # Prepositions and articles that stay lower case between two words.
+    DEFAULT_PREPOSITIONS = %w[de da do das dos e].freeze
+
+    # Company designations/abbreviations that are always upper-cased.
+    # Deliberately conservative: common words that also happen to be valid
+    # abbreviations (e.g. "me", the reflexive pronoun; "sa", the surname
+    # "Sá") are left out on purpose, see `text.capitalize`'s description.
+    DEFAULT_DESIGNATIONS = %w[LTDA EPP MEI EIRELI CNPJ].freeze
+
+    # Roman numerals commonly used in Brazilian company/entity names
+    # (e.g. "Fundação XXI"). Only applied when the original token was
+    # already written fully upper case, to avoid mistaking short
+    # Portuguese words (like "vi", "mim") for numerals.
+    ROMAN_NUMERALS = %w[
+      I II III IV V VI VII VIII IX X XI XII XIII XIV XV XVI XVII XVIII XIX XX
+    ].freeze
+
+    WORD_OR_SEPARATOR_REGEX = /[\p{L}\p{N}]+|[^\p{L}\p{N}]+/.freeze
+
+    # Capitalizes the first letter of each word the way a Brazilian name,
+    # company name or address is written.
+    #
+    # @param value [String] The text to capitalize.
+    # @param options [Hash] `:prepositions` and `:designations` replace the
+    #   default lists.
+    # @return [String] The capitalized text, or an empty string for empty
+    #   input.
+    #
+    # @example
+    #   capitalize("esponja vegetal")   #=> "Esponja Vegetal"
+    #   capitalize("fulano de tal")     #=> "Fulano de Tal"
+    #   capitalize("JOAQUIM JOSÉ")      #=> "Joaquim José"
+    def self.capitalize(value, options = {})
+      return '' unless value.is_a?(String)
+      return '' if value.strip.empty?
+
+      prepositions = (options[:prepositions] || options['prepositions'] || DEFAULT_PREPOSITIONS).map(&:downcase)
+      designations = (options[:designations] || options['designations'] || DEFAULT_DESIGNATIONS).map(&:upcase)
+
+      collapsed = value.strip.gsub(/\s+/, ' ')
+      tokens = collapsed.scan(WORD_OR_SEPARATOR_REGEX)
+
+      word_indices = tokens.each_index.select { |i| tokens[i].match?(/\A[\p{L}\p{N}]+\z/) }
+      first_word_idx = word_indices.first
+      last_word_idx = word_indices.last
+
+      word_indices.each do |i|
+        token = tokens[i]
+
+        if token.match?(/\A\d/)
+          tokens[i] = token.downcase
+          next
+        end
+
+        upcase_token = token.upcase
+
+        if token == upcase_token && ROMAN_NUMERALS.include?(upcase_token)
+          tokens[i] = upcase_token
+          next
+        end
+
+        if designations.include?(upcase_token)
+          tokens[i] = upcase_token
+          next
+        end
+
+        downcase_token = token.downcase
+        next_token = tokens[i + 1]
+        followed_by_punctuation = !next_token.nil? && next_token != ' '
+
+        if prepositions.include?(downcase_token) && i != first_word_idx && i != last_word_idx && !followed_by_punctuation
+          tokens[i] = downcase_token
+        else
+          tokens[i] = token[0].upcase + token[1..-1].to_s.downcase
+        end
+      end
+
+      tokens.join
+    end
+
+    # Removes diacritical marks (accents, tildes, cedillas) from a string.
+    #
+    # Every character is decomposed (Unicode NFD) and every combining mark
+    # is dropped.
+    #
+    # @param value [String] The text to strip accents from.
+    # @return [String] The text without diacritics.
+    #
+    # @example
+    #   remove_accents("São Paulo")  #=> "Sao Paulo"
+    #   remove_accents("Açaí")       #=> "Acai"
+    def self.remove_accents(value)
+      return '' unless value.is_a?(String)
+
+      value.unicode_normalize(:nfd).gsub(/[̀-ͯ]/, '')
+    end
+  end
+end