# 💧 HydroMate 💧
# Your Hydration Companion

A Discord bot that helps users stay hydrated and maintain healthy habits with automated reminders.

## How It Works

HydroMate sends you **Status-Aware Reminders** — only when you want them.
Choose exactly which statuses receive reminders: **Online**, **Idle**, **DND**, or even **Offline**.
Set **Quiet Hours** to silence reminders during sleep — they'll wait and arrive when you're ready.

### Highlights

- ⚡ **Event-based presence system** - Instant detection when you come online
- ⚙️ **Interactive settings panel** - All settings in one place with instant save
- 🎯 **Status preferences** - Choose which Discord statuses receive reminders
- 🌙 **Quiet hours** - Timezone-aware reminder suppression
- ⏰ **Custom intervals** - Personalize reminder frequency from 1-4 hours
- 🔥 **Gamification** - Streaks, achievements, and leaderboards
- 🌍 **Multi-language** - English, Turkish, Portuguese (BR), Spanish, Russian, German, French
- 📊 **Rich statistics** - Track your hydration journey
- 🏆 **Social features** - Compete with friends and server members

## ✨ Features

### Core Features

- ⚡ **Real-time Reminders** - Instant scheduling when you come online
- 💧 **Hydration Focus** - Stay hydrated with regular water reminders
- 🎯 **Smart Notifications** - Event-based presence detection
- ⚙️ **Interactive Settings Panel** - Components V2 UI with instant save and live re-render
- 🎯 **Status Preferences** - Multi-select: online, idle, DND, offline
- 🌙 **Quiet Hours** - Set start/end hours with timezone, reminders auto-reschedule
- ⏰ **Custom Intervals** - Set your own reminder frequency (1-4 hours)
- ⏸️ **Pause/Resume** - Full control over reminder activation
- 👥 **Multi-Server Support** - Works across multiple Discord servers
- 🔒 **Admin Controls** - Server admins can configure reminder channels

### Gamification & Engagement

- 🔥 **Streak System** - Track consecutive days of hydration with emoji tiers
- 🏆 **Achievements** - Unlock 12 achievements for milestones
- ✅ **Interactive Buttons** - Quick completion tracking with customizable expiration (1-4 hours)
- 📈 **Personal Stats** - Detailed statistics and progress tracking
- 💎 **Completion Rate** - Track your hydration consistency with visual progress bars
- 🎯 **Milestone Celebrations** - Special messages for 7, 14, 30, 60, 100+ day streaks

### Social Features

- 🏅 **User Leaderboards** - Paginated rankings (10/page) with button-based sorting (Streak, Completion %, Total Sips)
- 👥 **Role Competition** - Server role-based leaderboard system
- ⚔️ **Friend Comparison** - Head-to-head stats comparison
- 📊 **Server Statistics** - Comprehensive guild analytics with hydration score
- 🎉 **Public Celebrations** - Optional milestone announcements (admin toggle)
- 💎 **Hydration Score** - 6-tier server ranking system (Seedling to Diamond)

### Localization & Accessibility

- 🌍 **Multi-Language** - English (🇺🇸), Turkish (🇹🇷), Portuguese BR (🇧🇷), Spanish (🇪🇸), Russian (🇷🇺), German (🇩🇪), French (🇫🇷)
- 🔄 **Auto Language Detection** - Detects Discord locale on registration and guild join
- 🎯 **User-Selectable** - Change language anytime via `/reminder settings`
- 📝 **Fully Translated** - Commands, reminders, achievements, errors, and facts
- 💬 **Message Variations** - 12+ different reminder messages per language
- 💡 **Educational Content** - 25+ hydration facts per language

## 🚀 Initial Setup

### Step 1: Invite Bot
  1. Use invite link
  2. Select your server
  3. Grant required permission:
     - Manage Channels *(optional)*
     - View Channels
     - Send Messages
     - Send Messages in Threads *(optional)*
     - Embed Links
     - Read Message History
     - Add Reactions *(optional)*
     - Use External Emojis *(optional)*
     - Use Application Commands
### Step 2: Automatic Setup
**What happens when bot joins:**
1. Bot sends setup message in system channel
2. Two options presented:
   - 🚀 Auto Setup (creates `#health-reminders`)
   - ⚙️ Manual Setup (use `/setup channel`)
3. If no action in 5 minutes → auto creates channel

**Recommended:** Click "🚀 Auto Setup" for instant configuration! *(Bot needs Manage Channels permission)*

---

### Step 3: Manual Setup (Optional)

If you want a specific channel:

`/setup channel #your-channel`

**Requirements:**
- Channel must be text channel
- Bot needs Send Messages permission
- Bot needs Embed Links permission

---

## 📝 Quick Start (First-Time User Experience)

  1. **Get Started:** Click the 'Get Started' button in the welcome message or use `/reminder register`
  2. **First Reminder:** Your first reminder arrives shortly after registration
  3. **Customize:** Use `/reminder settings` to personalize your experience
  4. **Engagement:** Click 'Hydrated!' when you drink water
  5. **Progress:** Build your streak, unlock achievements and have fun!

## 📖 Commands

### User Commands

#### Reminder Management

- `/reminder register` - Register for health reminders
- `/reminder start` - Activate reminder notifications
- `/reminder stop` - Deactivate reminder notifications
- `/reminder status` - Check your reminder status (streaks, stats, achievements)

#### Settings

- `/reminder settings` - Open interactive settings panel
  - **Reminder type** - DM or server channel
  - **Language** - en, tr, pt-BR, es, ru, de, fr
  - **Interval** - 60–240 minutes (1–4 hours)
  - **Status preferences** - Multi-select: online, idle, DND, offline
  - **Quiet hours** - Start/end hour (0–23), reminders auto-rescheduled
  - **Timezone** - IANA timezone for quiet hours calculation

#### Social Features

- `/reminder compare @user` - Compare your stats with another user
- `/leaderboard users` - View paginated user rankings
  - Button-based sorting: Streak, Completion %, Total Sips
  - 10 users per page with navigation buttons
- `/leaderboard roles` - View role competition standings
- `/stats server` - View server statistics and achievements

### Admin Commands (Administrator only)

- `/setup channel #channel` - Set or change the reminder channel
- `/setup view` - View current bot settings for this server
- `/setup celebrations enabled:true|false` - Toggle public celebration announcements

### Support

- `/help` - Command guide with all available commands and features
- `/support` - Get help and join HydroMate Support server

## 🤝 Need Help?

  Join our [Support Server](https://discord.gg/sRUWQSNg44) - we're happy to help!

---

Made with 💙 by @okk_oguzkagan
Stay Hydrated, Stay Healthy 💪

HydroMate

A Discord bot that helps users stay hydrated and maintain healthy habits with automated reminders.

Voting for HydroMate

Do you want to support us?