@soadtech/nimbus-sdk

Cliente TypeScript para el data plane de Nimbus. Envuelve los endpoints /api/v1/files y /api/v1/folders con una API key de proyecto. Sin dependencias de runtime: usa fetch/FormData/Blob nativos (Node ≥ 18).

Instalación

npm install @soadtech/nimbus-sdk

Uso

import { Nimbus } from '@soadtech/nimbus-sdk';

const nimbus = new Nimbus({
  apiKey: process.env.NIMBUS_KEY!,        // nmb_live_... / nmb_test_...
  baseUrl: 'https://nimbus.tu-nas.local', // default: http://localhost:4100
});

// Carpetas (deben existir antes de subir)
await nimbus.createFolder('avatars', { public: true }); // pública → URLs directas
await nimbus.createFolder('invoices');                  // privada → URLs firmadas
const folders = await nimbus.listFolders();

// Subir (buffer de Node, Uint8Array, ArrayBuffer o Blob)
const { key, url, shortUrl, public: isPublic } = await nimbus.upload(buffer, {
  folder: 'avatars',
  filename: 'foto.jpg',
  contentType: 'image/jpeg', // opcional; la API valida por magic bytes igualmente
});

// Listar / URL firmada / borrar
const files = await nimbus.list({ folder: 'avatars', limit: 20 });
const fresh = await nimbus.getUrl(key, { ttl: 900 }); // string
const signed = await nimbus.getSignedUrl(key);        // { url, expiresIn }
await nimbus.delete(key);

Carpetas públicas vs privadas

El flag public de la carpeta decide cómo se sirven sus archivos:

| | public: true | public: false (default) | |---|---|---| | Objeto en MinIO | ACL public-read | privado | | url que devuelve la API | directa permanente (sin firma) | presigned (caduca, TTL) | | expiresIn en getSignedUrl | 0 (no caduca) | segundos del TTL |

En ambos casos cada archivo trae también un shortUrl estable y corto (https://tu-api/f/<id>) que hace 302 a la URL final. Es ideal para guardar en BD o poner en un <img src>: no caduca como enlace, y si el archivo es privado genera una presigned fresca en cada acceso.

// Público: url directa, shortUrl permanente
const a = await nimbus.upload(buf, { folder: 'avatars' });
// a.url      → https://cdn.tudominio.com/nimbus/<key>
// a.shortUrl → https://tu-api/f/aB3xY9   (redirect 302)

// Privado: url presigned temporal, shortUrl estable que regenera la firma
const b = await nimbus.upload(buf, { folder: 'invoices' });
// b.url      → https://cdn.tudominio.com/nimbus/<key>?X-Amz-...
// b.shortUrl → https://tu-api/f/Kp9mZ2   (302 a una presigned nueva cada vez)

Errores

Cualquier respuesta >= 400 lanza NimbusError con status y body:

import { NimbusError } from '@soadtech/nimbus-sdk';

try {
  await nimbus.upload(buffer, { folder: 'no-existe' });
} catch (err) {
  if (err instanceof NimbusError) {
    console.error(err.status, err.message); // 400 'La carpeta "no-existe" no existe; ...'
  }
}

API

| Método | Devuelve | |---|---| | upload(data, { folder, filename?, contentType? }) | UploadedFile (incl. url, shortUrl, public) | | list({ folder?, limit?, skip? }) | FileListItem[] | | getUrl(key, { ttl? }) | string | | getSignedUrl(key, { ttl? }) | PresignedUrl | | delete(key) | { ok: true } | | listFolders() | FolderInfo[] | | createFolder(name, { public? }) | FolderInfo | | deleteFolder(name) | { ok: true } |