Add login System + Complete system overhaul

.env.example

@@ -8,12 +8,104 @@ REDIS_URI="redis://localhost:6379"
 REDIS_URI_DEV="redis://localhost:6379"
 REDIS_TTL_SECONDS=3600 # 1 hour
 
-# Flash configs
-SECRET_KEY=""
+# Sentry configuration (error tracking & performance monitoring)
+SENTRY_DSN=""                          # Leave empty to disable Sentry
+SENTRY_SEND_PII="false"                # Send user emails/IPs (consider GDPR implications)
+SENTRY_TRACES_SAMPLE_RATE=0.1       # % of transactions to capture (1.0 in dev, 0.05-0.1 in prod to reduce costs)
+SENTRY_PROFILE_SAMPLE_RATE=0.05     # % of profiling sessions to capture (1.0 in dev, 0.01-0.05 in prod, very expensive)
+
+# Flask configs
+FLASK_SECRET_KEY="" # To generate: import os; print(os.urandom(32))
 HOST_URI="127.0.0.1:8000"
 SHORTEN_API_RATE_LIMIT_PER_HOUR=100
+ENV="development"  # change to "production" in production
+
+# Logging Configuration
+LOG_LEVEL=DEBUG                    # DEBUG, INFO, WARNING, ERROR, CRITICAL
+LOG_FORMAT=console                   # json (prod) or console (dev)
+
+# Sampling Rates (0.0 to 1.0)
+SAMPLE_RATE_REDIRECT=0.05        # 5% of URL redirects
+SAMPLE_RATE_STATS=0.20           # 20% of stats queries
+SAMPLE_RATE_CACHE=0.01           # 1% of cache operations
+SAMPLE_RATE_EXPORT=0.80          # 80% of exports
 
 # Configs for the contact and report forms
 CONTACT_WEBHOOK=""
 URL_REPORT_WEBHOOK=""
-HCAPTCHA_SECRET=""
+HCAPTCHA_SECRET=""
+
+# JWT configs
+JWT_ISSUER=
+JWT_AUDIENCE=
+ACCESS_TOKEN_TTL_SECONDS=3600
+REFRESH_TOKEN_TTL_SECONDS=2592000
+COOKIE_SECURE="false"    # false: for local dev, true: for production
+JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n.....\n-----END PRIVATE KEY-----"
+JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n.....\n-----END PUBLIC KEY-----"
+JWT_SECRET=""
+
+# To generate these private key run this commands:
+# openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out jwt_private_key.pem
+
+# for public key:
+# openssl rsa -pubout -in jwt_private_key.pem -out jwt_public_key.pem
+
+# for JWT_SECRET (if not using RSA keys):
+# import os; print(os.urandom(32).hex())
+# Use JWT_SECRET only if you are not using RSA keys (JWT_PRIVATE_KEY and JWT_PUBLIC_KEY)
+
+# OAuth configs
+
+# Google OAuth
+# How to generate these keys:
+# 1. Go to https://console.cloud.google.com/apis/credentials
+# 2. Create a new project (if you don't have one)
+# 3. Enable the Google+ API
+# 4. Configure OAuth consent screen (make sure to add http://localhost:8000 and http://127.0.0.1:8000)
+# 5. Create OAuth 2.0 Client IDs and get the client ID and client secret
+# 6. Set the authorized redirect URIs / Redirect URIs to:
+#    http://localhost:8000/oauth/google/callback (for local dev)
+#    http://127.0.0.1:8000/oauth/google/callback (for local dev)
+#    http://your-production-domain.com/oauth/google/callback (for production)
+GOOGLE_OAUTH_CLIENT_ID=""
+GOOGLE_OAUTH_CLIENT_SECRET=""
+GOOGLE_OAUTH_REDIRECT_URI="http://127.0.0.1:8000/oauth/google/callback"
+
+# GitHub OAuth
+# How to generate these keys:
+# 1. Go to https://github.com/settings/developers
+# 2. Create a new OAuth App (Not GitHub App !important)
+# 3. Set the homepage URL to http://127.0.0.1:8000 or http://localhost:8000 for local dev
+# 4. Set the authorization callback URI to http://127.0.0.1:8000/oauth/github/callback
+# For production, set it to http://your-production-domain.com/oauth/github/callback
+# 5. Make sure, where this app can be installed, "Any account" is selected
+# 6. click on "Generate a new Client Secret" to get the client secret
+GITHUB_OAUTH_CLIENT_ID=""
+GITHUB_OAUTH_CLIENT_SECRET=""
+GITHUB_OAUTH_REDIRECT_URI="http://127.0.0.1:8000/oauth/github/callback"
+
+
+# Discord OAuth
+# How to generate these keys:
+# 1. Go to https://discord.com/developers/applications
+# 2. Create a new application
+# 3. Go to OAuth2 section and add a redirect URI:
+#    http://localhost:8000/oauth/discord/callback (for local dev)
+#    http://your-production-domain.com/oauth/discord/callback (for production)
+# 4. In the scopes section, select "identify" and "email"
+DISCORD_OAUTH_CLIENT_ID=""
+DISCORD_OAUTH_CLIENT_SECRET=""
+DISCORD_OAUTH_REDIRECT_URI="http://127.0.0.1:8000/oauth/discord/callback"
+
+# ZeptoMail Configuration (for transactional emails)
+# How to get these credentials:
+# 1. Sign up at https://www.zoho.com/zeptomail/
+# 2. Add and verify your domain (DKIM + CNAME records)
+# 3. Create a Mail Agent
+# 4. Go to SMTP/API section and copy your Send Mail Token
+# 5. Set ZEPTO_API_TOKEN to the token value
+ZEPTO_API_TOKEN=""
+ZEPTO_FROM_EMAIL="noreply@your-domain.com"
+ZEPTO_FROM_NAME="Your App Name"
+APP_URL="http://127.0.0.1:8000"

