SDK JavaScript / Node.js

El SDK oficial de FiveHub.pro para JavaScript y TypeScript. Disponible para Node.js y browser (fetch nativo).

Instalación

npm install fivehub.pro

Inicialización

import { FiveHubClient } from 'fivehub.pro';

const client = new FiveHubClient({
  apiKey: 'TU_API_KEY',
  // organizationId: 'org_xxx', // opcional, solo con claves de usuario
  // baseUrl: 'https://fivehub.pro', // por defecto
});

Opciones de configuración

Opción	Tipo	Obligatoria	Descripción
apiKey	string	Sí	Tu API Key del Dashboard.
organizationId	string	No	Solo necesario con claves de usuario.
baseUrl	string	No	URL base de la API. Default: https://fivehub.pro.

---

Métodos — Assets

client.list(options?)

Lista los assets con paginación y filtro de carpeta opcionales.

// Todos los assets (sin filtro de carpeta)
const { assets, total } = await client.list({ limit: 20, offset: 0 });

// Solo assets en el nivel raíz (sin carpeta)
const { assets: root } = await client.list({ folderId: null });

// Assets dentro de una carpeta específica
const { assets: inFolder } = await client.list({ folderId: 'folder_abc123' });

Opción	Tipo	Descripción
limit	number	Máx. 100, default 50.
offset	number	Paginación. Default 0.
folderId	string | null	null=raíz, "id"=carpeta, omitir=todos.

---

client.upload(file, name?, folderId?)

Sube un archivo. Acepta File (browser) o Blob (Node.js). Máximo 100 MB.

Browser

const file = input.files![0];

// Subir al nivel raíz
const asset = await client.upload(file);

// Subir dentro de una carpeta
const asset = await client.upload(file, undefined, 'folder_abc123');
console.log('Subido:', asset.publicUrl);

Node.js

import { readFileSync } from 'fs';

const buffer = readFileSync('./recurso.zip');
const blob = new Blob([buffer], { type: 'application/zip' });

// Subir a una carpeta
const asset = await client.upload(blob, 'recurso-v2.zip', 'folder_abc123');
console.log('Subido:', asset.publicUrl);

---

client.get(id)

Obtiene los metadatos de un asset por su ID.

const asset = await client.get('asset_abc123');
console.log(asset.name, asset.folderId);

---

client.delete(id)

Elimina un asset permanentemente.

await client.delete('asset_abc123');

---

client.getSignedUrl(id, expiresIn?)

Genera una URL firmada temporal. Por defecto expira en 1 hora (3600s).

const { url, expiresIn } = await client.getSignedUrl('asset_abc123', 7200);
console.log(`URL válida por ${expiresIn}s:`, url);

---

Métodos — Carpetas

client.listFolders(options?)

Lista las carpetas de tu organización. Omitir parentId para obtener las carpetas raíz.

// Carpetas en el nivel raíz
const { folders } = await client.listFolders();

// Subcarpetas de una carpeta
const { folders: sub } = await client.listFolders({ parentId: 'folder_abc123' });

folders.forEach(f => console.log(f.id, f.name));

---

client.createFolder(name, options?)

Crea una carpeta. Pasa parentId para crearla dentro de otra carpeta.

// Carpeta en raíz
const folder = await client.createFolder('Scripts');

// Subcarpeta
const sub = await client.createFolder('v2', { parentId: folder.id });
console.log(sub.id, sub.name);

---

client.deleteFolder(id)

Elimina una carpeta. Sus subcarpetas también se eliminan. Los assets dentro no se borran — su folderId se vuelve null.

await client.deleteFolder('folder_abc123');

---

Tipos TypeScript

type Folder = {
  id: string;
  organizationId: string;
  parentId: string | null;
  name: string;
  createdAt: string;       // ISO 8601
};

type Asset = {
  id: string;
  organizationId: string;
  folderId: string | null; // null = nivel raíz
  key: string;
  name: string;
  mimeType: string | null;
  size: number | null;     // bytes
  publicUrl: string | null;
  createdAt: string;       // ISO 8601
};

type ListAssetsResponse = {
  assets: Asset[];
  total: number;
  limit: number;
  offset: number;
};

type ListFoldersResponse = {
  folders: Folder[];
};

type GetAssetUrlResponse = {
  url: string;
  expiresIn: number;
  asset: {
    id: string;
    name: string;
    mimeType: string | null;
    size: number | null;
  };
};

---

Manejo de errores

Todos los métodos lanzan un Error con el mensaje devuelto por la API cuando la petición falla.

try {
  await client.deleteFolder('id_inexistente');
} catch (err) {
  if (err instanceof Error) {
    console.error(err.message); // "Folder not found"
  }
}

---

Ejemplo completo — sincronizar directorio en una carpeta

import { FiveHubClient } from 'fivehub.pro';
import { readdirSync, readFileSync } from 'fs';
import { join, extname } from 'path';

const client = new FiveHubClient({ apiKey: process.env.FIVEHUB_API_KEY! });

const MIME: Record<string, string> = {
  '.png': 'image/png',
  '.jpg': 'image/jpeg',
  '.zip': 'application/zip',
};

async function syncToFolder(dir: string, folderName: string) {
  // Crear o reutilizar la carpeta destino
  const { folders } = await client.listFolders();
  let folder = folders.find(f => f.name === folderName);
  if (!folder) {
    folder = await client.createFolder(folderName);
  }

  const files = readdirSync(dir);
  for (const file of files) {
    const ext = extname(file);
    const type = MIME[ext] ?? 'application/octet-stream';
    const buffer = readFileSync(join(dir, file));
    const blob = new Blob([buffer], { type });

    const asset = await client.upload(blob, file, folder.id);
    console.log(`✓ ${file} → ${asset.publicUrl}`);
  }
}

syncToFolder('./recursos', 'Temporada-2');