cnpj-dv 0.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4715b7cec54902ddb19fba13cb6ed707dfe47aa621857a61ca0fe8beacf3ac70
-  data.tar.gz: bee5b04815a43097528464af159dbdbb54a6288c8f3e2491ff585dd0467ca4c1
+  metadata.gz: 8d6109a8bd760c61186dc99ec5503bb42880d9ebb3c19745962ba5a0d97c6cfc
+  data.tar.gz: 47242e1f246d23ebab4d8c3be97d7d7b46060c974e011ad0412a93595fb69767
 SHA512:
-  metadata.gz: 103dfbad0358767ffd771c187b336605672a0d3e7e9633a3c98e143c3a6717f735a46eb1de466f709e77d3abb94bb65cd791892a475ab9940ff2b62705324752
-  data.tar.gz: faa45d622b815d48d6b51d95e41b300eb989e6ebb2da5f4c8a85b74162f085e09fcda6c7c8347dc238b787ed14dd90801c18115d29e171ca442996c052696015
+  metadata.gz: 85686458b90a155cf2263ef4517f66732efbead21d29cc6683827ad2fae6a0f6e3949b17bbbbd2cd1a842c5cd1ff57a827e6ec1b10bc8cdb451d910ab954f383
+  data.tar.gz: 11dbfd7b80b6f25695678bc0a5e8804b08ae17fbbc7cf24aea2071f717092ebbc4e79db8945ed66d02bceef6e5f4ea467a8e7cd65c679c02381b087fd751b921

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# cnpj-dv
+
+## 2.0.0
+
+### 🎉 v2 at a glance 🎊
+
+- **Error hierarchy**: Aligns with the monorepo standard — API misuse vs domain errors, `CnpjDV::Error` marker, and native-compatible rescue.
+
+### BREAKING CHANGES
+
+- **Error classes**: Removed `CnpjCheckDigitsTypeError`, `CnpjCheckDigitsInputTypeError`, `CnpjCheckDigitsException`, `CnpjCheckDigitsInputLengthException`, and `CnpjCheckDigitsInputInvalidException`.
+- **Migration map**: `InputTypeError` → `TypeMismatchError`; `InputLengthException` → `InvalidLengthError`; `InputInvalidException` → `ValidationError`.
+- **Rescue targets**: `rescue CnpjCheckDigitsException` no longer applies; use `rescue CnpjDV::Error` for a library-wide catch, or `rescue DomainError` for `InvalidLengthError` and `ValidationError`.
+- **Docs**: READMEs now document misuse vs domain categories, per-class rescue guidance, and four rescue granularity levels — see [README](./README.md).
+
+## 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,306 @@
+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**: API misuse vs domain errors with a `CnpjDV::Error` marker for library-wide rescue
+
+
+
+## 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])
+```
+
+
+
+### Error handling
+
+Errors fall into two categories:
+
+| Category | Meaning |
+|---|---|
+| **API misuse** | The caller invoked the library incorrectly (wrong type). Detectable from the call shape. |
+| **Domain error** | The call was structurally correct, but a value violates a business rule (length, eligibility, format). |
+
+Every custom error includes the `CnpjDV::Error` marker module. Domain failures (`InvalidLengthError`, `ValidationError`) inherit from `CnpjDV::DomainError` (`RangeError`).
+
+#### Summary
+
+| Class | Inherits from | Category | Trigger condition |
+|---|---|---|---|
+| `CnpjDV::TypeMismatchError` | `TypeError` (+ `include Error`) | API misuse | Argument has the wrong data type |
+| `CnpjDV::InvalidLengthError` | `CnpjDV::DomainError` | Domain error | Sanitized length is not 12–14 |
+| `CnpjDV::ValidationError` | `CnpjDV::DomainError` | Domain error | Ineligible base/branch ID or repeated numeric digits |
+
+#### `CnpjDV::Error` (marker module)
+
+- **Inheritance:** module marker mixed into every library error via `include` (not a class).
+- **Category:** N/A (rescue target only) — not a failure mode by itself.
+- **When it is raised:** Never raised directly; included by every custom error the library raises.
+- **Example:** N/A
+- **How to rescue it:**
+
+```ruby
+rescue CnpjDV::Error
+  # everything this library raises
+```
+
+#### `CnpjDV::DomainError`
+
+- **Inheritance:** `CnpjDV::DomainError < RangeError` (includes `CnpjDV::Error`)
+- **Category:** Domain error — ancestor for numeric/length domain failures.
+- **When it is raised:** Not raised directly; prefer raising a leaf subclass.
+- **Example:** Prefer `raise CnpjDV::InvalidLengthError` over raising `DomainError` directly.
+- **How to rescue it:**
+
+```ruby
+rescue CnpjDV::DomainError
+  # InvalidLengthError, ValidationError, and any other DomainError subclass
+```
+
+#### `CnpjDV::TypeMismatchError`
+
+- **Inheritance:** `CnpjDV::TypeMismatchError < TypeError` (includes `CnpjDV::Error`)
+- **Category:** API misuse — the caller passed a value of the wrong type.
+- **When it is raised:** Raised when the CNPJ input is not a `String` or an `Array` of strings (or an array contains a non-string element).
+- **Example:**
+
+```ruby
+CnpjDV::CnpjCheckDigits.new(12_345_678_000_100) # raises CnpjDV::TypeMismatchError
+```
+
+- **How to rescue it:**
+
+```ruby
+rescue CnpjDV::TypeMismatchError
+  # this library's type-contract violation
+
+rescue TypeError
+  # native type errors, including this library's TypeMismatchError
+```
+
+#### `CnpjDV::InvalidLengthError`
+
+- **Inheritance:** `CnpjDV::InvalidLengthError < CnpjDV::DomainError < RangeError` (includes `CnpjDV::Error`)
+- **Category:** Domain error — a collection or string length violates a business rule.
+- **When it is raised:** Raised when the sanitized CNPJ input does not contain 12 to 14 alphanumeric characters.
+- **Example:**
+
+```ruby
+CnpjDV::CnpjCheckDigits.new('12345678901') # raises CnpjDV::InvalidLengthError
+```
+
+- **How to rescue it:**
+
+```ruby
+rescue CnpjDV::InvalidLengthError
+  # this exact length violation
+
+rescue CnpjDV::DomainError
+  # RangeError-rooted domain failures from this library
+```
+
+#### `CnpjDV::ValidationError`
+
+- **Inheritance:** `CnpjDV::ValidationError < CnpjDV::DomainError < RangeError` (includes `CnpjDV::Error`)
+- **Category:** Domain error — a value fails a non-numeric, non-length domain rule.
+- **When it is raised:** Raised when the base ID is `00000000`, the branch ID is `0000`, or the first 12 characters are the same numeric digit.
+- **Example:**
+
+```ruby
+CnpjDV::CnpjCheckDigits.new('000000000001') # raises CnpjDV::ValidationError
+```
+
+- **How to rescue it:**
+
+```ruby
+rescue CnpjDV::ValidationError
+  # this exact domain validation failure
+
+rescue CnpjDV::DomainError
+  # RangeError-rooted domain failures from this library
+```
+
+#### Rescue granularity
+
+```ruby
+# 1) Single native class — catches type misuse from this library (and other TypeErrors).
+rescue TypeError
+  # CnpjDV::TypeMismatchError and any other TypeError (library or not)
+
+# 2) CnpjDV::DomainError — catches business-rule violations under DomainError.
+rescue CnpjDV::DomainError
+  # CnpjDV::InvalidLengthError, CnpjDV::ValidationError, and other DomainError subclasses
+
+# 3) CnpjDV::Error — catches everything the library raises.
+rescue CnpjDV::Error
+  # every custom error that includes CnpjDV::Error
+
+# 4) Specific leaf class — catches only that exact failure mode.
+rescue CnpjDV::InvalidLengthError
+  # only CnpjDV::InvalidLengthError
+```
+
+Notable attributes on raised errors:
+
+- `TypeMismatchError`: `actual_input`, `actual_type`, `expected_type`
+- `InvalidLengthError`: `actual_input`, `evaluated_input`, `min_expected_length`, `max_expected_length`
+- `ValidationError`: `actual_input`, `reason`
+
+
+
+### Other available resources
+
+After `require 'cnpj-dv'`:
+
+- `CnpjDV::CNPJ_MIN_LENGTH`: `12`
+- `CnpjDV::CNPJ_MAX_LENGTH`: `14`
+- **Errors**: see above (`CnpjDV::Error`, `DomainError`, and raised leaves)
+
+
+
+## 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,269 @@
+![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**: Erros de uso da API vs erros de domínio, com o marcador `CnpjDV::Error` para resgate em nível de biblioteca
+
+## 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])
+```
+
+### Tratamento de erros
+
+Os erros se dividem em duas categorias:
+
+| Categoria | Significado |
+|---|---|
+| **Uso incorreto da API** | O chamador usou a biblioteca de forma incorreta (tipo errado). Detectável pela forma da chamada. |
+| **Erro de domínio** | A chamada estava estruturalmente correta, mas um valor viola uma regra de negócio (tamanho, elegibilidade, formato). |
+
+Todo erro customizado inclui o módulo marcador `CnpjDV::Error`. Falhas de domínio (`InvalidLengthError`, `ValidationError`) herdam de `CnpjDV::DomainError` (`RangeError`).
+
+#### Resumo
+
+| Classe | Herda de | Categoria | Condição de disparo |
+|---|---|---|---|
+| `CnpjDV::TypeMismatchError` | `TypeError` (+ `include Error`) | Uso incorreto da API | Argumento com tipo de dado incorreto |
+| `CnpjDV::InvalidLengthError` | `CnpjDV::DomainError` | Erro de domínio | Tamanho após sanitização não é 12–14 |
+| `CnpjDV::ValidationError` | `CnpjDV::DomainError` | Erro de domínio | Base/filial inelegível ou dígitos numéricos repetidos |
+
+#### `CnpjDV::Error` (módulo marcador)
+
+- **Herança:** módulo marcador misturado em todo erro da biblioteca via `include` (não é uma classe).
+- **Categoria:** N/A (apenas alvo de `rescue`) — não é um modo de falha por si só.
+- **Quando é levantado:** Nunca diretamente; incluído por todo erro customizado que a biblioteca levanta.
+- **Exemplo:** N/A
+- **Como resgatar:**
+
+```ruby
+rescue CnpjDV::Error
+  # tudo o que esta biblioteca levanta
+```
+
+#### `CnpjDV::DomainError`
+
+- **Herança:** `CnpjDV::DomainError < RangeError` (inclui `CnpjDV::Error`)
+- **Categoria:** Erro de domínio — ancestral das falhas numéricas/de tamanho.
+- **Quando é levantado:** Não é levantado diretamente; prefira uma subclasse folha.
+- **Exemplo:** Prefira `raise CnpjDV::InvalidLengthError` a levantar `DomainError` diretamente.
+- **Como resgatar:**
+
+```ruby
+rescue CnpjDV::DomainError
+  # InvalidLengthError, ValidationError e qualquer outra subclasse de DomainError
+```
+
+#### `CnpjDV::TypeMismatchError`
+
+- **Herança:** `CnpjDV::TypeMismatchError < TypeError` (inclui `CnpjDV::Error`)
+- **Categoria:** Uso incorreto da API — o chamador passou um valor do tipo errado.
+- **Quando é levantado:** Levantado quando a entrada de CNPJ não é `String` nem `Array` de strings (ou o array contém elemento que não é string).
+- **Exemplo:**
+
+```ruby
+CnpjDV::CnpjCheckDigits.new(12_345_678_000_100) # levanta CnpjDV::TypeMismatchError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjDV::TypeMismatchError
+  # violação de contrato de tipo desta biblioteca
+
+rescue TypeError
+  # erros nativos de tipo, incluindo TypeMismatchError desta biblioteca
+```
+
+#### `CnpjDV::InvalidLengthError`
+
+- **Herança:** `CnpjDV::InvalidLengthError < CnpjDV::DomainError < RangeError` (inclui `CnpjDV::Error`)
+- **Categoria:** Erro de domínio — o tamanho de uma coleção ou string viola uma regra de negócio.
+- **Quando é levantado:** Levantado quando a entrada de CNPJ sanitizada não contém de 12 a 14 caracteres alfanuméricos.
+- **Exemplo:**
+
+```ruby
+CnpjDV::CnpjCheckDigits.new('12345678901') # levanta CnpjDV::InvalidLengthError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjDV::InvalidLengthError
+  # esta violação exata de tamanho
+
+rescue CnpjDV::DomainError
+  # falhas de domínio enraizadas em RangeError desta biblioteca
+```
+
+#### `CnpjDV::ValidationError`
+
+- **Herança:** `CnpjDV::ValidationError < CnpjDV::DomainError < RangeError` (inclui `CnpjDV::Error`)
+- **Categoria:** Erro de domínio — um valor falha uma regra de domínio que não é numérica nem de tamanho.
+- **Quando é levantado:** Levantado quando a base é `00000000`, a filial é `0000`, ou os 12 primeiros caracteres são o mesmo dígito numérico.
+- **Exemplo:**
+
+```ruby
+CnpjDV::CnpjCheckDigits.new('000000000001') # levanta CnpjDV::ValidationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjDV::ValidationError
+  # esta falha exata de validação de domínio
+
+rescue CnpjDV::DomainError
+  # falhas de domínio enraizadas em RangeError desta biblioteca
+```
+
+#### Granularidade de rescue
+
+```ruby
+# 1) Uma classe nativa — captura uso incorreto de tipo desta biblioteca (e outros TypeError).
+rescue TypeError
+  # CnpjDV::TypeMismatchError e qualquer outro TypeError (da biblioteca ou não)
+
+# 2) CnpjDV::DomainError — captura violações de regra de negócio sob DomainError.
+rescue CnpjDV::DomainError
+  # CnpjDV::InvalidLengthError, CnpjDV::ValidationError e outras subclasses de DomainError
+
+# 3) CnpjDV::Error — captura tudo o que a biblioteca levanta.
+rescue CnpjDV::Error
+  # todo erro customizado que inclui CnpjDV::Error
+
+# 4) Classe folha específica — captura apenas aquele modo de falha.
+rescue CnpjDV::InvalidLengthError
+  # apenas CnpjDV::InvalidLengthError
+```
+
+Atributos relevantes nos erros:
+
+- `TypeMismatchError`: `actual_input`, `actual_type`, `expected_type`
+- `InvalidLengthError`: `actual_input`, `evaluated_input`, `min_expected_length`, `max_expected_length`
+- `ValidationError`: `actual_input`, `reason`
+
+### Outros recursos disponíveis
+
+Após `require 'cnpj-dv'`:
+
+- **`CnpjDV::CNPJ_MIN_LENGTH`**: `12`
+- **`CnpjDV::CNPJ_MAX_LENGTH`**: `14`
+- **Erros**: veja acima (`CnpjDV::Error`, `DomainError` e folhas levantadas)
+
+## 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,235 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+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 [TypeMismatchError] when input is not a +String+ or +Array<String>+
+    # @raise [InvalidLengthError] when character count is not between 12 and 14
+    # @raise [ValidationError] 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 [TypeMismatchError] 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 TypeMismatchError.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 [TypeMismatchError] when input is not a +String+ or +Array<String>+
+    def parse_array_input(cnpj_array)
+      return [] if cnpj_array.empty?
+
+      raise TypeMismatchError.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 [InvalidLengthError] 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 InvalidLengthError.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 [ValidationError] 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 ValidationError.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 [ValidationError] 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 ValidationError.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 [ValidationError] 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 ValidationError.new(
+        original_input,
+        'Repeated digits are not considered valid.'
+      )
+    end
+  end
+end

