br-utils 0.1.0

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

@@ -0,0 +1,244 @@
+require 'date'
+
+module BrazilianUtils
+  # Brazilian months enumeration
+  module Months
+    NAMES = {
+      1 => 'janeiro',
+      2 => 'fevereiro',
+      3 => 'março',
+      4 => 'abril',
+      5 => 'maio',
+      6 => 'junho',
+      7 => 'julho',
+      8 => 'agosto',
+      9 => 'setembro',
+      10 => 'outubro',
+      11 => 'novembro',
+      12 => 'dezembro'
+    }.freeze
+
+    def self.name(month_number)
+      NAMES[month_number]
+    end
+  end
+
+  module DateUtils
+    DATE_REGEX = /^\d{2}\/\d{2}\/\d{4}$/.freeze
+
+    # Brazilian national holidays (fixed dates)
+    NATIONAL_HOLIDAYS = {
+      [1, 1] => 'Ano Novo',
+      [4, 21] => 'Tiradentes',
+      [5, 1] => 'Dia do Trabalho',
+      [9, 7] => 'Independência do Brasil',
+      [10, 12] => 'Nossa Senhora Aparecida',
+      [11, 2] => 'Finados',
+      [11, 15] => 'Proclamação da República',
+      [12, 25] => 'Natal'
+    }.freeze
+
+    # State-specific holidays (fixed dates)
+    STATE_HOLIDAYS = {
+      'AC' => { [1, 23] => 'Dia do Evangélico', [6, 15] => 'Aniversário do Acre', [9, 5] => 'Dia da Amazônia', [11, 17] => 'Assinatura do Tratado de Petrópolis' },
+      'AL' => { [6, 24] => 'São João', [6, 29] => 'São Pedro', [9, 16] => 'Emancipação Política', [11, 20] => 'Morte de Zumbi dos Palmares' },
+      'AM' => { [9, 5] => 'Elevação do Amazonas à categoria de província' },
+      'AP' => { [3, 19] => 'Dia de São José', [9, 13] => 'Criação do Território Federal' },
+      'BA' => { [7, 2] => 'Independência da Bahia' },
+      'CE' => { [3, 19] => 'São José', [3, 25] => 'Data Magna do Ceará' },
+      'DF' => { [4, 21] => 'Fundação de Brasília', [11, 30] => 'Dia do Evangélico' },
+      'ES' => { [4, 21] => 'Nossa Senhora da Penha' },
+      'GO' => { [10, 24] => 'Pedra fundamental de Goiânia' },
+      'MA' => { [7, 28] => 'Adesão do Maranhão à independência do Brasil' },
+      'MG' => { [4, 21] => 'Data Magna de Minas Gerais' },
+      'MS' => { [10, 11] => 'Criação do estado' },
+      'MT' => { [11, 20] => 'Dia da Consciência Negra' },
+      'PA' => { [8, 15] => 'Adesão do Grão-Pará à independência do Brasil' },
+      'PB' => { [7, 26] => 'Homenagem à memória do ex-presidente João Pessoa', [8, 5] => 'Fundação do Estado em 1585' },
+      'PE' => { [3, 6] => 'Revolução Pernambucana de 1817', [6, 24] => 'São João' },
+      'PI' => { [10, 19] => 'Dia do Piauí' },
+      'PR' => { [12, 19] => 'Emancipação política do Paraná' },
+      'RJ' => { [4, 23] => 'Dia de São Jorge', [11, 20] => 'Dia da Consciência Negra' },
+      'RN' => { [6, 29] => 'Dia de São Pedro', [10, 3] => 'Mártires de Cunhaú e Uruaçu' },
+      'RO' => { [1, 4] => 'Criação do estado', [6, 18] => 'Dia do Evangélico' },
+      'RR' => { [10, 5] => 'Criação de Roraima' },
+      'RS' => { [9, 20] => 'Revolução Farroupilha' },
+      'SC' => { [8, 11] => 'Criação da capitania, separando-se de SP' },
+      'SE' => { [7, 8] => 'Autonomia política de Sergipe' },
+      'SP' => { [7, 9] => 'Revolução Constitucionalista de 1932' },
+      'TO' => { [10, 5] => 'Criação de Tocantins' }
+    }.freeze
+
+    VALID_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 if the given date is a national or state holiday in Brazil.
+    #
+    # This function takes a date as a Date or DateTime object and an optional UF (Unidade Federativa),
+    # returning a boolean value indicating whether the date is a holiday or nil if the date or
+    # UF are invalid.
+    #
+    # The method does not handle municipal holidays.
+    #
+    # @param target_date [Date, DateTime, Time] The date to be checked.
+    # @param uf [String, nil] The state abbreviation (UF) to check for state holidays.
+    #   If not provided, only national holidays will be considered.
+    #
+    # @return [Boolean, nil] Returns true if the date is a holiday, false if it is not,
+    #   or nil if the date or UF are invalid.
+    #
+    # @note This implementation includes fixed national and state holidays.
+    #   Movable holidays (like Carnival, Easter) are not included in this basic implementation.
+    #
+    # @example
+    #   is_holiday(Date.new(2024, 1, 1))          #=> true (New Year)
+    #   is_holiday(Date.new(2024, 1, 2))          #=> false
+    #   is_holiday(Date.new(2024, 7, 9), 'SP')    #=> true (SP state holiday)
+    #   is_holiday(Date.new(2024, 12, 25), 'RJ')  #=> true (Christmas)
+    def self.is_holiday(target_date, uf = nil)
+      return nil unless target_date.is_a?(Date) || target_date.is_a?(DateTime) || target_date.is_a?(Time)
+
+      # Convert to Date if needed
+      date = target_date.is_a?(Date) ? target_date : target_date.to_date
+
+      # Validate UF if provided
+      if uf && !VALID_UFS.include?(uf.to_s.upcase)
+        return nil
+      end
+
+      month_day = [date.month, date.day]
+
+      # Check national holidays
+      return true if NATIONAL_HOLIDAYS.key?(month_day)
+
+      # Check state holidays if UF is provided
+      if uf
+        state_uf = uf.to_s.upcase
+        state_holidays = STATE_HOLIDAYS[state_uf]
+        return true if state_holidays && state_holidays.key?(month_day)
+      end
+
+      false
+    end
+
+    # Converts a given date in Brazilian format (dd/mm/yyyy) to its textual representation.
+    #
+    # This function takes a date as a string in the format dd/mm/yyyy and converts it
+    # to a string with the date written out in Brazilian Portuguese, including the full
+    # month name and the year.
+    #
+    # @param date [String] The date to be converted into text. Expected format: dd/mm/yyyy.
+    #
+    # @return [String, nil] A string with the date written out in Brazilian Portuguese,
+    #   or nil if the date is invalid.
+    #
+    # @example
+    #   convert_date_to_text("01/01/2024")  #=> "Primeiro de janeiro de dois mil e vinte e quatro"
+    #   convert_date_to_text("15/03/2024")  #=> "Quinze de março de dois mil e vinte e quatro"
+    #   convert_date_to_text("invalid")     #=> nil
+    def self.convert_date_to_text(date)
+      return nil unless DATE_REGEX.match?(date)
+
+      begin
+        dt = Date.strptime(date, '%d/%m/%Y')
+      rescue ArgumentError
+        return nil
+      end
+
+      day = dt.day
+      month = dt.month
+      year = dt.year
+
+      # Convert day to text (special case for 1st)
+      day_str = if day == 1
+                  'Primeiro'
+                else
+                  # Reuse number_to_words from CurrencyUtils or implement inline
+                  number_to_words(day).capitalize
+                end
+
+      month_name = Months.name(month)
+      year_str = number_to_words(year)
+
+      "#{day_str} de #{month_name} de #{year_str}"
+    end
+
+    # Converts a number to its textual representation in Brazilian Portuguese.
+    # This is a simplified version focused on dates (days 1-31, years).
+    #
+    # @param number [Integer] The number to convert
+    # @return [String] The textual representation
+    #
+    # @private
+    def self.number_to_words(number)
+      return 'zero' if number.zero?
+
+      ones = %w[zero um dois três quatro cinco seis sete oito nove]
+      tens = %w[dez onze doze treze quatorze quinze dezesseis dezessete dezoito dezenove]
+      tens_multiples = %w[_ _ vinte trinta quarenta cinquenta sessenta setenta oitenta noventa]
+      hundreds = %w[
+        _
+        cento
+        duzentos
+        trezentos
+        quatrocentos
+        quinhentos
+        seiscentos
+        setecentos
+        oitocentos
+        novecentos
+      ]
+
+      if number < 10
+        return ones[number]
+      elsif number < 20
+        return tens[number - 10]
+      elsif number < 100
+        tens_digit = number / 10
+        ones_digit = number % 10
+        if ones_digit.zero?
+          return tens_multiples[tens_digit]
+        else
+          return "#{tens_multiples[tens_digit]} e #{ones[ones_digit]}"
+        end
+      elsif number == 100
+        return 'cem'
+      elsif number < 1000
+        hundreds_digit = number / 100
+        remainder = number % 100
+        if remainder.zero?
+          return hundreds[hundreds_digit]
+        else
+          return "#{hundreds[hundreds_digit]} e #{number_to_words(remainder)}"
+        end
+      elsif number < 1_000_000
+        # For years like 2024
+        thousands = number / 1000
+        remainder = number % 1000
+
+        result = []
+        
+        if thousands == 1
+          result << 'mil'
+        else
+          result << "#{number_to_words(thousands)} mil"
+        end
+
+        if remainder > 0
+          if remainder < 100
+            result << "e #{number_to_words(remainder)}"
+          else
+            result << number_to_words(remainder)
+          end
+        end
+
+        result.join(' ')
+      else
+        number.to_s
+      end
+    end
+
+    private_class_method :number_to_words
+  end
+end

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

