cnpj-dv 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4715b7cec54902ddb19fba13cb6ed707dfe47aa621857a61ca0fe8beacf3ac70
-  data.tar.gz: bee5b04815a43097528464af159dbdbb54a6288c8f3e2491ff585dd0467ca4c1
+  metadata.gz: 589e0576ee9e9cc2ddfeaf94c5f745792880885d7ea8dfcfb0953695b32a8981
+  data.tar.gz: 6662f13dfc238ea843cb79b14d1aaaf526c311e31f63dfc47937846a82ea3a2f
 SHA512:
-  metadata.gz: 103dfbad0358767ffd771c187b336605672a0d3e7e9633a3c98e143c3a6717f735a46eb1de466f709e77d3abb94bb65cd791892a475ab9940ff2b62705324752
-  data.tar.gz: faa45d622b815d48d6b51d95e41b300eb989e6ebb2da5f4c8a85b74162f085e09fcda6c7c8347dc238b787ed14dd90801c18115d29e171ca442996c052696015
+  metadata.gz: a3dbe7e29ebf3299714c285c90fbf170c6fb8a41e028e9fe64216d411233505cb7bb0230369e82d1a71dd14829c1b0031a046fefd21b96f0589af82af34bba09
+  data.tar.gz: 3a9f8a328af8c39185dc607db7529da03596235aa194ac57ad2fcdf623b5aad7f4a54124f6926f727a79fd89e9872212b21027a8e707e48d7d7961f902c1b86f

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# cnpj-dv
+
+## 1.0.0
+
+### 🚀 Stable Version Released!
+
+Utility class to calculate check digits on CNPJ (Brazilian Business Tax ID). Main features:
+
+- **Flexible input**: Accepts a `String` or `Array` of strings (formatted or raw).
+- **Format agnostic**: Automatically strips non-alphanumeric characters and uppercases letters before processing.
+- **Alphanumeric CNPJ**: Supports letters `A–Z` in the base; check digits remain numeric via modulo-11.
+- **Lazy evaluation**: `CnpjDV::CnpjCheckDigits` computes `first`, `second`, `both`, and `cnpj` only on first access, then caches.
+- **Eligibility gates**: Rejects wrong types, invalid length, all-zero base/branch IDs, and repeated numeric digits.
+- **Error handling**: `CnpjCheckDigitsInputTypeError` (`TypeError`) plus length/invalid `StandardError` subclasses with structured attributes.
+- **Minimal dependencies**: Requires `lacus-utils` for reusable utilities.
+
+For detailed usage and API reference, see the [README](./README.md).

data/README.md

