ews-calendar

## Purpose

Fetch calendar events from Microsoft Exchange Web Services (EWS) and return them as structured JSON.

## When to Use

- User asks about their calendar events ("What's on my calendar today?")
- Need to retrieve meetings for today, tomorrow, or a specific date
- Extracting meeting details: subject, time, location, organizer, body text, links

## Security Model

**Credentials are stored in OS keyring, NOT in config files:**

- **macOS**: Keychain Access (encrypted, OS-managed)
- **Linux**: libsecret / gnome-keyring (encrypted, OS-managed)

Only `EWS_URL` and `EWS_USER` are stored in OpenClaw config (non-secret). The password is retrieved securely at runtime.

## Setup

### 1. Install keyring tools (Linux only)

```bash
# Debian/Ubuntu
sudo apt install libsecret-tools gnome-keyring

# Fedora
sudo dnf install libsecret gnome-keyring

# Arch
sudo pacman -S libsecret gnome-keyring
```

macOS has Keychain built-in.

### 2. Store credentials in keyring

```bash
{baseDir}/ews-calendar-setup.sh --user "DOMAIN\\username"
```

You will be prompted for your password. This stores it securely in the OS keyring.

### 3. Configure OpenClaw

Add to `~/.openclaw/openclaw.json`:

```json5
{
  skills: {
    entries: {
      "ews-calendar": {
        enabled: true,
        env: {
          EWS_URL: "https://outlook.company.com/EWS/Exchange.asmx",
          EWS_USER: "DOMAIN\\username"
        }
      }
    }
  }
}
```

Replace with your actual Exchange URL and username.

## Usage

The skill runs `{baseDir}/ews-calendar-secure.sh` which:

1. Retrieves `EWS_PASS` from OS keyring
2. Calls the main script with all credentials in environment
3. Returns JSON output

### Command Syntax

```bash
{baseDir}/ews-calendar-secure.sh --date <DATE> [--output <FILE>] [--verbose]
```

### Parameters

- `--date` (required): Date filter
  - `YYYY-MM-DD` — specific date (e.g., `2026-03-03`)
  - `today` — today's date
  - `tomorrow` — tomorrow's date
- `--output <FILE>`: Write JSON to file instead of stdout
- `--verbose`: Enable debug logging
- `--debug-xml <FILE>`: Save raw XML response for debugging

### Output Format

Returns JSON array of calendar events:

```json
[
  {
    "subject": "Team Standup",
    "start": "2026-03-03T10:00:00Z",
    "end": "2026-03-03T10:30:00Z",
    "location": "Conference Room A",
    "organizer": "manager@company.com",
    "body": "Weekly sync meeting to discuss sprint progress...",
    "links": ["https://zoom.us/j/12345", "https://confluence.example.com/doc"]
  }
]
```

Returns empty array `[]` if no events found.

## Example Invocations

**Get today's events:**
```bash
{baseDir}/ews-calendar-secure.sh --date today
```

**Get tomorrow's events to file:**
```bash
{baseDir}/ews-calendar-secure.sh --date tomorrow --output /tmp/tomorrow.json
```

**Get specific date with debug:**
```bash
{baseDir}/ews-calendar-secure.sh --date 2026-03-03 --verbose --debug-xml /tmp/debug.xml
```

## Troubleshooting

### Password not found in keyring

```
[ERROR] Password not found in keyring for user: DOMAIN\username
[HINT] Run: ./ews-calendar-setup.sh to store credentials
```

**Solution:** Run the setup script to store your password:
```bash
{baseDir}/ews-calendar-setup.sh --user "DOMAIN\\username"
```

### Linux: secret-tool not found

```
[ERROR] 'secret-tool' not found. Install: apt install libsecret-tools
```

**Solution:** Install libsecret tools:
```bash
sudo apt install libsecret-tools gnome-keyring
```

### Linux: Keyring locked

On Linux, the keyring may be locked after login.

**Solution:** Unlock your keyring (usually happens automatically on desktop login). For headless servers, you may need to set up a keyring daemon.

### HTTP request failed

```
[ERROR] HTTP request failed with status: 401
```

**Possible causes:**
- Incorrect username or password
- Password changed — re-run setup script
- Account locked or expired

### SOAP Fault

```
[ERROR] SOAP Fault detected
Fault code: a:ErrorInvalidRequest
Fault string: The request is invalid.
```

**Possible causes:**
- Invalid EWS URL (check `EWS_URL` in config)
- Date format issue (use `YYYY-MM-DD`)
- Exchange server configuration issue

## Credential Management

### Update password (after password change)

```bash
{baseDir}/ews-calendar-setup.sh --user "DOMAIN\\username"
```

The script will overwrite the existing entry.

### Remove credentials

```bash
{baseDir}/ews-calendar-setup.sh --user "DOMAIN\\username" --delete
```

Or manually:

**macOS:**
```bash
security delete-generic-password -a "DOMAIN\\username" -s "ews-calendar"
```

**Linux:**
```bash
secret-tool clear service "ews-calendar" user "DOMAIN\\username"
```

### View stored credentials (macOS only)

```bash
security find-generic-password -a "DOMAIN\\username" -s "ews-calendar" -w
```

## Files in This Skill

```
{baseDir}/
├── SKILL.md                 # This file
├── ews-calendar.sh          # Main script (reads from env or .env)
├── ews-calendar-secure.sh   # Wrapper that gets password from keyring
├── ews-calendar-setup.sh    # Store credentials in keyring
├── templates/
│   ├── find-items.xml       # SOAP template for finding calendar items
│   └── get-item.xml         # SOAP template for getting item details
└── .env.example             # Example config for standalone usage
```

## Alternative: Standalone Usage (without keyring)

For development or testing, you can run `ews-calendar.sh` directly with a `.env` file:

1. Copy `.env.example` to `.env`
2. Fill in your credentials
3. Run: `./ews-calendar.sh --date today`

**Warning:** This stores password in plaintext. Use keyring for production.