br-utils 0.1.0

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

@@ -0,0 +1,272 @@
+module BrazilianUtils
+  # Utilities for formatting, validating, and generating Brazilian phone numbers.
+  #
+  # Brazilian phone numbers come in two types:
+  # - Mobile (Celular): 11 digits - DDD (2 digits) + 9 + 8 digits, e.g., "11994029275"
+  # - Landline (Fixo): 10 digits - DDD (2 digits) + [2-5] + 7 digits, e.g., "1635014415"
+  #
+  # DDD (Discagem Direta à Distância) is the area code, ranging from 11 to 99.
+  # Mobile numbers always have 9 as the 3rd digit (after DDD).
+  # Landline numbers have 2, 3, 4, or 5 as the 3rd digit (after DDD).
+  module PhoneUtils
+    # Pattern for mobile phone numbers (11 digits: DDD + 9 + 8 digits)
+    MOBILE_PATTERN = /^[1-9][1-9][9]\d{8}$/.freeze
+    
+    # Pattern for landline phone numbers (10 digits: DDD + [2-5] + 7 digits)
+    LANDLINE_PATTERN = /^[1-9][1-9][2-5]\d{7}$/.freeze
+
+    # Pattern for international dialing code (+55 or 55)
+    INTERNATIONAL_CODE_PATTERN = /\+?55/.freeze
+
+    # Formats a Brazilian phone number into the standard pattern.
+    #
+    # Formats as (DD)NNNNN-NNNN for both mobile and landline numbers.
+    #
+    # @param phone [String] A string representing the phone number (digits only)
+    #
+    # @return [String, nil] The formatted phone number or nil if invalid
+    #
+    # @example
+    #   format_phone("11994029275")
+    #   #=> "(11)99402-9275"
+    #
+    #   format_phone("1635014415")
+    #   #=> "(16)3501-4415"
+    #
+    #   format_phone("333333")
+    #   #=> nil
+    def self.format_phone(phone)
+      return nil unless is_valid(phone)
+
+      ddd = phone[0..1]
+      phone_number = phone[2..-1]
+
+      "(#{ddd})#{phone_number[0..-5]}-#{phone_number[-4..-1]}"
+    end
+
+    # Alias for format_phone
+    class << self
+      alias format format_phone
+    end
+
+    # Returns if a Brazilian phone number is valid.
+    #
+    # It does not verify if the number actually exists.
+    #
+    # @param phone_number [String] The phone number to validate (digits only, no country code)
+    # @param type [Symbol, String, nil] :mobile, :landline, "mobile", or "landline".
+    #   If not specified, checks for either type.
+    #
+    # @return [Boolean] True if the phone number is valid, false otherwise
+    #
+    # @example
+    #   is_valid("11994029275")
+    #   #=> true (mobile)
+    #
+    #   is_valid("1635014415")
+    #   #=> true (landline)
+    #
+    #   is_valid("11994029275", :mobile)
+    #   #=> true
+    #
+    #   is_valid("1635014415", :mobile)
+    #   #=> false
+    #
+    #   is_valid("1635014415", :landline)
+    #   #=> true
+    #
+    #   is_valid("123456")
+    #   #=> false
+    def self.is_valid(phone_number, type = nil)
+      return false unless phone_number.is_a?(String)
+
+      type_str = type.to_s if type
+
+      case type_str
+      when 'mobile'
+        valid_mobile?(phone_number)
+      when 'landline'
+        valid_landline?(phone_number)
+      else
+        valid_mobile?(phone_number) || valid_landline?(phone_number)
+      end
+    end
+
+    # Alias for is_valid
+    class << self
+      alias valid? is_valid
+    end
+
+    # Removes common symbols from a Brazilian phone number string.
+    #
+    # Removes: (, ), -, +, and spaces
+    #
+    # @param phone_number [String] The phone number to remove symbols from
+    #
+    # @return [String] A new string with the specified symbols removed
+    #
+    # @example
+    #   remove_symbols_phone("(11)99402-9275")
+    #   #=> "11994029275"
+    #
+    #   remove_symbols_phone("+55 11 99402-9275")
+    #   #=> "5511994029275"
+    #
+    #   remove_symbols_phone("(16) 3501-4415")
+    #   #=> "1635014415"
+    def self.remove_symbols_phone(phone_number)
+      return '' unless phone_number.is_a?(String)
+
+      phone_number.gsub(/[\(\)\-\+\s]/, '')
+    end
+
+    # Alias for remove_symbols_phone
+    class << self
+      alias remove_symbols remove_symbols_phone
+      alias sieve remove_symbols_phone
+    end
+
+    # Generates a valid and random phone number.
+    #
+    # @param type [Symbol, String, nil] :mobile, :landline, "mobile", or "landline".
+    #   If not specified, generates either type randomly.
+    #
+    # @return [String] A randomly generated valid phone number
+    #
+    # @example
+    #   generate
+    #   #=> "2234451215" (random type)
+    #
+    #   generate(:mobile)
+    #   #=> "11999115895"
+    #
+    #   generate(:landline)
+    #   #=> "1635317900"
+    #
+    #   generate("mobile")
+    #   #=> "21987654321"
+    def self.generate(type = nil)
+      type_str = type.to_s if type
+
+      case type_str
+      when 'mobile'
+        generate_mobile_phone
+      when 'landline'
+        generate_landline_phone
+      else
+        [method(:generate_mobile_phone), method(:generate_landline_phone)].sample.call
+      end
+    end
+
+    # Removes the international dialing code (+55 or 55) from a phone number.
+    #
+    # Only removes the code if the resulting number has more than 11 digits.
+    #
+    # @param phone_number [String] The phone number with or without international code
+    #
+    # @return [String] The phone number without international code, or the same number if no code present
+    #
+    # @example
+    #   remove_international_dialing_code("5511994029275")
+    #   #=> "11994029275"
+    #
+    #   remove_international_dialing_code("+5511994029275")
+    #   #=> "11994029275"
+    #
+    #   remove_international_dialing_code("1635014415")
+    #   #=> "1635014415" (no international code)
+    #
+    #   remove_international_dialing_code("+55 11 99402-9275")
+    #   #=> "+55 11 99402-9275" (has spaces, length check fails)
+    def self.remove_international_dialing_code(phone_number)
+      return '' unless phone_number.is_a?(String)
+
+      # Check if pattern matches and length (without spaces) is > 11
+      if INTERNATIONAL_CODE_PATTERN.match?(phone_number) && phone_number.gsub(' ', '').length > 11
+        phone_number.sub('55', '')
+      else
+        phone_number
+      end
+    end
+
+    # Returns if a Brazilian mobile number is valid.
+    #
+    # Mobile pattern: DDD (2 digits 1-9) + 9 + 8 digits (total 11 digits)
+    #
+    # @param phone_number [String] The mobile number to validate
+    #
+    # @return [Boolean] True if valid mobile, false otherwise
+    #
+    # @private
+    def self.valid_mobile?(phone_number)
+      return false unless phone_number.is_a?(String)
+
+      MOBILE_PATTERN.match?(phone_number.strip)
+    end
+
+    private_class_method :valid_mobile?
+
+    # Returns if a Brazilian landline number is valid.
+    #
+    # Landline pattern: DDD (2 digits 1-9) + [2-5] + 7 digits (total 10 digits)
+    #
+    # @param phone_number [String] The landline number to validate
+    #
+    # @return [Boolean] True if valid landline, false otherwise
+    #
+    # @private
+    def self.valid_landline?(phone_number)
+      return false unless phone_number.is_a?(String)
+
+      LANDLINE_PATTERN.match?(phone_number.strip)
+    end
+
+    private_class_method :valid_landline?
+
+    # Generates a valid DDD (area code) number.
+    #
+    # DDD consists of 2 digits, both ranging from 1-9.
+    #
+    # @return [String] A 2-digit DDD number
+    #
+    # @private
+    def self.generate_ddd_number
+      2.times.map { rand(1..9) }.join
+    end
+
+    private_class_method :generate_ddd_number
+
+    # Generates a valid and random mobile phone number.
+    #
+    # Format: DDD + 9 + 8 random digits (total 11 digits)
+    #
+    # @return [String] A valid mobile phone number
+    #
+    # @private
+    def self.generate_mobile_phone
+      ddd = generate_ddd_number
+      client_number = 8.times.map { rand(0..9) }.join
+
+      "#{ddd}9#{client_number}"
+    end
+
+    private_class_method :generate_mobile_phone
+
+    # Generates a valid and random landline phone number.
+    #
+    # Format: DDD + [2-5] + 7 random digits (total 10 digits)
+    #
+    # @return [String] A valid landline phone number
+    #
+    # @private
+    def self.generate_landline_phone
+      ddd = generate_ddd_number
+      first_digit = rand(2..5)
+      remaining_digits = rand(0..9999999).to_s.rjust(7, '0')
+
+      "#{ddd}#{first_digit}#{remaining_digits}"
+    end
+
+    private_class_method :generate_landline_phone
+  end
+end

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

