br-utils 0.1.1 → 0.2.0

data/lib/brazilian-utils/legal-nature-utils.rb

@@ -1,235 +1,238 @@
-module BrazilianUtils
-  # Utilities for consulting and validating the official *Natureza Jurídica* (Legal Nature) 
-  # codes defined by the Receita Federal do Brasil (RFB).
-  #
-  # The codes and descriptions in this module are sourced from the official 
-  # **Tabela de Natureza Jurídica** (RFB), as provided in the document used 
-  # by the Cadastro Nacional (e.g., FCN).
-  #
-  # This module offers simple lookups and validation helpers based on the official table. 
-  # It does not infer the current legal/registration status of any entity.
-  #
-  # Source: https://www.gov.br/empresas-e-negocios/pt-br/drei/links-e-downloads/arquivos/TABELADENATUREZAJURDICA.pdf
-  module LegalNatureUtils
-    # Official Legal Nature codes from Receita Federal do Brasil
-    # Format: 4-digit code => Description in Portuguese
-    LEGAL_NATURE = {
-      # 1. ADMINISTRAÇÃO PÚBLICA
-      '1015' => 'Órgão Público do Poder Executivo Federal',
-      '1023' => 'Órgão Público do Poder Executivo Estadual ou do Distrito Federal',
-      '1031' => 'Órgão Público do Poder Executivo Municipal',
-      '1040' => 'Órgão Público do Poder Legislativo Federal',
-      '1058' => 'Órgão Público do Poder Legislativo Estadual ou do Distrito Federal',
-      '1066' => 'Órgão Público do Poder Legislativo Municipal',
-      '1074' => 'Órgão Público do Poder Judiciário Federal',
-      '1082' => 'Órgão Público do Poder Judiciário Estadual',
-      '1104' => 'Autarquia Federal',
-      '1112' => 'Autarquia Estadual ou do Distrito Federal',
-      '1120' => 'Autarquia Municipal',
-      '1139' => 'Fundação Federal',
-      '1147' => 'Fundação Estadual ou do Distrito Federal',
-      '1155' => 'Fundação Municipal',
-      '1163' => 'Órgão Público Autônomo da União',
-      '1171' => 'Órgão Público Autônomo Estadual ou do Distrito Federal',
-      '1180' => 'Órgão Público Autônomo Municipal',
-      
-      # 2. ENTIDADES EMPRESARIAIS
-      '2011' => 'Empresa Pública',
-      '2038' => 'Sociedade de Economia Mista',
-      '2046' => 'Sociedade Anônima Aberta',
-      '2054' => 'Sociedade Anônima Fechada',
-      '2062' => 'Sociedade Empresária Limitada',
-      '2076' => 'Sociedade Empresária em Nome Coletivo',
-      '2089' => 'Sociedade Empresária em Comandita Simples',
-      '2097' => 'Sociedade Empresária em Comandita por Ações',
-      '2100' => 'Sociedade Mercantil de Capital e Indústria (extinta pelo NCC/2002)',
-      '2127' => 'Sociedade Empresária em Conta de Participação',
-      '2135' => 'Empresário (Individual)',
-      '2143' => 'Cooperativa',
-      '2151' => 'Consórcio de Sociedades',
-      '2160' => 'Grupo de Sociedades',
-      '2178' => 'Estabelecimento, no Brasil, de Sociedade Estrangeira',
-      '2194' => 'Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira',
-      '2208' => 'Entidade Binacional Itaipu',
-      '2216' => 'Empresa Domiciliada no Exterior',
-      '2224' => 'Clube/Fundo de Investimento',
-      '2232' => 'Sociedade Simples Pura',
-      '2240' => 'Sociedade Simples Limitada',
-      '2259' => 'Sociedade em Nome Coletivo',
-      '2267' => 'Sociedade em Comandita Simples',
-      '2275' => 'Sociedade Simples em Conta de Participação',
-      '2305' => 'Empresa Individual de Responsabilidade Limitada',
-      
-      # 3. ENTIDADES SEM FINS LUCRATIVOS
-      '3034' => 'Serviço Notarial e Registral (Cartório)',
-      '3042' => 'Organização Social',
-      '3050' => 'Organização da Sociedade Civil de Interesse Público (Oscip)',
-      '3069' => 'Outras Formas de Fundações Mantidas com Recursos Privados',
-      '3077' => 'Serviço Social Autônomo',
-      '3085' => 'Condomínio Edilícios',
-      '3093' => 'Unidade Executora (Programa Dinheiro Direto na Escola)',
-      '3107' => 'Comissão de Conciliação Prévia',
-      '3115' => 'Entidade de Mediação e Arbitragem',
-      '3123' => 'Partido Político',
-      '3131' => 'Entidade Sindical',
-      '3204' => 'Estabelecimento, no Brasil, de Fundação ou Associação Estrangeiras',
-      '3212' => 'Fundação ou Associação Domiciliada no Exterior',
-      '3999' => 'Outras Formas de Associação',
-      
-      # 4. PESSOAS FÍSICAS
-      '4014' => 'Empresa Individual Imobiliária',
-      '4022' => 'Segurado Especial',
-      '4081' => 'Contribuinte individual',
-      
-      # 5. ORGANIZAÇÕES INTERNACIONAIS E OUTRAS INSTITUIÇÕES EXTRATERRITORIAIS
-      '5002' => 'Organização Internacional e Outras Instituições Extraterritoriais'
-    }.freeze
-
-    # Normalizes a legal nature code to 4-digit format.
-    # Accepts formats like "2062", "206-2", or any string with exactly 4 digits.
-    #
-    # @param code [String] The code to normalize
-    # @return [String, nil] The normalized 4-digit code, or nil if invalid
-    #
-    # @private
-    def self.normalize(code)
-      return nil unless code.is_a?(String)
-
-      # Extract only digits from the input
-      digits = code.strip.gsub(/\D/, '')
-
-      # Return the digits only if we have exactly 4
-      digits.length == 4 ? digits : nil
-    end
-
-    private_class_method :normalize
-
-    # Checks if a string corresponds to a valid *Natureza Jurídica* code.
-    #
-    # Validation is based solely on the presence of the code in the official RFB table. 
-    # It does not verify the current legal status or registration of the entity.
-    #
-    # @param code [String] The code to be validated. Accepts either "NNNN" or "NNN-N" format.
-    #
-    # @return [Boolean] Returns true if the normalized code exists in the official table, 
-    #   false otherwise.
-    #
-    # @example Valid codes
-    #   is_valid("2062")      #=> true (Sociedade Empresária Limitada)
-    #   is_valid("206-2")     #=> true (same, with hyphen)
-    #   is_valid("1015")      #=> true (Órgão Público Federal)
-    #   is_valid("101-5")     #=> true (same, with hyphen)
-    #
-    # @example Invalid codes
-    #   is_valid("9999")      #=> false (not in official table)
-    #   is_valid("0000")      #=> false (not in official table)
-    #   is_valid("123")       #=> false (wrong length)
-    #   is_valid("abcd")      #=> false (not digits)
-    #   is_valid(nil)         #=> false (not a string)
-    def self.is_valid(code)
-      normalized = normalize(code)
-      return false unless normalized
-
-      LEGAL_NATURE.key?(normalized)
-    end
-
-    # Alias for is_valid to provide Ruby-style naming
-    class << self
-      alias valid? is_valid
-    end
-
-    # Retrieves the description of a *Natureza Jurídica* code.
-    #
-    # @param code [String] The code to look up. Accepts either "NNNN" or "NNN-N" format.
-    #
-    # @return [String, nil] The full description if the code is valid, otherwise nil.
-    #
-    # @example Valid lookups
-    #   get_description("2062")
-    #   #=> "Sociedade Empresária Limitada"
-    #
-    #   get_description("101-5")
-    #   #=> "Órgão Público do Poder Executivo Federal"
-    #
-    #   get_description("2305")
-    #   #=> "Empresa Individual de Responsabilidade Limitada"
-    #
-    # @example Invalid lookups
-    #   get_description("0000")
-    #   #=> nil
-    #
-    #   get_description("invalid")
-    #   #=> nil
-    def self.get_description(code)
-      normalized = normalize(code)
-      return nil unless normalized
-
-      LEGAL_NATURE[normalized]
-    end
-
-    # Returns a copy of the full *Natureza Jurídica* table.
-    #
-    # @return [Hash<String, String>] Mapping from 4-digit codes to descriptions
-    #
-    # @example
-    #   all_codes = list_all
-    #   all_codes["2062"]
-    #   #=> "Sociedade Empresária Limitada"
-    #
-    #   all_codes.size
-    #   #=> 60 (total number of codes in the official table)
-    def self.list_all
-      LEGAL_NATURE.dup
-    end
-
-    # Returns all codes within a specific category.
-    #
-    # Categories:
-    # - 1: Administração Pública (Public Administration)
-    # - 2: Entidades Empresariais (Business Entities)
-    # - 3: Entidades Sem Fins Lucrativos (Non-Profit Entities)
-    # - 4: Pessoas Físicas (Individuals)
-    # - 5: Organizações Internacionais (International Organizations)
-    #
-    # @param category [Integer, String] The category number (1-5)
-    #
-    # @return [Hash<String, String>] Codes and descriptions for the specified category
-    #
-    # @example
-    #   business_entities = list_by_category(2)
-    #   business_entities.keys
-    #   #=> ["2011", "2038", "2046", ...]
-    #
-    #   non_profits = list_by_category(3)
-    #   non_profits["3123"]
-    #   #=> "Partido Político"
-    def self.list_by_category(category)
-      category_str = category.to_s
-      return {} unless ['1', '2', '3', '4', '5'].include?(category_str)
-
-      LEGAL_NATURE.select { |code, _| code.start_with?(category_str) }
-    end
-
-    # Returns the category number for a given code.
-    #
-    # @param code [String] The code to check. Accepts either "NNNN" or "NNN-N" format.
-    #
-    # @return [Integer, nil] The category number (1-5), or nil if invalid
-    #
-    # @example
-    #   get_category("2062")
-    #   #=> 2 (Entidades Empresariais)
-    #
-    #   get_category("101-5")
-    #   #=> 1 (Administração Pública)
-    #
-    #   get_category("9999")
-    #   #=> nil (invalid code)
-    def self.get_category(code)
-      normalized = normalize(code)
-      return nil unless normalized && LEGAL_NATURE.key?(normalized)
-
-      normalized[0].to_i
-    end
-  end
-end
+require 'json'
+
+module BrazilianUtils
+  # Utilities for consulting and validating the official *Natureza Jurídica* (Legal Nature)
+  # codes defined by IBGE/CONCLA and the Receita Federal do Brasil (RFB).
+  #
+  # The table backing this module is CONCLA's Natureza Jurídica 2021 table:
+  # 92 codes currently in force, plus a best-effort list of codes retired by
+  # past revisions (see `data/legal_nature.json`).
+  #
+  # This module offers simple lookups and validation helpers based on the
+  # official table. It does not infer the current legal/registration status
+  # of any entity.
+  #
+  # Source: https://concla.ibge.gov.br/images/concla/documentacao/CONCLA-TNJ2021-NotasExplicativas.pdf
+  module LegalNatureUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'legal_nature.json')
+
+    # @private
+    def self.load_data
+      return @data if @data
+
+      raw = JSON.parse(File.read(DATA_FILE))
+      in_force = {}
+      raw['inForce'].each { |row| in_force[row['code']] = row }
+      retired = {}
+      raw['retired'].each { |row| retired[row['code']] = row }
+      @data = { in_force: in_force, retired: retired }
+    end
+
+    private_class_method :load_data
+
+    # Normalizes a legal nature code: strips hyphens, dots and whitespace,
+    # and requires exactly 4 digits.
+    #
+    # @param code [String, Integer] The code to normalize
+    # @return [String, nil] The normalized 4-digit code, or nil if invalid
+    #
+    # @private
+    def self.normalize(code)
+      return nil unless code.is_a?(String) || code.is_a?(Integer)
+
+      digits = code.to_s.gsub(/[-.\s]/, '')
+      digits.match?(/\A\d{4}\z/) ? digits : nil
+    end
+
+    private_class_method :normalize
+
+    # @private
+    def self.entry_to_hash(row)
+      entry = {
+        code: row['code'],
+        description: row['description'],
+        category: { code: row['category']['code'], description: row['category']['description'] },
+        legacy: row['legacy']
+      }
+      entry[:currentCode] = row['currentCode'] if row['legacy']
+      entry
+    end
+
+    private_class_method :entry_to_hash
+
+    # Checks if a string corresponds to a valid *Natureza Jurídica* code.
+    #
+    # Accepts both the 92 codes currently in force and the (best-effort)
+    # list of codes retired by a past revision.
+    #
+    # @param code [String] The code to be validated. Accepts "NNNN" or
+    #   "NNN-N", with hyphens/dots/whitespace tolerated around the digits.
+    #
+    # @return [Boolean] Returns true if the normalized code exists in the
+    #   official table (in force or retired), false otherwise.
+    #
+    # @example Valid codes
+    #   is_valid("2062")      #=> true (Sociedade Empresária Limitada)
+    #   is_valid("206-2")     #=> true (same, with hyphen)
+    #
+    # @example Invalid codes
+    #   is_valid("9999")      #=> false (not in official table)
+    #   is_valid("abcd")      #=> false (not digits)
+    #   is_valid(nil)         #=> false (not a string)
+    def self.is_valid(code)
+      normalized = normalize(code)
+      return false unless normalized
+
+      data = load_data
+      data[:in_force].key?(normalized) || data[:retired].key?(normalized)
+    end
+
+    class << self
+      alias valid? is_valid
+    end
+
+    # Retrieves the description of a *Natureza Jurídica* code.
+    #
+    # @param code [String] The code to look up. Accepts "NNNN" or "NNN-N".
+    #
+    # @return [String, nil] The full description if the code is valid, otherwise nil.
+    #
+    # @example
+    #   get_description("2062")   #=> "Sociedade Empresária Limitada"
+    #   get_description("101-5")  #=> "Órgão Público do Poder Executivo Federal"
+    def self.get_description(code)
+      normalized = normalize(code)
+      return nil unless normalized
+
+      data = load_data
+      row = data[:in_force][normalized] || data[:retired][normalized]
+      row && row['description']
+    end
+
+    # Looks a legal nature code up in the IBGE/CONCLA Natureza Jurídica 2021
+    # table.
+    #
+    # @param value [String, Integer] The code to look up ("NNNN" or "NNN-N").
+    # @return [Hash, nil] `{ code:, description:, category: { code:,
+    #   description: }, legacy:, currentCode: (only when legacy) }`, or nil
+    #   for an unknown code.
+    #
+    # @example
+    #   get("2062")   #=> { code: "2062", description: "Sociedade Empresária Limitada", category: { code: "2", description: "Entidades Empresariais" }, legacy: false }
+    #   get("2208")   #=> { code: "2208", description: "Entidade Binacional Itaipu", ..., legacy: true, currentCode: "2275" }
+    def self.get(value)
+      normalized = normalize(value)
+      return nil unless normalized
+
+      data = load_data
+      row = data[:in_force][normalized] || data[:retired][normalized]
+      row && entry_to_hash(row)
+    end
+
+    # Formats a legal nature code as `NNN-N`.
+    #
+    # The mask is applied as far as the digits go (fewer than 4 digits are
+    # returned unmasked); use {is_valid} to check the code first.
+    #
+    # @param value [String, Integer] The value to format.
+    # @param options [Hash] `:pad` left-pads the value with zeros to 4
+    #   digits first.
+    # @return [String] The masked code, or as much of the mask as fits.
+    #
+    # @example
+    #   format("2062")           #=> "206-2"
+    #   format("206-2")          #=> "206-2"
+    #   format("206")            #=> "206"
+    def self.format(value, options = {})
+      digits = value.to_s.gsub(/\D/, '')
+      digits = digits.rjust(4, '0') if options[:pad] || options['pad']
+      return digits if digits.length < 4
+
+      "#{digits[0, 3]}-#{digits[3]}"
+    end
+
+    # Generates a random valid legal nature code (4 digits), drawn only
+    # among the 92 codes currently in force.
+    #
+    # @return [String] A randomly generated, valid legal nature code.
+    def self.generate
+      load_data[:in_force].keys.sample
+    end
+
+    # Returns a copy of the *Natureza Jurídica* table as a map from code to
+    # description.
+    #
+    # @param params [Hash] `:include_retired` also includes the retired
+    #   codes (default false: only the 92 codes in force).
+    # @return [Hash<String, String>] Mapping from 4-digit codes to descriptions
+    #
+    # @example
+    #   all_codes = list
+    #   all_codes["2062"]  #=> "Sociedade Empresária Limitada"
+    def self.list(params = {})
+      include_retired = params[:include_retired] || params['include_retired']
+      data = load_data
+      result = {}
+      data[:in_force].each { |code, row| result[code] = row['description'] }
+      data[:retired].each { |code, row| result[code] = row['description'] } if include_retired
+      result
+    end
+
+    class << self
+      alias list_all list
+    end
+
+    # Returns every legal nature of a CONCLA category (the first digit of
+    # the code), sorted by code.
+    #
+    # Categories: 1 Administração Pública, 2 Entidades Empresariais,
+    # 3 Entidades sem Fins Lucrativos, 4 Pessoas Físicas,
+    # 5 Organizações Internacionais e Outras Instituições Extraterritoriais.
+    #
+    # @param category [Integer, String] The category number (1-5)
+    # @param options [Hash] `:include_retired` also includes retired codes.
+    #
+    # @return [Array<Hash>] The legal natures of the category, in the same
+    #   shape as {get}, sorted by code; an empty array for an unknown
+    #   category.
+    def self.list_by_category(category, options = {})
+      category_str = category.to_s
+      return [] unless %w[1 2 3 4 5].include?(category_str)
+
+      include_retired = options[:include_retired] || options['include_retired']
+      data = load_data
+
+      rows = data[:in_force].values.select { |row| row['category']['code'] == category_str }
+      rows += data[:retired].values.select { |row| row['category']['code'] == category_str } if include_retired
+
+      rows.sort_by { |row| row['code'] }.map { |row| entry_to_hash(row) }
+    end
+
+    # Returns the category number for a given code.
+    #
+    # @param code [String] The code to check. Accepts "NNNN" or "NNN-N".
+    #
+    # @return [Integer, nil] The category number (1-5), or nil if invalid
+    #
+    # @example
+    #   get_category("2062")   #=> 2 (Entidades Empresariais)
+    #   get_category("9999")   #=> nil (invalid code)
+    def self.get_category(code)
+      entry = get(code)
+      entry && entry[:category][:code].to_i
+    end
+
+    # Removes legal nature formatting and keeps only digits, capped to 4 digits.
+    #
+    # @param value [String, Integer] A legal nature code, with or without formatting.
+    # @return [String] The parsed digits.
+    #
+    # @example
+    #   parse("206-2")  #=> "2062"
+    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/legal-process-utils.rb

