nexabase_flutter_sdk 1.0.3

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

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