@@ -0,0 +1,151 @@
+module BrazilianUtils
+  # Utilities for formatting, validating, and generating Brazilian PIS numbers.
+  #
+  # PIS (Programa de Integração Social) is an 11-digit identification number
+  # for Brazilian workers, similar to a social security number.
+  #
+  # Format: XXX.XXXXX.XX-X (e.g., "123.45678.90-9")
+  module PISUtils
+    # Weights used for checksum calculation
+    WEIGHTS = [3, 2, 9, 8, 7, 6, 5, 4, 3, 2].freeze
+
+    # Removes formatting symbols from a PIS string.
+    #
+    # This function takes a PIS string with formatting symbols (dots and hyphens)
+    # and returns a cleaned version with only digits.
+    #
+    # @param pis [String] A PIS string that may contain formatting symbols
+    #
+    # @return [String] A cleaned PIS string with no formatting symbols
+    #
+    # @example
+    #   remove_symbols("123.45678.90-9")
+    #   #=> "12345678909"
+    #
+    #   remove_symbols("987.65432.10-0")
+    #   #=> "98765432100"
+    #
+    #   remove_symbols("12345678909")
+    #   #=> "12345678909"
+    def self.remove_symbols(pis)
+      return '' unless pis.is_a?(String)
+      
+      pis.gsub(/[.\-]/, '')
+    end
+
+    # Alias for remove_symbols
+    class << self
+      alias sieve remove_symbols
+    end
+
+    # Formats a valid PIS string with standard visual aid symbols.
+    #
+    # This function takes a valid numbers-only PIS string as input
+    # and adds standard formatting visual aid symbols for display.
+    #
+    # Format: XXX.XXXXX.XX-X
+    #
+    # @param pis [String] A valid numbers-only PIS string (11 digits)
+    #
+    # @return [String, nil] A formatted PIS string or nil if invalid
+    #
+    # @example
+    #   format_pis("12345678909")
+    #   #=> "123.45678.90-9"
+    #
+    #   format_pis("98765432100")
+    #   #=> "987.65432.10-0"
+    #
+    #   format_pis("123456789")
+    #   #=> nil (invalid)
+    def self.format_pis(pis)
+      return nil unless is_valid(pis)
+
+      "#{pis[0..2]}.#{pis[3..7]}.#{pis[8..9]}-#{pis[10]}"
+    end
+
+    # Alias for format_pis
+    class << self
+      alias format format_pis
+    end
+
+    # Returns whether the verifying checksum digit of the given PIS matches its base number.
+    #
+    # This function validates that:
+    # - The input is a string
+    # - The length is exactly 11 digits
+    # - All characters are digits
+    # - The checksum digit (last digit) is correct
+    #
+    # @param pis [String] PIS number as a string (11 digits)
+    #
+    # @return [Boolean] True if PIS is valid, false otherwise
+    #
+    # @example
+    #   is_valid("12345678909")
+    #   #=> true
+    #
+    #   is_valid("123.45678.90-9")
+    #   #=> false (contains symbols, use remove_symbols first)
+    #
+    #   is_valid("12345678900")
+    #   #=> false (invalid checksum)
+    #
+    #   is_valid("123456789")
+    #   #=> false (wrong length)
+    def self.is_valid(pis)
+      return false unless pis.is_a?(String)
+      return false unless pis.length == 11
+      return false unless pis.match?(/^\d+$/)
+      
+      pis[-1] == checksum(pis[0..9]).to_s
+    end
+
+    # Alias for is_valid
+    class << self
+      alias valid? is_valid
+    end
+
+    # Generates a random valid Brazilian PIS number.
+    #
+    # This function generates a random PIS number with the following characteristics:
+    # - It has 11 digits
+    # - It passes the weight calculation check
+    #
+    # @return [String] A randomly generated valid PIS number as a string
+    #
+    # @example
+    #   generate
+    #   #=> "12345678909" (example, actual value is random)
+    #
+    #   generate
+    #   #=> "98765432100" (example)
+    def self.generate
+      base = rand(0..9_999_999_999).to_s.rjust(10, '0')
+      base + checksum(base).to_s
+    end
+
+    # Calculates the checksum digit of the given base PIS string.
+    #
+    # The checksum algorithm:
+    # 1. Multiply each of the first 10 digits by corresponding weight
+    # 2. Sum all products
+    # 3. Calculate: 11 - (sum % 11)
+    # 4. If result is 10 or 11, use 0 instead
+    #
+    # @param base_pis [String] The first 10 digits of a PIS number
+    #
+    # @return [Integer] The checksum digit (0-9)
+    #
+    # @private
+    def self.checksum(base_pis)
+      pis_digits = base_pis.chars.map(&:to_i)
+      pis_sum = pis_digits.zip(WEIGHTS).sum { |digit, weight| digit * weight }
+      check_digit = 11 - (pis_sum % 11)
+
+      [10, 11].include?(check_digit) ? 0 : check_digit
+    end
+
+    private_class_method :checksum
+  end
+end

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

