br-utils 0.1.0 → 0.2.0

data/lib/brazilian-utils/area-code-utils.rb

@@ -0,0 +1,60 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for looking up Brazilian area codes (DDD), sourced from the
+  # Anatel Plano Geral de Numeração.
+  module AreaCodeUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'area_codes.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)
+      {
+        areaCode: row['areaCode'],
+        stateCode: row['stateCode'],
+        stateName: row['stateName'],
+        regionCode: row['regionCode'],
+        regionName: row['regionName'],
+        stateCodes: row['stateCodes']
+      }
+    end
+
+    private_class_method :to_symbolized
+
+    # Returns the state and region a DDD (area code) belongs to.
+    #
+    # @param area_code [String, Integer]
+    # @return [Hash, nil]
+    def self.get_info(area_code)
+      return nil if area_code.nil?
+
+      str = area_code.to_s.strip
+      return nil unless str.match?(/\A\d+\z/)
+
+      row = load_data.find { |r| r['areaCode'] == str.to_i }
+      row && to_symbolized(row)
+    end
+
+    # Returns every DDD that serves a state, sorted ascending.
+    #
+    # @param state_code [String]
+    # @return [Array<Integer>]
+    def self.list_by_state(state_code)
+      return [] unless state_code.is_a?(String)
+
+      normalized = state_code.strip.upcase
+      return [] if normalized.empty?
+
+      load_data
+        .select { |r| r['stateCodes'].include?(normalized) }
+        .map { |r| r['areaCode'] }
+        .sort
+    end
+  end
+end

data/lib/brazilian-utils/bank-account-utils.rb

@@ -0,0 +1,82 @@
+require_relative 'bank-utils'
+
+module BrazilianUtils
+  # Utilities for validating Brazilian bank accounts (bank code, agency,
+  # account and check digit).
+  #
+  # @note This implementation validates the account's *structure* (a known
+  #   COMPE `bankCode`, agency/account digit-count limits, an allowed
+  #   `digit` character) and a generic modulus 10 / modulus 11 fallback
+  #   check digit. The distinct, published check-digit algorithms some
+  #   banks use (Banco do Brasil, Santander, Banrisul, Caixa, Bradesco,
+  #   Nubank/Verhoeff, Itaú, HSBC/Kirton, Citibank) are **not** implemented:
+  #   there were no verifiable test vectors available to confirm a from-
+  #   scratch reproduction of each algorithm, and shipping an unverified
+  #   guess would be worse than this honestly-partial generic check.
+  module BankAccountUtils
+    # @private
+    def self.mod10_digit(digits)
+      sum = 0
+      digits.reverse.each_char.with_index do |ch, i|
+        d = ch.to_i
+        d *= 2 if i.even?
+        d -= 9 if d > 9
+        sum += d
+      end
+      (10 - (sum % 10)) % 10
+    end
+
+    private_class_method :mod10_digit
+
+    # @private
+    def self.mod11_digit(digits)
+      weights = [2, 3, 4, 5, 6, 7, 8, 9]
+      sum = 0
+      digits.reverse.each_char.with_index do |ch, i|
+        sum += ch.to_i * weights[i % weights.length]
+      end
+      rest = 11 - (sum % 11)
+      rest >= 10 ? 0 : rest
+    end
+
+    private_class_method :mod11_digit
+
+    # Validates a Brazilian bank account.
+    #
+    # @param params [Hash] `:bankCode` (3 digits), `:agency` (1-5 digits),
+    #   `:account` (1-13 digits) and `:digit` (1-2 characters, or the
+    #   literal `X`/`P` used by some banks), all strings.
+    # @return [Boolean]
+    def self.is_valid(params)
+      return false unless params.is_a?(Hash)
+
+      bank_code = params[:bankCode] || params['bankCode']
+      agency = params[:agency] || params['agency']
+      account = params[:account] || params['account']
+      digit = params[:digit] || params['digit']
+
+      return false unless [bank_code, agency, account, digit].all? { |v| v.is_a?(String) }
+      return false unless BankUtils.get_by_code(bank_code)
+      return false unless agency.match?(/\A\d{1,5}\z/)
+      return false unless account.match?(/\A\d{1,13}\z/)
+      return false unless digit.match?(/\A[0-9A-Za-z]{1,2}\z/)
+
+      digit_upcase = digit.upcase
+      return true if %w[X P].include?(digit_upcase) && digit.length == 1
+
+      return false unless digit.match?(/\A\d{1,2}\z/)
+
+      if digit.length == 2
+        first_ok = digit[0].to_i == mod10_digit(account)
+        second_ok = digit[1].to_i == mod11_digit(account + digit[0])
+        first_ok && second_ok
+      else
+        digit.to_i == mod10_digit(account) || digit.to_i == mod11_digit(account)
+      end
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for looking up Brazilian banks by COMPE code or ISPB, sourced
+  # from the Banco Central do Brasil STR participants list.
+  module BankUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'banks.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'], ispb: row['ispb'], name: row['name'] }
+    end
+
+    private_class_method :to_symbolized
+
+    # Looks a bank up by its 3-digit COMPE code.
+    #
+    # @param code [String, Integer] A number is read as the zero-padded
+    #   3-digit code.
+    # @return [Hash, nil]
+    def self.get_by_code(code)
+      return nil if code.nil?
+
+      str = code.to_s.strip
+      return nil unless str.match?(/\A\d+\z/)
+
+      padded = str.rjust(3, '0')
+      row = load_data.find { |r| r['code'] == padded }
+      row && to_symbolized(row)
+    end
+
+    # Looks a bank up by its 8-digit ISPB.
+    #
+    # @param value [String, Integer] With or without leading zeros.
+    # @return [Hash, nil]
+    def self.get_by_ispb(value)
+      return nil if value.nil?
+
+      str = value.to_s.strip
+      return nil unless str.match?(/\A\d+\z/)
+
+      padded = str.rjust(8, '0')
+      row = load_data.find { |r| r['ispb'] == padded }
+      row && to_symbolized(row)
+    end
+
+    # Returns every bank with a COMPE code.
+    #
+    # @return [Array<Hash>]
+    def self.list
+      load_data.map { |row| to_symbolized(row) }
+    end
+  end
+end

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

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
+require 'date'
+
 module BrazilianUtils
   module BoletoUtils
