cnpj-dv 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 589e0576ee9e9cc2ddfeaf94c5f745792880885d7ea8dfcfb0953695b32a8981
-  data.tar.gz: 6662f13dfc238ea843cb79b14d1aaaf526c311e31f63dfc47937846a82ea3a2f
+  metadata.gz: 8d6109a8bd760c61186dc99ec5503bb42880d9ebb3c19745962ba5a0d97c6cfc
+  data.tar.gz: 47242e1f246d23ebab4d8c3be97d7d7b46060c974e011ad0412a93595fb69767
 SHA512:
-  metadata.gz: a3dbe7e29ebf3299714c285c90fbf170c6fb8a41e028e9fe64216d411233505cb7bb0230369e82d1a71dd14829c1b0031a046fefd21b96f0589af82af34bba09
-  data.tar.gz: 3a9f8a328af8c39185dc607db7529da03596235aa194ac57ad2fcdf623b5aad7f4a54124f6926f727a79fd89e9872212b21027a8e707e48d7d7961f902c1b86f
+  metadata.gz: 85686458b90a155cf2263ef4517f66732efbead21d29cc6683827ad2fae6a0f6e3949b17bbbbd2cd1a842c5cd1ff57a827e6ec1b10bc8cdb451d910ab954f383
+  data.tar.gz: 11dbfd7b80b6f25695678bc0a5e8804b08ae17fbbc7cf24aea2071f717092ebbc4e79db8945ed66d02bceef6e5f4ea467a8e7cd65c679c02381b087fd751b921

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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!

data/README.md

@@ -33,7 +33,7 @@ A Ruby utility to calculate check digits on CNPJ (Brazilian Business Tax ID).
 - ✅ **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)
+- ✅ **Error handling**: API misuse vs domain errors with a `CnpjDV::Error` marker for library-wide rescue
 
 
 
@@ -125,56 +125,139 @@ CnpjDV::CnpjCheckDigits.new(%w[MG KGM J9X 0001])
 
 
 
-### Errors & exceptions handling
+### Error 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.
+Errors fall into two categories:
 
-- `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)
+| 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
-require 'cnpj-dv'
+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
 
-# 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
+# 4) Specific leaf class — catches only that exact failure mode.
+rescue CnpjDV::InvalidLengthError
+  # only CnpjDV::InvalidLengthError
 ```
 
 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`
+- `TypeMismatchError`: `actual_input`, `actual_type`, `expected_type`
+- `InvalidLengthError`: `actual_input`, `evaluated_input`, `min_expected_length`, `max_expected_length`
+- `ValidationError`: `actual_input`, `reason`
 
 
 
@@ -184,7 +267,7 @@ After `require 'cnpj-dv'`:
 
 - `CnpjDV::CNPJ_MIN_LENGTH`: `12`
 - `CnpjDV::CNPJ_MAX_LENGTH`: `14`
-- **Exceptions**: see above
+- **Errors**: see above (`CnpjDV::Error`, `DomainError`, and raised leaves)
 
 
 

data/README.pt.md

@@ -16,7 +16,7 @@ Utilitário em Ruby para calcular os dígitos verificadores de CNPJ (Cadastro Na
 - ✅ **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`)
+- ✅ **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
 
@@ -96,56 +96,139 @@ CnpjDV::CnpjCheckDigits.new(%w[9141 5732 0007])
 CnpjDV::CnpjCheckDigits.new(%w[MG KGM J9X 0001])
 ```
 
-### Erros e exceções
+### Tratamento de erros
 
-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.
+Os erros se dividem em duas categorias:
 
-- **`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)
+| 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
-require 'cnpj-dv'
+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
 
-# 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
+# 4) Classe folha específica — captura apenas aquele modo de falha.
+rescue CnpjDV::InvalidLengthError
+  # apenas CnpjDV::InvalidLengthError
 ```
 
 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`
