cpf_cnpj_plus 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3471ac722167a65351c70e1e5d5cc0942bd915ba0420eaef56050778bc05809b
-  data.tar.gz: d108eadcb37093bccfe1aca2b5ce65c5c4a1bfad4ebdb312a0d111fca8e0ff95
+  metadata.gz: 0be5c78bb01f594041dc6648af5e88c793a37909288d2e805ec4df415b1e80f3
+  data.tar.gz: c44eb35f3cd67072ba120f5c74960b295ba2abf8a902262743c2688f5ca8fad9
 SHA512:
-  metadata.gz: d4aa54004da35e9333beb2fdfce720ffec85f171cee7beb9d1204e27c576dddd7d319659581ed20569810c73468fe84c5633674536b3fa6870bee22b76c0e499
-  data.tar.gz: 22d11338440ada66d77bd93d05b74297a6a10642f25f7e634d93b44b595e6b08c55ffe06cdb5ca5f74305e44133f3f6f54d32a09001850a084a30c98b57f39be
+  metadata.gz: 4437f396b413c092653cd6f1960d5686e392fdb1bc488bb9244b919443d3de9c992d4187ef88f29e88b939a8bc3a086f49d4f71ac53e95b3fa1d8711c97c8a00
+  data.tar.gz: 685071ce041e859639aa0cd3c6091133481c725234b419bd49f18e36761339bcd55455ce751ac01fdf12643f08e8bd7f44f9c3c3976dee0c5bb6986f298bab79

data/.rubocop.yml

@@ -6,3 +6,6 @@ Style/StringLiterals:
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Metrics/BlockLength:
+  Max: 60

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-01
+
+- Adicionada API unificada que detecta CPF ou CNPJ pelo tamanho do
+  documento: `CpfCnpjPlus.valid?`, `CpfCnpjPlus.format` e
+  `CpfCnpjPlus.generate(:cpf | :cnpj, alphanumeric:)`.
+- Adicionado `CpfCnpjPlus.alphanumeric_cnpj?`, que identifica se um CNPJ
+  válido já usa o novo padrão alfanumérico (útil para auditar bases de
+  dados antes da migração de julho de 2026).
+- `format_cpf`/`format_cnpj` (e a nova `format`) agora aceitam a opção
+  `strict: true`, que retorna `nil` quando os dígitos verificadores ou a
+  estrutura do documento são inválidos, em vez de formatar um documento
+  incorreto silenciosamente.
+- Adicionado validador opcional para ActiveModel/Rails
+  (`require "cpf_cnpj_plus/active_model_validator"`), permitindo
+  `validates :campo, cpf_cnpj: true` (ou `type: :cpf`/`type: :cnpj`) em
+  models. Não é carregado por padrão e não adiciona `activemodel` como
+  dependência de runtime.
+- Testes adicionados para todas as features acima (100% de cobertura de
+  linhas).
+
+## [0.3.1] - 2026-08-01
+
+- Corrigido `exe/cnpj_plus --check`, que chamava um método inexistente
+  (`CpfCnpjPlus.valid?`) e quebrava com `NoMethodError`; agora usa
+  `valid_cnpj?`.
+- Corrigida a rejeição de CNPJs alfanuméricos "conhecidamente inválidos":
+  antes só bases numéricas com todos os dígitos iguais eram rejeitadas;
+  agora qualquer base de 12 caracteres repetidos é rejeitada, incluindo
+  letras (ex.: `"AAAAAAAAAAAA45"`).
+- Removida dependência morta de `byebug` nos specs do validator, que
+  quebrava `bundle exec rspec` em ambiente limpo (CI).
+- Corrigido o workflow de CI, que disparava em push apenas na branch
+  `master` e nunca era executado em `main`.
+- Corrigida a documentação do README, que citava um método
+  `CpfCnpjPlus.generate` inexistente (o correto é `generate_cpf`/`generate_cnpj`).
+- Adicionados testes para os casos acima e para os executáveis
+  `cnpj_plus`/`cpf_plus`.
+
 ## [0.1.0] - 2025-07-06
 
 - Initial release
@@ -9,5 +47,12 @@
 
 - Adjustment to be able to create the two new generation and formatting methods
 
