nexabase_flutter_sdk 1.0.5

SDK oficial de Flutter para Nexabase - Base de datos en tiempo real para aplicaciones Flutter

Nexabase Flutter SDK

SDK oficial de Flutter para Nexabase - La plataforma de base de datos en tiempo real para aplicaciones modernas.

✨ Características

• 🔐 Autenticación completa - Registro, login, gestión de sesiones con JWT
• 📊 Operaciones de base de datos - CRUD completo en colecciones con filtros avanzados
• 🔄 Tiempo real - WebSocket con suscripciones a cambios y reconexión automática
• 📁 Almacenamiento de archivos - Upload, download con límites de plan integrados
• 🏢 Multi-tenancy - Soporte completo para múltiples inquilinos
• 📈 Límites de plan - Control automático de recursos según el plan actual
• 🛡️ Manejo robusto de errores - Excepciones específicas con información detallada
• 🔁 Reintentos automáticos - Con backoff exponencial
• 💾 Cache inteligente - Reduce llamadas innecesarias a la API
• 📱 Multiplataforma - iOS, Android, Web, Desktop

🚀 Instalación

Añade el SDK a tu proyecto Flutter:

dependencies:
  nexabase_flutter_sdk: ^1.0.0

Luego ejecuta:

flutter pub get

⚡ Inicio Rápido

1. Inicialización

import 'package:nexabase_flutter_sdk/nexabase_flutter_sdk.dart';

// Inicializar el cliente (una vez en tu app)
await NexabaseClient.instance.initialize(
  AuthConfig(
    baseUrl: 'https://tu-proyecto.nexabase.com',
    apiKey: 'tu-api-key',
    enableDebugLogs: true, // Solo en desarrollo
  ),
);

2. Autenticación

// Registrar nuevo usuario
final user = await NexabaseClient.instance.auth.register(
  email: '[e-mail]',
  password: 'contraseña123',
  firstName: 'Juan',
  lastName: 'Pérez',
);

// Iniciar sesión
final user = await NexabaseClient.instance.auth.login(
  email: '[e-mail]',
  password: 'contraseña123',
);

// Obtener usuario actual
final currentUser = await NexabaseClient.instance.auth.getCurrentUser();

// Escuchar cambios de autenticación
NexabaseClient.instance.auth.authStateChanges.listen((state) {
  if (state.isAuthenticated) {
    print('Usuario conectado: ${state.user?.email}');
  } else {
    print('Usuario desconectado');
  }
});

3. Operaciones de Base de Datos (Colecciones)

// Crear registro en colección
final nuevoRegistro = await NexabaseClient.instance.database.createRecord(
  'usuarios',
  {
    'nombre': 'Ana García',
    'email': '[e-mail]',
    'activo': true,
    'rol': 'user',
  },
);

// Obtener registros con filtros avanzados
final respuesta = await NexabaseClient.instance.database.getRecordsAdvanced(
  'usuarios',
  page: 1,
  limit: 20,
  search: 'ana',
  filters: [
    CollectionFilter(
      field: 'activo',
      operator: FilterOperator.equals,
      value: true,
    ),
    CollectionFilter(
      field: 'rol',
      operator: FilterOperator.isIn,
      value: ['user', 'admin'],
    ),
  ],
  sort: [
    CollectionSort(
      field: 'created_at',
      direction: SortDirection.desc,
    ),
  ],
);

// Actualizar registro
final actualizado = await NexabaseClient.instance.database.updateRecord(
  'usuarios',
  'id-del-registro',
  {'nombre': 'Ana García Actualizada'},
);

// Eliminar registro
await NexabaseClient.instance.database.deleteRecord('usuarios', 'id-del-registro');

// Contar registros con filtros
final count = await NexabaseClient.instance.database.countRecords(
  'usuarios',
  filters: [
    CollectionFilter(
      field: 'activo',
      operator: FilterOperator.equals,
      value: true,
    ),
  ],
);

4. Tiempo Real

// Habilitar tiempo real para una colección
await NexabaseClient.instance.realtime.enableRealtimeForCollection('usuarios');

// Conectar al servicio de tiempo real
await NexabaseClient.instance.realtime.connect();

// Suscribirse a cambios en una colección
NexabaseClient.instance.realtime.subscribe('usuarios').listen((evento) {
  switch (evento.type) {
    case RealtimeEventType.created:
      print('Nuevo usuario: ${evento.record?.id}');
      break;
    case RealtimeEventType.updated:
      print('Usuario actualizado: ${evento.record?.id}');
      break;
    case RealtimeEventType.deleted:
      print('Usuario eliminado');
      break;
  }
});

// Monitorear estado de conexión
NexabaseClient.instance.realtime.connectionState.listen((estado) {
  print('Estado de tiempo real: $estado');
});

// Obtener estadísticas de tiempo real
final stats = await NexabaseClient.instance.realtime.getStats();
print('Conexiones activas: ${stats.totalConnections}');

// Obtener uso de tiempo real del tenant
final usage = await NexabaseClient.instance.realtime.getTenantUsage();
print('Conexiones usadas: ${usage.currentConnections}/${usage.limits.maxConnections}');

