Metadata-Version: 2.4
Name: sentinel2-data-alerts
Version: 0.2.0
Summary: Monitor Copernicus Data Space for new Sentinel-2, Sentinel-1, and Landsat imagery and receive Slack alerts.
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: duckdb>=1.4.4
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: requests>=2.32.5
Requires-Dist: shapely>=2.1.2
Provides-Extra: predict
Requires-Dist: satpass>=0.1.1; extra == 'predict'
Description-Content-Type: text/markdown

# sentinel2-data-alerts

Monitor [Copernicus Data Space](https://dataspace.copernicus.eu/) for new satellite imagery over your sites of interest and receive instant Slack alerts with direct links to the Copernicus Browser.

## Supported Sensors

| Sensor | Collection | Type |
|--------|-----------|------|
| **Sentinel-2** | `SENTINEL-2` L1C | Optical (SWIR false-colour) |
| **Sentinel-1** | `SENTINEL-1` GRD | SAR (VV/VH polarisation) |
| **Landsat-8** | `LANDSAT-8` L1 | Optical (SWIR) |
| **Landsat-9** | `LANDSAT-9` L1 | Optical (SWIR) |

## Installation

```bash
pip install sentinel2-data-alerts
```

Or install from source:

```bash
git clone https://github.com/your-org/sentinel2-data-alerts.git
cd sentinel2-data-alerts
pip install .
```

To include next-overpass predictions in Slack alerts (powered by [satpass](https://pypi.org/project/satpass/)):

```bash
pip install "sentinel2-data-alerts[predict]"
```

## Configuration

Create a `.env` file in the directory where you'll run the tool (or copy `.env.example`):

```bash
cp .env.example .env
```

Then fill in your credentials:

```env
# Copernicus Data Space credentials
# Register at https://dataspace.copernicus.eu/
CDSE_USERNAME=your-email@example.com
CDSE_PASSWORD=your-password

# Default Slack webhook URL for notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/triggers/YOUR/WEBHOOK/URL

# Polling interval in seconds (default: 3600)
POLL_INTERVAL_SECONDS=300

# How many hours back to query for new products (default: 24)
QUERY_HOURS=12

# Path to DuckDB database (default: ./sentinel2_reports.duckdb)
# DB_PATH=./sentinel2_reports.duckdb
```

## Usage

### Add monitoring sites

```bash
# Basic — uses the default Slack webhook
sentinel2-alerts addsite "Huelva Refinery" 37.18 -6.88

# With a custom webhook for this site
sentinel2-alerts addsite "Rotterdam Port" 51.95 4.13 --webhook https://hooks.slack.com/triggers/YOUR/OTHER/WEBHOOK
```

### Manage sites

```bash
# List all sites and their status
sentinel2-alerts listsites

# Remove a site
sentinel2-alerts removesite "Huelva Refinery"
```

### Per-site webhook management

Each site can optionally have its own Slack webhook URL. If not set, the default `SLACK_WEBHOOK_URL` from your `.env` is used.

```bash
# Set a custom webhook for an existing site
sentinel2-alerts setwebhook "Rotterdam Port" https://hooks.slack.com/triggers/YOUR/WEBHOOK

# Remove the custom webhook (revert to default)
sentinel2-alerts removewebhook "Rotterdam Port"
```

### Start polling

```bash
# Start the monitoring loop (polls every POLL_INTERVAL_SECONDS)
sentinel2-alerts poll

# Or simply (poll is the default command):
sentinel2-alerts
```

The poller will:
1. Authenticate with Copernicus Data Space
2. Query for new products across **all four sensors**
3. Check if any products intersect your monitored sites
4. Send a Slack alert for each new product with:
   - Product name and acquisition date
   - A shortened link to view in Copernicus Browser
   - A quicklook thumbnail (when available)
   - **Next overpass forecast** for the same sensor at that location (requires `[predict]` extras)
5. Track reported products in a local DuckDB database to avoid duplicate alerts

### Send a test notification

```bash
sentinel2-alerts test
```

### Use a custom database path

```bash
# Via CLI flag
sentinel2-alerts --db /path/to/my.duckdb listsites

# Or via environment variable
DB_PATH=/path/to/my.duckdb sentinel2-alerts poll
```

## Running with `python -m`

If you prefer not to use the CLI entry point:

```bash
python -m sentinel2_data_alerts poll
python -m sentinel2_data_alerts addsite "My Site" 51.5 -0.1
```

## Overpass Prediction (Optional)

When installed with `pip install "sentinel2-data-alerts[predict]"`, each Slack alert automatically includes a forecast of the next satellite overpass for that sensor at the alerted site's location.

This is powered by [satpass](https://pypi.org/project/satpass/), which sources acquisition plans from ESA (Sentinel-1/2 KML plans) and USGS (Landsat cycle data). Predictions are cached locally and refreshed every 12 hours.

You can also use the overpass module directly:

```python
from sentinel2_data_alerts.overpass import get_next_overpass, format_overpass_line

result = get_next_overpass(lat=51.5, lon=-0.1, collection="SENTINEL-2")
# {'satellite': 'sentinel2', 'platform': 'S2A', 'date': datetime(...), 'orbit': 94}

print(format_overpass_line(result))
# :crystal_ball: Next overpass: *2026-07-23 10:56 UTC* (S2A) orbit 94
```

Supported collections: `SENTINEL-2`, `SENTINEL-1`, `LANDSAT-8`, `LANDSAT-9`.

## Development

```bash
git clone https://github.com/your-org/sentinel2-data-alerts.git
cd sentinel2-data-alerts
pip install -e ".[predict]"
```

