Dan Head
c87a99f570
- IMAP mailbox monitoring with SSL/TLS, STARTTLS and plain connection support - ICS attachment extraction from emails and import to Nextcloud via CalDAV - Create or update calendar events by UID to avoid duplicates - Event filtering by summary (contains, regex or exact match, with inversion) - Deduplication by regex pattern extracted from event summaries - Move or mark processed emails as seen after import - Continuous polling mode and one-time run mode - Fully configurable via environment variables - Docker and Docker Compose support - Test suite with pytest
82 lines
2.4 KiB
Markdown
82 lines
2.4 KiB
Markdown
# 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)
|