@br-validators/core 0.12.0-alpha.0 → 0.12.0-alpha.1

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 +149 -27
  2. package/package.json +16 -4
package/README.md CHANGED
@@ -1,11 +1,12 @@
1
1
  # @br-validators/core
2
2
 
3
- 100% open-source Brazilian document validators (MIT).
3
+ 100% open-source Brazilian document validators (MIT). Pure TypeScript — no HTTP lookups, no frameworks.
4
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)
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/)
7
8
 
8
- > The unscoped name `br-validators` on npm is a different package. Use **`@br-validators/core`**.
9
+ > The unscoped name `br-validators` on npm is a **different package**. Use **`@br-validators/core`**.
9
10
 
10
11
  ---
11
12
 
@@ -19,64 +20,164 @@ Requires Node ≥ 18. ESM only (`"type": "module"`).
19
20
 
20
21
  ---
21
22
 
22
- ## Supported types
23
-
24
- | Module | Functions | Golden vector |
25
- |--------|-----------|---------------|
26
- | CNPJ | `validateCnpj`, `formatCnpj`, `stripCnpj` | `12ABC34501DE35` |
27
- | CPF | `validateCpf`, `formatCpf`, `stripCpf` | `12345678909` |
28
- | CEP | `validateCep`, `formatCep`, `stripCep` | `01310100` |
29
- | Telefone | `validateTelefone`, `formatTelefone`, `stripTelefone` | `11999999999` |
30
- | CNH | `validateCnh`, `formatCnh`, `stripCnh` | `62472927637` (11 digits, no CPF mask) |
31
- | RENAVAM | `validateRenavam`, `formatRenavam`, `stripRenavam` | `63977791104` (11 digits, modulo 11 peso 9) |
32
- | Placa | `validatePlaca`, `formatPlaca`, `convertPlacaToMercosul` | `ABC1D23` |
33
- | PIS/PASEP | `validatePisPasep`, `formatPisPasep` | `10027230888` |
34
- | PIX key | `validatePixKey`, `formatPixKey` | `pix@bcb.gov.br` |
35
- | Boleto | `validateBoleto`, `formatBoleto` | Situação 1 + 2 |
36
- | Credit card | `validateCartaoCredito`, `passesLuhn` | `4111111111111111` |
37
- | IE (27 UFs) | `validateInscricaoEstadual`, `validateIeSp`, … | per UF — see docs |
38
-
39
- Subpath imports for tree-shaking:
23
+ ## Platform APIs
24
+
25
+ Cross-cutting helpers that **compose existing validators** — never duplicate check-digit logic.
26
+
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) |
32
+
33
+ ```typescript
34
+ import { detect, sanitize, generate } from '@br-validators/core';
35
+ import { validateCpf } from '@br-validators/core/cpf';
36
+
37
+ // Auto-detect document type
38
+ detect('123.456.789-09');
39
+ // → { type: 'cpf', ok: true, value: '12345678909', format: 'numeric' }
40
+
41
+ detect('110042490114', { uf: 'SP' });
42
+ // → { type: 'inscricao-estadual', ok: true, ... }
43
+
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'] }
47
+
48
+ sanitize('110.042.490.114', 'inscricao-estadual', { uf: 'SP' });
49
+ // → { ok: true, value: '110042490114', fixes: [...] }
50
+
51
+ // Synthetic valid documents for tests (never production IDs)
52
+ const cpf = generate('cpf', { seed: 42 });
53
+ validateCpf(cpf).ok; // true
54
+
55
+ generate('cnpj', { format: 'alphanumeric', masked: true, seed: 7 });
56
+ generate('placa', { format: 'mercosul', seed: 3 });
57
+ ```
58
+
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:
40
89
 
41
90
  ```typescript
42
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';
43
95
  import { validateInscricaoEstadual } from '@br-validators/core/inscricao-estadual';
96
+ import { validateIeProdutorRural } from '@br-validators/core/inscricao-estadual-produtor-rural';
44
97
  ```
45
98
 
46
99
  ---
47
100
 
48
101
  ## Examples
49
102
 
103
+ ### CNPJ (numeric + alphanumeric)
104
+
50
105
  ```typescript
51
106
  import { validateCnpj, formatCnpj } from '@br-validators/core';
52
107
 
53
- const result = validateCnpj('12ABC34501DE35');
54
- // { ok: true, value: '12ABC34501DE35', format: 'alphanumeric', ... }
108
+ validateCnpj('12ABC34501DE35');
109
+ // { ok: true, value: '12ABC34501DE35', format: 'alphanumeric' }
55
110
 
56
111
  formatCnpj('12ABC34501DE35');
57
- // { ok: true, formatted: '12.ABC.345/01DE-35', ... }
112
+ // { ok: true, formatted: '12.ABC.345/01DE-35' }
58
113
  ```
