@theoptimalpartner/auth-react-client

Librería cliente de React completa para el servicio de autenticación de TheOptimalPartner. Incluye componentes, hooks, y un template de ejemplo con todas las funcionalidades de autenticación implementadas.

🚀 Características

• ✅ Autenticación completa: Login, registro, logout con tokens JWT
• ✅ Recuperación de contraseña: Solicitud y confirmación de reset
• ✅ Confirmación de cuenta: Verificación por email con código
• ✅ Cambio de contraseña: Para usuarios autenticados
• ✅ Nueva contraseña requerida: Flujo de Cognito para primera vez
• ✅ Reenvío de códigos: Confirmación y recuperación
• ✅ Rutas protegidas: Componente para proteger contenido
• ✅ Auto-refresh: Renovación automática de tokens
• ✅ TypeScript: Tipado completo incluido
• ✅ Template de ejemplo: Aplicación completa de referencia

📦 Instalación

npm install @theoptimalpartner/auth-react-client

🏗️ Template de Ejemplo

El paquete incluye un template completo en el directorio /example que demuestra todas las funcionalidades:

cd example
npm install
npm run dev

Páginas incluidas en el template:

• 🏠 HomePage - Página principal con navegación
• 🔐 LoginPage - Inicio de sesión con opciones de recuperación
• 📝 SignupPage - Registro con redirección a confirmación
• ✅ ConfirmAccountPage - Confirmación de cuenta con reenvío
• 🔑 ForgotPasswordPage - Solicitud de recuperación de contraseña
• 🆕 ResetPasswordPage - Restablecimiento con código
• 🔧 ChangePasswordPage - Cambio de contraseña para usuarios autenticados
• ⚡ NewPasswordRequiredPage - Nueva contraseña requerida (Cognito)
• 📊 DashboardPage - Panel con información del usuario

🛠️ Inicio Rápido

1. Configurar AuthProvider

Envuelve tu aplicación con el AuthProvider:

import React from "react";
import { AuthProvider } from "@theoptimalpartner/auth-react-client";

const authConfig = {
  apiBaseUrl: "https://tu-api-auth.amazonaws.com/dev", // URL de tu API Gateway
  autoRefresh: true,
  onTokenExpired: () => console.log("Token expirado"),
  onAuthError: (error) => console.error("Error de auth:", error),
};

function App() {
  return (
    <AuthProvider config={authConfig}>
      <Router>
        <Routes>
          <Route path="/login" element={<LoginPage />} />
          <Route path="/dashboard" element={<DashboardPage />} />
          {/* Más rutas... */}
        </Routes>
      </Router>
    </AuthProvider>
  );
}

2. Usar Componentes Preconstruidos

import React from "react";
import {
  LoginForm,
  SignupForm,
  ForgotPasswordForm,
  ResetPasswordForm,
  ConfirmAccountForm,
  ChangePasswordForm,
  ProtectedRoute,
} from "@theoptimalpartner/auth-react-client";

function LoginPage() {
  const navigate = useNavigate();
  
  return (
    <LoginForm
      onSuccess={() => navigate("/dashboard")}
      onError={(error) => console.error("Login falló:", error)}
      onSignupClick={() => navigate("/signup")}
    />
  );
}

function Dashboard() {
  return (
    <ProtectedRoute>
      <div>
        <h1>Panel Protegido</h1>
        <ChangePasswordForm 
          onSuccess={() => alert("Contraseña cambiada!")}
        />
      </div>
    </ProtectedRoute>
  );
}

3. Usar Hook de Autenticación

import { useAuth } from "@theoptimalpartner/auth-react-client";

function MiComponente() {
  const {
    // Estado
    user,
    isAuthenticated,
    isLoading,
    error,
    
    // Métodos principales
    login,
    signup,
    logout,
    
    // Funcionalidades extendidas
    changePassword,
    newPasswordRequired,
    forgotPassword,
    confirmForgotPassword,
    confirmSignUp,
    resendConfirmationCode,
  } = useAuth();

  // Usar los métodos...
}

📚 Referencia de API

AuthConfig

interface AuthConfig {
  apiBaseUrl: string;                    // URL de tu API Gateway (requerido)
  tokenStorageKey?: string;              // Por defecto: 'auth_token'
  refreshTokenStorageKey?: string;       // Por defecto: 'auth_refresh_token'
  autoRefresh?: boolean;                 // Por defecto: true
  onTokenExpired?: () => void;           // Callback cuando expire el token
  onAuthError?: (error: string) => void; // Callback para errores de auth
}

Hook useAuth