.github/workflows/api_test.yaml

@@ -23,10 +23,10 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: 3.12
 

.github/workflows/github-ci.yaml

@@ -3,7 +3,7 @@ name: Check Code Formatting
 on:
   push:
     branches:
-      - main
+      - '*'
     paths-ignore:
       - '**/*.md'
       - '**/*.rst'
@@ -21,10 +21,10 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: 3.12
 

.github/workflows/minify.yaml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: check out the repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: replace js and css files with minified ones
         uses: nizarmah/auto-minify@v3

.gitignore

@@ -129,6 +129,7 @@ celerybeat.pid
 
 # Environments
 .env
+.env.staging
 .venv
 env/
 venv/
@@ -183,4 +184,6 @@ todo.md
 
 # Local API Testings
 k6-tests/
-local_test_db/
+local_test_db/
+
+.DS_Store

README.md

@@ -21,21 +21,23 @@
 
 # ⚡ Introduction
 
-**spoo.me** is a free, open-source service for shortening URLs. It offers URL statistics, a free API, and customization options. You can create custom `slugs`, add `password protection`, and manage `link lifespans`.
+**spoo.me** is a free, open-source service for shortening URLs. It offers comprehensive URL statistics, a free API, and extensive customization options. You can create and manage your URLs, generate API keys, create custom `slugs`, add `password protection`, and manage `link lifespans`.
 
 # 🔥 Features
 
 - `Custom Slugs` - Create custom slugs for your URLs 🎯
 - `Emoji Slugs` - Use emojis as slugs for your URLs 😃
 - `Password Protection` - Protect your URLs with a password 🔒
 - `Link Max Clicks` - Set a maximum number of clicks for your URLs 📈
-- `URL Statistics` - View detailed statistics for your URLs 📊
+- `URL Statistics` - View detailed statistics for your URLs with advanced analytics 📊
 - `BOT Tracking` - Track bot clicks on your URLs 🤖
 - `API` - A free and open-sourced API for URL shortening and statistics 🛠️
 - `Export Click Data` - Export click data as a CSV, JSON, XLSX, or XML file 📤
+- `Dashboard` - Manage all your URLs and view analytics in one place 📱
+- `API Keys` - Generate API keys for programmatic access with rate limiting 🔑
 - `Open Source` - spoo.me is open-sourced and free to use 📖
 - `Absolutely Free` - No hidden costs, no premium plans, no limitations 💸
-- `No Registration` - No need to register an account to use spoo.me 📝
+- `No Registration Required` - Create short URLs without an account 📝
 - `Self Hosting` - You can host spoo.me on your own server 🏠
 
 # 📌 Endpoints
@@ -107,11 +109,30 @@ mv .env.example .env
 MONGODB_URI=<your_MONGODB_URI>
 CONTACT_WEBHOOK=<valid_webhook_URI>
 URL_REPORT_WEBHOOK=<valid_webhook_URI>
