NexaBase
DOCUMENTACIÓN

Documentación de NexaBase

Guías completas del SDK oficial, APIs y configuración para aprovechar al máximo tu backend.

JavaScript SDKTypeScript.NET SDKREST APIReal-time

Navegación

🚀 Quick Start

📋 API Reference

🔧 Avanzado

⚙️ Configuración Inicial

Antes de usar el SDK de NexaBase, necesitas completar estos 3 pasos:

1

Crear Cuenta

Regístrate en NexaBase para comenzar:

setup.sh
bash
# Visita el sitio para ver los planes
https://nexabase.online/#pricing
UTF-8
JavaScript
Ver Planes y Empezar →
2

Crear Primera Organización (Tenant)

Cada organización es un tenant aislado con su propia base de datos PostgreSQL.

  1. Inicia sesión en tu cuenta
  2. Haz clic en "Nueva Organización"
  3. Elige un nombre y subdominio único (ej: mi-empresa)
  4. Tu organización estará en: https://mi-empresa.nexabase.app
3

Generar API Key

Necesitas una API Key para autenticar tus peticiones al SDK:

  1. Ve al Dashboard de tu organización
  2. Navega a "Settings" → "API Keys"
  3. Haz clic en "Generate New API Key"
  4. Copia y guarda la key de forma segura

Importante: Seguridad de API Keys

No compartas tu API Key públicamente. Guárdala en variables de entorno (.env) y nunca la incluyas en tu código fuente.

📦 Instalación del SDK

Instala el SDK oficial de NexaBase para JavaScript/TypeScript o .NET:

JavaScript / TypeScript

terminal
npm
# Con npm
npm install @nexabase/sdk
                      
# Con yarn
yarn add @nexabase/sdk
UTF-8
JavaScript

