GSSoC Project Notifier

A minimal, production-ready, and lightweight monitoring service designed to notify you instantly on Telegram whenever new projects are added to the GirlScript Summer of Code (GSSoC) website.

How It Works

1. GitHub Actions Scheduler: Triggered every 5 minutes (via cron) or manually (via workflow_dispatch).
2. State Tracking: Reads state.json to check what projects were seen in previous runs.
3. Resilient Polling: Queries the GSSoC projects API endpoint with dynamic property mapping and up to 3 retries.
4. Change Detection: Identifies ONLY newly added projects, ignoring deleted, renamed, or reordered items to prevent duplicate alerts.
5. Telegram Alert: Sends a single combined alert containing the newly added project details if additions are detected.
6. State Sync: Saves the union of old and new projects back to state.json and pushes the commit directly to the repository (using the standard GitHub Action Bot).

---

Setup Requirements

1. Telegram Bot & Chat ID Setup

1. Open Telegram and search for @BotFather.
2. Create a new bot with /newbot and copy your bot API token (looks like 123456789:ABCdefGh...).
3. Search for @userinfobot or start a chat with your bot and visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates to get your Telegram user/chat ID (chat.id in JSON).

2. GitHub Secrets Configuration

In your GitHub repository settings, navigate to Settings > Secrets and variables > Actions and add the following repository secrets:

• GSSOC_API: The GSSoC projects API endpoint.
• TG_BOT: Your Telegram Bot API token.
• TG_CHAT: Your Telegram chat/channel/group ID.

---

Local Development

1. Install dependencies:

   npm install

2. Create a copy of .env.example named .env and fill in your variables:

   GSSOC_API=https://api.example.com/projects
   TG_BOT=your_telegram_bot_token
   TG_CHAT=your_telegram_chat_id

3. Run the monitor script:

   npm start

---

Telegram Message Format

When new projects are found, you will receive a notification in this format:

🚨 New GSSoC Projects Added

• <project_name>
• <project_name>

Repository:
<repo_url>

Total Projects: <count>

---

Reliability Features

• Exponential Backoff Retries: Retries up to 3 times before declaring failure.
• Graceful Exit: Exits with code 0 on temporary GSSoC API outages so your GitHub workflow actions remain green, while logging all issues clearly.
• Union-Based De-duplication: Tracks project names inside state.json to prevent spamming notifications on restarts or transient API glitches.