Upload README.md

README.md

@@ -0,0 +1,131 @@
+# BIP Cloud Event Notifier
+
+A standalone, single-file lightweight Python application that continuously monitors the BIP Event Portal for new events and instantly sends an email notification along with direct links to apply. The notifier runs as a background process alongside a FastAPI microservice that provides health endpoints.
+
+## Features
+- **Zero Database Required**: Uses memory/local file state to track the latest event IDs instead of a demanding database.
+- **Dynamic Polling Schedule**: Supports dynamic polling speeds via `NORMAL_INTERVAL` and `FAST_INTERVAL`. It automatically speeds up checking when new events are detected (for `FAST_DURATION` seconds) and completely pauses polling during inactive hours (5 PM to 8 AM IST) to conserve resources.
+- **Email Notifications**: Secure email dispatch via the modern Brevo API (recommended for cloud) or standard local SMTP fallback. Separate email recipients for new events (`EVENT_EMAIL_RECIPIENT`) and system warnings (`WARNING_EMAIL_RECIPIENT`) can be configured.
+- **Background Polling with Exponential Backoff**: Efficiently pings the server (default every 60 seconds). Network errors trigger an exponentially increasing sleep timer to gracefully handle short connection drops.
+- **FastAPI Health Server**: Hosts lightweight JSON endpoints (`/health`, `/latest`, `/assistant`) to quickly check monitoring status, cookie expiration, and the latest event info from an external dashboard.
+- **Silent Background Operation**: Maintains a clean terminal, only printing event IDs upon checking and logging errors strictly as needed.
+
+---
+
+## 🛠 Prerequisites
+
+1. **Python 3.x**
+2. **Pip Requirements**
+```bash
+pip install -r requirements.txt
+```
+3. **Brevo API Key (Recommended)**: Create a free account at [Brevo](https://www.brevo.com/) to easily send reliable API-based emails from cloud environments like Hugging Face.
+4. **App Password (Fallback)**: A Gmail App Password if preferring local SMTP.
+
+---
+
+## ⚙️ Initial Setup
+
+1. Open this directory in your terminal.
+2. Create a file named `.env` in the exact same directory as `main.py`.
+3. Paste the following configuration, replacing the values with your actual portal tokens and email settings:
+
+```ini
+# BIP Auth
+XSRF_TOKEN="your_xsrf_token_here"
+BIP_SESSION="your_bip_session_here"
+
+# Email Delivery
+EMAIL_ADDRESS="your_sender_address@gmail.com"
+EMAIL_PASSWORD="your_app_password"
+EVENT_EMAIL_RECIPIENT="recipient_for_new_events@gmail.com"
+WARNING_EMAIL_RECIPIENT="recipient_for_errors@gmail.com"
+BREVO_API_KEY="your_brevo_api_key"
+
+# Polling Intervals (in seconds)
+NORMAL_INTERVAL=120
+FAST_INTERVAL=30
+FAST_DURATION=120
+```
+
+---
+
+## 💻 CLI Commands & Workflow
+
+This script operates seamlessly as a Command Line Interface (CLI) application. Open your terminal in the script's directory.
+
+### 1. Test your Email Integration
+Before trusting the loop, manually trigger a test email to ensure Brevo/SMTP is working.
+```bash
+python main.py --test-alert
+```
+
+### 2. Test Real Event Delivery
+Fetch the actual latest event from BIP and trigger the full email template rendering and delivery.
+```bash
+python main.py --test-real-event
+```
+
+### 3. View the Latest Event
+Quickly pull and print the single most recent event on the portal in the terminal.
+```bash
+python main.py --latest
+```
+
+### 4. List All Recent Events
+Fetch the first page of recent events (up to 10) to get an overview of what is currently on the server.
+```bash
+python main.py --list-all
+```
+
+### 5. Start the Monitoring Server
+This will launch the primary application: the FastAPI web server on port 7860 and the background polling thread.
+```bash
+python main.py --run
+```
+*(Note: Running `python main.py` by itself with no arguments will default to `--run`.)*
+
+---
+
+## 🔄 The "Session / Scraper Error" Workflow
+
+The BIP portal cookies (`XSRF_TOKEN` and `BIP_SESSION`) expire periodically. When this happens:
+
+1. The script catches the `401 Unauthorized` or invalid cookie response.
+2. It sends a critical alert to your Warning Email: **⚠️ Scraper Error!**
+3. **The background thread completely PAUSES.** It safely halts to prevent spamming the network or creating an endless retry loop.
+4. The FastAPI `/health` endpoint updates to reflect `session_expired: true`.
+5. You must update your `XSRF_TOKEN` and `BIP_SESSION` environment variables (either in your `.env` file or in your Hugging Face Space secrets) with new, valid cookies and successfully **restart** the script/Space.
+
+---
+
+## ☁️ Deployment (100% Free via Hugging Face Spaces)
+
+The absolute best way to run this script 24/7 for free is using **Hugging Face Spaces**. We have included a completely pre-configured `Dockerfile` alongside the `requirements.txt`.
+
+### How to deploy to Hugging Face:
+
+1. Go to [huggingface.co/spaces](https://huggingface.co/spaces) and click **Create new Space**.
+2. **Setup your space:**
+   * Provide a space name.
+   * License: Choose `MIT` (or whatever you prefer).
+   * **Select the Space SDK:** Choose **`Docker`** (Blank).
+   * **Space Hardware:** Choose the free `CPU basic` tier.
+   * Click Create Space.
+3. Click "Files" and upload the contents of your local folder (`main.py`, `Dockerfile`, `requirements.txt`, etc.) directly into the Space.
+4. **Setup your Secrets:** 
+   Go to the Space's **Settings** tab -> **Variables and secrets** -> **New secret**.
+   You must add the exact same variables from your local `.env`:
+   * `XSRF_TOKEN`
+   * `BIP_SESSION`
+   * `EMAIL_ADDRESS`
+   * `EMAIL_PASSWORD`
+   * `EVENT_EMAIL_RECIPIENT`
+   * `WARNING_EMAIL_RECIPIENT`
+   * `BREVO_API_KEY`
+   * `NORMAL_INTERVAL`
+   * `FAST_INTERVAL`
+   * `FAST_DURATION`
+5. **Start your App!** Go back to the App tab. The container will automatically build the image and your script will launch. The active web UI defaults to the base `/` endpoint. Note that updates to interval variables happen immediately on the next loop tick, but you must manually restart the Space to supply a new `XSRF_TOKEN`.
+
+*(Note: Hugging Face Spaces will go to sleep after ~48 hours of inactivity. Using an automated cron job from a separate small server to hit your `/health` endpoint once a day can occasionally keep the container awake.)*