Autenticación

Endpoints de autenticación para registro, inicio de sesión y gestión de perfiles de usuario.

Modelos de Datos

Los siguientes modelos de Prisma pertenecen al schema auth:

User

model User {
  id            String    @id @default(cuid())
  email         String    @unique
  emailVerified DateTime? @map("email_verified")

  accounts      Account[]       @relation("UserAccounts")
  Authenticator Authenticator[]

  profile   UserProfile?
  createdAt DateTime     @default(now()) @map("created_at")
  updatedAt DateTime     @updatedAt @map("updated_at")

  @@map("users")
  @@schema("auth")
}

Account

model Account {
  id                String @id @default(cuid())
  userId            String @map("user_id")
  type              String
  provider          String
  providerAccountId String @map("provider_account_id")

  refresh_token String? @map("refresh_token") @db.Text
  access_token  String? @map("access_token") @db.Text
  id_token      String? @map("id_token") @db.Text
  session_state String? @map("session_state")
  scope         String?

  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  user User @relation(fields: [userId], references: [id], onDelete: Cascade, name: "UserAccounts")

  @@unique([provider, providerAccountId])
  @@map("accounts")
  @@schema("auth")
}

Authenticator

model Authenticator {
  credentialID         String  @unique
  userId               String
  providerAccountId    String
  credentialPublicKey  String
  counter              Int
  credentialDeviceType String
  credentialBackedUp   Boolean
  transports           String?

  user User @relation(fields: [userId], references: [id], onDelete: Cascade)

  @@id([userId, credentialID])
  @@schema("auth")
}

UserRole (Enum)

enum UserRole {
  ADMIN
  STAFF
  TRAINER
  MEMBER

  @@schema("auth")
}

Endpoints

Registrar Usuario

Registrar un nuevo usuario en el sistema.

URL: /api/v1/auth/register
Método: POST
Autenticación Requerida: No

Descripción Interna

Este endpoint realiza las siguientes operaciones:

Hashea la contraseña usando Bun.password.hash para almacenamiento seguro
Crea el usuario y perfil en una transacción atómica de Prisma:
- Crea el registro User con el email proporcionado
- Crea automáticamente el UserProfile asociado con nombre, tipo de documento y número de documento
- El rol por defecto es MEMBER
Crea la cuenta de credenciales en la tabla Account con:
- type: “credentials”
- provider: “credentials”
- access_token: contraseña hasheada
Retorna el usuario y perfil creados (sin la contraseña)

Nota: La verificación por email está comentada actualmente pero preparada para enviar un enlace de verificación.

Cuerpo de Solicitud

{
  "email": "user@example.com",
  "password": "password123",
  "documentType": "CC",
  "document": "123456789",
  "name": "John Doe"
}

Respuesta