.NET (C#)

terminal
bash
# Via dotnet CLI
dotnet add package NexaBase.SDK

# NuGet
https://www.nuget.org/packages/NexaBase.SDK
UTF-8
JavaScript

SDKs oficiales: Soporte completo para TypeScript y .NET con autocompletado en tu IDE.

🚀 Quick Start

Inicialización Básica

Existen varias formas de inicializar el cliente según tu caso de uso:

init.js
javascript
import { createNexaBaseClient } from '@nexabase/sdk';

// 1. Con API Key (recomendado para servidor/backend)
const nexabase = createNexaBaseClient({
  baseURL: 'https://mi-empresa.nexabase.app',
  apiKey: 'tu-api-key'
});

// 2. Con Bearer Token (para frontend con usuario autenticado)
const nexabase2 = createNexaBaseClient({
  baseURL: 'https://mi-empresa.nexabase.app',
  token: 'bearer-token-del-usuario'
});

// 3. Con Dual Auth (API Key + Token para máxima seguridad)
const nexabase3 = createNexaBaseClient({
  baseURL: 'https://mi-empresa.nexabase.app',
  apiKey: 'tu-api-key',
  token: 'bearer-token-del-usuario'
});
UTF-8
JavaScript

Cliente Autenticado (Login Automático)

Si prefieres autenticarte automáticamente con email/password:

auth.js
javascript
import { createAuthenticatedApiClient } from '@nexabase/sdk';

const nexabase = await createAuthenticatedApiClient(
  'https://mi-empresa.nexabase.app',
  'tu-api-key',
  'usuario@example.com',
  'tu-password'
);

// El cliente ya está autenticado y listo para usar
console.log(nexabase.getTokenInfo());
console.log(nexabase.getOrganization());
UTF-8
JavaScript

📚 Collections API

Las Collections son equivalentes a tablas en PostgreSQL. El SDK te permite listarlas, obtener detalles y schemas.

Listar Collections

list.js
javascript
const { data, meta } = await nexabase.collection('articulos').list({
  page: 1,
  limit: 10,
  sort: '-created_at'
});
UTF-8
JavaScript

Obtener Detalles de una Collection

collection-details.js
javascript
const { data: collection } = await nexabase.getCollection('users');

console.log(collection.name);
console.log(collection.record_count);
console.log(collection.schema);
UTF-8
JavaScript

Obtener Schema de una Collection

schema.js
javascript
const { data: schema } = await nexabase.getCollectionSchema('users');

console.log(schema.fields);  // Campos disponibles
console.log(schema.schema);  // Schema completo
UTF-8
JavaScript

📝 Documents API (CRUD)

Los documentos son los registros dentro de una Collection. El SDK proporciona métodos completos para CRUD operations.

GET

Listar Documentos

Lista documentos con soporte para paginación, filtrado, búsqueda y ordenamiento:

documents.js
javascript
const response = await nexabase.listDocuments('users', {
  page: 1,
  per_page: 10,
  search: 'john',
  sort: '-created_at',
  fields: 'id,name,email,created_at',
  filter: {
    status: 'active',
    role: 'user'
  },
  include: 'profile,posts'
});

console.log(response.data);       // Array de documentos
console.log(response.meta.total); // Total de registros
UTF-8
JavaScript
POST

Crear Documento

Crea un nuevo documento en una collection:

create.js
javascript
const { data: newUser } = await nexabase.createDocument('users', {
  name: 'John Doe',
  email: 'john@example.com',
  status: 'active',
  profile: {
    bio: 'Software developer',
    location: 'New York'
  }
});

console.log(newUser.id);
console.log(newUser.created_at);
UTF-8
JavaScript
GET

Obtener Documento

Obtiene un documento específico por su ID:

crud.js
javascript
// Crear
const nuevo = await nexabase.collection('usuarios').create({ nombre: 'Juan' });

// Actualizar (Patch)
await nexabase.collection('usuarios').update('uuid', { nombre: 'Juan Modificado' });

// Eliminar
await nexabase.collection('usuarios').delete('uuid');
UTF-8
JavaScript
PATCH

Actualizar Documento (Parcial)

Actualiza solo los campos especificados, manteniendo el resto:

update.js
javascript
const { data: updated } = await nexabase.updateDocument('users', 'user-id', {
  status: 'inactive',
  last_login: new Date().toISOString()
});

console.log(updated);
UTF-8
JavaScript
PUT

Reemplazar Documento (Completo)

Cuidado: PUT reemplaza el documento completo. Los campos no incluidos serán eliminados.

replace.js
javascript
const { data: replaced } = await nexabase.replaceDocument('users', 'user-id', {
  name: 'Jane Doe',
  email: 'jane@example.com',
  status: 'active'
  // Todos los demás campos serán eliminados
});
UTF-8
JavaScript
DELETE

Eliminar Documento

Elimina permanentemente un documento:

item.js
javascript
const item = await nexabase.collection('articulos').get('item-uuid-123');
UTF-8
JavaScript

🔐 Authentication API

Maneja autenticación de usuarios con sign in, sign up y gestión de sesiones:

auth.js
javascript
// Sign in
const { access_token, user } = await nexabase.signIn(
  'user@example.com',
  'password'
);

// Sign up
const auth = await nexabase.signUp(
  'user@example.com',
  'password',
  {
    name: 'John Doe',
    profile: { role: 'user' }
  }
);

// Get current user
const currentUser = await nexabase.getCurrentUser();

// Sign out
await nexabase.signOut();
UTF-8
JavaScript

🏢 Tenant & Plans API

Gestiona información del tenant, estadísticas de uso y planes:

usage.js
javascript
// Obtener información del tenant
const tenantInfo = await nexabase.getTenantInfo();

// Obtener estadísticas de uso
const usage = await nexabase.getUsageStats();
console.log(usage.current_usage.database_rows_count);
console.log(usage.usage_percentages.database_rows);

// Obtener planes disponibles
const plans = await nexabase.getAvailablePlans();

// Actualizar plan
await nexabase.upgradePlan('pro-plan-id', {
  billing_cycle: 'yearly',
  payment_method_id: 'pm_123456'
});
UTF-8
JavaScript

🎯 Factory Functions

El SDK incluye varias funciones helper para crear clientes de manera más conveniente:

factory.js
javascript
import {
  createTenantClient,
  createApiKeyClient,
  createSubdomainClient,
  createDualAuthClient
} from '@nexabase/sdk';

// Cliente específico de tenant
const tenantClient = createTenantClient(
  'https://api.nexabase.app',
  'tenant-id',
  'api-key'
);

// Cliente por subdominio (más simple)
const subdomainClient = createSubdomainClient(
  'mi-empresa',        // subdominio
  'api-key',
  'nexabase.app'       // dominio base
);

// Cliente con autenticación dual (recomendado para API de desarrollador)
const dualClient = createDualAuthClient(
  'https://api.nexabase.app',
  'api-key',
  'bearer-token'
);
UTF-8
JavaScript

📡 Event Handling

El SDK emite eventos para cambios en documentos y errores. Úsalos para reaccionar a cambios en tiempo real:

events.js
javascript
// Escuchar eventos de documentos
nexabase.on('document:created', (data) => {
  console.log(`Nuevo documento creado en ${data.collection}:`, data.document);
});

nexabase.on('document:updated', (data) => {
  console.log(`Documento actualizado en ${data.collection}:`, data.document);
});

nexabase.on('document:deleted', (data) => {
  console.log(`Documento ${data.id} eliminado de ${data.collection}`);
});

nexabase.on('error', (error) => {
  console.error('SDK Error:', error.code, error.message);
});
UTF-8
JavaScript

🚨 Manejo de Errores

El SDK proporciona códigos de error específicos para facilitar el manejo de errores:

errors.js
javascript
import { NexaBaseErrorCodes } from '@nexabase/sdk';

try {
  const document = await nexabase.getDocument('users', 'invalid-id');
} catch (error) {
  switch (error.code) {
    case NexaBaseErrorCodes.DOCUMENT_NOT_FOUND:
      console.log('Documento no encontrado');
      break;
    case NexaBaseErrorCodes.UNAUTHORIZED:
      console.log('Credenciales inválidas');
      break;
    case NexaBaseErrorCodes.PLAN_LIMIT_REACHED:
      console.log('Límite del plan alcanzado:', error.details);
      break;
    default:
      console.error('Error inesperado:', error.message);
  }
}
UTF-8
JavaScript

Códigos de Error Comunes

  • DOCUMENT_NOT_FOUND - El documento no existe
  • UNAUTHORIZED - Credenciales inválidas
  • FORBIDDEN - Sin permisos
  • PLAN_LIMIT_REACHED - Límite del plan alcanzado
  • VALIDATION_ERROR - Datos inválidos

📋 Formato de Respuestas

Todos los métodos del API retornan respuestas estandarizadas con la siguiente estructura:

response.ts
typescript
interface StandardResponse<T> {
  data: T;                    // Los datos solicitados
  meta: {                     // Metadata de paginación
    total: number;
    page: number;
    per_page: number;
    total_pages: number;
  };
  links: {                    // Links de navegación
    self: string;
    next?: string;
    prev?: string;
    first: string;
    last: string;
  };
  timestamp: string;          // Timestamp de la respuesta
}
UTF-8
JavaScript

🔧 Queries Avanzadas

Utiliza opciones avanzadas de filtrado, ordenamiento y paginación para queries complejas:

Filtrado Complejo

advanced-filter.js
javascript
const users = await nexabase.listDocuments('users', {
  filter: {
    status: 'active',
    'profile.role': 'admin',
    'created_at': { '$gte': '2024-01-01' }
  },
  sort: '-created_at,name',
  fields: 'id,name,email,profile.role',
  include: 'profile,permissions',
  search: 'john'
});
UTF-8
JavaScript

Paginación

pagination.js
javascript
const firstPage = await nexabase.listDocuments('posts', {
  page: 1,
  per_page: 20
});

console.log(firstPage.links.next); // URL para la siguiente página
UTF-8
JavaScript

Operadores de Filtrado

  • $eq - Igual a (por defecto)
  • $ne - No igual a
  • $gt - Mayor que
  • $gte - Mayor o igual que
  • $lt - Menor que
  • $lte - Menor o igual que
  • $in - Está en array
  • $nin - No está en array

📚 Soporte TypeScript

El SDK está completamente tipado y ofrece autocompletado completo en TypeScript:

types.ts
typescript
import { 
  NexaBase, 
  Document, 
  Collection, 
  StandardResponse,
  DocumentQueryOptions 
} from '@nexabase/sdk';

const nexabase: NexaBase = createNexaBaseClient(config);

const options: DocumentQueryOptions = {
  page: 1,
  per_page: 10,
  fields: 'id,name,email'
};

const response: StandardResponse<Document[]> = 
  await nexabase.listDocuments('users', options);
UTF-8
JavaScript

✨ Beneficios de TypeScript

  • • Autocompletado en tu IDE favorito
  • • Detección de errores en tiempo de desarrollo
  • • Documentación inline de todos los métodos
  • • Type safety en todas las operaciones
  • • Intellisense para parámetros y respuestas

¿Necesitas Ayuda Específica?

Nuestro equipo de desarrollo está disponible para resolver dudas y ayudarte con implementaciones específicas.

💬 Contactar Soporte 📝 Sugerir Contenido