br_validators 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7297d8bd1acfbea15d3f7ef85f6bbb6cd5cc5555129c6a83bfade0e69358c14b
-  data.tar.gz: 9eab13d77a0a931e3c7a6dc34542dc9a0a069f67f5b9c72f38b9517f457e8336
+  metadata.gz: 8ab3d772a8a5a9512686a875c429689adcb348af7eac07f7f795f2efa616d402
+  data.tar.gz: 5c222dfc1339f2c451501fd010767ce82b0111243e4768b0762a896b03b2a363
 SHA512:
-  metadata.gz: c8de53e6d4904f91915313b8f3f68ccfbe2b4e9269cff2bc0ea2f26c5cc87d2e13b3660cbd6130e4297a8d94d249758d4f1a5e5199b188882f16307413f37e7b
-  data.tar.gz: 6d948e9f10e7acd07d35c8e773f770931681afe19976fc447cbe29c6f37969a012629dac68ca187eb6b3f55fa8131cae69a0fd23d646eea250e2f8a719c085d7
+  metadata.gz: a9663daabd0c2079d63aa4990c0e5454bb47024b7e7cf1545f2db7f0a76a3c69aaf5e3141d7a808b94457a79a65eef48a0ddf5a5e378b76ec0474beb2ea87bfd
+  data.tar.gz: bcc9e9bce3dda58ff44c9039fb7107cdc217a0dddd997d4d935995eb524a7a0e0ad23c910203bfe540d94990a1b4cbc56b9f9c4fb84e9ea22cd0c1d7b46e6a55

data/CHANGELOG.md

