# directus-bulk-fetch

[![npm version](https://badge.fury.io/js/directus-bulk-fetch.svg)](https://www.npmjs.com/package/directus-bulk-fetch)
[![License](https://img.shields.io/npm/l/directus-bulk-fetch.svg)](LICENSE)

CLI para download em massa de arquivos da coleção `directus_files` do Directus.

## Descrição

Este pacote fornece uma ferramenta de linha de comando interativa para conectar-se a uma instância Directus e fazer o download em massa de arquivos da coleção `directus_files`, com suporte a downloads paralelos, retry automático, filtros por data e muito mais.

## Funcionalidades

- 🔐 Autenticação por token
- 📥 Download automático de arquivos
- 🚀 Downloads paralelos/simultâneos configuráveis
- 🔄 Retry automático com backoff exponencial
- ⏱️ Timeout configurável para requisições
- 🎯 Filtros por período de upload
- 💾 Detecção de arquivos já baixados (evita re-downloads)
- 📋 Modo resume: retoma downloads que falharam
- 📊 Relatório detalhado com estatísticas
- 💥 Rastreamento de falhas em JSON
- ⚙️ Configuração via arquivo .env ou modo interativo

## Instalação

### Via npm (Recomendado)

```bash
npm install -g directus-bulk-fetch
```

Ou com npx (sem instalação global):

```bash
npx directus-bulk-fetch
```

## Configuração

Copie o arquivo `.env.example` para `.env` e configure as variáveis:

```bash
cp .env.example .env
```

Edite o arquivo `.env` com suas credenciais:

```env
# Configuração do Directus
DIRECTUS_URL=http://localhost:8055
DIRECTUS_TOKEN=seu-token-aqui

# Configuração de Rate Limit (intervalo em milissegundos entre requisições)
RATE_LIMIT_INTERVAL_MS=200

# Número de downloads simultâneos
CONCURRENT_DOWNLOADS=3

# Diretório de destino para os arquivos baixados
OUTPUT_DIR=./downloads
```

## Uso

### Modo Interativo (Recomendado)

Se instalado globalmente:

```bash
directus-bulk-fetch
```

Com npx:

```bash
npx directus-bulk-fetch
```

### Menu Interativo

O CLI apresenta as seguintes opções:

1. **Fazer download de arquivos**: Inicia o processo de download com os parâmetros configurados
2. **Ver configuração atual**: Exibe as configurações em uso
3. **Configurar credenciais**: Permite alterar as credenciais para a sessão atual
4. **Sair**: Encerra a aplicação

### Parâmetros de Download

Durante o processo de download, você poderá configurar:

- **Data de início**: Filtrar arquivos a partir de uma data de upload
- **Data de fim**: Filtrar arquivos até uma data de upload
- **Limite de arquivos**: Quantidade máxima de arquivos a baixar (-1 para todos)
- **Diretório de destino**: Onde os arquivos serão salvos
- **Intervalo entre requisições**: Tempo em milissegundos entre cada lote de requisições (rate limiting)
- **Número de downloads simultâneos**: Quantidade de arquivos baixados em paralelo (1-10)
- **Número de retries**: Tentativas em caso de falha (1-10)
- **Timeout**: Tempo máximo de espera por requisição em milissegundos
- **Modo resume**: Baixar apenas arquivos que falharam anteriormente

## Como Funciona

1. **Conexão**: Conecta-se ao Directus usando a URL e token fornecidos
2. **Consulta**: Busca registros da coleção `directus_files` com os filtros de data aplicados
3. **Download em Lotes**: Baixa arquivos em lotes paralelos (configurável) usando a API do Directus (`/assets/:id`)
4. **Retry com Backoff**: Tenta novamente automaticamente em caso de falha, com espera exponencial
5. **Validação**: Verifica se o arquivo já existe antes de baixar (evita duplicatas)
6. **Rastreamento de Falhas**: Salva em JSON os arquivos que falharam após todas as tentativas
7. **Modo Resume**: Permite retomar o download apenas dos arquivos que falharam

## Exemplos de Uso

### Download de todos os arquivos

```bash
npx directus-bulk-fetch
# Selecione "Fazer download de arquivos"
# Deixe todos os filtros vazios
# Defina limite como -1
```

### Download com período específico

```bash
npx directus-bulk-fetch
# Selecione "Fazer download de arquivos"
# Informe data de início: 2024-01-01
# Informe data de fim: 2024-12-31
```

### Download em modo resume (após falhas)

```bash
npx directus-bulk-fetch
# Selecione "Fazer download de arquivos"
# Responda "Sim" para "Modo resume"
# Apenas arquivos que falharam anteriormente serão baixados
```

## Notas Técnicas

- ✅ Arquivos já existentes no diretório de destino não serão baixados novamente
- 🔄 O rate limiting ajuda a evitar sobrecarga no servidor Directus
- 💾 Falhas são salvas em `failed-downloads.json` no diretório de destino
- ⏱️ O retry usa backoff exponencial (1s, 2s, 3s, etc.)
- 🔗 URLs do Directus com barra final (`/`) são tratadas corretamente
- 🎯 Apenas arquivos com `filename_disk` válido são processados
- 🔐 Autenticação via query parameter para compatibilidade com `/assets` endpoint

## Solução de Problemas

### Erro 404 nos downloads

Verifique se:

- A URL do Directus está correta (pode ter ou não barra final)
- O token tem permissões para acessar a coleção `directus_files`
- Os arquivos existem fisicamente no storage do Directus

### Downloads lentos

Aumente o número de downloads simultâneos no `.env`:

```env
CONCURRENT_DOWNLOADS=5  # Aumentar de 3 para 5
```

### Muitos timeouts

Aumente o timeout no `.env`:

```env
TIMEOUT_MS=60000  # 60 segundos
```

## Roadmap

- [ ] Suporte a diferentes formatos de arquivo (não apenas JPG)
- [ ] Buscar metadados do arquivo para nome correto
- [ ] Opção de escolher coleção customizada
- [ ] Progress bar visual
- [ ] Exportação de relatório em CSV

## Licença

Ver arquivo LICENSE