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

### 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)

### Installation

```bash
# Clone the repository
git clone ssh://git@gitea.soliverez.com.ar/alvaro/caldavpuller.git
cd caldavpuller

# Build the project
cargo build --release

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

### 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
```

### 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
```

## 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

### 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
```

### Complete Configuration Example

See `config/example.toml` for a comprehensive configuration example with all available options.

## 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.

## More Information

- **Development & Design**: See [DEVELOPMENT.md](DEVELOPMENT.md)
- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md)
- **License**: See [LICENSE](LICENSE)

## 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