+
+# OAuth Configuration (Optional - for social login features)
+GOOGLE_CLIENT_ID=<your_google_client_id>
+GOOGLE_CLIENT_SECRET=<your_google_client_secret>
+GITHUB_CLIENT_ID=<your_github_client_id>
+GITHUB_CLIENT_SECRET=<your_github_client_secret>
+DISCORD_CLIENT_ID=<your_discord_client_id>
+DISCORD_CLIENT_SECRET=<your_discord_client_secret>
+
+# JWT Secret Keys (Required for authentication)
+JWT_SECRET_KEY=<your_jwt_secret_key>
+JWT_REFRESH_SECRET_KEY=<your_jwt_refresh_secret_key>
+
+# Email Configuration (Optional - for email verification)
+ZOHO_MAIL_USERNAME=<your_email_address>
+ZOHO_MAIL_PASSWORD=<your_email_password>
 ```
 
 > [!NOTE]
-> With this method, you can either use a cloud service like [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) to store the data remotely or you can use a local MongoDB instance.
-> If you want to use a local MongoDB instance, your MongoDB URI would be `mongodb://localhost:27017/`.
+> - OAuth credentials are optional. Users can still register with email/password if OAuth is not configured.
+> - JWT secret keys should be long, random strings. You can generate them using `openssl rand -hex 32`.
+> - Email configuration is optional but recommended for email verification features.
+> - With this method, you can either use a cloud service like [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) to store the data remotely or you can use a local MongoDB instance.
+> - If you want to use a local MongoDB instance, your MongoDB URI would be `mongodb://localhost:27017/`.
 
 ### 🚀 Starting the server
 
@@ -165,10 +186,29 @@ mv .env.example .env
 MONGODB_URI=<your_MONGODB_URI>
 CONTACT_WEBHOOK=<valid_webhook_URI>
 URL_REPORT_WEBHOOK=<valid_webhook_URI>
+
+# OAuth Configuration (Optional - for social login features)
+GOOGLE_CLIENT_ID=<your_google_client_id>
+GOOGLE_CLIENT_SECRET=<your_google_client_secret>
+GITHUB_CLIENT_ID=<your_github_client_id>
+GITHUB_CLIENT_SECRET=<your_github_client_secret>
+DISCORD_CLIENT_ID=<your_discord_client_id>
+DISCORD_CLIENT_SECRET=<your_discord_client_secret>
+
+# JWT Secret Keys (Required for authentication)
+JWT_SECRET_KEY=<your_jwt_secret_key>
+JWT_REFRESH_SECRET_KEY=<your_jwt_refresh_secret_key>
+
+# Email Configuration (Optional - for email verification)
+ZOHO_MAIL_USERNAME=<your_email_address>
+ZOHO_MAIL_PASSWORD=<your_email_password>
 ```
 
 > [!NOTE]
-> If you installed MongoDB locally, your MongoDB URI would be `mongodb://localhost:27017/` or if you are using MongoDB Atlas, you can find your MongoDB URI in the **Connect** tab of your cluster.
+> - OAuth credentials are optional. Users can still register with email/password if OAuth is not configured.
+> - JWT secret keys should be long, random strings. You can generate them using `openssl rand -hex 32`.
+> - Email configuration is optional but recommended for email verification features.
+> - If you installed MongoDB locally, your MongoDB URI would be `mongodb://localhost:27017/` or if you are using MongoDB Atlas, you can find your MongoDB URI in the **Connect** tab of your cluster.
 
 ### 🚀 Starting the server
 
@@ -226,7 +266,7 @@ Open your browser and go to `http://localhost:8000` to access the **spoo.me** UR
 <h6 align="center">
 <img src="https://spoo.me/static/images/favicon.png" height=30 title="Spoo.me Copyright">
 <br>
-© spoo.me . 2024
+© spoo.me . 2025
 
 All Rights Reserved</h6>
 

api/__init__.py

@@ -0,0 +1,2 @@
+# Namespace for API versions
+

api/v1/__init__.py

@@ -0,0 +1,13 @@
+from flask import Blueprint
+
+
+api_v1 = Blueprint("api_v1", __name__, url_prefix="/api/v1")
+
+
+# Import endpoints to register their routes on api_v1
+from . import shorten  # noqa: E402,F401
+from . import keys  # noqa: E402,F401
+from . import urls  # noqa: E402,F401
+from . import management  # noqa: E402,F401
+from . import stats  # noqa: E402,F401
+from . import exports  # noqa: E402,F401