@@ -3,6 +3,22 @@
 As mudanças de cada versão ficam aqui. O projeto segue o
 [versionamento semântico](https://semver.org/lang/pt-BR/).
 
+## [0.2.1] - 2026-10-26
+
+### Corrigido
+
+- Traços tipográficos (meia-risca, travessão, hífen sem quebra), comuns ao copiar do Word
+  ou de um PDF, contam como máscara, como o hífen comum.
+- Texto em outros encodings (Latin-1, Windows-1252, UTF-16) é convertido para UTF-8 antes
+  da validação (`BrValidators.texto`); antes, UTF-16 levantava `Encoding::CompatibilityError`.
+- `ChaveAcesso` confere o código IBGE da UF e o mês: uma chave só de zeros passava.
+- `Consulta`: resposta quebrada (que não é HTTP) também vira `Consulta::Erro`.
+
+### Outros
+
+- A API da página de teste devolve `detalhe` (DDD, UF do título, segmento do processo e
+  modelo da chave de acesso).
+
 ## [0.2.0] - 2026-10-26
 
 ### Novo

data/README.md

@@ -27,7 +27,7 @@ Ou direto: `gem install br_validators`. A gem está publicada no
 | Telefone | `Telefone` | fixo e celular, com os 67 DDDs da Anatel |
 | Placa | `Placa` | antiga e Mercosul, com conversão entre as duas |
 | RENAVAM | `RENAVAM` | 11 dígitos |
-| Chave de acesso | `ChaveAcesso` | NF-e, NFC-e, CT-e e MDF-e, inclusive com CNPJ alfanumérico |
+| Chave de acesso | `ChaveAcesso` | NF-e, NFC-e, CT-e e MDF-e, inclusive com CNPJ alfanumérico; confere UF e mês |
 | Processo judicial | `ProcessoCNJ` | numeração única do CNJ |
 
 A regra de cada um está no comentário do módulo, com o link da fonte oficial (Receita
@@ -48,9 +48,10 @@ BrValidators::CNPJ.format("12abc34501de35")     # => "12.ABC.345/01DE-35"
 BrValidators::CNS.format("898000000000436")      # => "898 0000 0000 0436"
 ```
 
-Pontos, hífens e espaços são ignorados em qualquer posição, inclusive o espaço não
-separável que vem junto ao copiar de um PDF ou de um site. Texto corrompido (bytes que
-não são UTF-8 válido) só dá `false`, sem erro. Passe sempre o documento como texto: um
+Pontos, traços e espaços são ignorados em qualquer posição, inclusive a meia-risca (–)
+e o espaço não separável que vêm junto ao copiar do Word, de um PDF ou de um site. O texto
+pode vir em qualquer encoding (UTF-8, Latin-1, UTF-16); texto corrompido só dá `false`,
+sem erro. Passe sempre o documento como texto: um
 número inteiro perde os zeros à esquerda (`01234567890` vira `1234567890`).
 
 A chave Pix é um caso à parte: em vez de `format` e `strip`, ela tem `type`, que diz
@@ -159,7 +160,10 @@ Dá para testar cada validador no navegador em https://br-validators.vercel.app.
 
 ```
 GET /api/validar?documento=cnpj&valor=12.ABC.345/01DE-35
-{"documento":"cnpj","valido":true,"formatado":"12.ABC.345/01DE-35","tipo":null}
+{"documento":"cnpj","valido":true,"formatado":"12.ABC.345/01DE-35","tipo":null,"detalhe":null}
+
+GET /api/validar?documento=titulo_eleitor&valor=1023%208501%200671
+{"documento":"titulo_eleitor","valido":true,"formatado":"1023 8501 0671","tipo":null,"detalhe":"PR"}
 ```
 
 ## Desenvolvimento

data/lib/br_validators/boleto.rb

@@ -22,11 +22,10 @@ module BrValidators
     # Pontos, espaços e hífens que aparecem na linha impressa. A linha copiada do
     # PDF do boleto ou do site do banco costuma vir com espaço não separável, que
     # [:space:] também pega.
-    MASK = /[.\-[:space:]]/
+    MASK = /[.\p{Pd}[:space:]]/
 
-    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "")
+      BrValidators.texto(value).gsub(MASK, "")
     end
 
     # :cobranca, :arrecadacao ou nil se a linha for inválida.

data/lib/br_validators/cep.rb

@@ -15,11 +15,10 @@ module BrValidators
   # https://www.correios.com.br/enviar/precisa-de-ajuda/imagens/tudo-sobre-cep
   module CEP
     # Pontos, hífens e espaços (inclusive os Unicode, como o não separável).
-    MASK = /[.\-[:space:]]/
+    MASK = /[.\p{Pd}[:space:]]/
 
-    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "")
+      BrValidators.texto(value).gsub(MASK, "")
     end
 
     # 8 dígitos. "00000-000" é o CEP que sistemas usam como "não informado";

data/lib/br_validators/chave_acesso.rb

@@ -11,7 +11,9 @@ module BrValidators
   #   serie (3), nNF (9), tpEmis (1), cNF (8) e o dígito verificador (1)
   #
   # Com o CNPJ alfanumérico, os 12 primeiros caracteres do CNPJ podem ter letras;
-  # todo o resto continua só com números.
+  # todo o resto continua só com números. Além do dígito verificador, conferimos
+  # que o cUF é o código IBGE de uma UF e que o mês vai de 01 a 12 (sem isso, uma
+  # chave só de zeros passaria).
   #
   # O dígito verificador usa módulo 11 com pesos de 2 a 9, da direita para a
   # esquerda, sobre os 43 primeiros caracteres. Cada caractere vale o código ASCII
@@ -21,23 +23,34 @@ module BrValidators
   # Fontes: Manual de Orientação do Contribuinte da NF-e e Nota Técnica Conjunta
   # 2025.001 (CNPJ alfanumérico nos documentos fiscais eletrônicos), publicados no
   # Portal da NF-e. https://www.nfe.fazenda.gov.br/portal/
+  # Códigos das UFs: tabela do IBGE. https://www.ibge.gov.br/explica/codigos-dos-municipios.php
   module ChaveAcesso
     # 6 números (cUF e AAMM), 12 letras ou números (raiz e ordem do CNPJ) e 26
     # números (dígitos do CNPJ e o resto da chave).
     PATTERN = /\A\d{6}[0-9A-Z]{12}\d{26}\z/
 
+    # Códigos IBGE das 27 UFs (o cUF, dois primeiros dígitos da chave).
+    UFS_IBGE = %w[
+      11 12 13 14 15 16 17
+      21 22 23 24 25 26 27 28 29
+      31 32 33 35
+      41 42 43
+      50 51 52 53
+    ].freeze
+
     # O DANFE imprime a chave em grupos de 4, separados por espaço.
-    MASK = /[.\-[:space:]]/
+    MASK = /[.\p{Pd}[:space:]]/
 
     # Tira a máscara e passa as letras do CNPJ para maiúsculas.
-    # upcase(:ascii) e scrub estão explicados no CNPJ e no CPF.
+    # O upcase(:ascii) está explicado no CNPJ.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "").upcase(:ascii)
+      BrValidators.texto(value).gsub(MASK, "").upcase(:ascii)
     end
 
     def self.valid?(value)
       chave = strip(value)
       return false unless chave.match?(PATTERN)
+      return false unless UFS_IBGE.include?(chave[0, 2]) && chave[4, 2].between?("01", "12")
 
       chave[43] == check_digit(chave[0, 43])
     end

data/lib/br_validators/cnpj.rb

@@ -16,7 +16,7 @@ module BrValidators
   module CNPJ
     # Caracteres de máscara aceitos na entrada: ponto, barra, hífen e espaços
     # (inclusive os espaços Unicode, como o não separável).
-    MASK = %r{[./\-[:space:]]}
+    MASK = %r{[./\p{Pd}[:space:]]}
 
     # 12 caracteres alfanuméricos e 2 dígitos no final.
     PATTERN = /\A[0-9A-Z]{12}\d{2}\z/
@@ -27,9 +27,9 @@ module BrValidators
     #
     # upcase(:ascii) mexe só nas letras de a a z. O upcase normal segue o Unicode e
     # transforma "ı" (i sem ponto) em "I" e "ß" em "SS", o que faria um texto
-    # errado passar como CNPJ válido. O scrub está explicado no CPF.
+    # errado passar como CNPJ válido.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "").upcase(:ascii)
+      BrValidators.texto(value).gsub(MASK, "").upcase(:ascii)
     end
 
     def self.valid?(value)

data/lib/br_validators/cns.rb

@@ -21,11 +21,10 @@ module BrValidators
     # 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. Espaços Unicode
     # (como o não separável) também contam como espaço.
-    MASK = /[.\-[:space:]]/
+    MASK = /[.\p{Pd}[:space:]]/
 
-    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "")
+      BrValidators.texto(value).gsub(MASK, "")
     end
 
     def self.valid?(value)

data/lib/br_validators/consulta.rb

@@ -92,9 +92,13 @@ module BrValidators
     module HTTP
       HEADERS = { "Accept" => "application/json", "User-Agent" => "br_validators/#{VERSION}" }.freeze
 
-      # Problemas de rede: não conectou, a conexão caiu, demorou demais ou o
-      # certificado falhou. Viram Consulta::Erro, para quem chama tratar um erro só.
-      ERROS_DE_REDE = [Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError].freeze
+      # Problemas de rede: não conectou, a conexão caiu, demorou demais, o
+      # certificado falhou ou a resposta veio quebrada (não é HTTP de verdade).
+      # Viram Consulta::Erro, para quem chama tratar um erro só.
+      ERROS_DE_REDE = [
+        Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError,
+        Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError
+      ].freeze
 
       def self.get(uri)
         http = Net::HTTP.new(uri.host, uri.port)

data/lib/br_validators/cpf.rb

@@ -8,17 +8,19 @@ module BrValidators
   # 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.
-    # [:space:] pega também os espaços Unicode, como o espaço não separável que
-    # vem junto ao copiar um número de um PDF ou de um site.
-    MASK = /[.\-[:space:]]/
+    # Caracteres de máscara que aceitamos na entrada: ponto, traços e espaços.
+    # Ao copiar um número de um PDF, do Word ou de um site, o hífen pode virar
+    # meia-risca (–) ou hífen sem quebra, e o espaço pode virar o não separável:
+    # \p{Pd} pega qualquer traço e [:space:] qualquer espaço. Os outros módulos
+    # seguem a mesma ideia.
+    MASK = /[.\p{Pd}[:space:]]/
 
     # Tira a máscara: "123.456.789-09" vira "12345678909".
     # Não remove letras nem outros símbolos, para que valid? possa recusá-los.
-    # O scrub troca bytes inválidos (texto corrompido) por "�", que nunca passa na
-    # validação; sem ele, o gsub levantaria um erro em vez de devolver false.
+    # BrValidators.texto (texto.rb) converte para UTF-8 e troca bytes inválidos
+    # por "�", que nunca passa na validação.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "")
+      BrValidators.texto(value).gsub(MASK, "")
     end
 
     def self.valid?(value)

data/lib/br_validators/pix.rb

@@ -45,9 +45,8 @@ module BrValidators
     # 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).
-    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
     def self.type(value)
-      key = value.to_s.scrub.gsub(EDGE_SPACES, "")
+      key = BrValidators.texto(value).gsub(EDGE_SPACES, "")
       return nil if key.size > MAX_LENGTH
 
       found = CHECKS.find { |_type, check| check.call(key) }

data/lib/br_validators/placa.rb

@@ -18,12 +18,12 @@ module BrValidators
     MERCOSUL = /\A[A-Z]{3}\d[A-Z]\d{2}\z/
 
     # Pontos, hífens e espaços.
-    MASK = /[.\-[:space:]]/
+    MASK = /[.\p{Pd}[:space:]]/
 
     # Tira a máscara e passa as letras para maiúsculas: "abc-1234" vira "ABC1234".
-    # upcase(:ascii) e scrub estão explicados no CNPJ e no CPF.
+    # O upcase(:ascii) está explicado no CNPJ.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "").upcase(:ascii)
+      BrValidators.texto(value).gsub(MASK, "").upcase(:ascii)
     end
 
     # :antiga, :mercosul ou nil se a placa for inválida.

data/lib/br_validators/processo_cnj.rb

@@ -31,11 +31,10 @@ module BrValidators
     }.freeze
 
     # Pontos, hífens e espaços.
-    MASK = /[.\-[:space:]]/
+    MASK = /[.\p{Pd}[:space:]]/
 
-    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "")
+      BrValidators.texto(value).gsub(MASK, "")
     end
 
     def self.valid?(value)

data/lib/br_validators/renavam.rb

@@ -16,11 +16,10 @@ module BrValidators
   # calculado através do módulo 11, peso 9"), válida desde abril de 2013.
   module RENAVAM
     # O RENAVAM não tem máscara oficial; aceitamos pontos, hífens e espaços.
-    MASK = /[.\-[:space:]]/
+    MASK = /[.\p{Pd}[:space:]]/
 
-    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "")
+      BrValidators.texto(value).gsub(MASK, "")
     end
 
     def self.valid?(value)

data/lib/br_validators/telefone.rb

@@ -38,12 +38,11 @@ module BrValidators
     FIXO = /\A[2-5]\d{7}\z/
 
     # Parênteses, "+", pontos, hífens e espaços.
-    MASK = /[()+.\-[:space:]]/
+    MASK = /[()+.\p{Pd}[:space:]]/
 
     # Tira a máscara: "+55 (11) 98765-4321" vira "5511987654321".
-    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "")
+      BrValidators.texto(value).gsub(MASK, "")
     end
 
     # :celular, :fixo ou nil se o número for inválido.

data/lib/br_validators/texto.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Entrada comum a todos os validadores: ver BrValidators.texto abaixo.
+module BrValidators
+  # Converte o valor recebido em texto UTF-8 antes de tirar a máscara. Todos os
+  # validadores passam por aqui, para tratar a entrada do mesmo jeito:
+  #   - nil vira "" e números viram texto;
+  #   - texto em outro encoding (Latin-1, Windows-1252, UTF-16) é convertido;
+  #   - bytes inválidos (texto corrompido) viram "�", que nunca passa na validação.
+  # Assim os validadores devolvem false em vez de levantar erro, e as máscaras
+  # podem usar classes Unicode, como [:space:] (espaços) e \p{Pd} (traços).
+  def self.texto(valor)
+    valor.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+  end
+end

data/lib/br_validators/titulo_eleitor.rb

@@ -29,11 +29,10 @@ module BrValidators
     }.freeze
 
     # O título impresso mostra o número em grupos separados por espaço.
-    MASK = %r{[./\-[:space:]]}
+    MASK = %r{[./\p{Pd}[:space:]]}
 
-    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
     def self.strip(value)
-      value.to_s.scrub.gsub(MASK, "")
+      BrValidators.texto(value).gsub(MASK, "")
     end
 
     def self.valid?(value)

data/lib/br_validators/version.rb

@@ -2,5 +2,5 @@
 
 # Versão da gem, lida também pelo gemspec.
 module BrValidators
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/br_validators.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "br_validators/version"
+require_relative "br_validators/texto"
 require_relative "br_validators/cpf"
 require_relative "br_validators/cnpj"
 require_relative "br_validators/cns"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: br_validators
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Pedro Pedrassolli
@@ -9,6 +9,10 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
+description: 'Validação e formatação de documentos brasileiros sem dependências, com
+  a regra de cada um conferida na fonte oficial. Inclui validadores para ActiveModel
+  (validates :cpf, cpf: true) com mensagens em pt-BR e en, e consultas online opcionais
+  pela BrasilAPI (CEP, CNPJ, banco e DDD).'
 email:
 - pedropedrassolli@outlook.com
 executables: []
@@ -34,6 +38,7 @@ files:
 - lib/br_validators/processo_cnj.rb
 - lib/br_validators/renavam.rb
 - lib/br_validators/telefone.rb
+- lib/br_validators/texto.rb
 - lib/br_validators/titulo_eleitor.rb
 - lib/br_validators/validators/boleto_validator.rb
 - lib/br_validators/validators/cep_validator.rb