[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81327":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":12,"contributorsCount":12,"subscribersCount":12,"size":12,"stars1d":12,"stars7d":12,"stars30d":12,"stars90d":12,"forks30d":12,"starsTrendScore":12,"compositeScore":14,"rankGlobal":9,"rankLanguage":9,"license":15,"archived":16,"fork":16,"defaultBranch":17,"hasWiki":18,"hasPages":16,"topics":19,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":12,"starSnapshotCount":12,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},81327,"icalendar","cayde-6\u002Ficalendar","cayde-6","TypeScript CalDAV\u002FiCalendar CLI toolkit",null,"TypeScript",21,0,43,40,"MIT License",false,"main",true,[20,21,22,23,5,24],"caldav","calendar","cli","ical","typescript","2026-06-12 04:01:32","# icalendar\n\n[![Release](https:\u002F\u002Fgithub.com\u002Fcayde-6\u002Ficalendar\u002Factions\u002Fworkflows\u002Frelease.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fcayde-6\u002Ficalendar\u002Factions\u002Fworkflows\u002Frelease.yml)\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F%40cayde-6%2Ficalendar)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@cayde-6\u002Ficalendar)\n[![CI](https:\u002F\u002Fgithub.com\u002Fcayde-6\u002Ficalendar\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fcayde-6\u002Ficalendar\u002Factions\u002Fworkflows\u002Fci.yml)\n[![Coverage](https:\u002F\u002Fcodecov.io\u002Fgh\u002Fcayde-6\u002Ficalendar\u002Fbranch\u002Fmain\u002Fgraph\u002Fbadge.svg)](https:\u002F\u002Fcodecov.io\u002Fgh\u002Fcayde-6\u002Ficalendar)\n\n![icalendar hero](.\u002Fassets\u002Fhero.png)\n\nTypeScript CLI for **CalDAV calendars**, **iCalendar events**, and **automation-friendly workflows**.\n\nPublished package: [`@cayde-6\u002Ficalendar`](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@cayde-6\u002Ficalendar)\n\n`icalendar` gives scripts, automations, and integrations a thin, reliable interface for:\n- listing calendars\n- listing events\n- creating events\n- updating events\n- deleting events\n- sending attendee invites through CalDAV\u002FiCalendar\n- setting a friendly organizer display name (for example `Calendar Bot`)\n\nIt was validated live against **real iCloud CalDAV** with create → update → invite → delete flows.\n\n## Why this exists\n\nMost CalDAV tooling is either too low-level for automation or too UI-centric for scripts and integrations. This repo wraps the ugly parts behind a small CLI and a layered codebase that is easy to embed, extend, and reason about.\n\n## Features\n\n- ESM TypeScript CLI with clean layering\n- published npm package: `@cayde-6\u002Ficalendar`\n- CalDAV access via `tsdav`\n- invite-ready ICS generation\n- attendee support for create\u002Fupdate flows\n- configurable organizer common name via env\n- text and JSON output modes\n- runtime-safe handling of `--help` \u002F `--version`\n- live-tested against iCloud CalDAV create → update → delete flows\n- GitHub Release + npm Trusted Publishing workflow\n- architecture and integration docs for embedders\n\n## Install\n\n### From npm\n\n```bash\nnpm install -g @cayde-6\u002Ficalendar\nicalendar --help\nicalendar --version\n```\n\n### From source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fcayde-6\u002Ficalendar.git\ncd icalendar\nnpm install\nnpm run build\n```\n\n### Use as a local CLI\n\n```bash\nnpm link\nicalendar --help\n```\n\n### Use without linking\n\n```bash\nnode --import tsx src\u002Fcli.ts --help\nnode dist\u002Fcli.js calendars list\n```\n\n## Configuration\n\nCopy the example file:\n\n```bash\ncp .env.example .env\n```\n\nRequired configuration:\n\n```env\nCALDAV_SERVER_URL=https:\u002F\u002Fcaldav.icloud.com\u002F\nCALDAV_USERNAME=primary.attendee@example.test\nCALDAV_PASSWORD=app-specific-password\n```\n\nOptional configuration:\n\n```env\nCALDAV_CALENDAR_NAME=Example Calendar\nCALDAV_ORGANIZER_NAME=Calendar Bot\nCALDAV_RANGE_START=2026-05-07T00:00:00+02:00\nCALDAV_RANGE_END=2026-05-08T00:00:00+02:00\nCALDAV_EXPAND_RECURRING=true\n```\n\n### iCloud setup: generate an app-specific password\n\nFor iCloud CalDAV you need an **app-specific password**. Your normal Apple ID password will not work.\n\nHow to generate it:\n\n1. Go to your Apple account settings: \u003Chttps:\u002F\u002Faccount.apple.com\u002F>\n2. Sign in with the Apple account that owns the iCloud calendar\n3. Open the **Sign-In and Security** section\n4. Find **App-Specific Passwords**\n5. Create a new password, for example named `icalendar`\n6. Copy the generated password and put it into:\n\n```env\nCALDAV_PASSWORD=your-app-specific-password\n```\n\nRecommended iCloud values:\n\n```env\nCALDAV_SERVER_URL=https:\u002F\u002Fcaldav.icloud.com\u002F\nCALDAV_USERNAME=your-apple-id-email@example.com\nCALDAV_PASSWORD=your-app-specific-password\n```\n\nIf authentication fails, the most common cause is using the normal Apple ID password instead of the generated app-specific one.\n\n## Quick examples\n\n### List calendars\n\n```bash\nicalendar calendars list\nicalendar calendars list --json\n```\n\n### List events\n\n```bash\nicalendar events list\nicalendar events list --json\n```\n\n### Create an event\n\n```bash\nicalendar events create \\\n  --summary \"Family sync\" \\\n  --start \"2026-05-07T18:00:00+02:00\" \\\n  --end \"2026-05-07T18:30:00+02:00\" \\\n  --description \"Agenda review\" \\\n  --location \"Belgrade\" \\\n  --attendees \"primary.attendee@example.test,secondary.attendee@example.test\"\n```\n\n### Update an event\n\n```bash\nicalendar events update \\\n  --url \"https:\u002F\u002Fcaldav.example.com\u002Fcalendars\u002Fpersonal\u002Fevent.ics\" \\\n  --summary \"Family sync\" \\\n  --start \"2026-05-07T18:00:00+02:00\" \\\n  --end \"2026-05-07T18:45:00+02:00\" \\\n  --attendees \"primary.attendee@example.test,secondary.attendee@example.test\"\n```\n\n### Delete an event\n\n```bash\nicalendar events delete \"https:\u002F\u002Fcaldav.example.com\u002Fcalendars\u002Fpersonal\u002Fevent.ics\"\n```\n\n## Programmatic usage\n\nThe package can also be used as a library.\n\n### CalDAV gateway\n\n```ts\nimport { TsdavCalendarGateway } from '@cayde-6\u002Ficalendar'\nimport type { RuntimeConfig } from '@cayde-6\u002Ficalendar'\n\nconst config: RuntimeConfig = {\n  serverUrl: 'https:\u002F\u002Fcaldav.icloud.com\u002F',\n  username: 'user@example.com',\n  password: 'app-specific-password',\n}\n\nconst gateway = new TsdavCalendarGateway(config)\nconst calendars = await gateway.listCalendars()\nconst events = await gateway.listEvents({ calendar: calendars[0] })\n```\n\n### ICS generation\n\n```ts\nimport { buildEventIcs } from '@cayde-6\u002Ficalendar'\nimport type { EventDraft } from '@cayde-6\u002Ficalendar'\n\nconst draft: EventDraft = {\n  summary: 'Team standup',\n  start: '2026-05-07T10:00:00+02:00',\n  end: '2026-05-07T10:15:00+02:00',\n  attendees: [{ email: 'colleague@example.com' }],\n}\n\nconst ics = buildEventIcs(draft, undefined, 'organizer@example.com', 'Calendar Bot')\n```\n\nExported types: `Calendar`, `CalendarEvent`, `EventDraft`, `EventAttendee`, `EventMutationResult`, `EventUpdate`, `TimeRange`, `CalendarGatewayPort`, `RuntimeConfig`.\n\n## Automation integration\n\nIf another automation, script, or service wants to adopt this CLI, start here:\n- [Automation integration guide](.\u002Fdocs\u002Fautomation-integration.md)\n- [Architecture](.\u002Fdocs\u002Farchitecture.md)\n\nShort version:\n1. install dependencies\n2. provide `.env`\n3. run `npm run build`\n4. use `icalendar ...` or `node dist\u002Fcli.js ...`\n5. prefer `--json` for machine consumers\n\n## Development\n\n```bash\nnpm run check\nnpm run build\nnpm test\nnpm run test:coverage\nnpm run verify\n```\n\n## Test strategy\n\nCurrent coverage includes:\n- calendar selection rules\n- time range defaults\n- command parsing for create\u002Fupdate\u002Fdelete\n- text\u002Fjson runtime output\n- env config parsing\n- ICS generation and ICS parsing\n- runtime error rendering\n\n## Architecture\n\n`icalendar` follows a layered CLI structure:\n\n```text\ncli -> app(commands\u002Fuse-cases) -> domain -> infra -> presentation -> shared\n```\n\nThe CalDAV SDK stays in `infra\u002F`, use-cases orchestrate, domain stays provider-agnostic, and renderers only format output.\n\n## Reliability notes\n\n- invite flows were smoke-tested live against iCloud CalDAV\n- `--help` and `--version` do not require env credentials\n- organizer display name is configurable with `CALDAV_ORGANIZER_NAME`\n- attendee invites work in both create and update flows\n- CLI defaults to the first calendar when `CALDAV_CALENDAR_NAME` is omitted\n- `npm run verify` covers typecheck, build, tests, and coverage reporting\n\n## Releases\n\n- GitHub releases are created from pushed tags: `v*`\n- npm publishing is wired through **npm Trusted Publishing** from GitHub Actions\n- current public package name: `@cayde-6\u002Ficalendar`\n\n## Repo docs\n\n- [Automation integration guide](.\u002Fdocs\u002Fautomation-integration.md)\n- [Architecture](.\u002Fdocs\u002Farchitecture.md)\n- [Release checklist](.\u002Fdocs\u002Frelease-checklist.md)\n- [Versioning policy](.\u002Fdocs\u002Fversioning.md)\n- [Changelog](.\u002FCHANGELOG.md)\n- [Contributing guide](.\u002FCONTRIBUTING.md)\n- [Security policy](.\u002FSECURITY.md)\n- GitHub Actions: `.github\u002Fworkflows\u002Fci.yml`, `.github\u002Fworkflows\u002Frelease.yml`\n\n## License\n\nMIT\n\n","`icalendar` 是一个用 TypeScript 编写的 CalDAV\u002FiCalendar 命令行工具包，旨在为脚本、自动化和集成提供便捷的接口。其核心功能包括日历和事件的增删改查、发送参会者邀请以及设置友好的组织者显示名称等，支持通过环境变量配置自定义选项。项目采用模块化设计，易于嵌入和扩展，并且经过了与真实 iCloud CalDAV 服务的交互测试，确保了稳定性和可靠性。适用于需要对日历进行编程控制或自动化处理的场景，如个人时间管理应用开发、团队协作工具构建等。",2,"2026-06-11 04:04:39","CREATED_QUERY"]