⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⣄⠀⠀⠀⠀⠀⠀⠀⠀⣠⣤⡀⠀⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⣄⠀⠀⠀⠀⠀⠀⠀⠀⣠⣤⡀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⢄⠈⢿⡆⠀⠀⠀⠀⠀⠀⢰⡿⠁⡠⠀⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⠀⢄⠈⢿⡆⠀⠀⠀⠀⠀⠀⢰⡿⠁⡠⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠘⣧⠈⢿⠀⠀⠀⠀⠀⠀⡿⠁⣼⠃⠀⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⠀⠘⣧⠈⢿⠀⠀⠀⠀⠀⠀⡿⠁⣼⠃⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⢻⣇⢸⣇⠀⠀⠀⠀⣸⡇⣸⡟⠀⠀⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⠀⠀⢻⣇⢸⣇⠀⠀⠀⠀⣸⡇⣸⡟⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣀⣿⣴⣶⣶⣦⣿⣀⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣀⣿⣴⣶⣶⣦⣿⣀⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⣀⣀⣀⠀⢹⣿⣿⣿⣿⣿⣿⣿⣿⡏⠀⣀⣀⣀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⣀⣀⣀⠀⢹⣿⣿⣿⣿⣿⣿⣿⣿⡏⠀⣀⣀⣀⠀⠀⠀⠀⠀⠀
⠀⠀⣠⣴⣾⠟⠋⠉⠀⠀⣿⣿⠿⢿⣿⣿⡿⠿⣿⣿⠀⠀⠉⠙⠻⣷⣦⣄⠀⠀     ⠀⠀⣠⣴⣾⠟⠋⠉⠀⠀⣿⣿⠿⢿⣿⣿⡿⠿⣿⣿⠀⠀⠉⠙⠻⣷⣦⣄⠀⠀
⠀⠘⢿⣿⣿⣦⣀⡀⠀⠀⠻⠁⠀⠈⠿⠿⠁⠀⠈⠟⠀⠀⢀⣀⣴⣿⣿⡿⠃⠀     ⠀⠘⢿⣿⣿⣦⣀⡀⠀⠀⠻⠁⠀⠈⠿⠿⠁⠀⠈⠟⠀⠀⢀⣀⣴⣿⣿⡿⠃⠀
⠀⠀⠀⠉⠙⠻⠿⠿⣿⣷⣶⣶⣶⣦⣤⣤⣴⣶⣶⣶⣾⣿⠿⠿⠟⠋⠉⠀⠀⠀     ⠀⠀⠀⠉⠙⠻⠿⠿⣿⣷⣶⣶⣶⣦⣤⣤⣴⣶⣶⣶⣾⣿⠿⠿⠟⠋⠉⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢠⣤⣤⣤⣬⣭⣭⣭⣭⣭⣭⣥⣤⣤⣤⡄⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⢠⣤⣤⣤⣬⣭⣭⣭⣭⣭⣭⣥⣤⣤⣤⡄⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢈⣉⠙⠛⠛⠛⠿⠿⠿⠿⠛⠛⠛⠋⢉⡁⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⢈⣉⠙⠛⠛⠛⠿⠿⠿⠿⠛⠛⠛⠋⢉⡁⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣶⣶⣶⣶⣶⣶⣾⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣶⣶⣶⣶⣶⣶⣾⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣇⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣇⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠙⠛⠛⠛⠛⠛⠛⠛⠛⠋⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀     ⠀⠀⠀⠀⠀⠀⠀⠀⠉⠉⠙⠛⠛⠛⠛⠛⠛⠛⠛⠋⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀

Sinclair

Rest API de manipulación de imágenes (Image Manipulation as a Service) con autenticación de usuarios a través de JWTs.
Esta API es para el proyecto final de la materia de Tópicos Especiales de Programación.

Requerimientos

• Bun: Guía de instalación

Setup

1. Clona el repositorio

git clone https://github.com/ClaraUCAB/Sinclair
cd Sinclair

2. Instala las dependencias

bun install

3. Configura las variables de entorno en .env. Utiliza .env.example como referencia.

Variables de Entorno

Variable	Default	Requerido	Descripción
PORT	3000	Sí	Puerto donde va a iniciar el servidor.
JWT_SECRET		Sí	Secreto usado para generar las JWT.
MONGODB_URI		Sí	URI de la base de datos de MongoDB.

Ejecución

Para ejecutar la API con normalidad, corre:

bun run start

Para development

Al ejecutar el script de development, la API se reiniciará automáticamente cuando algún archivo cambie para poder probar los cambios inmediatamente en tiempo real.

bun run dev

Uso

Autenticación

