# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

IMAP to Nextcloud Calendar Importer - A Python utility that monitors an IMAP mailbox for emails with ICS calendar attachments and imports them to a Nextcloud calendar via CalDAV.

## Commands

### Build and Run
```bash
# Build Docker image
docker build -t imap-calendar-importer .

# Run with Docker Compose (continuous mode)
docker-compose up -d

# Run once and exit
docker-compose run --rm imap-calendar-importer

# View logs
docker-compose logs -f

# Rebuild after code changes
docker-compose up -d --build
```

### Direct Python Execution
```bash
# Install dependencies
pip install -r requirements.txt

# Run directly (requires .env or environment variables set)
python imap_calendar_importer.py
```

### Testing
```bash
# Create virtual environment and install dependencies
python -m venv .venv
.venv/bin/pip install -r requirements.txt

# Run all tests
.venv/bin/pytest tests/ -v

# Run specific test class
.venv/bin/pytest tests/test_imap_calendar_importer.py::TestMatchesFilter -v

# Run with coverage (requires pytest-cov)
.venv/bin/pytest tests/ --cov=imap_calendar_importer --cov-report=term-missing
```

## Architecture

Single-file Python application (`imap_calendar_importer.py`) with one main class:

**`IMAPCalendarImporter`** - Handles the complete workflow:
1. `connect_imap()` - Establishes IMAP connection (SSL/TLS, STARTTLS, or plain)
2. `connect_caldav()` - Connects to Nextcloud CalDAV and discovers target calendar
3. `process_emails()` - Searches for unseen emails, extracts ICS attachments
4. `extract_ics_attachments()` - Parses MIME messages, applies summary filtering
5. `import_ics_to_calendar()` - Creates new or updates existing events by UID

**Execution Modes:**
- Continuous: Polls mailbox every `CHECK_INTERVAL` seconds
- One-time: Processes once and exits (`RUN_ONCE=true`)

## Configuration

All configuration via environment variables (see `.env.sample`). Key settings:
- `IMAP_*` - Mail server connection (server, port, credentials, SSL options)
- `CALDAV_*` - Nextcloud connection (URL, credentials, calendar name)
- `SUMMARY_FILTER*` - Event filtering by title (contains/regex/exact, with inversion)
- `RUN_ONCE` / `CHECK_INTERVAL` - Execution mode control

## Dependencies

- `caldav` - CalDAV client library
- `icalendar` - ICS parsing
- `urllib3` - HTTP client (used by caldav)