webortex-auth 1.0.3 → 1.1.0

package/CUSTOM_USER_MODEL.md

@@ -0,0 +1,303 @@
+# Custom User Model Guide
+
+This guide shows you how to extend the default User model with your own custom fields.
+
+## Method 1: Using `createCustomUserModel` Helper
+
+The easiest way to add custom fields to the User model.
+
+### Example: Adding Phone Number and Role
+
+```javascript
+import express from 'express';
+import mongoose from 'mongoose';
+import { authRoutes, createCustomUserModel } from 'webortex-auth';
+
+const app = express();
+app.use(express.json());
+
+// Connect to MongoDB
+await mongoose.connect(process.env.MONGO_URI);
+
+// Create custom User model with additional fields
+const CustomUser = createCustomUserModel(mongoose, {
+  phone: {
+    type: String,
+    required: false,
+  },
+  role: {
+    type: String,
+    enum: ['user', 'admin', 'moderator'],
+    default: 'user',
+  },
+  isVerified: {
+    type: Boolean,
+    default: false,
+  },
+  profilePicture: {
+    type: String,
+    default: null,
+  },
+});
+
+// Use auth routes with custom User model
+app.use('/api/auth', authRoutes(mongoose, CustomUser));
+
+app.listen(3000);
+```
+
+### Signup Request with Custom Fields
+
+```bash
+curl -X POST http://localhost:3000/api/auth/signup \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John Doe",
+    "email": "john@example.com",
+    "password": "securePass123",
+    "phone": "+1234567890",
+    "role": "admin"
+  }'
+```
+
+---
+
+## Method 2: Creating Your Own Model from Scratch
+
+For complete control, create your own User model.
+
+### Example: Fully Custom User Model
+
+```javascript
+import mongoose from 'mongoose';
+import bcrypt from 'bcryptjs';
+import { authRoutes } from 'webortex-auth';
+
+// Create your own User schema
+const userSchema = new mongoose.Schema({
+  // Required fields for authentication
+  name: {
+    type: String,
+    required: true,
+  },
+  email: {
+    type: String,
+    required: true,
+    unique: true,
+    lowercase: true,
+  },
+  password: {
+    type: String,
+    required: true,
+    select: false,
+  },
+  
+  // Your custom fields
+  company: {
+    type: String,
+    required: true,
+  },
+  department: String,
+  employeeId: {
+    type: String,
+    unique: true,
+  },
+  permissions: [{
+    type: String,
+  }],
+}, {
+  timestamps: true,
+});
+
+// IMPORTANT: Add password hashing middleware
+userSchema.pre('save', async function () {
+  if (!this.isModified('password')) return;
+  
+  const salt = await bcrypt.genSalt(10);
+  this.password = await bcrypt.hash(this.password, salt);
+});
+
+// IMPORTANT: Add password comparison method
+userSchema.methods.comparePassword = async function (candidatePassword) {
+  return await bcrypt.compare(candidatePassword, this.password);
+};
+
+// Create model
+const CustomUser = mongoose.model('User', userSchema);
+
+// Use with auth routes
+app.use('/api/auth', authRoutes(mongoose, CustomUser));
+```
+
+---
+
+## Method 3: Extending with Schema Options
+
+Add schema options like virtuals, indexes, etc.
+
+```javascript
+import { createCustomUserModel } from 'webortex-auth';
+
+const CustomUser = createCustomUserModel(
+  mongoose,
+  // Additional fields
+  {
+    firstName: String,
+    lastName: String,
+    dateOfBirth: Date,
+    address: {
+      street: String,
+      city: String,
+      country: String,
+      zipCode: String,
+    },
+  },
+  // Schema options
+  {
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+// Add virtual field
+CustomUser.schema.virtual('fullName').get(function () {
+  return `${this.firstName} ${this.lastName}`;
+});
+
+// Add index
+CustomUser.schema.index({ email: 1, dateOfBirth: 1 });
+
+app.use('/api/auth', authRoutes(mongoose, CustomUser));
+```
+
+---
+
+## Important Requirements
+
+When creating a custom User model, ensure it has:
+
+### Required Fields
+- ✅ `name` (String)
+- ✅ `email` (String, unique)
+- ✅ `password` (String, with `select: false`)
+
+### Required Methods
+- ✅ `comparePassword(candidatePassword)` - Returns Promise<boolean>
+
+### Required Middleware
+- ✅ Pre-save hook to hash password with bcrypt
+
+---
+
+## Using Custom User Model in Your App
+
+After setting up a custom User model, you can use it anywhere:
+
+```javascript
+import { createCustomUserModel } from 'webortex-auth';
+
+// Create the model
+const User = createCustomUserModel(mongoose, {
+  role: { type: String, default: 'user' },
+});
+
+// Use it in your routes
+app.get('/api/users', async (req, res) => {
+  const users = await User.find().select('-password');
+  res.json(users);
+});
+
+app.get('/api/users/:id', async (req, res) => {
+  const user = await User.findById(req.params.id);
+  res.json(user);
+});
+
+app.patch('/api/users/:id', async (req, res) => {
+  const user = await User.findByIdAndUpdate(
+    req.params.id,
+    req.body,
+    { new: true }
+  );
+  res.json(user);
+});
+```
+
+---
+
+## Complete Example
+
+```javascript
+import express from 'express';
+import mongoose from 'mongoose';
+import dotenv from 'dotenv';
+import { authRoutes, createCustomUserModel } from 'webortex-auth';
+
+dotenv.config();
+
+const app = express();
+app.use(express.json());
+
+// Connect to MongoDB
+await mongoose.connect(process.env.MONGO_URI);
+
+// Create custom User model
+const User = createCustomUserModel(mongoose, {
+  phone: String,
+  role: {
+    type: String,
+    enum: ['user', 'admin'],
+    default: 'user',
+  },
+  avatar: String,
+  bio: String,
+  socialLinks: {
+    twitter: String,
+    linkedin: String,
+    github: String,
+  },
+  preferences: {
+    newsletter: { type: Boolean, default: true },
+    notifications: { type: Boolean, default: true },
+  },
+});
+
+// Auth routes
+app.use('/api/auth', authRoutes(mongoose, User));
+
+// Custom user routes
+app.get('/api/users/me', async (req, res) => {
+  // Assuming you have auth middleware that sets req.userId
+  const user = await User.findById(req.userId);
+  res.json(user);
+});
+
+app.patch('/api/users/me', async (req, res) => {
+  const user = await User.findByIdAndUpdate(
+    req.userId,
+    { $set: req.body },
+    { new: true, runValidators: true }
+  );
+  res.json(user);
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+---
+
+## Tips
+
+1. **Don't modify password field** - The package handles password hashing automatically
+2. **Use select: false for sensitive fields** - Like the password field
+3. **Add validation** - Use Mongoose validators for your custom fields
+4. **Create indexes** - For fields you'll query frequently
+5. **Use virtuals** - For computed properties
+6. **Keep it simple** - Start with basic fields and add more as needed
+
+---
+
+## Need Help?
+
+If you have questions about custom User models, please open an issue on GitHub!

package/README.md

@@ -12,6 +12,7 @@ A production-ready, reusable authentication package for Node.js applications usi
 - 🎯 **Type Safe** - Clean API with factory functions
 - 🔄 **Reusable** - Use across multiple projects
 - 🛡️ **Production Ready** - Comprehensive error handling
+- 🎨 **Customizable** - Extend User model with your own fields
 
 ## 📦 Installation
 
@@ -243,6 +244,30 @@ app.use('/api/auth/login', limiter);
 app.use('/api/auth', authRoutes(mongoose));
 ```
 