data/src/cnpj-dv/errors.rb

@@ -0,0 +1,122 @@
+# 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
+
+  # Marker module mixed into every custom error raised by this library.
+  #
+  # Use +rescue CnpjDV::Error+ to catch every library error regardless of native
+  # ancestry.
+  module Error; end
+
+  # API misuse error raised when an argument's runtime type does not match the
+  # type required by the API contract.
+  class TypeMismatchError < TypeError
+    include Error
+
+    # @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 (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("CNPJ input must be of type #{expected_type}. Got #{actual_type}.")
+      @actual_input = actual_input
+      @actual_type = actual_type
+      @expected_type = expected_type
+    end
+  end
+
+  # Domain error ancestor for business-rule failures (length, validation, and
+  # other domain leaves). Prefer raising a leaf subclass.
+  class DomainError < RangeError
+    include Error
+  end
+
+  # Domain error raised when a string, array, or other collection has a length
+  # outside the bounds required by the domain rule.
+  class InvalidLengthError < DomainError
+    # @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
+
+  # Domain error raised when a value has a valid type and length but violates a
+  # validation rule that is not numeric-range or length-based (e.g. ineligible
+  # base/branch ID or repeated numeric digits).
+  class ValidationError < DomainError
+    # @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 = '2.0.0'
 end

