kapi-mvc-blank 1.0.0

package/compare-versions.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import http from 'http';
+
+function testEndpoint(path) {
+  return new Promise((resolve) => {
+    const options = {
+      hostname: 'localhost',
+      port: 3000,
+      path,
+      method: 'GET'
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          resolve(parsed);
+        } catch {
+          resolve(data);
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      resolve({ error: error.message });
+    });
+
+    req.end();
+  });
+}
+
+console.log('🧪 Testing API v1 vs v2 comparison...\n');
+
+// Test v1
+console.log('📊 API v1 Response (/api/v1/users/info):');
+const v1Info = await testEndpoint('/api/v1/users/info');
+console.log(JSON.stringify(v1Info, null, 2));
+
+// Test v2
+console.log('\n📊 API v2 Response (/api/v2/users/info):');
+const v2Info = await testEndpoint('/api/v2/users/info');
+console.log(JSON.stringify(v2Info, null, 2));
+
+console.log('\n✅ Comparison completed!');
+console.log('✓ v2 includes: api_version, os, arch, hostname');
+process.exit(0);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "kapi-mvc-blank",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "server.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "jest --watchAll"
+  },
+  "keywords": [
+    "api",
+    "node",
+    "prisma",
+    "mvc"
+  ],
+  "author": "@kferrandonFulbert",
+  "license": "ISC",
+  "description": "Framework MVC pour démarrer rapidement un projet d'API avec Node.js et Prisma (avec exemples d'authentification, upload de fichiers, documentation Swagger, logs avec Pino, etc.)",
+  "dependencies": {
+    "@prisma/adapter-mariadb": "^7.2.0",
+    "@prisma/client": "^7.2.0",
+    "bcryptjs": "^3.0.3",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.2.1",
+    "jsonwebtoken": "^9.0.3",
+    "multer": "^1.4.5-lts.1",
+    "pino": "^10.1.0",
+    "pino-http": "^11.0.0",
+    "rad-api": "^1.0.3",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^4.6.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "jest": "^30.2.0",
+    "nodemon": "^3.1.11",
+    "prisma": "^7.2.0",
+    "supertest": "^7.2.2"
+  }
+}

package/prisma/migrations/20260116084200_init/migration.sql

