nodejs-quickstart-structure 2.1.2 → 2.2.1

package/templates/clean-architecture/ts/src/infrastructure/repositories/userRepository.ts.ejs

@@ -3,87 +3,74 @@ import UserModel from '@/infrastructure/database/models/User';
 
 export class UserRepository {
     async save(user: UserEntity): Promise<UserEntity> {
+        const userData = {
+            name: user.name,
+            email: user.email,
+            <% if (auth.includes('JWT')) { %>password: user.password,<% } %>
+            <% if (typeof socialAuth !== 'undefined' && socialAuth && socialAuth.includes('Google')) { %>googleId: user.googleId,<% } %>
+            <% if (typeof socialAuth !== 'undefined' && socialAuth && socialAuth.includes('GitHub')) { %>githubId: user.githubId,<% } %>
+        };
+
 <%_ if (database === 'MongoDB') { -%>
-        const newUser = await UserModel.create({ 
-            name: user.name, 
-            email: user.email, 
-            <% if (auth.includes('JWT')) { %>password: user.password<% } %> 
-        });
-        return { id: newUser._id.toString(), name: newUser.name, email: newUser.email };
+        const newUser = await UserModel.create(userData);
+        return this.mapToEntity(newUser);
 <%_ } else if (database === 'None') { -%>
-        const newUser = await UserModel.create({ 
-            name: user.name, 
-            email: user.email,
-            <% if (auth.includes('JWT')) { %>password: user.password<% } %>
-        });
-        return { id: newUser.id, name: newUser.name, email: newUser.email };
+        const newUser = await UserModel.create(userData);
+        return this.mapToEntity(newUser);
 <%_ } else { -%>
-        const newUser = await UserModel.create({ 
-            name: user.name, 
-            email: user.email,
-            <% if (auth.includes('JWT')) { %>password: user.password<% } %>
-        });
-        return { id: newUser.id, name: newUser.name, email: newUser.email };
+        const newUser = await UserModel.create(userData);
+        return this.mapToEntity(newUser);
 <%_ } -%>
     }
 
     async findById(id: number | string): Promise<UserEntity | null> {
 <%_ if (database === 'MongoDB') { -%>
         const user = await UserModel.findById(id);
-        if (!user) return null;
-        return { id: user._id.toString(), name: user.name, email: user.email };
-<%_ } else if (database === 'None') { -%>
-        const user = await UserModel.findByPk(id);
-        if (!user) return null;
-        return { id: user.id, name: user.name, email: user.email };
 <%_ } else { -%>
         const user = await UserModel.findByPk(id);
-        if (!user) return null;
-        return { id: user.id, name: user.name, email: user.email };
 <%_ } -%>
+        if (!user) return null;
+        return this.mapToEntity(user);
     }
 
+    async findByEmail(email: string): Promise<UserEntity | null> {
+<%_ if (database === 'MongoDB') { -%>
+        const user = await UserModel.findOne({ email });
+<%_ } else if (database === 'None') { -%>
+        const user = await UserModel.findOne({ email });
+<%_ } else { -%>
+        const user = await UserModel.findOne({ where: { email } });
+<%_ } -%>
+        if (!user) return null;
+        return this.mapToEntity(user);
+    }
 
     async getUsers(): Promise<UserEntity[]> {
 <%_ if (database === 'MongoDB') { -%>
         const users = await UserModel.find();
-        return users.map(user => ({
-            id: user._id.toString(),
-            name: user.name,
-            email: user.email
-        }));
 <%_ } else if (database === 'None') { -%>
         const users = await UserModel.find();
-        return users.map(user => ({
-            id: user.id,
-            name: user.name,
-            email: user.email
-        }));
 <%_ } else { -%>
         const users = await UserModel.findAll();
-        return users.map(user => ({
-            id: user.id,
-            name: user.name,
-            email: user.email
-        }));
 <%_ } -%>
+        return users.map(user => this.mapToEntity(user));
     }
 
     async update(id: number | string, data: Partial<UserEntity>): Promise<UserEntity | null> {
 <%_ if (database === 'MongoDB') { -%>
         const user = await UserModel.findByIdAndUpdate(id, data, { new: true });
         if (!user) return null;
-        return { id: user._id.toString(), name: user.name, email: user.email };
+        return this.mapToEntity(user);
 <%_ } else if (database === 'None') { -%>
         const { id: _, ...updateData } = data;
-        const user = await UserModel.update(id, updateData as Parameters<typeof UserModel.update>[1]);
+        const user = await UserModel.update(id, updateData as Record<string, unknown>);
         if (!user) return null;
-        return { id: user.id, name: user.name, email: user.email };
+        return this.mapToEntity(user);
 <%_ } else { -%>
         const user = await UserModel.findByPk(id);
         if (!user) return null;
         await user.update(data);
-        return { id: user.id || 0, name: user.name, email: user.email };
+        return this.mapToEntity(user);
 <%_ } -%>
     }
 
@@ -100,4 +87,15 @@ export class UserRepository {
         return true;
 <%_ } -%>
     }