+    # The fator de vencimento epoch (day 1000) before the 2025-02-22 cycle
+    # reset, and how many days apart the two candidate dates for a given
+    # factor are, per the contract's own description. Not independently
+    # verified against a reference implementation (no test cases were
+    # available for `boleto.getInfo`).
+    FATOR_VENCIMENTO_OLD_EPOCH = Date.new(1997, 10, 7)
+    FATOR_VENCIMENTO_CYCLE_GAP_DAYS = 9000
     # Every Digitable Line from Boleto has exactly 47 characters
     DIGITABLE_LINE_LENGTH = 47
 
@@ -52,6 +61,136 @@ module BrazilianUtils
       # Alias for is_valid
       alias valid? is_valid
 
+      # Removes boleto formatting and keeps only digits, capped to 47
+      # digits (48 for a boleto de arrecadação, recognized by a leading
+      # `8`).
+      #
+      # @param value [String, Integer]
+      # @return [String]
+      def parse(value)
+        return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+        digits = value.to_s.gsub(/\D/, '')
+        return '' if digits.empty?
+
+        cap = digits[0] == '8' ? 48 : 47
+        digits[0, cap]
+      end
+
+      # @private
+      def 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
+
+      # Formats a boleto linha digitável with its printed mask.
+      #
+      # @param value [String, Integer]
+      # @param options [Hash] `:pad` left-pads the value with zeros to the
+      #   length of the pattern before masking.
+      # @return [String]
+      def format(value, options = {})
+        digits = value.to_s.gsub(/\D/, '')
+        pad = options[:pad] || options['pad']
+
+        if pad
+          target = digits[0] == '8' ? 48 : 47
+          digits = digits.rjust(target, '0')
+        end
+
+        return '' if digits.empty?
+
+        if digits.length == 48 && digits[0] == '8'
+          digits.chars.each_slice(12).map { |b| b.join }.map do |block|
+            block.length > 11 ? "#{block[0, 11]}-#{block[11]}" : block
+          end.join(' ')
+        else
+          apply_mask(digits, [5, 5, 5, 6, 5, 6, 1, 14], ['.', ' ', '.', ' ', '.', ' ', ' '])
+        end
+      end
+
+      # Generates a valid random boleto number.
+      #
+      # @param params [Hash] `:type` set to `"arrecadacao"` generates a
+      #   48-digit boleto de arrecadação instead of the default 47-digit
+      #   cobrança bancária linha digitável.
+      # @return [String, nil] `nil` for `type: "arrecadacao"`: it is not
+      #   implemented (this module's {is_valid} itself only recognizes the
+      #   47-digit cobrança bancária form, so a generated arrecadação
+      #   number could not be verified to round-trip through it).
+      def generate(params = {})
+        type = params[:type] || params['type']
+        return nil if type.to_s == 'arrecadacao'
+
+        banco = sprintf('%03d', rand(1..999))
+        moeda = '9'
+        campo_livre = 25.times.map { rand(0..9) }.join
+        fator_vencimento = sprintf('%04d', rand(1000..9999))
+        valor = sprintf('%010d', rand(0..9_999_999_999))
+
+        campo1_free = campo_livre[0, 5]
+        campo2 = campo_livre[5, 10]
+        campo3 = campo_livre[15, 10]
+
+        campo1 = "#{banco}#{moeda}#{campo1_free}"
+        dv1 = get_mod10(campo1)
+        dv2 = get_mod10(campo2)
+        dv3 = get_mod10(campo3)
+
+        barcode_without_dv = "#{banco}#{moeda}#{fator_vencimento}#{valor}#{campo_livre}"
+        dv_geral = get_mod11(barcode_without_dv)
+
+        "#{campo1}#{dv1}#{campo2}#{dv2}#{campo3}#{dv3}#{dv_geral}#{fator_vencimento}#{valor}"
+      end
+
+      # Extracts the amount, due date and bank code from a boleto.
+      #
+      # @note Only the 47-digit cobrança bancária form is supported; a
+      #   boleto de arrecadação (48-digit linha digitável or 44-digit
+      #   barcode) returns nil. The due-date resolution (fator de
+      #   vencimento, including the 2025-02-22 cycle reset) has no
+      #   available test cases and is unverified against a reference
+      #   implementation.
+      #
+      # @param value [String]
+      # @param options [Hash] `:referenceDate` resolves the fator de
+      #   vencimento cycle as of that date (default: today).
+      # @return [Hash, nil]
+      def get_info(value, options = {})
+        return nil unless is_valid(value)
+
+        digits = extract_only_numbers(value)
+        return nil unless digits.length == DIGITABLE_LINE_LENGTH
+
+        barcode = parse_digitable_line(digits)
+        bank_code = barcode[0, 3]
+        fator_vencimento = barcode[5, 4].to_i
+        amount_cents = barcode[9, 10].to_i
+
+        reference_date = options[:referenceDate] || options['referenceDate'] || Date.today
+        reference_date = reference_date.to_date if reference_date.respond_to?(:to_date)
+
+        due_date =
+          if fator_vencimento >= 1000
+            date_a = FATOR_VENCIMENTO_OLD_EPOCH + (fator_vencimento - 1000)
+            date_b = date_a + FATOR_VENCIMENTO_CYCLE_GAP_DAYS
+            (date_a - reference_date).abs <= (date_b - reference_date).abs ? date_a : date_b
+          end
+
+        {
+          bankCode: bank_code,
+          amount: amount_cents,
+          dueDate: due_date
+        }
+      end
+
       private
 
       # Extract only numeric characters from a string.

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