+## [0.3.0] - 2026-04-27
+
+- Added the `generate_cpf` method to generate valid CPF numbers.
+- Added the `generate_cnpj` method to generate valid CNPJ numbers.
+- Added the `format_cpf` method to format CPF numbers in the standard format (XXX.XXX.XXX-XX).
+- Added the `format_cnpj` method to format CNPJ numbers in the standard format (XX.XXX.XXX/XXXX-XX).
+- Updated the README.md file to include examples of the new generation and formatting methods.
 
 

data/README.md

@@ -1,6 +1,10 @@
 # CPF CNPJ Plus
 
-**cpf_cnpj_plus** é uma biblioteca Ruby para **validar, gerar e formatar** números de CPF e CNPJ brasileiros, tanto via código Ruby quanto pela linha de comando.
+[![Gem Version](https://img.shields.io/gem/v/cpf_cnpj_plus.svg)](https://rubygems.org/gems/cpf_cnpj_plus)
+[![Ruby](https://github.com/DougNeo/cpf_cnpj_plus/actions/workflows/main.yml/badge.svg)](https://github.com/DougNeo/cpf_cnpj_plus/actions/workflows/main.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+**cpf_cnpj_plus** é uma biblioteca Ruby para **validar, gerar e formatar** números de CPF e CNPJ brasileiros. Funciona em **Ruby puro** (sem dependências de runtime), tem um **validador opcional para Rails/ActiveModel**, e oferece **ferramentas de linha de comando**.
 
 ---
 
@@ -40,22 +44,57 @@ A gem oferece uma API unificada para CPF e CNPJ. Exemplos:
 ```ruby
 require "cpf_cnpj_plus"
 
-CPF
+# CPF
 CpfCnpjPlus.valid_cpf?("123.456.789-09") # => true ou false
 CpfCnpjPlus.format_cpf("12345678909") # => "123.456.789-09"
-CpfCnpjPlus.generate # => Gera um CPF válido
+CpfCnpjPlus.generate_cpf # => Gera um CPF válido
 
-CNPJ
-CpfCnpjPlus.valid?("12.345.678/0001-95") # => true ou false
+# CNPJ
+CpfCnpjPlus.valid_cnpj?("12.345.678/0001-95") # => true ou false
 CpfCnpjPlus.format_cnpj("12345678000195") # => "12.345.678/0001-95"
-CpfCnpjPlus.generate # => Gera um CNPJ válido
+CpfCnpjPlus.generate_cnpj # => Gera um CNPJ válido
+
+# CNPJ Alfanumérico (novo formato)
+CpfCnpjPlus.valid_cnpj?("12.ABC.345/01DE-35") # => true
+CpfCnpjPlus.format_cnpj("12ABC34501DE35") # => "12.ABC.345/01DE-35"
+CpfCnpjPlus.generate_cnpj(alphanumeric: true) # => Gera um CNPJ alfanumérico válido
+CpfCnpjPlus.alphanumeric_cnpj?("12ABC34501DE35") # => true (identifica se já usa o novo padrão)
+
+# API unificada (detecta CPF ou CNPJ pelo tamanho do documento)
+CpfCnpjPlus.valid?("123.456.789-09")   # => true ou false
+CpfCnpjPlus.valid?("12.345.678/0001-95") # => true ou false
+CpfCnpjPlus.format("12345678909")      # => "123.456.789-09"
+CpfCnpjPlus.format("12345678000195")   # => "12.345.678/0001-95"
+CpfCnpjPlus.generate(:cpf)             # => Gera um CPF válido
+CpfCnpjPlus.generate(:cnpj, alphanumeric: true) # => Gera um CNPJ alfanumérico válido
+
+# Formatação estrita (retorna nil se os dígitos verificadores forem inválidos)
+CpfCnpjPlus.format_cpf("12345678900", strict: true)   # => nil (dígitos verificadores errados)
+CpfCnpjPlus.format_cnpj("12345678000199", strict: true) # => nil (dígitos verificadores errados)
+```
+
+### Validação em Rails/ActiveModel
+
+A gem também traz um validador opcional para uso com `ActiveModel::Validations`
+(inclusive em models Rails). Ele **não** é carregado junto com
+`require "cpf_cnpj_plus"` — é preciso requerê-lo explicitamente, e `activemodel`
+precisa estar disponível na sua aplicação:
+
+```ruby
+require "cpf_cnpj_plus/active_model_validator"
+
+class Empresa
+  include ActiveModel::Model
+  attr_accessor :cnpj, :cpf
 
-CNPJ Alfanumérico (novo formato)
-CpfCnpjPlus.valid?("A1234567B00195") # => true ou false
-CpfCnpjPlus.format_cnpj("A1234567B00195") # => "A12.345.67B/0019-5"
-CpfCnpjPlus.generate # => Gera um CNPJ alfanumérico válido
+  validates :cnpj, cpf_cnpj: { type: :cnpj }  # aceita CNPJ numérico ou alfanumérico
+  validates :cpf, cpf_cnpj: { type: :cpf }
+  # ou, para detectar o tipo automaticamente pelo tamanho:
+  # validates :documento, cpf_cnpj: true
+end
 ```
 
+Suporta as opções padrão do Rails (`allow_nil`, `allow_blank`, `message`).
 
 ### Linha de comando
 
@@ -66,21 +105,27 @@ $ cpf_plus --check 123.456.789-09
 $ cpf_plus --format 12345678909
 $ cpf_plus --generate
 $ cnpj_plus --check 12.345.678/0001-95
-$ cnpj_plus --check A12.345.67B/0019-5
+$ cnpj_plus --check 12.ABC.345/01DE-35
 $ cnpj_plus --generate
 ```
 
 ## Compatibilidade
 
-- Ruby >= 3.1.0
+- Ruby >= 3.1.0 (testado em CI nas versões 3.1, 3.2, 3.3, 3.4 e 4.0).
+- Sem dependências de runtime — funciona em qualquer projeto Ruby puro.
+- Uso com Rails/ActiveModel é opcional: só é necessário se você requerer
+  `cpf_cnpj_plus/active_model_validator` (veja a seção "Validação em
+  Rails/ActiveModel" acima).
 
 ## Contribuição
 
 1. Faça um fork do projeto
 2. Crie sua branch (`git checkout -b minha-feature`)
-3. Commit suas alterações (`git commit -am 'Adiciona nova feature'`)
-4. Faça push para a branch (`git push origin minha-feature`)
-5. Abra um Pull Request
+3. Rode `bundle install` e depois `bundle exec rake` (specs + rubocop) para
+   garantir que tudo continua passando
+4. Commit suas alterações (`git commit -am 'Adiciona nova feature'`)
+5. Faça push para a branch (`git push origin minha-feature`)
+6. Abra um Pull Request
 
 ## Licença
 

data/exe/cnpj_plus

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/cpf_cnpj_plus"
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Uso: cnpj_plus [opções]"
+  opts.on("--check CNPJ",    "Valida um CNPJ (numérico ou alfanumérico)") { |v| options[:check]  = v }
+  opts.on("--format CNPJ",   "Formata um CNPJ")                           { |v| options[:format] = v }
+  opts.on("--generate",      "Gera um CNPJ numérico válido")              { options[:generate] = true }
+  opts.on("--alphanumeric",  "Gera um CNPJ alfanumérico (com --generate)") { options[:alphanumeric] = true }
+end.parse!
+
+if options[:check]
+  valid = CpfCnpjPlus.valid_cnpj?(options[:check])
+  puts valid ? "✅ CNPJ válido" : "❌ CNPJ inválido"
+elsif options[:format]
+  result = CpfCnpjPlus.format_cnpj(options[:format])
+  puts result || "❌ CNPJ inválido para formatação"
+elsif options[:generate]
+  puts CpfCnpjPlus.generate_cnpj(alphanumeric: options[:alphanumeric] || false)
+else
+  puts "Use --help para ver as opções disponíveis."
+end

data/exe/cpf_plus

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/cpf_cnpj_plus"
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Uso: cpf_plus [opções]"
+  opts.on("--check CPF",    "Valida um CPF")    { |v| options[:check]  = v }
+  opts.on("--format CPF",   "Formata um CPF")   { |v| options[:format] = v }
+  opts.on("--generate",     "Gera um CPF válido") { options[:generate] = true }
+end.parse!
+
+if options[:check]
+  valid = CpfCnpjPlus.valid_cpf?(options[:check])
+  puts valid ? "✅ CPF válido" : "❌ CPF inválido"
+elsif options[:format]
+  result = CpfCnpjPlus.format_cpf(options[:format])
+  puts result || "❌ CPF inválido para formatação"
+elsif options[:generate]
+  puts CpfCnpjPlus.generate_cpf
+else
+  puts "Use --help para ver as opções disponíveis."
+end

data/lib/cpf_cnpj_plus/active_model_validator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_model"
+require_relative "../cpf_cnpj_plus"
+
+# Validador ActiveModel opcional. Não é carregado por padrão junto com a gem —
+# quem quiser usar em um model Rails/ActiveModel deve fazer:
+#
+#   require "cpf_cnpj_plus/active_model_validator"
+#
+#   class Empresa
+#     include ActiveModel::Model
+#     attr_accessor :cnpj
+#
+#     validates :cnpj, cpf_cnpj: true                # detecta CPF ou CNPJ pelo tamanho
+#     validates :cnpj, cpf_cnpj: { type: :cnpj }      # aceita só CNPJ (numérico ou alfanumérico)
+#     validates :cpf,  cpf_cnpj: { type: :cpf }       # aceita só CPF
+#   end
+class CpfCnpjValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if options[:allow_nil] && value.nil?
+    return if options[:allow_blank] && (value.nil? || value.to_s.strip.empty?)
+
+    record.errors.add(attribute, options.fetch(:message, :invalid)) unless valid_document?(value)
+  end
+
+  private
+
+  def valid_document?(value)
+    case options[:type]&.to_sym
+    when :cpf then CpfCnpjPlus.valid_cpf?(value)
+    when :cnpj then CpfCnpjPlus.valid_cnpj?(value)
+    when nil then CpfCnpjPlus.valid?(value)
+    else
+      raise ArgumentError, "type deve ser :cpf ou :cnpj (recebido: #{options[:type].inspect})"
+    end
+  end
+end

data/lib/cpf_cnpj_plus/formatter/cnpj.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CpfCnpjPlus
+  module Formatter
+    # Responsável por formatar números de CNPJ para exibição.
+    # Suporta o formato numérico tradicional e o novo formato alfanumérico,
+    # aplicando a máscara padrão XX.XXX.XXX/XXXX-XX.
+    class Cnpj
+      def self.format(cnpj, strict: false)
+        cleaned = cnpj.to_s.upcase.gsub(/[^A-Z0-9]/, "")
+        return nil unless cleaned.length == 14
+        return nil if strict && !Validator::Cnpj.valid?(cleaned)
+
+        "#{cleaned[0..1]}.#{cleaned[2..4]}.#{cleaned[5..7]}/#{cleaned[8..11]}-#{cleaned[12..13]}"
+      end
+    end
+  end
+end

data/lib/cpf_cnpj_plus/formatter/cpf.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CpfCnpjPlus
+  module Formatter
+    # Responsável por formatar números de CPF para exibição.
+    # Aplica a máscara padrão XXX.XXX.XXX-XX a partir de uma string numérica.
+    class Cpf
+      def self.format(cpf, strict: false)
+        cleaned = cpf.to_s.gsub(/[^0-9]/, "")
+        return nil unless cleaned.length == 11
+        return nil if strict && !Validator::Cpf.valid?(cleaned)
+
+        "#{cleaned[0..2]}.#{cleaned[3..5]}.#{cleaned[6..8]}-#{cleaned[9..10]}"
+      end
+    end
+  end
+end

data/lib/cpf_cnpj_plus/formatter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CpfCnpjPlus
+  # Módulo responsável por agrupar formatadores de CPF e CNPJ.
+  # Fornece métodos e classes auxiliares para formatação de documentos brasileiros,
+  # incluindo suporte a formatos tradicionais e CNPJ alfanumérico.
+  module Formatter
+    require_relative "formatter/cnpj"
+    require_relative "formatter/cpf"
+  end
+end

data/lib/cpf_cnpj_plus/generator/cnpj.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module CpfCnpjPlus
+  module Generator
+    # Responsável por gerar números de CNPJ válidos aleatoriamente.
+    # Suporta geração no formato numérico tradicional e no novo formato
+    # alfanumérico, calculando os dígitos verificadores conforme a Receita Federal.
+    class Cnpj
+      DIGITS = ("0".."9").to_a.freeze
+      LETTERS = ("A".."Z").to_a.freeze
+      ALPHANUMERIC = (DIGITS + LETTERS).freeze
+
+      WEIGHTS_1D = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].freeze
+      WEIGHTS_2D = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].freeze
+
+      def self.generate(alphanumeric: false)
+        loop do
+          base = build_base(alphanumeric)
+          cnpj = build_cnpj(base)
+          return cnpj unless Validator::Cnpj.cnpj_not_valid?(cnpj)
+        end
+      end
+
+      def self.build_base(alphanumeric)
+        if alphanumeric
+          # Garante ao menos uma letra para ser genuinamente alfanumérico
+          base = Array.new(12) { ALPHANUMERIC.sample }
+          base[rand(0..11)] = LETTERS.sample
+          base
+        else
+          Array.new(12) { DIGITS.sample }
+        end
+      end
+
+      def self.build_cnpj(base)
+        values = base.map { |c| char_to_value(c) }
+        d1 = calculate_digit(values, WEIGHTS_1D)
+        d2 = calculate_digit(values + [d1], WEIGHTS_2D)
+        base.join + "#{d1}#{d2}"
+      end
+
+      def self.char_to_value(char)
+        char.ord - 48
+      end
+
+      def self.calculate_digit(values, weights)
+        soma = weights.each_with_index.sum { |w, i| values[i] * w }
+        result = (soma * 10) % 11
+        result == 10 ? 0 : result
+      end
+    end
+  end
+end

data/lib/cpf_cnpj_plus/generator/cpf.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CpfCnpjPlus
+  module Generator
+    # Responsável por gerar números de CPF válidos aleatoriamente.
+    # Calcula os dígitos verificadores conforme o algoritmo oficial da Receita Federal.
+    class Cpf
+      def self.generate
+        loop do
+          base = Array.new(9) { rand(0..9) }
+          cpf = build_cpf(base)
+          return cpf unless Validator::Cpf.cpf_not_valid?(cpf)
+        end
+      end
+
+      def self.build_cpf(base)
+        d1 = calculate_digit(base, (2..10).to_a.reverse)
+        d2 = calculate_digit(base + [d1], (2..11).to_a.reverse)
+        (base + [d1, d2]).join
+      end
+
+      def self.calculate_digit(digits, weights)
+        soma = digits.each_with_index.sum { |d, i| d * weights[i] }
+        result = (soma * 10) % 11
+        result == 10 ? 0 : result
+      end
+    end
+  end
+end

data/lib/cpf_cnpj_plus/generator.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CpfCnpjPlus
+  # Módulo responsável por agrupar geradores de CPF e CNPJ.
+  # Fornece métodos e classes auxiliares para geração de documentos brasileiros,
+  # incluindo suporte a formatos tradicionais e CNPJ alfanumérico.
+  module Generator
+    require_relative "generator/cnpj"
+    require_relative "generator/cpf"
+  end
+end

data/lib/cpf_cnpj_plus/validator/cnpj.rb

@@ -8,7 +8,7 @@ module CpfCnpjPlus
       def self.valid?(cnpj)
         cnpj = normalize(cnpj)
         return false unless valid_length?(cnpj)
-        return false if cpj_not_valid?(cnpj)
+        return false if cnpj_not_valid?(cnpj)
         return false unless valid_structure?(cnpj)
 
         base = cnpj[0..11].chars.map { |c| char_to_value(c) }
@@ -30,13 +30,7 @@ module CpfCnpjPlus
       end
 
       def self.char_to_value(char)
-        if ("0".."9").include?(char)
-          char.ord - 48
-        elsif ("A".."Z").include?(char)
-          char.ord - 48 # Ajuste para A=10, B=11, ..., Z=35
-        else
-          raise ArgumentError, "Caractere inválido"
-        end
+        char.ord - 48
       end
 
       def self.calculate_cnpj_digits(base)
@@ -63,11 +57,14 @@ module CpfCnpjPlus
         digit
       end
 
-      def self.cpj_not_valid?(cnpj)
-        cnpj = cnpj.to_s.gsub(/[^0-9]/, "")
-        %w[00000000000000 11111111111111 22222222222222 33333333333333
-           44444444444444 55555555555555 66666666666666 77777777777777
-           88888888888888 99999999999999].include?(cnpj)
+      def self.alphanumeric?(cnpj)
+        cnpj = normalize(cnpj)
+        valid?(cnpj) && cnpj[0..11].match?(/[A-Z]/)
+      end
+
+      def self.cnpj_not_valid?(cnpj)
+        base = cnpj.to_s[0..11]
+        base.to_s.length == 12 && base.chars.uniq.length == 1
       end
     end
   end

data/lib/cpf_cnpj_plus/validator/cpf.rb

@@ -8,36 +8,35 @@ module CpfCnpjPlus
       def self.valid?(cpf)
         cpf = cpf.to_s.gsub(/[^0-9]/, "")
         return false unless cpf.length == 11 && cpf =~ /^\d{11}$/
-        return false if cpj_not_valid?(cpf)
+        return false if cpf_not_valid?(cpf)
 
         first_digit(cpf) && second_digit(cpf)
       end
 
       def self.first_digit(cpf)
-        first_digit = cpf[0..8]
+        base_digits = cpf[0..8]
         soma = 0
         ponteiro = 10
-        first_digit.chars.each do |char|
-          res = (char.to_i * ponteiro)
-          soma += res
+        base_digits.chars.each do |char|
+          soma += char.to_i * ponteiro
           ponteiro -= 1
         end
-        soma * 10 % 11 == cpf[9].to_i
+        result = soma * 10 % 11
+        result == cpf[9].to_i || (result == 10 && cpf[9].to_i.zero?)
       end
 
       def self.second_digit(cpf)
-        second_digit = cpf[0..9]
+        base_digits = cpf[0..9]
         soma = 0
         ponteiro = 11
-        second_digit.chars.each do |char|
-          res = (char.to_i * ponteiro)
-          soma += res
+        base_digits.chars.each do |char|
+          soma += char.to_i * ponteiro
           ponteiro -= 1
         end
         soma * 10 % 11 == cpf[10].to_i || (soma * 10 % 11 == 10 && cpf[10].to_i.zero?)
       end
 
-      def self.cpj_not_valid?(cpf)
+      def self.cpf_not_valid?(cpf)
         cpf = cpf.to_s.gsub(/[^0-9]/, "")
         %w[00000000000 11111111111 22222222222 33333333333
            44444444444 55555555555 66666666666

data/lib/cpf_cnpj_plus/validator.rb

@@ -3,7 +3,7 @@
 module CpfCnpjPlus
   # Módulo responsável por agrupar validadores de CPF e CNPJ.
   # Fornece métodos e classes auxiliares para validação de documentos brasileiros,
-  # incluindo suporte a formatos tradicionais e futuros (como CNPJ alfanumérico).
+  # incluindo suporte a formatos tradicionais e CNPJ alfanumérico.
   module Validator
     require_relative "validator/cnpj"
     require_relative "validator/cpf"

data/lib/cpf_cnpj_plus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CpfCnpjPlus
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/cpf_cnpj_plus.rb

@@ -2,6 +2,8 @@
 
 require_relative "cpf_cnpj_plus/version"
 require_relative "cpf_cnpj_plus/validator"
+require_relative "cpf_cnpj_plus/formatter"
+require_relative "cpf_cnpj_plus/generator"
 
 # Módulo principal da gem cpf_cnpj_plus.
 # Fornece métodos para validação, geração e formatação de CPFs e CNPJs,
@@ -9,27 +11,68 @@ require_relative "cpf_cnpj_plus/validator"
 module CpfCnpjPlus
   class Error < StandardError; end
 
+  # CPF
+  def self.valid_cpf?(cpf)
+    CpfCnpjPlus::Validator::Cpf.valid?(cpf)
+  end
+
+  def self.format_cpf(cpf, strict: false)
+    CpfCnpjPlus::Formatter::Cpf.format(cpf, strict: strict)
+  end
+
+  def self.generate_cpf
+    CpfCnpjPlus::Generator::Cpf.generate
+  end
+
+  # CNPJ
+
   def self.valid_cnpj?(cnpj)
     CpfCnpjPlus::Validator::Cnpj.valid?(cnpj)
   end
 
-  def self.valid_cpf?(cpf)
-    CpfCnpjPlus::Validator::Cpf.valid?(cpf)
+  def self.format_cnpj(cnpj, strict: false)
+    CpfCnpjPlus::Formatter::Cnpj.format(cnpj, strict: strict)
   end
 
-  def self.format_cpf(cpf)
-    CpfCnpjPlus::Format::Cpf.format(cpf)
+  def self.generate_cnpj(alphanumeric: false)
+    CpfCnpjPlus::Generator::Cnpj.generate(alphanumeric: alphanumeric)
   end
 
-  def self.format_cnpj(cnpj)
-    CpfCnpjPlus::Format::Cnpj.format(cnpj)
+  def self.alphanumeric_cnpj?(cnpj)
+    CpfCnpjPlus::Validator::Cnpj.alphanumeric?(cnpj)
   end
 
-  def self.generate_cpf
-    CpfCnpjPlus::Generate::Cpf.generate
+  # API unificada (detecta CPF ou CNPJ pelo tamanho do documento)
+
+  def self.valid?(doc)
+    case document_type(doc)
+    when :cpf then valid_cpf?(doc)
+    when :cnpj then valid_cnpj?(doc)
+    else false
+    end
+  end
+
+  def self.format(doc, strict: false)
+    case document_type(doc)
+    when :cpf then format_cpf(doc, strict: strict)
+    when :cnpj then format_cnpj(doc, strict: strict)
+    end
+  end
+
+  def self.generate(type, alphanumeric: false)
+    case type.to_s.downcase
+    when "cpf" then generate_cpf
+    when "cnpj" then generate_cnpj(alphanumeric: alphanumeric)
+    else
+      raise ArgumentError, "type deve ser :cpf ou :cnpj (recebido: #{type.inspect})"
+    end
   end
 
-  def self.generate_cnpj
-    CpfCnpjPlus::Generate::Cnpj.generate
+  def self.document_type(doc)
+    case doc.to_s.upcase.gsub(/[^A-Z0-9]/, "").length
+    when 11 then :cpf
+    when 14 then :cnpj
+    end
   end
+  private_class_method :document_type
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: cpf_cnpj_plus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - DougNeo
 bindir: exe
 cert_chain: []
-date: 2025-07-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -23,17 +37,17 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: |-
-  Fornece métodos práticos para validar, gerar e formatar números de CPF e CNPJ, incluindo
-                          ferramentas de linha de comando para facilitar integrações em sistemas bancários,
-                          governamentais e aplicações Ruby em geral.
+description: Fornece métodos práticos para validar, gerar e formatar números de CPF
+  e CNPJ (incluindo o novo CNPJ alfanumérico), com API para Ruby puro, validador opcional
+  para Rails/ActiveModel e ferramentas de linha de comando.
 email:
 - doug.neo@gmail.com
-executables: []
+executables:
+- cnpj_plus
+- cpf_plus
 extensions: []
 extra_rdoc_files: []
 files:
-- ".byebug_history"
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
@@ -41,20 +55,29 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- exe/cnpj_plus
+- exe/cpf_plus
 - lib/cpf_cnpj_plus.rb
+- lib/cpf_cnpj_plus/active_model_validator.rb
+- lib/cpf_cnpj_plus/formatter.rb
+- lib/cpf_cnpj_plus/formatter/cnpj.rb
+- lib/cpf_cnpj_plus/formatter/cpf.rb
+- lib/cpf_cnpj_plus/generator.rb
+- lib/cpf_cnpj_plus/generator/cnpj.rb
+- lib/cpf_cnpj_plus/generator/cpf.rb
 - lib/cpf_cnpj_plus/validator.rb
 - lib/cpf_cnpj_plus/validator/cnpj.rb
 - lib/cpf_cnpj_plus/validator/cpf.rb
 - lib/cpf_cnpj_plus/version.rb
 - sig/cpf_cnpj_plus.rbs
-homepage: https://github.com/DougNeo/cpf_cnpj_plus.git
+homepage: https://github.com/DougNeo/cpf_cnpj_plus
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/DougNeo/cpf_cnpj_plus.git
-  source_code_uri: https://github.com/DougNeo/cpf_cnpj_plus.git
-  changelog_uri: https://github.com/DougNeo/cpf_cnpj_plus.git/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/DougNeo/cpf_cnpj_plus
+  changelog_uri: https://github.com/DougNeo/cpf_cnpj_plus/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -69,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Validação, geração e formatação de números de CPF e CNPJ para o Brasil.
 test_files: []

data/.byebug_history

@@ -1,4 +0,0 @@
-c
-described_class.valid_cpf?("10321255780")
-described_class.valid_cpf?("103.212.557-80")
-described_class.valid_cpf?("10321255780")