brasil-ceps-offline 2.0.5 → 2.1.0

package/README.md

@@ -7,10 +7,11 @@ Esqueça limites de requisição (Rate Limits), bloqueios de IP (HTTP 429) ou la
 ## ✨ Superpoderes
 
 - ⚡ **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.
+- 📦 **Cálculo de Frete Inteligente:** Calcule a distância real em km entre o seu galpão e o cliente final usando a Fórmula de Haversine — sem custo de API, sem limite de chamadas.
+- 📍 **Geofencing Offline:** Verifique se um CEP está dentro de um raio de entrega em uma única chamada. Ideal para definir zonas de cobertura logística.
+- 🕐 **Gestão de Fusos Horários:** Retorna o fuso horário IANA e o offset UTC atual de qualquer CEP — essencial para sistemas de agendamento que atendem o Acre, Amazonas ou Fernando de Noronha.
+- 🏢 **Enriquecimento de ERP (NFe):** Retorna e valida o código IBGE municipal para emissão de Notas Fiscais, integração com SAP, TOTVS e outros ERPs de forma instantânea.
+- 🛡️ **Sistema de Fallback Seguro:** Se o CEP pesquisado não estiver no banco local, a biblioteca busca os dados silenciosamente em APIs externas (BrasilAPI ou ViaCEP), garantindo que seu app nunca falhe.
 
 ---
 
@@ -42,19 +43,28 @@ npx brasil-ceps-offline sync
 A API foi desenhada para ser simples e tipada.
 
 ```ts
-import { getAddress } from 'brasil-ceps-offline';
-
-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.');
-  }
-}
+import { findByCep, getDistance, getCepsInRadius, getTimezone, validateIbge } from 'brasil-ceps-offline';
+
+// Busca básica por CEP
+const endereco = findByCep('74740-300');
+console.log(endereco);
+
+// Distância entre dois CEPs
+const distancia = getDistance('74740300', '01310100'); // Goiânia → São Paulo
+console.log(`${distancia?.distanceKm.toFixed(1)} km`); // ~873 km
 
-buscarLocalizacao();
+// CEPs dentro de um raio de 50 km
+const vizinhos = getCepsInRadius('01310100', 50);
+console.log(`${vizinhos.length} CEPs encontrados no raio de 50km`);
+
+// Fuso horário de um CEP
+const fuso = getTimezone('69050001'); // Manaus
+console.log(fuso?.timezone);       // "America/Manaus"
+console.log(fuso?.utcOffsetLabel); // "UTC-4"
+
+// Validação de IBGE para NFe
+const ibge = validateIbge('74740300', 5208707);
+console.log(ibge?.valid); // true
 ```
 
 ---
@@ -80,14 +90,60 @@ O retorno é um objeto padronizado com todos os dados fiscais e geográficos pro
 
 ---
 
-## 🛠️ Tipagem (TypeScript)
+## 🛠️ API Completa
+
+### `findByCep(cep)`
+Busca um endereço pelo CEP. Aceita qualquer formato (`"74740300"`, `"74.740-300"`).
+
+### `getDistance(cepA, cepB)`
+Calcula a distância em km entre dois CEPs via Fórmula de Haversine.
+```ts
+const result = getDistance('74740300', '01310100');
+// { distanceKm: 872.4, from: '74740300', to: '01310100' }
+```
+
+### `getCepsInRadius(centerCep, radiusKm, limit?)`
+Retorna endereços dentro do raio informado, ordenados por distância crescente.
+```ts
+const zona = getCepsInRadius('01310100', 30); // todos os CEPs a até 30km de São Paulo
+// [{ ...address, distanceKm: 0.3 }, { ...address, distanceKm: 1.1 }, ...]
+```
 
-A biblioteca exporta a interface principal para facilitar a tipagem no seu projeto:
+### `getTimezone(cep)`
+Retorna fuso horário IANA e offset UTC calculado dinamicamente (inclui horário de verão).
+```ts
+const fuso = getTimezone('69050001');
+// { cep: '69050001', timezone: 'America/Manaus', utcOffset: -4, utcOffsetLabel: 'UTC-4' }
+```
 
