Playerss

🏆 Quest Tracker API v2.0 - Extended

A production-ready REST API that extends Template 11 with JWT authentication, MongoDB integration, and social features. Transform your gamified quest system into a scalable, multi-user application.

🚀 What’s New in v2.0

This extended version transforms the original Template 11 into a production-ready API:

✨ New Features

• JWT Authentication - Secure token-based auth replacing API keys
• MongoDB Integration - Persistent data storage with Mongoose ODM
• User Management - Registration, login, profiles with gamification
• Quest Ownership - Users can only modify their own quests
• Quest Sharing - Share quests publicly or as templates
• Social Features - Follow users, like quests, activity feeds
• Discovery System - Trending quests, personalized recommendations
• Achievement System - Track and display user achievements
• Enhanced Security - Input validation, rate limiting, CORS
• Backward Compatibility - Legacy API key support maintained

📁 Project Structure

quest-tracker-api-extended/
├── package.json                 # Updated dependencies
├── server.js                    # Enhanced server with JWT & DB
├── .env.example                 # Environment configuration template
├── README.md                    # This file
├── database/
│   ├── connection.js           # MongoDB connection setup
│   └── models/
│       ├── User.js             # User model with gamification
│       ├── Quest.js            # Quest model with sharing
│       └── Achievement.js      # Achievement definitions
├── middleware/
│   ├── auth.js                 # JWT + legacy API key auth
│   └── validation.js           # Input validation (existing)
├── routes/
│   ├── auth.js                 # Authentication endpoints
│   ├── quests.js               # Quest CRUD with ownership
│   ├── players.js              # User profiles & leaderboards
│   ├── categories.js           # Quest categories (existing)
│   └── social.js               # Social features & discovery
├── utils/
│   └── jwt.js                  # JWT token utilities
├── database/migrations/
│   └── seed.js                 # Database seeding script
└── docs/                       # Documentation

🛠️ Setup Instructions

Prerequisites

• Node.js 18+
• MongoDB (local or Atlas)
• npm or yarn

1. Clone and Install

# Navigate to the extended project
cd quest-tracker-api-extended

# Install dependencies
npm install

2. Environment Configuration

# Copy environment template
cp .env.example .env

# Edit .env with your settings

Required Environment Variables:

# Server
PORT=3000
NODE_ENV=development

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=7d

# Database
DATABASE_URL=mongodb://localhost:27017/quest-tracker
# OR for MongoDB Atlas:
# DATABASE_URL=mongodb+srv://username:password@cluster.mongodb.net/quest-tracker

# CORS
CORS_ORIGIN=http://localhost:3000,http://localhost:3001

# Legacy API Keys (comma-separated)
LEGACY_API_KEYS=demo_key_12345,test_key_67890,student_key_abcde

3. Database Setup

# Ensure MongoDB is running
# For local MongoDB:
mongod

# Seed the database with sample data
npm run db:seed

4. Start the Server

# Development mode (with auto-reload)
npm run dev

# Production mode
npm start

The API will be available at http://localhost:3000

📖 API Documentation

🔐 Authentication

The API supports two authentication methods:

JWT Bearer Token (Recommended)

# 1. Register a new user
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "demo",
    "email": "demo@example.com",
    "password": "Password123",
    "displayName": "Demo User"
  }'

# 2. Login to get token
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "demo",
    "password": "Password123"
  }'

# 3. Use token in subsequent requests
curl http://localhost:3000/api/quests \
  -H "Authorization: Bearer <your-jwt-token>"

Legacy API Key (Backward Compatible)

curl http://localhost:3000/api/quests \
  -H "X-API-Key: demo_key_12345"

🎯 Core Endpoints

Authentication

| Method | Endpoint | Description | Auth | |——–|———-|————-|——| | POST | /api/auth/register | Register new user | Public | | POST | /api/auth/login | Login and get JWT | Public | | POST | /api/auth/refresh | Refresh access token | Public | | GET | /api/auth/me | Get current user | JWT |

Quests

| Method | Endpoint | Description | Auth | |——–|———-|————-|——| | GET | /api/quests | List user’s quests | JWT/API Key | | POST | /api/quests | Create new quest | JWT | | GET | /api/quests/:id | Get quest details | JWT/API Key | | PUT | /api/quests/:id | Update quest | JWT (owner) | | DELETE | /api/quests/:id | Soft delete quest | JWT (owner) | | POST | /api/quests/:id/complete | Complete quest | JWT (owner) | | POST | /api/quests/:id/share | Share quest | JWT (owner) | | POST | /api/quests/:id/clone | Clone shared quest | JWT |

Players & Leaderboards

| Method | Endpoint | Description | Auth | |——–|———-|————-|——| | GET | /api/players | Leaderboard | JWT/API Key | | GET | /api/players/:id | Player profile | JWT/API Key | | GET | /api/players/me | Current user profile | JWT | | PUT | /api/players/me | Update profile | JWT | | GET | /api/players/me/achievements | User achievements | JWT | | POST | /api/players/:id/follow | Follow/unfollow | JWT |

Social & Discovery

