{"id":43771538,"url":"https://github.com/klautnet/ts-caldav","last_synced_at":"2026-02-11T13:03:22.513Z","repository":{"id":267949097,"uuid":"902623195","full_name":"KlautNet/ts-caldav","owner":"KlautNet","description":"A lightweight and robust CalDAV client for Node.js applications, written in TypeScript. This library enables seamless integration with CalDAV servers to manage calendars, events, and tasks.","archived":false,"fork":false,"pushed_at":"2025-11-20T10:35:31.000Z","size":180,"stargazers_count":20,"open_issues_count":1,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-06T01:28:23.029Z","etag":null,"topics":["caldav","caldav-client","calendar","nodejs","package","react-native","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KlautNet.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-12T23:55:13.000Z","updated_at":"2025-12-16T15:33:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"37ff4303-89dc-46cd-bb7e-f37ebe57596d","html_url":"https://github.com/KlautNet/ts-caldav","commit_stats":null,"previous_names":["klautnet/caldavclient","klautnet/ts-caldav"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/KlautNet/ts-caldav","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlautNet%2Fts-caldav","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlautNet%2Fts-caldav/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlautNet%2Fts-caldav/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlautNet%2Fts-caldav/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KlautNet","download_url":"https://codeload.github.com/KlautNet/ts-caldav/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KlautNet%2Fts-caldav/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29333155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T12:42:24.625Z","status":"ssl_error","status_checked_at":"2026-02-11T12:41:23.344Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caldav","caldav-client","calendar","nodejs","package","react-native","typescript"],"created_at":"2026-02-05T16:36:35.398Z","updated_at":"2026-02-11T13:03:22.508Z","avatar_url":"https://github.com/KlautNet.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ts-caldav\n\n[![npm version](https://img.shields.io/npm/v/ts-caldav.svg)](https://www.npmjs.com/package/ts-caldav)\n[![Run Tests](https://github.com/KlautNet/ts-caldav/actions/workflows/test.yml/badge.svg)](https://github.com/KlautNet/ts-caldav/actions/workflows/test.yml)\n\n\u003e A lightweight, promise-based TypeScript CalDAV client for syncing calendar data in browser, Node.js, or React Native environments.\n\n**ts-caldav** helps you interact with CalDAV servers — allowing you to fetch calendars, manage events (including recurring events), and synchronize changes with minimal effort. Great for building calendar apps or integrations.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Known Working Servers](#known-working-servers)\n- [API Documentation](#api-documentation)\n- [Timezone Support](#timezone-support)\n- [Recurrence Support](#recurrence-support)\n- [Auth Notes](#auth-notes)\n- [Example: Sync Local Calendar](#example-use-case-sync-local-calendar)\n- [Limitations](#limitations)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- Credential validation with CalDAV servers\n- Automatic CalDAV endpoint discovery\n- Fetch calendar homes and individual calendars (with color support)\n- List, create (including recurring), and delete events\n- Detect event changes using `getctag` and `etag`\n- Efficient sync with diff-based event updates\n- Built for TypeScript, with full type safety\n\n## Installation\n\n```bash\nnpm install ts-caldav\n# or\npnpm install ts-caldav\n# or\nyarn add ts-caldav\n```\n\n## Quick Start\n\n```ts\nimport { CalDAVClient } from \"ts-caldav\";\n\nconst client = await CalDAVClient.create({\n  baseUrl: \"https://caldav.example.com\",\n  auth: {\n    type: \"basic\",\n    username: \"myuser\",\n    password: \"mypassword\",\n  }\n});\n\n// List calendars\nconst calendars = await client.getCalendars();\n\n// Fetch events\nconst events = await client.getEvents(calendars[0].url);\n```\n\n## Known Working Servers\n\n| Provider      | Endpoint Example |\n|:--------------|:------------------|\n| **Google**    | `https://apidata.googleusercontent.com/` |\n| **iCloud**    | `https://caldav.icloud.com/` |\n| **Yahoo**     | `https://caldav.calendar.yahoo.com` |\n| **GMX**       | `https://caldav.gmx.net` |\n| **Fastmail**  | `https://caldav.fastmail.com` |\n\n\u003e 💡 **Note:** Some servers may require enabling CalDAV support or generating app-specific passwords (especially iCloud and Fastmail).\n\n## API Documentation\n\n### `CalDAVClient.create(options)`\n\nCreates and validates a new CalDAV client instance.\n\n```ts\nconst client = await CalDAVClient.create({\n  baseUrl: \"https://caldav.example.com\",\n  auth: {\n    type: \"basic\",\n    username: \"john\",\n    password: \"secret\",\n  },\n  logRequests: true,\n});\n```\n\n### `CalDAVClient.createFromCache(options, cache)`\n\nRestores a client from cached state without re-fetching calendar home or validating credentials.\n\n```ts\nconst cache = client.exportCache();\nconst restored = await CalDAVClient.createFromCache({\n  baseUrl: \"https://caldav.example.com\",\n  auth: {\n    type: \"basic\",\n    username: \"john\",\n    password: \"secret\",\n  }\n}, cache);\n```\n\n### `getCalendars(): Promise\u003cCalendar[]\u003e`\n\nReturns an array of available calendars.\n\n### `getEvents(calendarUrl: string, options?): Promise\u003cEvent[]\u003e`\n\nFetches events within a given time range (defaults to 3 weeks ahead). When `all` is true and no range is provided, fetches all events.\n\n```ts\nconst events = await client.getEvents(calendarUrl, {\n  start: new Date(),\n  end: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),\n  all: false\n});\n```\n\n### `createEvent(calendarUrl, eventData)`\n\nSupports full-day, recurring, and timezone-aware events.\n\n```ts\nawait client.createEvent(calendar.url, {\n  summary: \"Team Sync\",\n  start: new Date(\"2025-07-01T09:00:00\"),\n  end: new Date(\"2025-07-01T10:00:00\"),\n  startTzid: \"Europe/Berlin\",\n  endTzid: \"Europe/Berlin\",\n  status: \"CONFIRMED\",\n  alarms: [\n    { action: \"DISPLAY\", trigger: \"-PT30M\", description: \"Popup reminder\" },\n    { action: \"AUDIO\", trigger: \"-PT15M\" },\n    {\n      action: \"EMAIL\",\n      trigger: \"-PT10M\",\n      summary: \"Email Reminder\",\n      description: \"Meeting coming up\",\n      attendees: [\"mailto:test@example.com\"],\n    },\n  ],\n});\n```\n\nIf `startTzid`/`endTzid` omitted, event stored in UTC.  \nTo use full timezone definitions, include your own `VTIMEZONE` in raw iCal.\n\n\u003e ⚠️ **ETag Notice:** Some CalDAV servers like Yahoo do not return an ETag header when creating events. Because ETag is required to safely update events, calling updateEvent on strict CalDAV servers may fail unless the ETag is manually retrieved via PROPFIND. You can use the getETag() function to manually fetch the ETag\n\n### `deleteEvent(calendarUrl, eventUid, etag?)`\n\nDelete by UID, optionally using ETag for safe deletion.\n\n### `syncChanges(calendarUrl, previousCtag, localEventRefs)`\n\nCompares remote state using `getctag`/`etag` and returns:\n\n- `changed`\n- `newCtag`\n- `newEvents`\n- `updatedEvents`\n- `deletedEvents`\n\n### `getEventsByHref(calendarUrl, hrefs)`\n\nFetch `.ics` data for specific events.\n\n### `getETag(href)`\n\nFetch the current ETag for an event.\n\n```ts\nconst etag = await client.getETag(\"/calendars/user/calendar-id/event-id.ics\");\nawait client.updateEvent(calendarUrl, {\n  uid: \"event-id\",\n  href: \"/calendars/user/calendar-id/event-id.ics\",\n  etag,\n  summary: \"Updated summary\",\n  start: new Date(),\n  end: new Date(Date.now() + 60 * 60 * 1000),\n});\n```\n\n\u003e ℹ️ Automatically strips weak validator prefixes (e.g., `W/\"...\"`).\n\n## Todo API\n\n### `getTodos(calendarUrl: string, options?): Promise\u003cTodo[]\u003e`\n\nFetches todos within a given range or all.\n\n### `getTodosByHref(calendarUrl: string, hrefs: string[]): Promise\u003cTodo[]\u003e`\n\nFetches full `.ics` data for specific todos.\n\n### `createTodo(calendarUrl: string, todoData)`\n\nCreates a new todo.\n\n```ts\nawait client.createTodo(calendar.url, {\n  summary: \"Buy groceries\",\n  due: new Date(\"2025-08-12T18:00:00\"),\n  alarms: [{ action: \"DISPLAY\", trigger: \"-PT1H\", description: \"Reminder\" }]\n});\n```\n\n### `updateTodo(calendarUrl: string, todo)`\n\nUpdates an existing todo.\n\n### `deleteTodo(calendarUrl: string, todoUid, etag?)`\n\nDeletes a todo by UID.\n\n### `syncTodoChanges(calendarUrl, previousCtag, localTodoRefs)`\n\nCompares remote todo list state with local references using `getctag` and `etag`.\nReturns:\n\n- `changed`\n- `newCtag`\n- `newTodos`\n- `updatedTodos`\n- `deletedTodos`\n\n## Timezone Support\n\n```ts\nawait client.createEvent(calendar.url, {\n  summary: \"Flight to SF\",\n  start: new Date(\"2025-07-01T15:00:00\"),\n  end: new Date(\"2025-07-01T18:00:00\"),\n  startTzid: \"Europe/Berlin\",\n  endTzid: \"America/Los_Angeles\",\n});\n```\n\nWhen fetching, `startTzid`/`endTzid` will be parsed for correct interpretation and normalization.\n\n## Recurrence Support\n\nSupports `freq`, `interval`, `count`, `until`, `byday`, `bymonthday`, `bymonth`.\n\n```ts\nrecurrenceRule: {\n  freq: \"MONTHLY\",\n  interval: 1,\n  byday: [\"FR\"],\n  until: new Date(\"2025-12-31\"),\n}\n```\n\n## Auth Notes\n\n- Basic Auth \u0026 OAuth2 supported\n- Works with Google, iCloud, Fastmail, Nextcloud, Radicale\n\n## Example Use Case: Sync Local Calendar\n\n```ts\nconst result = await client.syncChanges(calendar.url, lastCtag, localEventRefs);\nif (result.changed) {\n  const newEvents = await client.getEventsByHref(calendar.url, [\n    ...result.newEvents,\n    ...result.updatedEvents,\n  ]);\n  updateLocalDatabase(newEvents, result.deletedEvents);\n  saveNewCtag(result.newCtag);\n}\n```\n\n## Limitations\n\n- No WebDAV sync-token (uses getctag diffing)\n- Limited to VEVENT and VTODO components\n\n## Roadmap\n\n- Mock requests to prevent flaiky tests\n- VCARD and VJOURNAL support\n\n## Development\n\n```bash\ngit clone https://github.com/yourname/ts-caldav.git\ncd ts-caldav\nnpm install\nnpm run build\n```\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING](./contributing.md).\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./license.txt) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklautnet%2Fts-caldav","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fklautnet%2Fts-caldav","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklautnet%2Fts-caldav/lists"}