+- `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
 
@@ -153,7 +236,7 @@ Após `require 'cnpj-dv'`:
 
 - **`CnpjDV::CNPJ_MIN_LENGTH`**: `12`
 - **`CnpjDV::CNPJ_MAX_LENGTH`**: `14`
-- **Exceções**: veja acima
+- **Erros**: veja acima (`CnpjDV::Error`, `DomainError` e folhas levantadas)
 
 ## Algoritmo de cálculo
 

data/src/cnpj-dv/cnpj_check_digits.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'exceptions'
+require_relative 'errors'
 
 module CnpjDV
   # Minimum number of characters required for the CNPJ check digits calculation.
@@ -45,13 +45,11 @@ module CnpjDV
     #
     # @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-...+)
+    # @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)
 
@@ -126,13 +124,12 @@ module CnpjDV
     #
     # @param cnpj_input [Object] candidate CNPJ input
     # @return [Array<String>] uppercase alphanumeric characters
-    # @raise [CnpjCheckDigitsInputTypeError] when input is not a +String+ or
-    #   +Array<String>+
+    # @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 CnpjCheckDigitsInputTypeError.new(cnpj_input, 'string or string[]')
+      raise TypeMismatchError.new(cnpj_input, 'string or string[]')
     end
 
     # Strips non-alphanumeric characters and uppercases the remainder.
@@ -158,12 +155,11 @@ module CnpjDV
     #
     # @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>+
+    # @raise [TypeMismatchError] 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)
+      raise TypeMismatchError.new(cnpj_array, 'string or string[]') unless cnpj_array.all?(String)
 
       parse_string_input(cnpj_array.join)
     end
@@ -173,14 +169,13 @@ module CnpjDV
     #
     # @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
+    # @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 CnpjCheckDigitsInputLengthException.new(
+      raise InvalidLengthError.new(
         original_input,
         cnpj_chars.join,
         CNPJ_MIN_LENGTH,
@@ -192,12 +187,11 @@ module CnpjDV
     #
     # @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+)
+    # @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 CnpjCheckDigitsInputInvalidException.new(
+      raise ValidationError.new(
         original_input,
         "Base ID \"#{CNPJ_INVALID_BASE_ID}\" is not eligible."
       )
@@ -207,8 +201,7 @@ module CnpjDV
     #
     # @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+)
+    # @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
@@ -216,7 +209,7 @@ module CnpjDV
 
       return unless branch_id.all? { |char| char == '0' }
 
-      raise CnpjCheckDigitsInputInvalidException.new(
+      raise ValidationError.new(
         original_input,
         "Branch ID \"#{CNPJ_INVALID_BRANCH_ID}\" is not eligible."
       )
@@ -226,14 +219,14 @@ module CnpjDV
     #
     # @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-...+)
+    # @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 CnpjCheckDigitsInputInvalidException.new(
+      raise ValidationError.new(
         original_input,
         'Repeated digits are not considered valid.'
       )

data/src/cnpj-dv/{exceptions.rb → errors.rb}

@@ -18,11 +18,17 @@ module CnpjDV
   end
   private_constant :FormatActualInput
 
-  # Base error for all `cnpj-dv` type-related errors.
+  # Marker module mixed into every custom error raised by this library.
   #
-  # This class extends the native {TypeError} and serves as the base for all
-  # type validation errors in {CnpjCheckDigits}.
-  class CnpjCheckDigitsTypeError < TypeError
+  # 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
 
@@ -32,53 +38,29 @@ module CnpjDV
     # @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 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}."
-      )
+      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
 
-  # 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
+  # Domain error ancestor for business-rule failures (length, validation, and
+  # other domain leaves). Prefer raising a leaf subclass.
+  class DomainError < RangeError
+    include Error
   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
+  # 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
 
@@ -119,11 +101,10 @@ module CnpjDV
     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
+  # 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
 

data/src/cnpj-dv/version.rb

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

data/src/cnpj-dv.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
 
 require_relative 'cnpj-dv/version'
-require_relative 'cnpj-dv/exceptions'
+require_relative 'cnpj-dv/errors'
 require_relative 'cnpj-dv/cnpj_check_digits'
 
 # Check-digit calculation for Brazilian CNPJ (numeric and alphanumeric formats).
 #
-# The package distinguishes between **errors** and **exceptions**:
+# Errors fall into two categories:
 #
-# - {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).
+# - *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}
-# - Exception hierarchy under {CnpjDV::CnpjCheckDigitsTypeError} /
-#   {CnpjDV::CnpjCheckDigitsException}
+# - Error marker {CnpjDV::Error}; domain ancestor {CnpjDV::DomainError};
+#   raised leaves {CnpjDV::TypeMismatchError}, {CnpjDV::InvalidLengthError},
+#   {CnpjDV::ValidationError}
 #
 # @example
 #   require 'cnpj-dv'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cnpj-dv
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Julio L. Muller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-08 00:00:00.000000000 Z
+date: 2026-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lacus-utils
@@ -43,7 +43,7 @@ files:
 - README.pt.md
 - src/cnpj-dv.rb
 - src/cnpj-dv/cnpj_check_digits.rb
-- src/cnpj-dv/exceptions.rb
+- src/cnpj-dv/errors.rb
 - src/cnpj-dv/version.rb
 homepage: https://github.com/LacusSolutions/br-utils-ruby
 licenses: