brasil-ceps-offline 2.1.3 → 2.1.5

package/README.md

@@ -148,6 +148,54 @@ import type {
 
 ---
 
+## ☁️ Deploy na Vercel / Next.js
+
+A Vercel não executa `postinstall` durante o build de produção por padrão. Siga os passos abaixo para garantir que o banco de dados seja baixado antes do deploy.
+
+### 1. Adicione o sync ao script de build (`package.json`)
+
+```json
+{
+  "scripts": {
+    "build": "npx brasil-ceps-offline sync ./public/.db && next build"
+  }
+}
+```
+
+### 2. Inclua o banco no rastreamento de arquivos (`next.config.js`)
+
+O Next.js usa **Output File Tracing** para empacotar apenas os arquivos necessários. O SQLite precisa ser incluído explicitamente:
+
+```js
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    outputFileTracingIncludes: {
+      // Inclui o banco para todas as rotas da API
+      '/api/**': [
+        './public/.db/**',
+        './node_modules/brasil-ceps-offline/.db/**',
+      ],
+    },
+  },
+};
+
+module.exports = nextConfig;
+```
+
+### 3. Variável de ambiente (opcional)
+
+Se preferir armazenar o banco fora de `node_modules` (ex: em `/tmp` na Vercel):
+
+```bash
+BRASIL_CEPS_DB_PATH=/tmp/ceps.sqlite
+```
+
+> **Atenção:** O diretório `/tmp` na Vercel é efêmero — o banco precisará ser baixado a cada cold start. Para produção de alta disponibilidade, use o caminho padrão via `node_modules`.
+
+---
+
 ## ⚖️ Licença e Fonte dos Dados
 
 **Código fonte:** MIT License

package/dist/bin/cli.js

@@ -15,7 +15,7 @@ function printHelp() {
 brasil-ceps-offline — CLI de gerenciamento do banco de dados
 
 Uso:
-  npx brasil-ceps-offline <comando>
+  npx brasil-ceps-offline <comando> [destino]
 
 Comandos:
   sync     Baixa ou atualiza o banco de dados para a versão mais recente
@@ -24,6 +24,7 @@ Comandos:
 
 Exemplos:
   npx brasil-ceps-offline sync
+  npx brasil-ceps-offline sync ./public/.db
   npx brasil-ceps-offline status
   `.trim());
 }
@@ -58,7 +59,7 @@ async function main() {
     const command = (process.argv[2] ?? 'help');
     switch (command) {
         case 'sync':
-            await (0, download_db_1.downloadDatabase)();
+            await (0, download_db_1.downloadDatabase)(process.argv[3]);
             break;
         case 'status':
             printStatus();

package/dist/config.d.ts

@@ -1,21 +1,2 @@
-/**
- * Caminho para o banco de dados SQLite
- */
+export declare const DB_DIR: string;
 export declare const DB_PATH: string;
-/**
- * URL padrão para download do banco de dados (GitHub Releases)
- * NOTA: Você precisa substituir isso pela URL real do seu repositório
- */
-export declare const DEFAULT_DOWNLOAD_URL: string;
-/**
- * Timeout para downloads (30 segundos)
- */
-export declare const DOWNLOAD_TIMEOUT: number;
-/**
- * Tamanho máximo de chunk para downloads (1MB)
- */
-export declare const CHUNK_SIZE: number;
-/**
- * Número de tentativas de retry para download
- */
-export declare const MAX_RETRIES = 3;

package/dist/config.js

@@ -3,27 +3,42 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_RETRIES = exports.CHUNK_SIZE = exports.DOWNLOAD_TIMEOUT = exports.DEFAULT_DOWNLOAD_URL = exports.DB_PATH = void 0;
+exports.DB_PATH = exports.DB_DIR = void 0;
 const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
 /**
- * Caminho para o banco de dados SQLite
+ * Resolve o diretório `.db` tentando múltiplos candidatos em ordem de prioridade.
+ *
+ * Prioridade:
+ *  1. Vercel / Next.js build  — `<cwd>/node_modules/brasil-ceps-offline/.db`
+ *  2. Instalação npm padrão   — dois níveis acima de `dist/scripts/` → `<pkg>/.db`
+ *  3. Desenvolvimento local   — um nível acima de `dist/` → `<pkg>/.db`
+ *  4. Variável de ambiente    — `BRASIL_CEPS_DB_PATH` (caminho completo para o .sqlite)
+ *
+ * Retorna o primeiro diretório que já contenha `ceps.sqlite`, ou o caminho
+ * do candidato nº 1 como destino de instalação quando nenhum arquivo existe ainda.
  */
-exports.DB_PATH = path_1.default.join(__dirname, '..', '.db', 'ceps.sqlite');
-/**
- * URL padrão para download do banco de dados (GitHub Releases)
- * NOTA: Você precisa substituir isso pela URL real do seu repositório
- */
-exports.DEFAULT_DOWNLOAD_URL = process.env.BRASIL_CEPS_URL ||
-    'https://github.com/seu-usuario/brasil-ceps-offline-db/releases/download/latest/ceps.sqlite.zip';
-/**
- * Timeout para downloads (30 segundos)
- */
-exports.DOWNLOAD_TIMEOUT = 30 * 1000;
-/**
- * Tamanho máximo de chunk para downloads (1MB)
- */
-exports.CHUNK_SIZE = 1024 * 1024;
-/**
- * Número de tentativas de retry para download
- */
-exports.MAX_RETRIES = 3;
+function resolveDbDir() {
+    // Permite override total via env (útil em deploys customizados)
+    if (process.env.BRASIL_CEPS_DB_PATH) {
+        return path_1.default.dirname(process.env.BRASIL_CEPS_DB_PATH);
+    }
+    const candidates = [
+        // 1. Vercel/Next (cwd = raiz do projeto do usuário)
+        path_1.default.join(process.cwd(), 'node_modules', 'brasil-ceps-offline', '.db'),
+        // 2. npm install padrão: dist/scripts/ → ../../.db
+        path_1.default.join(__dirname, '..', '..', '.db'),
+        // 3. Fallback: dist/ → ../.db
+        path_1.default.join(__dirname, '..', '.db'),
+    ];
+    // Retorna o primeiro candidato que já tem o banco instalado
+    for (const dir of candidates) {
+        if (fs_1.default.existsSync(path_1.default.join(dir, 'ceps.sqlite'))) {
+            return dir;
+        }
+    }
+    // Nenhum banco encontrado → usa o candidato nº 1 como destino de instalação
+    return candidates[0];
+}
+exports.DB_DIR = resolveDbDir();
+exports.DB_PATH = process.env.BRASIL_CEPS_DB_PATH ?? path_1.default.join(exports.DB_DIR, 'ceps.sqlite');

package/dist/index.d.ts

@@ -129,4 +129,5 @@ export declare function getCepsInRadius(centerCep: string, radiusKm: number, lim
 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 { downloadDatabase } from './scripts/download-db';
 export type { Address, DistanceResult, AddressWithDistance, TimezoneResult, IbgeValidationResult, Coordinates, FallbackOptions, BrasilCepsConfig, } from './types';

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.brasilCeps = exports.BrasilCepsOffline = void 0;
+exports.downloadDatabase = exports.brasilCeps = exports.BrasilCepsOffline = void 0;
 exports.init = init;
 exports.findByCep = findByCep;
 exports.findByAddress = findByAddress;
@@ -13,12 +13,48 @@ exports.getCepsInRadius = getCepsInRadius;
 exports.getTimezone = getTimezone;
 exports.validateIbge = validateIbge;
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
-const config_1 = require("./config");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const database_1 = require("./database");
 const SELECT_ALL = `
   cep, state, city, neighborhood, street,
   ibge, ddd, timezone, latitude, longitude
 `;
+function log(msg) { console.log(`[brasil-ceps-offline] ${msg}`); }
+function resolveDatabasePath() {
+    const envPath = process.env.BRASIL_CEPS_DB_PATH;
+    if (envPath) {
+        if (!fs_1.default.existsSync(envPath)) {
+            throw new Error(`BRASIL_CEPS_DB_PATH definido, mas arquivo não existe: ${envPath}`);
+        }
+        return { dbPath: envPath, mode: 'env' };
+    }
+    const candidates = [
+        {
+            mode: 'serverless',
+            dbPath: path_1.default.join(process.cwd(), 'public', '.db', 'ceps.sqlite'),
+        },
+        {
+            mode: 'node',
+            dbPath: path_1.default.join(process.cwd(), 'node_modules', 'brasil-ceps-offline', '.db', 'ceps.sqlite'),
+        },
+        {
+            mode: 'relative',
+            dbPath: path_1.default.join(__dirname, '..', '..', '.db', 'ceps.sqlite'),
+        },
+        {
+            mode: 'cwd',
+            dbPath: path_1.default.join(process.cwd(), '.db', 'ceps.sqlite'),
+        },
+    ];
+    for (const candidate of candidates) {
+        if (fs_1.default.existsSync(candidate.dbPath))
+            return candidate;
+    }
+    const tried = candidates.map((c) => `- ${c.dbPath}`).join('\n');
+    throw new Error(`Banco de dados não encontrado. Caminhos testados:\n${tried}\n` +
+        `Execute "npx brasil-ceps-offline sync" (Node) ou "npx brasil-ceps-offline sync ./public/.db" (Vercel/Next).`);
+}
 /**
  * Motor de Inteligência Geográfica Offline para CEPs brasileiros.
  * Dados do Censo IBGE 2022 — sem rede, sem API keys, sem limites.
@@ -42,13 +78,21 @@ class BrasilCepsOffline {
     initialize(_config) {
         if (this.isInitialized)
             return;
+        const { dbPath, mode } = resolveDatabasePath();
+        if (mode === 'serverless') {
+            log(`Modo Serverless detectado. Usando banco em ${path_1.default.join(process.cwd(), 'public', '.db')}`);
+        }
         try {
-            this.db = new better_sqlite3_1.default(config_1.DB_PATH, { readonly: true, fileMustExist: true });
+            // Valida explicitamente antes de instanciar o better-sqlite3 (evita erros opacos em serverless)
+            if (!fs_1.default.existsSync(dbPath)) {
+                throw new Error(`Arquivo não existe: ${dbPath}`);
+            }
+            this.db = new better_sqlite3_1.default(dbPath, { readonly: true, fileMustExist: true });
             this.db.pragma('cache_size = -32000'); // 32 MB cache
             this.isInitialized = true;
         }
         catch (error) {
-            throw new Error(`Falha ao abrir o banco de dados em [${config_1.DB_PATH}]: ${error}`);
+            throw new Error(`Falha ao abrir o banco de dados em [${dbPath}]: ${error}`);
         }
     }
     /**
@@ -400,3 +444,5 @@ function validateIbge(cep, ibgeProvided) {
     exports.brasilCeps.initialize();
     return exports.brasilCeps.validateIbge(cep, ibgeProvided);
 }
+var download_db_1 = require("./scripts/download-db");
+Object.defineProperty(exports, "downloadDatabase", { enumerable: true, get: function () { return download_db_1.downloadDatabase; } });

package/dist/scripts/download-db.d.ts

@@ -1,2 +1,2 @@
-declare function downloadDatabase(): Promise<void>;
+declare function downloadDatabase(customPath?: string): Promise<void>;
 export { downloadDatabase };

package/dist/scripts/download-db.js

@@ -9,6 +9,7 @@ const path_1 = __importDefault(require("path"));
 const promises_1 = require("stream/promises");
 const stream_1 = require("stream");
 const zlib_1 = __importDefault(require("zlib"));
+const config_1 = require("../config");
 // ─── Constantes ──────────────────────────────────────────────────────────────
 const REPO = 'kaique-oliveira/brasil-ceps-offline';
 const ASSET_NAME = 'brasil-ceps.sqlite.gz';
@@ -16,32 +17,30 @@ 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() {
+function readVersionCache(versionFile) {
     try {
-        if (!fs_1.default.existsSync(VERSION_FILE))
+        if (!fs_1.default.existsSync(versionFile))
             return null;
-        return JSON.parse(fs_1.default.readFileSync(VERSION_FILE, 'utf-8'));
+        return JSON.parse(fs_1.default.readFileSync(versionFile, 'utf-8'));
     }
     catch {
         return null;
     }
 }
-function writeVersionCache(tag) {
+function writeVersionCache(versionFile, tag) {
     const data = { tag, downloadedAt: new Date().toISOString() };
-    fs_1.default.writeFileSync(VERSION_FILE, JSON.stringify(data, null, 2));
+    fs_1.default.writeFileSync(versionFile, JSON.stringify(data, null, 2));
 }
-function hasValidSchema() {
+function hasValidSchema(dbPath) {
     try {
-        if (!fs_1.default.existsSync(DB_PATH))
+        if (!fs_1.default.existsSync(dbPath))
             return false;
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
         const Database = require('better-sqlite3');
-        const db = new Database(DB_PATH, { readonly: true, fileMustExist: true });
+        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
         const cols = db.pragma('table_info(addresses)');
         db.close();
         return cols.some((c) => c.name === 'timezone');
@@ -51,10 +50,6 @@ function hasValidSchema() {
     }
 }
 // ─── 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...');
@@ -88,7 +83,7 @@ async function fetchLatestRelease() {
     }
 }
 // ─── Download e descompactação ────────────────────────────────────────────────
-async function downloadAndExtract(url) {
+async function downloadAndExtract(url, dbPath) {
     log(`Baixando banco de dados de: ${url}`);
     const res = await fetch(url, {
         headers: { 'User-Agent': USER_AGENT },
@@ -98,64 +93,64 @@ async function downloadAndExtract(url) {
     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);
+    const fileStream = fs_1.default.createWriteStream(dbPath);
     await (0, promises_1.pipeline)(nodeStream, zlib_1.default.createGunzip(), fileStream);
     log('Banco descompactado com sucesso.');
 }
 // ─── Ponto de entrada ─────────────────────────────────────────────────────────
-async function downloadDatabase() {
+async function downloadDatabase(customPath) {
     if (process.env.SKIP_POSTINSTALL_DB === 'true') {
         log('CI/CD detectado (SKIP_POSTINSTALL_DB=true). Pulando download.');
         return;
     }
-    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 dbDir = customPath ? path_1.default.resolve(customPath) : config_1.DB_DIR;
+    const dbPath = customPath ? path_1.default.join(dbDir, 'ceps.sqlite') : config_1.DB_PATH;
+    const versionFile = path_1.default.join(dbDir, 'version.json');
+    // Garante que o diretório existe antes de qualquer operação
+    if (!fs_1.default.existsSync(dbDir))
+        fs_1.default.mkdirSync(dbDir, { recursive: true });
+    log(`Banco será instalado em: ${dbPath}`);
     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()) {
+    const cache = readVersionCache(versionFile);
+    if (cache && cache.tag === tag && tag !== 'fallback' && hasValidSchema(dbPath)) {
         log(`Banco já está na versão mais recente (${tag}). Download ignorado.`);
         return;
     }
     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);
+        if (fs_1.default.existsSync(dbPath))
+            fs_1.default.unlinkSync(dbPath);
     }
-    else if (!hasValidSchema()) {
+    else if (!hasValidSchema(dbPath)) {
         log('Banco ausente ou com schema desatualizado. Iniciando download...');
-        if (fs_1.default.existsSync(DB_PATH))
-            fs_1.default.unlinkSync(DB_PATH);
+        if (fs_1.default.existsSync(dbPath))
+            fs_1.default.unlinkSync(dbPath);
     }
     try {
-        await downloadAndExtract(downloadUrl);
-        // Grava cache de versão apenas quando obteve tag real da API
+        await downloadAndExtract(downloadUrl, dbPath);
         if (tag !== 'fallback') {
-            writeVersionCache(tag);
-            log(`Versão ${tag} salva em ${VERSION_FILE}.`);
+            writeVersionCache(versionFile, tag);
+            log(`Versão ${tag} salva em ${versionFile}.`);
         }
         log('🚀 Banco de dados pronto. Zero-latência ativada.');
     }
     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);
+            if (fs_1.default.existsSync(dbPath))
+                fs_1.default.unlinkSync(dbPath);
             throw new Error(`Falha no download (incluindo fallback): ${err.message}`);
         }
-        // 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);
+        if (fs_1.default.existsSync(dbPath))
+            fs_1.default.unlinkSync(dbPath);
+        await downloadAndExtract(FALLBACK_URL, dbPath);
         log('🚀 Banco de dados instalado via fallback.');
     }
 }
-// Executa automaticamente apenas quando invocado diretamente (postinstall).
-// Quando importado pelo CLI ou pelos testes, não executa.
+// Executa automaticamente quando invocado diretamente (postinstall).
+// Quando importado como módulo (CLI, testes), não executa.
 if (require.main === module) {
     downloadDatabase().catch((err) => {
         console.error(`[brasil-ceps-offline] ❌ Erro crítico no instalador: ${err.message}`);

package/package.json

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