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 SDKTypeScriptREST 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:

# Visita el sitio de registro
https://nexabase.online/register
Crear Cuenta Ahora →
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 con npm o yarn:

# Con npm
npm install @nexabase/sdk
# Con yarn
yarn add @nexabase/sdk

Versión actual: El SDK incluye soporte completo para TypeScript y autocompletado en tu IDE.

🚀 Quick Start

Inicialización Básica

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

{`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 nexabase = createNexaBaseClient({
  baseURL: 'https://mi-empresa.nexabase.app',
  token: 'bearer-token-del-usuario'
});

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

Cliente Autenticado (Login Automático)

Si prefieres autenticarte automáticamente con email/password: 

{`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());`}

📚 Collections API

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

Listar Collections 

{`const response = await nexabase.listCollections({
  page: 1,
  per_page: 25,
  search: 'users',
  sort: '-created_at',
  fields: 'id,name,record_count,created_at'
});

console.log(response.data);  // Array de collections
console.log(response.meta);  // Metadata de paginación
console.log(response.links); // Links de navegación`}

Obtener Detalles de una Collection 

{`const { data: collection } = await nexabase.getCollection('users');

console.log(collection.name);
console.log(collection.record_count);
console.log(collection.schema);`}

Obtener Schema de una Collection 

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

console.log(schema.fields);  // Campos disponibles
console.log(schema.schema);  // Schema completo`}

📝 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: 

{`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`}
POST

Crear Documento

Crea un nuevo documento en una collection: 

{`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);`}
GET

Obtener Documento

Obtiene un documento específico por su ID: 

{`const { data: user } = await nexabase.getDocument('users', 'user-id', {
  fields: 'id,name,email,profile',
  include: 'posts'
});

console.log(user);`}
PATCH

Actualizar Documento (Parcial)

Actualiza solo los campos especificados, manteniendo el resto: 

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

console.log(updated);`}
PUT

Reemplazar Documento (Completo)

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

{`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
});`}
DELETE

Eliminar Documento

Elimina permanentemente un documento: 

{`const result = await nexabase.deleteDocument('users', 'user-id');
console.log(result.message); // "Document deleted successfully"`}

🔐 Authentication API

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

{`// 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();`}

🏢 Tenant & Plans API

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

{`// 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'
});`}

🎯 Factory Functions

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

{`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'
);`}

📡 Event Handling

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

{`// 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);
});`}

🚨 Manejo de Errores

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

{`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);
  }
}`}

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: 

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
}

🔧 Queries Avanzadas

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

Filtrado Complejo 

{`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'
});`}

Paginación 

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

console.log(firstPage.links.next); // URL para la siguiente página`}

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: 

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);

✨ 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