🤖 Rav Archive

✨ Arquivamento automático com 🌐 Playwright e 🕰️ Wayback Machine

Biblioteca NPM + CLI para preservação digital automática

🎯 Visão Geral

O RAV Archive é uma ferramenta completa para arquivamento automático de URLs no Internet Archive's Wayback Machine. Funciona como biblioteca NPM para desenvolvedores e CLI para usuários finais.

✨ Por que usar?

• 🚀 Zero configuração - Instalação e setup automáticos
• 📦 Dual-mode - Use como lib ou CLI
• 🧠 Inteligente - Evita duplicatas e detecta limites
• 📊 Transparente - Relatórios detalhados em tempo real
• ⚡ Eficiente - Processamento em lote otimizado

📦 Instalação Rápida

• COMO INSTALAR NODE JS NO WINDOWS?

npm i -g rav-archive           # ✅ Recomendado
npm install -g rav-archive     # ✅ Completo

# Após instalação, use em qualquer lugar:
rav-archive --help

🔍 VERIFICAR INSTALAÇÃO

npm ls -g rav-archive          # ✅ Listar pacote
npm list -g rav-archive        # ✅ Completo
rav-archive --version          # ✅ Versão instalada

🗑️ DESINSTALAR GLOBALMENTE

npm un -g rav-archive          # ✅ Recomendado  
npm uninstall -g rav-archive   # ✅ Completo
npm remove -g rav-archive      # ✅ Alternativo

🛠️ Uso Imediato

// Como biblioteca
const { RavArchive } = require('rav-archive');
const archive = new RavArchive();

// Arquivar URLs
await archive.archiveUrl('https://exemplo.com');
await archive.archiveFromFile('links.txt');

// Verificar status
const result = await archive.checkArchived('https://site.com');
const stats = archive.getStats();

# Como CLI
rav-archive file links.txt
rav-archive url https://exemplo.com
rav-archive stats
rav-archive --help

# Windows (batch)
iniciar.bat

🏁 Primeiros Passos

1. Prepare suas URLs

Crie um arquivo links.txt:

https://github.com
https://example.com
https://seu-site.com/blog

2. Execute

# Se instalou via NPM
rav-archive file links.txt

# Se baixou o projeto
node src/cli.js file links.txt

# Windows
iniciar.bat

3. Acompanhe o Progresso

• ✅ Configuração automática
• 🔍 Verificação de URLs existentes
• 📤 Arquivamento de novas URLs
• 📊 Relatório final gerado

⚡ Recursos Principais

🔧 Configuração Inteligente

• Instalação automática do Playwright
• Detecção de ambiente Node.js
• Setup completo sem intervenção

🧠 Lógica Avançada

• Verificação prévia no Wayback Machine
• Detecção de limites e rate limiting
• Retry automático em falhas
• Delays inteligentes entre requisições

📊 Monitoramento Completo

• Progresso em tempo real
• Estatísticas detalhadas
• Logs estruturados em JSON
• Relatórios em texto formatado

🛡️ Robusto e Confiável

• Tratamento de erros granular
• Timeouts configuráveis
• Conexão resiliente
• VPN-friendly

🛠️ Modos de Uso

📦 Como Biblioteca

Ideal para integrar em aplicações existentes:

const { RavArchive } = require('rav-archive');

// Configuração customizada
const archive = new RavArchive({
    browser: { headless: true },
    wayback: { maxAttemptsPerUrl: 5 }
});

// Fluxo completo
async function arquivarSites() {
    const resultados = await archive.archiveUrls([
        'https://site1.com',
        'https://site2.com'
    ]);
    
    console.log(`✅ ${resultados.metadata.summary.archived} URLs salvas`);
    console.log(`📊 Taxa de sucesso: ${((resultados.metadata.summary.archived / resultados.metadata.summary.total) * 100).toFixed(1)}%`);
    
    // URLs com sucesso
    const urlsSalvas = archive.getArchivedUrls();
    urlsSalvas.forEach(url => {
        console.log(`🔗 ${url.originalUrl} → ${url.archiveUrl}`);
    });
}

arquivarSites();

💻 Como CLI

Perfeito para uso direto e automação:

# Arquivamento de arquivo
rav-archive file lista.txt

# URL única
rav-archive url https://exemplo.com

# Múltiplas URLs
rav-archive batch https://site1.com,https://site2.com,https://site3.com

# Verificação
rav-archive check https://exemplo.com

# Estatísticas
rav-archive stats

# Ajuda completa
rav-archive --help

📊 Resultados e Relatórios

🎯 Saída em Tempo Real

📊 [5/10] https://exemplo.com
🔄 Tentativas: 1/4
📈 Progresso: 5/10 | ✅ 3 | ❌ 2 | 50.0%
⏱️  Tempo: 45s decorridos | ~45s restantes

