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

# EWS Calendar Skill

Extract calendar events from Microsoft Exchange via EWS API and return them as structured JSON.

## Features

- Fetch calendar events for today, tomorrow, or specific dates
- Returns structured JSON with subject, time, location, organizer, body text, and links
- Secure credential storage using OS keyring (macOS Keychain / Linux libsecret)
- NTLM authentication support
- URL extraction from event bodies and locations

## Prerequisites

- **curl** - HTTP requests
- **xmllint** - XML parsing (part of libxml2)
- **macOS**: Keychain Access (built-in)
- **Linux**: libsecret-tools + gnome-keyring

### Linux Setup

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

# Fedora
sudo dnf install libsecret gnome-keyring

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

## Installation

### 1. Clone the repository

```bash
git clone <repo-url>
cd ews-skill
```

### 2. Store credentials in OS keyring

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

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

### 3. Configure environment

Set environment variables or create a `.env` file:

```bash
EWS_URL=https://outlook.company.com/EWS/Exchange.asmx
EWS_USER=DOMAIN\\username
EWS_EMAIL=user@company.com  # optional, defaults to EWS_USER
```

## Usage

### Basic Commands

```bash
# Get today's events
./ews-calendar-secure.sh --date today

# Get tomorrow's events
./ews-calendar-secure.sh --date tomorrow

# Get events for a specific date
./ews-calendar-secure.sh --date 2026-03-03

# Write output to file
./ews-calendar-secure.sh --date today --output events.json

# Enable verbose logging
./ews-calendar-secure.sh --date today --verbose

# Debug raw XML response
./ews-calendar-secure.sh --date today --debug-xml response.xml
```

### Command Options

| Option | Description |
|--------|-------------|
| `-d, --date DATE` | Filter events by date (YYYY-MM-DD, `today`, or `tomorrow`) |
| `-o, --output FILE` | Writ...