brasil-ceps-offline 1.1.2 → 2.0.0

package/README.md

@@ -1,237 +1,99 @@
-# brasil-ceps-offline
+# 🗺️ Brasil CEPs Offline
 
-🚀 Busca rápida de CEPs brasileiros com **zero latência de rede** – dados completamente off-line usando SQLite.
+Um motor de inteligência geográfica e busca de CEPs **100% offline** para Node.js e TypeScript. 
 
-## 🎯 Características
+Esqueça limites de requisição (Rate Limits), bloqueios de IP (HTTP 429) ou latência de rede. Esta biblioteca traz um banco de dados local ultrarrápido baseado no **Censo IBGE 2022**, entregando não apenas o endereço, mas coordenadas exatas e dados fiscais em milissegundos.
 
-- ⚡ **Zero latência de rede** – Todas as buscas são locais
-- 💾 **1.2M+ registros** de CEPs brasileiros
-- 🏎️ **Milhões de buscas por segundo** com SQLite optimizado
-- 📦 **Zero dependências de runtime** além de Node.js
-- 🔄 **Sincronização automática** via postinstall hook
-- 🛠️ **CLI para gerenciamento** de banco de dados
-- � **Gap Hunter** para detectar e preencher lacunas de CEPs
-- 🧠 **AI Updater** para descoberta automática de novos CEPs
-- 🧪 **TypeScript** com tipos completos
+## ✨ Superpoderes
 
-## 📦 Instalação
+- ⚡ **Zero Latência:** Consultas locais em SQLite (tempo de resposta na casa dos ~1ms).
+- 🏢 **Pronto para NFe (Código IBGE):** Retorna o código IBGE oficial do município, essencial para emissão de notas fiscais e integração com ERPs.
+- 📍 **Precisão de GPS (Censo 2022):** Latitude e Longitude com precisão a nível de rua, prontas para cálculo de raio de entrega (Haversine) ou plotagem em mapas.
+- 📱 **Inteligência de Formulários:** Retorna DDD para validação de telefones e Fuso Horário (`timezone`) para sistemas de agendamento.
+- 🛡️ **Sistema de Fallback Seguro:** Se o CEP pesquisado for um loteamento inaugurado ontem e não estiver no banco local, a biblioteca busca os dados silenciosamente em APIs externas, garantindo que seu app nunca falhe.
 
-```bash
-npm install brasil-ceps-offline
-```
-
-Após a instalação, o banco de dados é automaticamente baixado via hook `postinstall` (aprox 50-100MB).
-
-## 🚀 Uso Rápido
-
-### Busca por CEP
-
-```typescript
-import { findByCep } from 'brasil-ceps-offline';
-
-const address = findByCep('01310100');
-console.log(address);
-// {
-//   cep: '01310100',
-//   state: 'SP',
-//   city: 'São Paulo',
-//   neighborhood: 'Centro',
-//   street: 'Avenida Paulista'
-// }
-```
-
-### Busca por Endereço
-
-```typescript
-import { findByAddress } from 'brasil-ceps-offline';
-
-const addresses = findByAddress('SP', 'São Paulo', 'Avenida Paulista');
-console.log(addresses);
-// [
-//   { cep: '01310100', state: 'SP', city: 'São Paulo', ... },
-//   { cep: '01310200', state: 'SP', city: 'São Paulo', ... },
-//   ...
-// ]
-```
-
-## 🎓 API Completa
-
-### Classe `BrasilCepsOffline`
-
-```typescript
-import { init, BrasilCepsOffline } from 'brasil-ceps-offline';
-
-const ceps = init(); // Inicializa/retorna singleton
-
-// Métodos:
-ceps.findAddressByCep(cep: string): Address | null
-ceps.findCepsByAddress(state, city?, street?): Address[]
-ceps.searchAddress(pattern, state?, limit?): Address[]
-ceps.getStats(): { totalRecords: number; databaseSize: string }
-ceps.close(): void
-```
+---
 
-### Funções de Conveniência
+## 🚀 Instalação e Configuração do Banco
 