@@ -0,0 +1,23 @@
+-- CreateTable
+CREATE TABLE `User` (
+    `id` INTEGER NOT NULL AUTO_INCREMENT,
+    `email` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NULL,
+
+    UNIQUE INDEX `User_email_key`(`email`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- CreateTable
+CREATE TABLE `Post` (
+    `id` INTEGER NOT NULL AUTO_INCREMENT,
+    `title` VARCHAR(191) NOT NULL,
+    `content` VARCHAR(191) NULL,
+    `published` BOOLEAN NOT NULL DEFAULT false,
+    `authorId` INTEGER NOT NULL,
+
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `Post` ADD CONSTRAINT `Post_authorId_fkey` FOREIGN KEY (`authorId`) REFERENCES `User`(`id`) ON DELETE RESTRICT ON UPDATE CASCADE;

package/prisma/migrations/migration_lock.toml

@@ -0,0 +1,3 @@
+# Please do not edit this file manually
+# It should be added in your version-control system (e.g., Git)
+provider = "mysql"

package/prisma/schema.prisma

@@ -0,0 +1,25 @@
+generator client {
+  provider = "prisma-client-js"
+  output   = "../generated/prisma"
+}
+
+datasource db {
+  provider = "mysql"
+}
+
+
+model User {
+  id    Int     @id @default(autoincrement())
+  email String  @unique
+  name  String?
+  posts Post[]
+}
+
+model Post {
+  id        Int     @id @default(autoincrement())
+  title     String
+  content   String?
+  published Boolean @default(false)
+  author    User    @relation(fields: [authorId], references: [id])
+  authorId  Int
+}

package/prisma.config.ts

@@ -0,0 +1,14 @@
+// This file was generated by Prisma, and assumes you have installed the following:
+// npm install --save-dev prisma dotenv
+import "dotenv/config";
+import { defineConfig } from "prisma/config";
+
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  migrations: {
+    path: "prisma/migrations",
+  },
+  datasource: {
+    url: process.env["DATABASE_URL"],
+  },
+});

package/src/__tests__/user.controller.test.js

@@ -0,0 +1,16 @@
+import request from 'supertest';
+import app, { initializeRoutes } from '../app.js';
+
+describe('User Controller', () => {
+  beforeAll(async () => {
+    await initializeRoutes();
+  });
+
+  test('GET /api/v1/users/info returns 200 and msg', async () => {
+    const res = await request(app)
+      .get('/api/v1/users/info')
+      .expect(200);
+    
+    expect(res.body).toEqual({ msg: 'ok' });
+  });
+});

package/src/app.js

@@ -0,0 +1,121 @@
+import express from 'express';
+import cors from 'cors';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pinoMiddleware } from './utils/logger.js';
+import { rateLimit } from 'express-rate-limit'
+import swaggerUi from 'swagger-ui-express';
+import swaggerSpec from './config/swagger.js';
+import { initializePrisma } from './services/prisma.service.js';
+
+dotenv.config();
+
+// Initialize Prisma globally
+initializePrisma();
+
+const app = express();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const UPLOAD_DIR = process.env.UPLOAD_DIR || 'uploads';
+
+const limiter = rateLimit({
+	windowMs: 15 * 60 * 1000, // 15 minutes
+	limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
+	standardHeaders: 'draft-8', // draft-6: `RateLimit-*` headers; draft-7 & draft-8: combined `RateLimit` header
+	legacyHeaders: false, // Disable the `X-RateLimit-*` headers.
+	ipv6Subnet: 56, // Set to 60 or 64 to be less aggressive, or 52 or 48 to be more aggressive
+})
+app.use(limiter);
+
+app.use(cors());
+app.use(pinoMiddleware);
+app.use(express.json());
+
+// Serve uploaded files statically
+app.use(`/${UPLOAD_DIR}`, express.static(UPLOAD_DIR));
+
+// Swagger UI
+app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+app.get('/docs.json', (req, res) => res.json(swaggerSpec));
+
+// Export function to initialize routes
+export async function initializeRoutes() {
+  const versionsDir = path.join(__dirname, './');
+  console.log(versionsDir);
+  const versionDirs = fs.readdirSync(versionsDir).filter(file => {
+    const fullPath = path.join(versionsDir, file);
+    return fs.statSync(fullPath).isDirectory() && /^v\d+$/.test(file);
+  });
+
+
+  // Sort versions numerically (v1, v2, v3, etc.)
+  versionDirs.sort((a, b) => {
+    const numA = Number.parseInt(a.slice(1), 10);
+    const numB = Number.parseInt(b.slice(1), 10);
+    return numA - numB;
+  });
+
+  // Load routes for each version
+  for (const version of versionDirs) {
+    const versionPath = path.join(__dirname, version);
+    const routesPath = path.join(versionPath, 'routes');
+   
+    if (fs.existsSync(routesPath)) {
+      const routeFiles = fs.readdirSync(routesPath).filter(f => f.endsWith('.routes.js'));
+       console.log(routeFiles);
+      for (const routeFile of routeFiles) {
+        let routeName = routeFile.replace('.routes.js', ''); // e.g., 'auth', 'user', 'upload'
+        
+        // Pluralize route names for better REST convention
+        if (routeName === 'user') routeName = 'users';
+        if (routeName === 'citation') routeName = 'citations';
+        if (routeName === 'upload') routeName = 'uploads';
+        
+        const routePath = path.join(routesPath, routeFile);
+        
+        try {
+          const routeModule = await import(`file://${routePath}`);
+          const router = routeModule.default;
+          
+          // Register route: /api/v1/auth, /api/v1/users, /api/v1/uploads, etc.
+          const apiPath = `/api/${version}/${routeName}`;
+          app.use(apiPath, router);
+          console.log(`✓ Route registered: ${apiPath}`);
+        } catch (err) {
+          console.error(`✗ Failed to load route ${routePath}:`, err.message);
+        }
+      }
+    }
+  }
+}
+
+// Error handler — normalize multer and validation errors
+app.use((err, req, res, next) => {
+  // Multer-specific errors
+  if (err?.name === 'MulterError') {
+    const status = err.code === 'LIMIT_FILE_SIZE' ? 413 : 400;
+    req.log?.warn({ err }, 'Multer error');
+    return res.status(status).json({ error: err.message, code: err.code });
+  }
+
+  // Errors thrown by validators / custom errors
+  if (err && (err.message || err.status)) {
+    const status = Number.isInteger(err.status) && err.status >= 400 ? err.status : 400;
+    req.log?.warn({ err }, 'Request error');
+    return res.status(status).json({ error: err.message || 'Bad Request' });
+  }
+
+  // Fallback to 500
+  if (err) {
+    req.log?.error({ err }, 'Unhandled error');
+    return res.status(500).json({ error: 'Internal Server Error' });
+  }
+
+  return next();
+});
+
+export default app; 