@@ -0,0 +1,113 @@
+module BrazilianUtils
+  # Utilities for validating Brazilian RENAVAM numbers.
+  #
+  # RENAVAM (Registro Nacional de Veículos Automotores) is an 11-digit
+  # identification number for motor vehicles in Brazil.
+  #
+  # The last digit is a verification digit calculated from the first 10 digits.
+  module RENAVAMUtils
+    # Weights used for verification digit calculation
+    # Applied to the first 10 digits in reverse order
+    DV_WEIGHTS = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3].freeze
+
+    # Validates the Brazilian vehicle registration number (RENAVAM).
+    #
+    # This function takes a RENAVAM string and checks if it is valid.
+    # A valid RENAVAM consists of exactly 11 digits, with the last digit as
+    # a verification digit calculated from the previous 10 digits.
+    #
+    # @param renavam [String] The RENAVAM string to be validated
+    #
+    # @return [Boolean] True if the RENAVAM is valid, false otherwise
+    #
+    # @example
+    #   is_valid_renavam("86769597308")
+    #   #=> true
+    #
+    #   is_valid_renavam("12345678901")
+    #   #=> false
+    #
+    #   is_valid_renavam("1234567890a")
+    #   #=> false (contains letter)
+    #
+    #   is_valid_renavam("12345678 901")
+    #   #=> false (contains space)
+    #
+    #   is_valid_renavam("12345678")
+    #   #=> false (wrong length)
+    #
+    #   is_valid_renavam("")
+    #   #=> false
+    def self.is_valid_renavam(renavam)
+      return false unless validate_renavam_format(renavam)
+
+      calculate_renavam_dv(renavam) == renavam[-1].to_i
+    end
+
+    # Alias for is_valid_renavam
+    class << self
+      alias is_valid is_valid_renavam
+      alias valid? is_valid_renavam
+    end
+
+    # Validates the format of a RENAVAM string.
+    #
+    # Checks:
+    # - Must be a string
+    # - Must be exactly 11 digits
+    # - Cannot be all the same digit (e.g., "11111111111")
+    #
+    # @param renavam [String] The RENAVAM string to validate
+    #
+    # @return [Boolean] True if format is valid, false otherwise
+    #
+    # @private
+    def self.validate_renavam_format(renavam)
+      return false unless renavam.is_a?(String)
+      return false unless renavam.length == 11
+      return false unless renavam.match?(/^\d+$/)
+      return false if renavam.chars.uniq.length == 1  # All same digit
+
+      true
+    end
+
+    private_class_method :validate_renavam_format
+
+    # Sums the weighted digits of a RENAVAM.
+    #
+    # Takes the first 10 digits, reverses them, multiplies each by the
+    # corresponding weight, and returns the sum.
+    #
+    # @param renavam [String] The RENAVAM string
+    #
+    # @return [Integer] The sum of weighted digits
+    #
+    # @private
+    def self.sum_weighted_digits(renavam)
+      base_digits = renavam[0..9].reverse.chars.map(&:to_i)
+      base_digits.zip(DV_WEIGHTS).sum { |digit, weight| digit * weight }
+    end
+
+    private_class_method :sum_weighted_digits
+
+    # Calculates the verification digit for a RENAVAM.
+    #
+    # Algorithm:
+    # 1. Sum the weighted digits (first 10 digits reversed, multiplied by weights)
+    # 2. Calculate: 11 - (sum % 11)
+    # 3. If result >= 10, return 0, otherwise return the result
+    #
+    # @param renavam [String] The RENAVAM string
+    #
+    # @return [Integer] The verification digit (0-9)
+    #
+    # @private
+    def self.calculate_renavam_dv(renavam)
+      weighted_sum = sum_weighted_digits(renavam)
+      dv = 11 - (weighted_sum % 11)
+      dv >= 10 ? 0 : dv
+    end
+
+    private_class_method :calculate_renavam_dv
+  end
+end

