SubTracker API

A comprehensive subscription management API that helps users track their subscriptions, manage renewal dates, and receive automated email reminders.

🚀 Features

🔐 Authentication System

• User registration and login
• JWT-based authentication
• Secure password hashing with bcrypt
• Profile management

📋 Subscription Management

• Create, read, update, and delete subscriptions
• Automatic renewal date calculation
• Support for multiple frequencies (daily, weekly, monthly, yearly)
• Categorized subscriptions (entertainment, technology, finance, etc.)
• Status tracking (active, cancelled, expired)

📧 Smart Email Reminders

• Automated email notifications before renewal dates
• Reminder schedule: 7, 5, 2, and 1 days before renewal

🔒 Security & Performance

• Rate limiting and bot protection with Arcjet
• Input validation and sanitization
• Error handling middleware
• MongoDB transactions for data integrity

🛠 Tech Stack

Backend Framework

• Node.js - JavaScript runtime
• Express.js - Web application framework
• ES Modules - Modern JavaScript module system

Database

• MongoDB - NoSQL database
• Mongoose - MongoDB object modeling

Authentication & Security

• JSON Web Tokens (JWT) - Stateless authentication
• bcryptjs - Password hashing
• Arcjet - Security layer (rate limiting, bot detection)

Email System

• Nodemailer - Email sending library
• Gmail SMTP - Email service provider
• Upstash Workflow - Scheduled email automation

🔗 API Endpoints

Authentication

POST /api/v1/auth/sign-up    # User registration
POST /api/v1/auth/sign-in    # User login
POST /api/v1/auth/sign-out   # User logout

Users

GET    /api/v1/users/             # Get all users
GET    /api/v1/users/profile      # Get current user profile
PUT    /api/v1/users/profile      # Update current user profile
GET    /api/v1/users/:id          # Get user by ID
POST   /api/v1/users/             # Create new user
PUT    /api/v1/users/:id          # Update user by ID
DELETE /api/v1/users/:id          # Delete user by ID

Subscriptions

GET    /api/v1/subscriptions/                    # Get all subscriptions
GET    /api/v1/subscriptions/upcoming_renewals   # Get upcoming renewals
GET    /api/v1/subscriptions/user/:id            # Get user's subscriptions
GET    /api/v1/subscriptions/:id                 # Get subscription details
POST   /api/v1/subscriptions/                    # Create subscription
PUT    /api/v1/subscriptions/:id                 # Update subscription
DELETE /api/v1/subscriptions/:id                 # Delete subscription
PUT    /api/v1/subscriptions/:id/cancel          # Cancel subscription

Workflows

POST /api/v1/workflows/subscription/reminders    # Trigger reminder workflow

🚀 Getting Started

Prerequisites

• Node.js (v16 or higher)
• MongoDB (local or cloud instance)
• Gmail account with app password

Installation

1. Clone the repository

   git clone <repository-url>
   cd sub-tracker

2. Install dependencies

   npm install

3. Environment Setup Create .env.development.local file:

   # Server Configuration
   PORT=5500
   SERVER_URL=http://localhost:5500
   NODE_ENV=development
   
   # Database
   DB_URI=mongodb://localhost:27017/subscription-tracker
   
   # JWT Configuration
   JWT_SECRET=your-super-secret-jwt-key
   JWT_EXPIRES_IN=7d
   
   # Email Configuration
   EMAIL_PASSWORD=your-gmail-app-password
   
   # Upstash QStash (for workflows)
   QSTASH_TOKEN=your-qstash-token
   QSTASH_URL=https://qstash.upstash.io
   
   # Arcjet Security
   ARCJET_KEY=your-arcjet-key
   ARCJET_ENV=development

4. Start the development server

   npm run dev

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

📧 Email Configuration

Gmail Setup

1. Enable 2-factor authentication on your Gmail account
2. Generate an App Password:
   • Go to Google Account settings
   • Security → 2-Step Verification → App passwords
   • Generate password for "Mail"
3. Use the generated password as EMAIL_PASSWORD in your environment

Email Features

• Automated Reminders: Sent 7, 5, 2, and 1 days before renewal
• Beautiful Templates: Clean, responsive design similar to Amazon
• Smart Scheduling: Uses Upstash Workflow for precise timing

📝 Usage Examples

Create User

curl -X POST http://localhost:5500/api/v1/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "password123"
  }'

Create Subscription

curl -X POST http://localhost:5500/api/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Netflix Premium",
    "price": 15.99,
    "currency": "USD",
    "frequency": "monthly",
    "category": "entertainment",
    "paymentMethod": "Credit Card ending in 1234",
    "startDate": "2025-05-01T00:00:00.000Z"
  }'

🔒 Security Features

• JWT Authentication: Stateless authentication with secure tokens
• Password Hashing: bcrypt with salt rounds for secure password storage
• Rate Limiting: Arcjet protection against brute force attacks
• Bot Detection: Automatic blocking of malicious bots
• Input Validation: Mongoose schema validation
• Error Handling: Comprehensive error middleware

🎯 Key Features

Smart Renewal Calculation

• Automatically calculates renewal dates based on frequency
• Updates renewal dates when start date or frequency changes
• Handles different subscription periods accurately

Email Workflow

• Integrates with Upstash Workflow for scheduled emails
• Graceful handling of workflow failures
• Subscription creation continues even if email scheduling fails

User Management

• Profile-based authentication
• Cascade deletion (deleting user removes all subscriptions)
• Email uniqueness validation

Built with ❤️ by Khulan