@@ -0,0 +1,54 @@
+module BrazilianUtils
+  module EmailUtils
+    # Email validation pattern based on RFC 5322
+    # This pattern validates:
+    # - Email must not start with a dot
+    # - Local part (before @): alphanumeric, dots, underscores, percent, plus, minus
+    # - @ symbol required
+    # - Domain part: alphanumeric, dots, hyphens
+    # - Dot separator required
+    # - TLD: at least 2 alphabetic characters
+    EMAIL_PATTERN = /\A(?![.])[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\z/.freeze
+
+    # Checks if a string corresponds to a valid email address.
+    #
+    # This function validates email addresses following the specifications defined 
+    # by RFC 5322, which is the widely accepted standard for email address formats.
+    #
+    # @param email [String] The input string to be checked
+    #
+    # @return [Boolean] Returns true if email is a valid email address, false otherwise
+    #
+    # @example Valid emails
+    #   is_valid("brutils@brutils.com")       #=> true
+    #   is_valid("user.name@example.com")     #=> true
+    #   is_valid("user+tag@example.co.uk")    #=> true
+    #   is_valid("user_123@test-domain.com")  #=> true
+    #
+    # @example Invalid emails
+    #   is_valid("invalid-email@brutils")     #=> false (no TLD)
+    #   is_valid(".user@example.com")         #=> false (starts with dot)
+    #   is_valid("user@")                     #=> false (no domain)
+    #   is_valid("@example.com")              #=> false (no local part)
+    #   is_valid("user name@example.com")     #=> false (space not allowed)
+    #   is_valid(nil)                         #=> false (not a string)
+    #
+    # @note The validation rules generally follow RFC 5322 specifications:
+    #   - Local part cannot start with a dot
+    #   - Local part can contain: letters, numbers, dots, underscores, percent, plus, minus
+    #   - Must have @ symbol
+    #   - Domain can contain: letters, numbers, dots, hyphens
+    #   - Must have at least one dot in domain
+    #   - TLD must be at least 2 characters and only letters
+    def self.is_valid(email)
+      return false unless email.is_a?(String)
+
+      EMAIL_PATTERN.match?(email)
+    end
+
+    # Alias for is_valid to provide alternative naming convention
+    class << self
+      alias valid? is_valid
+    end
+  end
+end

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

@@ -0,0 +1,235 @@
+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',
+      '2070' => '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
+    #   #=> 64 (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