brazil-validator 0.1.0

data/lib/br_validator/pix.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "shared"
+require_relative "cpf"
+require_relative "cnpj"
+require_relative "email"
+require_relative "phone"
+
+module BrValidator
+  # Validates, normalizes, and formats PIX keys (CPF, CNPJ, e-mail, phone,
+  # or random key).
+  module Pix
+    module_function
+
+    # Identifies which kind of PIX key a value looks like.
+    KEY_TYPES = %i[cpf cnpj email phone evp].freeze
+
+    # Formats verified against Bacen's official DICT schema
+    # (github.com/bacen/pix-dict-api openapi.yaml) and the Manual de
+    # Padrões para Iniciação do Pix:
+    # - CPF/CNPJ keys are digits-only (^[0-9]{11}$ / ^[0-9]{14}$). The DICT
+    #   schema does not yet accept alphanumeric CNPJ as a key.
+    # - The EVP (random key) is a canonical, case-insensitive UUID
+    #   (8-4-4-4-12).
+    # - Phone keys use the international format "+55AANNNNNNNNN", where AA
+    #   is the DDD and NNNNNNNNN is a 9-digit mobile number -- Brazilian
+    #   Pix only registers Brazilian mobile numbers, so the country code is
+    #   fixed at 55.
+    # - Email keys are case-insensitive and capped at 77 characters.
+    EVP_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
+    CPF_SHAPE = /\A\d{11}\z/.freeze
+    CNPJ_SHAPE = /\A\d{14}\z/.freeze
+    PHONE_CHARS = /\A[\d\s()+-]+\z/.freeze
+    PHONE_KEY_FORM = /\A\+55\d{11}\z/.freeze
+    MAX_EMAIL_KEY_LENGTH = 77
+    private_constant :EVP_REGEX, :CPF_SHAPE, :CNPJ_SHAPE, :PHONE_CHARS, :PHONE_KEY_FORM,
+                      :MAX_EMAIL_KEY_LENGTH
+
+    # Detects which kind of PIX key value looks like, or nil if it matches
+    # none.
+    def key_type(value)
+      trimmed = value.strip
+
+      return :evp if trimmed.match?(EVP_REGEX)
+      return :email if trimmed.include?("@")
+      return :phone if trimmed.start_with?("+")
+      return :cpf if trimmed.match?(CPF_SHAPE)
+      return :cnpj if trimmed.match?(CNPJ_SHAPE)
+
+      nil
+    end
+
+    def normalize_phone_key(value)
+      "+#{Shared.remove_non_digits(value)}"
+    end
+    private_class_method :normalize_phone_key
+
+    def valid_phone_key?(value)
+      return false unless value.match?(PHONE_CHARS)
+
+      phone = normalize_phone_key(value)
+
+      return false unless phone.match?(PHONE_KEY_FORM)
+
+      ddd = phone[3...5]
+      subscriber_first_digit = phone[5]
+
+      Shared::VALID_DDDS.include?(ddd) && subscriber_first_digit == "9"
+    end
+    private_class_method :valid_phone_key?
+
+    def format_phone_key(value)
+      phone = normalize_phone_key(value)
+
+      return value unless phone.match?(PHONE_KEY_FORM)
+
+      "+55 #{Phone.format(phone[3..])}"
+    end
+    private_class_method :format_phone_key
+
+    # Returns true if value is a valid PIX key of any recognized type.
+    def is_valid?(value)
+      type = key_type(value)
+
+      return false if type.nil?
+
+      trimmed = value.strip
+
+      case type
+      when :cpf then Cpf.is_valid?(trimmed)
+      when :cnpj then Cnpj.is_valid?(trimmed)
+      when :email then trimmed.length <= MAX_EMAIL_KEY_LENGTH && Email.is_valid?(trimmed)
+      when :phone then valid_phone_key?(trimmed)
+      when :evp then true
+      end
+    end
+
+    # Dispatches to the canonical normalize rule of value's detected key
+    # type. If the type cannot be detected, value is returned unchanged.
+    def normalize(value)
+      type = key_type(value)
+
+      return value if type.nil?
+
+      trimmed = value.strip
+
+      case type
+      when :cpf then Cpf.normalize(trimmed)
+      when :cnpj then Cnpj.normalize(trimmed)
+      when :email then Email.normalize(trimmed)
+      when :phone then normalize_phone_key(trimmed)
+      when :evp then trimmed.downcase
+      end
+    end
+
+    # Dispatches to the canonical format rule of value's detected key
+    # type. If the type cannot be detected, value is returned unchanged.
+    def format(value)
+      type = key_type(value)
+
+      return value if type.nil?
+
+      trimmed = value.strip
+
+      case type
+      when :cpf then Cpf.format(trimmed)
+      when :cnpj then Cnpj.format(trimmed)
+      when :email then Email.format(trimmed)
+      when :phone then format_phone_key(trimmed)
+      when :evp then trimmed.downcase
+      end
+    end
+  end
+end