const {
  // Estado de autenticación
  user: AuthUser | null,
  tokens: AuthTokens | null,
  isAuthenticated: boolean,
  isLoading: boolean,
  error: string | null,

  // Métodos principales
  login: (emailOrUsername: string, password: string) => Promise<boolean>,
  signup: (email: string, password: string, userData?) => Promise<boolean>,
  logout: () => Promise<void>,
  refreshAuth: () => Promise<void>,
  clearError: () => void,

  // Gestión de contraseñas
  changePassword: (data: ChangePasswordRequest) => Promise<void>,
  newPasswordRequired: (data: NewPasswordRequiredRequest) => Promise<AuthTokens>,
  forgotPassword: (data: ForgotPasswordRequest) => Promise<void>,
  confirmForgotPassword: (data: ConfirmForgotPasswordRequest) => Promise<void>,

  // Confirmación de cuenta
  confirmSignUp: (data: ConfirmSignUpRequest) => Promise<void>,
  resendConfirmationCode: (data: ResendConfirmationRequest) => Promise<void>,
} = useAuth();

Tipos de Request

interface ChangePasswordRequest {
  previousPassword: string;
  proposedPassword: string;
}

interface NewPasswordRequiredRequest {
  session: string;
  newPassword: string;
  identifier: string;
}

interface ForgotPasswordRequest {
  email?: string;
  username?: string;
}

interface ConfirmForgotPasswordRequest {
  email?: string;
  username?: string;
  confirmationCode: string;
  newPassword: string;
}

interface ConfirmSignUpRequest {
  email?: string;
  username?: string;
  confirmationCode: string;
}

interface ResendConfirmationRequest {
  email?: string;
  username?: string;
}

🎨 Componentes Disponibles

Formularios de Autenticación

LoginForm

<LoginForm
  onSuccess={() => {}}                // Callback de éxito
  onError={(error) => {}}             // Callback de error
  onSignupClick={() => {}}            // Navegación a registro
  className="custom-class"            // Clase CSS personalizada
  showSignupLink={true}               // Mostrar enlace de registro
/>

SignupForm

<SignupForm
  onSuccess={(data) => {}}            // Callback de éxito con datos
  onError={(error) => {}}             // Callback de error
  onLoginClick={() => {}}             // Navegación a login
  className="custom-class"            // Clase CSS personalizada
  requireUsername={false}             // Requerir campo username
  showOptionalFields={true}           // Mostrar campos opcionales
/>

ForgotPasswordForm

<ForgotPasswordForm
  onSuccess={(data) => {}}            // Callback de éxito
  onError={(error) => {}}             // Callback de error
  onBackToLogin={() => {}}            // Navegación a login
  className="custom-class"            // Clase CSS personalizada
  showBackLink={true}                 // Mostrar enlace de regreso
/>

ResetPasswordForm

<ResetPasswordForm
  onSuccess={() => {}}                // Callback de éxito
  onError={(error) => {}}             // Callback de error
  onBackToForgot={() => {}}           // Volver a solicitar código
  onBackToLogin={() => {}}            // Navegación a login
  className="custom-class"            // Clase CSS personalizada
  initialEmail="[email protected]"     // Email inicial
  showBackLinks={true}                // Mostrar enlaces de navegación
/>

ConfirmAccountForm

<ConfirmAccountForm
  onSuccess={() => {}}                // Callback de éxito
  onError={(error) => {}}             // Callback de error
  onBackToLogin={() => {}}            // Navegación a login
  onBackToSignup={() => {}}           // Navegación a registro
  className="custom-class"            // Clase CSS personalizada
  initialEmail="[email protected]"     // Email inicial
  showBackLinks={true}                // Mostrar enlaces de navegación
/>

ChangePasswordForm

<ChangePasswordForm
  onSuccess={() => {}}                // Callback de éxito
  onError={(error) => {}}             // Callback de error
  className="custom-class"            // Clase CSS personalizada
/>

NewPasswordRequiredForm

<NewPasswordRequiredForm
  onSuccess={() => {}}                // Callback de éxito
  onError={(error) => {}}             // Callback de error
  className="custom-class"            // Clase CSS personalizada
  initialSession="session-token"      // Sesión inicial
  initialIdentifier="[email protected]" // Identificador inicial
/>

Utilidades

ProtectedRoute

<ProtectedRoute
  fallback={<LoginPage />}            // Componente para no autenticados
  redirectTo="/login"                 // URL de redirección
>
  <TuContenidoProtegido />
</ProtectedRoute>

JWTStatus & JWTStats

import { JWTStatus, JWTStats } from "@theoptimalpartner/auth-react-client";

// Muestra el estado del token actual
<JWTStatus />

