@br-validators/core 1.6.2 → 1.8.0

package/README.md

@@ -1,11 +1,13 @@
 # @br-validators/core
 
 > **The** Brazilian document validation library for TypeScript.  
-> 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.
+> Validate, format, and generate CPF, CNPJ (including the new alphanumeric format), NF-e, BR Code PIX, boleto, IE (all 27 states), ANP fuel prices, and 15+ more — zero dependencies, fully typed, never throws.
 
 [![npm](https://img.shields.io/npm/v/@br-validators/core)](https://www.npmjs.com/package/@br-validators/core)
+[![npm downloads](https://img.shields.io/npm/dm/@br-validators/core?label=downloads)](https://www.npmjs.com/package/@br-validators/core)
 [![MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/AlexandreZanata/br-validators/blob/main/LICENSE)
 [![Node ≥ 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)]()
+[![GitHub release](https://img.shields.io/github/v/release/AlexandreZanata/br-validators)](https://github.com/AlexandreZanata/br-validators/releases)
 
 ```bash
 npm install @br-validators/core
@@ -29,7 +31,7 @@ Every Brazilian SaaS eventually reinvents CPF validation — usually wrong.
 - ✅ **Zero runtime dependencies** — pure TypeScript logic, no HTTP calls
 - ✅ **Never throws** — every function returns `{ ok: true, value } | { ok: false, message, code }`
 - ✅ **Tree-shakeable** — subpath imports per document type
-- ✅ **Reference data** — IBGE, Bacen banks, DDD lookup, national holidays, CNAE, CFOP, NCM, CBO, natureza jurídica, NBS, CEST, moedas, países Bacen, Incoterms, portos, aeroportos — embedded offline with weekly freshness ([DATA-FRESHNESS.md](../../docs/DATA-FRESHNESS.md))
+- ✅ **Reference data** — IBGE, Bacen banks, DDD lookup, national holidays, CNAE, CFOP, NCM, CBO, natureza jurídica, NBS, CEST, eSocial categorias, moedas, PTAX cotações, países Bacen, Incoterms, portos, aeroportos, **ANP fuel prices (LPC)** — embedded offline with daily freshness ([DATA-FRESHNESS.md](../../docs/DATA-FRESHNESS.md); ANP weekly)
 - ✅ **ESM only**, Node ≥ 18, works in browser, Bun, Deno
 
 ---
@@ -272,16 +274,21 @@ Embedded JSON from official `.gov.br` sources — **no runtime HTTP**. Each modu
 | Bacen STR banks (COMPE / ISPB) | `@br-validators/core/bancos` | `bancos lookup` · `list` | `/data/bancos` | `getBancos`, `getBancoPorCodigo`, `getBancoPorIspb` | [Bacen Participantes STR](https://www.bcb.gov.br/content/estabilidadefinanceira/str1/ParticipantesSTR.csv) |
 | ANAC public aerodromos | `@br-validators/core/aeroportos` | `aeroportos lookup` | `/data/logistics` | `getAeroportos`, `getAeroportoPorIata`, `getAeroportoPorIcao`, `getAeroportosPorMunicipio` | [ANAC aeródromos públicos CSV](https://www.anac.gov.br/acesso-a-informacao/dados-abertos/areas-de-atuacao/aerodromos/lista-de-aerodromos-publicos/aerodromospublicosv1.csv/@@download/file/aerodromospublicosv1.csv) |
 | ANTAQ port installations | `@br-validators/core/portos` | `portos lookup` | `/data/logistics` | `getPortoPorCodigo`, `searchPortos`, `getPortosPorMunicipio` | [ANTAQ instalações portuárias zip](https://www.gov.br/antaq/pt-br/central-de-conteudos/Instalaesporturias06052025.zip) |
+| ANP fuel prices (LPC) | `@br-validators/core/anp-combustiveis` | — | `/data/logistics` | `getAnpPrecosMedios`, `getAnpPrecosMediosPorIbge`, `getAnpSemanaAtual` | [ANP levantamento LPC](https://www.gov.br/anp/pt-br/assuntos/precos-e-defesa-da-concorrencia/precos/levantamento-de-precos-de-combustiveis-ultimas-semanas-pesquisadas) |
 | TSE ↔ IBGE municipality codes | `@br-validators/core/tse-municipios` | `tse-municipios lookup` | `/data/ibge` (cross-ref) | `getMapeamentoTseIbge`, `getMunicipioIbgePorCodigoTse`, `getCodigosTsePorMunicipio` | [TSE municipio_tse_ibge.zip](https://cdn.tse.jus.br/estatistica/sead/odsele/municipio_tse_ibge/municipio_tse_ibge.zip) |
 | DDD geographic lookup | `@br-validators/core/telefone` | `ddd lookup` | — | `getDddInfo` (extends telefone validator) | [Anatel DDD panel](https://informacoes.anatel.gov.br/paineis/areas-tarifarias/codigos-nacionais) |
 | National holidays | `@br-validators/core/feriados` | `feriados list --year` | `/data/calendar` | `isFeriadoNacional`, `getFeriadosNacionais`, `getProximoDiaUtil` | [Lei 662/1949](https://www.planalto.gov.br/ccivil_03/leis/l0662.htm) + annual Portaria MGI |
 | CNAE 2.3 subclasses | `@br-validators/core/cnaes` | `cnae lookup` · `search` | `/data/fiscal` | `getCnaePorCodigo`, `searchCnaes` | [IBGE CNAE API v2](https://servicodados.ibge.gov.br/api/docs/cnae) |
 | CFOP fiscal operations | `@br-validators/core/cfop` | `cfop lookup` · `search` | `/data/fiscal` | `getCfopPorCodigo`, `searchCfop` | [CONFAZ CFOP SINIEF](https://www.confaz.fazenda.gov.br/legislacao/ajustes/sinief/cfop_cvsn_70_vigente) |
+| CST (ICMS, IPI, PIS, COFINS) | `@br-validators/core/cst` | — | `/data/fiscal` | `getCstIcmsPorCodigo`, `getCstIpiPorCodigo`, `searchCstIcms` | [RFB SPED CST tables](http://www.sped.fazenda.gov.br/spedtabelas/AppConsulta/publico/aspx/ConsultaTabelasExternas.aspx?CodSistema=SpedFiscal) |
+| LC 116 ISS services | `@br-validators/core/lc116` | — | `/data/fiscal` | `getLc116PorCodigo`, `searchLc116` | [LC 116/2003 Planalto](https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp116.htm) |
+| eSocial worker categories | `@br-validators/core/esocial` | — | `/data/fiscal` | `getEsocialCategoriaPorCodigo`, `searchEsocialCategorias` | [eSocial S-1.3 Tabelas](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-s-1-3-nt-06-2026/tabelas.html) |
 | NCM Mercosur nomenclature | `@br-validators/core/ncm` | `ncm lookup` · `search` | `/data/fiscal` | `getNcmPorCodigo`, `searchNcm` | [Siscomex NCM JSON](https://portalunico.siscomex.gov.br/classif/api/publico/nomenclatura/download/json) |
 | Natureza jurídica (CNPJ) | `@br-validators/core/natureza-juridica` | `natureza-juridica lookup` | `/data/fiscal` | `getNaturezaJuridicaPorCodigo` | [RFB Naturezas.zip](https://dadosabertos.rfb.gov.br/CNPJ/dados_abertos_cnpj/) |
 | NBS (NFSe Nacional) | `@br-validators/core/nbs` | `nbs lookup` | `/data/fiscal` | `getNbsPorCodigo`, `searchNbs` | [NFSe Anexo B NBS2 xlsx](https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/anexo_b-nbs2-lista_servico_nacional-snnfse.xlsx) |
 | CEST (substituição tributária) | `@br-validators/core/cest` | `cest lookup` | `/data/fiscal` | `getCestPorCodigo`, `getCestPorNcm`, `searchCest` | [CONFAZ ICMS 142/2018](https://www.confaz.fazenda.gov.br/legislacao/convenios/2018/CV142_18) |
 | ISO 4217 + Bacen PTAX moedas | `@br-validators/core/moedas` | `moedas lookup` | `/data/trade` | `getMoedaPorCodigo`, `searchMoedas` | [Bacen PTAX Moedas API](https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/Moedas) |
+| Bacen PTAX Fechamento | `@br-validators/core/ptax` | — | `/data/trade` | `getPtaxCotacao`, `getPtaxUltimoDiaUtil` | [Bacen Olinda PTAX API](https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/swagger-ui3) |
 | NF-e Bacen country codes | `@br-validators/core/paises-bacen` | `paises-bacen lookup` | `/data/trade` | `getPaisPorCodigoBacen`, `getPaisesBacen` | [NF-e country table](http://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=FOXZNFX/p50=) |
 | ICC Incoterms 2020 | `@br-validators/core/incoterms` | `incoterms lookup` | `/data/trade` | `getIncotermPorCodigo`, `getIncoterms` | [ICC Incoterms rules](https://iccwbo.org/resources-for-business/incoterms-rules/) |
 | CBO 2002 occupations | `@br-validators/core/cbo` | `cbo lookup` · `search` | `/data/fiscal` | `getCboPorCodigo`, `searchCbo` | [MTE CBO downloads](https://www.gov.br/trabalho-e-emprego/pt-br/assuntos/cbo/servicos/downloads) |
@@ -295,6 +302,8 @@ import { getDddInfo } from '@br-validators/core/telefone';
 import { isFeriadoNacional } from '@br-validators/core/feriados';
 import { getCnaePorCodigo } from '@br-validators/core/cnaes';
 import { getCfopPorCodigo } from '@br-validators/core/cfop';
+import { getCstIcmsPorCodigo } from '@br-validators/core/cst';
+import { getLc116PorCodigo } from '@br-validators/core/lc116';
 import { getNcmPorCodigo } from '@br-validators/core/ncm';
 import { getCboPorCodigo } from '@br-validators/core/cbo';
 import { getNaturezaJuridicaPorCodigo } from '@br-validators/core/natureza-juridica';
@@ -305,6 +314,7 @@ import { getPaisPorCodigoBacen } from '@br-validators/core/paises-bacen';
 import { getIncotermPorCodigo } from '@br-validators/core/incoterms';
 import { getAeroportoPorIata } from '@br-validators/core/aeroportos';
 import { getPortoPorCodigo } from '@br-validators/core/portos';
+import { getAnpPrecosMedios } from '@br-validators/core/anp-combustiveis';
 import { getDataCatalog } from '@br-validators/core/data-catalog';
 
 getMunicipioPorCodigo(3550308)?.nome; // São Paulo
@@ -323,10 +333,17 @@ getPaisPorCodigoBacen('1058')?.nome;  // Brasil (NF-e cPais)
 getIncotermPorCodigo('FOB')?.nome;    // Free On Board
 getAeroportoPorIata('GRU')?.nome;     // Guarulhos — SP
 getPortoPorCodigo('BRSSZ')?.nome;     // Santos organized port
+getAnpPrecosMedios({ uf: 'SP', municipio: 'São Paulo', produto: 'GASOLINE_REGULAR' })?.precoMedio;
 getDataCatalog().length;              // registered datasets
 ```
 
-Freshness table (auto-updated weekly): [docs/DATA-FRESHNESS.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/DATA-FRESHNESS.md) · Per-type official URLs: [docs/OFFICIAL-SOURCES.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/OFFICIAL-SOURCES.md)
+Freshness table (auto-updated daily; ANP weekly): [docs/DATA-FRESHNESS.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/DATA-FRESHNESS.md) · Per-type official URLs: [docs/OFFICIAL-SOURCES.md](https://github.com/AlexandreZanata/br-validators/blob/main/docs/OFFICIAL-SOURCES.md)
+
+---
+
+## Current release
+
+**v1.7.0** — all six `@br-validators/*` packages ship the same semver. New in core: `@br-validators/core/anp-combustiveis` (`getAnpPrecosMedios`, `getAnpPrecosMediosPorIbge`, `getAnpSemanaAtual`). [CHANGELOG](https://github.com/AlexandreZanata/br-validators/blob/main/CHANGELOG.md#170---2026-06-24)
 
 ---
 
@@ -344,11 +361,13 @@ import { parseNfeChave } from '@br-validators/core/nfe-chave';
 
 ## Related packages
 
-| Package | Status |
+| Package | npm |
 |---|---|
-| [`@br-validators/cli`](https://www.npmjs.com/package/@br-validators/cli) | Published |
-| [`@br-validators/zod`](https://www.npmjs.com/package/@br-validators/zod) | Published — Zod 3/4 schemas |
-| [`@br-validators/react-hook-form`](https://www.npmjs.com/package/@br-validators/react-hook-form) | Published — RHF resolvers |
+| [`@br-validators/cli`](https://www.npmjs.com/package/@br-validators/cli) | Terminal — validate, format, detect, generate |
+| [`@br-validators/zod`](https://www.npmjs.com/package/@br-validators/zod) | Zod 3/4 schemas |
+| [`@br-validators/react-hook-form`](https://www.npmjs.com/package/@br-validators/react-hook-form) | RHF rules + resolvers |
+| [`@br-validators/express`](https://www.npmjs.com/package/@br-validators/express) | Express + Fastify middleware |
+| [`@br-validators/vue`](https://www.npmjs.com/package/@br-validators/vue) | Vue 3 composables |
 
 ---
 

package/dist/aeroportos.d.ts

@@ -1,4 +1,4 @@
-import { b as DatasetChanges, c as DatasetVerification } from './types-CCKLomYy.js';
+import { b as DatasetChanges, c as DatasetVerification } from './types-CnePu8im.js';
 
 interface Aeroporto {
     iata: string | null;

package/dist/anp-combustiveis.d.ts

@@ -0,0 +1,64 @@
+import { b as DatasetChanges, c as DatasetVerification } from './types-CnePu8im.js';
+
+declare const ANP_COMBUSTIVEL_VALUES: readonly ["ETHANOL", "GASOLINE_REGULAR", "GASOLINE_PREMIUM", "DIESEL_S500", "DIESEL_S10", "CNG", "LPG_P13"];
+type AnpCombustivel = (typeof ANP_COMBUSTIVEL_VALUES)[number];
+interface AnpSemanaPesquisa {
+    inicio: string;
+    fim: string;
+}
+interface AnpPrecoMedio {
+    semanaInicio: string;
+    semanaFim: string;
+    uf: string;
+    estadoNome: string;
+    municipioNome: string;
+    municipioIbge: number | null;
+    produto: AnpCombustivel;
+    postosPesquisados: number;
+    unidade: string;
+    precoMedio: number;
+    precoMinimo: number;
+    precoMaximo: number;
+    desvioPadrao: number | null;
+    coeficienteVariacao: number | null;
+}
+interface AnpPrecosMediosQuery {
+    uf: string;
+    municipio: string;
+    produto: AnpCombustivel;
+    semanaInicio?: string;
+}
+interface AnpCombustiveisDataVersion {
+    id: 'anp-combustiveis';
+    nome: string;
+    fonte: string;
+    endpoints: string[];
+    capturadoEm: string;
+    atualizadoEm: string;
+    contagens: {
+        semanas: number;
+        precosMedios: number;
+        municipios: number;
+        produtos: number;
+        ufs: number;
+    };
+    alteracoes: DatasetChanges;
+    verificacao: DatasetVerification;
+    documentacao: string;
+}
+
+/**
+ * ANP weekly fuel price survey — offline embedded municipal averages.
+ * @see docs/OFFICIAL-SOURCES.md#anp-combustiveis
+ */
+
+declare function getAnpSemanasPesquisa(): readonly AnpSemanaPesquisa[];
+declare function getAnpSemanaAtual(): AnpSemanaPesquisa | undefined;
+declare function getAnpPrecosMedios(query: AnpPrecosMediosQuery): AnpPrecoMedio | undefined;
+declare function getAnpPrecosMediosPorIbge(codigo: number, produto: AnpCombustivel, semanaInicio?: string): AnpPrecoMedio | undefined;
+
+declare const ANP_LPC_LISTING_URL = "https://www.gov.br/anp/pt-br/assuntos/precos-e-defesa-da-concorrencia/precos/levantamento-de-precos-de-combustiveis-ultimas-semanas-pesquisadas";
+
+declare const ANP_COMBUSTIVEIS_DATA_VERSION: AnpCombustiveisDataVersion;
+
+export { ANP_COMBUSTIVEIS_DATA_VERSION, ANP_COMBUSTIVEL_VALUES, ANP_LPC_LISTING_URL, type AnpCombustiveisDataVersion, type AnpCombustivel, type AnpPrecoMedio, type AnpPrecosMediosQuery, type AnpSemanaPesquisa, getAnpPrecosMedios, getAnpPrecosMediosPorIbge, getAnpSemanaAtual, getAnpSemanasPesquisa };