@nuvemlatam/js

SDK oficial de Nuvem para JavaScript y TypeScript. Isomórfico: funciona en browser, Node.js 18+ y Cloudflare Workers.

Instalacion

npm install @nuvemlatam/js
# o
pnpm add @nuvemlatam/js
# o
yarn add @nuvemlatam/js

Inicio rapido

import { createClient } from '@nuvemlatam/js';

const nuvem = createClient({
  apiKey: 'nv_live_xxxxxxxxxxxxxxxx',
  // baseUrl opcional — por defecto 'https://api.nuvem-latam.com'
  // timeoutMs opcional — por defecto 30000
});

Base de datos (nuvem.db)

Tablas

// Crear tabla
const tabla = await nuvem.db.tables.create('productos', [
  { name: 'nombre', type: 'TEXT', nullable: false },
  { name: 'precio', type: 'REAL', nullable: false },
  { name: 'stock', type: 'INTEGER', nullable: true, default: '0' },
]);

// Listar tablas
const tablas = await nuvem.db.tables.list();

// Obtener tabla
const productos = await nuvem.db.tables.get('productos');

// Eliminar tabla
await nuvem.db.tables.drop('productos');

Registros

// Insertar registro
const producto = await nuvem.db.insert('productos', {
  nombre: 'Laptop',
  precio: 999.99,
  stock: 5,
});

// Listar registros con paginacion
const { records, total } = await nuvem.db.list('productos', {
  limit: 20,
  offset: 0,
});

// Obtener registro por ID
const item = await nuvem.db.get('productos', 'rec_abc123');

// Actualizar registro
const actualizado = await nuvem.db.update('productos', 'rec_abc123', {
  stock: 4,
});

// Eliminar registro
await nuvem.db.delete('productos', 'rec_abc123');

Autenticacion de usuarios (nuvem.auth)

// Registro
const { accessToken, refreshToken, user } = await nuvem.auth.signup({
  email: '[email protected]',
  password: 'mi-contrasena-segura',
  name: 'Juan Perez', // opcional
});

// Login
const tokens = await nuvem.auth.login({
  email: '[email protected]',
  password: 'mi-contrasena-segura',
});

// Renovar access token
const nuevoTokens = await nuvem.auth.refresh(tokens.refreshToken);

// Cerrar sesion
await nuvem.auth.logout(tokens.refreshToken);

// Obtener usuario autenticado (requiere JWT, no API key)
const usuario = await nuvem.auth.me(tokens.accessToken);

Almacenamiento (nuvem.storage)

// Subir archivo
const archivo = await nuvem.storage.upload(file, {
  name: 'mi-imagen.png', // opcional — usa el nombre original si se omite
  public: true,          // opcional — false por defecto
});

// Listar archivos
const { records } = await nuvem.storage.list({ limit: 10, offset: 0 });

// Descargar archivo (retorna Blob)
const blob = await nuvem.storage.download('file_abc123');

// Obtener metadatos
const meta = await nuvem.storage.meta('file_abc123');

// Actualizar visibilidad
const actualizado = await nuvem.storage.update('file_abc123', {
  public: false,
});

// Eliminar archivo
await nuvem.storage.delete('file_abc123');

Funciones edge (nuvem.functions)

// Crear funcion
const fn = await nuvem.functions.create({
  name: 'saludar',
  code: `export default async (input) => ({ mensaje: 'Hola, ' + input.nombre })`,
  envVars: { MI_VAR: 'valor' }, // opcional
});

// Listar funciones
const { records } = await nuvem.functions.list({ limit: 20 });

// Obtener funcion
const detalle = await nuvem.functions.get('fn_abc123');

// Actualizar funcion
const actualizada = await nuvem.functions.update('fn_abc123', {
  code: `export default async (input) => ({ resultado: input.x * 2 })`,
});

// Invocar funcion
const resultado = await nuvem.functions.invoke('fn_abc123', { nombre: 'Mundo' });
console.log(resultado.output); // { mensaje: 'Hola, Mundo' }
console.log(resultado.durationMs); // tiempo de ejecucion en ms

// Obtener logs
const logs = await nuvem.functions.logs('fn_abc123', { limit: 50 });

// Eliminar funcion
await nuvem.functions.delete('fn_abc123');

Manejo de errores

Todos los metodos del SDK lanzan NuvemError cuando la API responde con un error.

import { NuvemError } from '@nuvemlatam/js';

try {
  const tabla = await nuvem.db.tables.get('no-existe');
} catch (err) {
  if (err instanceof NuvemError) {
    console.log(err.status);    // ej: 404
    console.log(err.code);      // ej: 'TABLE_NOT_FOUND'
    console.log(err.messageEs); // mensaje en espanol
    console.log(err.messagePt); // mensagem em portugues
    console.log(err.isNetwork); // true si fue error de red/timeout
  }
}

Tipos TypeScript

El SDK exporta todos los tipos de @nuvemlatam/shared para que no tengas que agregarlo como dependencia separada:

import type {
  ProjectDTO,
  ApiKeyDTO,
  TableDTO,
  ColumnInput,
  UserDTO,
  AuthTokensDTO,
  FileDTO,
  EdgeFunctionDTO,
  FunctionInvokeResult,
} from '@nuvemlatam/js';

Documentacion completa

Visita docs.nuvem-latam.com para la referencia completa de la API.