create-charcole 2.0.4 → 2.2.0

package/template/js/src/modules/auth/auth.routes.js

@@ -0,0 +1,131 @@
+import { Router } from "express";
+import { AuthController } from "./auth.controller.js";
+
+const router = Router();
+
+/**
+ * @swagger
+ * /api/auth/register:
+ *   post:
+ *     summary: Register a new user
+ *     description: Create a new user account with email and password
+ *     tags:
+ *       - Authentication
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - email
+ *               - password
+ *               - name
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *                 example: user@example.com
+ *               password:
+ *                 type: string
+ *                 format: password
+ *                 minLength: 8
+ *                 example: SecurePassword123
+ *               name:
+ *                 type: string
+ *                 example: John Doe
+ *     responses:
+ *       201:
+ *         description: User registered successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *                 message:
+ *                   type: string
+ *                   example: User registered successfully
+ *                 data:
+ *                   type: object
+ *                   properties:
+ *                     id:
+ *                       type: string
+ *                       example: user_123abc
+ *                     email:
+ *                       type: string
+ *                       example: user@example.com
+ *                     token:
+ *                       type: string
+ *                       example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+ *       400:
+ *         description: Validation error or user already exists
+ *       500:
+ *         description: Internal server error
+ */
+router.post("/register", AuthController.register);
+
+/**
+ * @swagger
+ * /api/auth/login:
+ *   post:
+ *     summary: Login user
+ *     description: Authenticate user with email and password
+ *     tags:
+ *       - Authentication
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - email
+ *               - password
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *                 example: user@example.com
+ *               password:
+ *                 type: string
+ *                 format: password
+ *                 example: SecurePassword123
+ *     responses:
+ *       200:
+ *         description: Login successful
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *                 message:
+ *                   type: string
+ *                   example: Login successful
+ *                 data:
+ *                   type: object
+ *                   properties:
+ *                     id:
+ *                       type: string
+ *                       example: user_123abc
+ *                     email:
+ *                       type: string
+ *                       example: user@example.com
+ *                     token:
+ *                       type: string
+ *                       example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+ *       401:
+ *         description: Invalid credentials
+ *       400:
+ *         description: Validation error
+ *       500:
+ *         description: Internal server error
+ */
+router.post("/login", AuthController.login);
+
+export default router;

package/template/js/src/modules/auth/auth.schemas.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { USER_ROLES, AUTH_PROVIDERS } from "./auth.constants.js";
+
+export const emailSchema = z
+  .string()
+  .email("Invalid email address")
+  .toLowerCase();
+
+export const passwordSchema = z
+  .string()
+  .min(8, "Password must be at least 8 characters")
+  .max(72, "Password too long");
+
+export const userSchema = z.object({
+  id: z.string().uuid(),
+  email: emailSchema,
+  name: z.string().min(1).max(100),
+  role: z.enum(USER_ROLES).default("user"),
+  provider: z.enum(AUTH_PROVIDERS).default("credentials"),
+
+  passwordHash: z.string().optional(), // credentials only
+  isEmailVerified: z.boolean().default(false),
+
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+
+export const registerSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  email: emailSchema,
+  password: passwordSchema,
+});
+
+export const loginSchema = z.object({
+  email: emailSchema,
+  password: z.string().min(1, "Password is required"),
+});
+
+export const jwtPayloadSchema = z.object({
+  sub: z.string().uuid(), // user id
+  email: emailSchema,
+  role: z.enum(USER_ROLES),
+});
+
+export const forgotPasswordSchema = z.object({
+  email: emailSchema,
+});
+
+export const resetPasswordSchema = z.object({
+  token: z.string().min(1),
+  newPassword: passwordSchema,
+});
+
+export const publicUserSchema = userSchema.omit({
+  passwordHash: true,
+});
+
+export const validate = (schema, data) => {
+  return schema.parse(data);
+};

package/template/js/src/modules/auth/auth.service.js

@@ -0,0 +1,67 @@
+import bcrypt from "bcryptjs";
+import jwt from "jsonwebtoken";
+import { registerSchema, loginSchema } from "./auth.schemas.js";
+
+const SALT_ROUNDS = 10;
+const JWT_EXPIRES_IN = "7d";
+
+export const AuthService = {
+  async hashPassword(password) {
+    return bcrypt.hash(password, SALT_ROUNDS);
+  },
+
+  async comparePassword(password, hash) {
+    return bcrypt.compare(password, hash);
+  },
+
+  signToken(payload) {
+    return jwt.sign(payload, process.env.JWT_SECRET, {
+      expiresIn: JWT_EXPIRES_IN,
+    });
+  },
+
+  async register(data, userRepo) {
+    const input = registerSchema.parse(data);
+
+    const existingUser = await userRepo.findByEmail(input.email);
+    if (existingUser) {
+      throw new Error("Email already in use");
+    }
+
+    const passwordHash = await this.hashPassword(input.password);
+
+    const user = await userRepo.create({
+      email: input.email,
+      name: input.name,
+      passwordHash,
+    });
+
+    return user;
+  },
+
+  async login(data, userRepo) {
+    const input = loginSchema.parse(data);
+
+    const user = await userRepo.findByEmail(input.email);
+    if (!user || !user.passwordHash) {
+      throw new Error("Invalid credentials");
+    }
+
+    const isValid = await this.comparePassword(
+      input.password,
+      user.passwordHash,
+    );
+
+    if (!isValid) {
+      throw new Error("Invalid credentials");
+    }
+
+    const token = this.signToken({
+      sub: user.id,
+      email: user.email,
+      role: user.role,
+    });
+
+    return { user, token };
+  },
+};

