@br-validators/core 0.12.0-alpha.2 → 0.12.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +145 -137
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,110 +1,63 @@
1
1
  # @br-validators/core
2
2
 
3
- 100% open-source Brazilian document validators (MIT). Pure TypeScript — no HTTP lookups, no frameworks.
3
+ > **The** Brazilian document validation library for TypeScript.
4
+ > Validate, format, and generate CPF, CNPJ (including the new alphanumeric format), NF-e, BR Code PIX, boleto, IE (all 27 states), and 15+ more — zero dependencies, fully typed, never throws.
4
5
 
5
- **npm:** [`@br-validators/core`](https://www.npmjs.com/package/@br-validators/core)
6
- **Repo:** [github.com/AlexandreZanata/br-validators](https://github.com/AlexandreZanata/br-validators)
7
- **Playground:** [doc-raiz-playground.vercel.app](https://doc-raiz-playground.vercel.app/)
8
-
9
- > The unscoped name `br-validators` on npm is a **different package**. Use **`@br-validators/core`**.
10
-
11
- ---
12
-
13
- ## Install
6
+ [![npm](https://img.shields.io/npm/v/@br-validators/core)](https://www.npmjs.com/package/@br-validators/core)
7
+ [![MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/AlexandreZanata/br-validators/blob/main/LICENSE)
8
+ [![Node ≥ 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)]()
14
9
 
15
10
  ```bash
16
11
  npm install @br-validators/core
17
12
  ```
18
13
 
19
- Requires Node ≥ 18. ESM only (`"type": "module"`).
14
+ **Try it now → [doc-raiz-playground.vercel.app](https://doc-raiz-playground.vercel.app)**
15
+ **CLI → `npm install -g @br-validators/cli`**
20
16
 
21
- ---
17
+ > ⚠️ The unscoped `br-validators` on npm is a different package. Use **`@br-validators/core`**.
22
18
 
23
- ## Platform APIs
19
+ ---
24
20
 
25
- Cross-cutting helpers that **compose existing validators** — never duplicate check-digit logic.
21
+ ## Why this library
26
22
 
27
- | API | Import | Purpose |
28
- |-----|--------|---------|
29
- | **`detect()`** | `@br-validators/core/detect` | Classify raw input (priority router over all shipped types) |
30
- | **`sanitize()`** | `@br-validators/core/sanitize` | ETL fixes → validate (returns `fixes[]`) |
31
- | **`generate()`** | `@br-validators/core/generate` | Synthetic **test fixtures** only (`seed` for reproducibility) |
23
+ Every Brazilian SaaS eventually reinvents CPF validation — usually wrong.
24
+ `@br-validators/core` implements each algorithm from its **official primary source**
25
+ (Receita Federal, Bacen, CONTRAN, TSE, SEFAZ, FEBRABAN, Anatel) so you don't have to.
32
26
 
33
- ```typescript
34
- import { detect, sanitize, generate } from '@br-validators/core';
35
- import { validateCpf } from '@br-validators/core/cpf';
27
+ - ✅ **CNPJ alfanumérico** — new RFB format (effective July 2026), ready now
28
+ - ✅ **18 document types** — CPF, CNPJ, CEP, NF-e chave, BR Code PIX, boleto, CNH, RENAVAM, placa, PIS/PASEP, PIX key, cartão de crédito, IE (27 UFs), IE produtor rural, título de eleitor, telefone, + platform APIs
29
+ - ✅ **Zero runtime dependencies** — pure TypeScript logic, no HTTP calls
30
+ - ✅ **Never throws** — every function returns `{ ok: true, value } | { ok: false, message, code }`
31
+ - ✅ **Tree-shakeable** — subpath imports per document type
32
+ - ✅ **ESM only**, Node ≥ 18, works in browser, Bun, Deno
36
33
 
37
- // Auto-detect document type
38
- detect('123.456.789-09');
39
- // → { type: 'cpf', ok: true, value: '12345678909', format: 'numeric' }
34
+ ---
40
35
 
41
- detect('110042490114', { uf: 'SP' });
42
- // → { type: 'inscricao-estadual', ok: true, ... }
36
+ ## Quick start
43
37
 
44
- // Messy ETL input → canonical + fix audit trail
45
- sanitize(' 123.456.789-09 ', 'cpf');
46
- // → { ok: true, value: '12345678909', fixes: ['trimmed', 'removed_non_digits'] }
38
+ ```typescript
39
+ import { validateCpf, formatCpf } from '@br-validators/core';
47
40
 
48
- sanitize('110.042.490.114', 'inscricao-estadual', { uf: 'SP' });
49
- // → { ok: true, value: '110042490114', fixes: [...] }
41
+ validateCpf('123.456.789-09');
42
+ // { ok: true, value: '12345678909' }
50
43
 
51
- // Synthetic valid documents for tests (never production IDs)
52
- const cpf = generate('cpf', { seed: 42 });
53
- validateCpf(cpf).ok; // true
44
+ formatCpf('12345678909');
45
+ // { ok: true, formatted: '123.456.789-09' }
54
46
 
55
- generate('cnpj', { format: 'alphanumeric', masked: true, seed: 7 });
56
- generate('placa', { format: 'mercosul', seed: 3 });
47
+ validateCpf('111.111.111-11');
48
+ // { ok: false, message: 'CPF with all identical digits is invalid', code: 'KNOWN_INVALID_PATTERN' }
57
49
  ```
58
50
 
59
- **Detect notes:** 11-digit bucket tries CPF → CNH → PIS (RENAVAM equivalent DV may classify as `pis-pasep`). IE detection requires `{ uf }`. 48-digit boleto arrecadação is skipped.
60
-
61
- **Generate policy:** 9 types — CPF, CNPJ, CEP, placa, PIS, RENAVAM, CNH, telefone, cartão. Excludes boleto, NF-e chave, IE, BR Code, PIX.
62
-
63
- ---
64
-
65
- ## Per-type validators
66
-
67
- Every module exposes `validate*`, `format*`, `strip*` (where applicable). All return `ValidationResult` — **never throw** on invalid input.
68
-
69
- | Subpath | Key functions | Golden vector |
70
- |---------|---------------|---------------|
71
- | `./cnpj` | `validateCnpj`, `formatCnpj`, `stripCnpj` | `12ABC34501DE35` (alphanumeric) |
72
- | `./cpf` | `validateCpf`, `formatCpf`, `stripCpf` | `12345678909` |
73
- | `./cep` | `validateCep`, `formatCep`, `stripCep` | `01310100` |
74
- | `./telefone` | `validateTelefone`, `formatTelefone`, `stripTelefone` | `11999999999` (celular) |
75
- | `./cnh` | `validateCnh`, `formatCnh`, `stripCnh` | `62472927637` (11 digits, no CPF mask) |
76
- | `./renavam` | `validateRenavam`, `formatRenavam`, `stripRenavam` | `63977791104` |
77
- | `./titulo-eleitor` | `validateTituloEleitor`, `formatTituloEleitor`, `stripTituloEleitor` | `004356870906` |
78
- | `./nfe-chave` | `validateNfeChave`, `parseNfeChave`, `formatNfeChave` | `52060433009911002506550120000007800267301615` |
79
- | `./brcode` | `validateBrCode`, `parseBrCode` | EMV PIX payload (CRC16) |
80
- | `./placa` | `validatePlaca`, `formatPlaca`, `convertPlacaToMercosul` | `ABC1D23` (Mercosul), `ABC1234` (legacy) |
81
- | `./pis-pasep` | `validatePisPasep`, `formatPisPasep`, `stripPisPasep` | `10027230888` |
82
- | `./pix` | `validatePixKey`, `formatPixKey`, `detectPixKeyType` | `pix@bcb.gov.br` |
83
- | `./boleto` | `validateBoleto`, `formatBoleto`, `convertLinhaToCodigoBarras` | Situação 1 + 2 (FEBRABAN) |
84
- | `./cartao-credito` | `validateCartaoCredito`, `passesLuhn`, `detectCardBrand` | `4111111111111111` |
85
- | `./inscricao-estadual` | `validateInscricaoEstadual`, `formatInscricaoEstadual` | `110042490114` (SP) — **27 UFs**, `{ uf }` required |
86
- | `./inscricao-estadual-produtor-rural` | `validateIeProdutorRural`, `validateIeSpRural` | `P011004243002` (SP Regra II) |
87
-
88
- Tree-shaking via subpaths:
51
+ ### CNPJ — numeric and alphanumeric (new RFB format)
89
52
 
90
53
  ```typescript
91
- import { validateCnpj } from '@br-validators/core/cnpj';
92
- import { validateNfeChave } from '@br-validators/core/nfe-chave';
93
- import { validateTituloEleitor } from '@br-validators/core/titulo-eleitor';
94
- import { validateBrCode } from '@br-validators/core/brcode';
95
- import { validateInscricaoEstadual } from '@br-validators/core/inscricao-estadual';
96
- import { validateIeProdutorRural } from '@br-validators/core/inscricao-estadual-produtor-rural';
97
- ```
98
-
99
- ---
54
+ import { validateCnpj, formatCnpj } from '@br-validators/core/cnpj';
100
55
 
101
- ## Examples
102
-
103
- ### CNPJ (numeric + alphanumeric)
104
-
105
- ```typescript
106
- import { validateCnpj, formatCnpj } from '@br-validators/core';
56
+ // Numeric (current format)
57
+ validateCnpj('11.222.333/0001-81');
58
+ // { ok: true, value: '11222333000181', format: 'numeric' }
107
59
 
60
+ // Alphanumeric (new format — effective July 2026)
108
61
  validateCnpj('12ABC34501DE35');
109
62
  // { ok: true, value: '12ABC34501DE35', format: 'alphanumeric' }
110
63
 
@@ -112,105 +65,160 @@ formatCnpj('12ABC34501DE35');
112
65
  // { ok: true, formatted: '12.ABC.345/01DE-35' }
113
66
  ```
114
67
 
115
- ### Inscrição Estadual (all 27 UFs)
68
+ ### Auto-detect document type
116
69
 
117
70
  ```typescript
118
- import { validateInscricaoEstadual } from '@br-validators/core/inscricao-estadual';
71
+ import { detect } from '@br-validators/core';
119
72
 
120
- validateInscricaoEstadual('110042490114', { uf: 'SP' });
121
- validateInscricaoEstadual('0730000100109', { uf: 'DF' });
122
- // getIeOfficialSourceUrl('SP') → SEFAZ primary URL
73
+ detect('123.456.789-09');
74
+ // { type: 'cpf', ok: true, value: '12345678909' }
75
+
76
+ detect('ABC1D23');
77
+ // { type: 'placa', ok: true, format: 'mercosul' }
78
+
79
+ detect('110042490114', { uf: 'SP' });
80
+ // { type: 'inscricao-estadual', ok: true }
123
81
  ```
124
82
 
125
- ### SP produtor rural (`P` prefix)
83
+ ### Generate valid documents for tests
126
84
 
127
85
  ```typescript
128
- import { validateIeProdutorRural } from '@br-validators/core/inscricao-estadual-produtor-rural';
86
+ import { generate } from '@br-validators/core';
87
+
88
+ generate('cpf', { seed: 42 }); // reproducible, always valid
89
+ generate('cnpj', { format: 'alphanumeric', masked: true });
90
+ generate('placa', { format: 'mercosul' });
91
+ generate('renavam');
92
+ generate('cnh');
93
+ generate('inscricao-estadual', { uf: 'SP', seed: 42 });
94
+ generate('titulo-eleitor', { uf: 'SC', seed: 42 });
95
+ generate('cartao-credito', { brand: 'visa', seed: 42 });
96
+ ```
97
+
98
+ > `generate()` is for test fixtures and seed data only — never use in production.
99
+
100
+ ### ETL / data cleanup
101
+
102
+ ```typescript
103
+ import { sanitize } from '@br-validators/core';
104
+
105
+ sanitize(' 123.456.789-09 ', 'cpf');
106
+ // { ok: true, value: '12345678909', fixes: ['trimmed', 'removed_non_digits'] }
129
107
 
130
- validateIeProdutorRural('SP', 'P-01100424.3/002');
131
- // { ok: true, value: 'P011004243002', ... }
108
+ sanitize('110.042.490.114', 'inscricao-estadual', { uf: 'SP' });
109
+ // { ok: true, value: '110042490114', fixes: [...] }
132
110
  ```
133
111
 
134
- ### NF-e / NFC-e chave de acesso (44 digits)
112
+ ### NF-e chave de acesso (44 digits)
135
113
 
136
114
  ```typescript
137
115
  import { validateNfeChave, parseNfeChave } from '@br-validators/core/nfe-chave';
138
116
 
139
117
  const result = validateNfeChave('52060433009911002506550120000007800267301615');
140
- // { ok: true, parsed: { cUF, cnpj, mod, serie, nNF, ... }, uf: 'GO' }
118
+ // { ok: true, parsed: { cUF: '52', cnpj: '33009911002506', mod: '55', ... }, uf: 'GO' }
141
119
  ```
142
120
 
143
121
  ### BR Code (PIX QR payload)
144
122
 
145
123
  ```typescript
146
- import { validateBrCode } from '@br-validators/core/brcode';
124
+ import { validateBrCode, parseBrCode } from '@br-validators/core/brcode';
147
125
 
148
- validateBrCode('00020126580014br.gov.bcb.pix0136...63041D3D');
149
- // { ok: true, pixKey, merchantName, merchantCity, ... }
126
+ parseBrCode('00020126580014br.gov.bcb.pix0136...');
127
+ // { ok: true, pixKey, pixKeyType, merchantName, merchantCity, amount, txid }
150
128
  ```
151
129
 
152
- ### Boleto (linha digitável ↔ código de barras)
130
+ ### Form handler (React / Next.js)
153
131
 
154
132
  ```typescript
155
- import { validateBoleto, convertLinhaToCodigoBarras } from '@br-validators/core/boleto';
156
-
157
- validateBoleto('03399.02579 08991.834006 71742.301014 6 14500000099668');
133
+ 'use client';
134
+ import { validateCnpj, formatCnpj } from '@br-validators/core/cnpj';
135
+ import { useState } from 'react';
136
+
137
+ export function CnpjField() {
138
+ const [input, setInput] = useState('');
139
+ const result = input ? validateCnpj(input) : null;
140
+ const formatted = result?.ok ? formatCnpj(result.value) : null;
141
+
142
+ return (
143
+ <div>
144
+ <input value={input} onChange={e => setInput(e.target.value)} />
145
+ {formatted?.ok && <p>✅ {formatted.formatted}</p>}
146
+ {result && !result.ok && <p>❌ {result.message}</p>}
147
+ </div>
148
+ );
149
+ }
158
150
  ```
159
151
 
160
- ---
161
-
162
- ## Official sources
163
-
164
- Every algorithm cites a primary government or standards body source (RFB, Bacen, CONTRAN, TSE, SEFAZ, FEBRABAN, ISO, Correios, Anatel, SIPREV).
165
-
166
- Full index: [docs/OFFICIAL-SOURCES.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/OFFICIAL-SOURCES.md)
167
-
168
- Per-type constants: `CNPJ_OFFICIAL_SOURCE_URL`, `NFE_CHAVE_OFFICIAL_SOURCE_URL`, `IE_OFFICIAL_SOURCE_URLS`, `BRCODE_OFFICIAL_SOURCE_URL`, etc.
152
+ ### Shell / CI
169
153
 
170
- Golden test vectors: `tests/vectors/*.official.json` in the repo.
154
+ ```bash
155
+ br-validators cnpj validate "$CNPJ" --quiet || exit 1
156
+ br-validators ie validate "$IE" --uf SP --json
157
+ br-validators detect '123.456.789-09' --json
158
+ br-validators generate cpf --seed 42 --masked
159
+ br-validators generate inscricao-estadual --uf SP --seed 42
160
+ br-validators generate cartao-credito --brand visa --seed 42
161
+ ```
171
162
 
172
163
  ---
173
164
 
174
- ## API reference
175
-
176
- | Doc | Content |
177
- |-----|---------|
178
- | [LIBRARY-API.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/LIBRARY-API.md) | Full signatures + platform APIs |
179
- | [VALIDATION-RULES.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/VALIDATION-RULES.md) | Business rules (BR-* IDs) |
180
- | [DELIVERY-SURFACES.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/DELIVERY-SURFACES.md) | Library + CLI + playground matrix |
165
+ ## All supported types
166
+
167
+ | Document | Subpath import | CLI | Playground |
168
+ |---|---|---|---|
169
+ | CPF | `@br-validators/core/cpf` | `br-validators cpf …` | `/cpf` |
170
+ | CNPJ (numeric + alphanumeric) | `@br-validators/core/cnpj` | `br-validators cnpj …` | `/cnpj` |
171
+ | CEP | `@br-validators/core/cep` | `br-validators cep …` | `/cep` |
172
+ | Telefone | `@br-validators/core/telefone` | `br-validators telefone …` | `/telefone` |
173
+ | CNH | `@br-validators/core/cnh` | `br-validators cnh …` | `/cnh` |
174
+ | RENAVAM | `@br-validators/core/renavam` | `br-validators renavam …` | `/renavam` |
175
+ | Título de Eleitor | `@br-validators/core/titulo-eleitor` | `br-validators titulo-eleitor …` | `/titulo-eleitor` |
176
+ | Placa (Mercosul + legada) | `@br-validators/core/placa` | `br-validators placa …` | `/placa` |
177
+ | PIS / PASEP / NIS | `@br-validators/core/pis-pasep` | `br-validators pis-pasep …` | `/pis` |
178
+ | PIX key | `@br-validators/core/pix` | `br-validators pix …` | `/pix` |
179
+ | BR Code (PIX QR payload) | `@br-validators/core/brcode` | `br-validators brcode …` | `/brcode` |
180
+ | Boleto (Situação 1 + 2) | `@br-validators/core/boleto` | `br-validators boleto …` | `/boleto` |
181
+ | NF-e / NFC-e chave (44 digits) | `@br-validators/core/nfe-chave` | `br-validators nfe-chave …` | `/nfe-chave` |
182
+ | Cartão de crédito (Luhn) | `@br-validators/core/cartao-credito` | `br-validators cartao …` | `/cartao-credito` |
183
+ | Inscrição Estadual (27 UFs) | `@br-validators/core/inscricao-estadual` | `br-validators ie … --uf SP` | `/ie` |
184
+ | IE Produtor Rural | `@br-validators/core/inscricao-estadual-produtor-rural` | `br-validators ie …` (auto-detect `P` prefix) | `/ie` |
185
+ | **detect()** | `@br-validators/core/detect` | `br-validators detect …` | `/detect` |
186
+ | **sanitize()** | `@br-validators/core/sanitize` | `br-validators sanitize …` | `/sanitize` |
187
+ | **generate()** | `@br-validators/core/generate` | `br-validators generate …` | `/generate` |
188
+
189
+ Full official sources per type: [docs/OFFICIAL-SOURCES.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/OFFICIAL-SOURCES.md)
181
190
 
182
191
  ---
183
192
 
184
- ## CLI companion
193
+ ## Tree-shaking
185
194
 
186
- ```bash
187
- npm install -g @br-validators/cli
188
-
189
- br-validators list
190
- br-validators cnpj validate 12ABC34501DE35 --json
191
- br-validators nfe-chave validate 52060433009911002506550120000007800267301615 --json
192
- br-validators titulo-eleitor validate 004356870906
193
- br-validators brcode validate '<emv-payload>'
194
- br-validators ie validate 110042490114 --uf SP
195
+ ```typescript
196
+ // Only ships the CPF module — nothing else
197
+ import { validateCpf } from '@br-validators/core/cpf';
195
198
 
196
- # Platform APIs
197
- br-validators detect '123.456.789-09' --json
198
- br-validators sanitize cpf ' 123.456.789-09 ' --json
199
- br-validators generate cpf --seed 42 --masked --json
199
+ // Only ships NF-e module
200
+ import { parseNfeChave } from '@br-validators/core/nfe-chave';
200
201
  ```
201
202
 
202
203
  ---
203
204
 
204
- ## Related packages (monorepo)
205
+ ## Related packages
205
206
 
206
207
  | Package | Status |
207
- |---------|--------|
208
- | `@br-validators/cli` | Published — terminal CLI |
209
- | `@br-validators/zod` | Workspace — Zod schemas (not on npm yet) |
210
- | `@br-validators/react-hook-form` | Workspace — RHF resolvers (not on npm yet) |
208
+ |---|---|
209
+ | [`@br-validators/cli`](https://www.npmjs.com/package/@br-validators/cli) | Published |
210
+ | `@br-validators/zod` | Coming soon — Zod schemas |
211
+ | `@br-validators/react-hook-form` | Coming soon — RHF resolvers |
212
+
213
+ ---
214
+
215
+ ## Contributing
216
+
217
+ Issues, corrections, and new document types are welcome.
218
+ See [CONTRIBUTING.md](https://github.com/AlexandreZanata/br-validators/blob/main/CONTRIBUTING.md) and open `good first issue` items.
211
219
 
212
220
  ---
213
221
 
214
222
  ## License
215
223
 
216
- MIT
224
+ [MIT](https://github.com/AlexandreZanata/br-validators/blob/main/LICENSE) — permanently free and open source.
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@br-validators/core",
3
- "version": "0.12.0-alpha.2",
4
- "description": "Brazilian document validators (MIT) — CPF, CNPJ, CEP, CNH, RENAVAM, NF-e chave, IE (27 UFs), PIX, boleto, BR Code + detect/sanitize/generate platform APIs",
3
+ "version": "0.12.0-alpha.3",
4
+ "description": "The Brazilian document validation library for TypeScript — CPF, CNPJ (alphanumeric), NF-e, PIX, boleto, IE (27 UFs), and 15+ more. Zero deps, fully typed, never throws.",
5
+ "homepage": "https://www.npmjs.com/package/@br-validators/core",
5
6
  "license": "MIT",
6
7
  "type": "module",
7
8
  "repository": {
@@ -9,7 +10,6 @@
9
10
  "url": "git+https://github.com/AlexandreZanata/br-validators.git",
10
11
  "directory": "packages/br-validators"
11
12
  },
12
- "homepage": "https://github.com/AlexandreZanata/br-validators/tree/main/packages/br-validators#readme",
13
13
  "bugs": {
14
14
  "url": "https://github.com/AlexandreZanata/br-validators/issues"
15
15
  },