@dtechvision/executor-caldav

CalDAV integration plugin for Executor. Connect to any CalDAV server (Nextcloud, Fastmail, iCloud, Google Calendar via CalDAV, etc.) and manage calendars and events through Executor's unified tool catalog.

Features

• Auto-discovery — discovers principal URL and calendar-home set via standard CalDAV PROPFIND
• List calendars — enumerates available calendars with display names
• List events — queries events in a date range using CalDAV REPORT
• Get / add / update / delete events — full CRUD via iCalendar VEVENT
• Multiple auth methods — Basic auth, API key placements, OAuth2 bearer, or no auth
• UUID-based filenames — events stored as <uid>.ics for predictable URLs

Install

bun add @dtechvision/executor-caldav

This package is a peer to @executor-js/sdk. Your host app must already provide the SDK.

Usage

import { createExecutor } from "@executor-js/sdk";
import { caldavPlugin } from "@dtechvision/executor-caldav";

const executor = await createExecutor({
  plugins: [caldavPlugin()] as const,
});

// Register a CalDAV server
await executor.caldav.addServer({
  url: "https://cloud.example.com/remote.php/dav/",
  name: "Work Calendar",
  slug: "work",
  authenticationTemplate: [{ kind: "basic", slug: "basic" }],
});

// Create a connection with credentials
await executor.connections.create({
  owner: "org",
  name: "default",
  integration: "work",
  template: "basic",
  values: {
    username: "[email protected]",
    password: "app-password",
  },
});

// Tool catalog now includes CalDAV tools
const tools = await executor.tools.list();
// -> list_calendars, list_events, get_event, add_event, update_event, delete_event

// List calendars
const result = await executor.execute("tools.work.org.default.list_calendars", {});

// List events for the next week
const today = new Date();
const start = today.toISOString().slice(0, 10) + "T00:00:00Z";
const end = new Date(today.getTime() + 7 * 86400000).toISOString().slice(0, 10) + "T00:00:00Z";

const events = await executor.execute("tools.work.org.default.list_events", {
  calendarUrl: "/remote.php/dav/calendars/alice/personal/",
  start,
  end,
});

Auth methods

| Kind | Description | Connection values | |------|-------------|-------------------| | none | Open server | none | | basic | Username + password as Authorization: Basic <base64> | username, password | | apikey | Custom header/query placements | per-placement variables | | oauth2 | OAuth bearer token | token |

Tools per connection

| Tool | Description | Approval | |------|-------------|----------| | list_calendars | Discover principal, calendar-home, and list calendars | No | | list_events | List events in a calendar between two ISO dates | No | | get_event | Get a single event by UID | No | | add_event | Add a new VEVENT to a calendar | Yes | | update_event | Overwrite an existing event by UID | Yes | | delete_event | Delete an event by UID | Yes |

What is CalDAV?

CalDAV is an open standard (RFC 4791) for accessing calendar data over HTTP/WebDAV. Any server that implements the spec should work — the plugin speaks standard PROPFIND, REPORT, PUT, GET, and DELETE.

Tested servers

| Server | Status | Notes | |--------|--------|-------| | Nextcloud (SabreDAV) | Verified | Auto-discovery, calendar listing, event CRUD | | Fastmail | Untested | Should work — follows RFC 4791 | | Google Calendar (CalDAV) | Untested | Requires app-specific password for Basic auth | | iCloud | Untested | Requires app-specific password |

If you use a server not listed and hit an issue, open a GitHub issue with the response XML and we can tighten the parser.

Using with Effect

Import from the source directly for the raw Effect-shaped plugin:

import { caldavPlugin } from "@dtechvision/executor-caldav/src/sdk/plugin";

The promise-wrapped surface (@dtechvision/executor-caldav) is recommended for host-app integration.

License

MIT