+### `validateIbge(cep, ibgeProvided)`
+Valida o código IBGE informado contra o banco de dados.
 ```ts
-import type { Address } from 'brasil-ceps-offline';
+const ok = validateIbge('74740300', 5208707);
+// { valid: true, expected: 5208707, provided: 5208707 }
+```
+
+### `findByAddress(state, city?, street?)`
+Busca CEPs por estado, cidade e/ou rua.
+
+### `search(pattern, state?, limit?)`
+Busca avançada com padrão LIKE em cidade, bairro e logradouro.
 
-const myAddress: Address = await getAddress('01001000');
+---
+
+## 🛠️ Tipagem (TypeScript)
+
+A biblioteca exporta todas as interfaces para facilitar a tipagem no seu projeto:
+
+```ts
+import type {
+  Address,
+  DistanceResult,
+  AddressWithDistance,
+  TimezoneResult,
+  IbgeValidationResult,
+  Coordinates,
+} from 'brasil-ceps-offline';
 ```
 
 ---

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import Database from 'better-sqlite3';
-import { Address, BrasilCepsConfig, FallbackOptions } from './types';
+import { Address, BrasilCepsConfig, FallbackOptions, DistanceResult, AddressWithDistance, TimezoneResult, IbgeValidationResult, Coordinates } from './types';
 /**
  * Motor de Inteligência Geográfica Offline para CEPs brasileiros.
  * Dados do Censo IBGE 2022 — sem rede, sem API keys, sem limites.
@@ -55,6 +55,44 @@ export declare class BrasilCepsOffline {
         totalRecords: number;
         databaseSize: string;
     };
+    /**
+     * Calcula a distância em km entre dois CEPs usando a Fórmula de Haversine.
+     * @returns DistanceResult com a distância, ou null se algum dos CEPs não for encontrado
+     */
+    getDistance(cepA: string, cepB: string): DistanceResult | null;
+    /**
+     * Calcula a distância em km entre duas coordenadas geográficas.
+     */
+    calculateDistance(coordA: Coordinates, coordB: Coordinates): number;
+    /**
+     * Retorna todos os endereços dentro de um raio em km a partir de um CEP central.
+     * Usa bounding-box SQL para limitar o scan antes de aplicar Haversine exato.
+     *
+     * @param centerCep  CEP do ponto central
+     * @param radiusKm   Raio em quilômetros
+     * @param limit      Máximo de resultados (padrão: 500)
+     */
+    getCepsInRadius(centerCep: string, radiusKm: number, limit?: number): AddressWithDistance[];
+    /**
+     * Retorna o fuso horário IANA e o offset UTC atual para um CEP.
+     * O offset é calculado dinamicamente (considera horário de verão se aplicável).
+     */
+    getTimezone(cep: string): TimezoneResult | null;
+    /**
+     * Valida se o código IBGE informado corresponde ao CEP.
+     * Útil para sistemas de checkout e emissão de NFe.
+     *
+     * @param cep           CEP a consultar
+     * @param ibgeProvided  Código IBGE informado pelo usuário ou ERP
+     */
+    validateIbge(cep: string, ibgeProvided: number): IbgeValidationResult | null;
+    /** Fórmula de Haversine — retorna distância em km. */
+    private static haversine;
+    /**
+     * Resolve o offset UTC atual de um fuso IANA usando Intl.DateTimeFormat.
+     * Funciona corretamente com horário de verão (onde aplicável).
+     */
+    private static resolveUtcOffset;
     /**
      * Fecha a conexão com o banco de dados.
      */
@@ -70,3 +108,12 @@ export declare function findByCep(cep: string): Address | null;
 export declare function findByAddress(state: string, city?: string, street?: string): Address[];
 /** Busca avançada com padrão LIKE. */
 export declare function search(pattern: string, state?: string, limit?: number): Address[];
+/** Calcula a distância em km entre dois CEPs. */
+export declare function getDistance(cepA: string, cepB: string): DistanceResult | null;
+/** Retorna endereços dentro de um raio em km a partir de um CEP central. */
+export declare function getCepsInRadius(centerCep: string, radiusKm: number, limit?: number): AddressWithDistance[];
+/** Retorna fuso horário IANA e offset UTC atual de um CEP. */
+export declare function getTimezone(cep: string): TimezoneResult | null;
+/** Valida se o código IBGE informado corresponde ao CEP. */
+export declare function validateIbge(cep: string, ibgeProvided: number): IbgeValidationResult | null;
+export type { Address, DistanceResult, AddressWithDistance, TimezoneResult, IbgeValidationResult, Coordinates, FallbackOptions, BrasilCepsConfig, } from './types';