-```typescript
-findByCep(cep: string): Address | null
-findByAddress(state, city?, street?): Address[]
-search(pattern, state?, limit?): Address[]
-```
-
-## 🔄 Sincronização de Banco
+Instale a biblioteca via NPM, Yarn ou pnpm:
 
 ```bash
-# Atualizar banco de dados
-npx brasil-ceps-offline sync
-
-# Ver status e estatísticas
-npx brasil-ceps-offline status
-
-# Ver ajuda
-npx brasil-ceps-offline help
+npm install brasil-ceps-offline
 ```
 
-O comando `sync` utiliza `fs.renameSync()` para uma transição atômica. Servidores em execução continuarão usando o banco antigo até fechar a conexão, garantindo zero-downtime.
+## 📥 Sincronizando o Banco de Dados Local
 
-## 🎯 Gap Hunter - Descoberta de Lacunas de CEPs
+Para manter a instalação da biblioteca leve no NPM, o banco de dados geográfico de alta precisão (~167MB) é hospedado de forma segura no GitHub Releases.
 
-### Modo AUTO (Recomendado)
+Após a instalação, execute o comando abaixo para baixar o banco de dados mais recente para a sua máquina/servidor:
 
 ```bash
-npm run hunt
-```
-
-Auto-detecta todos os prefixos de 5 dígitos presentes na base e testa CEPs faltantes (números 000-999) para cada um. Ideal para rodar à noite e aumentar cobertura.
-
-### Modo MANUAL (Específico)
-
-```bash
-npm run hunt -- 01310 16400 04501
+# Baixa e atualiza o banco de dados local (.sqlite)
+npx brasil-ceps-offline sync
 ```
 
-Testa apenas os prefixos especificados. Mais rápido para validação de regiões específicas.
-
-**Como funciona:**
-
-- Detecta CEPs já cadastrados
-- Testa números faltantes via API BrasilAPI/ViaCEP
-- Rate limiting: 1 requisição/segundo
-- Insere novos CEPs encontrados automaticamente no SQLite
-- Com recurso de 4.500+ prefixos: ~75-120 horas para cobertura completa
+> **Recomendação:** Você pode adicionar este comando no seu CI/CD ou no script de `postinstall` do seu `package.json` para garantir que o servidor sempre inicie com o banco atualizado.
 
-## 🤖 AI Updater - Automação com IA
+---
 
-Script que executa automaticamente a cada mês no GitHub Actions:
+## 💻 Como Usar
 
-1. **Busca notícias reais** sobre novos CEPs no Google News (última semana)
-2. **Processa com IA** (GPT-4o-mini) para extrair dados estruturados
-3. **Insere no banco** automaticamente
+A API foi desenhada para ser simples e tipada.
 
-Ideal para manter dados sempre atualizados com descobertas públicas.
+```ts
+import { getAddress } from 'brasil-ceps-offline';
 
-**Executar manualmente:**
+async function buscarLocalizacao() {
+  try {
+    // A biblioteca limpa automaticamente hífens e formatações
+    const endereco = await getAddress('74740-300');
+    console.log(endereco);
+  } catch (error) {
+    console.error('CEP inválido ou não encontrado.');
+  }
+}
 
-```bash
-OPENAI_API_KEY=sk-xxx npm run ai:update
+buscarLocalizacao();
 ```
 
-## 🏗️ Arquitetura
-
-```
-brasil-ceps-offline/
-├── src/
-│   ├── index.ts          # API principal
-│   ├── database.ts       # Funções do SQLite
-│   ├── types.ts          # Interfaces TypeScript
-│   ├── config.ts         # Configurações
-│   ├── scripts/
-│   │   ├── download-db.ts    # Download automático
-│   │   ├── gap-hunter.ts     # Descoberta de lacunas
-│   │   └── ai-updater.ts     # Automação com IA
-│   └── bin/
-│       └── sync.ts           # CLI de sincronização
-├── .db/
-│   └── ceps.sqlite       # Banco de dados (~50-100MB)
-└── dist/                 # Código compilado
-```
+---
 
-## 📊 Performance
-
-- **Busca por CEP**: ~1ms (indexado)
-- **Busca por endereço**: ~5-50ms (depende quantidade de resultados)
-- **Memória**: ~100MB (cache SQLite) + código
-- **Taxa**: 10M+ buscas/segundo em máquinas modernas
-
-## 📝 Schema do Banco
-
-```sql
-CREATE TABLE addresses (
-  cep TEXT PRIMARY KEY,          -- CEP sem formatação (8 dígitos)
-  state TEXT NOT NULL,           -- UF (2 letras: SP, RJ, etc)
-  city TEXT NOT NULL,            -- Nome da cidade
-  neighborhood TEXT,             -- Bairro
-  street TEXT NOT NULL           -- Nome da rua/avenida
-);
-
--- Índices para buscas rápidas
-CREATE INDEX idx_cep ON addresses(cep);
-CREATE INDEX idx_state ON addresses(state);
-CREATE INDEX idx_city ON addresses(city);
-CREATE INDEX idx_street ON addresses(street);
-CREATE INDEX idx_state_city_street ON addresses(state, city, street);
+## 📦 Resposta Enriquecida (Interface)
+
+O retorno é um objeto padronizado com todos os dados fiscais e geográficos prontos para uso:
+
+```json
+{
+  "cep": "74740300",
+  "state": "GO",
+  "city": "Goiânia",
+  "neighborhood": "Aruana Ii",
+  "street": "Rua Ar 3",
+  "ibge": 5208707,
+  "ddd": "62",
+  "timezone": "America/Sao_Paulo",
+  "latitude": -16.6925197501606,
+  "longitude": -49.2019380833593
+}
 ```
 