+
+    private mapToEntity(user: { id?: string | number; _id?: { toString(): string }; name: string; email: string; password?: string | null; googleId?: string | null; githubId?: string | null }): UserEntity {
+        return {
+            id: user.id || user._id?.toString(),
+            name: user.name,
+            email: user.email,
+            password: user.password,
+            <% if (typeof socialAuth !== 'undefined' && socialAuth && socialAuth.includes('Google')) { %>googleId: user.googleId,<% } %>
+            <% if (typeof socialAuth !== 'undefined' && socialAuth && socialAuth.includes('GitHub')) { %>githubId: user.githubId,<% } %>
+        } as UserEntity;
+    }
 }

package/templates/clean-architecture/ts/src/interfaces/graphql/resolvers/user.resolvers.ts.ejs

@@ -25,15 +25,15 @@ export const userResolvers = {
       const user = await userController.updateUser(id, { name, email });
       return user;
     },
-    deleteUser: async (_: unknown, { id }: { id: string }, <% if (auth.includes('JWT')) { %>context<% } else { %>_context<% } %>: MyContext) => {
-      <%_ if (auth.includes('JWT')) { -%>
+    deleteUser: async (_: unknown, { id }: { id: string }, <%_ if (auth.includes('JWT')) { _%>context<%_ } else { _%>_context<%_ } _%>: MyContext) => {
+      <%_ if (auth.includes('JWT')) { _%>
       if (!context.user) throw new Error('Unauthorized');
-      <% } %>
+      <%_ } _%>
       const result = await userController.deleteUser(id);
       return result;
     }
-  }<%_ if (database === 'MongoDB') { -%>,
+  }<%_ if (database === 'MongoDB') { _%>,
   User: {
     id: (parent: { id?: string; _id?: unknown }) => parent.id || parent._id
-  }<%_ } %>
+  }<%_ } _%>
 };

package/templates/clean-architecture/ts/src/utils/httpCodes.ts

@@ -3,6 +3,7 @@ export const HTTP_STATUS = {
     CREATED: 201,
     BAD_REQUEST: 400,
     UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
     NOT_FOUND: 404,
     INTERNAL_SERVER_ERROR: 500
 } as const;

package/templates/common/.env.example.ejs

@@ -45,4 +45,14 @@ JWT_SECRET=your_jwt_secret_key_here_change_it
 JWT_REFRESH_SECRET=your_jwt_refresh_secret_key_here_change_it
 JWT_EXPIRES_IN=15m
 JWT_REFRESH_EXPIRES_IN=7d
+<%_ if (socialAuth && socialAuth.includes('Google')) { -%>
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback
+<%_ } -%>
+<%_ if (socialAuth && socialAuth.includes('GitHub')) { -%>
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+GITHUB_CALLBACK_URL=http://localhost:3000/api/auth/github/callback
+<%_ } -%>
 <% } -%>

package/templates/common/README.md.ejs

@@ -13,7 +13,7 @@ This project follows a strict **7-Step Production-Ready Process** to ensure qual
 
 ---
 
-## 🚀 7-Step Production-Ready Process
+## 7-Step Production-Ready Process
 
 1.  **Initialize Git**: `git init` (Required for Husky hooks and security gates).
 2.  **Install Dependencies**: `npm install`.
@@ -25,7 +25,7 @@ This project follows a strict **7-Step Production-Ready Process** to ensure qual
 
 ---
 