data/src/cnpj-dv.rb

@@ -1,9 +1,35 @@
 # frozen_string_literal: true
 
 require_relative 'cnpj-dv/version'
+require_relative 'cnpj-dv/errors'
+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).
+#
+# Errors fall into two categories:
+#
+# - *API misuse* — the caller invoked the library incorrectly (wrong type).
+#   Raised as {CnpjDV::TypeMismatchError} (+TypeError+).
+# - *Domain errors* — the call shape was valid, but a value violates a business
+#   rule (invalid length, ineligible base/branch, repeated digits). Length
+#   failures raise {CnpjDV::InvalidLengthError}; other domain failures raise
+#   {CnpjDV::ValidationError} (both under {CnpjDV::DomainError} / +RangeError+).
+#
+# Every custom error includes the {CnpjDV::Error} marker module so consumers can
+# +rescue CnpjDV::Error+ for a library-wide catch.
+#
+# Public API:
+#
+# - {CnpjDV::CnpjCheckDigits}
+# - {CnpjDV::CNPJ_MIN_LENGTH}, {CnpjDV::CNPJ_MAX_LENGTH}
+# - Error marker {CnpjDV::Error}; domain ancestor {CnpjDV::DomainError};
+#   raised leaves {CnpjDV::TypeMismatchError}, {CnpjDV::InvalidLengthError},
+#   {CnpjDV::ValidationError}
+#
+# @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: 2.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-20 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/errors.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: []