EventKit Integration

Expert-level EventKit patterns for macOS/iOS applications. Specialized for reminder systems, permission handling, and bidirectional sync.

When to Use

Use this skill when:

• Integrating EventKit Reminders or Events
• Handling EventKit permissions and authorization
• Implementing bidirectional sync with external data
• Using zero-width character steganography for identity tracking
• Batch EventKit operations
• Building zombie task self-healing logic

Core Principles

1. Actor-Based Service

import EventKit
import Foundation

actor EventKitService {
    private let eventStore = EKEventStore()
    private var timeFlowCalendar: EKCalendar?

    func initialize() async throws {
        let remindersGranted = try await eventStore.requestFullAccessToReminders()
        let eventsGranted = try await eventStore.requestFullAccessToEvents()

        guard remindersGranted && eventsGranted else {
            throw EventKitError.permissionDenied
        }

        timeFlowCalendar = try await getOrCreateTimeFlowCalendar()
    }
}

2. Calendar Management

private func getOrCreateTimeFlowCalendar() async throws -> EKCalendar {
    let calendars = eventStore.calendars(for: .reminder)

    if let existing = calendars.first(where: { $0.title == "TimeFlow" }) {
        return existing
    }

    let calendar = EKCalendar(for: .reminder, eventStore: eventStore)
    calendar.title = "TimeFlow"
    calendar.source = eventStore.defaultCalendarForNewReminders()?.source

    try eventStore.saveCalendar(calendar, commit: true)
    return calendar
}

3. Batch Fetch Pattern

func fetchAllReminders() async throws -> [ReminderSnapshot] {
    guard let calendar = timeFlowCalendar else {
        throw EventKitError.calendarNotFound
    }

    let incompletePredicate = eventStore.predicateForIncompleteReminders(
        withDueDateStarting: nil, ending: nil, calendars: [calendar]
    )

    return try await withCheckedThrowingContinuation { continuation in
        eventStore.fetchReminders(matching: incompletePredicate) { reminders in
            if let reminders = reminders {
                let snapshots = reminders.map { $0.toSnapshot() }
                continuation.resume(returning: snapshots)
            } else {
                continuation.resume(returning: [])
            }
        }
    }
}

Permission Handling

Authorization Flow

enum EventKitError: Error, LocalizedError {
    case permissionDenied
    case calendarNotFound

    var errorDescription: String? {
        switch self {
        case .permissionDenied:
            return "需要访问提醒事项的权限"
        case .calendarNotFound:
            return "找不到 TimeFlow 日历"
        }
    }
}

Check Before Operations

func updateReminder(_ reminder: EKReminder) async throws {
    // Verify calendar exists before operation
    guard timeFlowCalendar != nil else {
        throw EventKitError.calendarNotFound
    }

    try eventStore.save(reminder, commit: true)
}

Sync Patterns

Zero-Width Character Steganography

Embed identity signatures invisibly in EventKit notes:

func buildNotes(from task: IdentityMap) -> String {
    let baseNotes = task.notesSnapshot ?? ""

    // Embed zero-width signature for identity tracking
    let signature = "\u{200B}TIMEFLOW:\(task.localUUID)\u{200C}"

    return baseNotes.isEmpty ? signature : baseNotes + "\n" + signature
}

func extractSignature(from notes: String?) -> String? {
    guard let notes = notes else { return nil }

    let pattern = #"\u{200B}TIMEFLOW:([^\u{200B}]+)\u{200C}"#
    guard let regex = try? NSRegularExpression(pattern: pattern),
          let match = regex.firstMatch(in: notes, range: NSRange(notes.startRange, in: notes)) else {
        return nil
    }

    guard let range = Range(match.range(at: 1), in: notes) else { return nil }
    return String(notes[range])
}

Critical: Prevent Sync Loops

When creating new IdentityMap from EventKit, bind immediately:

private func findOrCreateIdentityMap(for reminder: ReminderSnapshot) -> IdentityMap? {
    if let existing = swiftDataService.findIdentityMap(by: reminder.id) {
        return existing
    }

    let newMap = swiftDataService.createIdentityMap(
        title: reminder.title,
        projectName: nil,
        contextTags: []
    )

    // CRITICAL: Bind immediately and mark as clean
    // This prevents: New Map -> Dirty -> Push -> Duplicate infinite loop
    newMap.ekIdentifier = reminder.id
    newMap.lastSyncDate = Date()
    newMap.isDirty = false

    return newMap
}

Batch Operations

Batch Delete with Chunking

func deleteReminders(identifiers: [String]) async throws -> Int {
    var deletedCount = 0
    let batchSize = 500

    for id in identifiers {
        if let reminder = eventStore.calendarItem(withIdentifier: id) as? EKReminder {
            try eventStore.remove(reminder, commit: false)
            deletedCount += 1
        }

        // Commit in batches for performance
        if deletedCount % batchSize == 0 {
            try eventStore.commit()
        }
    }

    // Final commit
    try eventStore.commit()
    return deletedCount
}

Zombie Task Self-Healing

Grace Period Pattern

Don't delete immediately created tasks:

nonisolated func purgeZombieTasksBackground() {
    let context = ModelContext(container)
    context.autosaveEnabled = false

    // Grace period: 1 hour
    // Newly created tasks have nil ekID, but aren't zombies
    let oneHourAgo = Date().addingTimeInterval(-3600)

    let descriptor = FetchDescriptor<IdentityMap>(
        predicate: #Predicate { $0.ekIdentifier == nil && $0.createdAt < oneHourAgo }
    )

    let zombies = (try? context.fetch(descriptor)) ?? []
    guard !zombies.isEmpty else { return }

    // Group by title to identify duplicates
    let grouped = Dictionary(grouping: zombies, by: { $0.titleSnapshot })

    for (title, tasks) in grouped where tasks.count > 1 {
        // Keep oldest, delete duplicates
        let sorted = tasks.sorted { $0.createdAt < $1.createdAt }
        for task in sorted.dropFirst() {
            context.delete(task)
        }
    }

    try? context.save()
}

Testing Patterns

Mock EventKit for Tests

@MainActor
final class EventKitServiceTests: XCTestCase {
    var mockService: MockEventKitService!

    override func setUp() async throws {
        try await super.setUp()
        mockService = MockEventKitService()
    }

    func testFetchAllReminders() async throws {
        // Given: Mock reminders
        mockService.addReminder(id: "EK-1", title: "Task 1")
        mockService.addReminder(id: "EK-2", title: "Task 2")

        // When: Fetch
        let reminders = try await mockService.fetchAllReminders()

        // Then: Verify
        XCTAssertEqual(reminders.count, 2)
    }
}

Best Practices

Common Pitfalls

Running EventKit Tests

# Test EventKit integration
xcodebuild test -scheme YourApp \
  -destination 'platform=macOS' \
  -only-testing:'YourAppTests/EventKitTests/testFetchAllReminders'