📄 Relatório Final

RELATÓRIO DE ARQUIVAMENTO - RAV ARCHIVE
============================================================
Data de geração: 15/12/2024 14:30:25
Total de URLs processadas: 10
URLs arquivadas com sucesso: 8
Falhas: 2
Taxa de sucesso: 80.0%

📁 Estrutura de Saída

📁 DADOS/
└── 📄 archive_results.json    # Resultados estruturados

📁 DOCS/
└── 📄 relatorio_2024-12-15T143025Z.txt  # Relatório formatado

⚙️ Configuração

🔧 Configuração Customizada

const archive = new RavArchive({
    browser: {
        headless: true,           // Modo headless
        timeout: 60000,           // Timeout de 60s
    },
    wayback: {
        baseDelay: 10000,         // Delay base de 10s
        maxAttemptsPerUrl: 4,     // Máximo de tentativas
        maxRetries: 2             // Retries por falha
    },
    directories: {
        data: 'DADOS',           // Pasta de dados
        docs: 'RELATORIOS'       // Pasta de relatórios
    }
});

📝 Formato do links.txt

# URLs válidas (uma por linha)
https://exemplo.com
https://site.com/pagina
http://outro-site.com/artigo

# Evite:
exemplo.com                    # ❌ Sem protocolo
javascript:void(0)             # ❌ URL inválida
                               # ❌ Linha vazia

📁 Estrutura de Arquivos

📁 rav-archive/
├── 📄 package.json                     # Configuração NPM
├── 📄 README.md                        # Documentação
├── 📄 LICENSE                          # Licença MIT
├── ⚡ iniciar.bat                      # Launcher Windows
├── 📝 links.txt                        # URLs exemplo
├── 🖼️ rav-archive.gif                  # Demonstração
├── 📁 src/                             # Código fonte
│   ├── 📄 index.js                     # Ponto de entrada (Lib)
│   ├── 📄 cli.js                       # Ponto de entrada (CLI)
│   ├── 📁 core/                        # Núcleo principal
│   │   ├── 📄 AutoInstaller.js         # Setup automático
│   │   ├── 📄 ConnectionManager.js     # Gerenciamento conexão
│   │   └── 📄 SmartArchiveChecker.js   # Lógica arquivamento
│   ├── 📁 commands/                    # Comandos CLI
│   │   ├── 📄 file.js                  # Arquivo → URLs
│   │   ├── 📄 url.js                   # URL única
│   │   ├── 📄 batch.js                 # Múltiplas URLs
│   │   ├── 📄 check.js                 # Verificação
│   │   └── 📄 stats.js                 # Estatísticas
│   ├── 📁 config/                      # Configurações
│   │   ├── 📄 default.js               # Config padrão
│   │   ├── 📄 colors.js                # Cores console
│   │   └── 📄 constants.js             # Constantes
│   └── 📁 utils/                       # Utilitários
│       ├── 📄 logger.js                # Logging
│       ├── 📄 validator.js             # Validação
│       └── 📄 file-manager.js          # Gerenciamento arquivos
├── 📁 DOCS/                            # [GERADO]
│   └── 📄 relatorio_[data].txt         # Relatórios
└── 📁 DADOS/                           # [GERADO]
    └── 📄 archive_results.json         # Resultados JSON

🏗️ Arquitetura

🔄 Fluxo de Processamento

1. Setup → Instala dependências automaticamente
2. Validação → Verifica URLs e conexão
3. Verificação → Checa URLs já arquivadas
4. Arquivamento → Processa URLs novas
5. Relatório → Gera resultados e estatísticas

🎯 Design Patterns

• Modular → Componentes independentes
• Configurável → Customização flexível
• Extensível → Fácil adição de features
• Robusto → Tratamento completo de erros

🐛 Troubleshooting

❌ Problemas Comuns

# Erro: Cannot find module 'playwright'
# Solução: Execute novamente (instala automaticamente)
rav-archive file links.txt

# Erro: Navigation timeout
# Solução: Verifique conexão internet
ping 8.8.8.8

# Erro: Invalid URL
# Solução: Verifique formato no links.txt
cat links.txt

🔧 Comandos de Diagnóstico

# Verificar instalação
node --version
npm list rav-archive

# Testar conexão
npx playwright test

# Limpar cache
npx playwright install

📄 Licença

Este projeto está sob licença MIT. Veja o arquivo LICENSE para detalhes.

🙋 FAQ Rápido

Não! O RAV Archive instala todas as dependências automaticamente na primeira execução.

Sim! É até recomendado para evitar limites de rate limiting do Wayback Machine.

Centenas, mas recomenda-se processar em lotes de 50-100 URLs com intervalos.

O sistema faz até 4 tentativas com retry automático antes de marcar como falha.

Feito com 💚 por RavenaStar

⬆ Voltar ao topo