{
  "message": "Usuario registrado exitosamente",
  "data": {
    "user": {
      "id": "cm...",
      "email": "user@example.com"
    },
    "profile": {
      "id": "cm...",
      "role": "USER"
    }
  }
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.auth.register.$post({
  json: {
    email: 'user@example.com',
    password: 'password123',
    documentType: 'CC',
    document: '123456789',
    name: 'John Doe'
  }
})

if (res.ok) {
  const data = await res.json()
  console.log(data.message)
}

Iniciar Sesión

Autenticar un usuario y obtener tokens de acceso.

URL: /api/v1/auth/login
Método: POST
Autenticación Requerida: No

Descripción Interna

Este endpoint realiza las siguientes operaciones:

Busca la cuenta de credenciales del usuario por email en la tabla Account
Verifica la contraseña usando Bun.password.verify comparando con el hash almacenado
Genera tokens JWT:
- Access Token: contiene sub (userId), email, role y pid (profileId). Expira según TOKEN_EXPIRATION
- Refresh Token: contiene solo sub (userId). Expira según REFRESH_TOKEN_EXPIRATION
Retorna los tokens junto con la información básica del usuario y perfil

Errores Comunes

401 Unauthorized: Credenciales inválidas

Cuerpo de Solicitud

{
  "email": "user@example.com",
  "password": "password123"
}

Respuesta

{
  "message": "Login exitoso",
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "eyJ...",
    "user": { ... }
  }
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.auth.login.$post({
  json: {
    email: 'user@example.com',
    password: 'password123'
  }
})

Obtener Perfil

Obtener el perfil del usuario actualmente autenticado.

URL: /api/v1/auth/profile
Método: GET
Autenticación Requerida: Sí

Descripción Interna

Este endpoint realiza las siguientes operaciones:

Obtiene el userId del token JWT en el contexto de la petición
Consulta el perfil completo del usuario incluyendo todas las relaciones:
- Membresía activa (membership)
- Perfil de entrenador si aplica (trainer)
- Rachas activas (streaks)
- Logros obtenidos con detalles (userAchievements.achievement)
- Objetivos personales (goals)
- Meta nutricional (nutritionGoal)
- Seguidores y seguidos (followers, follows)
- Consumo de agua (waterIntake)
- Likes dados (likes)
- Actividades diarias (dailyActivities)
Retorna toda la información del perfil con las relaciones anidadas

Respuesta

{
  "data": {
    "id": "...",
    "userId": "...",
    "name": "John Doe",
    ...
  }
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.auth.profile.$get()

Actualizar Perfil

Actualizar el perfil del usuario actualmente autenticado.

URL: /api/v1/auth/profile
Método: PATCH
Autenticación Requerida: Sí

Descripción Interna

Este endpoint realiza las siguientes operaciones:

Obtiene el userId del token JWT en el contexto
Actualiza el UserProfile con los campos proporcionados:
- Convierte dateOfBirth a objeto Date si se proporciona
- Campos actualizables: name, phone, avatar_url, dateOfBirth, gender, etc.
Verifica completitud del perfil:
- Si profileComplete es false, evalúa si todos los campos requeridos están llenos
- Si el perfil está completo, actualiza profileComplete a true
Retorna el perfil actualizado

Cuerpo de Solicitud (Parcial)

{
  "name": "Jane Doe",
  "phone": "1234567890"
}

Respuesta

{
  "message": "Perfil actualizado exitosamente",
  "data": { ... }
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.auth.profile.$patch({
  json: {
    name: 'Jane Doe'
  }
})

Refrescar Tokens

Refrescar el token de acceso usando un token de refresco válido (pasado via cookie).

URL: /api/v1/auth/refresh
Método: GET
Autenticación Requerida: No (usa cookie de Refresh Token)

Descripción Interna

Este endpoint realiza las siguientes operaciones:

Extrae el refresh token de la cookie de la petición
Verifica el token usando el AUTH_SECRET y extrae el sub (userId)
Busca el usuario en la base de datos con su email, rol y profileId
Genera nuevos tokens:
- Nuevo Access Token con la información actualizada del usuario
- Nuevo Refresh Token
Retorna ambos tokens nuevos

Errores Comunes

401 Unauthorized: Token de refresco inválido o expirado

Respuesta

{
  "message": "Tokens refrescados exitosamente",
  "data": {
    "accessToken": "...",
    "refreshToken": "..."
  }
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.auth.refresh.$get()

Cerrar Sesión

Cerrar sesión del usuario y limpiar cookies de autenticación.

URL: /api/v1/auth/logout
Método: POST
Autenticación Requerida: Sí

Descripción Interna

Este endpoint realiza las siguientes operaciones:

Invalida la sesión del usuario actual
Limpia las cookies de autenticación (access token y refresh token)
Retorna confirmación del cierre de sesión

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.auth.logout.$post()

Olvidé mi Contraseña

Solicitar un enlace para restablecer la contraseña.

URL: /api/v1/auth/forgot-password
Método: POST
Autenticación Requerida: No

Descripción Interna

Este endpoint realiza las siguientes operaciones:

Busca el usuario por email en la base de datos
Verifica el email - Si el email no ha sido verificado, lanza error (requiere contactar soporte)
Genera token de reset válido por 5 minutos usando JWT
Construye el enlace de restablecimiento: {FRONTEND_URL}/reset-password?token={resetToken}
Envía email al usuario con el enlace de restablecimiento

Errores Comunes

400 Bad Request: El email no ha sido verificado
404 Not Found: Usuario no encontrado

Cuerpo de Solicitud

{
  "email": "user@example.com"
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.auth['forgot-password'].$post({
  json: {
    email: 'user@example.com'
  }
})

Restablecer Contraseña

Restablecer contraseña usando el token proporcionado.

URL: /api/v1/auth/reset-password
Método: POST
Autenticación Requerida: No

Descripción Interna

Este endpoint realiza las siguientes operaciones:

Verifica el token JWT y extrae el sub (userId)
Hashea la nueva contraseña usando Bun.password.hash
Busca la cuenta de credenciales del usuario
Actualiza el access_token (contraseña hasheada) en la tabla Account
Retorna confirmación del cambio

Errores Comunes

400 Bad Request: Token inválido o expirado

Cuerpo de Solicitud

{
  "token": "reset_token_here",
  "newPassword": "newpassword123"
}

Ejemplo de Cliente Hono

import { hcWithType } from '@vitality-gym/api/client'

const client = hcWithType('http://localhost:3000')

const res = await client.api.v1.auth['reset-password'].$post({
  json: {
    token: 'reset_token',
    newPassword: 'newpassword123'
  }
})