@@ -0,0 +1,223 @@
+cnpj-dv for Ruby
+
+[Gem Version](https://rubygems.org/gems/cnpj-dv)
+[Downloads Count](https://rubygems.org/gems/cnpj-dv)
+[Ruby Version](https://www.ruby-lang.org/)
+[Test Status](https://github.com/LacusSolutions/br-utils-ruby/actions)
+[Last Update Date](https://github.com/LacusSolutions/br-utils-ruby)
+[Project License](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE)
+
+> 🚀 **Full support for the [new alphanumeric CNPJ format](https://github.com/user-attachments/files/23937961/calculodvcnpjalfanaumerico.pdf).**
+
+> 🌎 [Acessar documentação em português](https://github.com/LacusSolutions/br-utils-ruby/blob/main/packages/cnpj-dv/README.pt.md)
+
+A Ruby utility to calculate check digits on CNPJ (Brazilian Business Tax ID).
+
+## Ruby Support
+
+
+| Ruby 3.2  | Ruby 3.3  | Ruby 3.4  |
+| --------- | --------- | --------- |
+| Passing ✔ | Passing ✔ | Passing ✔ |
+
+
+
+
+## Features
+
+- ✅ **Alphanumeric CNPJ**: Full support for the new alphanumeric CNPJ format (introduced in 2026)
+- ✅ **Flexible input**: Accepts `String` or `Array` of strings
+- ✅ **Format agnostic**: Strips non-alphanumeric characters from string input and uppercases letters
+- ✅ **Auto-expansion**: Multi-character strings in arrays are joined and parsed like a single string
+- ✅ **Input validation**: Rejects ineligible CNPJs (all-zero base ID `00000000`, all-zero branch `0000`, or 12 numeric-only repeated digits)
+- ✅ **Lazy evaluation**: Check digits are calculated only when accessed (via methods)
+- ✅ **Caching**: Calculated values are cached for subsequent access
+- ✅ **Minimal dependencies**: Only `[lacus-utils](https://rubygems.org/gems/lacus-utils)`
+- ✅ **Error handling**: Specific types for type, length, and invalid CNPJ scenarios (`TypeError` vs `StandardError` semantics)
+
+
+
+## Installation
+
+Install the gem directly:
+
+```bash
+gem install cnpj-dv
+```
+
+Or add it to your `Gemfile` and run `bundle install`:
+
+```ruby
+gem 'cnpj-dv'
+```
+
+
+
+## Require
+
+```ruby
+require 'cnpj-dv'
+```
+
+
+
+## Quick Start
+
+```ruby
+require 'cnpj-dv'
+
+check_digits = CnpjDV::CnpjCheckDigits.new('914157320007')
+
+check_digits.first   # => '9'
+check_digits.second  # => '3'
+check_digits.both    # => '93'
+check_digits.cnpj    # => '91415732000793'
+```
+
+With alphanumeric CNPJ (new format):
+
+```ruby
+require 'cnpj-dv'
+
+check_digits = CnpjDV::CnpjCheckDigits.new('MGKGMJ9X0001')
+
+check_digits.first   # => '6'
+check_digits.second  # => '8'
+check_digits.both    # => '68'
+check_digits.cnpj    # => 'MGKGMJ9X000168'
+```
+
+
+
+## Usage
+
+The main resource of this package is the class `CnpjDV::CnpjCheckDigits`. Through an instance, you access CNPJ check-digit information:
+
+- `initialize`: `CnpjDV::CnpjCheckDigits.new(cnpj_input)` — `cnpj_input` must be a `String` or an `Array` of strings. After sanitization, the value must have 12–14 alphanumeric characters (formatting stripped from strings; letters uppercased). Only the **first 12** characters are used as the base; if you pass 13 or 14 characters (e.g. a full CNPJ including prior check digits), characters 13–14 are **ignored** and the digits are recalculated. There are **no options**, keyword arguments, or configuration objects — the constructor takes only the CNPJ input.
+- `first`: First check digit (13th character of the full CNPJ). Lazy, cached.
+- `second`: Second check digit (14th character of the full CNPJ). Lazy, cached.
+- `both`: Both check digits concatenated as a string.
+- `cnpj`: The complete CNPJ as a string of 14 characters (12 base characters + 2 check digits).
+
+
+
+### Input formats
+
+The `CnpjCheckDigits` class accepts multiple input formats:
+
+**String input:** raw digits and/or letters, or formatted CNPJ (e.g. `91.415.732/0007-93`, `MG.KGM.J9X/0001-68`). Non-alphanumeric characters are removed; lowercase letters are uppercased.
+
+**Array of strings:** each element must be a string; values are concatenated and then parsed like a single string (e.g. `['9','1','4',…]`, `['9141','5732','0007']`, `['MG','KGM','J9X','0001']`). Non-string elements are not allowed.
+
+```ruby
+require 'cnpj-dv'
+
+# String — plain, formatted, or with existing check digits (only first 12 chars used)
+CnpjDV::CnpjCheckDigits.new('914157320007')
+CnpjDV::CnpjCheckDigits.new('91.415.732/0007')
+CnpjDV::CnpjCheckDigits.new('91415732000793')
+
+# Array of strings — single- or multi-character elements
+CnpjDV::CnpjCheckDigits.new(%w[9 1 4 1 5 7 3 2 0 0 0 7])
+CnpjDV::CnpjCheckDigits.new(%w[9141 5732 0007])
+CnpjDV::CnpjCheckDigits.new(%w[MG KGM J9X 0001])
+```
+
+
+
+### Errors & exceptions handling
+
+This package uses **TypeError vs StandardError** semantics: *type errors* indicate incorrect API use (e.g. wrong type); *exceptions* indicate invalid or ineligible data (e.g. invalid length or business rules). You can rescue specific classes or use the base classes.
+
+- `CnpjDV::CnpjCheckDigitsTypeError` — base class for type errors; extends Ruby’s `TypeError`
+- `CnpjDV::CnpjCheckDigitsInputTypeError` — input is not `String` or `Array` of strings (or array contains a non-string element)
+- `CnpjDV::CnpjCheckDigitsException` — base class for data/flow exceptions; extends `StandardError`
+- `CnpjDV::CnpjCheckDigitsInputLengthException` — sanitized length is not 12–14
+- `CnpjDV::CnpjCheckDigitsInputInvalidException` — base ID `00000000`, branch ID `0000`, or 12 identical numeric digits (repeated-digit pattern)
+
+```ruby
+require 'cnpj-dv'
+
+# Input type (e.g. integer not allowed)
+begin
+  CnpjDV::CnpjCheckDigits.new(12_345_678_000_100)
+rescue CnpjDV::CnpjCheckDigitsInputTypeError => e
+  puts e.message
+  # => CNPJ input must be of type string or string[]. Got integer number.
+end
+
+# Length (must be 12–14 alphanumeric characters after sanitization)
+begin
+  CnpjDV::CnpjCheckDigits.new('12345678901')
+rescue CnpjDV::CnpjCheckDigitsInputLengthException => e
+  puts e.message
+  # => CNPJ input "12345678901" does not contain 12 to 14 characters. Got 11.
+end
+
+# Invalid (e.g. all-zero base or branch, or repeated numeric digits)
+begin
+  CnpjDV::CnpjCheckDigits.new('000000000001')
+rescue CnpjDV::CnpjCheckDigitsInputInvalidException => e
+  puts e.message
+  # => CNPJ input "000000000001" is invalid. Base ID "00000000" is not eligible.
+end
+
+# Any data exception from the package
+begin
+  CnpjDV::CnpjCheckDigits.new('000000000001')
+rescue CnpjDV::CnpjCheckDigitsException => e
+  puts e.message
+end
+```
+
+Notable attributes on raised errors:
+
+- `CnpjCheckDigitsInputTypeError`: `actual_input`, `actual_type`, `expected_type`
+- `CnpjCheckDigitsInputLengthException`: `actual_input`, `evaluated_input`, `min_expected_length`, `max_expected_length`
+- `CnpjCheckDigitsInputInvalidException`: `actual_input`, `reason`
+
+
+
+### Other available resources
+
+After `require 'cnpj-dv'`:
+
+- `CnpjDV::CNPJ_MIN_LENGTH`: `12`
+- `CnpjDV::CNPJ_MAX_LENGTH`: `14`
+- **Exceptions**: see above
+
+
+
+## Calculation algorithm
+
+The package computes check digits with the official Brazilian modulo-11 rules extended to alphanumeric characters:
+
+1. **Character value:** each character contributes `ord(character) − 48` (so `0`–`9` stay 0–9; letters use their ASCII offset from `0`).
+2. **Weights:** from **right to left**, multiply by weights that cycle **2, 3, 4, 5, 6, 7, 8, 9**, then repeat from 2.
+3. **First check digit (13th position):** apply steps 1–2 to the first **12** base characters; let `r = sum % 11`. The digit is `0` if `r < 2`, otherwise `11 − r`.
+4. **Second check digit (14th position):** apply steps 1–2 to the first 12 characters **plus** the first check digit; same formula for `r`.
+
+
+
+## Contribution & Support
+
+We welcome contributions! Please see our [Contributing Guidelines](https://github.com/LacusSolutions/br-utils-ruby/blob/main/CONTRIBUTING.md) for details. If you find this project helpful, please consider:
+
+- ⭐ Starring the repository
+- 🤝 Contributing to the codebase
+- 💡 [Suggesting new features](https://github.com/LacusSolutions/br-utils-ruby/issues)
+- 🐛 [Reporting bugs](https://github.com/LacusSolutions/br-utils-ruby/issues)
+
+
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE) file for details.
+
+## Changelog
+
+See [CHANGELOG](./CHANGELOG.md) for a list of changes and version history.
+
+---
+
+Made with ❤️ by [Lacus Solutions](https://github.com/LacusSolutions)

data/README.pt.md

@@ -0,0 +1,186 @@
+![cnpj-dv para Ruby](https://br-utils.vercel.app/img/cover_cnpj-dv.jpg)
+
+> 🚀 **Suporte total ao [novo formato alfanumérico de CNPJ](https://github.com/user-attachments/files/23937961/calculodvcnpjalfanaumerico.pdf).**
+
+> 🌎 [Access documentation in English](https://github.com/LacusSolutions/br-utils-ruby/blob/main/packages/cnpj-dv/README.md)
+
+Utilitário em Ruby para calcular os dígitos verificadores de CNPJ (Cadastro Nacional da Pessoa Jurídica).
+
+## Recursos
+
+- ✅ **CNPJ alfanumérico**: Suporte completo ao novo formato alfanumérico de CNPJ (a partir de 2026)
+- ✅ **Entrada flexível**: Aceita `String` ou `Array` de strings
+- ✅ **Agnóstico ao formato**: Remove caracteres não alfanuméricos da entrada em string e converte letras para maiúsculas
+- ✅ **Junção em array**: Strings com vários caracteres em arrays são concatenadas e interpretadas como uma única sequência
+- ✅ **Validação de entrada**: Rejeita CNPJs inelegíveis (base toda zero `00000000`, filial `0000`, ou 12 dígitos numéricos repetidos)
+- ✅ **Avaliação lazy**: Dígitos verificadores são calculados apenas quando acessados (via métodos)
+- ✅ **Cache**: Valores calculados são armazenados em cache para acessos subsequentes
+- ✅ **Dependências mínimas**: Apenas [`lacus-utils`](https://rubygems.org/gems/lacus-utils)
+- ✅ **Tratamento de erros**: Tipos específicos para tipo, tamanho e CNPJ inválido (semântica `TypeError` vs `StandardError`)
+
+## Instalação
+
+Instale a gem diretamente:
+
+```bash
+gem install cnpj-dv
+```
+
+Ou adicione ao seu `Gemfile` e execute `bundle install`:
+
+```ruby
+gem 'cnpj-dv'
+```
+
+## Require
+
+```ruby
+require 'cnpj-dv'
+```
+
+## Início rápido
+
+```ruby
+require 'cnpj-dv'
+
+check_digits = CnpjDV::CnpjCheckDigits.new('914157320007')
+
+check_digits.first   # => '9'
+check_digits.second  # => '3'
+check_digits.both    # => '93'
+check_digits.cnpj    # => '91415732000793'
+```
+
+Com CNPJ alfanumérico (novo formato):
+
+```ruby
+require 'cnpj-dv'
+
+check_digits = CnpjDV::CnpjCheckDigits.new('MGKGMJ9X0001')
+
+check_digits.first   # => '6'
+check_digits.second  # => '8'
+check_digits.both    # => '68'
+check_digits.cnpj    # => 'MGKGMJ9X000168'
+```
+
+## Utilização
+
+O principal recurso deste pacote é a classe `CnpjDV::CnpjCheckDigits`. Por meio da instância, você acessa as informações dos dígitos verificadores do CNPJ:
+
+- **`initialize`**: `CnpjDV::CnpjCheckDigits.new(cnpj_input)` — `cnpj_input` deve ser `String` ou `Array` de strings. Após a sanitização, o valor deve ter 12–14 caracteres alfanuméricos (formatação removida em strings; letras em maiúsculas). Apenas os **primeiros 12** caracteres entram como base; com 13 ou 14 caracteres (ex.: CNPJ completo com DV anteriores), os caracteres 13 e 14 são **ignorados** e os dígitos são recalculados. Não há **opções**, argumentos nomeados nem objeto de configuração — o construtor recebe apenas a entrada de CNPJ.
+- **`first`**: Primeiro dígito verificador (13º caractere do CNPJ completo). Lazy, em cache.
+- **`second`**: Segundo dígito verificador (14º caractere do CNPJ completo). Lazy, em cache.
+- **`both`**: Ambos os dígitos verificadores concatenados em uma string.
+- **`cnpj`**: O CNPJ completo como string de 14 caracteres (12 da base + 2 dígitos verificadores).
+
+### Formatos de entrada
+
+A classe `CnpjCheckDigits` aceita múltiplos formatos de entrada:
+
+**String:** dígitos e/ou letras crus, ou CNPJ formatado (ex.: `91.415.732/0007-93`, `MG.KGM.J9X/0001-68`). Caracteres não alfanuméricos são removidos; letras minúsculas viram maiúsculas.
+
+**Array de strings:** cada elemento deve ser string; os valores são concatenados e interpretados como uma única string (ex.: `['9','1','4',…]`, `['9141','5732','0007']`, `['MG','KGM','J9X','0001']`). Elementos que não são strings não são permitidos.
+
+```ruby
+require 'cnpj-dv'
+
+# String — crua, formatada ou com DV existentes (apenas os 12 primeiros caracteres são usados)
+CnpjDV::CnpjCheckDigits.new('914157320007')
+CnpjDV::CnpjCheckDigits.new('91.415.732/0007')
+CnpjDV::CnpjCheckDigits.new('91415732000793')
+
+# Array de strings — elementos de um ou vários caracteres
+CnpjDV::CnpjCheckDigits.new(%w[9 1 4 1 5 7 3 2 0 0 0 7])
+CnpjDV::CnpjCheckDigits.new(%w[9141 5732 0007])
+CnpjDV::CnpjCheckDigits.new(%w[MG KGM J9X 0001])
+```
+
+### Erros e exceções
+
+Este pacote usa a distinção **TypeError vs StandardError**: *erros de tipo* indicam uso incorreto da API (ex.: tipo errado); *exceções* indicam dados inválidos ou inelegíveis (ex.: tamanho ou regras de negócio). Você pode resgatar classes específicas ou as classes base.
+
+- **`CnpjDV::CnpjCheckDigitsTypeError`** — classe base para erros de tipo; estende o `TypeError` do Ruby
+- **`CnpjDV::CnpjCheckDigitsInputTypeError`** — entrada não é `String` nem `Array` de strings (ou o array contém elemento que não é string)
+- **`CnpjDV::CnpjCheckDigitsException`** — classe base para exceções de dados/fluxo; estende `StandardError`
+- **`CnpjDV::CnpjCheckDigitsInputLengthException`** — tamanho após sanitização não é 12–14
+- **`CnpjDV::CnpjCheckDigitsInputInvalidException`** — base `00000000`, filial `0000`, ou 12 dígitos numéricos idênticos (padrão de repetição)
+
+```ruby
+require 'cnpj-dv'
+
+# Tipo de entrada (ex.: inteiro não permitido)
+begin
+  CnpjDV::CnpjCheckDigits.new(12_345_678_000_100)
+rescue CnpjDV::CnpjCheckDigitsInputTypeError => e
+  puts e.message
+  # => CNPJ input must be of type string or string[]. Got integer number.
+end
+
+# Tamanho (deve ser 12–14 caracteres alfanuméricos após sanitização)
+begin
+  CnpjDV::CnpjCheckDigits.new('12345678901')
+rescue CnpjDV::CnpjCheckDigitsInputLengthException => e
+  puts e.message
+  # => CNPJ input "12345678901" does not contain 12 to 14 characters. Got 11.
+end
+
+# Inválido (ex.: base ou filial zeradas, ou dígitos numéricos repetidos)
+begin
+  CnpjDV::CnpjCheckDigits.new('000000000001')
+rescue CnpjDV::CnpjCheckDigitsInputInvalidException => e
+  puts e.message
+  # => CNPJ input "000000000001" is invalid. Base ID "00000000" is not eligible.
+end
+
+# Qualquer exceção de dados do pacote
+begin
+  CnpjDV::CnpjCheckDigits.new('000000000001')
+rescue CnpjDV::CnpjCheckDigitsException => e
+  puts e.message
+end
+```
+
+Atributos relevantes nos erros:
+
+- `CnpjCheckDigitsInputTypeError`: `actual_input`, `actual_type`, `expected_type`
+- `CnpjCheckDigitsInputLengthException`: `actual_input`, `evaluated_input`, `min_expected_length`, `max_expected_length`
+- `CnpjCheckDigitsInputInvalidException`: `actual_input`, `reason`
+
+### Outros recursos disponíveis
+
+Após `require 'cnpj-dv'`:
+
+- **`CnpjDV::CNPJ_MIN_LENGTH`**: `12`
+- **`CnpjDV::CNPJ_MAX_LENGTH`**: `14`
+- **Exceções**: veja acima
+
+## Algoritmo de cálculo
+
+O pacote calcula os dígitos verificadores com as regras oficiais brasileiras de módulo 11 estendidas a caracteres alfanuméricos:
+
+1. **Valor do caractere:** cada caractere contribui com `ord(caractere) − 48` (assim `0`–`9` permanecem 0–9; letras usam o deslocamento ASCII em relação a `0`).
+2. **Pesos:** da **direita para a esquerda**, multiplicar pelos pesos que ciclam **2, 3, 4, 5, 6, 7, 8, 9** e voltam a 2.
+3. **Primeiro dígito verificador (13ª posição):** aplicar os itens 1–2 aos **primeiros 12** caracteres da base; seja `r = soma % 11`. O dígito é `0` se `r < 2`, senão `11 − r`.
+4. **Segundo dígito verificador (14ª posição):** aplicar os itens 1–2 aos 12 primeiros caracteres **mais** o primeiro dígito verificador; mesma fórmula para `r`.
+
+## Contribuição e suporte
+
+Contribuições são bem-vindas! Consulte as [Diretrizes de contribuição](https://github.com/LacusSolutions/br-utils-ruby/blob/main/CONTRIBUTING.md). Se o projeto for útil para você, considere:
+
+- ⭐ Dar uma estrela no repositório
+- 🤝 Contribuir com código
+- 💡 [Sugerir novas funcionalidades](https://github.com/LacusSolutions/br-utils-ruby/issues)
+- 🐛 [Reportar bugs](https://github.com/LacusSolutions/br-utils-ruby/issues)
+
+## Licença
+
+Este projeto está sob a licença MIT — veja o arquivo [LICENSE](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE).
+
+## Changelog
+
+Veja o [CHANGELOG](./CHANGELOG.md) para alterações e histórico de versões.
+
+---
+
+Feito com ❤️ por [Lacus Solutions](https://github.com/LacusSolutions)

data/src/cnpj-dv/cnpj_check_digits.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative 'exceptions'
+
+module CnpjDV
+  # Minimum number of characters required for the CNPJ check digits calculation.
+  CNPJ_MIN_LENGTH = 12
+
+  # Maximum number of characters accepted as input for the CNPJ check digits
+  # calculation.
+  CNPJ_MAX_LENGTH = 14
+
+  CNPJ_BASE_ID_LENGTH = 8
+  CNPJ_INVALID_BASE_ID = '0' * CNPJ_BASE_ID_LENGTH
+  CNPJ_BRANCH_ID_LENGTH = 4
+  CNPJ_INVALID_BRANCH_ID = '0' * CNPJ_BRANCH_ID_LENGTH
+
+  DELTA_FACTOR = '0'.ord
+  WEIGHTS = [2, 3, 4, 5, 6, 7, 8, 9].freeze
+  DIGIT_CHARS = '0123456789'
+
+  private_constant :CNPJ_BASE_ID_LENGTH, :CNPJ_INVALID_BASE_ID,
+                   :CNPJ_BRANCH_ID_LENGTH, :CNPJ_INVALID_BRANCH_ID,
+                   :DELTA_FACTOR, :WEIGHTS, :DIGIT_CHARS
+
+  # Calculates and exposes CNPJ check digits from a valid base input.
+  #
+  # Validates length, base ID, branch ID and rejects repeated numeric digits.
+  #
+  # @example Numeric base
+  #   check_digits = CnpjDV::CnpjCheckDigits.new('914157320007')
+  #   check_digits.first   # => '9'
+  #   check_digits.second  # => '3'
+  #   check_digits.both    # => '93'
+  #   check_digits.cnpj    # => '91415732000793'
+  #
+  # @example Alphanumeric base
+  #   check_digits = CnpjDV::CnpjCheckDigits.new('MGKGMJ9X0001')
+  #   check_digits.first   # => '6'
+  #   check_digits.second  # => '8'
+  #   check_digits.both    # => '68'
+  #   check_digits.cnpj    # => 'MGKGMJ9X000168'
+  class CnpjCheckDigits
+    # Creates a calculator for the given CNPJ base (12 to 14 characters).
+    #
+    # @param cnpj_input [String, Array<String>] alphanumeric CNPJ with or without
+    #   formatting, or an array of strings
+    # @raise [CnpjCheckDigitsInputTypeError] when input is not a +String+ or
+    #   +Array<String>+
+    # @raise [CnpjCheckDigitsInputLengthException] when character count is not
+    #   between 12 and 14
+    # @raise [CnpjCheckDigitsInputInvalidException] when base ID is all zero
+    #   (+00.000.000+), branch ID is all zero (+0000+) or all digits are numeric
+    #   the same (repeated digits, e.g. +77.777.777/7777-...+)
+    def initialize(cnpj_input)
+      parsed_input = parse_input(cnpj_input)
+
+      validate_length(parsed_input, cnpj_input)
+      validate_base_id(parsed_input, cnpj_input)
+      validate_branch_id(parsed_input, cnpj_input)
+      validate_non_repeated_digits(parsed_input, cnpj_input)
+
+      @cnpj_chars = parsed_input[0, CNPJ_MIN_LENGTH]
+      @cached_first_digit = nil
+      @cached_second_digit = nil
+    end
+
+    # First check digit (13th character of the full CNPJ).
+    #
+    # @return [String] a single numeric character (+"0"+–+"9"+)
+    def first
+      @cached_first_digit = _calculate(@cnpj_chars) if @cached_first_digit.nil?
+
+      DIGIT_CHARS[@cached_first_digit]
+    end
+
+    # Second check digit (14th character of the full CNPJ).
+    #
+    # @return [String] a single numeric character (+"0"+–+"9"+)
+    def second
+      @cached_second_digit = _calculate([*@cnpj_chars, first]) if @cached_second_digit.nil?
+
+      DIGIT_CHARS[@cached_second_digit]
+    end
+
+    # Both check digits concatenated (13th and 14th characters).
+    #
+    # @return [String] two-character numeric string
+    def both
+      first + second
+    end
+
+    # Full 14-character CNPJ (base 12 characters concatenated with the 2 check
+    # digits).
+    #
+    # @return [String] 14-character CNPJ (base may contain letters + numeric DVs)
+    def cnpj
+      @cnpj_chars.join + both
+    end
+
+    # Protected (not private) so test spy subclasses can override and call +super+.
+    # Leading underscore matches the cross-language helper name (`_calculate`).
+    protected
+
+    # Computes a single check digit using the standard CNPJ modulo-11 algorithm.
+    #
+    # @param cnpj_sequence [Array<String>] characters used in the weighted sum
+    # @return [Integer] check digit in the range 0–9
+    def _calculate(cnpj_sequence)
+      length = cnpj_sequence.length
+      sum_result = 0
+
+      (length - 1).downto(0) do |index|
+        char_value = cnpj_sequence[index].ord - DELTA_FACTOR
+        sum_result += char_value * WEIGHTS[(length - 1 - index) % 8]
+      end
+
+      remainder = sum_result % 11
+
+      remainder < 2 ? 0 : 11 - remainder
+    end
+
+    private
+
+    # Parses a string or an array of strings into alphanumeric characters.
+    #
+    # @param cnpj_input [Object] candidate CNPJ input
+    # @return [Array<String>] uppercase alphanumeric characters
+    # @raise [CnpjCheckDigitsInputTypeError] when input is not a +String+ or
+    #   +Array<String>+
+    def parse_input(cnpj_input)
+      return parse_string_input(cnpj_input) if cnpj_input.is_a?(String)
+      return parse_array_input(cnpj_input) if cnpj_input.is_a?(Array)
+
+      raise CnpjCheckDigitsInputTypeError.new(cnpj_input, 'string or string[]')
+    end
+
+    # Strips non-alphanumeric characters and uppercases the remainder.
+    #
+    # @param cnpj_string [String] raw or formatted CNPJ string
+    # @return [Array<String>] uppercase alphanumeric characters
+    def parse_string_input(cnpj_string)
+      result = []
+
+      cnpj_string.each_char do |char|
+        code = char.ord
+        if code.between?(48, 57) || code.between?(65, 90)
+          result << char
+        elsif code.between?(97, 122)
+          result << (code - 32).chr
+        end
+      end
+
+      result
+    end
+
+    # Concatenates an array of strings and normalizes the result.
+    #
+    # @param cnpj_array [Array] candidate array of string chunks
+    # @return [Array<String>] uppercase alphanumeric characters
+    # @raise [CnpjCheckDigitsInputTypeError] when input is not a +String+ or
+    #   +Array<String>+
+    def parse_array_input(cnpj_array)
+      return [] if cnpj_array.empty?
+
+      raise CnpjCheckDigitsInputTypeError.new(cnpj_array, 'string or string[]') unless cnpj_array.all?(String)
+
+      parse_string_input(cnpj_array.join)
+    end
+
+    # Ensures character count is between {CNPJ_MIN_LENGTH} and
+    # {CNPJ_MAX_LENGTH}.
+    #
+    # @param cnpj_chars [Array<String>] normalized characters
+    # @param original_input [String, Array<String>] original caller input
+    # @raise [CnpjCheckDigitsInputLengthException] when character count is not
+    #   between 12 and 14
+    def validate_length(cnpj_chars, original_input)
+      chars_count = cnpj_chars.length
+
+      return if chars_count.between?(CNPJ_MIN_LENGTH, CNPJ_MAX_LENGTH)
+
+      raise CnpjCheckDigitsInputLengthException.new(
+        original_input,
+        cnpj_chars.join,
+        CNPJ_MIN_LENGTH,
+        CNPJ_MAX_LENGTH
+      )
+    end
+
+    # Rejects base ID (first 8 digits) when it is all zeros.
+    #
+    # @param cnpj_chars [Array<String>] normalized characters
+    # @param original_input [String, Array<String>] original caller input
+    # @raise [CnpjCheckDigitsInputInvalidException] when base ID is all zeros
+    #   (+00.000.000+)
+    def validate_base_id(cnpj_chars, original_input)
+      return unless cnpj_chars[0, CNPJ_BASE_ID_LENGTH].all? { |char| char == '0' }
+
+      raise CnpjCheckDigitsInputInvalidException.new(
+        original_input,
+        "Base ID \"#{CNPJ_INVALID_BASE_ID}\" is not eligible."
+      )
+    end
+
+    # Rejects branch ID (digits 9–12) when it is all zeros.
+    #
+    # @param cnpj_chars [Array<String>] normalized characters
+    # @param original_input [String, Array<String>] original caller input
+    # @raise [CnpjCheckDigitsInputInvalidException] when branch ID is all zeros
+    #   (+0000+)
+    def validate_branch_id(cnpj_chars, original_input)
+      branch_start = CNPJ_BASE_ID_LENGTH
+      branch_end = branch_start + CNPJ_BRANCH_ID_LENGTH
+      branch_id = cnpj_chars[branch_start...branch_end]
+
+      return unless branch_id.all? { |char| char == '0' }
+
+      raise CnpjCheckDigitsInputInvalidException.new(
+        original_input,
+        "Branch ID \"#{CNPJ_INVALID_BRANCH_ID}\" is not eligible."
+      )
+    end
+
+    # Rejects inputs where all first 12 characters are the same numeric digit.
+    #
+    # @param cnpj_chars [Array<String>] normalized characters
+    # @param original_input [String, Array<String>] original caller input
+    # @raise [CnpjCheckDigitsInputInvalidException] when all digits are numeric
+    #   the same (repeated digits, e.g. +77.777.777/7777-...+)
+    def validate_non_repeated_digits(cnpj_chars, original_input)
+      first_char = cnpj_chars[0]
+      return unless first_char.match?(/\A\d\z/)
+      return unless cnpj_chars[1, CNPJ_MIN_LENGTH - 1].all? { |char| char == first_char }
+
+      raise CnpjCheckDigitsInputInvalidException.new(
+        original_input,
+        'Repeated digits are not considered valid.'
+      )
+    end
+  end
+end

data/src/cnpj-dv/exceptions.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'lacus-utils'
+
+module CnpjDV
+  # Formats the original input for inclusion in an exception message.
+  module FormatActualInput
+    module_function
+
+    # @param actual_input [Object] the original input value
+    # @return [String] a quoted string, or compact JSON for arrays
+    def call(actual_input)
+      return "\"#{actual_input}\"" if actual_input.is_a?(String)
+
+      JSON.generate(actual_input)
+    end
+  end
+  private_constant :FormatActualInput
+
+  # Base error for all `cnpj-dv` type-related errors.
+  #
+  # This class extends the native {TypeError} and serves as the base for all
+  # type validation errors in {CnpjCheckDigits}.
+  class CnpjCheckDigitsTypeError < TypeError
+    # @return [Object] the offending input value
+    attr_reader :actual_input
+
+    # @return [String] human-readable type of {#actual_input}
+    attr_reader :actual_type
+
+    # @return [String] description of the expected type
+    attr_reader :expected_type
+
+    # @param actual_input [Object] the offending input value
+    # @param actual_type [String] human-readable type of +actual_input+
+    # @param expected_type [String] description of the expected type
+    # @param message [String] error message
+    def initialize(actual_input, actual_type, expected_type, message)
+      super(message)
+      @actual_input = actual_input
+      @actual_type = actual_type
+      @expected_type = expected_type
+    end
+  end
+
+  # Error raised when the input provided to {CnpjCheckDigits} is not of the
+  # expected type (+String+ or +Array<String>+). The error message includes both
+  # the actual type of the input and the expected type.
+  class CnpjCheckDigitsInputTypeError < CnpjCheckDigitsTypeError
+    # @param actual_input [Object] the offending input value (the whole array when
+    #   a non-string element is found)
+    # @param expected_type [String] description of the expected type (e.g.
+    #   +"string or string[]"+)
+    def initialize(actual_input, expected_type)
+      actual_type = LacusUtils.describe_type(actual_input)
+
+      super(
+        actual_input,
+        actual_type,
+        expected_type,
+        "CNPJ input must be of type #{expected_type}. Got #{actual_type}."
+      )
+    end
+  end
+
+  # Base exception for all `cnpj-dv` rules-related errors.
+  #
+  # This class extends the native {StandardError} and serves as the base for all
+  # non-type-related errors in {CnpjCheckDigits}. It is suitable for validation
+  # errors, range errors, and other business logic exceptions that are not
+  # strictly type-related.
+  class CnpjCheckDigitsException < StandardError
+  end
+
+  # Error raised when the input (after optional processing) does not have the
+  # required length to calculate the check digits. A valid CNPJ input must
+  # contain between 12 and 14 alphanumeric characters. The error message
+  # distinguishes between the original input and the evaluated one (which strips
+  # punctuation characters).
+  class CnpjCheckDigitsInputLengthException < CnpjCheckDigitsException
+    # @return [String, Array<String>] the original input
+    attr_reader :actual_input
+
+    # @return [String] the normalized alphanumeric string
+    attr_reader :evaluated_input
+
+    # @return [Integer] minimum expected length (12)
+    attr_reader :min_expected_length
+
+    # @return [Integer] maximum expected length (14)
+    attr_reader :max_expected_length
+
+    # @param actual_input [String, Array<String>] the original input
+    # @param evaluated_input [String] the normalized alphanumeric string
+    # @param min_expected_length [Integer] minimum expected length
+    # @param max_expected_length [Integer] maximum expected length
+    def initialize(actual_input, evaluated_input, min_expected_length, max_expected_length)
+      super(build_message(actual_input, evaluated_input, min_expected_length, max_expected_length))
+      @actual_input = actual_input
+      @evaluated_input = evaluated_input
+      @min_expected_length = min_expected_length
+      @max_expected_length = max_expected_length
+    end
+
+    private
+
+    def build_message(actual_input, evaluated_input, min_len, max_len)
+      fmt_actual = FormatActualInput.call(actual_input)
+      fmt_evaluated =
+        if actual_input == evaluated_input
+          evaluated_input.length.to_s
+        else
+          "#{evaluated_input.length} in \"#{evaluated_input}\""
+        end
+
+      "CNPJ input #{fmt_actual} does not contain #{min_len} to #{max_len} characters. " \
+        "Got #{fmt_evaluated}."
+    end
+  end
+
+  # Exception raised when the CNPJ input contains invalid character sequences,
+  # like all digits are repeated. This is a business logic exception and it is
+  # highly recommended that users of the library catch it and handle it
+  # appropriately.
+  class CnpjCheckDigitsInputInvalidException < CnpjCheckDigitsException
+    # @return [String, Array<String>] the original input
+    attr_reader :actual_input
+
+    # @return [String] human-readable reason why the input is invalid
+    attr_reader :reason
+
+    # @param actual_input [String, Array<String>] the original input
+    # @param reason [String] human-readable reason why the input is invalid
+    def initialize(actual_input, reason)
+      super("CNPJ input #{FormatActualInput.call(actual_input)} is invalid. #{reason}")
+      @actual_input = actual_input
+      @reason = reason
+    end
+  end
+end

data/src/cnpj-dv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-module CnpjDv
-  VERSION = '0.0.1'
+module CnpjDV
+  VERSION = '1.0.0'
 end

data/src/cnpj-dv.rb

@@ -1,9 +1,29 @@
 # frozen_string_literal: true
 
 require_relative 'cnpj-dv/version'
+require_relative 'cnpj-dv/exceptions'
+require_relative 'cnpj-dv/cnpj_check_digits'
 
-module CnpjDv
-  def self.hello
-    'cnpj-dv'
-  end
+# Check-digit calculation for Brazilian CNPJ (numeric and alphanumeric formats).
+#
+# The package distinguishes between **errors** and **exceptions**:
+#
+# - {CnpjDV::CnpjCheckDigitsTypeError} (extends the native {TypeError})
+#   signals incorrect API usage (the input is of the wrong *type*).
+# - {CnpjDV::CnpjCheckDigitsException} (extends the native {StandardError})
+#   signals invalid or ineligible data (right type, bad value).
+#
+# Public API:
+#
+# - {CnpjDV::CnpjCheckDigits}
+# - {CnpjDV::CNPJ_MIN_LENGTH}, {CnpjDV::CNPJ_MAX_LENGTH}
+# - Exception hierarchy under {CnpjDV::CnpjCheckDigitsTypeError} /
+#   {CnpjDV::CnpjCheckDigitsException}
+#
+# @example
+#   require 'cnpj-dv'
+#
+#   check_digits = CnpjDV::CnpjCheckDigits.new('914157320007')
+#   check_digits.cnpj # => '91415732000793'
+module CnpjDV
 end

metadata

@@ -1,28 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: cnpj-dv
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Julio L. Muller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-07 00:00:00.000000000 Z
-dependencies: []
-description:
+date: 2026-07-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lacus-utils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+description: Utility to calculate check digits on CNPJ (Brazilian Business Tax ID)
 email:
+- juliolmuller@outlook.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
+- README.md
+- README.pt.md
 - src/cnpj-dv.rb
+- src/cnpj-dv/cnpj_check_digits.rb
+- src/cnpj-dv/exceptions.rb
 - src/cnpj-dv/version.rb
 homepage: https://github.com/LacusSolutions/br-utils-ruby
 licenses:
 - MIT
 metadata:
+  source_code_uri: https://github.com/LacusSolutions/br-utils-ruby
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -32,7 +59,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -42,5 +69,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Check-digit calculation for CNPJ (Brazilian company ID)
+summary: Check-digit calculation for CNPJ (Brazilian Business Tax ID)
 test_files: []