-## 🚀 Key Features
+## Key Features
 
 -   **Architecture**: <%= architecture %> (<% if (architecture === 'Clean Architecture') { %>Domain, UseCases, Infrastructure<% } else { %>MVC Pattern<% } %>).
 -   **Database**: <%= database %> <% if (database !== 'None') { %>(via <%= database === 'MongoDB' ? 'Mongoose' : 'Sequelize' %>)<% } %>.
@@ -157,20 +157,71 @@ API is exposed via **REST**.
 A Swagger UI for API documentation is available at:
 - **URL**: `http://localhost:3000/api-docs` (Dynamic based on PORT)
 
-### 🛣️ User Endpoints:
+### User Endpoints:
 - `GET /api/users`: List all users.
 - `GET /api/users/:id`: Get a user by ID.
 - `POST /api/users`: Create a new user.
 - `PATCH /api/users/:id`: Partially update a user.
 - `DELETE /api/users/:id`: Delete a user (Soft Delete).
 <%_ if (auth.includes('JWT')) { %>
-### 🔐 Auth Endpoints:
+### Auth Endpoints:
 - `POST /api/auth/login`: Exchange credentials for a short-lived `accessToken` and a long-lived `refreshToken`.
 - `POST /api/auth/refresh`: Submit a `refreshToken` to receive a new pair of tokens. (Includes theft-detection logic).
 - `POST /api/auth/logout`: Revoke (blacklist) the active `accessToken` and delete the `refreshToken`.
 - `POST /api/users`: Acts as Sign Up when password is provided.
+<%_ if (socialAuth && socialAuth.filter(a => a !== 'None').length > 0) { _%>
+### Social Authentication Flows
+
+This project supports two distinct social authentication flows:
+
+#### 1. The Redirection Flow (Best for MVC/Web)
+Standard OAuth2 flow using browser redirects.
+- **Start**: `GET /api/auth/google` (or `/github`)
+- **Callback**: Handled automatically by the backend via `/google/callback`.
+- **Result**: User is logged in and redirected to home; `accessToken` and `refreshToken` are securely saved as **HttpOnly cookies** in the browser.
+- **Callback URL**: `http://localhost:3000/api/auth/google/callback` (Standardized for both MVC and Clean Architecture).
+
+  > [!TIP]
+  > **Testing in Swagger**: The "Execute" button in Swagger UI will show a "Failed to fetch" error for this route because browsers block redirects to external domains (like Google) inside AJAX requests. To test this, simply open `http://localhost:3000/api/auth/google` directly in your browser tab.
+
+#### 2. The Exchange Flow (Best for SPAs/Mobile Apps)
+A headless flow where the client provides the OAuth code.
+- **API**: `POST /api/auth/social/exchange`
+- **Body**: `{ "code": "AUTH_CODE", "provider": "Google" }`
+- **Result**: Returns JWT tokens (`accessToken`, `refreshToken`) in the JSON response.
+
+---
+<%_ } _%>
   *Note: To access protected user endpoints (GET/PATCH/DELETE), include `Authorization: Bearer <your_accessToken>` in the headers.*
 <% } -%>