@@ -131,10 +131,12 @@ module BrazilianUtils
 
     # Generates a random legal process ID.
     #
-    # @param year [Integer] The year for the legal process ID (default is current year).
+    # @param year [Integer, Hash] The year for the legal process ID (default
+    #   is current year), or a single options Hash (as the contract's
+    #   `GenerateProcessoJuridicoParams`) with `:year` and `:court`.
     #   The year should not be in the past.
     # @param orgao [Integer] The judicial segment code (1-9) for the legal process ID
-    #   (default is random)
+    #   (default is random). Ignored when `year` is a Hash.
     #
     # @return [String, nil] A randomly generated legal process ID (20 digits),
     #   or nil if arguments are invalid
@@ -146,9 +148,19 @@ module BrazilianUtils
     #   generate()
     #   #=> "88031888120233030000" (uses current year and random orgao)
     #
+    #   generate(year: 2023, court: 5)
+    #   #=> "51659517020235080562" (contract-style options Hash)
+    #
     #   generate(2022, 10)
     #   #=> nil (year in the past, orgao out of range)
-    def self.generate(year = Time.now.year, orgao = rand(1..9))
+    def self.generate(year = Time.now.year, orgao = nil)
+      if year.is_a?(Hash)
+        options = year
+        year = options[:year] || options['year'] || Time.now.year
+        orgao = options[:court] || options[:orgao] || options['court'] || options['orgao']
+      end
+      orgao ||= rand(1..9)
+
       return nil if year < Time.now.year
       return nil unless (1..9).include?(orgao)
 
