# Calendar Tool - Documentation

## Overview

Calendar Tool provides unified calendar management for Sofiia agent via CalDAV protocol. Currently supports Radicale server, extensible to Google Calendar, iCloud, etc.

## Architecture

```
┌─────────────┐     CalDAV      ┌─────────────┐
│   Sofiia    │ ──────────────► │   Radicale  │
│   Agent     │ ◄──────────────  │   Server    │
└─────────────┘                 └─────────────┘
       │
       ▼
┌─────────────────────────┐
│   Calendar Service     │
│   (FastAPI)            │
├─────────────────────────┤
│ • /v1/calendar/*       │
│ • /v1/tools/calendar   │
│ • Reminder Worker      │
└─────────────────────────┘
```

## Configuration

### Environment Variables

```bash
# Radicale Server URL
RADICALE_URL=https://caldav.daarion.space

# Database
DATABASE_URL=sqlite:///./calendar.db
```

## API Endpoints

### Connection Management

#### Connect Radicale Account
```bash
POST /v1/calendar/connect/radicale
{
  "workspace_id": "ws1",
  "user_id": "user1", 
  "username": "calendar_user",
  "password": "secure_password"
}
```

#### List Accounts
```bash
GET /v1/calendar/accounts?workspace_id=ws1&user_id=user1
```

### Calendar Operations

#### List Calendars
```bash
GET /v1/calendar/calendars?account_id=acc_1
```

#### List Events
```bash
GET /v1/calendar/events?account_id=acc_1&time_min=2024-01-01&time_max=2024-12-31
```

#### Create Event
```bash
POST /v1/calendar/events?account_id=acc_1
{
  "title": "Meeting with Team",
  "start": "2024-01-15T10:00:00",
  "end": "2024-01-15T11:00:00",
  "timezone": "Europe/Kiev",
  "location": "Conference Room A",
  "description": "Weekly sync",
  "attendees": ["team@example.com"]
}
```

#### Update Event
```bash
PATCH /v1/calendar/events/{uid}?account_id=acc_1
{
  "title": "Updated Title",
  "description": "New description"
}
```

#### Delete Event
```bash
DELETE /v1/calendar/events/{uid}?account_id=acc_1
```

### Reminders

#### Set Reminder
```bash
POST /v1/calendar/reminders?account_id=acc_1
{
  "event_uid": "evt-123",
  "remind_at": "2024-01-15T09:00:00",
  "channel": "inapp"  # inapp, telegram, email
}
```

## Unified Tool Endpoint

For Sofiia agent, use the unified `/v1/tools/calendar` endpoint:

```bash
POST /v1/tools/calendar
{
  "action": "create_event",
  "workspace_id": "ws1",
  "user_id": "user1",
  "account_id": "acc_1",
  "params": {
    "title": "Doctor Appointment",
    "start": "2024-02-01T14:00:00",
    "end": "2024-02-01T14:30:00",
    "timezone": "Europe/Kiev"
  }
}
```

### Available Actions

| Action | Description | Required Params |
|--------|-------------|-----------------|
| `connect` | Connect Radicale account | `username`, `password` |
| `list_calendars` | List calendars | `account_id` |
| `list_events` | List events | `account_id`, `calendar_id` (optional) |
| `get_event` | Get single event | `account_id`, `uid` |
| `create_event` | Create event | `account_id`, `title`, `start`, `end` |
| `update_event` | Update event | `account_id`, `uid` |
| `delete_event` | Delete event | `account_id`, `uid` |
| `set_reminder` | Set reminder | `account_id`, `event_uid`, `remind_at` |

## Deployment

### Docker Compose

```bash
cd ops
docker-compose -f docker-compose.calendar.yml up -d
```

This starts:
- Radicale CalDAV server on port 5232
- Caddy reverse proxy with TLS on port 8443

### Local Development

```bash
cd services/calendar-service
pip install -r requirements.txt
uvicorn main:app --reload --port 8001
```

## Testing

```bash
cd services/calendar-service
pytest tests/ -v
```

## Security Notes

- Passwords are stored in plaintext (in production, use encryption)
- Caddy handles TLS termination
- Radicale uses HTTP Basic Auth
- No external API dependencies (self-hosted)