data/lib/br_validator/shared.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module BrValidator
+  # Small helpers reused by more than one validator.
+  #
+  # Not part of the public API of brazil-validator: this module holds
+  # implementation details shared across validators, not a stable contract.
+  module Shared
+    module_function
+
+    # Strips every character that is not 0-9.
+    def remove_non_digits(value)
+      value.gsub(/\D/, "")
+    end
+
+    # Anatel's Plano de Numeração Brasileiro: exactly 67 valid DDD (area)
+    # codes, not every two-digit value from 11-99.
+    VALID_DDDS = %w[
+      11 12 13 14 15 16 17 18 19
+      21 22 24
+      27 28
+      31 32 33 34 35 37 38
+      41 42 43 44 45 46 47 48 49
+      51 53 54 55
+      61 62 63 64 65 66 67 68 69
+      71 73 74 75 77 79
+      81 82 83 84 85 86 87 88 89
+      91 92 93 94 95 96 97 98 99
+    ].freeze
+  end
+end

data/lib/br_validator/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BrValidator
+  VERSION = "0.1.0"
+end

data/lib/br_validator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "br_validator/version"
+require_relative "br_validator/cpf"
+require_relative "br_validator/cnpj"
+require_relative "br_validator/cep"
+require_relative "br_validator/phone"
+require_relative "br_validator/email"
+require_relative "br_validator/pix"
+require_relative "br_validator/ie"
+
+module BrValidator
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: brazil-validator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matheus
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-09-13 00:00:00.000000000 Z
+dependencies: []
+description: CPF, CNPJ, CEP, phone numbers, e-mail, PIX keys, and Inscrição Estadual
+  validators for Ruby.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/br_validator.rb
+- lib/br_validator/cep.rb
+- lib/br_validator/cnpj.rb
+- lib/br_validator/cpf.rb
+- lib/br_validator/email.rb
+- lib/br_validator/ie.rb
+- lib/br_validator/ie/ac.rb
+- lib/br_validator/ie/al.rb
+- lib/br_validator/ie/am.rb
+- lib/br_validator/ie/ap.rb
+- lib/br_validator/ie/ba.rb
+- lib/br_validator/ie/ce.rb
+- lib/br_validator/ie/df.rb
+- lib/br_validator/ie/es.rb
+- lib/br_validator/ie/go.rb
+- lib/br_validator/ie/ma.rb
+- lib/br_validator/ie/mg.rb
+- lib/br_validator/ie/mod11.rb
+- lib/br_validator/ie/ms.rb
+- lib/br_validator/ie/mt.rb
+- lib/br_validator/ie/pa.rb
+- lib/br_validator/ie/pb.rb
+- lib/br_validator/ie/pe.rb
+- lib/br_validator/ie/pi.rb
+- lib/br_validator/ie/pr.rb
+- lib/br_validator/ie/rj.rb
+- lib/br_validator/ie/rn.rb
+- lib/br_validator/ie/ro.rb
+- lib/br_validator/ie/rr.rb
+- lib/br_validator/ie/rs.rb
+- lib/br_validator/ie/sc.rb
+- lib/br_validator/ie/se.rb
+- lib/br_validator/ie/sp.rb
+- lib/br_validator/ie/to.rb
+- lib/br_validator/phone.rb
+- lib/br_validator/pix.rb
+- lib/br_validator/shared.rb
+- lib/br_validator/version.rb
+homepage: https://github.com/matheuslm7/brazil-validator
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/matheuslm7/brazil-validator
+  source_code_uri: https://github.com/matheuslm7/brazil-validator/tree/master/ruby
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key: 
+specification_version: 4
+summary: Validation, normalization, and formatting for Brazilian data.
+test_files: []