-## 🛠️ Desenvolvimento Local
-
-```bash
-# Instalar dependências
-npm install
-
-# Compilar TypeScript
-npm run build
+---
 
-# Ver tipos TypeScript
-npm run dev
+## 🛠️ Tipagem (TypeScript)
 
-# Executar Gap Hunter (testes de lacunas)
-npm run hunt
+A biblioteca exporta a interface principal para facilitar a tipagem no seu projeto:
 
-# Executar AI Updater (automação com IA)
-OPENAI_API_KEY=sk-xxx npm run ai:update
+```ts
+import type { Address } from 'brasil-ceps-offline';
 
-# Testar
-npm test
+const myAddress: Address = await getAddress('01001000');
 ```
 
-## 🔒 Segurança
-
-- Banco de dados é **somente-leitura** para aplicações
-- Sem conexões de rede (exceto Gap Hunter e AI Updater opcionais)
-- Sem coleta de dados ou telemetria
-- Open-source e auditável
-
-## 🤝 Contribuindo
-
-Contribuições são bem-vindas! Areas de interesse:
-
-- Melhorias de performance
-- Compressão de banco (ex: zstd)
-- Suporte a múltiplas versões de banco
-- Testes mais abrangentes
-- Documentação
-
-## 📄 Licença
-
-MIT – Use livremente
-
-## 🙏 Referências
+---
 
-- [CEP Aberto](https://cepaberto.com.br/) – Fonte de dados
-- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) – Driver SQLite
-- [OpenAI API](https://openai.com/api/) – Para automação com IA
-- [Google News RSS](https://news.google.com/) – Para descoberta de novos CEPs
+## ⚖️ Licença e Fonte dos Dados
 
----
+**Código fonte:** MIT License
 
-**Made with ❤️ para a comunidade Brasil dev**
+**Dados:** Baseados no Cadastro Nacional de Endereços do Censo 2022 (IBGE). Dados públicos de uso livre.

package/dist/builder.d.ts

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
 /**
- * Builder: Processa CSVs massivos de CEPs para SQLite com alta performance
+ * Builder: IBGE BigQuery CSV → SQLite
  *
- * Stack: better-sqlite3 + csv-parse + Node.js Streams
- * RAM: Eficiente - não carrega arquivos inteiros na memória
+ * Formato do CSV de entrada:
+ *   cep, logradouro, localidade, id_municipio, nome_municipio, sigla_uf, estabelecimentos, centroide
  *
- * Suporta dois formatos:
- * 1. Com headers: cep, uf, cidade, bairro, logradouro
- * 2. Sem headers: cep, logradouro, desc, bairro, municipio_code
+ * Stack  : better-sqlite3 + csv-parse (streams)
+ * RAM    : O(1) — apenas o batch corrente fica em memória
+ * Output : .db/ceps.sqlite
  *
  * Uso:
  *   ts-node src/builder.ts
- *   npx ts-node src/builder.ts
+ *   npm run builder
  */
 export {};