5. Almacenamiento de Archivos

// Subir archivo desde bytes
final archivo = await NexabaseClient.instance.storage.uploadBytes(
  bytes: archivoBytes,
  fileName: 'imagen.jpg',
  mimeType: 'image/jpeg',
  folder: 'fotos-perfil',
  collection: 'usuarios',
  recordId: 'user-123',
  field: 'avatar',
);

// Descargar archivo
final datos = await NexabaseClient.instance.storage.downloadFile(archivo.id);

// Obtener información de archivo
final fileInfo = await NexabaseClient.instance.storage.getFileInfo(archivo.id);

// Listar archivos (requiere permisos admin/developer)
final archivos = await NexabaseClient.instance.storage.listFiles();

// Obtener estadísticas de almacenamiento
final stats = await NexabaseClient.instance.storage.getStats();
print('Archivos totales: ${stats.totalFiles}');
print('Espacio usado: ${stats.planLimits?.currentUsageGb}GB/${stats.planLimits?.limitGb}GB');

// Obtener uso de almacenamiento del tenant
final usage = await NexabaseClient.instance.storage.getTenantUsage();
print('Storage: ${usage.storage.usedGb}GB/${usage.storage.limitGb}GB');
print('Bandwidth: ${usage.bandwidth.usedGb}GB/${usage.bandwidth.limitGb}GB');

🔧 Configuración Avanzada

Manejo de Errores

try {
  final registro = await NexabaseClient.instance.database.getRecord('usuarios', 'id');
} on PlanLimitException catch (e) {
  print('Límite de plan alcanzado: ${e.resource}');
  print('Uso actual: ${e.currentUsage}/${e.limit}');
  print('Plan: ${e.planName}');
} on NotFoundException {
  print('Registro no encontrado');
} on NetworkException catch (e) {
  print('Error de red: ${e.message} (Código: ${e.statusCode})');
} on NexabaseException catch (e) {
  print('Error de Nexabase: ${e.message}');
}

Filtros Avanzados

// Múltiples filtros con diferentes operadores
final filtros = [
  CollectionFilter(
    field: 'edad',
    operator: FilterOperator.greaterThanOrEqual,
    value: 18,
  ),
  CollectionFilter(
    field: 'estado',
    operator: FilterOperator.isIn,
    value: ['activo', 'verificado'],
  ),
  CollectionFilter(
    field: 'email',
    operator: FilterOperator.contains,
    value: '@empresa.com',
  ),
  CollectionFilter(
    field: 'fecha_registro',
    operator: FilterOperator.greaterThan,
    value: '2024-01-01',
  ),
];

final usuarios = await NexabaseClient.instance.database.getRecordsAdvanced(
  'usuarios',
  filters: filtros,
  sort: [
    CollectionSort(field: 'fecha_registro', direction: SortDirection.desc),
    CollectionSort(field: 'nombre', direction: SortDirection.asc),
  ],
);

Configuración de Interceptores

// El SDK incluye interceptores automáticos para: // - Logging de peticiones (solo en debug) // - Reintentos automáticos // - Manejo de errores específicos de Nexabase // - Cache inteligente // - Autenticación automática con refresh de tokens

📖 API Reference

Operadores de Filtro Disponibles

• FilterOperator.equals - Igual a
• FilterOperator.notEquals - Diferente de
• FilterOperator.greaterThan - Mayor que
• FilterOperator.greaterThanOrEqual - Mayor o igual que
• FilterOperator.lessThan - Menor que
• FilterOperator.lessThanOrEqual - Menor o igual que
• FilterOperator.contains - Contiene texto
• FilterOperator.startsWith - Comienza con
• FilterOperator.endsWith - Termina con
• FilterOperator.isIn - Está en lista
• FilterOperator.isNotIn - No está en lista
• FilterOperator.isNull - Es nulo
• FilterOperator.isNotNull - No es nulo

Roles de Usuario

• UserRole.ADMIN - Administrador completo
• UserRole.DEVELOPER - Desarrollador con acceso técnico
• UserRole.USER - Usuario estándar

🧪 Testing

Ejecuta las pruebas del SDK:

cd nexabase_flutter_sdk flutter test

📱 Ejemplo Completo

Revisa la aplicación de ejemplo en la carpeta example/ para ver una implementación completa con:

• Inicialización del SDK
• Autenticación de usuarios
• Operaciones CRUD en colecciones
• Filtros y búsquedas avanzadas
• Suscripciones en tiempo real
• Upload y gestión de archivos
• Manejo de límites de plan
• UI responsiva

cd example flutter run

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -am 'Añadir nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Crea un Pull Request

📋 Requisitos

• Flutter >=3.10.0
• Dart >=3.0.0
• Nexabase API Key (obtén una en nexabase.com)

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para detalles.

🆘 Soporte

• 📚 Documentación oficial
• 💬 Discord de la comunidad
• 🐛 Reportar issues
• 📧 Contacto directo

---

Desarrollado con ❤️ por el equipo de Nexabase