package/template/js/src/modules/auth/package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "bcryptjs": "^3.0.3",
+    "jsonwebtoken": "^9.0.3"
+  }
+}

package/template/js/src/modules/health/controller.js

@@ -3,8 +3,39 @@ import { sendSuccess } from "../../utils/response.js";
 import { asyncHandler } from "../../middlewares/errorHandler.js";
 
 /**
- * Health check endpoint
- * Always returns healthy status (ping endpoint)
+ * @swagger
+ * /api/health:
+ *   get:
+ *     summary: Health check endpoint
+ *     description: Returns the health status of the API
+ *     tags:
+ *       - Health
+ *     responses:
+ *       200:
+ *         description: Service is healthy
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *                 message:
+ *                   type: string
+ *                   example: Service is healthy
+ *                 data:
+ *                   type: object
+ *                   properties:
+ *                     status:
+ *                       type: string
+ *                       example: healthy
+ *                     uptime:
+ *                       type: number
+ *                       example: 123.45
+ *                     timestamp:
+ *                       type: string
+ *                       format: date-time
  */
 export const getHealth = asyncHandler(async (req, res) => {
   sendSuccess(
@@ -30,8 +61,78 @@ export const createItemSchema = z.object({
   }),
 });
 
+/**
+ * @swagger
+ * /api/items:
+ *   post:
+ *     summary: Create a new item
+ *     description: Example endpoint demonstrating validation with Zod
+ *     tags:
+ *       - Items
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - name
+ *             properties:
+ *               name:
+ *                 type: string
+ *                 minLength: 1
+ *                 maxLength: 100
+ *                 example: My Item
+ *               description:
+ *                 type: string
+ *                 example: This is an example item
+ *     responses:
+ *       201:
+ *         description: Item created successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *                 message:
+ *                   type: string
+ *                   example: Item created successfully
+ *                 data:
+ *                   type: object
+ *                   properties:
+ *                     id:
+ *                       type: string
+ *                       example: abc123def
+ *                     name:
+ *                       type: string
+ *                       example: My Item
+ *                     description:
+ *                       type: string
+ *                       nullable: true
+ *                       example: This is an example item
+ *                     createdAt:
+ *                       type: string
+ *                       format: date-time
+ *       400:
+ *         description: Validation error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: false
+ *                 message:
+ *                   type: string
+ *                   example: Validation failed
+ */
 export const createItem = asyncHandler(async (req, res) => {
-  const { name, description } = req.validatedData.body;
+  const parsedData = createItemSchema.parse({ body: req.body });
+  const { name, description } = parsedData.body;
 
   // Simulate some async work
   await new Promise((resolve) => setTimeout(resolve, 10));

package/template/js/src/modules/swagger/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@charcoles/swagger": "file:./charcole-swagger-1.0.0.tgz"
+  }
+}

package/template/js/src/repositories/user.repo.js

@@ -0,0 +1,19 @@
+import { randomUUID } from "crypto";
+
+const users = [];
+
+export const userRepo = {
+  async findByEmail(email) {
+    return users.find((u) => u.email === email);
+  },
+
+  async create(data) {
+    const user = {
+      id: randomUUID(),
+      role: "user",
+      ...data,
+    };
+    users.push(user);
+    return user;
+  },
+};

package/template/js/src/routes/index.js

@@ -0,0 +1,25 @@
+import { Router } from "express";
+import {
+  getHealth,
+  createItem,
+  createItemSchema,
+} from "../modules/health/controller.js";
+import { validateRequest } from "../middlewares/validateRequest.js";
+import { requireAuth } from "../modules/auth/auth.middlewares.js";
+import protectedRoutes from "./protected.js";
+import authRoutes from "../modules/auth/auth.routes.js";
+const router = Router();
+
+// Health check
+router.get("/health", getHealth);
+
+// Example: Create item with validation
+router.post("/items", validateRequest(createItemSchema), createItem);
+
+// 🔐 Auth routes
+router.use("/auth", authRoutes);
+
+// 🔐 Protected routes (REQUIRED BEARER TOKEN FOR THEM)
+router.use("/protected", protectedRoutes);
+
+export default router;

package/template/js/src/routes/protected.js

@@ -0,0 +1,57 @@
+import { Router } from "express";
+import { requireAuth } from "../modules/auth/auth.middlewares.js";
+
+const router = Router();
+
+/**
+ * @swagger
+ * /api/protected/me:
+ *   get:
+ *     summary: Get current user profile
+ *     description: Returns the authenticated user's information
+ *     tags:
+ *       - Protected
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: User profile retrieved successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message:
+ *                   type: string
+ *                   example: You are authenticated
+ *                 user:
+ *                   type: object
+ *                   properties:
+ *                     id:
+ *                       type: string
+ *                       example: user_123abc
+ *                     email:
+ *                       type: string
+ *                       example: user@example.com
+ *       401:
+ *         description: Unauthorized - Invalid or missing token
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 success:
+ *                   type: boolean
+ *                   example: false
+ *                 message:
+ *                   type: string
+ *                   example: Unauthorized
+ */
+router.get("/me", requireAuth, (req, res) => {
+  res.json({
+    message: "You are authenticated",
+    user: req.user,
+  });
+});
+
+export default router;

package/template/ts/.env.example

@@ -1,8 +1,16 @@
+# Server Configuration
 NODE_ENV=development
 PORT=3000
 
+# Logging
 LOG_LEVEL=info
 
+# CORS
 CORS_ORIGIN=*
 
+# Request
 REQUEST_TIMEOUT=30000
+
+
+# Authentication
+JWT_SECRET=your-secret-key-here

package/template/ts/README.md

@@ -8,11 +8,12 @@ Welcome! This guide will help you set up and start using the Charcole API framew
 2. [Project Structure](#project-structure)
 3. [Configuration](#configuration)
 4. [Creating Your First Endpoint](#creating-your-first-endpoint)
-5. [Error Handling](#error-handling)
-6. [Validation](#validation)
-7. [Logging](#logging)
-8. [Running Your API](#running-your-api)
-9. [Troubleshooting](#troubleshooting)
+5. [API Documentation with Swagger](#api-documentation-with-swagger)
+6. [Error Handling](#error-handling)
+7. [Validation](#validation)
+8. [Logging](#logging)
+9. [Running Your API](#running-your-api)
+10. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -396,6 +397,128 @@ router.get("/users/:id", async (req, res) => {
 
 ---
 
+## 📖 API Documentation with Swagger
+
+Your API comes with **automatic interactive documentation** powered by Swagger UI!
+
+### Accessing the Documentation
+
+1. Start your server: `npm run dev`
+2. Visit: **http://localhost:3000/api-docs**
+
+You'll see all your APIs automatically documented and can test them directly from the browser!
+
+### How It Works
+
+All built-in APIs are already documented. When you create new endpoints, simply add JSDoc comments with `@swagger` annotations:
+
+```typescript
+/**
+ * @swagger
+ * /api/users:
+ *   get:
+ *     summary: Get all users
+ *     tags:
+ *       - Users
+ *     responses:
+ *       200:
+ *         description: Success
+ */
+export const getAllUsers = asyncHandler(async (req: Request, res: Response) => {
+  // Your code here
+});
+```
+
+That's it! Your new endpoint will automatically appear in Swagger UI.
+
+### Quick Example: Documenting a POST Endpoint
+
+```typescript
+/**
+ * @swagger
+ * /api/posts:
+ *   post:
+ *     summary: Create a new post
+ *     tags:
+ *       - Posts
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - title
+ *             properties:
+ *               title:
+ *                 type: string
+ *                 example: My First Post
+ *               content:
+ *                 type: string
+ *                 example: This is the post content
+ *     responses:
+ *       201:
+ *         description: Post created successfully
+ *       400:
+ *         description: Validation error
+ */
+export const createPost = asyncHandler(async (req: Request, res: Response) => {
+  // Your implementation
+});
+```
+
+### Protected Endpoints (with Authentication)
+
+For endpoints that require authentication, add the `security` field:
+
+```typescript
+/**
+ * @swagger
+ * /api/profile:
+ *   get:
+ *     summary: Get user profile
+ *     tags:
+ *       - Profile
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: Profile retrieved
+ *       401:
+ *         description: Unauthorized
+ */
+router.get("/profile", requireAuth, getProfile);
+```
+
+### 📘 Complete Guide
+
+For comprehensive examples including:
+
+- Path and query parameters
+- File uploads
+- Complex schemas
+- Error responses
+- CRUD operations
+
+See the **[Complete Swagger Documentation Guide](src/lib/swagger/SWAGGER_GUIDE.md)**
+
+### Testing APIs in Swagger UI
+
+1. Open http://localhost:3000/api-docs
+2. Click on any endpoint to expand it
+3. Click "Try it out"
+4. Fill in the parameters
+5. Click "Execute"
+6. See the response!
+
+For protected endpoints:
+
+1. Click the "Authorize" button at the top
+2. Enter your JWT token
+3. Now you can test protected endpoints
+
+---
+
 ## ✔️ Validation
 
 ### Zod Schema Basics