wohnbot/README.md

# wohn-bot

A Python bot that monitors Berlin's public housing portal (inberlinwohnen.de) and WG rooms (wgcompany.de). Sends Telegram notifications when new listings appear and can automatically apply to some listings.

## What it does

- Monitors inberlinwohnen.de for new apartment listings from 6 housing companies (HOWOGE, Gewobag, Degewo, Gesobau, Stadt und Land, WBM)
- Monitors wgcompany.de for WG room listings with configurable filters
- Sends Telegram notifications with listing details
- Logs listing times to CSV for pattern analysis
- Auto-apply feature for supported housing companies

## Auto-Apply Support

All six housing companies monitored by this bot now support the autopilot (automatic application) feature. Use autopilot with care — automatic form submission is destructive and may send many requests if configured incorrectly.

| Company | Status | Notes |
|---------|--------|-------|
| HOWOGE | Working | Fully automated and tested |
| Degewo | Working | Uses Wohnungshelden portal; automated |
| Stadt und Land | Working | Embedded form handled automatically |
| Gewobag | Working | Wohnungshelden iframe handled automatically |
| Gesobau | Working | Automated form submission implemented |
| WBM | Working | Automated form submission implemented |
| WGcompany | Monitoring only | WGcompany monitoring only (no autopilot) |

Recommended precautions:

- Run with `/autopilot off` while testing new selectors or after changing config.
- Inspect `data/applications.json` and saved screenshots in `data/` after enabling autopilot.
- Respect site terms of use and rate limits; set `CHECK_INTERVAL` appropriately.

## Setup

### Docker (recommended)

```bash
cp .env.example .env
# Edit .env with your credentials
docker compose up -d
```

### Local development

```bash
pip install -r requirements.txt
playwright install chromium

export TELEGRAM_BOT_TOKEN=your_token
export TELEGRAM_CHAT_ID=your_chat_id
# ... other env vars

python monitor.py
```

## Configuration

### Required environment variables

- `TELEGRAM_BOT_TOKEN` - Bot token from @BotFather
- `TELEGRAM_CHAT_ID` - Your Telegram chat ID

### InBerlin login (required for auto-apply)

- `INBERLIN_EMAIL` - Your inberlinwohnen.de email
- `INBERLIN_PASSWORD` - Your inberlinwohnen.de password

### Form data (for auto-apply)

- `FORM_ANREDE` - Salutation (Herr/Frau)
- `FORM_VORNAME` - First name
- `FORM_NACHNAME` - Last name
- `FORM_EMAIL` - Email address
- `FORM_PHONE` - Phone number
- `FORM_STRASSE` - Street name
- `FORM_HAUSNUMMER` - House number
- `FORM_PLZ` - Postal code
- `FORM_ORT` - City
- `FORM_PERSONS` - Number of persons in household
- `FORM_CHILDREN` - Number of children
- `FORM_INCOME` - Monthly net income

### WGcompany filters

- `WGCOMPANY_ENABLED` - Enable WGcompany monitoring (true/false)
- `WGCOMPANY_MIN_SIZE` - Minimum room size in sqm
- `WGCOMPANY_MAX_SIZE` - Maximum room size in sqm
- `WGCOMPANY_MIN_PRICE` - Minimum price in EUR
- `WGCOMPANY_MAX_PRICE` - Maximum price in EUR
- `WGCOMPANY_BEZIRK` - District filter (optional)

## Telegram Commands

- `/autopilot on|off` - Enable or disable automatic applications (use `/autopilot on` or `/autopilot off`).
- `/status` - Show current status and statistics (autopilot state, application counts by company).
- `/plot` - Generate and send a weekly listing-patterns plot (`data/weekly_plot.png`).
- `/errorrate` - Generate and send an autopilot success vs failure plot (`data/error_rate.png`).
- `/help` - Show available commands and usage information.

Note: The bot only processes commands from the configured `TELEGRAM_CHAT_ID`. Use `/autopilot off` while testing selector changes or after modifying configuration to avoid accidental submissions.

## Data files

All data is stored in the `data/` directory:

- `listings.json` - Previously seen inberlinwohnen listings
- `wgcompany_listings.json` - Previously seen WGcompany listings
- `applications.json` - Application history
- `listing_times.csv` - Time series data for listings
- `state.json` - Runtime state (autopilot toggle)
- `monitor.log` - Application logs

## Debugging

When applications fail, the bot saves:

- Screenshots to `data/*.png`
- Page HTML to `data/debug_page.html`

Check these files to understand why an application failed.

## Code Structure

The bot has been modularized for better maintainability. The main components are:

- `main.py`: The entry point for the bot.
- `handlers/`: Contains company-specific handlers for auto-apply functionality. Each company has its own handler file:
  - `howoge_handler.py`
  - `gewobag_handler.py`
  - `degewo_handler.py`
  - `gesobau_handler.py`
  - `stadtundland_handler.py`
  - `wbm_handler.py`
- `application_handler.py`: Orchestrates the application process by delegating to the appropriate handler.
- `telegram_bot.py`: Handles Telegram bot commands and notifications.

The `handlers/` directory includes a `BaseHandler` class that provides shared functionality for all company-specific handlers.

## Unit Tests

The project includes unit tests to ensure functionality and reliability. Key test files:

- `tests/test_telegram_bot.py`: Tests the Telegram bot's commands and messaging functionality.
- `tests/test_error_rate_plot.py`: Tests the error rate plot generator for autopilot applications.

### Running Tests

To run the tests, use:

```bash
pytest tests/
```

Ensure all dependencies are installed and the environment is configured correctly before running the tests.

## Workflow Diagram

```mermaid
graph TD
    A[Start] --> B[Fetch Listings]
    B --> C{New Listings?}
    C -->|Yes| D[Log to CSV]
    C -->|Yes| E[Send Telegram Notification]
    C -->|Yes| F{Autopilot Enabled?}
    F -->|Yes| G[Auto-Apply to Listings]
    F -->|No| H[Save to Applications.json]
    C -->|No| I[End]
    D --> I
    E --> I
    G --> H
    H --> I
```

This diagram illustrates the workflow of the bot, from fetching listings to logging, notifying, and optionally applying to new listings.

## License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) License.

You are free to:

- **Share** — copy and redistribute the material in any medium or format
- **Adapt** — remix, transform, and build upon the material

Under the following terms:

- **Attribution** — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
- **NonCommercial** — You may not use the material for commercial purposes.

For more details, see the [full license text](https://creativecommons.org/licenses/by-nc/4.0/).