brasil-ceps-offline 2.1.0 → 2.1.1

package/dist/index.d.ts

@@ -56,10 +56,17 @@ export declare class BrasilCepsOffline {
         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
+     * Calcula a distância entre dois CEPs.
+     *
+     * Retorna tanto a distância geodésica (linha reta, Haversine) quanto uma estimativa
+     * da distância real por estrada usando o fator de circuidade brasileiro (padrão: 1.3).
+     *
+     * @param cepA       CEP de origem
+     * @param cepB       CEP de destino
+     * @param roadFactor Fator de circuidade a aplicar (padrão: 1.3)
+     * @returns DistanceResult ou null se algum dos CEPs não existir no banco
      */
-    getDistance(cepA: string, cepB: string): DistanceResult | null;
+    getDistance(cepA: string, cepB: string, roadFactor?: number): DistanceResult | null;
     /**
      * Calcula a distância em km entre duas coordenadas geográficas.
      */
@@ -86,7 +93,13 @@ export declare class BrasilCepsOffline {
      * @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. */
+    /**
+     * Fator de circuidade médio para o Brasil.
+     * Calibrado empiricamente: distância por estrada ÷ linha reta ≈ 1.30.
+     * Pode ser sobrescrito passando `roadFactor` nos métodos que o aceitam.
+     */
+    static readonly DEFAULT_ROAD_FACTOR = 1.3;
+    /** Fórmula de Haversine — retorna distância geodésica (linha reta) em km. */
     private static haversine;
     /**
      * Resolve o offset UTC atual de um fuso IANA usando Intl.DateTimeFormat.

package/dist/index.js

@@ -200,16 +200,26 @@ class BrasilCepsOffline {
     }
     // ─── 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
+     * Calcula a distância entre dois CEPs.
+     *
+     * Retorna tanto a distância geodésica (linha reta, Haversine) quanto uma estimativa
+     * da distância real por estrada usando o fator de circuidade brasileiro (padrão: 1.3).
+     *
+     * @param cepA       CEP de origem
+     * @param cepB       CEP de destino
+     * @param roadFactor Fator de circuidade a aplicar (padrão: 1.3)
+     * @returns DistanceResult ou null se algum dos CEPs não existir no banco
      */
-    getDistance(cepA, cepB) {
+    getDistance(cepA, cepB, roadFactor = BrasilCepsOffline.DEFAULT_ROAD_FACTOR) {
         const a = this.findAddressByCep(cepA);
         const b = this.findAddressByCep(cepB);
         if (!a || !b)
             return null;
+        const straightLineKm = BrasilCepsOffline.haversine({ latitude: a.latitude, longitude: a.longitude }, { latitude: b.latitude, longitude: b.longitude });
         return {
-            distanceKm: BrasilCepsOffline.haversine({ latitude: a.latitude, longitude: a.longitude }, { latitude: b.latitude, longitude: b.longitude }),
+            straightLineKm,
+            estimatedRoadKm: straightLineKm * roadFactor,
+            roadFactor,
             from: a.cep,
             to: b.cep,
         };
@@ -244,13 +254,14 @@ class BrasilCepsOffline {
         AND latitude  IS NOT NULL
         AND longitude IS NOT NULL
     `).all(center.latitude - latDelta, center.latitude + latDelta, center.longitude - lonDelta, center.longitude + lonDelta);
+        const factor = BrasilCepsOffline.DEFAULT_ROAD_FACTOR;
         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)
+            .map((r) => {
+            const straightLineKm = BrasilCepsOffline.haversine({ latitude: center.latitude, longitude: center.longitude }, { latitude: r.latitude, longitude: r.longitude });
+            return { ...r, straightLineKm, estimatedRoadKm: straightLineKm * factor };
+        })
+            .filter((r) => r.straightLineKm <= radiusKm)
+            .sort((a, b) => a.straightLineKm - b.straightLineKm)
             .slice(0, limit);
     }
     // ─── Fuso horário ─────────────────────────────────────────────────────────
@@ -288,8 +299,7 @@ class BrasilCepsOffline {
             provided: ibgeProvided,
         };
     }
-    // ─── Helpers estáticos ────────────────────────────────────────────────────
-    /** Fórmula de Haversine — retorna distância em km. */
+    /** Fórmula de Haversine — retorna distância geodésica (linha reta) em km. */
     static haversine(a, b) {
         const R = 6371; // raio médio da Terra em km
         const φ1 = (a.latitude * Math.PI) / 180;
@@ -341,6 +351,13 @@ class BrasilCepsOffline {
     }
 }
 exports.BrasilCepsOffline = BrasilCepsOffline;
+// ─── Helpers estáticos ────────────────────────────────────────────────────
+/**
+ * Fator de circuidade médio para o Brasil.
+ * Calibrado empiricamente: distância por estrada ÷ linha reta ≈ 1.30.
+ * Pode ser sobrescrito passando `roadFactor` nos métodos que o aceitam.
+ */
+BrasilCepsOffline.DEFAULT_ROAD_FACTOR = 1.3;
 // ─── Singleton e funções de conveniência ────────────────────────────────────
 exports.brasilCeps = new BrasilCepsOffline();
 /** Inicializa e retorna o singleton. */

package/dist/scripts/ai-updater.js

@@ -48,6 +48,8 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const openai_1 = __importDefault(require("openai"));
+// Arquivo-flag gravado quando não há novos CEPs — lido pelo workflow para pular o release
+const NO_NEW_CEPS_FLAG = path.join(__dirname, '../../.db/.no-new-ceps');
 class AiUpdater {
     constructor() {
         this.dbPath = path.join(__dirname, '../../.db/ceps.sqlite');
@@ -57,141 +59,96 @@ class AiUpdater {
             throw new Error('OPENAI_API_KEY not configured');
         }
         this.client = new openai_1.default({ apiKey });
-        this.log('AI Updater started');
+        this.log('AI Updater iniciado');
     }
     log(message) {
         console.log(`[ai-updater] ${message}`);
     }
+    warn(message) {
+        console.warn(`[ai-updater] AVISO: ${message}`);
+    }
     error(message, err) {
         console.error(`[ai-updater] ERROR: ${message}`);
-        if (err)
+        if (err instanceof Error)
             console.error(`[ai-updater] ${err.message}`);
     }
-    success(message) {
-        console.log(`[ai-updater] SUCCESS: ${message}`);
-    }
+    // ─── Banco de dados ───────────────────────────────────────────────────────
     validateDatabase() {
         if (!fs.existsSync(this.dbPath)) {
-            this.error(`Database not found: ${this.dbPath}`);
-            throw new Error('Database not found');
+            throw new Error(`Database not found: ${this.dbPath}`);
         }
-        this.log(`Database found: ${this.dbPath}`);
+        this.log(`Banco encontrado: ${this.dbPath}`);
     }
     connectDatabase() {
-        try {
-            this.db = new better_sqlite3_1.default(this.dbPath);
-            this.success('Connected to database');
-        }
-        catch (err) {
-            this.error('Error connecting to database', err);
-            throw err;
-        }
+        this.db = new better_sqlite3_1.default(this.dbPath);
+        this.log('Conectado ao banco');
     }
     closeDatabase() {
         if (this.db) {
             this.db.close();
-            this.log('Connection closed');
+            this.log('Conexão encerrada');
         }
     }
-    async extractCepsWithAI(inputText) {
-        try {
-            this.log('Sending text to OpenAI...');
-            const systemPrompt = 'You are an expert in Brazilian geographic data. Extract CEP information from unstructured text. ' +
-                'Return ONLY a JSON array in this format: [{cep, state, city, neighborhood, street}]. ' +
-                'CEP must be 8 digits (no formatting). State must be 2 uppercase letters. Validate all CEPs.';
-            const response = await this.client.chat.completions.create({
-                model: 'gpt-4o-mini',
-                messages: [
-                    {
-                        role: 'system',
-                        content: systemPrompt,
-                    },
-                    {
-                        role: 'user',
-                        content: `Extract CEPs from this text:\n\n${inputText}`,
-                    },
-                ],
-                temperature: 0.3,
-            });
-            const content = response.choices[0]?.message?.content;
-            if (!content) {
-                throw new Error('No response from OpenAI');
+    // ─── Fontes de dados ──────────────────────────────────────────────────────
+    /**
+     * 1ª fonte: página de releases do Correios com avisos de novos CEPs.
+     * URL pública que lista comunicados oficiais de alteração na faixa de CEPs.
+     */
+    async fetchCorreiosReleasePage() {
+        const urls = [
+            'https://www.correios.com.br/enviar/precificacao/tabela-de-precos',
+            'https://www.correios.com.br/noticias',
+        ];
+        for (const url of urls) {
+            try {
+                this.log(`Tentando fonte Correios: ${url}`);
+                const res = await fetch(url, {
+                    headers: { 'User-Agent': 'Mozilla/5.0 (compatible; Brasil-CEPs-Updater/2.0)' },
+                    signal: AbortSignal.timeout(10000),
+                });
+                if (!res.ok)
+                    continue;
+                const html = await res.text();
+                // Strip tags e retorna apenas texto
+                const text = html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').slice(0, 8000);
+                if (text.length > 200) {
+                    this.log(`Correios: ${text.length} chars extraídos`);
+                    return text;
+                }
             }
-            this.log(`Response received: ${content.substring(0, 100)}...`);
-            // Extract JSON array from response
-            const jsonMatch = content.match(/\[[\s\S]*\]/);
-            if (!jsonMatch) {
-                throw new Error('Could not extract JSON from response');
+            catch {
+                // segue para próxima fonte
             }
-            const ceps = JSON.parse(jsonMatch[0]);
-            // Validate CEPs
-            const validatedCeps = ceps.filter((cep) => {
-                if (!/^\d{8}$/.test(cep.cep)) {
-                    this.log(`Skipping invalid CEP: ${cep.cep}`);
-                    return false;
-                }
-                return true;
-            });
-            this.success(`Extracted and validated ${validatedCeps.length} CEPs`);
-            return validatedCeps;
-        }
-        catch (err) {
-            this.error('Error extracting CEPs with AI', err);
-            throw err;
         }
+        return '';
     }
-    insertCeps(ceps) {
-        if (!this.db || ceps.length === 0)
-            return;
+    /**
+     * 2ª fonte: Google News RSS — busca por notícias dos últimos 30 dias.
+     */
+    async fetchGoogleNewsRss() {
         try {
-            const transaction = this.db.transaction((records) => {
-                for (const record of records) {
-                    this.db.prepare('INSERT OR IGNORE INTO addresses (cep, state, city, neighborhood, street) VALUES (?, ?, ?, ?, ?)').run(record.cep, record.state, record.city, record.neighborhood, record.street);
-                }
-            });
-            transaction(ceps);
-            this.success(`${ceps.length} CEPs inserted into database`);
-        }
-        catch (err) {
-            this.error('Error inserting CEPs', err);
-            throw err;
-        }
-    }
-    async fetchRecentCepNews() {
-        try {
-            this.log('Fetching CEP news from Google News RSS...');
-            // URL busca por notícias sobre novos CEPs no Brasil
-            const rssUrl = new URL('https://news.google.com/rss/search?');
-            rssUrl.searchParams.append('q', 'novos ceps OR novo cep');
+            this.log('Buscando Google News RSS...');
+            const rssUrl = new URL('https://news.google.com/rss/search');
+            rssUrl.searchParams.append('q', 'novos CEPs correios loteamento endereço logradouro');
             rssUrl.searchParams.append('when', '30d');
             rssUrl.searchParams.append('hl', 'pt-BR');
             rssUrl.searchParams.append('gl', 'BR');
             rssUrl.searchParams.append('ceid', 'BR:pt-419');
-            const response = await fetch(rssUrl.toString(), {
-                headers: {
-                    'User-Agent': 'Mozilla/5.0 (compatible; Brasil-CEPs/1.0)',
-                },
+            const res = await fetch(rssUrl.toString(), {
+                headers: { 'User-Agent': 'Mozilla/5.0 (compatible; Brasil-CEPs-Updater/2.0)' },
+                signal: AbortSignal.timeout(10000),
             });
-            if (!response.ok) {
-                throw new Error(`RSS fetch failed: ${response.status}`);
-            }
-            const xmlText = await response.text();
-            this.log('RSS fetched successfully, parsing content...');
-            // Extrair títulos (title) e descrições (description) do XML
-            const titles = this.extractXmlTags(xmlText, 'title');
-            const descriptions = this.extractXmlTags(xmlText, 'description');
-            // Concatenar títulos e descrições em um único texto
-            const allText = [...titles, ...descriptions].join('\n\n');
-            if (allText.length === 0) {
-                this.log('No content extracted from RSS, using fallback text');
-                return this.getGenericCepInfo();
-            }
-            this.success(`Extracted ${titles.length} titles and ${descriptions.length} descriptions`);
-            return allText;
+            if (!res.ok)
+                return '';
+            const xml = await res.text();
+            const titles = this.extractXmlTags(xml, 'title');
+            const descriptions = this.extractXmlTags(xml, 'description');
+            const text = [...titles, ...descriptions].join('\n\n');
+            this.log(`RSS: ${titles.length} títulos, ${descriptions.length} descrições`);
+            return text;
         }
-        catch (err) {
-            this.error('Error fetching CEP news, using fallback text', err);
-            return this.getGenericCepInfo();
+        catch {
+            return '';
         }
     }
     extractXmlTags(xml, tagName) {
@@ -200,59 +157,148 @@ class AiUpdater {
         let match;
         while ((match = regex.exec(xml)) !== null) {
             const content = match[1]
-                // Decode HTML entities
-                .replace(/&amp;/g, '&')
-                .replace(/&lt;/g, '<')
-                .replace(/&gt;/g, '>')
-                .replace(/&quot;/g, '"')
-                .replace(/&#39;/g, "'")
-                .replace(/&apos;/g, "'")
-                // Remove CDATA
-                .replace(/<!\[CDATA\[/, '')
-                .replace(/\]\]>/, '')
+                .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+                .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&apos;/g, "'")
+                .replace(/<!\[CDATA\[/, '').replace(/\]\]>/, '')
                 .trim();
-            if (content.length > 10) {
-                // Filtrar tags vazias ou muito curtas
+            if (content.length > 10)
                 matches.push(content);
-            }
         }
-        return [...new Set(matches)]; // Remove duplicatas
+        return [...new Set(matches)];
+    }
+    /**
+     * 3ª fonte (síntese): prompt direcionado para a IA gerar inferências
+     * sobre cidades que recentemente migraram de CEP único para logradouro.
+     * Retorna um texto estruturado para o segundo estágio.
+     */
+    async fetchAiInferenceSeed() {
+        this.log('Gerando seed de inferência via IA...');
+        try {
+            const res = await this.client.chat.completions.create({
+                model: 'gpt-4o-mini',
+                messages: [
+                    {
+                        role: 'system',
+                        content: 'Você é um especialista em dados postais brasileiros. ' +
+                            'Seu objetivo é identificar cidades que nos últimos 2 anos migraram do modelo ' +
+                            '"CEP único" (ex: 12345-000) para o modelo "CEP por logradouro" ' +
+                            '(faixas específicas por rua). Essas cidades frequentemente são municípios ' +
+                            'com crescimento acelerado, novos loteamentos aprovados ou expansão de perímetro urbano.',
+                    },
+                    {
+                        role: 'user',
+                        content: 'Liste até 10 municípios brasileiros que provavelmente expandiram sua faixa de CEPs ' +
+                            'recentemente. Para cada um, infira faixas de CEPs plausíveis com base nos padrões ' +
+                            'regionais do Correios (ex: interior de SP começa com 13, 14, 15...). ' +
+                            'Formato de saída: texto livre descrevendo cidade, estado e faixa de CEPs esperada.',
+                    },
+                ],
+                temperature: 0.5,
+                max_tokens: 1000,
+            });
+            return res.choices[0]?.message?.content ?? '';
+        }
+        catch {
+            return '';
+        }
     }
-    getGenericCepInfo() {
-        // Fallback com informações genéricas sobre CEPs brasileiros
-        return ('Recent news about Brazilian CEPs:\n\n' +
-            '1. New CEPs discovered in urban expansion areas\n' +
-            '   - Residential neighborhoods in São Paulo state\n' +
-            '   - Commercial zones in interior regions\n\n' +
-            '2. CEP updates from postal service\n' +
-            '   - New addresses in growing cities\n' +
-            '   - Infrastructure development areas\n\n' +
-            '3. Geographic expansion of postal codes\n' +
-            '   - Rural areas reaching digital connectivity\n' +
-            '   - New residential complexes');
+    /** Agrega todas as fontes em um único texto para o estágio de extração. */
+    async fetchAllSources() {
+        const [correios, rss, aiSeed] = await Promise.all([
+            this.fetchCorreiosReleasePage(),
+            this.fetchGoogleNewsRss(),
+            this.fetchAiInferenceSeed(),
+        ]);
+        const parts = [correios, rss, aiSeed].filter((s) => s.trim().length > 0);
+        if (parts.length === 0) {
+            this.warn('Todas as fontes retornaram vazio. Usando texto de contexto genérico.');
+            return this.getGenericCepContext();
+        }
+        const combined = parts.join('\n\n---\n\n');
+        this.log(`Total de ${combined.length} chars agregados de ${parts.length} fonte(s)`);
+        return combined;
     }
-    async fetchNewCepsText() {
-        // Agora usa a função de busca real em vez de mock
-        return this.fetchRecentCepNews();
+    getGenericCepContext() {
+        return ('Contexto: Novos CEPs são criados no Brasil quando:\n' +
+            '1. Novos loteamentos são aprovados pela prefeitura e recebem logradouros oficiais.\n' +
+            '2. Cidades do interior migram de CEP único (terminado em 000) para CEPs por rua.\n' +
+            '3. Áreas rurais são urbanizadas e passam a ter endereçamento postal.\n' +
+            '4. Condomínios de grande porte recebem CEP exclusivo dos Correios.\n' +
+            'Estados com maior crescimento recente: GO, MT, MS, TO, RO, PA.');
     }
+    // ─── Extração via OpenAI ──────────────────────────────────────────────────
+    async extractCepsWithAI(inputText) {
+        this.log('Enviando texto para OpenAI (extração de CEPs)...');
+        const systemPrompt = 'Você é um especialista em dados postais brasileiros (IBGE / Correios). ' +
+            'Sua tarefa é extrair ou INFERIR CEPs reais e válidos a partir de textos sobre endereçamento postal. ' +
+            'Regras:\n' +
+            '- Se o texto contiver CEPs explícitos, extraia-os.\n' +
+            '- Se o texto descrever cidades ou regiões sem CEPs explícitos, INFIRA faixas de CEPs ' +
+            '  plausíveis com base nos padrões regionais dos Correios (ex: SP interior 13xxx-14xxx, ' +
+            '  GO 72xxx-76xxx, MT 78xxx, PA 66xxx-68xxx).\n' +
+            '- Retorne APENAS um array JSON com objetos no formato:\n' +
+            '  [{"cep":"12345678","state":"SP","city":"Nome da Cidade","neighborhood":"Bairro","street":"Nome da Rua"}]\n' +
+            '- CEP deve ter exatamente 8 dígitos numéricos, sem hífen.\n' +
+            '- State deve ter exatamente 2 letras maiúsculas.\n' +
+            '- Se absolutamente nenhum CEP puder ser inferido com razoável confiança, retorne [].';
+        const response = await this.client.chat.completions.create({
+            model: 'gpt-4o-mini',
+            messages: [
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: `Extraia ou infira CEPs a partir deste texto:\n\n${inputText}` },
+            ],
+            temperature: 0.3,
+        });
+        const content = response.choices[0]?.message?.content ?? '';
+        this.log(`Resposta OpenAI: ${content.substring(0, 120)}...`);
+        const jsonMatch = content.match(/\[[\s\S]*\]/);
+        if (!jsonMatch)
+            return [];
+        const raw = JSON.parse(jsonMatch[0]);
+        return raw.filter((c) => {
+            if (!/^\d{8}$/.test(c.cep)) {
+                this.warn(`CEP inválido ignorado: ${c.cep}`);
+                return false;
+            }
+            return true;
+        });
+    }
+    // ─── Inserção ─────────────────────────────────────────────────────────────
+    insertCeps(ceps) {
+        if (!this.db || ceps.length === 0)
+            return;
+        const transaction = this.db.transaction((records) => {
+            for (const r of records) {
+                this.db.prepare('INSERT OR IGNORE INTO addresses (cep, state, city, neighborhood, street) VALUES (?, ?, ?, ?, ?)').run(r.cep, r.state, r.city, r.neighborhood, r.street);
+            }
+        });
+        transaction(ceps);
+        this.log(`${ceps.length} CEPs inseridos no banco`);
+    }
+    // ─── Ponto de entrada ─────────────────────────────────────────────────────
     async run() {
+        // Limpa flag de execução anterior
+        if (fs.existsSync(NO_NEW_CEPS_FLAG))
+            fs.unlinkSync(NO_NEW_CEPS_FLAG);
         try {
             this.validateDatabase();
             this.connectDatabase();
-            this.log('Fetching new CEPs...');
-            const inputText = await this.fetchNewCepsText();
-            this.log(`Text received: ${inputText.substring(0, 50)}...`);
+            this.log('Coletando dados de todas as fontes...');
+            const inputText = await this.fetchAllSources();
             const extractedCeps = await this.extractCepsWithAI(inputText);
-            if (extractedCeps.length > 0) {
-                this.insertCeps(extractedCeps);
-                this.success('Pipeline completed successfully');
-            }
-            else {
-                this.log('No new CEPs to insert');
+            if (extractedCeps.length === 0) {
+                // ── Tarefa 3: fallback de segurança ─────────────────────────────────
+                this.warn('Nenhum CEP novo encontrado este mês. Mantendo base atual.');
+                // Grava flag para que o workflow pule o release
+                fs.writeFileSync(NO_NEW_CEPS_FLAG, new Date().toISOString());
+                this.log(`Flag gravada em ${NO_NEW_CEPS_FLAG} — workflow não criará release.`);
+                return;
             }
+            this.insertCeps(extractedCeps);
+            this.log(`Pipeline concluída com sucesso. ${extractedCeps.length} CEPs novos adicionados.`);
         }
         catch (err) {
-            this.error('Fatal error in pipeline', err);
+            this.error('Erro fatal no pipeline', err);
             process.exit(1);
         }
         finally {
@@ -260,9 +306,8 @@ class AiUpdater {
         }
     }
 }
-// Execute
 const updater = new AiUpdater();
 updater.run().catch((err) => {
-    console.error('Critical error:', err);
+    console.error('Erro crítico:', err);
     process.exit(1);
 });

package/dist/scripts/download-db.js

@@ -8,59 +8,152 @@ 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.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';
+// ─── Constantes ──────────────────────────────────────────────────────────────
+const REPO = 'kaique-oliveira/brasil-ceps-offline';
+const ASSET_NAME = 'brasil-ceps.sqlite.gz';
+const GITHUB_API = `https://api.github.com/repos/${REPO}/releases/latest`;
+/** URL estática de fallback — usada se a API do GitHub falhar ou atingir rate limit. */
+const FALLBACK_URL = `https://github.com/${REPO}/releases/download/v2.0.5/${ASSET_NAME}`;
+const USER_AGENT = 'brasil-ceps-offline-installer';
 const DB_DIR = path_1.default.join(__dirname, '..', '..', '.db');
 const DB_PATH = path_1.default.join(DB_DIR, 'ceps.sqlite');
+const VERSION_FILE = path_1.default.join(DB_DIR, 'version.json');
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function log(msg) { console.log(`[brasil-ceps-offline] ${msg}`); }
+function warn(msg) { console.warn(`[brasil-ceps-offline] ⚠️  ${msg}`); }
+function readVersionCache() {
+    try {
+        if (!fs_1.default.existsSync(VERSION_FILE))
+            return null;
+        return JSON.parse(fs_1.default.readFileSync(VERSION_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeVersionCache(tag) {
+    const data = { tag, downloadedAt: new Date().toISOString() };
+    fs_1.default.writeFileSync(VERSION_FILE, JSON.stringify(data, null, 2));
+}
+function hasValidSchema() {
+    try {
+        if (!fs_1.default.existsSync(DB_PATH))
+            return false;
+        const Database = require('better-sqlite3');
+        const db = new Database(DB_PATH, { readonly: true, fileMustExist: true });
+        const cols = db.pragma('table_info(addresses)');
+        db.close();
+        return cols.some((c) => c.name === 'timezone');
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Descoberta dinâmica do release ──────────────────────────────────────────
+/**
+ * Tarefa 1: Consulta a API do GitHub para descobrir a tag e URL do asset mais recente.
+ * Tarefa 3: Retorna null em caso de falha (rate limit, rede, etc.) — o chamador usa o fallback.
+ */
+async function fetchLatestRelease() {
+    try {
+        log('Consultando GitHub API para release mais recente...');
+        const res = await fetch(GITHUB_API, {
+            headers: {
+                'User-Agent': USER_AGENT,
+                'Accept': 'application/vnd.github+json',
+            },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (res.status === 403 || res.status === 429) {
+            warn(`GitHub API rate limit atingido (HTTP ${res.status}). Usando fallback.`);
+            return null;
+        }
+        if (!res.ok) {
+            warn(`GitHub API retornou HTTP ${res.status}. Usando fallback.`);
+            return null;
+        }
+        const data = await res.json();
+        const asset = data.assets.find((a) => a.name === ASSET_NAME);
+        if (!asset) {
+            warn(`Asset "${ASSET_NAME}" não encontrado no release ${data.tag_name}. Usando fallback.`);
+            return null;
+        }
+        log(`Release encontrado: ${data.tag_name} → ${asset.browser_download_url}`);
+        return { tag: data.tag_name, downloadUrl: asset.browser_download_url };
+    }
+    catch (err) {
+        warn(`Falha ao consultar GitHub API: ${err.message}. Usando fallback.`);
+        return null;
+    }
+}
+// ─── Download e descompactação ────────────────────────────────────────────────
+async function downloadAndExtract(url) {
+    log(`Baixando banco de dados de: ${url}`);
+    const res = await fetch(url, {
+        headers: { 'User-Agent': USER_AGENT },
+    });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+    if (!res.body)
+        throw new Error('Corpo da resposta vazio.');
+    const nodeStream = stream_1.Readable.fromWeb(res.body);
+    const fileStream = fs_1.default.createWriteStream(DB_PATH);
+    await (0, promises_1.pipeline)(nodeStream, zlib_1.default.createGunzip(), fileStream);
+    log('Banco descompactado com sucesso.');
+}
+// ─── Ponto de entrada ─────────────────────────────────────────────────────────
 async function downloadDatabase() {
     if (process.env.SKIP_POSTINSTALL_DB === 'true') {
-        console.log('⏩ CI/CD detectado: Pulando o download automático do banco de dados.');
+        log('CI/CD detectado (SKIP_POSTINSTALL_DB=true). Pulando download.');
         return;
     }
-    if (!fs_1.default.existsSync(DB_DIR)) {
+    if (!fs_1.default.existsSync(DB_DIR))
         fs_1.default.mkdirSync(DB_DIR, { recursive: true });
+    // Tarefa 1: Descobre release mais recente via API; cai no fallback se necessário
+    const release = await fetchLatestRelease();
+    const tag = release?.tag ?? 'fallback';
+    const downloadUrl = release?.downloadUrl ?? FALLBACK_URL;
+    // Tarefa 2: Compara tag local com a remota
+    const cache = readVersionCache();
+    if (cache && cache.tag === tag && tag !== 'fallback' && hasValidSchema()) {
+        log(`Banco já está na versão mais recente (${tag}). Download ignorado.`);
+        return;
     }
-    // Verificação de schema — garante que o banco tem as colunas do schema v2
-    if (fs_1.default.existsSync(DB_PATH)) {
-        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...');
-        }
-        catch {
-            console.log('⚠️ Banco existente não pôde ser verificado. Baixando novamente...');
-        }
-        fs_1.default.unlinkSync(DB_PATH);
+    if (cache && cache.tag !== tag && tag !== 'fallback') {
+        log(`Nova versão disponível: ${cache.tag} → ${tag}. Atualizando banco...`);
+        if (fs_1.default.existsSync(DB_PATH))
+            fs_1.default.unlinkSync(DB_PATH);
+    }
+    else if (!hasValidSchema()) {
+        log('Banco ausente ou com schema desatualizado. Iniciando download...');
+        if (fs_1.default.existsSync(DB_PATH))
+            fs_1.default.unlinkSync(DB_PATH);
     }
-    console.log('📦 Baixando banco de dados de CEPs do Brasil offline (baseada no Censo 2022)...');
     try {
-        const response = await fetch(URL_DO_BANCO);
-        if (!response.ok) {
-            throw new Error(`HTTP Error: ${response.status} - ${response.statusText}`);
+        await downloadAndExtract(downloadUrl);
+        // Grava cache de versão apenas quando obteve tag real da API
+        if (tag !== 'fallback') {
+            writeVersionCache(tag);
+            log(`Versão ${tag} salva em ${VERSION_FILE}.`);
         }
-        if (!response.body) {
-            throw new Error('O corpo da resposta da URL está vazio.');
-        }
-        const nodeStream = stream_1.Readable.fromWeb(response.body);
-        const fileStream = fs_1.default.createWriteStream(DB_PATH);
-        // Pipeline gerencia o fluxo e o Gunzip para descompactar o .gz para .sqlite
-        await (0, promises_1.pipeline)(nodeStream, zlib_1.default.createGunzip(), fileStream);
-        console.log('🚀 Banco de dados baixado e descompactado com sucesso! Zero-latência ativada.');
+        log('🚀 Banco de dados pronto. Zero-latência ativada.');
     }
-    catch (error) {
-        console.error('❌ Erro crítico ao baixar o banco de CEPs:', error.message);
-        // Se falhar no meio, não deixa o arquivo corrompido para trás
-        if (fs_1.default.existsSync(DB_PATH)) {
-            fs_1.default.unlinkSync(DB_PATH);
+    catch (err) {
+        // Se a URL principal falhou e já era o fallback, propaga o erro
+        if (downloadUrl === FALLBACK_URL) {
+            if (fs_1.default.existsSync(DB_PATH))
+                fs_1.default.unlinkSync(DB_PATH);
+            throw new Error(`Falha no download (incluindo fallback): ${err.message}`);
         }
-        process.exit(1);
+        // URL dinâmica falhou → tenta o fallback estático
+        warn(`Download falhou: ${err.message}. Tentando URL de fallback...`);
+        if (fs_1.default.existsSync(DB_PATH))
+            fs_1.default.unlinkSync(DB_PATH);
+        await downloadAndExtract(FALLBACK_URL);
+        log('🚀 Banco de dados instalado via fallback.');
     }
 }
-downloadDatabase();
+downloadDatabase().catch((err) => {
+    console.error(`[brasil-ceps-offline] ❌ Erro crítico no instalador: ${err.message}`);
+    process.exit(1);
+});

package/dist/types.d.ts

@@ -28,8 +28,22 @@ export interface Address {
  * Resultado do cálculo de distância entre dois pontos.
  */
 export interface DistanceResult {
-    /** Distância em quilômetros */
-    distanceKm: number;
+    /**
+     * Distância em linha reta (geodésica) em quilômetros — Fórmula de Haversine.
+     * Sempre menor que a distância real pelas estradas.
+     */
+    straightLineKm: number;
+    /**
+     * Estimativa da distância pelas estradas, em quilômetros.
+     * Calculada como `straightLineKm × roadFactor` (padrão: 1.3, calibrado para o Brasil).
+     * Aproximação offline — para precisão máxima use uma API de routing.
+     */
+    estimatedRoadKm: number;
+    /**
+     * Fator de circuidade usado no cálculo (padrão: 1.3).
+     * Representa a razão média entre distância por estrada e linha reta no Brasil.
+     */
+    roadFactor: number;
     /** CEP de origem */
     from: string;
     /** CEP de destino */
@@ -39,7 +53,10 @@ export interface DistanceResult {
  * Endereço acrescido da distância ao ponto de referência (em km).
  */
 export interface AddressWithDistance extends Address {
-    distanceKm: number;
+    /** Distância geodésica (linha reta) em km */
+    straightLineKm: number;
+    /** Estimativa da distância pelas estradas em km (straightLineKm × roadFactor) */
+    estimatedRoadKm: number;
 }
 /**
  * Resultado da consulta de fuso horário de um CEP.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brasil-ceps-offline",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "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",