{"_id":"@appkit/apple-calendar","_rev":"4-f45cf375227cefeee11f6240fbe85dbb","name":"@appkit/apple-calendar","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@appkit/apple-calendar","version":"0.1.0","keywords":["calendar","macos","eventkit","ical","events","native","apple"],"author":{"name":"Dave Weaver"},"license":"MIT","_id":"@appkit/apple-calendar@0.1.0","maintainers":[{"name":"davideweaver","email":"davideweaver@hotmail.com"}],"homepage":"https://github.com/dweaver/apple-calendar#readme","bugs":{"url":"https://github.com/dweaver/apple-calendar/issues"},"os":["darwin"],"bin":{"apple-calendar":"dist/bin/calendar-helper"},"dist":{"shasum":"0860d556f562048cf68a85e900cac7426f04cd45","tarball":"https://registry.npmjs.org/@appkit/apple-calendar/-/apple-calendar-0.1.0.tgz","fileCount":9,"integrity":"sha512-cUbnhuETU2VL42Irs6+HFDZWW5Cdeg5kUYWfYDYsKU+MihbGNeVtvpco6qHknQtQwHrKvzKZHW5IJxlsMR3ehA==","signatures":[{"sig":"MEUCIQCIuJ8r1Vy29TQ4DbDEUx4XtxoWSCJggOOf9TEuyxoDzQIgW2KGgccxlwUGuTrHJLMFAdabAKR0xGKmBBJ/JXkBMT0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":182017},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"cf64586c306916c8290d58915b31daebba86f33d","scripts":{"test":"jest","build":"npm run build:native && npm run build:ts","clean":"rm -rf dist","release":"commit-and-tag-version","build:ts":"tsc","postrelease":"git push --follow-tags origin main","build:native":"cd src/native && chmod +x build.sh && ./build.sh","release:first":"commit-and-tag-version --first-release","release:major":"commit-and-tag-version --release-as major","release:minor":"commit-and-tag-version --release-as minor","release:patch":"commit-and-tag-version --release-as patch","test:accepted":"npx ts-node test-accepted.ts","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"davideweaver","email":"davideweaver@hotmail.com"},"repository":{"url":"git+https://github.com/dweaver/apple-calendar.git","type":"git"},"_npmVersion":"11.4.2","description":"Native macOS Calendar integration using EventKit with participation status support","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","ts-jest":"^29.0.0","ts-node":"^10.9.2","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.19.25","commit-and-tag-version":"^12.6.1"},"_npmOperationalInternal":{"tmp":"tmp/apple-calendar_0.1.0_1765211615085_0.8238455706439618","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@appkit/apple-calendar","version":"0.1.1","keywords":["calendar","macos","eventkit","ical","events","native","apple"],"author":{"name":"Dave Weaver"},"license":"MIT","_id":"@appkit/apple-calendar@0.1.1","maintainers":[{"name":"davideweaver","email":"davideweaver@hotmail.com"}],"homepage":"https://github.com/dweaver/apple-calendar#readme","bugs":{"url":"https://github.com/dweaver/apple-calendar/issues"},"os":["darwin"],"bin":{"apple-calendar":"dist/bin/calendar-helper"},"dist":{"shasum":"810f034bb86c624f01e613762fdd21b07968510d","tarball":"https://registry.npmjs.org/@appkit/apple-calendar/-/apple-calendar-0.1.1.tgz","fileCount":9,"integrity":"sha512-dDSwVgUwtIJWt2S+NL0U1Iy29fz+/yR54lZj19dYshmmv1myTDh21rWcR9+yT5xGO2ByGclz4RJDUHFcVDrczA==","signatures":[{"sig":"MEUCIAVmqFCwtsZU9LCBUqnHnU1ahkJOOYKXeoVMCxAXCKvsAiEA/iIzhK+pUBt58w2PySRePpEUter2nyscFgiumO3O7XA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":182109},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"12c4833d74ff79e159564f50a9dc08492bdf70f9","scripts":{"test":"jest","build":"npm run build:native && npm run build:ts","clean":"rm -rf dist","release":"commit-and-tag-version","build:ts":"tsc","postrelease":"git push --follow-tags origin main","build:native":"cd src/native && chmod +x build.sh && ./build.sh","release:first":"commit-and-tag-version --first-release","release:major":"commit-and-tag-version --release-as major","release:minor":"commit-and-tag-version --release-as minor","release:patch":"commit-and-tag-version --release-as patch","test:accepted":"npx ts-node test-accepted.ts","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"davideweaver","email":"davideweaver@hotmail.com"},"repository":{"url":"git+https://github.com/dweaver/apple-calendar.git","type":"git"},"_npmVersion":"11.4.2","description":"Native macOS Calendar integration using EventKit with participation status support","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","ts-jest":"^29.0.0","ts-node":"^10.9.2","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.19.25","commit-and-tag-version":"^12.6.1"},"_npmOperationalInternal":{"tmp":"tmp/apple-calendar_0.1.1_1765211734964_0.30475385844890757","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@appkit/apple-calendar","version":"0.1.2","keywords":["calendar","macos","eventkit","ical","events","native","apple"],"author":{"name":"Dave Weaver"},"license":"MIT","_id":"@appkit/apple-calendar@0.1.2","maintainers":[{"name":"davideweaver","email":"davideweaver@hotmail.com"}],"homepage":"https://github.com/appkitstudio/apple-calendar#readme","bugs":{"url":"https://github.com/appkitstudio/apple-calendar/issues"},"os":["darwin"],"bin":{"apple-calendar":"dist/bin/calendar-helper"},"dist":{"shasum":"08545c6233b90a1086f7a407b65b7e9ba9609c1b","tarball":"https://registry.npmjs.org/@appkit/apple-calendar/-/apple-calendar-0.1.2.tgz","fileCount":9,"integrity":"sha512-OHLbXizP7p+hxJ/wN/3rUktYXi7a+YUQbPe2tPtT5PXEdVzHPCnPdHO2THVrseOd5lgClOmK3Cbk3lrn/Xzy/A==","signatures":[{"sig":"MEUCIF2vRHBqJgd4RIc5sG6J9bNqgZkOEkQOa7UoasLvlmYIAiEA22qVa3FsVmzBOlihMG8o8XAookps8mzYOQmeBGTRAwY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":182221},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"205f08444a270b3eb411ee305bdf46e972d0e4e3","scripts":{"test":"jest","build":"npm run build:native && npm run build:ts","clean":"rm -rf dist","release":"commit-and-tag-version","build:ts":"tsc","postrelease":"git push --follow-tags origin main","build:native":"cd src/native && chmod +x build.sh && ./build.sh","release:first":"commit-and-tag-version --first-release","release:major":"commit-and-tag-version --release-as major","release:minor":"commit-and-tag-version --release-as minor","release:patch":"commit-and-tag-version --release-as patch","test:accepted":"npx ts-node test-accepted.ts","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"davideweaver","email":"davideweaver@hotmail.com"},"repository":{"url":"git+https://github.com/appkitstudio/apple-calendar.git","type":"git"},"_npmVersion":"11.4.2","description":"Native macOS Calendar integration using EventKit with participation status support","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","ts-jest":"^29.0.0","ts-node":"^10.9.2","typescript":"^5.0.0","@types/jest":"^29.0.0","@types/node":"^20.19.25","commit-and-tag-version":"^12.6.1"},"_npmOperationalInternal":{"tmp":"tmp/apple-calendar_0.1.2_1765211836456_0.41746078853578594","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@appkit/apple-calendar","version":"0.1.3","description":"Native macOS Calendar integration using EventKit with participation status support","main":"dist/index.js","types":"dist/index.d.ts","bin":{"apple-calendar":"dist/bin/calendar-helper"},"scripts":{"build:native":"cd src/native && chmod +x build.sh && ./build.sh","build:ts":"tsc","build":"npm run build:native && npm run build:ts","clean":"rm -rf dist","test":"jest","test:accepted":"npx ts-node test-accepted.ts","prepublishOnly":"npm run clean && npm run build && npm test","release":"commit-and-tag-version","release:minor":"commit-and-tag-version --release-as minor","release:major":"commit-and-tag-version --release-as major","release:patch":"commit-and-tag-version --release-as patch","release:first":"commit-and-tag-version --first-release","postrelease":"git push --follow-tags origin main"},"keywords":["calendar","macos","eventkit","ical","events","native","apple"],"author":{"name":"Dave Weaver"},"license":"MIT","os":["darwin"],"engines":{"node":">=18.0.0"},"devDependencies":{"@types/jest":"^29.0.0","@types/node":"^20.19.25","commit-and-tag-version":"^12.6.1","jest":"^29.0.0","ts-jest":"^29.0.0","ts-node":"^10.9.2","typescript":"^5.0.0"},"repository":{"type":"git","url":"git+https://github.com/appkitstudio/apple-calendar.git"},"bugs":{"url":"https://github.com/appkitstudio/apple-calendar/issues"},"homepage":"https://github.com/appkitstudio/apple-calendar#readme","publishConfig":{"access":"public"},"_id":"@appkit/apple-calendar@0.1.3","gitHead":"e19d980301d904162ef2d6b0b096d72e845bd937","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-x7OOfuzqbOfKPs7el1jX3sXq0vKdXmSpzWxqbSMFRT8CBpQ8uiSXMhXHy7WEbvyGnlKcK03Tk9qfkyQHgpRuXg==","shasum":"77288f1e91ceb6037438edb2dfd2b517bee288e0","tarball":"https://registry.npmjs.org/@appkit/apple-calendar/-/apple-calendar-0.1.3.tgz","fileCount":9,"unpackedSize":182391,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDRlZt+H579eFxV7woHlKfjvy9vAYTF9/g8dLcDVJ4qGwIhAKohj9+yVsrVfOUItJ9six/08z75ItK8u2yYxpwxHSQF"}]},"_npmUser":{"name":"davideweaver","email":"davideweaver@hotmail.com"},"directories":{},"maintainers":[{"name":"davideweaver","email":"davideweaver@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/apple-calendar_0.1.3_1765213515842_0.8662103208187752"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-08T16:33:34.965Z","modified":"2025-12-08T17:05:16.227Z","0.1.0":"2025-12-08T16:33:35.232Z","0.1.1":"2025-12-08T16:35:35.107Z","0.1.2":"2025-12-08T16:37:16.612Z","0.1.3":"2025-12-08T17:05:16.012Z"},"bugs":{"url":"https://github.com/appkitstudio/apple-calendar/issues"},"author":{"name":"Dave Weaver"},"license":"MIT","homepage":"https://github.com/appkitstudio/apple-calendar#readme","keywords":["calendar","macos","eventkit","ical","events","native","apple"],"repository":{"type":"git","url":"git+https://github.com/appkitstudio/apple-calendar.git"},"description":"Native macOS Calendar integration using EventKit with participation status support","maintainers":[{"name":"davideweaver","email":"davideweaver@hotmail.com"}],"readme":"# apple-calendar\n\nNative macOS Calendar integration using EventKit with participation status support.\n\n## Features\n\n- ✅ **Native EventKit Integration** - Direct access to macOS Calendar via Swift\n- ✅ **Participation Status** - Filter events by accepted/declined/tentative/pending\n- ✅ **TypeScript API** - Clean, type-safe interface for Node.js\n- ✅ **Pre-compiled Binary** - No Swift toolchain required for end users\n- ✅ **Zero Dependencies** - Minimal runtime footprint\n- ✅ **Fast** - Native performance, no parsing overhead\n\n## Installation\n\n```bash\nnpm install @appkit/apple-calendar\n```\n\n**Requirements:**\n\n- macOS 10.14 or later\n- Node.js 18 or later\n\n## Quick Start\n\n```typescript\nimport { getEventsToday, ParticipationStatus } from \"@appkit/apple-calendar\";\n\n// Get today's accepted events\nconst events = await getEventsToday({\n  participationStatus: [ParticipationStatus.Accepted],\n});\n\nconsole.log(events);\n```\n\n## API Reference\n\n### Event Queries\n\n#### `getEventsToday(options?)`\n\nGet events for today (00:00 - 23:59).\n\n```typescript\nconst events = await getEventsToday({\n  calendars: [\"Work\", \"Personal\"],\n  includeAllDay: false,\n  participationStatus: [ParticipationStatus.Accepted],\n});\n```\n\n**Options:**\n\n- `calendars?: string[]` - Filter by calendar names\n- `includeAllDay?: boolean` - Include all-day events (default: `false`)\n- `participationStatus?: ParticipationStatus[]` - Filter by status\n\n#### `getEventsFromToday(days, options?)`\n\nGet events from today through N days ahead.\n\n```typescript\n// Get next 7 days of accepted events\nconst events = await getEventsFromToday(7, {\n  participationStatus: [ParticipationStatus.Accepted],\n});\n```\n\n#### `getUpcomingEvents(hours?, options?)`\n\nGet upcoming events starting from now.\n\n```typescript\n// Get events in the next 24 hours\nconst events = await getUpcomingEvents(24);\n```\n\n#### `getEventsBetween(startDate, endDate, options?)`\n\nGet events in a specific date range.\n\n```typescript\nconst start = new Date(\"2024-01-01\");\nconst end = new Date(\"2024-01-31\");\nconst events = await getEventsBetween(start, end);\n```\n\n#### `queryEvents(options)`\n\nLow-level query with full control.\n\n```typescript\nconst result = await queryEvents({\n  startDate: new Date(),\n  endDate: new Date(Date.now() + 86400000),\n  calendars: [\"Work\"],\n  includeAllDay: true,\n  participationStatus: [\n    ParticipationStatus.Accepted,\n    ParticipationStatus.Tentative,\n  ],\n});\n\nconsole.log(result.events);\nconsole.log(result.errors); // Any errors that occurred\n```\n\n### Calendar Queries\n\n#### `listCalendars()`\n\nGet all available calendars.\n\n```typescript\nconst calendars = await listCalendars();\n\ncalendars.forEach((cal) => {\n  console.log(`${cal.title} (${cal.type}) - ${cal.color}`);\n});\n```\n\n## Types\n\n### `ParticipationStatus`\n\nEnum for event participation status:\n\n```typescript\nenum ParticipationStatus {\n  Unknown = 0, // Status not set\n  Pending = 1, // Invitation pending\n  Accepted = 2, // User accepted\n  Declined = 3, // User declined\n  Tentative = 4, // User marked as maybe\n}\n```\n\n### `CalendarEvent`\n\nEvent object returned by queries:\n\n```typescript\ninterface CalendarEvent {\n  id: string;\n  title: string;\n  startDate: Date;\n  endDate: Date;\n  calendar: string;\n  location?: string;\n  isAllDay: boolean;\n  participationStatus: ParticipationStatus;\n  notes?: string;\n  url?: string;\n  isRecurring: boolean;\n}\n```\n\n### `Calendar`\n\nCalendar object returned by `listCalendars()`:\n\n```typescript\ninterface Calendar {\n  title: string;\n  type: string;\n  isWritable: boolean;\n  color?: string;\n}\n```\n\n## Examples\n\n### Filter Out Declined/Tentative Events\n\n```typescript\nimport {\n  getEventsFromToday,\n  ParticipationStatus,\n} from \"@appkit/apple-calendar\";\n\n// Only get events I've accepted\nconst acceptedEvents = await getEventsFromToday(7, {\n  participationStatus: [ParticipationStatus.Accepted],\n});\n```\n\n### Query Specific Calendars\n\n```typescript\nimport { getEventsToday } from \"@appkit/apple-calendar\";\n\n// Only work events\nconst workEvents = await getEventsToday({\n  calendars: [\"Work Calendar\"],\n});\n\n// Multiple calendars\nconst events = await getEventsToday({\n  calendars: [\"Work\", \"Personal\", \"Family\"],\n});\n```\n\n### Get All Events Including All-Day\n\n```typescript\nimport { getEventsToday } from \"@appkit/apple-calendar\";\n\nconst allEvents = await getEventsToday({\n  includeAllDay: true,\n});\n```\n\n### List Available Calendars\n\n```typescript\nimport { listCalendars } from \"@appkit/apple-calendar\";\n\nconst calendars = await listCalendars();\nconsole.log(\"Available calendars:\");\ncalendars.forEach((cal) => {\n  console.log(`- ${cal.title} (${cal.type})`);\n});\n```\n\n### Custom Date Range with Filtering\n\n```typescript\nimport { queryEvents, ParticipationStatus } from \"@appkit/apple-calendar\";\n\nconst result = await queryEvents({\n  startDate: new Date(\"2024-01-01\"),\n  endDate: new Date(\"2024-12-31\"),\n  calendars: [\"Work\"],\n  includeAllDay: false,\n  participationStatus: [ParticipationStatus.Accepted],\n});\n\nconsole.log(`Found ${result.events.length} events`);\nif (result.errors && result.errors.length > 0) {\n  console.error(\"Errors:\", result.errors);\n}\n```\n\n## Command-Line Usage\n\nThe native binary can also be used directly:\n\n```bash\n# List calendars\n./dist/bin/calendar-helper calendars\n\n# Get today's events\n./dist/bin/calendar-helper events today\n\n# Get next 7 days\n./dist/bin/calendar-helper events today+7\n\n# Get events with filters\n./dist/bin/calendar-helper events \\\n  --days 7 \\\n  --calendars \"Work,Personal\" \\\n  --participation 2 \\\n  --include-all-day\n\n# Custom date range\n./dist/bin/calendar-helper events \\\n  --start 2024-01-01T00:00:00Z \\\n  --end 2024-01-31T23:59:59Z\n```\n\n## Building from Source\n\n```bash\n# Install dependencies\nnpm install\n\n# Build native binary and TypeScript\nnpm run build\n\n# Or build separately\nnpm run build:native  # Build Swift binary\nnpm run build:ts      # Build TypeScript\n```\n\n**Build Requirements:**\n\n- Xcode Command Line Tools\n- Swift 5.0 or later\n\n## How It Works\n\nThis package includes a pre-compiled Swift binary that uses Apple's EventKit framework to query calendar data. The TypeScript wrapper provides a clean API that executes the binary and parses its JSON output.\n\n**Architecture:**\n\n1. TypeScript API receives query\n2. Constructs command-line arguments\n3. Executes Swift binary (EventKit)\n4. Parses JSON response\n5. Returns typed results\n\n**Why Native?**\n\n- `icalBuddy` doesn't support participation status\n- AppleScript Calendar integration is limited\n- EventKit is the official, most capable API\n\n## Privacy & Permissions\n\nThis package requires Calendar access. On first use:\n\n1. macOS will prompt for Calendar access\n2. Grant access to your terminal or app\n3. Future calls will work without prompts\n\n**Privacy:** All queries are local-only. No data leaves your machine.\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please open an issue or PR.\n\n## Troubleshooting\n\n**Binary not found:**\n\n```bash\nnpm run build:native\n```\n\n**Permission denied:**\n\n- System Settings → Privacy & Security → Calendars\n- Enable access for Terminal or your app\n\n**No events returned:**\n\n- Check calendar names with `listCalendars()`\n- Verify date ranges are correct\n- Check participation status filters\n\n**Build errors:**\n\n- Ensure Xcode Command Line Tools are installed: `xcode-select --install`\n- Verify Swift version: `swift --version` (needs 5.0+)\n","readmeFilename":"README.md"}