@@ -238,5 +250,21 @@ module BrazilianUtils
     end
 
     private_class_method :load_legal_process_data
+
+    # Removes legal process formatting and keeps only digits, capped to 20
+    # digits.
+    #
+    # @param value [String, Integer] A legal process number, with or without
+    #   the CNJ mask.
+    # @return [String] The parsed digits.
+    #
+    # @example
+    #   parse("0002080-25.2012.5.15.0049")  #=> "00020802520125150049"
+    #   parse("00020802520125150049123")    #=> "00020802520125150049"
+    def self.parse(value)
+      return '' unless value.is_a?(String) || value.is_a?(Integer)
+
+      value.to_s.gsub(/\D/, '')[0, 20]
+    end
   end
 end

data/lib/brazilian-utils/license-plate-utils.rb

@@ -34,19 +34,19 @@ module BrazilianUtils
     #   #=> "ABC1C34"
     #
     #   convert_to_mercosul("ABC4*67")
-    #   #=> nil
+    #   #=> ""
     def self.convert_to_mercosul(license_plate)
-      return nil unless license_plate.is_a?(String)
+      return '' unless license_plate.is_a?(String)
 
       clean = remove_symbols(license_plate).upcase
-      return nil unless valid_old_format?(clean)
+      return '' unless valid_old_format?(clean)
 
       chars = clean.chars