+<% if (socialAuth && socialAuth.filter(a => a !== 'None').length > 0) { -%>
+### Social Authentication Setup
+To use social login, you must configure the following in your `.env`:
+
+#### Callback URL Configuration
+For the best practice standardized API structure, you **must** configure the Redirect URIs in your developer portals (Google/GitHub) as follows:
+
+| Provider | Redirect URI (Callback URL) |
+| :--- | :--- |
+| **Google** | `http://localhost:3000/api/auth/google/callback` |
+| **GitHub** | `http://localhost:3000/api/auth/github/callback` |
+
+> [!IMPORTANT]
+> This standardized path works for both **MVC** and **Clean Architecture** templates.
+
+#### <% if (socialAuth.includes('Google')) { %>1. Google Integration<% } %>
+1. Go to [Google Cloud Console](https://console.cloud.google.com/).
+2. Create/Select a project and go to **APIs & Services > Credentials**.
+3. Create an **OAuth client ID** for a **Web application**.
+4. Add Redirect URI: `http://localhost:3000/api/auth/google/callback`.
+5. Set `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and `GOOGLE_CALLBACK_URL` in `.env`.
+
+#### <% if (socialAuth.includes('GitHub')) { %>2. GitHub Integration<% } %>
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers).
+2. Register a **New OAuth App**.
+3. Set Callback URL: `http://localhost:3000/api/auth/github/callback`.
+4. Set `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and `GITHUB_CALLBACK_URL` in `.env`.
+<% } -%>
 <% } -%>
 <% if (communication === 'Kafka') { -%>
 ## 📡 Testing Kafka Asynchronous Flow
@@ -212,10 +263,10 @@ curl -X PATCH http://localhost:3000/api/users/1 \
 ```text
 [Kafka] Producer: Sent USER_CREATED event for 'kafka@example.com'
 [Kafka] Consumer: Received USER_CREATED. 
-[Kafka] Consumer: 📧 Sending welcome email to 'kafka@example.com'... Done!
+[Kafka] Consumer: Sending welcome email to 'kafka@example.com'... Done!
 ```
 
-### 🛠️ Kafka Troubleshooting
+### Kafka Troubleshooting
 If the connection or events are failing:
 1. **Check Docker**: Ensure Kafka container is running (`docker ps`).
 2. **Verify Broker**: `KAFKA_BROKER` in `.env` must match your host/port (standard: 9093).
@@ -224,24 +275,24 @@ If the connection or events are failing:
 <% } -%>
 
 <% if (caching === 'Redis') { -%>
-## ⚡ Caching
+## Caching
 This project uses **Redis** for caching.
 - **Client**: `ioredis`
 - **Connection**: Configured via `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD` in `.env`.
 <% } else if (caching === 'Memory Cache') { -%>
-## ⚡ Caching
+## Caching
 This project uses **Memory Cache** for in-memory caching.
 - **Client**: `node-cache`
 <% } -%>
 
-## 📝 Logging
+## Logging
 This project uses **Winston** for structured logging.
 - **Development**: Logs are printed to the console.
 - **Production**: Logs are saved to files:
   - `error.log`: Only error level logs.
   - `combined.log`: All logs.
 
-## 🐳 Docker Deployment
+## Docker Deployment
 This project uses a **Multi-Stage Dockerfile** for optimized production images.
 
 <% if (database !== 'None' || caching === 'Redis' || communication === 'Kafka') { -%>
@@ -288,7 +339,7 @@ docker build -t <%= projectName %> .
 docker run -p 3000:3000 <%= projectName %>
 ```
 <% } -%>
-## 🚀 PM2 Deployment (VPS/EC2)
+## PM2 Deployment (VPS/EC2)
 This project is pre-configured for direct deployment to a VPS/EC2 instance using **PM2** (via `ecosystem.config.js`).
 1. Install dependencies
 ```bash
@@ -324,17 +375,17 @@ docker-compose down
 -   **Rate Limiting**: Protects against DDoS / Brute-force.
 -   **HPP**: Prevents HTTP Parameter Pollution attacks.
 <% if (includeSecurity) { %>
-### 🛡️ Enterprise Hardening (Big Tech Standard)
+### Enterprise Hardening (Big Tech Standard)
 -   **Snyk SCA**: Run `npm run snyk:test` for dependency scanning.
 -   **SonarCloud**: Automated SAST on every Push/PR.
 -   **Digital Guardians**: Recommended Gitleaks integration for secret protection.
 -   **Security Policy**: Standard `SECURITY.md` for vulnerability reporting.
 <% } %>
-## 🤖 AI-Native Development
+## AI-Native Development
 
 This project is "AI-Ready" out of the box. We have pre-configured industry-leading AI context files to bridge the gap between "Generated Code" and "AI-Assisted Development."
 
 - **Magic Defaults**: We've automatically tailored your AI context to focus on **<%= projectName %>** and its specific architectural stack (<%= architecture %>, <%= database %>, etc.).
 - **Use Cursor?** We've configured **`.cursorrules`** at the root. It enforces project standards (80% coverage, MVC/Clean) directly within the editor. 
-  - *Pro-tip*: You can customize the `Project Goal` placeholder in `.cursorrules` to help the AI understand your specific business logic!
+- *Pro-tip*: You can customize the `Project Goal` placeholder in `.cursorrules` to help the AI understand your specific business logic!
 - **Use ChatGPT/Gemini/Claude?** Check the **`prompts/`** directory. It contains highly-specialized Agent Skill templates. You can copy-paste these into any LLM to give it a "Senior Developer" understanding of your codebase immediately.