@cubehosting/sdk chama a API pública sem você montar o pedido à mão: um método para cada rota, com os tipos do TypeScript, os logs ao vivo, o envio de arquivos grandes ao Blob e os erros com o code da API. Não tem dependências: usa o fetch do Node.js 20 ou mais novo.
Instalar
Começar
Crie uma chave em Chaves de API e guarde na variávelCUBE_API_KEY. O modelo Leitura basta para ver projetos, logs e métricas; para enviar e controlar, o Deploy (CI/CD); para os arquivos do projeto, uma chave com Arquivos · ler e Arquivos · escrever (o Ler e escrever tem as duas). Veja as permissões. A chave Só Blob alcança só os métodos do Blob.
Enviar código
O.zip vai como Buffer, Uint8Array ou Blob, com o mesmo limite do plano (5 MB no Free e 10 MB nos pagos). Os outros campos são os de Criar um projeto; variables é um objeto { NOME: "valor" }.
.zip, respeitando o .gitignore, use a CLI (cube deploy).
Logs ao vivo
lines linhas, depois as novas, e cada mudança de estado como status. follow: false manda só as últimas e termina; source: 'build' mostra a instalação. Feche com break ou com um signal. O texto é do seu projeto: mostre como texto, nunca como HTML.
Blob
OuploadBlob faz os três passos do envio: pede o envio, manda os bytes direto ao armazenamento (em partes de 16 MB acima disso) e confirma. Para um arquivo grande, passe um Blob do disco, que não carrega tudo na memória:
CubeUploadError com o objectId: chame uploadBlob(path, data, { objectId }) com o mesmo arquivo para mandar só o que falta. As partes que chegaram ficam guardadas por 24 horas.
Arquivos do projeto
Com uma chave com Arquivos · ler (files:read) para ler e Arquivos · escrever (files:write) para mudar, nos planos pagos. Tudo acontece na caixa do seu projeto, e cada ação entra na Atividade com o nome da chave.
O compareFiles diz, pelo tamanho e o SHA-256, se cada arquivo do seu computador é new, changed, unchanged ou blocked no projeto, sem mudar nada. O uploadFile manda um arquivo de até 500 MB em partes de 16 MB (o envio em partes do começo ao fim) e o applyProjectChanges faz valer no projeto no ar, reinstalando as dependências só se o manifesto mudou:
shouldOverwrite: true (sem ele, 409 file_already_exists). O readFile e o writeFile são para texto até 1 MB; o downloadFile e o downloadFilesZip pedem o link (que só abre com a mesma chave) e devolvem a resposta para você ler.
Erros
Toda resposta de erro vira umCubeApiError, com o code fixo em inglês da página Códigos de erro e a mensagem em português para mostrar a uma pessoa.
Sem conexão ou com o tempo esgotado, o erro é um
CubeConnectionError. Todos herdam de CubeError.
Segurança
- A chave fica num campo privado do cliente: não aparece no
console.log, noJSON.stringifynem em erro nenhum. - O SDK não segue redirecionamento: a chave só vai ao endereço da API.
- Os bytes do Blob vão direto ao armazenamento pela URL assinada, sem a chave.
- O
User-Agentleva só o nome e a versão do SDK.