@@ -0,0 +1,91 @@
+module BrazilianUtils
+  # Utilities for the CAEPF (Cadastro de Atividade Econômica da Pessoa
+  # Física): 14 digits — a 9-digit CPF base, a 3-digit sequence and 2 check
+  # digits.
+  module CAEPFUtils
+    # @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
+
+    # Computes a CNPJ-style modulus 11 check digit (the same algorithm
+    # `CNPJUtils` uses) over an arbitrary-length base.
+    #
+    # @private
+    def self.hashdigit(base, position)
+      weights = []
+      (position - 8).downto(2) { |w| weights << w }
+      9.downto(2) { |w| weights << w }
+
+      val = base.chars.first(position - 1).zip(weights).sum { |d, w| d.to_i * w } % 11
+      val < 2 ? 0 : 11 - val
+    end
+
+    private_class_method :hashdigit
+
+    # @private
+    def self.check_digits(base12)
+      first = hashdigit(base12, 13)
+      second = hashdigit(base12 + first.to_s, 14)
+      ((first * 10 + second) + 12) % 100
+    end
+
+    private_class_method :check_digits
+
+    # Validates a CAEPF: 14 digits, with both check digits following the
+    # CNPJ modulus 11 rule, shifted by 12 (wrapping around 100).
+    #
+    # @param value [String, Integer] Masked as `000.000.000/000-00` or not.
+    # @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{14}\z/)
+      return false if digits[0, 9].chars.uniq.length == 1
+
+      digits[12, 2].to_i == check_digits(digits[0, 12])
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Formats a CAEPF with the mask `000.000.000/000-00`, applied as far as
+    # the digits go.
+    #
+    # @param value [String, Integer]
+    # @param options [Hash] `:pad` left-pads with zeros to 14 digits first.
+    # @return [String]
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(14, '0') if options[:pad] || options['pad']
+      return '' if digits.empty?
+
+      apply_mask(digits, [3, 3, 3, 3, 2], ['.', '.', '/', '-'])
+    end
+
+    # Removes CAEPF formatting and keeps only digits, capped to 14 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, 14]
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+require 'json'
+
+module BrazilianUtils
+  # Utilities for the CBO (Classificação Brasileira de Ocupações) 2002
+  # occupation table (6-digit "ocupação" granularity).
+  module CBOUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'cbo.json')
+
+    # @private
+    def self.load_data
+      @data ||= JSON.parse(File.read(DATA_FILE))
+    end
+
+    private_class_method :load_data
+
+    # Normalizes a CBO value to its bare 6 digits: bare digits (string or
+    # integer) are left-padded with zeros to 6; the `NNNN-NN` mask (a
+    # single separator between the groups) is read as written. Any other
+    # string is rejected (its digits are not picked out).
+    #
+    # @private
+    def self.normalize(value)
+      return nil if value.nil?
+      return value.to_s.rjust(6, '0') if value.is_a?(Integer)
+      return nil unless value.is_a?(String)
+
+      raw = value.strip
+      return raw.rjust(6, '0') if raw.match?(/\A\d+\z/)
+
+      m = raw.match(%r{\A(\d{4})[ .\-/](\d{2})\z})
+      m && "#{m[1]}#{m[2]}"
+    end
+
+    private_class_method :normalize
+
+    # Checks whether a CBO code exists in the official 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 CBO code up and returns its (bare, 6-digit) code and title.
+    #
+    # @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 CBO formatting and keeps only digits, capped to 6 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, 6]
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+module BrazilianUtils
+  # Utilities for the CEI (Cadastro Específico do INSS), a 12-digit
+  # registration number for a work/construction site or rural employer.
+  module CEIUtils
+    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 CEI: 12 digits, 11 base digits and one check digit.
+    #
+    # @param value [String, Integer] Bare digits, or split into the printed
+    #   groups (2, 3, 5 and 2 digits) by whitespace or the usual mask
+    #   characters (`.`, `-`, `/`).
+    # @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 CEI with the mask `00.000.00000/00`, applied as far as the
+    # digits go.
+    #
+    # @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 CEI 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/cep-utils.rb

