br_validators 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2a8eb5df36f0aae424cad2f9f7be8d3ca4b319d144b58023af72d61a94a597bc
+  data.tar.gz: 6cbba05d5a095be1b04d0d9b0e5aa63116fca27cd0b2eb2902fc7a66a844a7b7
+SHA512:
+  metadata.gz: aa4a7ece5360498679b28eeef9b8dea03c73e24c2742bc7f6a669a2e97f8a5453bf0ee313dec7f5804f8ca3c34d4e7c57a24b56710ab1e23f583c5c0c90b11d0
+  data.tar.gz: f97f6579ff6a8333b86bff8da5eb6d279defa9aca7641b1eedc51e794b9884092d245ecacaaa45f68719d925246e7242e827daa8957e28886af5b262745a0642

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+As mudanças de cada versão ficam aqui. O projeto segue o
+[versionamento semântico](https://semver.org/lang/pt-BR/).
+
+## [Não lançado]
+
+- Página para testar os validadores no navegador (https://br-validators-gem.vercel.app).
+
+## [0.1.0] - 2026-10-25
+
+- `BrValidators::CPF` com `valid?`, `format` e `strip`.
+- `BrValidators::CNPJ` para o formato numérico e o alfanumérico da Receita Federal.
+- `BrValidators::CNS` com as rotinas de validação do Ministério da Saúde.
+- `BrValidators::Pix` com `valid?` e `type`, seguindo a especificação do DICT.
+- `BrValidators::Boleto` para a linha digitável de cobrança (47 dígitos) e de arrecadação (48 dígitos).
+- Validadores para ActiveModel (`validates :cpf, cpf: true` e afins) com mensagens em pt-BR e en.
+- Publicação automática no RubyGems ao criar uma tag.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Pedrassolli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# br_validators
+
+Gem Ruby para validar e formatar documentos brasileiros, sem dependências.
+
+## Instalação
+
+No `Gemfile`:
+
+```ruby
+gem "br_validators"
+```
+
+> A versão 0.1.0 está pronta e vai ser publicada no RubyGems em breve. Até lá, use direto
+> do GitHub: `gem "br_validators", github: "PedroPedrassolli/br_validators"`.
+
+## O que tem
+
+| Documento | Observação |
+| --- | --- |
+| CPF | |
+| CNPJ | numérico e alfanumérico (o formato novo da Receita Federal, a partir de julho de 2026) |
+| CNS | Cartão Nacional de Saúde |
+| Chave Pix | CPF, CNPJ, e-mail, celular e chave aleatória |
+| Boleto | linha digitável de cobrança e de arrecadação |
+
+Cada documento tem os mesmos três métodos:
+
+```ruby
+BrValidators::CPF.valid?("123.456.789-09") # => true
+BrValidators::CPF.format("12345678909")    # => "123.456.789-09"
+BrValidators::CPF.strip("123.456.789-09")  # => "12345678909"
+
+BrValidators::CNPJ.valid?("12.ABC.345/01DE-35") # => true (CNPJ alfanumérico)
+BrValidators::CNPJ.format("12abc34501de35")     # => "12.ABC.345/01DE-35"
+
+BrValidators::CNS.format("898000000000436")      # => "898 0000 0000 0436"
+```
+
+A chave Pix é um caso à parte: em vez de `format` e `strip`, ela tem `type`, que diz
+o tipo da chave. Ela precisa estar como o Banco Central guarda (sem máscara, e-mail e
+chave aleatória em minúsculas):
+
+```ruby
+BrValidators::Pix.type("+5511987654321")             # => :phone
+BrValidators::Pix.type("maria.souza@exemplo.com.br") # => :email
+BrValidators::Pix.valid?("123.456.789-09")           # => false (chave de CPF não tem máscara)
+```
+
+O boleto aceita a linha digitável de cobrança (bancos) e de arrecadação (contas de
+consumo e tributos) e também tem `type`:
+
+```ruby
+BrValidators::Boleto.type("00190.00009 02345.678904 12345.678176 1 10000000012345") # => :cobranca
+BrValidators::Boleto.valid?("826700000019000000000000000000000000000000000000")      # => true
+```
+
+## Rails e ActiveModel
+
+Em projetos com ActiveModel (todo app Rails tem), os validadores entram sozinhos:
+
+```ruby
+class Cliente < ApplicationRecord
+  validates :cpf, cpf: true
+  validates :cnpj, cnpj: true, allow_blank: true
+  validates :cartao_sus, cns: true
+  validates :chave_pix, pix: { message: "não parece uma chave Pix" }
+  validates :linha_digitavel, boleto: true
+end
+```
+
+As mensagens de erro vêm em português (`pt-BR`) e inglês (`en`). Para trocar o texto,
+sobrescreva as chaves `errors.messages.cpf_invalid`, `cnpj_invalid`, `cns_invalid`,
+`pix_invalid` e `boleto_invalid` no seu arquivo de tradução.
+
+Os validadores se chamam `CpfValidator`, `CnpjValidator`, `CnsValidator`, `PixValidator` e
+`BoletoValidator`, no nível de cima, porque é assim que o Rails encontra `cpf: true`.
+
+Já existem boas gems para CPF e CNPJ. A ideia aqui é juntar num lugar só os documentos
+que costumam aparecer em sistemas brasileiros (inclusive CNS, Pix e boleto), com
+mensagens de erro em português e inglês.
+
+## Página de teste
+
+Dá para testar cada validador no navegador em https://br-validators-gem.vercel.app. A página
+(`public/`) é HTML e JavaScript puro e chama uma função Ruby da Vercel
+(`api/validar.rb`) que usa a própria gem, então as regras ficam num lugar só:
+
+```
+GET /api/validar?documento=cnpj&valor=12.ABC.345/01DE-35
+{"documento":"cnpj","valido":true,"formatado":"12.ABC.345/01DE-35","tipo":null}
+```
+
+## Desenvolvimento
+
+Precisa de Ruby 3.3 ou mais novo.
+
+```sh
+bundle install
+bundle exec rake test   # testes (a cobertura mínima é 100% das linhas)
+bundle exec rubocop     # estilo
+node --test "test/js/*.test.mjs"   # testes da página de teste
+```
+
+O passo a passo para contribuir está no [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Licença
+
+[MIT](LICENSE)

data/lib/br_validators/active_model.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+# Validação nos models do Rails (ou de qualquer classe com ActiveModel):
+#
+#   validates :cpf, cpf: true
+#   validates :cnpj, cnpj: true, allow_blank: true
+#   validates :chave_pix, pix: { message: "não parece uma chave Pix" }
+#
+# O Rails procura a classe pelo nome da opção ("cpf: true" vira CpfValidator),
+# por isso os validadores ficam no nível de cima, fora do módulo BrValidators.
+# As mensagens de erro estão em lib/br_validators/locale (pt-BR e en).
+I18n.load_path += Dir[File.expand_path("locale/*.yml", __dir__)]
+
+module BrValidators
+  # Base comum: cada validador só diz qual módulo usa e qual mensagem mostra.
+  # allow_nil e allow_blank já são tratados pelo próprio ActiveModel.
+  class DocumentValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, value)
+      return if self.class::DOCUMENT.valid?(value)
+
+      record.errors.add(attribute, options[:message] || self.class::ERROR)
+    end
+  end
+end
+
+# Um arquivo por validador (o Rails espera uma classe por arquivo).
+require_relative "validators/cpf_validator"
+require_relative "validators/cnpj_validator"
+require_relative "validators/cns_validator"
+require_relative "validators/pix_validator"
+require_relative "validators/boleto_validator"

data/lib/br_validators/boleto.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # Linha digitável de boleto. Aceita os dois tipos:
+  #
+  # Cobrança (bancos), 47 dígitos em 5 campos:
+  #   AAABC.CCCCX DDDDD.DDDDDY EEEEE.EEEEEZ K UUUUVVVVVVVVVV
+  #   - campos 1, 2 e 3 terminam com um dígito verificador de módulo 10;
+  #   - K é o dígito verificador geral do código de barras (módulo 11);
+  #   - UUUU é o fator de vencimento e V o valor.
+  #   Fonte: especificação de boleto do Banco do Brasil, que segue o padrão FEBRABAN.
+  #   https://www.bb.com.br/docs/pub/emp/empl/dwn/Doc5175Bloqueto.pdf
+  #
+  # Arrecadação (contas de consumo, tributos), 48 dígitos, sempre começa com 8:
+  #   4 blocos de 11 dígitos, cada um seguido do seu dígito verificador.
+  #   O 3º dígito diz o módulo: 6 ou 7 usam módulo 10; 8 ou 9 usam módulo 11.
+  #   O 4º dígito é o verificador geral do código de barras.
+  #   Fonte: "Layout padrão de arrecadação" da FEBRABAN, versão 7 (2023). O manual
+  #   diz que o dígito de cada bloco usa o mesmo módulo do verificador geral.
+  #   https://cmsarquivos.febraban.org.br/Arquivos/documentos/PDF/Layout%20-%20C%C3%B3digo%20de%20Barras%20-%20Vers%C3%A3o%207%20-%2001_03_2023_mn.pdf
+  module Boleto
+    # Pontos, espaços e hífens que aparecem na linha impressa.
+    MASK = /[.\-\s]/
+
+    def self.strip(value)
+      value.to_s.gsub(MASK, "")
+    end
+
+    # :cobranca, :arrecadacao ou nil se a linha for inválida.
+    def self.type(value)
+      line = strip(value)
+      return :cobranca if line.match?(/\A\d{47}\z/) && valid_cobranca?(line)
+      return :arrecadacao if line.match?(/\A8\d{47}\z/) && valid_arrecadacao?(line)
+
+      nil
+    end
+
+    def self.valid?(value)
+      !type(value).nil?
+    end
+
+    # Devolve a linha com a máscara de cada tipo, ou nil se for inválida:
+    #   cobrança:    "00190.00009 02345.678904 12345.678176 1 10000000012345"
+    #   arrecadação: "82670000001-9 00000000000-0 00000000000-0 00000000000-0"
+    def self.format(value)
+      line = strip(value)
+      case type(line)
+      when :cobranca then format_cobranca(line)
+      when :arrecadacao then line.scan(/\d{12}/).map { |block| "#{block[0, 11]}-#{block[11]}" }.join(" ")
+      end
+    end
+
+    def self.format_cobranca(line)
+      "#{line[0, 5]}.#{line[5, 5]} #{line[10, 5]}.#{line[15, 6]} " \
+        "#{line[21, 5]}.#{line[26, 6]} #{line[32]} #{line[33, 14]}"
+    end
+
+    def self.valid_cobranca?(line)
+      fields = [line[0, 10], line[10, 11], line[21, 11]]
+      return false unless fields.all? { |field| check_digit_ok?(field, method(:mod10)) }
+
+      barcode = cobranca_barcode(line)
+      barcode[4] == mod11_cobranca(without(barcode, 4)).to_s
+    end
+
+    # Remonta o código de barras (44 dígitos) a partir da linha digitável:
+    # banco e moeda, DV geral, fator e valor, e o "campo livre" dos campos 1 a 3.
+    def self.cobranca_barcode(line)
+      line[0, 4] + line[32] + line[33, 14] + line[4, 5] + line[10, 10] + line[21, 10]
+    end
+
+    def self.valid_arrecadacao?(line)
+      check = arrecadacao_check(line[2])
+      return false unless check
+
+      blocks = line.scan(/\d{12}/)
+      return false unless blocks.all? { |block| check_digit_ok?(block, check) }
+
+      barcode = blocks.map { |block| block[0, 11] }.join
+      barcode[3] == check.call(without(barcode, 3)).to_s
+    end
+
+    # O 3º dígito da arrecadação diz qual módulo usar. Outros valores são inválidos.
+    def self.arrecadacao_check(value_id)
+      case value_id
+      when "6", "7" then method(:mod10)
+      when "8", "9" then method(:mod11_arrecadacao)
+      end
+    end
+
+    # O último dígito do trecho é o verificador dos anteriores?
+    def self.check_digit_ok?(chunk, check)
+      chunk[-1] == check.call(chunk[0..-2]).to_s
+    end
+
+    # O texto sem o caractere da posição indicada (onde fica o DV geral).
+    def self.without(text, index)
+      text[0, index] + text[(index + 1)..]
+    end
+
+    # Pesos 2, 1, 2, 1... da direita para a esquerda; produtos com dois algarismos
+    # entram somados (12 vira 1 + 2). O dígito é o que falta para a próxima dezena.
+    def self.mod10(digits)
+      sum = digits.reverse.chars.each_with_index.sum do |digit, index|
+        product = digit.to_i * (index.even? ? 2 : 1)
+        (product / 10) + (product % 10)
+      end
+      (10 - (sum % 10)) % 10
+    end
+
+    # Pesos 2 a 9, da direita para a esquerda, voltando ao 2 depois do 9.
+    def self.mod11_sum(digits)
+      digits.reverse.chars.each_with_index.sum { |digit, index| digit.to_i * ((index % 8) + 2) }
+    end
+
+    # Na cobrança, quando a conta dá 0, 10 ou 11, o dígito vira 1 (nunca é 0).
+    def self.mod11_cobranca(digits)
+      digit = 11 - (mod11_sum(digits) % 11)
+      [0, 10, 11].include?(digit) ? 1 : digit
+    end
+
+    # Na arrecadação, resto 0 ou 1 vira dígito 0.
+    def self.mod11_arrecadacao(digits)
+      rest = mod11_sum(digits) % 11
+      rest < 2 ? 0 : 11 - rest
+    end
+
+    private_class_method :format_cobranca, :valid_cobranca?, :cobranca_barcode, :valid_arrecadacao?,
+                         :arrecadacao_check, :check_digit_ok?, :without, :mod10, :mod11_sum,
+                         :mod11_cobranca, :mod11_arrecadacao
+  end
+end

data/lib/br_validators/cnpj.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # CNPJ: 14 caracteres. Os 12 primeiros podem ser números ou letras maiúsculas
+  # (formato alfanumérico, usado pela Receita Federal a partir de julho de 2026);
+  # os 2 últimos são sempre dígitos verificadores. Os CNPJs só com números
+  # continuam válidos e seguem a mesma conta.
+  #
+  # Cada caractere vale o código ASCII dele menos 48: "0" vale 0, "9" vale 9,
+  # "A" vale 17, "Z" vale 42. Os dígitos verificadores usam módulo 11 com pesos
+  # de 2 a 9, da direita para a esquerda (voltando ao 2 depois do 9).
+  # Se o resto for 0 ou 1, o dígito é 0; senão, é 11 menos o resto.
+  #
+  # Fonte: manual do dígito verificador do CNPJ, da Receita Federal.
+  # https://www.gov.br/receitafederal/pt-br/centrais-de-conteudo/publicacoes/documentos-tecnicos/cnpj/manual-dv-cnpj.pdf
+  module CNPJ
+    # Caracteres de máscara aceitos na entrada: ponto, barra, hífen e espaços.
+    MASK = %r{[./\-\s]}
+
+    # 12 caracteres alfanuméricos e 2 dígitos no final.
+    PATTERN = /\A[0-9A-Z]{12}\d{2}\z/
+
+    # Tira a máscara e passa as letras para maiúsculas:
+    # "12.abc.345/01de-35" vira "12ABC34501DE35".
+    # A Receita só usa maiúsculas, mas é comum alguém digitar em minúsculas.
+    def self.strip(value)
+      value.to_s.gsub(MASK, "").upcase
+    end
+
+    def self.valid?(value)
+      cnpj = strip(value)
+      return false unless cnpj.match?(PATTERN)
+
+      # 00.000.000/0000-00 e parecidos passam na conta, mas não existem.
+      return false if cnpj.squeeze.size == 1
+
+      cnpj[12, 2] == check_digits(cnpj[0, 12])
+    end
+
+    # Devolve "12.ABC.345/01DE-35", ou nil se o CNPJ for inválido.
+    def self.format(value)
+      return nil unless valid?(value)
+
+      cnpj = strip(value)
+      "#{cnpj[0, 2]}.#{cnpj[2, 3]}.#{cnpj[5, 3]}/#{cnpj[8, 4]}-#{cnpj[12, 2]}"
+    end
+
+    def self.check_digits(base)
+      first = check_digit(base)
+      second = check_digit("#{base}#{first}")
+      "#{first}#{second}"
+    end
+
+    def self.check_digit(chars)
+      # Pesos 2, 3, ..., 9, 2, 3... a partir do último caractere.
+      sum = chars.reverse.chars.each_with_index.sum do |char, index|
+        (char.ord - 48) * ((index % 8) + 2)
+      end
+      rest = sum % 11
+      (rest < 2 ? 0 : 11 - rest).to_s
+    end
+
+    private_class_method :check_digits, :check_digit
+  end
+end

data/lib/br_validators/cns.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # CNS (Cartão Nacional de Saúde): 15 dígitos, só números.
+  #
+  # A validação segue as duas rotinas do Ministério da Saúde:
+  # - Números que começam com 1 ou 2 são gerados a partir do PIS (os 11 primeiros
+  #   dígitos). A soma do PIS com pesos de 15 a 5 dá o dígito verificador; o número
+  #   esperado é PIS + "000" + DV, ou PIS + "001" + DV quando a primeira conta dá 10.
+  # - Números que começam com 7, 8 ou 9 são válidos quando a soma dos 15 dígitos,
+  #   com pesos de 15 a 1, é divisível por 11.
+  # Qualquer outro primeiro dígito é inválido.
+  #
+  # O CNS não tem máscara oficial. O 16º número impresso no cartão é o número da
+  # via e não faz parte do CNS.
+  #
+  # Fonte: regras de validação do CNS publicadas pela Anvisa, com as rotinas do
+  # Ministério da Saúde.
+  # https://rni-docs.anvisa.gov.br/docs/regras_gerais/validacoes/validacaoCNS/
+  module CNS
+    # O cartão mostra o número em grupos separados por espaço; aceitamos também
+    # pontos e hífens, que às vezes aparecem em sistemas antigos.
+    MASK = /[.\-\s]/
+
+    def self.strip(value)
+      value.to_s.gsub(MASK, "")
+    end
+
+    def self.valid?(value)
+      cns = strip(value)
+      return false unless cns.match?(/\A\d{15}\z/)
+
+      case cns[0]
+      when "1", "2" then cns == from_pis(cns[0, 11])
+      when "7", "8", "9" then (weighted_sum(cns) % 11).zero?
+      else false
+      end
+    end
+
+    # Devolve o CNS em grupos de 3, 4, 4 e 4 dígitos, como aparece impresso no
+    # cartão ("123 4567 8901 0000"), ou nil se for inválido.
+    def self.format(value)
+      return nil unless valid?(value)
+
+      cns = strip(value)
+      "#{cns[0, 3]} #{cns[3, 4]} #{cns[7, 4]} #{cns[11, 4]}"
+    end
+
+    # Monta o CNS esperado para um PIS, como na rotina do Ministério da Saúde.
+    def self.from_pis(pis)
+      sum = weighted_sum(pis)
+      digit = 11 - (sum % 11)
+      digit = 0 if digit == 11
+      return "#{pis}000#{digit}" unless digit == 10
+
+      # Quando o dígito dá 10, a rotina soma 2 e coloca "001" no meio.
+      digit = 11 - ((sum + 2) % 11)
+      "#{pis}001#{digit}"
+    end
+
+    # Pesos começando em 15 e diminuindo de 1 em 1 a cada dígito.
+    def self.weighted_sum(digits)
+      digits.chars.each_with_index.sum { |digit, index| digit.to_i * (15 - index) }
+    end
+
+    private_class_method :from_pis, :weighted_sum
+  end
+end

data/lib/br_validators/cpf.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # CPF: 11 dígitos, sendo os dois últimos verificadores.
+  #
+  # Cada dígito verificador é calculado com módulo 11 sobre os dígitos anteriores:
+  # o primeiro usa pesos de 10 a 2 nos 9 primeiros dígitos; o segundo usa pesos de
+  # 11 a 2 nos 10 primeiros (os 9 + o primeiro verificador). Se o resto da divisão
+  # por 11 for 0 ou 1, o dígito é 0; senão, é 11 menos o resto.
+  module CPF
+    # Caracteres de máscara que aceitamos na entrada: ponto, hífen e espaços.
+    MASK = /[.\-\s]/
+
+    # Tira a máscara: "123.456.789-09" vira "12345678909".
+    # Não remove letras nem outros símbolos, para que valid? possa recusá-los.
+    def self.strip(value)
+      value.to_s.gsub(MASK, "")
+    end
+
+    def self.valid?(value)
+      digits = strip(value)
+      return false unless digits.match?(/\A\d{11}\z/)
+
+      # 111.111.111-11, 222.222.222-22... passam na conta, mas não são CPFs reais.
+      return false if digits.squeeze.size == 1
+
+      digits[9, 2] == check_digits(digits[0, 9])
+    end
+
+    # Devolve "123.456.789-09", ou nil se o CPF for inválido
+    # (formatar um número errado esconderia o erro de quem chamou).
+    def self.format(value)
+      return nil unless valid?(value)
+
+      digits = strip(value)
+      "#{digits[0, 3]}.#{digits[3, 3]}.#{digits[6, 3]}-#{digits[9, 2]}"
+    end
+
+    def self.check_digits(base)
+      first = check_digit(base)
+      second = check_digit("#{base}#{first}")
+      "#{first}#{second}"
+    end
+
+    # Pesos decrescentes até 2, começando por (tamanho + 1): 10..2 para 9 dígitos,
+    # 11..2 para 10 dígitos.
+    def self.check_digit(digits)
+      weights = (2..(digits.size + 1)).to_a.reverse
+      sum = digits.chars.zip(weights).sum { |digit, weight| digit.to_i * weight }
+      rest = sum % 11
+      (rest < 2 ? 0 : 11 - rest).to_s
+    end
+
+    private_class_method :check_digits, :check_digit
+  end
+end

data/lib/br_validators/locale/en.yml

@@ -0,0 +1,8 @@
+en:
+  errors:
+    messages:
+      cpf_invalid: "is not a valid CPF"
+      cnpj_invalid: "is not a valid CNPJ"
+      cns_invalid: "is not a valid CNS"
+      pix_invalid: "is not a valid Pix key"
+      boleto_invalid: "is not a valid boleto line"

data/lib/br_validators/locale/pt-BR.yml

@@ -0,0 +1,8 @@
+pt-BR:
+  errors:
+    messages:
+      cpf_invalid: "não é um CPF válido"
+      cnpj_invalid: "não é um CNPJ válido"
+      cns_invalid: "não é um CNS válido"
+      pix_invalid: "não é uma chave Pix válida"
+      boleto_invalid: "não é uma linha digitável de boleto válida"

data/lib/br_validators/pix.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # Chave Pix: diz se a chave está no formato que o DICT (o diretório de chaves
+  # do Banco Central) aceita e qual é o tipo dela.
+  #
+  # Tipos e formatos, como o DICT guarda as chaves (sem máscara):
+  # - :cpf   -> 11 dígitos, com os dígitos verificadores corretos
+  # - :cnpj  -> 14 caracteres, numérico ou alfanumérico, com os verificadores corretos
+  # - :phone -> "+", código do país e número, só dígitos (ex.: "+5511987654321")
+  # - :email -> em minúsculas, com no máximo 77 caracteres
+  # - :evp   -> chave aleatória, um UUID em minúsculas
+  #
+  # Fontes: especificação da API do DICT e Manual Operacional do DICT (v8.5),
+  # que passou a aceitar o CNPJ alfanumérico.
+  # https://github.com/bacen/pix-dict-api
+  # https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Regulamento_Pix/X_ManualOperacionaldoDICT.pdf
+  module Pix
+    MAX_LENGTH = 77
+
+    PHONE = /\A\+[1-9][0-9]\d{1,14}\z/
+    EVP = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/
+
+    # Mesma expressão da especificação do DICT, quebrada em linhas (o "x" no
+    # final faz o Ruby ignorar as quebras). O "\#" precisa da barra: sem ela,
+    # o Ruby leria "#$&" como uma variável e sumiria com esses caracteres.
+    EMAIL = %r{
+      \A[a-z0-9.!\#$&'*+/=?^_`{|}~-]+
+      @[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?
+      (?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*\z
+    }x
+
+    # Cada tipo e a verificação dele, na ordem em que são testados.
+    CHECKS = {
+      cpf: ->(key) { key.match?(/\A\d{11}\z/) && CPF.valid?(key) },
+      cnpj: ->(key) { key.match?(/\A[0-9A-Z]{12}\d{2}\z/) && CNPJ.valid?(key) },
+      phone: ->(key) { key.match?(PHONE) },
+      email: ->(key) { key.match?(EMAIL) },
+      evp: ->(key) { key.match?(EVP) }
+    }.freeze
+
+    # Devolve :cpf, :cnpj, :phone, :email ou :evp, ou nil se a chave for inválida.
+    # Só os espaços nas pontas são ignorados: o resto precisa estar exatamente
+    # como o DICT guarda (sem máscara, e-mail e chave aleatória em minúsculas).
+    def self.type(value)
+      key = value.to_s.strip
+      return nil if key.size > MAX_LENGTH
+
+      found = CHECKS.find { |_type, check| check.call(key) }
+      found&.first
+    end
+
+    def self.valid?(value)
+      !type(value).nil?
+    end
+  end
+end

data/lib/br_validators/validators/boleto_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :linha_digitavel, boleto: true
+class BoletoValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::Boleto
+  ERROR = :boleto_invalid
+end

data/lib/br_validators/validators/cnpj_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :cnpj, cnpj: true
+class CnpjValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::CNPJ
+  ERROR = :cnpj_invalid
+end

data/lib/br_validators/validators/cns_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :cns, cns: true
+class CnsValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::CNS
+  ERROR = :cns_invalid
+end

data/lib/br_validators/validators/cpf_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :cpf, cpf: true
+class CpfValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::CPF
+  ERROR = :cpf_invalid
+end

data/lib/br_validators/validators/pix_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :chave_pix, pix: true
+class PixValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::Pix
+  ERROR = :pix_invalid
+end

data/lib/br_validators/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Versão da gem, lida também pelo gemspec.
+module BrValidators
+  VERSION = "0.1.0"
+end

data/lib/br_validators.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "br_validators/version"
+require_relative "br_validators/cpf"
+require_relative "br_validators/cnpj"
+require_relative "br_validators/cns"
+require_relative "br_validators/pix"
+require_relative "br_validators/boleto"
+
+# Validação e formatação de documentos brasileiros.
+#
+# Cada documento tem um módulo próprio (BrValidators::CPF, BrValidators::CNPJ...)
+# com os mesmos três métodos:
+#   valid?(valor)  -> true ou false
+#   format(valor)  -> o documento com a máscara, ou nil se for inválido
+#   strip(valor)   -> o documento sem a máscara
+module BrValidators
+end
+
+# Validação nos models (validates :cpf, cpf: true): só entra quando o projeto tem
+# o ActiveModel (todo app Rails tem), para a gem continuar sem dependências.
+require_relative "br_validators/active_model" if Gem.loaded_specs.key?("activemodel")

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: br_validators
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pedro Pedrassolli
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- pedropedrassolli@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/br_validators.rb
+- lib/br_validators/active_model.rb
+- lib/br_validators/boleto.rb
+- lib/br_validators/cnpj.rb
+- lib/br_validators/cns.rb
+- lib/br_validators/cpf.rb
+- lib/br_validators/locale/en.yml
+- lib/br_validators/locale/pt-BR.yml
+- lib/br_validators/pix.rb
+- lib/br_validators/validators/boleto_validator.rb
+- lib/br_validators/validators/cnpj_validator.rb
+- lib/br_validators/validators/cns_validator.rb
+- lib/br_validators/validators/cpf_validator.rb
+- lib/br_validators/validators/pix_validator.rb
+- lib/br_validators/version.rb
+homepage: https://github.com/PedroPedrassolli/br_validators
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/PedroPedrassolli/br_validators
+  changelog_uri: https://github.com/PedroPedrassolli/br_validators/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/PedroPedrassolli/br_validators/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Valida e formata CPF, CNPJ (inclusive alfanumérico), CNS, chave Pix e boleto.
+test_files: []