-      
+
       # Convert the 5th character (index 4) - the first digit after the letters
       # 0→A, 1→B, 2→C, etc.
       chars[4] = ('A'.ord + chars[4].to_i).chr
-      
+
       chars.join
     end
 
@@ -279,5 +279,21 @@ module BrazilianUtils
     end
 
     private_class_method :valid_mercosul?
+
+    # Removes separators from a license plate, upper-cases it and caps it to
+    # 7 characters.
+    #
+    # @param value [String] A license plate string, in any case, with or
+    #   without separators.
+    # @return [String] The parsed value.
+    #
+    # @example
+    #   parse("abc-1234")     #=> "ABC1234"
+    #   parse("abc123456")    #=> "ABC1234"
+    def self.parse(value)
+      return '' unless value.is_a?(String)
+
+      remove_symbols(value).upcase[0, 7]
+    end
   end
 end

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

@@ -0,0 +1,58 @@
+require 'json'
+require_relative 'text-utils'
+
+module BrazilianUtils
+  # Utilities for looking up Brazilian municipalities by IBGE code, sourced
+  # from the IBGE Localidades API (5,571 municipalities).
+  module MunicipalityUtils
+    DATA_FILE = File.join(File.dirname(__FILE__), 'data', 'municipalities.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'], name: row['name'], stateCode: row['stateCode'] }
+    end
+
+    private_class_method :to_symbolized
+
+    # Looks a municipality up by its 7-digit IBGE code.
+    #
+    # @param code [String, Integer]
+    # @return [Hash, nil]
+    def self.get_by_code(code)
+      return nil if code.nil?
+
+      str = code.to_s.gsub(/\D/, '')
+      return nil unless str.length == 7
+
+      row = load_data.find { |r| r['code'] == str }
+      row && to_symbolized(row)
+    end
+
+    # Returns Brazilian municipalities, sorted by name (pt-BR collation).
+    #
+    # @param state_code [String, nil] Only that state's municipalities; when
+    #   omitted, every municipality. An empty or unknown code returns an
+    #   empty list (matching is case-sensitive).
+    # @return [Array<Hash>]
+    def self.list(state_code = nil)
+      rows = load_data
+
+      unless state_code.nil?
+        return [] unless state_code.is_a?(String) && !state_code.empty?
+
+        rows = rows.select { |r| r['stateCode'] == state_code }
+      end
+
+      rows
+        .sort_by { |r| TextUtils.remove_accents(r['name']).downcase }
+        .map { |r| to_symbolized(r) }
+    end
+  end
+end