cnpj-dv 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e41c3c9ce1d2a8c96fe2c35183bb28dcaf629590313a5d769b2fe18d6f3a97c3
-  data.tar.gz: f9b596418d1be76f103142bde7675ea23ce6c2ca588d4acc176419e7e901072f
+  metadata.gz: 589e0576ee9e9cc2ddfeaf94c5f745792880885d7ea8dfcfb0953695b32a8981
+  data.tar.gz: 6662f13dfc238ea843cb79b14d1aaaf526c311e31f63dfc47937846a82ea3a2f
 SHA512:
-  metadata.gz: a3c72b3f1757dca405986fbd44232620cdf6cd3bb200c26f3b2a7121b7b7a917aa1432afc0770bdba46a395b56cbfd712c13f6186f9329f7274729912e98b7db
-  data.tar.gz: b495d166c64353bf05c6a4c9dcbd351646eb360021fde40f4cf85b9a70412d8b2390249106e2c80cfa15bfe70f9bf69fd691fff68e15a648b2774bc436c9f8bb
+  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/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Julio L. Muller
+
+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,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.0'
+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,27 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: cnpj-dv
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Julio L. Muller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-04 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: []
@@ -31,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:
   - - ">="
@@ -41,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: []