@fecommunity/reactpress-server 1.0.4-beta.0 → 3.0.0

package/README.md

@@ -1,395 +1,366 @@
 # @fecommunity/reactpress-server
 
-NestJS-based backend API server for ReactPress - A modern React-based CMS platform.
+ReactPress Server - NestJS 10 backend API for ReactPress CMS with simple installation.
 
-## Installation
+[![NPM Version](https://img.shields.io/npm/v/@fecommunity/reactpress-server.svg)](https://www.npmjs.com/package/@fecommunity/reactpress-server)
+[![License](https://img.shields.io/npm/l/@fecommunity/reactpress-server.svg)](https://github.com/fecommunity/reactpress/blob/master/server/LICENSE)
+[![Node Version](https://img.shields.io/node/v/@fecommunity/reactpress-server.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![NestJS](https://img.shields.io/badge/NestJS-10-red)](https://nestjs.com/)
 
-```bash
-# For new projects
-npm install @fecommunity/reactpress-server @fecommunity/reactpress-config
-
-# Using yarn
-yarn add @fecommunity/reactpress-server @fecommunity/reactpress-config
-
-# Using pnpm in workspace root (add -w flag)
-pnpm add -w @fecommunity/reactpress-server @fecommunity/reactpress-config
-
-# Using pnpm in standalone project
-pnpm add @fecommunity/reactpress-server @fecommunity/reactpress-config
-```
+## Overview
 
-## Features
+ReactPress Server is a backend API built with NestJS 10 that powers the ReactPress CMS platform. It provides RESTful APIs for content management, user authentication, media handling, and more. With its simple installation process, it offers a smooth setup experience.
 
-- 🚀 **NestJS Framework** - Built on modern, scalable Node.js framework
-- 🔐 **Authentication & Authorization** - JWT-based auth with role management
-- 📝 **Content Management** - Full CRUD for articles, categories, tags, and comments
-- 🗃️ **Database Integration** - MySQL support with TypeORM
-- 📁 **File Upload** - Local and cloud storage support (Ali OSS)
-- 🌍 **Internationalization** - Multi-language support
-- 📚 **API Documentation** - Auto-generated Swagger docs
-- 🔒 **Security** - Rate limiting, CORS, Helmet integration
+The server is built with a modular architecture following NestJS best practices, making it extensible and maintainable. It automatically generates OpenAPI/Swagger documentation that powers the [ReactPress Toolkit](../toolkit).
 
 ## Quick Start
 
-### 1. Initialize Server
+### Installation & Setup
 
 ```bash
-# Using npx (recommended for first-time use)
-npx @fecommunity/reactpress-server init
+# Regular startup
+npx @fecommunity/reactpress-server
 
-# Or if installed globally
-reactpress-server init
+# PM2 startup for production
+npx @fecommunity/reactpress-server --pm2
 ```
 
-This will create configuration files and set up your environment.
-
-### 2. Start Development Server
-
-```bash
-# Using npx
-npx @fecommunity/reactpress-server dev
-
-# Or if installed globally
-reactpress-server dev
-```
+That's it! The command will automatically:
 
-The server will start on `http://localhost:3002` with API documentation at `http://localhost:3002/api`.
+1. **Auto-detect** if configuration exists
+2. **Launch installation wizard** in your browser if no configuration found
+3. **Start the server** immediately after installation
+4. **Open API documentation** at `http://localhost:3002/api`
 
-### 3. Start Production Server
+## Features
 
+- 🚀 **Simple Installation** - No complex CLI parameters needed
+- 🔧 **Auto-Configuration** - Generates `.env` files automatically
+- 🔌 **Database Setup** - Creates MySQL database with migrations
+- 🎯 **Seamless Flow** - From installation to running server
+- 📖 **Auto-Documentation** - Swagger API docs available immediately
+- ⚡ **PM2 Support** - Optional PM2 process management
+- 🔐 **Security** - JWT with refresh token rotation, rate limiting
+- 🛡️ **Protection** - Helmet.js, CSRF protection, input validation
+- 📱 **Responsive APIs** - Mobile-friendly RESTful endpoints
+- 🌐 **Globalization** - Multi-language support
+- 📊 **Analytics Tracking** - Built-in view and visitor analytics
+- 🔄 **Data Synchronization** - Scheduled tasks and webhook support
+
+## Requirements
+
+- Node.js >= 18.20.4
+- MySQL 8.0+ or PostgreSQL 13+
+- npm or pnpm package manager
+
+## Usage Scenarios
+
+### Standalone API Server
+Perfect for:
+- Headless CMS implementation
+- Mobile app backend
+- Microservices architecture
+- Custom frontend integration
+- Enterprise API gateway
+
+### Full ReactPress Stack
+Use with ReactPress client for complete CMS solution:
 ```bash
-# Using npx
-npx @fecommunity/reactpress-server start
+# Start server
+npx @fecommunity/reactpress-server
 
-# Or if installed globally
-reactpress-server start
+# In another terminal, start client
+npx @fecommunity/reactpress-client
 ```
 
-## CLI Commands
+## API Modules
 
-The package includes a powerful CLI for server management:
+ReactPress Server provides comprehensive API modules:
 
-### Initialize Project
-```bash
-# Using npx (recommended)
-npx @fecommunity/reactpress-server init [options]
-
-# Or if installed globally
-reactpress-server init [options]
-
-Options:
-  -p, --port <port>     Server port (default: 3002)
-  --api-prefix <prefix> API prefix (default: /api)
-  --db-host <host>      Database host (default: localhost)
-  --db-port <port>      Database port (default: 3306)
-  --db-name <name>      Database name (default: reactpress)
-```
-
-### Development Mode
-```bash
-# Using npx
-npx @fecommunity/reactpress-server dev [options]
+- **Article Management** - Create, read, update, delete articles with versioning
+- **User Authentication** - Registration, login, password management, 2FA
+- **Comment System** - Comment moderation and management with spam detection
+- **Media Management** - File upload and management (local/S3/Cloudinary)
+- **Category & Tag** - Content organization systems with hierarchy
+- **Page Management** - Custom page creation with templates
+- **Settings** - System configuration management with environment overrides
+- **SMTP** - Email sending capabilities with template system
+- **Search** - Full-text search functionality with Elasticsearch integration
+- **Analytics** - Visitor and view tracking with export capabilities
+- **Webhooks** - Event-driven integrations with external services
+- **Scheduled Tasks** - Cron jobs for automated operations
 
-# Or if installed globally
-reactpress-server dev [options]
+## PM2 Support
 
-Options:
-  -p, --port <port>     Server port (default: 3002)
-  --no-open            Don't open browser automatically
-```
+ReactPress server supports PM2 process management for production deployments:
 
-### Production Mode
 ```bash
-# Using npx
-npx @fecommunity/reactpress-server start [options]
-
-# Or if installed globally
-reactpress-server start [options]
-
-Options:
-  -p, --port <port>     Server port (default: 3002)
+# Start with PM2
+npx @fecommunity/reactpress-server --pm2
 ```
 
-### Build Project
-```bash
-# Using npx
-npx @fecommunity/reactpress-server build
+PM2 features:
+- Automatic process restart on crash
+- Memory monitoring
+- Log management with rotation
+- Process management
+- Health checks
 
-# Or if installed globally
-reactpress-server build
-```
-
-## Environment Configuration
+## Configuration
 
-Create a `.env` file in your project root:
+The installation wizard will create a `.env` file with:
 
 ```env
-# Server Configuration
-SERVER_PORT=3002
-SERVER_API_PREFIX=/api
-NODE_ENV=development
-
-# Database Configuration
-DB_HOST=localhost
+# Database Configuration (Production)
+DB_HOST=prod-db.cluster-xyz.amazonaws.com
 DB_PORT=3306
-DB_USERNAME=root
-DB_PASSWORD=your_password
-DB_DATABASE=reactpress
-
-# JWT Configuration
-JWT_SECRET=your_jwt_secret_key
-JWT_EXPIRES_IN=7d
-
-# File Upload (Optional - Ali OSS)
-OSS_ACCESS_KEY_ID=your_access_key_id
-OSS_ACCESS_KEY_SECRET=your_access_key_secret
-OSS_BUCKET=your_bucket_name
-OSS_REGION=your_region
-
-# Email Configuration (Optional)
-EMAIL_HOST=smtp.gmail.com
-EMAIL_PORT=587
-EMAIL_USER=your_email@gmail.com
-EMAIL_PASS=your_app_password
+DB_USER=reactpress_user
+DB_PASSWD=secure_password_here
+DB_DATABASE=reactpress_prod
+DB_SSL=true
+
+# Site URLs (Production)
+CLIENT_SITE_URL=https://yourdomain.com
+SERVER_SITE_URL=https://api.yourdomain.com
+
+# Security Settings (Production)
+JWT_SECRET=your-very-secure-jwt-secret-here
+JWT_EXPIRES_IN=24h
+JWT_REFRESH_EXPIRES_IN=7d
+
+# SMTP Configuration (Production)
+SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+SMTP_PORT=587
+SMTP_USER=your_smtp_username
+SMTP_PASS=your_smtp_password
+SMTP_FROM=noreply@yourdomain.com
+
+# Cloud Storage (Optional)
+S3_ACCESS_KEY_ID=your_aws_access_key
+S3_SECRET_ACCESS_KEY=your_aws_secret_key
+S3_BUCKET_NAME=your_bucket_name
+S3_REGION=us-east-1
 ```
 
-## Programmatic Usage
+## API Documentation
 
-You can also use the server programmatically in your Node.js applications:
+Once running, visit `http://localhost:3002/api` for:
+- Interactive Swagger documentation
+- API endpoint explorer
+- Authentication examples
+- Response schemas
+- Request/response validation
+- Code generation for multiple languages
 
-```typescript
-import { bootstrap } from '@fecommunity/reactpress-server';
-
-async function startServer() {
-  const app = await bootstrap({
-    port: 3002,
-    apiPrefix: '/api',
-    cors: true
-  });
-  
-  console.log('ReactPress server started successfully!');
-}
-
-startServer();
-```
-
-## API Endpoints
+## Development
 
-The server provides comprehensive REST APIs:
+```bash
+# Clone repository
+git clone https://github.com/fecommunity/reactpress.git
+cd reactpress/server
 
-### Authentication
-- `POST /api/auth/login` - User login
-- `POST /api/auth/register` - User registration
-- `GET /api/auth/profile` - Get user profile
+# Install dependencies
+pnpm install
 
-### Articles
-- `GET /api/articles` - Get articles (with pagination)
-- `POST /api/articles` - Create article
-- `GET /api/articles/:id` - Get article by ID
-- `PUT /api/articles/:id` - Update article
-- `DELETE /api/articles/:id` - Delete article
+# Start development server with hot reload
+pnpm run dev
 
-### Categories
-- `GET /api/categories` - Get all categories
-- `POST /api/categories` - Create category
-- `PUT /api/categories/:id` - Update category
-- `DELETE /api/categories/:id` - Delete category
+# Start with PM2 (development)
+pnpm run pm2:start
 
-### Tags
-- `GET /api/tags` - Get all tags
-- `POST /api/tags` - Create tag
-- `PUT /api/tags/:id` - Update tag
-- `DELETE /api/tags/:id` - Delete tag
+# Build for production
+pnpm run build
 
-### Comments
-- `GET /api/comments` - Get comments
-- `POST /api/comments` - Create comment
-- `PUT /api/comments/:id` - Update comment
-- `DELETE /api/comments/:id` - Delete comment
+# Run tests
+pnpm run test
 
-### File Upload
-- `POST /api/upload/image` - Upload image
-- `POST /api/upload/file` - Upload file
+# Run tests with coverage
+pnpm run test:cov
 
-## Database Setup
+# Run end-to-end tests
+pnpm run test:e2e
+```
 
-### MySQL Installation
+## Project Structure
 
-**Ubuntu/Debian:**
-```bash
-sudo apt update
-sudo apt install mysql-server
-sudo mysql_secure_installation
 ```
-
-**macOS:**
-```bash
-brew install mysql
-brew services start mysql
+server/
+├── src/
+│   ├── modules/          # Feature modules
+│   │   ├── article/      # Article management
+│   │   ├── auth/         # Authentication
+│   │   ├── user/         # User management
+│   │   └── ...           # Other modules
+│   ├── common/           # Shared utilities and decorators
+│   ├── filters/          # Exception filters
+│   ├── interceptors/     # Request/response interceptors
+│   ├── guards/           # Authentication guards
+│   ├── pipes/            # Data transformation pipes
+│   ├── logger/           # Logging utilities
+│   └── utils/            # Utility functions
+├── public/               # Static assets
+│   └── swagger/          # Swagger documentation
+├── dist/                 # Compiled output
+└── bin/                  # CLI entry points
 ```
 
-**Windows:**
-Download and install from [MySQL Official Website](https://dev.mysql.com/downloads/mysql/)
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DB_HOST` | Database host | `127.0.0.1` |
+| `DB_PORT` | Database port | `3306` |
+| `DB_USER` | Database username | - |
+| `DB_PASSWD` | Database password | - |
+| `DB_DATABASE` | Database name | `reactpress` |
+| `SERVER_PORT` | Server port | `3002` |
+| `JWT_SECRET` | JWT secret key | - |
+| `CLIENT_SITE_URL` | Client site URL | `http://localhost:3001` |
+| `SERVER_SITE_URL` | Server site URL | `http://localhost:3002` |
+| `SMTP_HOST` | SMTP server host | - |
+| `SMTP_PORT` | SMTP server port | - |
+| `SMTP_USER` | SMTP username | - |
+| `SMTP_PASS` | SMTP password | - |
 
-### Database Creation
+## CLI Commands
 
-```sql
-CREATE DATABASE reactpress;
-CREATE USER 'reactpress'@'localhost' IDENTIFIED BY 'your_password';
-GRANT ALL PRIVILEGES ON reactpress.* TO 'reactpress'@'localhost';
-FLUSH PRIVILEGES;
-```
+```bash
+# Show help
+npx @fecommunity/reactpress-server --help
 
-## Advanced Usage
+# Start server
+npx @fecommunity/reactpress-server
 
-### Custom Configuration
+# Start with PM2
+npx @fecommunity/reactpress-server --pm2
 
-```typescript
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from '@fecommunity/reactpress-server';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  
-  // Custom middleware
-  app.use('/custom', customMiddleware);
-  
-  // Custom global filters
-  app.useGlobalFilters(new CustomExceptionFilter());
-  
-  await app.listen(3002);
-}
-
-bootstrap();
-```
+# Specify port
+npx @fecommunity/reactpress-server --port 3002
 
-### Plugin Development
+# Enable verbose logging
+npx @fecommunity/reactpress-server --verbose
 
-```typescript
-import { Module } from '@nestjs/common';
-import { PluginInterface } from '@fecommunity/reactpress-server';
-
-@Module({
-  // Your plugin implementation
-})
-export class CustomPlugin implements PluginInterface {
-  install() {
-    // Plugin installation logic
-  }
-}
-```
+# Run database migrations
+npx @fecommunity/reactpress-server --migrate
 
-## Deployment
+# Seed database with sample data
+npx @fecommunity/reactpress-server --seed
+```
 
-### PM2 (Recommended)
+## Integration with ReactPress Toolkit
 
-```bash
-# Install PM2
-npm install -g pm2
+The server automatically generates the OpenAPI specification that powers the ReactPress Toolkit:
 
-# Start with PM2
-npm run pm2
+```typescript
+// The toolkit is automatically generated from this server's API
+import { api, types } from '@fecommunity/reactpress-toolkit';
 
-# Monitor
-pm2 monitor
+// All API endpoints are strongly typed
+const articles: types.IArticle[] = await api.article.findAll();
 ```
 
-### Docker
-
-```dockerfile
-FROM node:18-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-COPY . .
-RUN npm run build
-EXPOSE 3002
-CMD ["npm", "start"]
-```
+## Database Schema
+
+ReactPress uses MySQL/PostgreSQL with the following key tables:
+- `users` - User accounts and profiles with 2FA support
+- `articles` - Blog posts and content with versioning
+- `categories` - Content categorization with hierarchy
+- `tags` - Content tagging system
+- `comments` - Reader comments and discussions with moderation
+- `files` - Media file management
+- `settings` - System configuration with environment overrides
+- `views` - Analytics and tracking
+- `webhooks` - Event-driven integrations
+- `scheduled_tasks` - Automated operations
+
+## Security Features
+
+- **JWT Authentication** - Secure token-based authentication with refresh rotation
+- **Rate Limiting** - Adaptive throttling to prevent abuse
+- **Input Validation** - Sanitize all user inputs with Zod schema validation
+- **Helmet.js** - Secure HTTP headers
+- **CSRF Protection** - Prevent cross-site request forgery
+- **SQL Injection Prevention** - Through TypeORM parameterized queries
+- **CORS Configuration** - Controlled cross-origin resource sharing
+- **Data Encryption** - At-rest encryption for sensitive data
+- **Audit Logging** - Comprehensive activity tracking
+
+## Performance Optimization
+
+- **Database Indexing** - Optimized queries with proper indexing
+- **Connection Pooling** - Efficient database connection management
+- **Caching** - Redis integration for frequently accessed data
+- **Compression** - Gzip compression for API responses
+- **Pagination** - Efficient data retrieval for large datasets
+- **Query Optimization** - TypeORM query builder for complex operations
+- **Background Jobs** - Queue system for long-running tasks
+
+## Testing
 
-### Docker Compose
-
-```yaml
-version: '3.8'
-services:
-  reactpress-server:
-    build: .
-    ports:
-      - "3002:3002"
-    environment:
-      - DB_HOST=mysql
-      - DB_USERNAME=root
-      - DB_PASSWORD=password
-      - DB_DATABASE=reactpress
-    depends_on:
-      - mysql
-  
-  mysql:
-    image: mysql:5.7
-    environment:
-      - MYSQL_ROOT_PASSWORD=password
-      - MYSQL_DATABASE=reactpress
-    ports:
-      - "3306:3306"
-```
+```bash
+# Run unit tests
+pnpm run test
 
-## Integration with Frontend
+# Run integration tests
+pnpm run test:integration
 
-Use with ReactPress client:
+# Run end-to-end tests
+pnpm run test:e2e
 
-```bash
-# Install both server and client
-npm install @fecommunity/reactpress-server @fecommunity/reactpress-client @fecommunity/reactpress-config
+# Run tests with coverage
+pnpm run test:cov
 
-# Start server
-npx reactpress-server dev
+# Run linting
+pnpm run lint
 
-# In another terminal, start client
-npx reactpress-client dev
+# Run formatting
+pnpm run format
+
+# Run type checking
+pnpm run type-check
 ```
 
-## Troubleshooting
+## Deployment
 
-### Common Issues
+### Production Deployment with PM2
 
-1. **Database Connection Error**
-   ```
-   Error: connect ECONNREFUSED 127.0.0.1:3306
-   ```
-   - Ensure MySQL is running
-   - Check database credentials in `.env`
+```
+# Start server with PM2
+npx @fecommunity/reactpress-server --pm2
 
-2. **Port Already in Use**
-   ```
-   Error: listen EADDRINUSE :::3002
-   ```
-   - Change port in `.env` file or use `-p` option
+# Or build and start manually
+pnpm run build
+pnpm run start:prod
+```
 
-3. **JWT Secret Missing**
-   ```
-   Error: JWT_SECRET is not defined
-   ```
-   - Add `JWT_SECRET=your_secret_key` to `.env`
+## Monitoring & Logging
 
-### Debug Mode
+- **Structured Logging** - JSON-formatted logs for easy parsing
+- **Error Tracking** - Comprehensive error reporting with context
+- **Performance Metrics** - Response time and throughput monitoring
+- **Health Checks** - API endpoint for service status
+- **Alerting** - Basic alerting capabilities
 
-Start server with debug information:
+## Support
 
-```bash
-DEBUG=* npx reactpress-server dev
-```
+- 📖 [Documentation](https://github.com/fecommunity/reactpress)
+- 🐛 [Issues](https://github.com/fecommunity/reactpress/issues)
+- 💬 [Discussions](https://github.com/fecommunity/reactpress/discussions)
+- 📧 [Support](mailto:support@reactpress.dev)
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a pull request
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details.
 
-## Links
+---
 
-- [GitHub Repository](https://github.com/fecommunity/reactpress)
-- [Documentation](https://reactpress.surge.sh)
-- [npm Package](https://www.npmjs.com/package/@fecommunity/reactpress-server)
-- [API Documentation](http://localhost:3002/api) (when server is running)
+Built with ❤️ by [FECommunity](https://github.com/fecommunity)