+### Custom User Model
+
+Extend the default User model with your own fields:
+
+```javascript
+import { authRoutes, createCustomUserModel } from 'webortex-auth';
+
+// Create custom User model with additional fields
+const CustomUser = createCustomUserModel(mongoose, {
+  phone: String,
+  role: {
+    type: String,
+    enum: ['user', 'admin'],
+    default: 'user',
+  },
+  avatar: String,
+});
+
+// Use with auth routes
+app.use('/api/auth', authRoutes(mongoose, CustomUser));
+```
+
+**📖 For detailed examples, see [CUSTOM_USER_MODEL.md](CUSTOM_USER_MODEL.md)**
+
 ## ⚠️ Common Errors & Fixes
 
 ### Error: `buffering timed out after 10000ms`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webortex-auth",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Reusable authentication package for Express + MongoDB with dependency injection",
   "type": "module",
   "main": "./src/index.js",

package/src/controllers/auth.controller.js

@@ -4,10 +4,11 @@ import { createUserModel } from '../models/User.model.js';
 /**
  * Creates authentication controllers with injected mongoose instance
  * @param {Object} mongoose - Connected mongoose instance from consuming app
+ * @param {Model} [customUserModel] - Optional custom User model (if not provided, uses default)
  * @returns {Object} Authentication controllers (signup, login)
  */