| Method | Endpoint | Description | Auth | |——–|———-|————-|——| | GET | /api/quests/shared/public | Browse public quests | Public | | GET | /api/quests/templates | Quest templates | Public | | GET | /api/discover/trending | Trending quests | Public | | GET | /api/discover/recommended | Personalized | JWT | | GET | /api/social/feed | Activity feed | JWT | | POST | /api/social/quests/:id/like | Like/unlike quest | JWT |

📊 Response Format

All responses follow a consistent format:

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Human readable message",
  "meta": {
    // Pagination, filters, etc.
  }
}

🧪 Testing

Quick Test Commands

# Check API status
curl http://localhost:3000/api/status

# Test with legacy API key
curl http://localhost:3000/api/quests?api_key=demo_key_12345

# Register new user
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "TestPass123",
    "displayName": "Test User"
  }'

# Login
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier":"demo","password":"Password123"}'

# Create a quest (with JWT)
curl -X POST http://localhost:3000/api/quests \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "title": "Learn Node.js",
    "description": "Complete Node.js tutorial",
    "category": "learning",
    "priority": "high",
    "difficulty": "medium"
  }'

🗄️ Database Schema

User Model

{
  username: String,           // Unique, required
  email: String,              // Unique, required
  password: String,           // Hashed with bcrypt
  displayName: String,
  level: Number,              // Gamification level
  totalXP: Number,
  currentStreak: Number,
  achievements: Array,
  preferences: {
    categories: Array,
    difficulty: String,
    theme: String,
    privacy: Object
  },
  social: {
    followers: Array,
    following: Array
  },
  stats: {
    totalQuestsStarted: Number,
    totalQuestsCompleted: Number
  }
}

Quest Model

{
  title: String,
  description: String,
  owner: ObjectId,            // Reference to User
  status: String,             // pending, in_progress, completed
  category: String,
  priority: String,
  difficulty: String,
  xpReward: Number,           // Auto-calculated
  deadline: Date,
  tags: Array,
  sharing: {
    isPublic: Boolean,
    isTemplate: Boolean,
    likes: Array,
    clones: Number
  },
  completion: {
    completedAt: Date,
    totalXPEarned: Number
  },
  isDeleted: Boolean          // Soft delete
}

🚀 Deployment

Environment Variables for Production

NODE_ENV=production
PORT=3000
JWT_SECRET=your-production-secret-key
DATABASE_URL=mongodb+srv://prod-user:password@cluster.mongodb.net/quest-tracker
CORS_ORIGIN=https://your-frontend-domain.com

Deploy to Railway (Recommended)

1. Create account at railway.app
2. Connect your GitHub repository
3. Add MongoDB database service
4. Configure environment variables
5. Deploy with automatic CI/CD

Deploy to Render

1. Create account at render.com
2. Create new Web Service
3. Connect GitHub repository
4. Add MongoDB add-on or external database
5. Configure environment variables

📚 Key Features Explained

JWT Authentication Flow

1. User registers/logs in → receives access token + refresh token
2. Include Authorization: Bearer <token> header in requests
3. Token expires after configured time (default 7 days)
4. Use refresh token to get new access token

Quest Ownership

• Each quest has an owner field referencing the creating user
• Users can only modify (update/delete/complete) their own quests
• Public quests can be viewed by anyone
• Private quests require ownership to view

Quest Sharing

• Public Share: Makes quest visible in public feeds
• Template: Allows other users to clone the quest
• Share Code: Unique code for easy sharing
• Likes: Users can like public quests
• Clones: Track how many times a quest has been cloned

Gamification System

• XP System: Earn XP by completing quests
• Level Up: Gain levels as XP increases
• Streaks: Track consecutive days of quest completion
• Achievements: Unlock achievements for milestones
• Leaderboards: Rank users by level, XP, or streaks

🔒 Security Features

• Password Hashing: bcrypt with salt rounds
• JWT Tokens: Secure, expiring tokens
• Rate Limiting: 100 requests per 15 minutes per IP
• Input Validation: express-validator for all inputs
• CORS: Configurable origin whitelist
• Helmet: Security headers
• Soft Delete: Data recovery capability

🐛 Troubleshooting

Common Issues

Database Connection Failed

# Check MongoDB is running
mongod --version

# Verify connection string in .env
DATABASE_URL=mongodb://localhost:27017/quest-tracker

JWT Token Invalid

• Token may be expired - login again to get new token
• Check Authorization header format: Bearer <token>

Cannot Create Quests

• JWT authentication required (API keys work for read-only)
• Check token is valid and not expired

Port Already in Use

# Kill process on port 3000
npx kill-port 3000

# Or change PORT in .env
PORT=3001

📄 License

This project extends Template 11 from the W3.5 curriculum.

🤝 Contributing

This is a student project for learning purposes. Feel free to extend it with:

• Additional social features
• Real-time updates with WebSockets
• Email notifications
• Mobile app integration
• Analytics dashboard

📞 Support

For issues or questions:

1. Check the API docs at /api/docs when server is running
2. Review the test commands in this README
3. Check server logs for error messages

---

Built with ❤️ extending Template 11

Version 2.0.0