caldavpuller/README.md

# CalDAV Calendar Synchronizer

A Rust-based command-line tool that synchronizes calendar events between Zoho Calendar and Nextcloud via CalDAV protocol. It allows you to selectively import events from specific Zoho calendars into a single Nextcloud calendar.

## Features

- **Selective Calendar Import**: Choose which Zoho calendars to sync from
- **Single Target Calendar**: All events consolidated into one Nextcloud calendar
- **Timezone Support**: Handles events across different timezones correctly
- **Next Week Focus**: Optimized for importing events for the next 7 days
- **Simple Data Transfer**: Extracts only title, time, and duration as requested
- **Secure Authentication**: Uses app-specific passwords for security
- **Dry Run Mode**: Preview what would be synced before making changes

## Quick Start

### 1. Prerequisites

- Rust 1.70+ (for building from source)
- Zoho account with CalDAV access
- Nextcloud instance with CalDAV enabled
- App-specific passwords for both services (recommended)

### 2. Installation

```bash
# Clone the repository
git clone <repository-url>
cd caldavpuller

# Build the project
cargo build --release

# The binary will be at target/release/caldav-sync
```

### 3. Configuration

Copy the example configuration file:

```bash
cp config/example.toml config/config.toml
```

Edit `config/config.toml` with your settings:

```toml
# Zoho CalDAV Configuration (Source)
[zoho]
server_url = "https://caldav.zoho.com/caldav"
username = "your-zoho-email@domain.com"
password = "your-zoho-app-password"

# Select which calendars to import
selected_calendars = ["Work Calendar", "Personal Calendar"]

# Nextcloud Configuration (Target)
[nextcloud]
server_url = "https://your-nextcloud-domain.com"
username = "your-nextcloud-username"
password = "your-nextcloud-app-password"
target_calendar = "Imported-Zoho-Events"
create_if_missing = true
```

### 4. First Run

Test the configuration with a dry run:

```bash
./target/release/caldav-sync --debug --list-events
```

Perform a one-time sync:

```bash
./target/release/caldav-sync --once
```

## Configuration Details

### Zoho Setup

1. **Enable CalDAV in Zoho**:
   - Go to Zoho Mail Settings → CalDAV
   - Enable CalDAV access
   - Generate an app-specific password

2. **Find Calendar Names**:
   ```bash
   ./target/release/caldav-sync --list-events --debug
   ```
   This will show all available calendars.

### Nextcloud Setup

1. **Enable CalDAV**:
   - Usually enabled by default
   - Access at `https://your-domain.com/remote.php/dav/`

2. **Generate App Password**:
   - Go to Settings → Security → App passwords
   - Create a new app password for the sync tool

3. **Target Calendar**:
   - The tool can automatically create the target calendar
   - Or create it manually in Nextcloud first

## Usage

### Command Line Options

```bash
caldav-sync [OPTIONS]

Options:
  -c, --config <CONFIG>          Configuration file path [default: config/default.toml]
  -s, --server-url <SERVER_URL>  CalDAV server URL (overrides config file)
  -u, --username <USERNAME>      Username for authentication (overrides config file)
  -p, --password <PASSWORD>      Password for authentication (overrides config file)
      --calendar <CALENDAR>      Calendar name to sync (overrides config file)
  -d, --debug                    Enable debug logging
      --once                     Perform a one-time sync and exit
      --full-resync              Force a full resynchronization
      --list-events              List events and exit
  -h, --help                     Print help
  -V, --version                  Print version
```

### Common Operations

1. **List Available Events**:
   ```bash
   caldav-sync --list-events
   ```

2. **One-Time Sync**:
   ```bash
   caldav-sync --once
   ```

3. **Full Resynchronization**:
   ```bash
   caldav-sync --full-resync
   ```

4. **Override Configuration**:
   ```bash
   caldav-sync --username "user@example.com" --password "app-password" --once
   ```

## Configuration Reference

### Complete Configuration Example

```toml
[server]
url = "https://caldav.zoho.com/caldav"
username = "your-email@domain.com"
password = "your-app-password"
timeout = 30

[calendar]
name = "Work Calendar"
color = "#4285F4"

[sync]
sync_interval = 300
sync_on_startup = true
weeks_ahead = 1
dry_run = false

[filters]
exclude_patterns = ["Cancelled:", "BLOCKED"]
min_duration_minutes = 5
max_duration_hours = 24

[logging]
level = "info"
file = "caldav-sync.log"
```

### Environment Variables

You can also use environment variables:

```bash
export CALDAV_SERVER_URL="https://caldav.zoho.com/caldav"
export CALDAV_USERNAME="your-email@domain.com"
export CALDAV_PASSWORD="your-app-password"
export CALDAV_CALENDAR="Work Calendar"

./target/release/caldav-sync
```

## Security Considerations

1. **Use App Passwords**: Never use your main account password
2. **Secure Configuration**: Set appropriate file permissions on config files
3. **SSL/TLS**: Always use HTTPS connections
4. **Log Management**: Be careful with debug logs that may contain sensitive data

## Troubleshooting

### Common Issues

1. **Authentication Failures**:
   - Verify app-specific passwords are correctly set up
   - Check that CalDAV is enabled in both services
   - Ensure correct server URLs

2. **Calendar Not Found**:
   - Use `--list-events` to see available calendars
   - Check calendar name spelling
   - Verify permissions

3. **Timezone Issues**:
   - Events are automatically converted to UTC internally
   - Original timezone information is preserved
   - Check system timezone if times seem off

4. **SSL Certificate Issues**:
   - Ensure server URLs use HTTPS
   - Check if custom certificates need to be configured

### Debug Mode

Enable debug logging for troubleshooting:

```bash
caldav-sync --debug --list-events
```

This will show detailed HTTP requests, responses, and processing steps.

## Development

### Building from Source

```bash
# Clone the repository
git clone <repository-url>
cd caldavpuller

# Build in debug mode
cargo build

# Build in release mode
cargo build --release

# Run tests
cargo test

# Check code formatting
cargo fmt --check

# Run linter
cargo clippy
```

### Project Structure

```
caldavpuller/
├── src/
│   ├── main.rs              # CLI interface and entry point
│   ├── lib.rs               # Library interface
│   ├── config.rs            # Configuration management
│   ├── caldav_client.rs     # CalDAV HTTP client
│   ├── event.rs             # Event data structures
│   ├── timezone.rs          # Timezone handling
│   ├── calendar_filter.rs   # Calendar filtering logic
│   ├── sync.rs              # Synchronization engine
│   └── error.rs             # Error types and handling
├── config/
│   ├── default.toml         # Default configuration
│   └── example.toml         # Example configuration
├── tests/
│   └── integration_tests.rs # Integration tests
├── Cargo.toml               # Rust project configuration
└── README.md                # This file
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the debug output with `--debug`
3. Open an issue on the project repository
4. Include your configuration (with sensitive data removed) and debug logs