package/src/config/swagger.js

@@ -0,0 +1,30 @@
+import swaggerJsdoc from 'swagger-jsdoc';
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'API documentation',
+      version: process.env.npm_package_version || '1.0.0',
+      description: 'MVC API documentation blank template'
+    },
+    servers: [
+      { url: '/api/v1' },
+      { url: '/api/v2' }
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT'
+        }
+      }
+    }
+  },
+  apis: ['./src/v*/routes/*.js', './src/v*/controllers/*.js']
+};
+
+const swaggerSpec = swaggerJsdoc(options);
+
+export default swaggerSpec;

package/src/jest.config.cjs

@@ -0,0 +1,10 @@
+module.exports = {
+  testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.js'],
+  transform: {},
+  testMatch: ['**/__tests__/**/*.test.js'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1'
+  },
+  transformIgnorePatterns: ['node_modules/(?!(supertest|.*\\.mjs$))']
+};

package/src/server.js

@@ -0,0 +1,10 @@
+import app, { initializeRoutes } from './app.js';
+
+const PORT = process.env.PORT || 3000;
+
+// Initialize routes then start server
+await initializeRoutes();
+
+app.listen(PORT, () => {
+  console.log(`🚀 Server running on port ${PORT}`);
+});

package/src/services/jwt.service.js

@@ -0,0 +1,7 @@
+import jwt from 'jsonwebtoken';
+
+export const generateToken = (payload) => {
+  return jwt.sign(payload, process.env.JWT_SECRET, {
+    expiresIn: process.env.JWT_EXPIRE
+  });
+};

package/src/services/prisma.service.js

@@ -0,0 +1,26 @@
+import { PrismaMariaDb } from '@prisma/adapter-mariadb';
+import { PrismaClient } from '../../generated/prisma/client.js';
+
+let prisma;
+
+export function initializePrisma() {
+  const maria = new PrismaMariaDb({
+    host: process.env.DATABASE_HOST,
+    port: process.env.DATABASE_PORT,
+    user: process.env.DATABASE_USER,
+    password: process.env.DATABASE_PASSWORD,
+    database: process.env.DATABASE_NAME
+  });
+
+  prisma = new PrismaClient({ adapter: maria });
+  return prisma;
+}
+
+export function getPrisma() {
+  if (!prisma) {
+    throw new Error('Prisma has not been initialized. Call initializePrisma() first.');
+  }
+  return prisma;
+}
+
+export default prisma;

package/src/utils/logger.js