-export const createAuthController = (mongoose) => {
-    const User = createUserModel(mongoose);
+export const createAuthController = (mongoose, customUserModel = null) => {
+    const User = customUserModel || createUserModel(mongoose);
 
     /**
      * Signup Controller

package/src/index.js

@@ -6,4 +6,4 @@
  */
 
 export { createAuthRoutes as authRoutes } from './routes/auth.routes.js';
-export { createUserModel } from './models/User.model.js';
+export { createUserModel, createCustomUserModel } from './models/User.model.js';

package/src/models/User.model.js

@@ -1,43 +1,53 @@
 import bcrypt from 'bcryptjs';
 
 /**
- * Creates User model with injected mongoose instance
- * @param {Object} mongoose - Connected mongoose instance from consuming app
- * @returns {Model} User model
+ * Creates a custom User model by extending the base schema
+ * @param {Object} mongoose - Connected mongoose instance
+ * @param {Object} additionalFields - Additional schema fields to add
+ * @param {Object} [schemaOptions] - Additional schema options
+ * @returns {Model} Extended User model
  */
-export const createUserModel = (mongoose) => {
+export const createCustomUserModel = (mongoose, additionalFields = {}, schemaOptions = {}) => {
   // Prevent model recompilation error
   if (mongoose.models.User) {
     return mongoose.models.User;
   }
 
-  const userSchema = new mongoose.Schema(
-    {
-      name: {
-        type: String,
-        required: [true, 'Name is required'],
-        trim: true,
-      },
-      email: {
-        type: String,
-        required: [true, 'Email is required'],
-        unique: true,
-        lowercase: true,
-        trim: true,
-        match: [
-          /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/,
-          'Please provide a valid email',
-        ],
-      },
-      password: {
-        type: String,
-        required: [true, 'Password is required'],
-        minlength: [6, 'Password must be at least 6 characters'],
-        select: false, // Don't return password by default
-      },
+  // Base user fields
+  const baseFields = {
+    name: {
+      type: String,
+      required: [true, 'Name is required'],
+      trim: true,
+    },
+    email: {
+      type: String,
+      required: [true, 'Email is required'],
+      unique: true,
+      lowercase: true,
+      trim: true,
+      match: [
+        /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/,
+        'Please provide a valid email',
+      ],
+    },
+    password: {
+      type: String,
+      required: [true, 'Password is required'],
+      minlength: [6, 'Password must be at least 6 characters'],
+      select: false, // Don't return password by default
     },
+  };
+
+  // Merge base fields with additional fields
+  const schemaFields = { ...baseFields, ...additionalFields };
+
+  // Create schema with merged fields
+  const userSchema = new mongoose.Schema(
+    schemaFields,
     {
       timestamps: true,
+      ...schemaOptions,
     }
   );
 
@@ -63,3 +73,12 @@ export const createUserModel = (mongoose) => {
 
   return mongoose.model('User', userSchema);
 };
+
+/**
+ * Creates User model with injected mongoose instance
+ * @param {Object} mongoose - Connected mongoose instance from consuming app
+ * @returns {Model} User model
+ */
+export const createUserModel = (mongoose) => {
+  return createCustomUserModel(mongoose);
+};

package/src/routes/auth.routes.js

@@ -4,11 +4,12 @@ import { createAuthController } from '../controllers/auth.controller.js';
 /**
  * Creates authentication routes with injected mongoose instance
  * @param {Object} mongoose - Connected mongoose instance from consuming app
+ * @param {Model} [customUserModel] - Optional custom User model (if not provided, uses default)
  * @returns {Router} Express router with auth routes
  */
-export const createAuthRoutes = (mongoose) => {
+export const createAuthRoutes = (mongoose, customUserModel = null) => {
     const router = express.Router();
-    const { signup, login } = createAuthController(mongoose);
+    const { signup, login } = createAuthController(mongoose, customUserModel);
 
     // POST /signup - Register new user
     router.post('/signup', signup);