feat: add generic CalDAV calendar data source (#42)

* feat: add generic CalDAV calendar data source

Add @aris/source-caldav package that fetches calendar events from any
CalDAV server via tsdav + ical.js.

- Supports Basic auth and OAuth via explicit authMethod discriminant
- serverUrl provided at construction time, not hardcoded
- Optional timeZone for correct local day boundaries
- Credentials cleared from memory after client login
- Failed calendar fetches logged, not silently dropped
- Login promise cached with retry on failure

Co-authored-by: Ona <no-reply@ona.com>

* fix: deduplicate concurrent fetchEvents calls

Co-authored-by: Ona <no-reply@ona.com>

* fix: timezone-aware signals, low-priority cancelled events

- computeSignals uses startOfDay(timeZone) for 'later today' boundary
- Cancelled events get urgency 0.1, excluded from context inProgress/nextEvent

Co-authored-by: Ona <no-reply@ona.com>

---------

Co-authored-by: Ona <no-reply@ona.com>
This commit is contained in:
2026-02-28 16:09:11 +00:00
committed by GitHub
parent 82ac2b577d
commit 40ad90aa2d
16 changed files with 1485 additions and 1 deletions

View File

@@ -0,0 +1,58 @@
# @aris/source-caldav
A FeedSource that fetches calendar events from any CalDAV server.
## Usage
```ts
import { CalDavSource } from "@aris/source-caldav"
// Basic auth (Nextcloud, Radicale, Baikal, iCloud, etc.)
const source = new CalDavSource({
serverUrl: "https://caldav.example.com",
authMethod: "basic",
username: "user",
password: "pass",
lookAheadDays: 7, // optional, default: 0 (today only)
timeZone: "America/New_York", // optional, default: UTC
})
// OAuth
const source = new CalDavSource({
serverUrl: "https://caldav.provider.com",
authMethod: "oauth",
accessToken: "...",
refreshToken: "...",
tokenUrl: "https://provider.com/oauth/token",
})
```
### iCloud
Use your Apple ID email as the username and an [app-specific password](https://support.apple.com/en-us/102654):
```ts
const source = new CalDavSource({
serverUrl: "https://caldav.icloud.com",
authMethod: "basic",
username: "you@icloud.com",
password: "<app-specific-password>",
})
```
## Testing
```bash
bun test
```
### Live test
`bun run test:live` connects to a real CalDAV server and prints all events to the console. It prompts for:
- **CalDAV server URL** — e.g. `https://caldav.icloud.com`
- **Username** — your account email
- **Password** — your password (or app-specific password for iCloud)
- **Look-ahead days** — how many days beyond today to fetch (default: 0)
The script runs both `fetchContext` and `fetchItems`, printing the calendar context (in-progress events, next event, today's count) followed by each event with its title, time, location, signals, and attendees.