@@ -57,9 +57,12 @@ module BrazilianUtils
     :cep,
     :logradouro,
     :complemento,
+    :unidade,
     :bairro,
     :localidade,
     :uf,
+    :estado,
+    :regiao,
     :ibge,
     :gia,
     :ddd,
@@ -141,6 +144,20 @@ module BrazilianUtils
       8.times.map { rand(10) }.join
     end
 
+    # Removes CEP formatting and keeps only digits, capped to 8 digits.
+    #
+    # @param value [String, Integer] A CEP, with or without formatting.
+    # @return [String] The parsed digits.
+    #
+    # @example
+    #   parse("01001-000")      #=> "01001000"
+    #   parse("01001000123")    #=> "01001000"
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 8]
+    end
+
     # API OPERATIONS
     ################
 
@@ -203,9 +220,12 @@ module BrazilianUtils
           cep: data['cep'],
           logradouro: data['logradouro'],
           complemento: data['complemento'],
+          unidade: data['unidade'],
           bairro: data['bairro'],
           localidade: data['localidade'],
           uf: data['uf'],
+          estado: data['estado'],
+          regiao: data['regiao'],
           ibge: data['ibge'],
           gia: data['gia'],
           ddd: data['ddd'],
@@ -245,9 +265,19 @@ module BrazilianUtils
     #   #=> CEPNotFound: SP - Example - Example
     #
     # @see https://viacep.com.br/
-    def self.get_cep_information_from_address(federal_unit, city, street, raise_exceptions: false)
+    def self.get_cep_information_from_address(federal_unit, city = nil, street = nil, raise_exceptions: false)
       base_api_url = 'https://viacep.com.br/ws/%s/%s/%s/json/'
 
+      # Accept the contract's single-Hash-argument form, e.g.
+      # get_cep_information_from_address(state: "SP", city: "São Paulo", street: "Paulista")
+      if federal_unit.is_a?(Hash)
+        params = federal_unit
+        federal_unit = params[:state] || params[:uf] || params['state'] || params['uf']
+        city = params[:city] || params['city']
+        street = params[:street] || params['street']
+        raise_exceptions = params[:raise_exceptions] || params['raise_exceptions'] || raise_exceptions
+      end
+
       # Validate UF
       uf_code = federal_unit.to_s.upcase
       uf_name = UF.name_from_code(uf_code)
@@ -294,9 +324,12 @@ module BrazilianUtils
             cep: address_data['cep'],
             logradouro: address_data['logradouro'],
             complemento: address_data['complemento'],
+            unidade: address_data['unidade'],
             bairro: address_data['bairro'],
             localidade: address_data['localidade'],
             uf: address_data['uf'],
+            estado: address_data['estado'],
+            regiao: address_data['regiao'],
             ibge: address_data['ibge'],
             gia: address_data['gia'],
             ddd: address_data['ddd'],