// Muestra estadísticas detalladas del JWT
<JWTStats />

🔗 Endpoints Soportados

El cliente se conecta automáticamente a estos endpoints de tu API:

• POST /login - Inicio de sesión
• POST /signup - Registro de usuario
• POST /logout - Cierre de sesión
• POST /refresh-token - Renovación de tokens
• POST /validate-token - Validación de token
• POST /change-password - Cambio de contraseña
• POST /new-password-required - Nueva contraseña requerida
• POST /forgot-password - Solicitud de recuperación
• POST /confirm-forgot-password - Confirmación de recuperación
• POST /confirm-signup - Confirmación de registro
• POST /resend-confirmation-code - Reenvío de código

🎯 Flujos de Autenticación Completos

1. Registro y Confirmación

Signup → ConfirmAccount → Login → Dashboard

2. Recuperación de Contraseña

Login → ForgotPassword → ResetPassword → Login → Dashboard

3. Cambio de Contraseña

Dashboard → ChangePassword → Success

4. Nueva Contraseña Requerida (Cognito)

Login → NewPasswordRequired → Dashboard

🎨 Personalización de Estilos

Los componentes vienen con clases CSS que puedes personalizar:

/* Contenedores principales */
.auth-page { /* Página completa */ }
.auth-container { /* Contenedor del formulario */ }
.auth-header { /* Header con título */ }

/* Formularios */
.auth-form { /* Contenedor del formulario */ }
.form-group { /* Contenedor del campo */ }
.form-input { /* Campos de entrada */ }
.submit-button { /* Botón principal */ }
.secondary-button { /* Botón secundario */ }

/* Mensajes */
.error-message { /* Mensajes de error */ }
.success-message { /* Mensajes de éxito */ }

/* Navegación */
.auth-link { /* Contenedor de enlaces */ }
.link-button { /* Botones de enlace */ }
.auth-links { /* Múltiples enlaces */ }
.auth-actions { /* Acciones adicionales */ }

🔧 Configuración Avanzada

Manejo de Errores Personalizado

const authConfig = {
  apiBaseUrl: "tu-api-url",
  onAuthError: (error) => {
    // Log personalizado
    console.error("Auth Error:", error);
    
    // Notificaciones toast
    toast.error(error);
    
    // Redirección condicional
    if (error.includes("expired")) {
      navigate("/login");
    }
  },
  onTokenExpired: () => {
    toast.warning("Sesión expirada, por favor inicia sesión nuevamente");
    navigate("/login");
  }
};

Storage Personalizado

import { authStorage } from "@theoptimalpartner/auth-react-client";

// Acceso directo al storage
const token = authStorage.getAccessToken();
const refreshToken = authStorage.getRefreshToken();

// Limpiar storage manualmente
authStorage.clearTokens();

// Establecer tokens manualmente
authStorage.setTokens(accessToken, refreshToken);

Validación JWT Offline

import { 
  validateTokenOffline,
  decodeJWTToken,
  isJWTExpired 
} from "@theoptimalpartner/auth-react-client";

// Validar token sin llamada a API
const validation = await validateTokenOffline(token);
if (validation.valid) {
  console.log("Token válido:", validation.decoded);
}

// Decodificar JWT
const decoded = decodeJWTToken(token);

// Verificar expiración
const isExpired = isJWTExpired(token);

🌐 Soporte para Múltiples Identificadores

El sistema soporta tanto email como username para autenticación:

// Login con email
await login("[email protected]", "contraseña123");

// Login con username  
await login("nombreusuario", "contraseña123");

// Recuperación con email
await forgotPassword({ email: "[email protected]" });

// Recuperación con username
await forgotPassword({ username: "nombreusuario" });

📱 Ejemplo de Implementación Completa

Ver el directorio /example para una aplicación React completa que implementa:

• Todas las páginas de autenticación
• Navegación entre flujos
• Estilos responsivos
• Manejo de errores
• Estados de carga
• Rutas protegidas
• Dashboard con funcionalidades

# Clonar y ejecutar el ejemplo
git clone [tu-repo]
cd auth-react-client/example
npm install
npm run dev

🛡️ Seguridad

• ✅ Tokens JWT seguros con validación offline
• ✅ Auto-refresh de tokens antes de expiración
• ✅ Limpieza automática de storage en logout
• ✅ Validación de formularios del lado cliente
• ✅ Manejo seguro de errores sin exponer detalles
• ✅ Soporte para tokens blacklist

📄 Licencia

MIT

🤝 Contribución

Para contribuir al proyecto, ver las guías en el repositorio principal.

Desarrollado por TheOptimalPartner 🚀