@@ -0,0 +1,21 @@
+import fs from 'fs';
+import path from 'path';
+import pino from 'pino';
+import pinoHttp from 'pino-http';
+
+const LOG_DIR = process.env.LOG_DIR || 'logs';
+const LOG_FILE = process.env.LOG_FILE || 'app.log';
+
+// Ensure log directory exists
+if (!fs.existsSync(LOG_DIR)) {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+}
+
+const logPath = path.join(LOG_DIR, LOG_FILE);
+const destination = pino.destination(logPath);
+
+const logger = pino({ level: process.env.LOG_LEVEL || 'info' }, destination);
+
+const pinoMiddleware = pinoHttp({ logger });
+
+export { logger, pinoMiddleware };

package/src/v1/controllers/auth.controller.js

@@ -0,0 +1,19 @@
+import bcrypt from 'bcryptjs';
+import { generateToken } from '../services/jwt.service.js';
+
+// this is an example controller for handling authentication (register, login)
+export const register = async (req, res) => {
+  // TODO : enregistrer l'utilisateur
+  res.json({ message: 'Register OK' });
+};
+
+export const login = async (req, res) => {
+  // TODO : vérifier email + mot de passe
+
+  const token = generateToken({
+    id: 1,
+    role: 'user'
+  });
+
+  res.json({ token });
+};

package/src/v1/controllers/upload.controller.js

@@ -0,0 +1,15 @@
+// this is an exemple controller for handling file uploads
+export const uploadFile = (req, res) => {
+  
+  if (!req.file) {
+      req.log?.warn("No file uploaded");
+    return res.status(400).json({ error: 'No file uploaded' });
+  }
+
+  // Log upload
+  req.log?.info({ filename: req.file.filename, size: req.file.size }, 'file uploaded');
+
+  const uploadDir = process.env.UPLOAD_DIR || 'uploads';
+  const fileUrl = `${req.protocol}://${req.get('host')}/${uploadDir}/${req.file.filename}`;
+  res.status(201).json({ filename: req.file.filename, url: fileUrl });
+};

package/src/v1/controllers/user.controller.js

@@ -0,0 +1,16 @@
+// this is an example controller for handling user profile and info endpoints
+export const profile = (req, res) => {
+  req.log?.info({ userId: req.user?.id }, 'profile requested');
+  res.json({
+    id: req.user.id,
+    role: req.user.role
+  });
+};
+
+export const info = (req, res) => {
+  req.log?.info('info endpoint');
+  res.status(200);
+  res.json({
+    msg: "ok"
+  });
+};

package/src/v1/middlewares/auth.middleware.js

@@ -0,0 +1,19 @@
+import jwt from 'jsonwebtoken';
+
+export const authMiddleware = (req, res, next) => {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader) {
+    return res.status(401).json({ error: 'Token missing' });
+  }
+
+  const token = authHeader.split(' ')[1];
+
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = decoded;
+    next();
+  } catch {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+};

package/src/v1/middlewares/role.middleware.js

@@ -0,0 +1,8 @@
+export const roleMiddleware = (role) => {
+  return (req, res, next) => {
+    if (req.user.role !== role) {
+      return res.status(403).json({ error: 'Forbidden' });
+    }
+    next();
+  };
+};

package/src/v1/models/user.model.js

@@ -0,0 +1,6 @@
+export default {
+  id: Number,
+  email: String,
+  password: String,
+  role: String
+};

package/src/v1/routes/auth.routes.js

@@ -0,0 +1,9 @@
+import { Router } from 'express';
+import { register, login } from '../controllers/auth.controller.js';
+
+const router = Router();
+
+router.post('/register', register);
+router.post('/login', login);
+
+export default router;

package/src/v1/routes/upload.routes.js

