@zentrax/sdk

SDK Node.js/TypeScript não-oficial para a API v1 do Zentrax (/v1/apps, /v1/databases, /v1/account).

• ✅ 100% TypeScript, com tipos completos para todas as respostas
• ✅ Zero dependências em runtime (usa fetch nativo — Node.js 18+)
• ✅ Suporte a CJS e ESM
• ✅ Erros tipados (ZentraxAuthError, ZentraxNotFoundError, ZentraxValidationError, ...)

Instalação

npm install @zentrax/sdk

Uso básico

import { ZentraxSDK } from '@zentrax/sdk';

const zentrax = new ZentraxSDK({
  apiToken: process.env.ZENTRAX_API_TOKEN!,
  // baseUrl: 'https://api.myzentrax.lat', // opcional, esse é o padrão
});

const apps = await zentrax.apps.list();
console.log(apps);

Configuração do cliente

new ZentraxSDK({
  apiToken: 'seu-token',   // obrigatório
  baseUrl: 'https://...',  // opcional
  timeoutMs: 30_000,       // opcional, padrão 30s
  headers: {},             // opcional, headers extras
  fetch: customFetch,      // opcional, para ambientes sem fetch global
});

Recursos disponíveis

zentrax.apps

| Método | Rota | Descrição | |---|---|---| | apps.list() | GET /v1/apps | Lista todas as aplicações | | apps.get(appId) | GET /v1/apps/:id | Detalhes de uma aplicação | | apps.stats(appId) | GET /v1/apps/:id/stats | Uso de CPU/RAM/rede | | apps.logs(appId, { tail }) | GET /v1/apps/:id/logs | Últimas linhas de log | | apps.start(appId) | POST /v1/apps/:id/start | Inicia a aplicação | | apps.stop(appId) | POST /v1/apps/:id/stop | Para a aplicação | | apps.restart(appId) | POST /v1/apps/:id/restart | Reinicia a aplicação | | apps.delete(appId) | POST /v1/apps/:id/delete | Remove a aplicação | | apps.rebuild(appId) | POST /v1/apps/:id/rebuild | Reconstrói a imagem | | apps.backup(appId) | POST /v1/apps/:id/backup | Gera e baixa um backup .zip (retorna Buffer) | | apps.commit(appId, zip) | POST /v1/apps/:id/commit | Substitui o código por um novo .zip | | apps.upload(zip, opts) | POST /v1/apps/upload | Cria uma aplicação a partir de um .zip | | apps.listFiles(appId, path?) | GET /v1/apps/:id/files | Lista arquivos/diretórios | | apps.readFile(appId, path) | GET /v1/apps/:id/files/content | Lê conteúdo de um arquivo | | apps.writeFile(appId, path, content) | PUT /v1/apps/:id/files/content | Escreve conteúdo (máx 2 MB) | | apps.renameFile(appId, oldPath, newPath) | PUT /v1/apps/:id/files/rename | Renomeia/move | | apps.createFolder(appId, path) | POST /v1/apps/:id/files/mkdir | Cria diretório | | apps.deleteFile(appId, path) | POST /v1/apps/:id/files/delete | Remove arquivo/diretório |

zentrax.databases

| Método | Rota | Descrição | |---|---|---| | databases.create(params) | POST /v1/databases | Cria uma database | | databases.list() | GET /v1/databases | Lista databases | | databases.get(id) | GET /v1/databases/:id | Detalhes + credenciais | | databases.delete(id) | DELETE /v1/databases/:id | Remove a database | | databases.start(id) | POST /v1/databases/:id/start | Inicia | | databases.stop(id) | POST /v1/databases/:id/stop | Para | | databases.restart(id) | POST /v1/databases/:id/restart | Reinicia | | databases.logs(id, { tail }) | GET /v1/databases/:id/logs | Logs | | databases.stats(id) | GET /v1/databases/:id/stats | Uso de recursos |

zentrax.account

| Método | Rota | Descrição | |---|---|---| | account.get() | GET /v1/account | Usuário, plano e aplicações |

Exemplos

Criar e acompanhar uma database

const db = await zentrax.databases.create({
  name: 'meu-banco',
  engine: 'postgresql',
  memoryMb: 256,
});

console.log(db.connectionString);

const stats = await zentrax.databases.stats(db.id);
console.log(stats);

Deploy de uma aplicação a partir de um zip local

import { readFile } from 'node:fs/promises';

const zipBuffer = await readFile('./meu-app.zip');

const result = await zentrax.apps.upload(zipBuffer, {
  appName: 'minha-api',
  language: 'node',
  command: 'node index.js',
  memory: 512,
}, 'meu-app.zip');

console.log(result.appId, result.status);

Editar um arquivo remoto

await zentrax.apps.writeFile(appId, '/app/src/config.json', JSON.stringify({ foo: 'bar' }));

Tratamento de erros

import { ZentraxNotFoundError, ZentraxApiError } from '@zentrax/sdk';

try {
  await zentrax.apps.get('id-invalido');
} catch (err) {
  if (err instanceof ZentraxNotFoundError) {
    console.log('Aplicação não encontrada');
  } else if (err instanceof ZentraxApiError) {
    console.log('Erro da API:', err.status, err.body);
  } else {
    throw err;
  }
}

Estrutura do projeto

src/
  client.ts           -> classe ZentraxSDK (ponto de entrada)
  http-client.ts       -> cliente HTTP interno (fetch, auth, erros)
  errors.ts            -> classes de erro tipadas
  resources/
    apps.ts             -> recurso `zentrax.apps`
    databases.ts         -> recurso `zentrax.databases`
    account.ts           -> recurso `zentrax.account`
  types/
    apps.ts, databases.ts, account.ts -> tipos de request/response
  index.ts              -> exports públicos

Build

npm install
npm run build     # gera dist/ (CJS + ESM + .d.ts) via tsup
npm run typecheck  # apenas checa tipos