device_calendar_plus

Changed

• Breaking: updateEvent and deleteEvent act on one thing — a one-off
  event or a single occurrence — and take instanceId instead of eventId.
  A bare ID of a recurring series is refused with
  DeviceCalendarException(invalidArguments) and nothing is written. Moving a
  series' start through updateEvent used to shift the whole series and drop
  every earlier occurrence without an error; series-wide changes now go
  through updateRecurring / deleteRecurring (#175).

  Migrating:

  • updateEvent(eventId: event.instanceId, …) →
    updateEvent(instanceId: event.instanceId, …). Same for deleteEvent.
    For a one-off event instanceId equals eventId, so nothing else
    changes.
  • updateEvent(eventId: seriesId, …) on a recurring event →
    updateRecurring(seriesId, EventSpan.allEvents, …). startDate /
    endDate map to start / duration; the other fields are the same.
  • deleteEvent(eventId: seriesId) on a recurring event →
    deleteRecurring(seriesId, EventSpan.allEvents).

Added

• updateRecurring takes reminders (a Patch<List<Duration>>), to set or
  clear reminders across a series, as updateEvent does for one event (#175).

Fixed

Recurring events

• updateRecurring with thisAndFollowing on an event that doesn't repeat
  is refused with invalidArguments on both platforms, and nothing is
  written. iOS matched the timestamp against the event itself, so it edited
  or deleted the whole event and reported success (#124).
• Android: moving an all-day series with updateRecurring lands on the day
  you asked for. The new start was compared in the wrong timezone: west of
  UTC a same-day start was refused and a day-earlier move onto a day the rule
  doesn't generate got through; east of UTC (e.g. Sydney) a one-day move did
  nothing (#144).
• iOS: switching a timed series to all-day with updateRecurring keeps every
  occurrence on its calendar day. West of UTC the series gained an extra
  occurrence the day before its start and lost its last one (#187).
• iOS: updateRecurring refuses a start move with no new rule when it breaks
  any day the rule pins, as Android does. A yearly
  BYMONTH=11;BYDAY=4TH series could be moved to a Thursday in December
  (#188).
• createEvent and updateRecurring refuse a recurrence rule whose FREQ
  isn't DAILY/WEEKLY/MONTHLY/YEARLY, or that is malformed, with
  invalidArguments and write nothing, on both platforms. iOS createEvent
  dropped the rule and saved a one-off event; Android stored FREQ=HOURLY
  as an hourly series (#125).
• Android: updateEvent or deleteEvent on one occurrence of a series on a
  synced calendar (Google, Exchange) no longer hides the whole series when
  the series hasn't synced yet (#163).

Native modals

• The native modals (showEventModal, showCreateEventModal) always
  complete; several paths used to leave the await hanging or crash (#123):
  • One modal at a time: a call while another modal is showing throws
    DeviceCalendarException(operationFailed) straight away. It used to
    orphan the first call's future and, on iOS, fail to present, so both
    hung.
  • Android: rotating the device while a modal is open no longer drops the
    result; the future completes when the calendar app returns.
  • iOS: swiping the view modal down completes the future.
  • iOS: a modal no longer silently fails to appear when the app is already
    presenting a sheet; it's presented on top.
  • With no Activity (Android) or window (iOS) to present from, the call
    throws DeviceCalendarException(operationFailed), as openAppSettings
    does. iOS used to crash, and Android threw an unconverted
    PlatformException.
  • Android: showEventModal on an event that doesn't exist throws
    DeviceCalendarException(notFound), as iOS does. It used to open the
    calendar app on nothing and complete normally.

Permissions

• iOS 18: answering a full-access prompt with Add Events Only reports
  writeOnly rather than notDetermined, so a createEvent straight after
  the prompt passes its permission check (#137).

Changed

• Minimum supported SDK is now Flutter 3.44 / Dart 3.12. Android migrated to
  Flutter's built-in Kotlin, so the KGP deprecation warning no longer prints
  on every flutter build (#133).
• Event times are stored at whole seconds on both platforms. iOS always did
  this; Android now floors the times it writes, so a start passed with
  milliseconds reads back without them (#165).

Fixed

Recurring events

• updateRecurring with a new rule anchors the series on the first day that
  rule generates, on both platforms. Changing a weekly series to another
  weekday left its start on the old day, so the first occurrence was stranded
  there. A rule that generates no occurrence at all is refused with
  invalidArguments and the series is left untouched (#140).
• Android: updateEvent or deleteEvent on a single occurrence of a
  recurring event in a local calendar no longer makes the other occurrences
  disappear, the earlier ones for good (#153).
• Android: deleteRecurring with thisAndFollowing also removes an
  occurrence on or after the split that had been edited on its own, matching
  iOS (#157).
• Android: updateRecurring with thisAndFollowing carries an occurrence on
  or after the split that had been edited on its own into the new series,
  with its edits, as iOS does. It used to stay on the old series, listed next
  to a duplicate, and on a synced calendar the edit was lost (#158).
• Android: getEvent resolves all-day recurring instance IDs (it always
  returned null) and returns a recurring master's real end date instead of a
  zero-length one (#122).

Synced calendars

• Android: deletes and recurring edits on a synced calendar (Google,
  Exchange) now reach the server. The plugin wrote them as the calendar's
  own sync adapter, so they were never uploaded and the next sync brought a
  deleted event back, one duplicate per cycle. Per-occurrence cancellations
  upload too (#132, #161).

Listing events

• Android: listEvents returns an all-day event when the window is a sub-day
  slice of its date (e.g. 10:00–11:00), and orders all-day events by their
  local midnight among timed events in non-UTC zones, as iOS does (#122).
• listEvents rejects an endDate before startDate with ArgumentError,
  like the other date-range methods, and answers an empty range
  (endDate == startDate) with no events on both platforms (#162).

Calendars

• updateCalendar and deleteCalendar throw the documented readOnly for a
  calendar that can't be modified, on both platforms. iOS used to surface a
  refused delete as operationFailed; Android renamed or deleted any row it
  was handed (#126).
• Android createCalendar refuses a non-local accountType with readOnly,
  as listSources already reports and iOS already does for non-creatable
  sources, instead of leaving a phantom calendar the account's sync adapter
  can wipe (#126).
• createCalendar / updateCalendar throw ArgumentError for a colorHex
  that isn't #RRGGBB (the # optional) instead of storing it silently as
  black, and forward the canonical #RRGGBB to the platform (#126).
• deleteCalendar('') throws ArgumentError, like the other mutations (#126).
• Android listCalendars no longer crashes on a provider row with a NULL
  display name (#126).

Docs

• CalendarSource.supportsCalendarCreation, CreateCalendarOptionsIos and
  CreateCalendarOptionsAndroid describe what the code actually does: iOS
  creates under iCloud or local, Android under the local account type (#126).

Platform packages: device_calendar_plus_android 0.8.0, device_calendar_plus_ios 0.8.0.

Fixed

• iOS: a grant is honoured immediately. The first time a user allowed access, the very next call could still fail with permissionDenied until the app was restarted, because EventKit briefly kept reporting notDetermined after the grant (#134).
• showCreateEventModal needs no calendar permission on Android or iOS 17+ — the system editor saves with its own access — so it now works as a fallback after a denial, and autoPermissions never prompts for it. On iOS 16 and below the in-process editor still requires full access (#121, #141).
• Android read endpoints report permissionDenied instead of a silent empty result when READ_CALENDAR isn't held, and full-tier mutations require both READ_CALENDAR and WRITE_CALENDAR, matching iOS (#121).
• iOS: createEvent with a named calendarId under write-only access reports permissionDenied (with a hint) instead of a misleading notFound (#121).

Docs

• CalendarPermissionStatus.denied spells out the difference between the permanent denial hasPermissions reports and the just-declined prompt requestPermissions reports.

Per-event color lands, plus one rename to swallow.

Added

• Event.colorHex — the event's custom color as #RRGGBB, with a parsed Event.color getter (read-only, mirrors Calendar.colorHex). Android reads it from EVENT_COLOR; null when the event just uses its calendar's color, and always null on iOS (EventKit has no per-event colors). No write support (#117).

Changed

• Breaking: WeeklyRecurrence's wkst field and constructor parameter are renamed to weekStart, matching the spelled-out naming of the other recurrence fields. The emitted RRULE is unchanged (still WKST=). Update WeeklyRecurrence(wkst: …) call sites and .wkst reads to weekStart.

Ships device_calendar_plus 0.8.0 and device_calendar_plus_android 0.7.1. The platform interface and iOS packages are unchanged.

Docs + packaging polish. No code or behaviour changes.

Changed

• Added the device pub.dev topic (dropped federated to stay within the five-topic limit).

Docs

• Slimmed the README to an overview plus a getting-started snippet, with the worked examples moved into focused topic guides under doc/.
• Trimmed the public API doc comments to the consumer-facing contract and removed native-API implementation details.

Feature release. App-facing API is additive; device_calendar_plus_platform_interface has breaking signature changes for platform implementers.

Added

• Write-only access — requestPermissions(level: CalendarAccessLevel.writeOnly) for the gentler add-only prompt (#89).
• Automatic permissions — DeviceCalendar.instance.autoPermissions = AutoPermissionMode.asNeeded | .full; methods request access on first use (#90).
• Optional calendarId — omit it on createEvent to write to the default calendar (#88).
• Event reminders — reminders: List<Duration> on create, Patch<List<Duration>> on update, Event.reminders read back; minute-granular relative offsets (#87).

Fixed

• Android: honest permissionDenied (not "no writable calendar") when a default can't be resolved (#112); tighter denial reporting (#108).
• Docs: iOS write-only re-prompts and upgrades in-app (#109).

All four packages bumped 0.6.0 → 0.7.0 in lockstep.

chore(release): prepare 0.6.0

Changed

• No-op updates are now valid instead of throwing. updateEvent, updateRecurring and updateCalendar return without a platform write when no fields are provided, so "save with no edits" is a harmless no-op rather than an ArgumentError (#95). updateRecurring returns the targeted scope's event id. updateRecurring's duration now accepts zero (an instantaneous event); only a negative duration is rejected.

Fixed

• Recurrence parsing accepts a negative BYMONTHDAY (e.g. -1 for the last day of the month) instead of rejecting the rule (#91)
• Turning a recurring occurrence non-recurring with thisAndFollowing + Patch.clear() now splits the series on iOS instead of collapsing the whole series into one event (#93) — see the device_calendar_plus_ios changelog
• listEvents returns every event across spans longer than ~4 years without dropping or duplicating recurring instances (iOS, #94), and includes zero-duration events sitting exactly on the query start (Android, #416) — see the platform changelogs
• createCalendar fails with a clear error on iOS sources that can't hold calendars, instead of an opaque failure (#96) — see the device_calendar_plus_ios changelog
• iOS EventKit operations run off the main thread, preventing UI stalls on large calendars (#79) — see the device_calendar_plus_ios changelog

Docs

• Documented listEvents per-instance expansion and the eventId@timestamp instanceId format (#97)

• iOS: fix showEventModal(edit: true) crash (#77)
• Docs: clarify showEventModal view modal is not read-only

Changed

• Breaking: updateRecurring() is redesigned around series semantics (#69). Times are now expressed as startTime (EventTimeOfDay) plus duration instead of absolute startDate/endDate, so every occurrence keeps its own date — changing a series' time no longer re-anchors the series to the occurrence you happened to edit (#68, thanks @SuperKrallan). The recurrence rule is now a Patch<RecurrenceRule>: Patch.set replaces it, Patch.clear collapses the series into a single event. Returns the event ID of the affected scope.
• Breaking: EventSpan.thisInstance is gone — EventSpan is now just allEvents and thisAndFollowing. Single occurrences are handled by updateEvent / deleteEvent with an instance ID (below).
• Breaking: updateEvent() with an instance ID (eventId@timestamp) edits only that occurrence, detaching it from the series; a bare event ID on a recurring event updates the whole series.
• Breaking: deleteEvent() with an instance ID removes only that occurrence; a bare event ID deletes the event (the whole series when recurring).

Added

• EventTimeOfDay — small validating hour/minute value class used by updateRecurring().

Fixed

• Occurrence edits with a startDate past the occurrence's untouched end are rejected with invalidArguments on iOS too, matching Android, instead of saving an inverted event.
• Android: events with no status read back as EventStatus.none instead of EventStatus.tentative — thanks @mauriziopinotti (#70).
• Android: all Calendar Provider work runs on a background thread; large calendars could ANR — thanks @mauriziopinotti (#73).

Added

• updateRecurring() — update a recurring event with a span choice: EventSpan.allEvents (whole series), thisAndFollowing (this occurrence and every later one), or thisInstance (only this occurrence). Can change or remove the recurrence rule. Resolves the long-standing limitation that updateEvent() could not edit recurrence. Based on @SuperKrallan (#36)
• deleteRecurring() — delete part of a recurring event with a span choice: EventSpan.allEvents (whole series), thisAndFollowing (this occurrence and every later one), or thisInstance (only this occurrence). Now supported on both iOS and Android (Android uses EXDATE on the master rather than a cancelled exception event). Based on @SuperKrallan (#43)
• EventSpan enum for choosing the scope of a recurring-event operation, shared by updateRecurring() and deleteRecurring()
• url parameter on updateEvent() — based on @SuperKrallan (#38)
• edit parameter on showEventModal() — when true, opens the native editor directly (EKEventEditViewController on iOS, ACTION_EDIT on Android) instead of the read-only viewer. Based on @xonaman (#45)
• Calendar.color getter — derived Flutter Color? parsed from colorHex, saving consumers from writing the same hex-parsing helper. Based on @xonaman (#46)

Changed

• Breaking: updateEvent() description, location and url now take a Patch<String> instead of a String. null leaves the field unchanged, Patch.set(value) assigns a value, Patch.clear() removes it — clearing an optional field was previously impossible.

Fixed

• Missing availability parameter in platform interface test mock — based on @SuperKrallan (#39)

Added

• listSources() to discover calendar accounts/sources — based on @magic-fit (#14)
• Source selection on createCalendar — iOS via CreateCalendarOptionsIos(sourceId:), Android via optional accountType
• supportsCalendarCreation on CalendarSource
• availability parameter on updateEvent() — thanks @SuperKrallan (#29)
• url field on events (iOS: EKEvent.url, Android: CUSTOM_APP_URI) — thanks @magic-fit (#32)
• showCreateEventModal() with optional pre-fill (title, dates, location, description)
• Read-only attendees on events (name, email, role, status)

Fixed

• Android: all-day events appearing in wrong day's query in non-UTC timezones (#20)
• Android: hasPermissions() now works from background services without an Activity (#31)
• Android: calendar/event queries use application context for background compatibility — thanks @vitalii-vov (#26)
• Android: notDetermined permission status correctly distinguished from denied — thanks @Albert221 (#12)
• iOS: calendar source lookup fallback when default source is unavailable — thanks @zaqwery (#13)
• iOS: createCalendar default fallback now picks iCloud over Gmail CalDAV (#33)

Added

• iOS: Swift Package Manager support

Fixed

• Fixed parsing of instanceId for events with @ in their event ID (e.g., Google Calendar IDs like abc123@google.com)

feat(android): add CreateCalendarOptionsAndroid for custom account na…

Fixed

• showEventModal() now properly awaits until the modal is dismissed (iOS and Android)

chore: bump version and update changelogs

Added

• openAppSettings() method to guide users to system settings when permissions are denied
• Testing status documentation in README

Removed

• BREAKING: getPlatformVersion() method (unused boilerplate)

Changed

• Updated all platform packages to 0.2.0

Added

• Android: ProGuard/R8 rules for release build compatibility

Initial release.

Added

• Calendar permissions management (request/check)
• List device calendars with metadata (name, color, read-only status, primary flag)
• Query events by date range with optional calendar filtering
• Get single event by ID with support for recurring event instances
• Create events with full metadata support
• Update events including single-instance and all-instance updates for recurring events
• Delete events (single or all instances)
• Show native event modal
• All-day event support with floating date behavior
• Timezone handling for timed events
• Typed exception model with DeviceCalendarException and DeviceCalendarError enum
• Federated plugin architecture (Android + iOS)
• Support for Android API 24+ (target/compile 35)
• Support for iOS 13+