br-utilities 0.0.0 → 1.0.0

data/README.pt.md

@@ -0,0 +1,1296 @@
+![br-utilities para Ruby](https://br-utils.vercel.app/img/cover_br-utils.jpg)
+
+> 🚀 **Suporte total ao [novo formato alfanumérico de CNPJ](https://github.com/user-attachments/files/23937961/calculodvcnpjalfanaumerico.pdf).**
+
+> 🌎 [Access documentation in English](./README.md)
+
+Kit em Ruby para as principais operações com dados brasileiros: CPF (Cadastro de Pessoa Física) e CNPJ (Cadastro Nacional da Pessoa Jurídica). Envolve [`cpf-utilities`](https://rubygems.org/gems/cpf-utilities) e [`cnpj-utilities`](https://rubygems.org/gems/cnpj-utilities) em uma única classe fachada (`BrUtils`).
+
+## Suporte a Ruby
+
+| ![Ruby 3.1](https://img.shields.io/badge/Ruby-3.1-CC342D?logo=ruby&logoColor=white) | ![Ruby 3.2](https://img.shields.io/badge/Ruby-3.2-CC342D?logo=ruby&logoColor=white) | ![Ruby 3.3](https://img.shields.io/badge/Ruby-3.3-CC342D?logo=ruby&logoColor=white) | ![Ruby 3.4](https://img.shields.io/badge/Ruby-3.4-CC342D?logo=ruby&logoColor=white) | ![Ruby 4.0](https://img.shields.io/badge/Ruby-4.0-CC342D?logo=ruby&logoColor=white) |
+| --- | --- | --- | --- | --- |
+| Passing ✔ | Passing ✔ | Passing ✔ | Passing ✔ | Passing ✔ |
+
+Requer Ruby **≥ 3.1** (veja `required_ruby_version` no gemspec).
+
+## Recursos
+
+- ✅ **API unificada de alto nível**: Helpers de classe `BrUtils.cpf` / `.cnpj` encaminham para `BrUtils::DEFAULT.cpf` / `.cnpj`; cada domínio oferece `format`, `generate` e `is_valid`
+- ✅ **Domínios empacotados**: [`cpf-utilities`](https://rubygems.org/gems/cpf-utilities) e [`cnpj-utilities`](https://rubygems.org/gems/cnpj-utilities) instalados juntos
+- ✅ **CNPJ alfanumérico**: Suporte completo ao novo formato alfanumérico de CNPJ (a partir de 2026)
+- ✅ **Instância reutilizável**: Classe `BrUtils` com configurações padrão opcionais de CPF e CNPJ (mapeamentos aninhados, kwargs planos de componentes ou instâncias prontas de utils)
+- ✅ **Acesso em dois níveis**: Prefira atalhos de classes principais na raiz da fachada (`BrUtils::CpfFormatter`, `BrUtils::CnpjValidator`, …); Options, helpers e erros ficam nos módulos aninhados (`BrUtils::CpfFmt`, `BrUtils::CnpjUtils`, …). Os irmãos na raiz (`CpfUtils`, `CnpjUtils`, `CpfFmt`, …) continuam funcionando
+- ✅ **Sobrescritas por chamada**: Configure padrões na fachada / utils de domínio; sobrescreva opções em uma única chamada de `format` / `generate` / `is_valid`
+- ✅ **Tratamento de erros**: Erros de domínio propagam inalterados dos pacotes incluídos; esta gem define `BrUtils::TypeMismatchError` e `BrUtils::InvalidArgumentCombinationError` para uso indevido da API
+
+## Instalação
+
+Instale a gem diretamente:
+
+```bash
+gem install br-utilities
+```
+
+Ou adicione ao seu `Gemfile` e execute `bundle install`:
+
+```ruby
+gem 'br-utilities'
+```
+
+Isso instala **`br-utilities`** junto com [`cpf-utilities`](https://rubygems.org/gems/cpf-utilities) e [`cnpj-utilities`](https://rubygems.org/gems/cnpj-utilities) (que por sua vez trazem os pacotes componentes de CPF e CNPJ). Você **não** precisa de `gem install` / linhas `gem` separados para os pacotes de domínio ao usar **`br-utilities`**.
+
+## Require
+
+```ruby
+require 'br-utilities'
+```
+
+## Início rápido
+
+Prefira os helpers de classe do agregador (`BrUtils.cpf` / `BrUtils.cnpj`) para chamadas pontuais — eles encaminham para `BrUtils::DEFAULT`:
+
+```ruby
+require 'br-utilities'
+
+cpf = '12345678909'
+cnpj = '03603568000195'
+
+# CPF (pessoa física)
+BrUtils.cpf.format(cpf)              # => "123.456.789-09"
+BrUtils.cpf.generate(format: true)   # => ex.: "478.442.410-55"
+BrUtils.cpf.is_valid('123.456.789-09') # => true
+
+# CNPJ (pessoa jurídica)
+BrUtils.cnpj.format(cnpj)            # => "03.603.568/0001-95"
+BrUtils.cnpj.generate(format: true)  # => ex.: "AB.123.CDE/0001-55"
+BrUtils.cnpj.is_valid('98765432000198') # => true
+```
+
+**Com agregadores de domínio:**
+
+```ruby
+require 'br-utilities'
+
+cpf = '12345678909'
+cnpj = '03603568000195'
+
+CpfUtils.format(cpf)      # => "123.456.789-09"
+CnpjUtils.format(cnpj)    # => "03.603.568/0001-95"
+CpfUtils.is_valid(cpf)    # => true
+CnpjUtils.is_valid(cnpj)  # => true
+```
+
+**Com helpers funcionais** (módulos irmãos na raiz, carregados por esta gem):
+
+```ruby
+require 'br-utilities'
+
+cpf = '12345678909'
+cnpj = '03603568000195'
+
+CpfFmt.cpf_fmt(cpf)     # => "123.456.789-09"
+CpfVal.cpf_val(cpf)     # => true
+CnpjFmt.cnpj_fmt(cnpj)  # => "03.603.568/0001-95"
+CnpjVal.cnpj_val(cnpj)  # => true
+```
+
+## Utilização
+
+Você pode trabalhar destas formas equivalentes:
+
+1. **`BrUtils.cpf` / `.cnpj`** — helpers de classe para chamadas rápidas (encaminham para `DEFAULT`).
+2. **`BrUtils::DEFAULT`** — singleton compartilhado mutável (o mesmo objeto usado pelos helpers de classe; em todo o processo / não isolado por thread).
+3. **`BrUtils.new`** — instância configurável com padrões compartilhados entre os domínios CPF e CNPJ.
+4. **Agregadores de domínio** — `CpfUtils` / `CnpjUtils` (ou `BrUtils::CpfUtils` / `BrUtils::CnpjUtils`) diretamente.
+5. **Classes principais sob `BrUtils`** — `BrUtils::CpfFormatter`, `BrUtils::CnpjGenerator` e atalhos relacionados.
+6. **Módulos aninhados do pacote** — Options, helpers, erros e tipos via `BrUtils::CpfFmt` / `CpfGen` / `CpfVal` / `CnpjFmt` / `CnpjGen` / `CnpjVal` / `CpfUtils` / `CnpjUtils`.
+7. **Módulos irmãos na raiz** (ainda suportados) — `CpfFmt`, `CnpjUtils` e demais inalterados.
+
+Todas as abordagens expõem as mesmas opções e comportamento dentro de cada domínio. Para tabelas de opções exaustivas e detalhes específicos de cada componente, consulte o README de cada [pacote incluído](#pacotes-incluídos).
+
+### Helpers de classe (`BrUtils.cpf` / `.cnpj`)
+
+Esses métodos de classe retornam as mesmas instâncias de utils de domínio que `BrUtils::DEFAULT`. Prefira-os para chamadas pontuais:
+
+```ruby
+BrUtils.cpf.format('12345678909')
+BrUtils.cpf.generate(format: true)
+BrUtils.cpf.is_valid('12345678909')
+
+BrUtils.cnpj.format('03603568000195')
+BrUtils.cnpj.generate(type: 'numeric')
+BrUtils.cnpj.is_valid('98765432000198')
+```
+
+### `BrUtils::DEFAULT` (instância padrão)
+
+`BrUtils::DEFAULT` é o singleton pré-construído e **mutável** por trás dos helpers de classe (paridade com a exportação padrão do JS / `br_utils` do Python). Sua configuração é **em todo o processo e compartilhada entre threads**: mutá-lo (ex.: `DEFAULT.cpf = …`) afeta chamadas subsequentes de `BrUtils.cpf` / `.cnpj` para todos os callers no processo. Prefira `BrUtils.new` ou opções por chamada para trabalho concorrente ou isolado; instâncias customizadas permanecem independentes de `DEFAULT`:
+
+```ruby
+BrUtils::DEFAULT.cpf = CpfUtils.new(formatter: { dash_key: '|' })
+BrUtils.cpf.format('12345678909')   # => "123.456.789|09"
+
+custom = BrUtils.new
+custom.cpf.format('12345678909')    # => "123.456.789-09" (não afetado)
+```
+
+### `BrUtils` (classe)
+
+Para utils de CPF ou CNPJ padrão customizados, crie sua própria instância:
+
+```ruby
+require 'br-utilities'
+
+utils = BrUtils.new(
+  cpf: {
+    formatter: { hidden: true, hidden_key: '#' },
+    generator: { format: true }
+  },
+  cnpj: {
+    formatter: { hidden: true },
+    generator: { type: 'numeric', format: true },
+    validator: { type: 'numeric' }
+  }
+)
+
+utils.cpf.format('12345678909')        # => "123.###.###-##"
+utils.cpf.generate                     # => ex.: "005.265.352-88"
+utils.cnpj.format('03603568000195')    # => "03.603.***/****-**"
+utils.cnpj.generate                    # => ex.: "73.008.535/0005-06"
+
+# Acessar ou substituir instâncias internas de domínio
+utils.cpf    # => CpfUtils
+utils.cnpj   # => CnpjUtils
+```
+
+- **`BrUtils.new(settings = nil, **keywords)`**: Configurações opcionais. Passe um `Hash` de settings com chaves `:cpf` e/ou `:cnpj`, **ou** as mesmas chaves (mais kwargs planos de componentes) como argumentos nomeados — não ambos (passar ambos lança `BrUtils::InvalidArgumentCombinationError`).
+  - **`:cpf` / `:cnpj`**: Uma instância pronta de `CpfUtils` / `CnpjUtils` **ou** um `Hash` de configuração repassado ao construtor do utils correspondente. Dentro desse `Hash`, cada chave de recurso (`:formatter`, `:generator` e `:validator` para CNPJ) aceita um objeto de opções ou um mapeamento de valores de opção.
+  - **`:cpf_formatter`**, **`:cpf_generator`**, **`:cnpj_formatter`**, **`:cnpj_generator`**, **`:cnpj_validator`**: Argumentos planos de conveniência quando apenas componentes individuais precisam de customização. São ignorados quando o argumento `:cpf` ou `:cnpj` correspondente é fornecido.
+- **`#cpf`**, **`#cnpj`**: Acessores (getters e setters) das instâncias de utils de domínio. Os setters aceitam uma instância de utils, um `Hash` de configuração ou `nil` para voltar aos padrões (substitui a instância inteira; não faz merge).
+
+Opções planas no construtor (alternativa aos mapeamentos aninhados `:cpf` / `:cnpj`):
+
+```ruby
+require 'br-utilities'
+
+utils = BrUtils.new(
+  cpf_formatter: CpfFmt::CpfFormatterOptions.new(hidden: true, hidden_key: '#'),
+  cpf_generator: CpfGen::CpfGeneratorOptions.new(format: true),
+  cnpj_formatter: CnpjFmt::CnpjFormatterOptions.new(hidden: true, hidden_key: '#'),
+  cnpj_generator: CnpjGen::CnpjGeneratorOptions.new(format: true, type: 'numeric'),
+  cnpj_validator: CnpjVal::CnpjValidatorOptions.new(type: 'numeric')
+)
+```
+
+Passar um `Hash` de settings posicional junto com qualquer palavra-chave lança:
+
+```ruby
+BrUtils.new({ cpf: {} }, cnpj: CnpjUtils.new)
+# lança BrUtils::InvalidArgumentCombinationError
+```
+
+### Padrões da instância e sobrescritas por chamada
+
+```ruby
+require 'br-utilities'
+
+utils = BrUtils.new(
+  cpf: {
+    formatter: { hidden: true, hidden_key: '#' },
+    generator: { format: true }
+  },
+  cnpj: {
+    formatter: { hidden: true, hidden_key: '#' },
+    generator: { format: true },
+    validator: { type: 'numeric' }
+  }
+)
+
+cpf = '12345678909'
+cnpj = '03603568000195'
+
+utils.cpf.format(cpf)                  # => "123.###.###-##"
+utils.cpf.format(cpf, hidden: false)   # só nesta chamada: sem máscara
+utils.cpf.generate(format: false)      # só nesta chamada: saída compacta
+
+utils.cnpj.format(cnpj)                  # => "03.603.###/####-##"
+utils.cnpj.format(cnpj, hidden: false)   # só nesta chamada: sem máscara
+utils.cnpj.is_valid('1QB5UKALPYFP59')    # => false (validador da instância é só numérico)
+utils.cnpj.is_valid(                     # => true nesta chamada
+  '1QB5UKALPYFP59',
+  type: 'alphanumeric'
+)
+```
+
+Passar uma instância de `CnpjFmt::CnpjFormatterOptions`, `CnpjGen::CnpjGeneratorOptions` ou `CnpjVal::CnpjValidatorOptions` ao construtor de `BrUtils` armazena esse objeto por referência — mutá-lo depois afeta chamadas subsequentes sem sobrescrita por chamada.
+
+Para alterar uma única opção aninhada sem substituir o utils de domínio inteiro, mute via os acessores de domínio (ex.: `utils.cpf.formatter.options.hidden = true`).
+
+### Operações de CPF
+
+Os métodos de CPF são acessados via `BrUtils.cpf`, `utils.cpf`, `CpfUtils` ou os helpers `CpfFmt` / `CpfGen` / `CpfVal`. O CPF usa a API de [`cpf-utilities`](../cpf-utilities/README.pt.md).
+
+#### Formatação (`#format` / `CpfFmt.cpf_fmt`)
+
+| Opção | Tipo | Padrão | Descrição |
+|--------|------|---------|-------------|
+| `hidden` | `Boolean` | `false` | Se `true`, mascara dígitos entre `hidden_start` e `hidden_end` com `hidden_key` |
+| `hidden_key` | `String` | `'*'` | Caractere(s) usados para substituir dígitos mascarados |
+| `hidden_start` | `Integer` | `3` | Índice inicial (0–10, inclusivo) do intervalo a ocultar |
+| `hidden_end` | `Integer` | `10` | Índice final (0–10, inclusivo) do intervalo a ocultar |
+| `dot_key` | `String` | `'.'` | Delimitador de ponto (ex.: em `123.456.789`) |
+| `dash_key` | `String` | `'-'` | Delimitador de hífen (ex.: antes dos dígitos verificadores `…-09`) |
+| `escape` | `Boolean` | `false` | Se `true`, escapa caracteres especiais HTML no resultado |
+| `encode` | `Boolean` | `false` | Se `true`, codifica o resultado para URL (similar ao `encodeURIComponent` do JavaScript) |
+| `on_fail` | `Proc` / invocável | retorna `''` | Callback quando o tamanho da entrada sanitizada ≠ 11; o retorno é usado como resultado |
+
+O **`on_fail`** padrão retorna uma string vazia. Comprimento inválido **não** lança exceção em `#format`.
+
+```ruby
+require 'br-utilities'
+
+cpf = '12345678909'
+
+BrUtils.cpf.format(cpf)                              # => "123.456.789-09"
+BrUtils.cpf.format(cpf, hidden: true, hidden_key: '#') # => "123.###.###-##"
+BrUtils.cpf.format(cpf, dot_key: '', dash_key: '_')  # => "123456789_09"
+
+CpfFmt.cpf_fmt(cpf, hidden: true)                    # => "123.***.***-**"
+```
+
+#### Geração (`#generate` / `CpfGen.cpf_gen`)
+
+| Opção | Tipo | Padrão | Descrição |
+|--------|------|---------|-------------|
+| `format` | `Boolean` | `false` | Se `true`, retorna o CPF gerado no formato padrão (`000.000.000-00`) |
+| `prefix` | `String` | `''` | String parcial inicial (0–9 dígitos). Não dígitos são removidos; caracteres faltantes são gerados e os dígitos verificadores calculados. Prefixos com mais de 9 dígitos são truncados silenciosamente. |
+
+Regras de prefixo: a base (primeiros 9 dígitos) não pode ser toda zeros; 9 dígitos repetidos (ex.: `999999999`) não são permitidos.
+
+```ruby
+require 'br-utilities'
+
+BrUtils.cpf.generate                       # => ex.: "11508890048"
+BrUtils.cpf.generate(format: true)         # => ex.: "661.134.831-00"
+BrUtils.cpf.generate(prefix: '123456789')  # => "12345678909"
+CpfGen.cpf_gen(prefix: '123456789', format: true) # => "123.456.789-09"
+```
+
+#### Validação (`#is_valid` / `CpfVal.cpf_val`)
+
+Aceita CPF formatado ou não (ou um `Array` de strings). Retorna **`true`** ou **`false`** sem lançar exceção para CPF inválido. Não há opções de validador.
+
+```ruby
+require 'br-utilities'
+
+BrUtils.cpf.is_valid('12345678909')      # => true
+BrUtils.cpf.is_valid('123.456.789-09')   # => true
+BrUtils.cpf.is_valid('12345678900')      # => false
+CpfVal.cpf_val('12345678909')            # => true
+```
+
+### Operações de CNPJ
+
+Os métodos de CNPJ são acessados via `BrUtils.cnpj`, `utils.cnpj`, `CnpjUtils` ou os helpers `CnpjFmt` / `CnpjGen` / `CnpjVal`. O CNPJ usa a API de [`cnpj-utilities`](../cnpj-utilities/README.pt.md).
+
+#### Formatação (`#format` / `CnpjFmt.cnpj_fmt`)
+
+| Opção | Tipo | Padrão | Descrição |
+|--------|------|---------|-------------|
+| `hidden` | `Boolean` | `false` | Se `true`, mascara caracteres entre `hidden_start` e `hidden_end` com `hidden_key` |
+| `hidden_key` | `String` | `'*'` | Caractere(s) usados para substituir caracteres mascarados |
+| `hidden_start` | `Integer` | `5` | Índice inicial (0–13, inclusivo) do intervalo a ocultar |
+| `hidden_end` | `Integer` | `13` | Índice final (0–13, inclusivo) do intervalo a ocultar |
+| `dot_key` | `String` | `'.'` | Delimitador de ponto (ex.: em `12.345.678`) |
+| `slash_key` | `String` | `'/'` | Delimitador de barra (ex.: antes da filial `…/0001-90`) |
+| `dash_key` | `String` | `'-'` | Delimitador de hífen (ex.: antes dos dígitos verificadores `…-90`) |
+| `escape` | `Boolean` | `false` | Se `true`, escapa caracteres especiais HTML no resultado |
+| `encode` | `Boolean` | `false` | Se `true`, codifica o resultado para URL (similar ao `encodeURIComponent` do JavaScript) |
+| `on_fail` | `Proc` / invocável | retorna `''` | Callback quando o tamanho da entrada sanitizada ≠ 14; o retorno é usado como resultado |
+
+O **`on_fail`** padrão retorna uma string vazia. Tipos de entrada incorretos lançam **`CnpjFmt::TypeMismatchError`**.
+
+```ruby
+require 'br-utilities'
+
+cnpj = '03603568000195'
+
+BrUtils.cnpj.format(cnpj)              # => "03.603.568/0001-95"
+BrUtils.cnpj.format('12ABC34500DE99')  # => "12.ABC.345/00DE-99"
+BrUtils.cnpj.format(                   # => "03.603.###/####-##"
+  cnpj,
+  hidden: true,
+  hidden_key: '#'
+)
+BrUtils.cnpj.format(                   # => "03603568|0001_95"
+  cnpj,
+  dot_key: '',
+  slash_key: '|',
+  dash_key: '_'
+)
+
+CnpjFmt.cnpj_fmt(cnpj)                 # => "03.603.568/0001-95"
+```
+
+#### Geração (`#generate` / `CnpjGen.cnpj_gen`)
+
+| Opção | Tipo | Padrão | Descrição |
+|--------|------|---------|-------------|
+| `format` | `Boolean` | `false` | Se `true`, retorna o CNPJ gerado no formato padrão (`00.000.000/0000-00`) |
+| `prefix` | `String` | `''` | String parcial inicial (0–12 caracteres alfanuméricos). Caracteres faltantes são gerados e os dígitos verificadores calculados. |
+| `type` | `String` | `'alphanumeric'` | Conjunto de caracteres para a parte gerada aleatoriamente: `'numeric'`, `'alphabetic'` ou `'alphanumeric'`. **Os dígitos verificadores são sempre numéricos.** |
+
+Regras de prefixo: o ID base (primeiros 8 caracteres) e o ID da filial (caracteres 9–12) não podem ser todos zeros; 12 dígitos repetidos (ex.: `111111111111`) também não são permitidos.
+
+```ruby
+require 'br-utilities'
+
+BrUtils.cnpj.generate               # => ex.: "1GJTR3J3XSSA96"
+BrUtils.cnpj.generate(format: true) # => ex.: "V1.J0V.8WE/DVZ7-50"
+BrUtils.cnpj.generate(              # => ex.: "12345678855883"
+  prefix: '12345678',
+  type: 'numeric'
+)
+CnpjGen.cnpj_gen(type: 'numeric')   # => ex.: "65453043000178"
+```
+
+#### Validação (`#is_valid` / `CnpjVal.cnpj_val`)
+
+| Opção | Tipo | Padrão | Descrição |
+|--------|------|---------|-------------|
+| `case_sensitive` | `Boolean` | `true` | Se `false`, letras minúsculas são aceitas para CNPJ alfanumérico (a entrada é convertida para maiúsculas antes da validação). |
+| `type` | `String` | `'alphanumeric'` | `'numeric'`: apenas dígitos (0–9); `'alphanumeric'`: dígitos e letras (0–9, A–Z). |
+
+```ruby
+require 'br-utilities'
+
+BrUtils.cnpj.is_valid('98765432000198')   # => true
+BrUtils.cnpj.is_valid('98765432000199')   # => false
+BrUtils.cnpj.is_valid('1QB5UKALPYFP59')   # => true
+BrUtils.cnpj.is_valid('1QB5UKALpyfp59')   # => false
+BrUtils.cnpj.is_valid(                     # => true
+  '1QB5UKALpyfp59',
+  case_sensitive: false
+)
+BrUtils.cnpj.is_valid(                     # => false
+  '1QB5UKALPYFP59',
+  type: 'numeric'
+)
+
+CnpjVal.cnpj_val('98765432000198')                         # => true
+CnpjVal.cnpj_val('1QB5UKALpyfp59', case_sensitive: false)  # => true
+CnpjVal.cnpj_val('1QB5UKALPYFP59', type: 'numeric')        # => false
+```
+
+CNPJ inválido retorna **`false`** sem lançar exceção. Tipos de entrada incorretos lançam **`CnpjVal::TypeMismatchError`**.
+
+### Agregadores de domínio (isolados)
+
+Use `CpfUtils` ou `CnpjUtils` diretamente quando precisar de apenas um domínio:
+
+```ruby
+require 'br-utilities'
+
+cpf_utils = CpfUtils.new(
+  formatter: { hidden: true },
+  generator: { format: true }
+)
+
+cnpj_utils = CnpjUtils.new(
+  formatter: { hidden: true },
+  generator: { format: true },
+  validator: { type: 'numeric' }
+)
+
+cpf_utils.format('12345678909')       # => "123.***.***-**"
+cnpj_utils.format('03603568000195')   # => "03.603.***/****-**"
+```
+
+### Acessando componentes
+
+Cada agregador de domínio expõe seu formatador, gerador e validador internos:
+
+```ruby
+require 'br-utilities'
+
+utils = BrUtils.new
+
+utils.cpf.formatter.format('12345678909', hidden: true)  # => "123.***.***-**"
+utils.cpf.generator.generate(format: true)               # => ex.: "545.507.690-68"
+utils.cpf.validator.is_valid('12345678909')              # => true
+
+utils.cnpj.formatter.format('12ABC34500DE99')            # => "12.ABC.345/00DE-99"
+utils.cnpj.generator.generate(format: true)              # => ex.: "8O.BE5.2KL/UI0Y-06"
+utils.cnpj.validator.is_valid('03603568000195')          # => true
+```
+
+### Usando classes componentes e módulos aninhados
+
+Caminhos preferidos após `require 'br-utilities'`:
+
+```ruby
+require 'br-utilities'
+
+# Classes principais na raiz da fachada
+formatter = BrUtils::CpfFormatter.new(hidden: true)
+generator = BrUtils::CnpjGenerator.new(type: 'numeric')
+validator = BrUtils::CnpjValidator.new
+
+formatter.format('12345678909')   # => "123.***.***-**"
+
+# Options, helpers e erros nos módulos aninhados do pacote
+options = BrUtils::CpfFmt::CpfFormatterOptions.new(dash_key: '|')
+BrUtils::CpfFmt.cpf_fmt('12345678909')   # => "123.456.789-09"
+
+begin
+  BrUtils::CnpjFmt.cnpj_fmt(12_345)
+rescue BrUtils::CnpjFmt::TypeMismatchError
+  # tipo de entrada incorreto
+end
+```
+
+Os irmãos na raiz continuam suportados (os mesmos objetos dos nests):
+
+```ruby
+CpfFmt.cpf_fmt('12345678909', dash_key: '|')   # => "123.456.789|09"
+CpfGen.cpf_gen(format: true)                   # => ex.: "478.442.410-55"
+CpfVal.cpf_val('12345678909')                  # => true
+CnpjFmt.cnpj_fmt('01ABC234000X56', slash_key: '|') # => "01.ABC.234|000X-56"
+CnpjGen.cnpj_gen(type: 'numeric')              # => ex.: "65453043000178"
+CnpjVal.cnpj_val('9JN7MGLJZXIO50')             # => true
+```
+
+Consulte [`cpf-utilities`](../cpf-utilities/README.pt.md) e [`cnpj-utilities`](../cnpj-utilities/README.pt.md) para detalhes completos de opções e erros.
+
+### Misturando estilos
+
+Use `BrUtils` onde uma configuração compartilhada ajuda, e componentes ou helpers isolados em outros pontos — são as mesmas classes subjacentes:
+
+```ruby
+require 'br-utilities'
+
+utils = BrUtils.new(cnpj: { validator: { type: 'numeric' } })
+
+# Via fachada
+utils.cpf.format('12345678909')   # => "123.456.789-09"
+
+# Via componente retornado pela fachada
+utils.cnpj.formatter.format('12ABC34500DE99')   # => "12.ABC.345/00DE-99"
+
+# Via instância de componente separada
+BrUtils::CnpjFormatter.new.format('03603568000195')   # => "03.603.568/0001-95"
+
+# Via helpers funcionais
+CpfFmt.cpf_fmt('12345678909')           # => "123.456.789-09"
+CnpjVal.cnpj_val('98.765.432/0001-98')  # => true
+```
+
+## API
+
+### Exportações
+
+Após `require 'br-utilities'`:
+
+- **`BrUtils`**: Classe fachada para criar uma instância com configurações opcionais dos utils de CPF e CNPJ.
+- **`BrUtils.cpf` / `.cnpj`**: Helpers de classe que encaminham para os acessores de domínio de `BrUtils::DEFAULT`.
+- **`BrUtils::DEFAULT`**: Instância pré-construída e mutável de `BrUtils` (o mesmo objeto usado pelos helpers de classe). Em todo o processo / compartilhada entre threads — prefira `BrUtils.new` ou opções por chamada sob concorrência.
+- **`BrUtils::VERSION`**: String da versão da gem.
+- **Atalhos de classes principais**: `BrUtils::CpfFormatter`, `BrUtils::CpfFormatterOptions`, `BrUtils::CpfGenerator`, `BrUtils::CpfGeneratorOptions`, `BrUtils::CpfValidator`, `BrUtils::CnpjFormatter`, `BrUtils::CnpjFormatterOptions`, `BrUtils::CnpjGenerator`, `BrUtils::CnpjGeneratorOptions`, `BrUtils::CnpjValidator`, `BrUtils::CnpjValidatorOptions` (os mesmos objetos das classes irmãs). Atalhos de marcadores de erro: `BrUtils::CpfFormatterError`, `BrUtils::CpfGeneratorError`, `BrUtils::CpfValidatorError`, `BrUtils::CnpjFormatterError`, `BrUtils::CnpjGeneratorError`, `BrUtils::CnpjValidatorError`.
+- **Módulos aninhados do pacote**: `BrUtils::CpfUtils`, `BrUtils::CnpjUtils`, `BrUtils::CpfFmt`, `BrUtils::CpfGen`, `BrUtils::CpfVal`, `BrUtils::CnpjFmt`, `BrUtils::CnpjGen`, `BrUtils::CnpjVal` — superfície completa dos irmãos (Options, helpers, erros, tipos).
+- **Módulos irmãos na raiz** (ainda suportados): `CpfUtils`, `CnpjUtils`, `CpfFmt`, `CpfGen`, `CpfVal`, `CnpjFmt`, `CnpjGen`, `CnpjVal` — os mesmos objetos dos nests.
+
+### Erros e exceções
+
+`BrUtils` define apenas erros de uso indevido da API para as regras de argumentos desta gem. Erros de domínio são lançados pelos pacotes incluídos e propagam inalterados.
+
+#### Definidos por `br-utilities`
+
+Os erros definidos por esta gem são **apenas uso indevido da API** (tipo errado ou combinação inválida de argumentos). Todo erro customizado inclui o módulo marcador `BrUtils::Error`. Esta gem **não** define `BrUtils::DomainError` nem folhas de domínio — falhas de domínio vêm apenas dos [pacotes incluídos](#propagados-dos-pacotes-incluídos) e mantêm os namespaces desses pacotes (`CpfFmt::…`, `CnpjGen::…`, …).
+
+`rescue BrUtils::Error` captura **apenas** erros que esta gem lança. **Não** captura erros de componentes que propagam inalterados.
+
+##### Resumo
+
+| Classe | Herda de | Categoria | Condição de disparo |
+|-------|---------------|----------|-------------------|
+| `BrUtils::InvalidArgumentCombinationError` | `BrUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include BrUtils::Error`) | Uso indevido da API | `Hash` de settings não-`nil` passado junto com qualquer argumento nomeado não-`nil` |
+| `BrUtils::TypeMismatchError` | `BrUtils::TypeMismatchError < TypeError < StandardError` (+ `include BrUtils::Error`) | Uso indevido da API | Argumento `settings` não-`nil` em `BrUtils.new` não é um `Hash` |
+
+##### `BrUtils::Error` (módulo marcador)
+
+- **Herança:** módulo marcador misturado em todo erro customizado que esta gem lança via `include` (não é uma classe).
+- **Categoria:** N/A (apenas alvo de rescue) — não é um modo de falha por si só.
+- **Quando é lançado:** Nunca lançado diretamente; incluído por todo erro customizado que esta gem lança.
+- **Exemplo:** N/A
+- **Como resgatar:**
+
+```ruby
+rescue BrUtils::Error
+  # TypeMismatchError, InvalidArgumentCombinationError apenas desta gem
+  # (não CpfFmt::*, CnpjGen::* ou outros erros dos pacotes incluídos)
+```
+
+##### `BrUtils::TypeMismatchError`
+
+- **Herança:** `BrUtils::TypeMismatchError < TypeError < StandardError` (inclui `BrUtils::Error`)
+- **Categoria:** Uso indevido da API — o caller passou um valor do tipo errado.
+- **Quando é lançado:** Quando `BrUtils.new` recebe um argumento `settings` não-`nil` que não é um `Hash`.
+- **Exemplo:**
+
+```ruby
+BrUtils.new('not-a-hash')   # lança BrUtils::TypeMismatchError
+BrUtils.new(false)          # lança BrUtils::TypeMismatchError (false é não-nil)
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue BrUtils::TypeMismatchError
+  # violação de contrato de tipo desta gem
+
+rescue TypeError
+  # erros nativos de tipo, incluindo TypeMismatchError desta gem
+```
+
+##### `BrUtils::InvalidArgumentCombinationError`
+
+- **Herança:** `BrUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (inclui `BrUtils::Error`)
+- **Categoria:** Uso indevido da API — o caller misturou padrões de argumentos mutuamente exclusivos.
+- **Quando é lançado:** Quando `BrUtils.new` recebe um `Hash` de settings não-`nil` e qualquer argumento nomeado não-`nil` (`cpf:`, `cnpj:`, `cpf_formatter:`, …) ao mesmo tempo.
+- **Exemplo:**
+
+```ruby
+BrUtils.new({ cpf: { formatter: { hidden: true } } }, cnpj: { formatter: { hidden: true } })
+# lança BrUtils::InvalidArgumentCombinationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue BrUtils::InvalidArgumentCombinationError
+  # combinação inválida de assinatura desta gem
+
+rescue ArgumentError
+  # erros nativos de argumento, incluindo InvalidArgumentCombinationError desta gem
+```
+
+##### Granularidade de rescue
+
+Cada nível é mostrado como seu próprio exemplo isolado (não os una em uma única escada de `rescue` — um handler nativo amplo tornaria cláusulas mais estreitas inalcançáveis).
+
+```ruby
+require 'br-utilities'
+
+# 1) Classe nativa única — captura erros de uso indevido desse tipo,
+#    incluindo os não-biblioteca já tratados em outro ponto do código do consumidor.
+begin
+  BrUtils.new('not-a-hash')
+rescue TypeError
+  # BrUtils::TypeMismatchError e qualquer outro TypeError (biblioteca ou não)
+end
+
+begin
+  BrUtils.new({ cpf: {} }, cnpj: CnpjUtils.new)
+rescue ArgumentError
+  # BrUtils::InvalidArgumentCombinationError e qualquer outro ArgumentError (biblioteca ou não)
+end
+```
+
+```ruby
+require 'br-utilities'
+
+# 2) DomainError dos pacotes — esta gem não define DomainError; falhas de domínio
+#    vêm dos pacotes incluídos e mantêm esses namespaces (ex.: CpfFmt, CnpjFmt).
+begin
+  BrUtils.new.cpf.format('12345678909', hidden_start: -1)
+rescue CpfFmt::DomainError
+  # CpfFmt::OutOfRangeError, CpfFmt::ValidationError e outras subclasses de DomainError
+end
+
+begin
+  BrUtils.new.cnpj.format('91415732000793', hidden_start: -1)
+rescue CnpjFmt::DomainError
+  # CnpjFmt::OutOfRangeError, CnpjFmt::ValidationError e outras subclasses de DomainError
+end
+```
+
+```ruby
+require 'br-utilities'
+
+# 3) BrUtils::Error — captura tudo que esta gem lança, independentemente da ancestralidade nativa.
+#    Não captura CpfFmt::*, CnpjGen::* ou outros erros dos pacotes incluídos.
+begin
+  BrUtils.new('not-a-hash')
+rescue BrUtils::Error
+  # todo erro customizado que inclui BrUtils::Error
+end
+```
+
+```ruby
+require 'br-utilities'
+
+# 4) Classe folha específica — captura apenas aquele modo de falha exato.
+begin
+  BrUtils.new('not-a-hash')
+rescue BrUtils::TypeMismatchError
+  # apenas BrUtils::TypeMismatchError
+end
+```
+
+#### Propagados dos pacotes incluídos
+
+Os erros dos componentes mantêm os namespaces dos pacotes e se propagam inalterados pela fachada (e pelas APIs aninhadas / irmãs na raiz). Cada pacote também expõe um módulo marcador `*::Error` para rescue em toda a biblioteca. **Dados** inválidos de CPF/CNPJ em `#is_valid` retornam `false` (sem raise de domínio). Falha de comprimento na formatação **não** é lançada por `#format` — é entregue a **`on_fail`** como `CpfFmt::InvalidLengthError` ou `CnpjFmt::InvalidLengthError` (`on_fail` padrão retorna `''`).
+
+`CpfUtils::*` / `CnpjUtils::*` de uso indevido também se propagam quando agregadores aninhados são construídos ou chamados via `BrUtils`. Para tabelas de opções e casos extremos, veja [`cpf-utilities`](../cpf-utilities/README.pt.md) e [`cnpj-utilities`](../cnpj-utilities/README.pt.md).
+
+##### Resumo
+
+| Classe | Herda de | Categoria | Condição de disparo |
+|-------|---------------|----------|-------------------|
+| `CnpjFmt::InvalidArgumentCombinationError` | `CnpjFmt::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjFmt::Error`) | Uso indevido da API | Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CnpjFormatter` / `cnpj_fmt` |
+| `CnpjFmt::TypeMismatchError` | `CnpjFmt::TypeMismatchError < TypeError < StandardError` (+ `include CnpjFmt::Error`) | Uso indevido da API | Entrada de CNPJ ou opção do formatador tem o tipo errado (ou o retorno de `on_fail` não é `String`) |
+| `CnpjGen::InvalidArgumentCombinationError` | `CnpjGen::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjGen::Error`) | Uso indevido da API | Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CnpjGenerator` / `cnpj_gen` |
+| `CnpjGen::TypeMismatchError` | `CnpjGen::TypeMismatchError < TypeError < StandardError` (+ `include CnpjGen::Error`) | Uso indevido da API | Opção do gerador (`format` / `prefix` / `type`) tem o tipo errado |
+| `CnpjUtils::InvalidArgumentCombinationError` | `CnpjUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjUtils::Error`) | Uso indevido da API | Construtor/`#format`/`#generate`/`#is_valid`/helpers de classe: `Hash`/instância de settings/options não-`nil` com qualquer argumento nomeado não-`nil` |
+| `CnpjUtils::TypeMismatchError` | `CnpjUtils::TypeMismatchError < TypeError < StandardError` (+ `include CnpjUtils::Error`) | Uso indevido da API | Argumento `settings` não-`nil` de `CnpjUtils.new` não é um `Hash` |
+| `CnpjVal::InvalidArgumentCombinationError` | `CnpjVal::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjVal::Error`) | Uso indevido da API | Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CnpjValidator` / `cnpj_val` |
+| `CnpjVal::TypeMismatchError` | `CnpjVal::TypeMismatchError < TypeError < StandardError` (+ `include CnpjVal::Error`) | Uso indevido da API | Entrada de CNPJ ou opção do validador tem o tipo errado |
+| `CpfFmt::InvalidArgumentCombinationError` | `CpfFmt::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CpfFmt::Error`) | Uso indevido da API | Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CpfFormatter` / `cpf_fmt` |
+| `CpfFmt::TypeMismatchError` | `CpfFmt::TypeMismatchError < TypeError < StandardError` (+ `include CpfFmt::Error`) | Uso indevido da API | Entrada de CPF ou opção do formatador tem o tipo errado (ou o retorno de `on_fail` não é `String`) |
+| `CpfGen::InvalidArgumentCombinationError` | `CpfGen::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CpfGen::Error`) | Uso indevido da API | Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CpfGenerator` / `cpf_gen` |
+| `CpfGen::TypeMismatchError` | `CpfGen::TypeMismatchError < TypeError < StandardError` (+ `include CpfGen::Error`) | Uso indevido da API | Opção do gerador (`format` / `prefix`) tem o tipo errado |
+| `CpfUtils::InvalidArgumentCombinationError` | `CpfUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CpfUtils::Error`) | Uso indevido da API | Construtor: `Hash` de settings não-`nil` com qualquer argumento nomeado não-`nil`; ou `#format`/`#generate`/helpers de classe: `Hash`/instância `*Options` de options não-`nil` com qualquer argumento nomeado não-`nil` |
+| `CpfUtils::TypeMismatchError` | `CpfUtils::TypeMismatchError < TypeError < StandardError` (+ `include CpfUtils::Error`) | Uso indevido da API | Argumento `settings` não-`nil` de `CpfUtils.new` não é um `Hash` |
+| `CpfVal::TypeMismatchError` | `CpfVal::TypeMismatchError < TypeError < StandardError` (+ `include CpfVal::Error`) | Uso indevido da API | Entrada de CPF não é `String` nem `Array` de strings |
+| `CnpjFmt::InvalidLengthError` | `CnpjFmt::InvalidLengthError < CnpjFmt::DomainError < RangeError < StandardError` (+ `include CnpjFmt::Error`) | Erro de domínio | Comprimento sanitizado ≠ 14 — **passado a `on_fail`**, não lançado por `#format` |
+| `CnpjFmt::OutOfRangeError` | `CnpjFmt::OutOfRangeError < CnpjFmt::DomainError < RangeError < StandardError` (+ `include CnpjFmt::Error`) | Erro de domínio | `hidden_start` / `hidden_end` fora de `0`–`13` |
+| `CnpjFmt::ValidationError` | `CnpjFmt::ValidationError < CnpjFmt::DomainError < RangeError < StandardError` (+ `include CnpjFmt::Error`) | Erro de domínio | `hidden_key` / `dot_key` / `slash_key` / `dash_key` contém caractere proibido |
+| `CnpjGen::ValidationError` | `CnpjGen::ValidationError < CnpjGen::DomainError < RangeError < StandardError` (+ `include CnpjGen::Error`) | Erro de domínio | `prefix` inelegível, ou `type` fora de `'alphabetic'` / `'alphanumeric'` / `'numeric'` |
+| `CnpjVal::ValidationError` | `CnpjVal::ValidationError < CnpjVal::DomainError < RangeError < StandardError` (+ `include CnpjVal::Error`) | Erro de domínio | `type` do validador não é `'alphanumeric'` nem `'numeric'` |
+| `CpfFmt::InvalidLengthError` | `CpfFmt::InvalidLengthError < CpfFmt::DomainError < RangeError < StandardError` (+ `include CpfFmt::Error`) | Erro de domínio | Comprimento sanitizado ≠ 11 — **passado a `on_fail`**, não lançado por `#format` |
+| `CpfFmt::OutOfRangeError` | `CpfFmt::OutOfRangeError < CpfFmt::DomainError < RangeError < StandardError` (+ `include CpfFmt::Error`) | Erro de domínio | `hidden_start` / `hidden_end` fora de `0`–`10` |
+| `CpfFmt::ValidationError` | `CpfFmt::ValidationError < CpfFmt::DomainError < RangeError < StandardError` (+ `include CpfFmt::Error`) | Erro de domínio | `hidden_key` / `dot_key` / `dash_key` contém caractere proibido |
+| `CpfGen::ValidationError` | `CpfGen::ValidationError < CpfGen::DomainError < RangeError < StandardError` (+ `include CpfGen::Error`) | Erro de domínio | `prefix` inelegível (base zerada ou 9 dígitos repetidos) |
+
+##### `CpfFmt::DomainError`
+
+- **Herança:** `CpfFmt::DomainError < RangeError < StandardError` (inclui `CpfFmt::Error`)
+- **Categoria:** Erro de domínio — ancestral das folhas de domínio do formatador.
+- **Quando é lançado:** Não é lançado diretamente; alvo de rescue para `OutOfRangeError`, `ValidationError` e `InvalidLengthError` relançado.
+- **Exemplo:** Prefira resgatar uma folha, ou `CpfFmt::DomainError` para todas as falhas de domínio do formatador de CPF.
+- **Como resgatar:**
+
+```ruby
+rescue CpfFmt::DomainError
+  # OutOfRangeError, ValidationError, InvalidLengthError (se relançado a partir de on_fail)
+```
+
+##### `CpfFmt::TypeMismatchError`
+
+- **Herança:** `CpfFmt::TypeMismatchError < TypeError < StandardError` (inclui `CpfFmt::Error`)
+- **Categoria:** Uso indevido da API — tipo errado para entrada de CPF ou opção do formatador.
+- **Quando é lançado:** Lançado quando `#format` / `cpf_fmt` recebe entrada que não é `String` / `Array<String>`, uma opção tem o tipo errado, ou `on_fail` não retorna `String`.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cpf.format(12_345)   # lança CpfFmt::TypeMismatchError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfFmt::TypeMismatchError
+  # violação de contrato de tipo do formatador
+
+rescue TypeError
+  # erros nativos de tipo, incluindo CpfFmt::TypeMismatchError
+```
+
+##### `CpfFmt::InvalidArgumentCombinationError`
+
+- **Herança:** `CpfFmt::InvalidArgumentCombinationError < ArgumentError < StandardError` (inclui `CpfFmt::Error`)
+- **Categoria:** Uso indevido da API — `options` e argumentos nomeados misturados na API do formatador.
+- **Quando é lançado:** Lançado por `CpfFmt::CpfFormatter` / `CpfFmt.cpf_fmt` quando uma instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` são passados juntos. (O agregador de CPF lança `CpfUtils::InvalidArgumentCombinationError` para o mesmo padrão em `CpfUtils#format`.)
+- **Exemplo:**
+
+```ruby
+CpfFmt::CpfFormatter.new({ dash_key: '_' }, hidden: true)
+# lança CpfFmt::InvalidArgumentCombinationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfFmt::InvalidArgumentCombinationError
+  # combinação inválida de assinatura do formatador
+
+rescue ArgumentError
+  # erros nativos de argumento, incluindo este
+```
+
+##### `CpfFmt::InvalidLengthError` (entregue via callback)
+
+- **Herança:** `CpfFmt::InvalidLengthError < CpfFmt::DomainError < RangeError < StandardError` (inclui `CpfFmt::Error`)
+- **Categoria:** Erro de domínio — o comprimento sanitizado do CPF não é exatamente 11.
+- **Quando é lançado:** **Não é lançado** por `#format` / `cpf_fmt`; construído e passado como segundo argumento a `on_fail`.
+- **Exemplo:**
+
+```ruby
+custom_fail = ->(value, error) {
+  error   # => #<CpfFmt::InvalidLengthError ...>
+  "Invalid CPF: #{value}"
+}
+
+BrUtils.new.cpf.format('123', on_fail: custom_fail)   # => "Invalid CPF: 123"
+BrUtils.new.cpf.format('123')                         # => "" (on_fail padrão)
+```
+
+- **Como resgatar:** Trate dentro de `on_fail` (típico), ou faça rescue se relançar:
+
+```ruby
+rescue CpfFmt::InvalidLengthError
+  # esta violação exata de comprimento
+
+rescue CpfFmt::DomainError
+  # falhas de domínio com raiz em RangeError de cpf-fmt
+```
+
+##### `CpfFmt::OutOfRangeError`
+
+- **Herança:** `CpfFmt::OutOfRangeError < CpfFmt::DomainError < RangeError < StandardError` (inclui `CpfFmt::Error`)
+- **Categoria:** Erro de domínio — `hidden_start` / `hidden_end` fora de `0`–`10`.
+- **Quando é lançado:** Lançado ao construir ou aplicar opções do formatador com índice de ocultação fora do intervalo.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cpf.format('12345678909', hidden_start: -1)   # lança CpfFmt::OutOfRangeError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfFmt::OutOfRangeError
+  # esta violação exata de intervalo
+
+rescue CpfFmt::DomainError
+  # falhas de domínio com raiz em RangeError de cpf-fmt
+```
+
+##### `CpfFmt::ValidationError`
+
+- **Herança:** `CpfFmt::ValidationError < CpfFmt::DomainError < RangeError < StandardError` (inclui `CpfFmt::Error`)
+- **Categoria:** Erro de domínio — uma opção de chave contém um caractere proibido.
+- **Quando é lançado:** Lançado quando `hidden_key`, `dot_key` ou `dash_key` contém um caractere proibido.
+- **Exemplo:**
+
+```ruby
+BrUtils.new(cpf: { formatter: { dot_key: 'å' } })   # lança CpfFmt::ValidationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfFmt::ValidationError
+  # esta falha exata de validação de domínio
+
+rescue CpfFmt::DomainError
+  # falhas de domínio com raiz em RangeError de cpf-fmt
+```
+
+##### `CpfGen::DomainError`
+
+- **Herança:** `CpfGen::DomainError < RangeError < StandardError` (inclui `CpfGen::Error`)
+- **Categoria:** Erro de domínio — ancestral das folhas de domínio do gerador.
+- **Quando é lançado:** Não é lançado diretamente; alvo de rescue para `CpfGen::ValidationError`.
+- **Exemplo:** Prefira `rescue CpfGen::ValidationError` ou `CpfGen::DomainError`.
+- **Como resgatar:**
+
+```ruby
+rescue CpfGen::DomainError
+  # ValidationError e outras subclasses de DomainError de cpf-gen
+```
+
+##### `CpfGen::TypeMismatchError`
+
+- **Herança:** `CpfGen::TypeMismatchError < TypeError < StandardError` (inclui `CpfGen::Error`)
+- **Categoria:** Uso indevido da API — tipo errado para uma opção do gerador.
+- **Quando é lançado:** Lançado quando `format` ou `prefix` tem o tipo de runtime errado.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cpf.generate(prefix: 123)   # lança CpfGen::TypeMismatchError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfGen::TypeMismatchError
+  # violação de contrato de tipo do gerador
+
+rescue TypeError
+  # erros nativos de tipo, incluindo CpfGen::TypeMismatchError
+```
+
+##### `CpfGen::InvalidArgumentCombinationError`
+
+- **Herança:** `CpfGen::InvalidArgumentCombinationError < ArgumentError < StandardError` (inclui `CpfGen::Error`)
+- **Categoria:** Uso indevido da API — `options` e argumentos nomeados misturados na API do gerador.
+- **Quando é lançado:** Lançado por `CpfGen::CpfGenerator` / `CpfGen.cpf_gen` quando uma instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` são passados juntos. (O agregador de CPF lança `CpfUtils::InvalidArgumentCombinationError` para o mesmo padrão em `CpfUtils#generate`.)
+- **Exemplo:**
+
+```ruby
+CpfGen::CpfGenerator.new({ format: true }, prefix: '123')
+# lança CpfGen::InvalidArgumentCombinationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfGen::InvalidArgumentCombinationError
+  # combinação inválida de assinatura do gerador
+
+rescue ArgumentError
+  # erros nativos de argumento, incluindo este
+```
+
+##### `CpfGen::ValidationError`
+
+- **Herança:** `CpfGen::ValidationError < CpfGen::DomainError < RangeError < StandardError` (inclui `CpfGen::Error`)
+- **Categoria:** Erro de domínio — `prefix` inelegível.
+- **Quando é lançado:** Lançado quando `prefix` é uma base zerada (`'000000000'`) ou 9 dígitos repetidos (ex.: `'999999999'`).
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cpf.generate(prefix: '000000000')   # lança CpfGen::ValidationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfGen::ValidationError
+  # esta falha exata de validação de domínio
+
+rescue CpfGen::DomainError
+  # falhas de domínio com raiz em RangeError de cpf-gen
+```
+
+##### `CpfVal::TypeMismatchError`
+
+- **Herança:** `CpfVal::TypeMismatchError < TypeError < StandardError` (inclui `CpfVal::Error`)
+- **Categoria:** Uso indevido da API — tipo errado para entrada de CPF.
+- **Quando é lançado:** Lançado quando `#is_valid` / `cpf_val` recebe um valor que não é `String` nem `Array` de strings (incluindo elemento de array que não é string). **Dados** de CPF inválidos retornam `false` e não lançam.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cpf.is_valid(12_345_678_909)   # lança CpfVal::TypeMismatchError
+BrUtils.new.cpf.is_valid('12345678900')    # => false (dados inválidos, sem raise)
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfVal::TypeMismatchError
+  # violação de contrato de tipo do validador
+
+rescue TypeError
+  # erros nativos de tipo, incluindo CpfVal::TypeMismatchError
+```
+
+##### `CnpjFmt::DomainError`
+
+- **Herança:** `CnpjFmt::DomainError < RangeError < StandardError` (inclui `CnpjFmt::Error`)
+- **Categoria:** Erro de domínio — ancestral das folhas de domínio do formatador.
+- **Quando é lançado:** Não é lançado diretamente; alvo de rescue para `OutOfRangeError`, `ValidationError` e `InvalidLengthError` relançado.
+- **Exemplo:** Prefira resgatar uma folha, ou `CnpjFmt::DomainError` para todas as falhas de domínio do formatador de CNPJ.
+- **Como resgatar:**
+
+```ruby
+rescue CnpjFmt::DomainError
+  # OutOfRangeError, ValidationError, InvalidLengthError (se relançado a partir de on_fail)
+```
+
+##### `CnpjFmt::TypeMismatchError`
+
+- **Herança:** `CnpjFmt::TypeMismatchError < TypeError < StandardError` (inclui `CnpjFmt::Error`)
+- **Categoria:** Uso indevido da API — tipo errado para entrada de CNPJ ou opção do formatador.
+- **Quando é lançado:** Lançado quando `#format` / `cnpj_fmt` recebe entrada que não é `String` / `Array<String>`, uma opção tem o tipo errado, ou `on_fail` não retorna `String`.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cnpj.format(12_345)   # lança CnpjFmt::TypeMismatchError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjFmt::TypeMismatchError
+  # violação de contrato de tipo do formatador
+
+rescue TypeError
+  # erros nativos de tipo, incluindo CnpjFmt::TypeMismatchError
+```
+
+##### `CnpjFmt::InvalidArgumentCombinationError`
+
+- **Herança:** `CnpjFmt::InvalidArgumentCombinationError < ArgumentError < StandardError` (inclui `CnpjFmt::Error`)
+- **Categoria:** Uso indevido da API — `options` e argumentos nomeados misturados na API do formatador.
+- **Quando é lançado:** Lançado por `CnpjFmt::CnpjFormatter` / `CnpjFmt.cnpj_fmt` quando uma instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` são passados juntos. (O agregador de CNPJ lança `CnpjUtils::InvalidArgumentCombinationError` para o mesmo padrão em `CnpjUtils#format`.)
+- **Exemplo:**
+
+```ruby
+CnpjFmt::CnpjFormatter.new({ slash_key: '|' }, hidden: true)
+# lança CnpjFmt::InvalidArgumentCombinationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjFmt::InvalidArgumentCombinationError
+  # combinação inválida de assinatura do formatador
+
+rescue ArgumentError
+  # erros nativos de argumento, incluindo este
+```
+
+##### `CnpjFmt::InvalidLengthError` (entregue via callback)
+
+- **Herança:** `CnpjFmt::InvalidLengthError < CnpjFmt::DomainError < RangeError < StandardError` (inclui `CnpjFmt::Error`)
+- **Categoria:** Erro de domínio — o comprimento sanitizado do CNPJ não é exatamente 14.
+- **Quando é lançado:** **Não é lançado** por `#format` / `cnpj_fmt`; construído e passado como segundo argumento a `on_fail`.
+- **Exemplo:**
+
+```ruby
+custom_fail = ->(value, error) {
+  error   # => #<CnpjFmt::InvalidLengthError ...>
+  "Invalid CNPJ: #{value}"
+}
+
+BrUtils.new.cnpj.format('123', on_fail: custom_fail)   # => "Invalid CNPJ: 123"
+BrUtils.new.cnpj.format('123')                         # => "" (on_fail padrão)
+```
+
+- **Como resgatar:** Trate dentro de `on_fail` (típico), ou faça rescue se relançar:
+
+```ruby
+rescue CnpjFmt::InvalidLengthError
+  # esta violação exata de comprimento
+
+rescue CnpjFmt::DomainError
+  # falhas de domínio com raiz em RangeError de cnpj-fmt
+```
+
+##### `CnpjFmt::OutOfRangeError`
+
+- **Herança:** `CnpjFmt::OutOfRangeError < CnpjFmt::DomainError < RangeError < StandardError` (inclui `CnpjFmt::Error`)
+- **Categoria:** Erro de domínio — `hidden_start` / `hidden_end` fora de `0`–`13`.
+- **Quando é lançado:** Lançado ao construir ou aplicar opções do formatador com índice de ocultação fora do intervalo.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cnpj.format('91415732000793', hidden_start: -1)   # lança CnpjFmt::OutOfRangeError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjFmt::OutOfRangeError
+  # esta violação exata de intervalo
+
+rescue CnpjFmt::DomainError
+  # falhas de domínio com raiz em RangeError de cnpj-fmt
+```
+
+##### `CnpjFmt::ValidationError`
+
+- **Herança:** `CnpjFmt::ValidationError < CnpjFmt::DomainError < RangeError < StandardError` (inclui `CnpjFmt::Error`)
+- **Categoria:** Erro de domínio — uma opção de chave contém um caractere proibido.
+- **Quando é lançado:** Lançado quando `hidden_key`, `dot_key`, `slash_key` ou `dash_key` contém um caractere proibido.
+- **Exemplo:**
+
+```ruby
+BrUtils.new(cnpj: { formatter: { slash_key: 'å' } })   # lança CnpjFmt::ValidationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjFmt::ValidationError
+  # esta falha exata de validação de domínio
+
+rescue CnpjFmt::DomainError
+  # falhas de domínio com raiz em RangeError de cnpj-fmt
+```
+
+##### `CnpjGen::DomainError`
+
+- **Herança:** `CnpjGen::DomainError < RangeError < StandardError` (inclui `CnpjGen::Error`)
+- **Categoria:** Erro de domínio — ancestral das folhas de domínio do gerador.
+- **Quando é lançado:** Não é lançado diretamente; alvo de rescue para `CnpjGen::ValidationError`.
+- **Exemplo:** Prefira `rescue CnpjGen::ValidationError` ou `CnpjGen::DomainError`.
+- **Como resgatar:**
+
+```ruby
+rescue CnpjGen::DomainError
+  # ValidationError e outras subclasses de DomainError de cnpj-gen
+```
+
+##### `CnpjGen::TypeMismatchError`
+
+- **Herança:** `CnpjGen::TypeMismatchError < TypeError < StandardError` (inclui `CnpjGen::Error`)
+- **Categoria:** Uso indevido da API — tipo errado para uma opção do gerador.
+- **Quando é lançado:** Lançado quando `format`, `prefix` ou `type` tem o tipo de runtime errado.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cnpj.generate(prefix: 123)   # lança CnpjGen::TypeMismatchError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjGen::TypeMismatchError
+  # violação de contrato de tipo do gerador
+
+rescue TypeError
+  # erros nativos de tipo, incluindo CnpjGen::TypeMismatchError
+```
+
+##### `CnpjGen::InvalidArgumentCombinationError`
+
+- **Herança:** `CnpjGen::InvalidArgumentCombinationError < ArgumentError < StandardError` (inclui `CnpjGen::Error`)
+- **Categoria:** Uso indevido da API — `options` e argumentos nomeados misturados na API do gerador.
+- **Quando é lançado:** Lançado por `CnpjGen::CnpjGenerator` / `CnpjGen.cnpj_gen` quando uma instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` são passados juntos. (O agregador de CNPJ lança `CnpjUtils::InvalidArgumentCombinationError` para o mesmo padrão em `CnpjUtils#generate`.)
+- **Exemplo:**
+
+```ruby
+CnpjGen::CnpjGenerator.new({ format: true }, prefix: '123')
+# lança CnpjGen::InvalidArgumentCombinationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjGen::InvalidArgumentCombinationError
+  # combinação inválida de assinatura do gerador
+
+rescue ArgumentError
+  # erros nativos de argumento, incluindo este
+```
+
+##### `CnpjGen::ValidationError`
+
+- **Herança:** `CnpjGen::ValidationError < CnpjGen::DomainError < RangeError < StandardError` (inclui `CnpjGen::Error`)
+- **Categoria:** Erro de domínio — `prefix` inelegível ou `type` não permitido.
+- **Quando é lançado:** Lançado quando `prefix` é base/filial zerada ou 12 dígitos repetidos, ou quando `type` não é `'alphabetic'`, `'alphanumeric'` ou `'numeric'`.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cnpj.generate(type: 'boolean')   # lança CnpjGen::ValidationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjGen::ValidationError
+  # esta falha exata de validação de domínio
+
+rescue CnpjGen::DomainError
+  # falhas de domínio com raiz em RangeError de cnpj-gen
+```
+
+##### `CnpjVal::DomainError`
+
+- **Herança:** `CnpjVal::DomainError < RangeError < StandardError` (inclui `CnpjVal::Error`)
+- **Categoria:** Erro de domínio — ancestral das folhas de domínio do validador.
+- **Quando é lançado:** Não é lançado diretamente; alvo de rescue para `CnpjVal::ValidationError`.
+- **Exemplo:** Prefira `rescue CnpjVal::ValidationError` ou `CnpjVal::DomainError`.
+- **Como resgatar:**
+
+```ruby
+rescue CnpjVal::DomainError
+  # ValidationError e outras subclasses de DomainError de cnpj-val
+```
+
+##### `CnpjVal::TypeMismatchError`
+
+- **Herança:** `CnpjVal::TypeMismatchError < TypeError < StandardError` (inclui `CnpjVal::Error`)
+- **Categoria:** Uso indevido da API — tipo errado para entrada de CNPJ ou opção do validador.
+- **Quando é lançado:** Lançado quando `#is_valid` / `cnpj_val` recebe um valor que não é `String` nem `Array` de strings, ou uma opção do validador tem o tipo errado. **Dados** de CNPJ inválidos retornam `false` e não lançam.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cnpj.is_valid(12_345_678_000_198)   # lança CnpjVal::TypeMismatchError
+BrUtils.new.cnpj.is_valid('00000000000000')     # => false (dados inválidos, sem raise)
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjVal::TypeMismatchError
+  # violação de contrato de tipo do validador
+
+rescue TypeError
+  # erros nativos de tipo, incluindo CnpjVal::TypeMismatchError
+```
+
+##### `CnpjVal::InvalidArgumentCombinationError`
+
+- **Herança:** `CnpjVal::InvalidArgumentCombinationError < ArgumentError < StandardError` (inclui `CnpjVal::Error`)
+- **Categoria:** Uso indevido da API — `options` e argumentos nomeados misturados na API do validador.
+- **Quando é lançado:** Lançado por `CnpjVal::CnpjValidator` / `CnpjVal.cnpj_val` quando uma instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` são passados juntos. (O agregador de CNPJ lança `CnpjUtils::InvalidArgumentCombinationError` para o mesmo padrão em `CnpjUtils#is_valid`.)
+- **Exemplo:**
+
+```ruby
+CnpjVal.cnpj_val('98765432000198', { type: 'numeric' }, case_sensitive: false)
+# lança CnpjVal::InvalidArgumentCombinationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjVal::InvalidArgumentCombinationError
+  # combinação inválida de assinatura do validador
+
+rescue ArgumentError
+  # erros nativos de argumento, incluindo este
+```
+
+##### `CnpjVal::ValidationError`
+
+- **Herança:** `CnpjVal::ValidationError < CnpjVal::DomainError < RangeError < StandardError` (inclui `CnpjVal::Error`)
+- **Categoria:** Erro de domínio — `type` do validador não permitido.
+- **Quando é lançado:** Lançado quando `type` não é `'alphanumeric'` nem `'numeric'`.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cnpj.is_valid('91415732000793', type: 'boolean')   # lança CnpjVal::ValidationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjVal::ValidationError
+  # esta falha exata de validação de domínio
+
+rescue CnpjVal::DomainError
+  # falhas de domínio com raiz em RangeError de cnpj-val
+```
+
+##### `CpfUtils::TypeMismatchError`
+
+- **Herança:** `CpfUtils::TypeMismatchError < TypeError < StandardError` (inclui `CpfUtils::Error`)
+- **Categoria:** Uso indevido da API — o caller passou um valor do tipo errado.
+- **Quando é lançado:** Quando `CpfUtils.new` recebe um argumento `settings` não-`nil` que não é um `Hash`.
+- **Exemplo:**
+
+```ruby
+CpfUtils.new('not-a-hash')   # lança CpfUtils::TypeMismatchError
+CpfUtils.new(false)          # lança CpfUtils::TypeMismatchError (false é não-nil)
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfUtils::TypeMismatchError
+  # violação de contrato de tipo do agregador de CPF (não BrUtils::Error)
+
+rescue TypeError
+  # erros nativos de tipo, incluindo CpfUtils::TypeMismatchError
+```
+
+##### `CpfUtils::InvalidArgumentCombinationError`
+
+- **Herança:** `CpfUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (inclui `CpfUtils::Error`)
+- **Categoria:** Uso indevido da API — o caller misturou padrões de argumentos mutuamente exclusivos.
+- **Quando é lançado:** Quando `CpfUtils.new` recebe um `Hash` de settings não-`nil` e qualquer argumento nomeado não-`nil`, ou quando `#format` / `#generate` misturam um `Hash`/`*Options` de options não-`nil` com qualquer argumento nomeado não-`nil`. `#is_valid` não tem caminho de options e não lança este erro.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cpf.format({ hidden: true }, dash_key: '|')
+# lança CpfUtils::InvalidArgumentCombinationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CpfUtils::InvalidArgumentCombinationError
+  # combinação inválida de assinatura do agregador de CPF (não BrUtils::Error)
+
+rescue ArgumentError
+  # erros nativos de argumento, incluindo CpfUtils::InvalidArgumentCombinationError
+```
+
+##### `CnpjUtils::TypeMismatchError`
+
+- **Herança:** `CnpjUtils::TypeMismatchError < TypeError < StandardError` (inclui `CnpjUtils::Error`)
+- **Categoria:** Uso indevido da API — o caller passou um valor do tipo errado.
+- **Quando é lançado:** Quando `CnpjUtils.new` recebe um argumento `settings` não-`nil` que não é um `Hash`.
+- **Exemplo:**
+
+```ruby
+CnpjUtils.new('not-a-hash')   # lança CnpjUtils::TypeMismatchError
+CnpjUtils.new(false)          # lança CnpjUtils::TypeMismatchError (false é não-nil)
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjUtils::TypeMismatchError
+  # violação de contrato de tipo do agregador de CNPJ (não BrUtils::Error)
+
+rescue TypeError
+  # erros nativos de tipo, incluindo CnpjUtils::TypeMismatchError
+```
+
+##### `CnpjUtils::InvalidArgumentCombinationError`
+
+- **Herança:** `CnpjUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (inclui `CnpjUtils::Error`)
+- **Categoria:** Uso indevido da API — o caller misturou padrões de argumentos mutuamente exclusivos.
+- **Quando é lançado:** Quando `CnpjUtils.new`, `#format`, `#generate`, `#is_valid` ou os helpers de classe recebem um `Hash`/instância de settings/options não-`nil` e qualquer argumento nomeado não-`nil` ao mesmo tempo.
+- **Exemplo:**
+
+```ruby
+BrUtils.new.cnpj.format({ hidden: true }, slash_key: '|')
+# lança CnpjUtils::InvalidArgumentCombinationError
+```
+
+- **Como resgatar:**
+
+```ruby
+rescue CnpjUtils::InvalidArgumentCombinationError
+  # combinação inválida de assinatura do agregador de CNPJ (não BrUtils::Error)
+
+rescue ArgumentError
+  # erros nativos de argumento, incluindo CnpjUtils::InvalidArgumentCombinationError
+```
+
+### Pacotes incluídos
+
+| Pacote | Principais recursos | README |
+|---------|----------------|--------|
+| [`cpf-utilities`](https://rubygems.org/gems/cpf-utilities) | `CpfUtils`, `CpfFormatter`, `CpfGenerator`, `CpfValidator`, `CpfFmt.cpf_fmt`, `CpfGen.cpf_gen`, `CpfVal.cpf_val` | [docs](../cpf-utilities/README.pt.md) |
+| [`cnpj-utilities`](https://rubygems.org/gems/cnpj-utilities) | `CnpjUtils`, `CnpjFormatter`, `CnpjGenerator`, `CnpjValidator`, `CnpjFmt.cnpj_fmt`, `CnpjGen.cnpj_gen`, `CnpjVal.cnpj_val` | [docs](../cnpj-utilities/README.pt.md) |
+
+Todos os acima são puxados como dependências de **`br-utilities`**. Demos interativas: [CPF](https://cpf-utils.vercel.app/) e [CNPJ](https://cnpj-utils.vercel.app/).
+
+## 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)