package/dist/index.js

@@ -8,6 +8,10 @@ exports.init = init;
 exports.findByCep = findByCep;
 exports.findByAddress = findByAddress;
 exports.search = search;
+exports.getDistance = getDistance;
+exports.getCepsInRadius = getCepsInRadius;
+exports.getTimezone = getTimezone;
+exports.validateIbge = validateIbge;
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const config_1 = require("./config");
 const database_1 = require("./database");
@@ -194,6 +198,133 @@ class BrasilCepsOffline {
             databaseSize: `${(size / 1024 / 1024).toFixed(2)} MB`,
         };
     }
+    // ─── Cálculo de distância (Haversine) ────────────────────────────────────
+    /**
+     * Calcula a distância em km entre dois CEPs usando a Fórmula de Haversine.
+     * @returns DistanceResult com a distância, ou null se algum dos CEPs não for encontrado
+     */
+    getDistance(cepA, cepB) {
+        const a = this.findAddressByCep(cepA);
+        const b = this.findAddressByCep(cepB);
+        if (!a || !b)
+            return null;
+        return {
+            distanceKm: BrasilCepsOffline.haversine({ latitude: a.latitude, longitude: a.longitude }, { latitude: b.latitude, longitude: b.longitude }),
+            from: a.cep,
+            to: b.cep,
+        };
+    }
+    /**
+     * Calcula a distância em km entre duas coordenadas geográficas.
+     */
+    calculateDistance(coordA, coordB) {
+        return BrasilCepsOffline.haversine(coordA, coordB);
+    }
+    // ─── Busca por raio (geofencing) ─────────────────────────────────────────
+    /**
+     * Retorna todos os endereços dentro de um raio em km a partir de um CEP central.
+     * Usa bounding-box SQL para limitar o scan antes de aplicar Haversine exato.
+     *
+     * @param centerCep  CEP do ponto central
+     * @param radiusKm   Raio em quilômetros
+     * @param limit      Máximo de resultados (padrão: 500)
+     */
+    getCepsInRadius(centerCep, radiusKm, limit = 500) {
+        this.ensureInitialized();
+        const center = this.findAddressByCep(centerCep);
+        if (!center || !center.latitude || !center.longitude)
+            return [];
+        // 1° de latitude ≈ 111 km; 1° de longitude ≈ 111 km * cos(lat)
+        const latDelta = radiusKm / 111;
+        const lonDelta = radiusKm / (111 * Math.cos((center.latitude * Math.PI) / 180));
+        const rows = this.db.prepare(`
+      SELECT ${SELECT_ALL} FROM addresses
+      WHERE latitude  BETWEEN ? AND ?
+        AND longitude BETWEEN ? AND ?
+        AND latitude  IS NOT NULL
+        AND longitude IS NOT NULL
+    `).all(center.latitude - latDelta, center.latitude + latDelta, center.longitude - lonDelta, center.longitude + lonDelta);
+        return rows
+            .map((r) => ({
+            ...r,
+            distanceKm: BrasilCepsOffline.haversine({ latitude: center.latitude, longitude: center.longitude }, { latitude: r.latitude, longitude: r.longitude }),
+        }))
+            .filter((r) => r.distanceKm <= radiusKm)
+            .sort((a, b) => a.distanceKm - b.distanceKm)
+            .slice(0, limit);
+    }
+    // ─── Fuso horário ─────────────────────────────────────────────────────────
+    /**
+     * Retorna o fuso horário IANA e o offset UTC atual para um CEP.
+     * O offset é calculado dinamicamente (considera horário de verão se aplicável).
+     */
+    getTimezone(cep) {
+        const addr = this.findAddressByCep(cep);
+        if (!addr || !addr.timezone)
+            return null;
+        const utcOffset = BrasilCepsOffline.resolveUtcOffset(addr.timezone);
+        return {
+            cep: addr.cep,
+            timezone: addr.timezone,
+            utcOffset,
+            utcOffsetLabel: `UTC${utcOffset >= 0 ? '+' : ''}${utcOffset}`,
+        };
+    }
+    // ─── Validação IBGE ───────────────────────────────────────────────────────
+    /**
+     * Valida se o código IBGE informado corresponde ao CEP.
+     * Útil para sistemas de checkout e emissão de NFe.
+     *
+     * @param cep           CEP a consultar
+     * @param ibgeProvided  Código IBGE informado pelo usuário ou ERP
+     */
+    validateIbge(cep, ibgeProvided) {
+        const addr = this.findAddressByCep(cep);
+        if (!addr)
+            return null;
+        return {
+            valid: addr.ibge === ibgeProvided,
+            expected: addr.ibge,
+            provided: ibgeProvided,
+        };
+    }
+    // ─── Helpers estáticos ────────────────────────────────────────────────────
+    /** Fórmula de Haversine — retorna distância em km. */
+    static haversine(a, b) {
+        const R = 6371; // raio médio da Terra em km
+        const φ1 = (a.latitude * Math.PI) / 180;
+        const φ2 = (b.latitude * Math.PI) / 180;
+        const Δφ = ((b.latitude - a.latitude) * Math.PI) / 180;
+        const Δλ = ((b.longitude - a.longitude) * Math.PI) / 180;
+        const sinΔφ = Math.sin(Δφ / 2);
+        const sinΔλ = Math.sin(Δλ / 2);
+        const h = sinΔφ * sinΔφ + Math.cos(φ1) * Math.cos(φ2) * sinΔλ * sinΔλ;
+        return R * 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h));
+    }
+    /**
+     * Resolve o offset UTC atual de um fuso IANA usando Intl.DateTimeFormat.
+     * Funciona corretamente com horário de verão (onde aplicável).
+     */
+    static resolveUtcOffset(ianaTimezone) {
+        try {
+            const now = new Date();
+            const parts = new Intl.DateTimeFormat('en', {
+                timeZone: ianaTimezone, timeZoneName: 'shortOffset',
+            }).formatToParts(now);
+            const offset = parts.find((p) => p.type === 'timeZoneName')?.value ?? 'GMT+0';
+            // offset é algo como "GMT-3" ou "GMT+5:30"
+            const match = offset.match(/GMT([+-])(\d+)(?::(\d+))?/);
+            if (!match)
+                return 0;
+            const sign = match[1] === '+' ? 1 : -1;
+            const hours = parseInt(match[2], 10);
+            const minutes = parseInt(match[3] ?? '0', 10);
+            return sign * (hours + minutes / 60);
+        }
+        catch {
+            return 0;
+        }
+    }
     /**
      * Fecha a conexão com o banco de dados.
      */