data/lib/brazilian-utils/voter-id-utils.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module BrazilianUtils
+  module VoterIdUtils
+    # UF codes mapping to federative union numbers
+    UF_CODES = {
+      'SP' => '01', 'MG' => '02', 'RJ' => '03', 'RS' => '04',
+      'BA' => '05', 'PR' => '06', 'CE' => '07', 'PE' => '08',
+      'SC' => '09', 'GO' => '10', 'MA' => '11', 'PB' => '12',
+      'PA' => '13', 'ES' => '14', 'PI' => '15', 'RN' => '16',
+      'AL' => '17', 'MT' => '18', 'MS' => '19', 'DF' => '20',
+      'SE' => '21', 'AM' => '22', 'RO' => '23', 'AC' => '24',
+      'AP' => '25', 'RR' => '26', 'TO' => '27', 'ZZ' => '28'
+    }.freeze
+
+    module_function
+
+    # Check if a Brazilian voter ID number is valid.
+    #
+    # @param voter_id [String] The voter ID to validate
+    # @return [Boolean] true if valid, false otherwise
+    def is_valid_voter_id(voter_id)
+      # Ensure voter_id is a string with only digits and valid length
+      return false unless voter_id.is_a?(String)
+      return false unless voter_id.match?(/^\d+$/)
+      return false unless is_length_valid?(voter_id)
+
+      # Extract parts (using negative indexing for federative union and verifying digits)
+      sequential_number = get_sequential_number(voter_id)
+      federative_union = get_federative_union(voter_id)
+      verifying_digits = get_verifying_digits(voter_id)
+
+      # Validate federative union
+      return false unless is_federative_union_valid?(federative_union)
+
+      # Validate first verifying digit
+      vd1 = calculate_vd1(sequential_number, federative_union)
+      return false if vd1 != verifying_digits[0].to_i
+
+      # Validate second verifying digit
+      vd2 = calculate_vd2(federative_union, vd1)
+      return false if vd2 != verifying_digits[1].to_i
+
+      true
+    end
+
+    # Alias for is_valid_voter_id
+    alias valid_voter_id? is_valid_voter_id
+
+    # Format a voter ID for display with visual spaces.
+    #
+    # @param voter_id [String] The voter ID to format
+    # @return [String, nil] Formatted voter ID or nil if invalid
+    def format_voter_id(voter_id)
+      return nil unless is_valid_voter_id(voter_id)
+
+      "#{voter_id[0..3]} #{voter_id[4..7]} #{voter_id[8..9]} #{voter_id[10..11]}"
+    end
+
+    # Alias for format_voter_id
+    alias format format_voter_id
+
+    # Generate a random valid Brazilian voter ID.
+    #
+    # @param federative_union [String] The UF code (e.g., "SP", "MG", "ZZ")
+    # @return [String, nil] A valid voter ID or nil if UF is invalid
+    def generate(federative_union = 'ZZ')
+      federative_union = federative_union.upcase
+      return nil unless UF_CODES.key?(federative_union)
+
+      uf_number = UF_CODES[federative_union]
+      return nil unless is_federative_union_valid?(uf_number)
+
+      # Generate random 8-digit sequential number
+      sequential_number = format('%08d', rand(0..99_999_999))
+
+      # Calculate verification digits
+      vd1 = calculate_vd1(sequential_number, uf_number)
+      vd2 = calculate_vd2(uf_number, vd1)
+
+      "#{sequential_number}#{uf_number}#{vd1}#{vd2}"
+    end
+
+    private
+
+    # Check if the length of the voter ID is valid.
+    # Typically 12 digits, but can be 13 for SP and MG (edge case).
+    def is_length_valid?(voter_id)
+      return true if voter_id.length == 12
+
+      # Edge case: SP and MG can have 13 digits
+      federative_union = get_federative_union(voter_id)
+      voter_id.length == 13 && ['01', '02'].include?(federative_union)
+    end
+
+    # Extract the sequential number (first 8 digits).
+    def get_sequential_number(voter_id)
+      voter_id[0..7]
+    end
+
+    # Extract the federative union (2 digits before last 2 digits).
+    def get_federative_union(voter_id)
+      voter_id[-4..-3]
+    end
+
+    # Extract the verifying digits (last 2 digits).
+    def get_verifying_digits(voter_id)
+      voter_id[-2..-1]
+    end
+
+    # Check if the federative union is valid (between '01' and '28').
+    def is_federative_union_valid?(federative_union)
+      num = federative_union.to_i
+      num >= 1 && num <= 28
+    end
+
+    # Calculate the first verifying digit.
+    #
+    # @param sequential_number [String] First 8 digits
+    # @param federative_union [String] 2-digit UF code
+    # @return [Integer] The first verification digit
+    def calculate_vd1(sequential_number, federative_union)
+      # Weights: 2, 3, 4, 5, 6, 7, 8, 9
+      weights = (2..9).to_a
+
+      sum = sequential_number.chars.each_with_index.sum do |digit, index|
+        digit.to_i * weights[index]
+      end
+
+      rest = sum % 11
+      vd1 = rest
+
+      # Edge case: rest == 0 and federative_union is SP ('01') or MG ('02')
+      vd1 = 1 if rest == 0 && ['01', '02'].include?(federative_union)
+
+      # Edge case: rest == 10
+      vd1 = 0 if rest == 10
+
+      vd1
+    end
+
+    # Calculate the second verifying digit.
+    #
+    # @param federative_union [String] 2-digit UF code
+    # @param vd1 [Integer] First verification digit
+    # @return [Integer] The second verification digit
+    def calculate_vd2(federative_union, vd1)
+      # Weights: 7, 8, 9
+      sum = (federative_union[0].to_i * 7) +
+            (federative_union[1].to_i * 8) +
+            (vd1 * 9)
+
+      rest = sum % 11
+      vd2 = rest
+
+      # Edge case: rest == 0 and federative_union is SP ('01') or MG ('02')
+      vd2 = 1 if rest == 0 && ['01', '02'].include?(federative_union)
+
+      # Edge case: rest == 10
+      vd2 = 0 if rest == 10
+
+      vd2
+    end
+  end
+end