traderpal_connect 1.0.0-beta.4
traderpal_connect: ^1.0.0-beta.4 copied to clipboard
[BETA] TraderPal Connect SDK for Flutter - A comprehensive SDK for integrating TraderPal services into Flutter applications with JWT authentication and subscription management. This is a beta version [...]
TraderPal Connect #
TraderPal Connect es un SDK completo de Flutter para integrar servicios de TraderPal en aplicaciones Flutter. Proporciona una interfaz de usuario completa y moderna para aplicaciones de trading e inversión, con autenticación JWT, gestión de suscripciones, y una arquitectura escalable basada en Clean Architecture.
📋 Información del Proyecto #
- Versión: 1.0.0-beta.4
- Flutter: >=3.24.0 (compatible con 3.27.1 y 3.35+)
- Dart SDK: >=3.4.0 <4.0.0
- Licencia: Ver LICENSE
- Estado: Beta - Versión de prueba temprana
✅ Versiones Probadas y Certificadas #
- ✅ Flutter 3.27.1 (Dart 3.6.0) - Versión de referencia actual
- ✅ Flutter 3.35+ (Dart 3.6.x+) - Compatible y probado
📱 Requisitos de Plataforma #
- iOS: 15.5+ (compatible con iOS 12+)
- Android: minSdkVersion 24 (API 24+)
- Gradle: 8.6.1 - 8.11.1
- Kotlin: 2.1.0
🆕 Novedades en la Versión 1.0.0-beta.4 #
✨ Nuevas Características #
- 🔧 Soporte para Entornos Sandbox y Producción: Nuevo parámetro
useSandboxenTraderPalSDK.initialize()para cambiar dinámicamente entre entornos - 🌐 Gestión Dinámica de URLs: Configuración flexible de URLs de API mediante variables de entorno (
API_URLyAPI_URL_DEBUG) - 🔄 Reinicialización Automática: El cliente API se reinicializa automáticamente cuando cambia la URL base
🐛 Correcciones #
- ✅ Corregido el problema donde el SDK no respetaba correctamente el parámetro
useSandbox - ✅ Asegurado que el cliente API siempre use la URL correcta antes de cada petición HTTP
- 🧹 Eliminados logs excesivos de depuración para un código más limpio
📝 Mejoras #
- 📚 Documentación actualizada con información sobre el parámetro
useSandbox - 🔧 Mejorada la gestión de configuración de entorno
✨ Características Principales #
🔐 Autenticación y Seguridad #
- Autenticación JWT: Validación de tokens JWT con verificación de expiración
- Gestión de Suscripciones: Validación automática del estado de suscripción
- Validación de Cuenta: Verificación del estado de la cuenta del usuario
🎨 Interfaz de Usuario #
- Tema Oscuro/Claro: Soporte completo para ambos modos de visualización
- Diseño Responsive: Optimizado para diferentes tamaños de pantalla
- Componentes Reutilizables: Widgets pre-construidos para funcionalidades comunes
- Animaciones Fluidas: Integración con
flutter_animatepara transiciones suaves
📊 Funcionalidades de Trading #
- Portfolio: Visualización y gestión de portafolios
- Búsqueda de Activos: Búsqueda avanzada de acciones y activos
- Órdenes: Gestión completa de órdenes de compra y venta
- Actividad Financiera: Historial detallado de transacciones
- Favoritos: Gestión de activos favoritos
- Gráficos: Visualización de datos con
syncfusion_flutter_charts
💰 Gestión Financiera #
- Depósitos: Múltiples métodos de pago (tarjeta, transferencia bancaria, QR)
- Retiros: Procesamiento de retiros
- Funding: Gestión de fondos y operaciones financieras
- Reportes: Estados de cuenta mensuales y confirmaciones de operaciones
- Documentos: Gestión de documentos y formularios (W8-BEN)
🏗️ Arquitectura #
- Clean Architecture: Estructura organizada por capas
- State Management: Riverpod para gestión de estado reactiva
- API Service: Cliente HTTP robusto con manejo de errores normalizado
- Providers: Providers especializados (Auth, User, Market, Navigation)
- Configuración: Sistema flexible de variables de entorno
🚀 Inicio Rápido #
Prerequisitos #
- Flutter SDK >=3.24.0 (recomendado: 3.27.1)
- Dart SDK >=3.4.0 <4.0.0
- Cuenta de TraderPal con token JWT válido
- Archivo
.envconfigurado con las URLs de API (ver sección de configuración)
Instalación #
Agrega traderpal_connect a tu pubspec.yaml:
dependencies:
traderpal_connect: ^1.0.0-beta.4
Luego ejecuta:
flutter pub get
Configuración Inicial #
- Configurar variables de entorno (requerido):
Crea un archivo .env en la raíz de tu proyecto con las siguientes variables:
# URL de producción (usada cuando useSandbox=false)
API_URL=https://your-production-api-url.com/v1/
# URL de sandbox (usada cuando useSandbox=true)
API_URL_DEBUG=https://your-sandbox-api-url.com/v1/
# Configuración opcional
PACKAGE_VERSION=1.0.0
DEBUG_MODE=true
LOG_LEVEL=info
# Credenciales para autenticación de Partner (requerido para obtener tokens con la clase Connect)
PARTNER_EMAIL=your-partner-email@example.com
PARTNER_PASSWORD=your-partner-password
PARTNER_API_KEY=your-partner-api-key
# MODE solo es necesario si usas la clase Connect del ejemplo (opcional)
# Si usas Connect: MODE=dev usa API_URL_DEBUG, cualquier otro valor usa API_URL
# Si usas TraderPalSDK.initialize() con useSandbox, MODE no es necesario
MODE=dev
# Token para Footprint SDK (requerido para onboarding). No es obligatorio en el demo.
TRADERPAL_FOOTPRINT_TOKEN=your-footprint-token
# User ID de TraderPal (opcional, puede pasarse directamente en el código)
TRADERPAL_USER_ID=your-user-id
Nota:
- El SDK requiere que al menos
API_URLoAPI_URL_DEBUGestén configurados en el archivo.env. - El SDK principal usa el parámetro
useSandboxenTraderPalSDK.initialize()para determinar qué URL usar, NO necesita la variableMODE. - La variable
MODEsolo es necesaria si usas la claseConnectdel ejemplo para obtener tokens automáticamente. - Para obtener tokens de autenticación con la clase
Connect, también necesitas configurar las credenciales de Partner (PARTNER_EMAIL,PARTNER_PASSWORD,PARTNER_API_KEY).
- Inicializar el SDK:
import 'package:flutter/material.dart';
import 'package:traderpal_connect/traderpal_connect.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
// Cargar variables de entorno (opcional)
await dotenv.load(fileName: ".env");
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Mi App',
home: const HomeScreen(),
);
}
}
class HomeScreen extends StatelessWidget {
const HomeScreen({super.key});
@override
Widget build(BuildContext context) {
return Scaffold(
body: Center(
child: ElevatedButton(
onPressed: () async {
// Inicializar y abrir el SDK
await TraderPalSDK.initialize(
token: 'tu-jwt-token-aqui',
userId: 'tu-user-id',
context: context,
mode: 'dark', // o 'light'
useSandbox: false, // true para usar API_URL_DEBUG, false para API_URL
onComplete: () {
print('SDK inicializado correctamente');
},
onCancel: () {
print('Usuario canceló');
},
onError: (error) {
print('Error: $error');
},
);
},
child: const Text('Abrir TraderPal Connect'),
),
),
);
}
}
📦 Dependencias Principales #
Dependencias Core #
- dio: ^5.4.0 - Cliente HTTP para llamadas API
- flutter_riverpod: ^2.5.1 - Gestión de estado reactiva
- flutter_dotenv: ^5.1.0 - Gestión de variables de entorno
Dependencias UI #
- google_fonts: ^6.2.0 - Fuentes de Google (Inter) - Compatible con Dart 3.6.0
- flutter_svg: ^2.1.0 - Soporte para archivos SVG - Compatible con Dart 3.6.0
- flutter_animate: ^4.5.2 - Animaciones fluidas
- syncfusion_flutter_charts: ^29.1.38 - Gráficos avanzados - Compatible con Dart 3.6.0
- table_calendar: ^3.1.2 - Calendarios interactivos
Dependencias de Funcionalidad #
- url_launcher: ^6.3.0 - Lanzamiento de URLs externas
- webview_flutter: ^4.10.0 - Integración de WebViews
Dependencias de Desarrollo #
- flutter_lints: ^5.0.0 - Reglas de linting
- flutter_test: SDK de testing de Flutter
📁 Estructura del Proyecto #
lib/
├── traderpal_connect.dart # Archivo principal de exportación
└── src/
├── app/
│ ├── traderpal_app.dart # Widget principal de la aplicación
│ ├── layouts/ # Layouts reutilizables
│ └── themes/
│ └── colors.dart # Sistema de colores y temas
├── config/
│ └── env_config.dart # Configuración de entorno
├── models/ # Modelos de datos
│ ├── user_models.dart
│ ├── portfolio_models.dart
│ ├── deposit_models.dart
│ ├── order_models.dart
│ └── ...
├── presentation/
│ ├── pages/ # Páginas de la aplicación
│ │ ├── home/ # Página principal
│ │ ├── search/ # Búsqueda de activos
│ │ ├── account/ # Gestión de cuenta
│ │ ├── portfolio/ # Portafolio
│ │ ├── deposit/ # Depósitos
│ │ ├── withdraw/ # Retiros
│ │ ├── funding/ # Funding
│ │ ├── orders/ # Órdenes
│ │ ├── stocks/ # Detalles de acciones
│ │ ├── buy/ # Compra
│ │ ├── sell/ # Venta
│ │ ├── favorites/ # Favoritos
│ │ ├── financial_activity/ # Actividad financiera
│ │ ├── reports/ # Reportes
│ │ ├── documents/ # Documentos
│ │ ├── menu/ # Menú
│ │ └── welcome/ # Pantalla de bienvenida
│ └── widgets/ # Widgets reutilizables
│ ├── bottom_menu.dart
│ ├── base_amount_page.dart
│ ├── amount_page/
│ └── ...
├── providers/ # Providers de Riverpod
│ ├── auth_provider.dart
│ ├── user_provider.dart
│ ├── market_provider.dart
│ └── navigation_provider.dart
└── services/ # Servicios de negocio
├── api_service.dart
├── subscription_service.dart
└── api/ # Servicios API específicos
├── user_api.dart
├── market_api.dart
├── order_api.dart
├── deposit_api.dart
└── ...
🎨 Sistema de Colores #
El paquete incluye un sistema de colores completo con escalas para diferentes modos:
- Escala Gris: 13 tonos (0-12) para modo claro y oscuro
- Escala Azul: 13 tonos para elementos primarios
- Escala Verde: 13 tonos para elementos de éxito/ganancia
- Escala Amarilla: 13 tonos para advertencias
- Escala Roja: 13 tonos para errores/pérdidas
- Escala Morada: 13 tonos para elementos especiales
- Escala Rosa: 13 tonos para elementos destacados
- Escala Naranja: 13 tonos para elementos de atención
Uso del Sistema de Colores #
import 'package:traderpal_connect/traderpal_connect.dart';
// Modo oscuro (por defecto)
AppColors.setMode(ColorMode.dark);
Color backgroundColor = AppColors.background;
Color primaryColor = AppColors.blue6;
// Modo claro
AppColors.setMode(ColorMode.light);
Color backgroundColor = AppColors.background;
📱 Páginas Disponibles #
Páginas Principales #
- HomePage: Página principal con resumen de cuenta y opciones rápidas
- SearchPage: Búsqueda avanzada de activos financieros
- AccountPage: Gestión completa de la cuenta del usuario
- PortfolioPage: Visualización y gestión de portafolios
- MenuPage: Menú de opciones y configuración
Páginas de Trading #
- StocksPage: Detalles de acciones con gráficos y análisis
- BuyPage: Interfaz de compra de activos
- SellPage: Interfaz de venta de activos
- OrdersPage: Gestión de órdenes pendientes y ejecutadas
Páginas Financieras #
- DepositPage: Depósitos con múltiples métodos de pago
- WithdrawPage: Retiros (InSwitch y Wire Transfer)
- FundingPage: Gestión de fondos
- FinancialActivityPage: Historial de actividad financiera
Páginas Adicionales #
- FavoritesPage: Gestión de activos favoritos
- ReportsPage: Reportes y documentos
- DocumentsPage: Gestión de documentos
- WelcomePage: Pantalla de bienvenida y términos
🔧 Uso Avanzado #
Inicialización del API Service #
import 'package:traderpal_connect/traderpal_connect.dart';
// Inicializar el servicio API
final apiService = ApiService();
await apiService.initialize();
// Validar suscripción
final result = await apiService.validateSubscription('tu-token');
Uso de Providers #
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:traderpal_connect/traderpal_connect.dart';
class MyWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final userStatus = ref.watch(userStatusProvider);
return userStatus.when(
data: (status) => Text('Usuario: ${status.userId}'),
loading: () => CircularProgressIndicator(),
error: (err, stack) => Text('Error: $err'),
);
}
}
Navegación Programática #
import 'package:traderpal_connect/traderpal_connect.dart';
// Navegar a una página específica
GlobalNavigation.navigateToPage(2); // Navega a AccountPage
// Cerrar el SDK
TraderPalSDK.close(context);
Configuración de Entornos (Sandbox vs Producción) #
// Usar entorno de producción (API_URL)
await TraderPalSDK.initialize(
token: 'tu-token',
userId: 'tu-user-id',
context: context,
useSandbox: false, // Usa API_URL del .env
// ... otros parámetros
);
// Usar entorno de sandbox (API_URL_DEBUG)
await TraderPalSDK.initialize(
token: 'tu-token',
userId: 'tu-user-id',
context: context,
useSandbox: true, // Usa API_URL_DEBUG del .env
// ... otros parámetros
);
Importante: Asegúrate de tener ambas URLs configuradas en tu archivo .env:
API_URL: URL de producciónAPI_URL_DEBUG: URL de sandbox/desarrollo
Obtención de Tokens de Autenticación #
El SDK requiere un token JWT válido para funcionar. Hay dos formas principales de obtener este token:
Opción 1: Usando la Clase Connect (Recomendado)
La clase Connect maneja automáticamente el login y la renovación de tokens usando las credenciales de Partner configuradas en el .env:
import 'package:traderpal_connect/traderpal_connect.dart';
// Asumiendo que tienes una clase Connect similar al ejemplo
// Inicializar Connect y obtener el token
final connect = Connect();
await connect.startTokenManager(); // Hace login y configura refresh automático
final token = connect.authToken;
if (token == null || token.isEmpty) {
// Manejar error
return;
}
// Usar el token para inicializar el SDK
await TraderPalSDK.initialize(
token: token,
userId: userId,
context: context,
useSandbox: true,
// ... otros parámetros
);
Configuración requerida en .env:
PARTNER_EMAIL: Email del partnerPARTNER_PASSWORD: Contraseña del partnerPARTNER_API_KEY: API Key del partnerMODE(opcional):devpara usarAPI_URL_DEBUG, cualquier otro valor usaAPI_URL. Solo necesario para la claseConnectdel ejemplo.
Nota: La clase Connect usa MODE para determinar qué URL usar. Si usas TraderPalSDK.initialize() directamente con el parámetro useSandbox, no necesitas MODE.
La clase Connect automáticamente:
- Hace login usando las credenciales de Partner
- Obtiene
authTokenyrefreshToken - Configura un timer para refrescar el token cada 3 horas
- Maneja la renovación automática de tokens
- Usa
MODEdel.envpara determinar qué URL usar (dev=API_URL_DEBUG, otros =API_URL)
Opción 2: Token Manual (Solo para pruebas)
Si ya tienes un token JWT válido (obtenido de otra fuente, hardcodeado para testing, o almacenado en una variable de entorno diferente), puedes usarlo directamente:
Opción 2a: Token desde Variable de Entorno
Agrega una variable de entorno diferente en tu .env:
# Token JWT directo (alternativa a usar credenciales de Partner)
TRADERPAL_TOKEN=tu-jwt-token-aqui
Luego úsalo en tu código:
import 'package:flutter_dotenv/flutter_dotenv.dart';
// Obtener token desde variable de entorno
final token = dotenv.env['TRADERPAL_TOKEN'];
if (token == null || token.isEmpty) {
// Manejar error
return;
}
// Usar el token para inicializar el SDK
await TraderPalSDK.initialize(
token: token,
userId: userId,
context: context,
useSandbox: true,
// ... otros parámetros
);
Opción 2b: Token Hardcodeado (Solo para Desarrollo/Testing)
// Token hardcodeado - SOLO para desarrollo y testing
const String hardcodedToken = 'tu-jwt-token-aqui';
await TraderPalSDK.initialize(
token: hardcodedToken,
userId: userId,
context: context,
useSandbox: true,
// ... otros parámetros
);
⚠️ Advertencia: Los tokens hardcodeados solo deben usarse en desarrollo/testing. Nunca los incluyas en código de producción.
Cuándo usar cada opción:
- Opción 1 (Connect): Cuando necesitas autenticación automática con renovación de tokens
- Opción 2a (Variable de entorno): Cuando obtienes el token de otro sistema o servicio externo
- Opción 2b (Hardcodeado): Solo para desarrollo rápido y testing local
Configuración de Footprint SDK para Onboarding #
Si necesitas integrar el proceso de onboarding con Footprint SDK, necesitas obtener un sessionToken del endpoint de onboarding:
import 'package:dio/dio.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:footprint_sdk/footprint_sdk.dart';
/// Obtiene el session token del endpoint de onboarding para Footprint
Future<String?> fetchOnboardingSessionToken(String userId) async {
try {
final footprintToken = dotenv.env['TRADERPAL_FOOTPRINT_TOKEN'];
if (footprintToken == null || footprintToken.isEmpty) {
throw Exception('TRADERPAL_FOOTPRINT_TOKEN no está configurado');
}
final dio = Dio();
final apiUrl = dotenv.env['API_URL_DEBUG'] ?? dotenv.env['API_URL'];
final url = '${apiUrl}onboarding/$userId/session-token';
final response = await dio.post(
url,
options: Options(
headers: {
'Authorization': 'Bearer $footprintToken',
'Content-Type': 'application/json',
},
),
data: <String, dynamic>{},
);
if (response.statusCode == 200 && response.data != null) {
// El token puede venir en diferentes formatos
if (response.data is String) {
return response.data as String;
} else if (response.data is Map<String, dynamic>) {
final data = response.data as Map<String, dynamic>;
return data['sessionToken'] ??
data['token'] ??
data['onboardingSessionToken'] ??
data['session_token'];
}
}
return null;
} catch (e) {
print('Error obteniendo session token: $e');
return null;
}
}
/// Inicia el proceso de onboarding con Footprint
Future<void> startOnboarding(String userId, BuildContext context) async {
try {
// Obtener el session token
final sessionToken = await fetchOnboardingSessionToken(userId);
if (sessionToken == null || sessionToken.isEmpty) {
throw Exception('No se pudo obtener el session token');
}
// Inicializar Footprint SDK con el token obtenido
await footprint.init(
FootprintConfiguration(
authToken: sessionToken,
redirectUrl: "traderpal.co",
onComplete: (token) {
// Onboarding completado exitosamente
// Aquí puedes usar el token para inicializar TraderPalSDK
print('Onboarding completado. Token: $token');
},
onCancel: () {
// Usuario canceló el flujo
print('Onboarding cancelado por el usuario');
},
),
context,
);
} catch (e) {
print('Error en onboarding: $e');
}
}
Configuración requerida en .env:
TRADERPAL_FOOTPRINT_TOKEN: Token de autenticación para el endpoint de onboardingAPI_URLoAPI_URL_DEBUG: URL base de la API
Nota: El sessionToken obtenido del endpoint de onboarding es específico para Footprint SDK y se usa únicamente para el proceso de onboarding. Una vez completado el onboarding, Footprint retornará un token que puedes usar para inicializar TraderPalSDK.
📝 API Reference #
Clases Principales #
TraderPalSDK
Clase estática principal para inicializar y gestionar el SDK.
Métodos principales:
initialize(): Inicializa el SDK con token, userId y opciones de configuracióntoken(String, requerido): Token JWT del usuariouserId(String, requerido): ID del usuariocontext(BuildContext, requerido): Contexto de Fluttermode(String, opcional): Modo de tema ('dark' o 'light')useSandbox(bool, opcional): Si estrue, usaAPI_URL_DEBUG; si esfalse, usaAPI_URL(default:false)onComplete(Function, opcional): Callback cuando la inicialización es exitosaonCancel(Function, opcional): Callback cuando el usuario cancelaonError(Function, opcional): Callback cuando ocurre un error
close(): Cierra el SDK y regresa a la app del clienteaccountClosed(): Verifica si la cuenta está cerrada
TraderPalApp
Widget principal que configura la aplicación con tema y navegación.
ApiService
Servicio para realizar llamadas API con manejo de errores normalizado.
Métodos principales:
initialize(): Inicializa el cliente HTTPvalidateSubscription(): Valida el estado de suscripción
SubscriptionService
Servicio para validar tokens JWT y suscripciones.
Métodos principales:
validateSubscription(): Valida un token JWT y retorna el estado
AppColors / AppColorsDark
Sistema de colores completo con escalas para diferentes tonos y modos.
Connect (Clase de Ejemplo)
Clase helper para manejar la autenticación y obtención de tokens de forma automática.
Métodos principales:
startTokenManager(): Inicializa el gestor de tokens, hace login y configura refresh automático cada 3 horaslogin(): Realiza login usando credenciales de Partner (PARTNER_EMAIL,PARTNER_PASSWORD,PARTNER_API_KEY)_refreshTokenLogic(): Renueva automáticamente los tokens cuando expiran
Propiedades:
authToken(String?): Token de autenticación actualrefreshToken(String?): Token de refresh actual
Nota: Esta es una clase de ejemplo que puedes usar como referencia. Asegúrate de tener configuradas las variables de entorno necesarias en tu archivo .env.
Providers Disponibles #
- authProvider: Gestión de autenticación y tokens
- userStatusProvider: Estado del usuario
- marketProvider: Datos de mercado
- navigationProvider: Control de navegación
Widgets Reutilizables #
- BottomMenu: Menú de navegación inferior
- BaseAmountPage: Página base para entrada de montos
- TraderPalFooter: Footer personalizado
- MarketStatus: Indicador de estado del mercado
- SearchResultCard: Tarjeta de resultado de búsqueda
- DateFilterScreen: Filtro de fechas
- ConfirmationScreen: Pantalla de confirmación
🔒 Seguridad #
- Validación automática de tokens JWT
- Verificación de expiración de tokens
- Manejo seguro de credenciales
- Validación de suscripciones en tiempo real
🌐 Plataformas Soportadas #
- ✅ Android
- ✅ iOS
- ✅ Web
📄 Licencia #
Este proyecto está bajo la Licencia especificada en el archivo LICENSE.
🤝 Contribuir #
- Fork el proyecto
- Crea una rama para tu feature (
git checkout -b feature/AmazingFeature) - Commit tus cambios (
git commit -m 'Add some AmazingFeature') - Push a la rama (
git push origin feature/AmazingFeature) - Abre un Pull Request
📞 Soporte #
Para soporte técnico o consultas sobre el paquete:
- Crea un issue en el repositorio
- Contacta al equipo de desarrollo de TraderPal
📚 Ejemplo Completo #
Para ver un ejemplo completo de cómo usar este paquete, consulta el directorio /example.
Ejecutar el ejemplo #
cd example
flutter pub get
flutter run
Desarrollado por TraderPal con ❤️ para la comunidad Flutter
Versión Beta: Esta es una versión beta para pruebas tempranas y retroalimentación. Algunas funcionalidades pueden estar en desarrollo activo.