Al realizar operaciones es necesario una JWT agregada como header Authorization: Bearer <token> en todas las peticiones.
Para esto primero es necesario autenticarse. Esto se logra con los siguientes endpoints:

Método	URL	Descripción
POST	/auth/register	Registra al usuario en la DB.
POST	/auth/login	Autentica al usuario. Devuelve una JWT.

Transformación de imágenes

Método	URL	Descripción
POST	/images/rotate	Rota la imagen.
POST	/images/resize	Redimensiona la imagen.
POST	/images/crop	Recorta la imagen.
POST	/images/filter	Aplica un filtro a la imagen.
POST	/images/format	Cambia el formato de la imagen.
POST	/images/pipeline	Encadena múltiples operaciones simultáneamente.

Parámetros

Parámetros para los endpoints de /auth/register y /auth/login

{
    email: string,
    password: string,
}

Parámetros para los endpoints de /images/rotate

{
    angle: number,
}

Parámetros para los endpoints de /images/resize

{
    width: number,
    height: number,
    fit?: ('cover' | 'contain' | 'fill' | 'inside' | 'outside'),
}

Parámetros para los endpoints de /images/crop

{
    left: number,
    top: number,
    width: number,
    height: number,
}

Parámetros para los endpoints de /images/filter

{
    filter: ('blur' | 'sharpen' | 'grayscale'),
}

Parámetros para los endpoints de /images/format

{
    format: ('jpeg' | 'png' | 'webp' | 'avif' | 'tiff'),
}

Parámetros para los endpoints de /images/pipeline

El endpoint de pipeline tiene un único parámetro operations, el cual debe ser suministrado como un string en forma de JSON.
Este debe contener una lista de operaciones. Las operaciones pueden repetirse para aplicarse varias veces y se ejecutarán en orden.

{
    operations: ('rotate' | 'resize' | 'crop' | 'filter' | 'format')[],
}

Refiérase al ejemplo de pipeline en la sección de ejemplos.

Códigos de Estado HTTP

Código	Situación
200	Operación exitosa
400	Parámetros inválidos o faltantes
401	Token JWT ausente o inválido
413	Archivo demasiado grande
415	Formato de imagen no soportado
500	Error interno del servidor

Ejemplos

Registrar usuario

curl -X POST http://localhost:3000/auth/register \
    -H 'Content-Type: application/json' \
    -d '{"email": "user@email.com", "password": "waos123"}'

Iniciar sesión

curl -X POST http://localhost:3000/auth/login \
    -H 'Content-Type: application/json' \
    -d '{"email": "user@email.com", "password": "waos123"}'

# export SINCLAIR_JWT='<token>'

Rotar

curl -X POST http://localhost:3000/images/rotate \
    -H "Authorization: Bearer $SINCLAIR_JWT" \
    -H 'Content-Type: multipart/form-data' \
    -F 'image=@images/narga.png' \
    -F 'angle=111' \
    --output rotated.png

Redimensionar

curl -X POST http://localhost:3000/images/resize \
    -H "Authorization: Bearer $SINCLAIR_JWT" \
    -H 'Content-Type: multipart/form-data' \
    -F 'image=@images/narga.png' \
    -F 'width=30' \
    -F 'height=20' \
    --output resized.png

Recortar

curl -X POST http://localhost:3000/images/crop \
    -H "Authorization: Bearer $SINCLAIR_JWT" \
    -H 'Content-Type: multipart/form-data' \
    -F 'image=@images/niko.png' \
    -F 'left=264' -F 'top=300' -F 'width=550' -F 'height=600' \
    --output cropped.png

Aplicar filtro

curl -X POST http://localhost:3000/images/filter \
    -H "Authorization: Bearer $SINCLAIR_JWT" \
    -H 'Content-Type: multipart/form-data' \
    -F 'image=@images/niko.png' \
    -F 'filter=grayscale' \
    --output filtered.png

Convertir formato

curl -X POST http://localhost:3000/images/format \
    -H "Authorization: Bearer $SINCLAIR_JWT" \
    -H 'Content-Type: multipart/form-data' \
    -F 'image=@images/niko.png' \
    -F 'format=jpeg' \
    --output converted.jpeg

Pipeline

curl -X POST http://localhost:3000/images/pipeline \
    -H "Authorization: Bearer $SINCLAIR_JWT" \
    -H 'Content-Type: multipart/form-data' \
    -F 'image=@images/narga.png' \
    -F 'operations=["rotate", "crop", "rotate", "format", "rotate"]' \
    -F 'angle=100' \
    -F 'left=20' \
    -F 'top=30' \
    -F 'width=50' \
    -F 'height=60' \
    -F 'format=tiff' \
    --output pipeline_result.tiff