@@ -0,0 +1,80 @@
+import { Router } from 'express';
+import multer from 'multer';
+import path from 'path';
+import fs from 'fs';
+import { uploadFile } from '../controllers/upload.controller.js';
+
+const router = Router();
+
+const uploadDir = process.env.UPLOAD_DIR || 'uploads';
+const MAX_SIZE = parseInt(process.env.UPLOAD_MAX_SIZE || String(5 * 1024 * 1024), 10); // default 5MB
+
+// Ensure upload directory exists
+if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir, { recursive: true });
+
+const storage = multer.diskStorage({
+  destination: (req, file, cb) => cb(null, uploadDir),
+  filename: (req, file, cb) => {
+    const ext = path.extname(file.originalname);
+    const name = `${Date.now()}-${Math.random().toString(36).slice(2,8)}${ext}`;
+    cb(null, name);
+  }
+});
+
+const imageFileFilter = (req, file, cb) => {
+  const allowed = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+  if (allowed.includes(file.mimetype)) cb(null, true);
+  else cb(new Error('Only image files are allowed'), false);
+};
+
+const upload = multer({ storage, fileFilter: imageFileFilter, limits: { fileSize: MAX_SIZE } });
+
+/**
+ * @openapi
+ * /uploads:
+ *   post:
+ *     summary: Upload an image file
+ *     consumes:
+ *       - multipart/form-data
+ *     requestBody:
+ *       content:
+ *         multipart/form-data:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               file:
+ *                 type: string
+ *                 format: binary
+ *     responses:
+ *       201:
+ *         description: File uploaded
+ */
+
+const storageWithName = multer.diskStorage({
+  destination: (req, file, cb) => cb(null, uploadDir),
+  filename: (req, file, cb) => {
+    const requested = req.params?.name || '';
+    // sanitize base name and keep or infer extension
+    const safeBase = path.basename(requested, path.extname(requested)).replace(/[^a-zA-Z0-9-_\.]/g, '-');
+    const extFromReq = path.extname(requested);
+    const ext = extFromReq || path.extname(file.originalname) || '';
+    const name = safeBase ? `${safeBase}${ext}` : `${Date.now()}-${Math.random().toString(36).slice(2,8)}${ext}`;
+    cb(null, name);
+  }
+});
+
+const uploadWithName = multer({ storage: storageWithName, fileFilter: imageFileFilter, limits: { fileSize: MAX_SIZE } });
+
+router.post('/:name', (req, res, next) => {
+  const handler = uploadWithName.fields([{ name: 'file', maxCount: 1 }, { name: 'image', maxCount: 1 }]);
+  handler(req, res, (err) => {
+    if (err) return next(err);
+    if (!req.file && req.files) {
+      if (req.files.file && req.files.file.length) req.file = req.files.file[0];
+      else if (req.files.image && req.files.image.length) req.file = req.files.image[0];
+    }
+    uploadFile(req, res, next);
+  });
+});
+
+export default router;

package/src/v1/routes/user.routes.js

@@ -0,0 +1,49 @@
+/**
+ * @openapi
+ * /users/profile:
+ *   get:
+ *     summary: Get current user profile
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: User profile
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 id:
+ *                   type: string
+ *                 role:
+ *                   type: string
+ *       401:
+ *         description: Unauthorized
+ */
+import { Router } from 'express';
+import { profile, info } from '../controllers/user.controller.js';
+import { authMiddleware } from '../middlewares/auth.middleware.js';
+
+const router = Router();
+
+router.get('/profile', authMiddleware, profile);
+
+/**
+ * @openapi
+ * /users/info:
+ *   get:
+ *     summary: Simple info endpoint
+ *     responses:
+ *       200:
+ *         description: OK
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 msg:
+ *                   type: string
+ */
+router.get('/info', info);
+
+export default router;

package/src/v1/services/jwt.service.js

@@ -0,0 +1,7 @@
+import jwt from 'jsonwebtoken';
+
+export const generateToken = (payload) => {
+  return jwt.sign(payload, process.env.JWT_SECRET, {
+    expiresIn: process.env.JWT_EXPIRE
+  });
+};