@@ -232,3 +363,23 @@ function search(pattern, state, limit) {
     exports.brasilCeps.initialize();
     return exports.brasilCeps.searchAddress(pattern, state, limit);
 }
+/** Calcula a distância em km entre dois CEPs. */
+function getDistance(cepA, cepB) {
+    exports.brasilCeps.initialize();
+    return exports.brasilCeps.getDistance(cepA, cepB);
+}
+/** Retorna endereços dentro de um raio em km a partir de um CEP central. */
+function getCepsInRadius(centerCep, radiusKm, limit) {
+    exports.brasilCeps.initialize();
+    return exports.brasilCeps.getCepsInRadius(centerCep, radiusKm, limit);
+}
+/** Retorna fuso horário IANA e offset UTC atual de um CEP. */
+function getTimezone(cep) {
+    exports.brasilCeps.initialize();
+    return exports.brasilCeps.getTimezone(cep);
+}
+/** Valida se o código IBGE informado corresponde ao CEP. */
+function validateIbge(cep, ibgeProvided) {
+    exports.brasilCeps.initialize();
+    return exports.brasilCeps.validateIbge(cep, ibgeProvided);
+}

package/dist/scripts/download-db.js

@@ -8,8 +8,8 @@ const path_1 = __importDefault(require("path"));
 const promises_1 = require("stream/promises");
 const stream_1 = require("stream");
 const zlib_1 = __importDefault(require("zlib"));
