Migrador de documentos: envia arquivos e pastas de um caminho local para o Click.Drive via CLI, preservando a estrutura de pastas e tratando duplicidades automaticamente.
O script requer Node.js 18 ou superior (inclui o npm). Ele funciona da mesma forma em Windows, macOS e Linux.
| Sistema | Como instalar |
|---|---|
| Windows | Baixe o instalador LTS em nodejs.org e execute-o, ou instale via nvm-windows. |
| macOS | brew install node (via Homebrew), ou baixe o instalador LTS em nodejs.org. |
| Linux | Use o gerenciador de pacotes da distro (ex: sudo apt install nodejs npm no Ubuntu/Debian) ou, para ter controle de versão, o nvm. |
Para confirmar a instalação:
node --version
npm --versiongit clone <url-deste-repositorio>
cd clickdrive-migrator
npm installCopie o arquivo de exemplo e preencha com as credenciais da sua conta:
# Linux, macOS, Git Bash ou WSL
cp .env.example .env# Windows (PowerShell)
Copy-Item .env.example .env Windows (cmd.exe)
copy .env.example .env| Variável | Obrigatória | Padrão | Descrição |
|---|---|---|---|
CLICKDRIVE_API_URL |
Sim | — | URL base da api-clickdrive (ex: http://localhost:8080) |
CLICKDRIVE_TOKEN |
Sim | — | Token de sessão do Tavola, sem o prefixo Bearer |
CLICKDRIVE_CONCURRENCY |
Não | 4 |
Máximo de requisições (upload/criação de pasta) em paralelo |
CLICKDRIVE_MAX_RETRIES |
Não | 3 |
Tentativas extras em erros transitórios (5xx, timeout, rede) |
CLICKDRIVE_RETRY_BASE_MS |
Não | 500 |
Atraso base (ms) do backoff exponencial entre tentativas |
CLICKDRIVE_REQUEST_TIMEOUT_MS |
Não | 30000 |
Tempo máximo (ms) de espera por uma requisição antes de considerá-la falha (conta como erro transitório, reenviada com backoff) |
CLICKDRIVE_RESET_STATE |
Não | false |
Se true, ignora o checkpoint de retomada e migra tudo do zero |
A cada pasta criada ou arquivo enviado com sucesso, o script grava um checkpoint em ./.clickdrive-migrator-state/<hash-do-caminho>.jsonl (um arquivo por caminho migrado). Se a execução for interrompida — queda de energia, perda de rede, Ctrl+C — basta rodar o mesmo comando novamente: tudo que já foi migrado com sucesso é reconhecido pelo checkpoint e pulado (sem nova chamada à API), e a migração continua apenas nos itens pendentes.
Esse checkpoint é local ao script (não é uma consulta à ClickDrive, que não expõe busca por nome), então ele só sabe o que este processo já migrou. Um conflito de nome com algo que já existia na ClickDrive antes, ou criado por outra via, continua caindo no fluxo de duplicidade descrito abaixo.
Para forçar uma migração do zero, ignorando qualquer checkpoint existente, defina CLICKDRIVE_RESET_STATE=true ou apague o arquivo correspondente em .clickdrive-migrator-state/.
Para não sobrecarregar a api-clickdrive em migrações grandes, os uploads e criações de pasta respeitam um limite de concorrência (CLICKDRIVE_CONCURRENCY, padrão 4 requisições simultâneas) e falhas transitórias (erros 5xx, timeout ou de rede) são reenviadas automaticamente com backoff exponencial (CLICKDRIVE_MAX_RETRIES tentativas, começando em CLICKDRIVE_RETRY_BASE_MS). Erros definitivos (401, 403, 404, 409, 413, 422) não são reenviados, 409 segue o fluxo de duplicidade descrito abaixo, os demais contam como falha.
Se você já tem um token criado para esta integração, apenas copie e cole o valor em CLICKDRIVE_TOKEN. Caso ainda não tenha um, gere um novo:
-
Gere um Access Token
- Faça login na sua conta.
- Vá em Configurações e depois em API.
- Clique em Gerar Access Token.
- Preencha uma descrição e clique em Gerar.
- Copie e guarde o token.
-
Associe o usuário à API
- Na mesma tela onde o token foi gerado, associe seu e-mail à API e clique em Salvar e-mail.
node script-main.js "./caminho-para-pasta/arquivo.doc"
node script-main.js "/home/usuario/financeiro"- Se o caminho informado for um arquivo, ele é enviado diretamente para a raiz do workspace no Click.Drive.
- Se o caminho informado for uma pasta, o script cria essa pasta na raiz do workspace e replica toda a árvore de subpastas e arquivos dentro dela, criando cada pasta necessária antes de enviar seus arquivos.
O script auxiliar scripts/list-workspace.js lista a árvore de pastas e arquivos já existente no workspace do Click.Drive (estilo tree), útil para conferir o resultado de uma migração. Usa as mesmas variáveis de ambiente do migrador (.env: CLICKDRIVE_API_URL, CLICKDRIVE_TOKEN).
node scripts/list-workspace.js # lista a árvore inteira a partir da raiz
node scripts/list-workspace.js <ancestor_id> # lista a árvore a partir de uma pasta específicaAo final, exibe a contagem total de pastas e arquivos encontrados.
Quando a api-clickdrive responde 409 Conflict (já existe um arquivo ou pasta com o mesmo nome naquele local), o script não tenta reenviar o item para o mesmo destino. Em vez disso, ele garante uma subpasta duplicated no Click.Drive, no mesmo local remoto onde ocorreu o conflito, cria/envia o item (arquivo ou pasta, com seu conteúdo) dentro dela, e segue migrando o restante normalmente. O arquivo/pasta local não é movido ou alterado.
Exemplo: se /home/usuario/financeiro/contratos/contrato1.txt conflitar no Click.Drive dentro da pasta contratos, o arquivo é enviado para uma pasta duplicated criada no Click.Drive dentro de contratos.
O nome duplicated é reservado pelo script em qualquer nível da árvore migrada: se você já tiver uma pasta local com esse nome (criada por você, não pelo script), ela é inteiramente ignorada na migração, sem aviso no console, sem contar como falha nas estatísticas finais. Como essa exclusão acontece na leitura da árvore local, CLICKDRIVE_RESET_STATE=true não resolve o caso, já que ele só limpa o checkpoint de retomada, não muda quais pastas são consideradas na travessia. Se você tiver uma pasta duplicated legítima, renomeie-a antes de migrar.
Cada execução grava um arquivo em logs/migration-<timestamp>.log com todos os arquivos processados, pastas criadas, uploads concluídos e falhas, além de exibir o mesmo conteúdo no console.
| Código | Significado |
|---|---|
0 |
Migração concluída sem falhas |
1 |
Uso inválido, configuração ausente, caminho inexistente ou pelo menos uma falha durante a migração |