59
114
 
115
+ ### Inscrição Estadual (all 27 UFs)
116
+
60
117
  ```typescript
61
118
  import { validateInscricaoEstadual } from '@br-validators/core/inscricao-estadual';
62
119
 
63
120
  validateInscricaoEstadual('110042490114', { uf: 'SP' });
64
121
  validateInscricaoEstadual('0730000100109', { uf: 'DF' });
122
+ // getIeOfficialSourceUrl('SP') → SEFAZ primary URL
123
+ ```
124
+
125
+ ### SP produtor rural (`P` prefix)
126
+
127
+ ```typescript
128
+ import { validateIeProdutorRural } from '@br-validators/core/inscricao-estadual-produtor-rural';
129
+
130
+ validateIeProdutorRural('SP', 'P-01100424.3/002');
131
+ // { ok: true, value: 'P011004243002', ... }
132
+ ```
133
+
134
+ ### NF-e / NFC-e chave de acesso (44 digits)
135
+
136
+ ```typescript
137
+ import { validateNfeChave, parseNfeChave } from '@br-validators/core/nfe-chave';
138
+
139
+ const result = validateNfeChave('52060433009911002506550120000007800267301615');
140
+ // { ok: true, parsed: { cUF, cnpj, mod, serie, nNF, ... }, uf: 'GO' }
141
+ ```
142
+
143
+ ### BR Code (PIX QR payload)
144
+
145
+ ```typescript
146
+ import { validateBrCode } from '@br-validators/core/brcode';
147
+
148
+ validateBrCode('00020126580014br.gov.bcb.pix0136...63041D3D');
149
+ // { ok: true, pixKey, merchantName, merchantCity, ... }
150
+ ```
151
+
152
+ ### Boleto (linha digitável ↔ código de barras)
153
+
154
+ ```typescript
155
+ import { validateBoleto, convertLinhaToCodigoBarras } from '@br-validators/core/boleto';
156
+
157
+ validateBoleto('03399.02579 08991.834006 71742.301014 6 14500000099668');
65
158
  ```
66
159
 
67
160
  ---
68
161
 
69
162
  ## Official sources
70
163
 
71
- Every algorithm cites a primary government source. Full table: [OFFICIAL-SOURCES.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/OFFICIAL-SOURCES.md)
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.
72
169
 
73
- Per-type URLs also available via constants (`CNPJ_OFFICIAL_SOURCE_URL`, `IE_OFFICIAL_SOURCE_URLS`, etc.).
170
+ Golden test vectors: `tests/vectors/*.official.json` in the repo.
74
171
 
75
172
  ---
76
173
 
77
174
  ## API reference
78
175
 
79
- [docs/LIBRARY-API.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/LIBRARY-API.md)
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 |
80
181
 
81
182
  ---
82
183
 
@@ -84,11 +185,32 @@ Per-type URLs also available via constants (`CNPJ_OFFICIAL_SOURCE_URL`, `IE_OFFI
84
185
 
85
186
  ```bash
86
187
  npm install -g @br-validators/cli
188
+
189
+ br-validators list
87
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
+
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
88
200
  ```
89
201
 
90
202
  ---
91
203
 
204
+ ## Related packages (monorepo)
205
+
206
+ | 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) |
211
+
212
+ ---
213
+
92
214
  ## License
93
215
 
94
216
  MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@br-validators/core",
3
- "version": "0.12.0-alpha.0",
4
- "description": "100% open-source Brazilian document validators — CPF, CNPJ, CEP, IE (27 UFs), PIX, boleto, and more",
3
+ "version": "0.12.0-alpha.1",
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",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "repository": {
@@ -18,10 +18,22 @@
18
18
  "cpf",
19
19
  "cnpj",
20
20
  "cep",
21
- "validator",
22
- "inscricao-estadual",
21
+ "cnh",
22
+ "renavam",
23
+ "nfe",
24
+ "titulo-eleitor",
25
+ "placa",
26
+ "pis-pasep",
27
+ "telefone",
23
28
  "pix",
29
+ "brcode",
24
30
  "boleto",
31
+ "cartao-credito",
32
+ "inscricao-estadual",
33
+ "validator",
34
+ "detect",
35
+ "sanitize",
36
+ "generate",
25
37
  "typescript"
26
38
  ],
27
39
  "publishConfig": {