-// ⚠️ Atualizado para v2.0.4 - Certifique-se de que o arquivo existe neste release
-const URL_DO_BANCO = 'https://github.com/kaique-oliveira/brasil-ceps-offline/releases/download/v2.0.4/brasil-ceps.sqlite.gz';
+// ⚠️ Atualizado para v2.0.5 - Schema IBGE 2022 com timezone, DDD e coordenadas
+const URL_DO_BANCO = 'https://github.com/kaique-oliveira/brasil-ceps-offline/releases/download/v2.0.5/brasil-ceps.sqlite.gz';
 const DB_DIR = path_1.default.join(__dirname, '..', '..', '.db');
 const DB_PATH = path_1.default.join(DB_DIR, 'ceps.sqlite');
 async function downloadDatabase() {
@@ -20,17 +20,24 @@ async function downloadDatabase() {
     if (!fs_1.default.existsSync(DB_DIR)) {
         fs_1.default.mkdirSync(DB_DIR, { recursive: true });
     }
-    // Verificação de Integridade/Atualização Forçada
+    // Verificação de schema — garante que o banco tem as colunas do schema v2
     if (fs_1.default.existsSync(DB_PATH)) {
-        const stats = fs_1.default.statSync(DB_PATH);
-        // Se o arquivo tiver menos de 100MB, é a versão antiga (39MB)
-        // O novo banco tem aproximadamente 167MB
-        if (stats.size > 100 * 1024 * 1024) {
-            console.log('✅ Banco de CEPs atualizado já está instalado.');
-            return;
+        try {
+            const Database = require('better-sqlite3');
+            const db = new Database(DB_PATH, { readonly: true, fileMustExist: true });
+            const cols = db.pragma('table_info(addresses)');
+            db.close();
+            const hasTimezone = cols.some((c) => c.name === 'timezone');
+            if (hasTimezone) {
+                console.log('✅ Banco de CEPs (schema v2) já está instalado.');
+                return;
+            }
+            console.log('⚠️ Schema desatualizado detectado (falta timezone). Baixando banco v2...');
         }
-        console.log('⚠️ Banco de dados antigo detectado. Iniciando atualização para a base 2022...');
-        fs_1.default.unlinkSync(DB_PATH); // Remove o banco antigo para permitir o novo download
+        catch {
+            console.log('⚠️ Banco existente não pôde ser verificado. Baixando novamente...');
+        }
+        fs_1.default.unlinkSync(DB_PATH);
     }
     console.log('📦 Baixando banco de dados de CEPs do Brasil offline (baseada no Censo 2022)...');
     try {

package/dist/types.d.ts

@@ -24,6 +24,54 @@ export interface Address {
     /** Longitude do centróide do logradouro — Censo 2022 (ex: -49.2019) */
     longitude: number;
 }
+/**
+ * Resultado do cálculo de distância entre dois pontos.
+ */
+export interface DistanceResult {
+    /** Distância em quilômetros */
+    distanceKm: number;
+    /** CEP de origem */
+    from: string;
+    /** CEP de destino */
+    to: string;
+}
+/**
+ * Endereço acrescido da distância ao ponto de referência (em km).
+ */
+export interface AddressWithDistance extends Address {
+    distanceKm: number;
+}
+/**
+ * Resultado da consulta de fuso horário de um CEP.
+ */
+export interface TimezoneResult {
+    /** CEP consultado */
+    cep: string;
+    /** Fuso horário IANA (ex: "America/Sao_Paulo") */
+    timezone: string;
+    /** Offset UTC atual em horas (ex: -3 para BRT, -4 para AMT) */
+    utcOffset: number;
+    /** Representação legível (ex: "UTC-3") */
+    utcOffsetLabel: string;
+}
+/**
+ * Resultado da validação de código IBGE.
+ */
+export interface IbgeValidationResult {
+    /** Se o código IBGE informado confere com o CEP */
+    valid: boolean;
+    /** Código IBGE real do CEP */
+    expected: number;
+    /** Código IBGE informado para validação */
+    provided: number;
+}
+/**
+ * Par de coordenadas geográficas.
+ */
+export interface Coordinates {
+    latitude: number;
+    longitude: number;
+}
 /**
  * Opções para busca com fallback online.
  * Usadas apenas pelo método assíncrono `findAddressByCepWithFallback`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brasil-ceps-offline",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "description": "Motor de Inteligência Geográfica Offline para CEPs brasileiros — dados do Censo IBGE 2022 com IBGE, DDD, fuso horário e coordenadas",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",