feat: map Google Calendar events to read-only Delta tasks #447

New issue

Closed

opened 2026-05-13 18:43:22 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-05-13 18:43:22 +00:00

Owner

Parent: #123
Depends on: #444, #446
Related: #290

Problem

Before wiring a pull route, Delta needs a well-tested mapper from Google Calendar event payloads into read-only Delta task rows plus external-link metadata. This mapper must preserve future-use data without prematurely building UI for every Google Calendar feature.

Decisions

Google Calendar v1 is pull-only and read-only.
Pulled events become normal Delta task rows protected by the read-only import guard.
Import all event history for selected calendars; do not add an initial-window or pruning setting in v1.
Import all Google event types by default; do not filter eventTypes.
Use tentative canonical external id {calendarId}:{event.id}.
Store calendarId, eventId, iCalUID, etag, updated, sequence, eventType, status, visibility, transparency, source calendar attributes, and raw useful payload in metadata.
Map Google calendar name to Delta category.
Preserve Google all-day exclusive end-date semantics to avoid off-by-one bugs.
Port effective timed-event timezone into task fields where needed and preserve original Google start/end/timezone payloads in metadata.
Best-effort convert supported Google description formatting into Tiptap JSON; preserve raw description in metadata.
Map Meet/conference links into meetingUrl.
Preserve conference, attendee, attachment, organizer/creator, reminder, source, and raw provider payloads in metadata for later features.
Hidden-detail private events import as private event with [private] source metadata.
Transparent/free events import, preserve transparency, and can render quieter later.
Skip likely existing .ics duplicates by matching iCalUID; report them as duplicate skipped instead of auto-linking or creating duplicates.

Recurrence decisions

Map Google recurring masters and exceptions into Delta's existing RRULE/master-exception model.
Cancelled recurring instances become exdates on the master.
If a materialized exception row already exists for a cancelled occurrence, suppress/cancel it so it does not render.
Completion-based Delta recurrence is not exported to Google because v1 is pull-only.

Acceptance criteria

Mapper tests cover normal timed events, all-day one-day and multi-day events, time zones, all Google event types, private hidden-detail events, transparent/free events, Meet links, descriptions with supported formatting, attachments/reminders/attendees metadata preservation, recurring masters, recurring exceptions, and cancelled instances.
Google metadata preservation is rich enough for later attendee, reminder, attachment, raw JSON, and conference UI without refetching every historical event.
The mapper does not add attendee/reminder/attachment UI.
The mapper does not write to Google.

Non-goals

Do not add the manual pull route here if the mapper is not yet integrated.
Do not build future attachment, attendee, reminder, free/busy, or raw JSON UI here.
Do not introduce a new project/calendar model; use category mapping.

Parent: #123 Depends on: #444, #446 Related: #290 ## Problem Before wiring a pull route, Delta needs a well-tested mapper from Google Calendar event payloads into read-only Delta task rows plus external-link metadata. This mapper must preserve future-use data without prematurely building UI for every Google Calendar feature. ## Decisions - Google Calendar v1 is pull-only and read-only. - Pulled events become normal Delta task rows protected by the read-only import guard. - Import all event history for selected calendars; do not add an initial-window or pruning setting in v1. - Import all Google event types by default; do not filter `eventTypes`. - Use tentative canonical external id `{calendarId}:{event.id}`. - Store `calendarId`, `eventId`, `iCalUID`, `etag`, `updated`, `sequence`, `eventType`, status, visibility, transparency, source calendar attributes, and raw useful payload in metadata. - Map Google calendar name to Delta category. - Preserve Google all-day exclusive end-date semantics to avoid off-by-one bugs. - Port effective timed-event timezone into task fields where needed and preserve original Google start/end/timezone payloads in metadata. - Best-effort convert supported Google description formatting into Tiptap JSON; preserve raw description in metadata. - Map Meet/conference links into `meetingUrl`. - Preserve conference, attendee, attachment, organizer/creator, reminder, source, and raw provider payloads in metadata for later features. - Hidden-detail private events import as `private event` with `[private]` source metadata. - Transparent/free events import, preserve `transparency`, and can render quieter later. - Skip likely existing `.ics` duplicates by matching `iCalUID`; report them as duplicate skipped instead of auto-linking or creating duplicates. ## Recurrence decisions - Map Google recurring masters and exceptions into Delta's existing RRULE/master-exception model. - Cancelled recurring instances become `exdates` on the master. - If a materialized exception row already exists for a cancelled occurrence, suppress/cancel it so it does not render. - Completion-based Delta recurrence is not exported to Google because v1 is pull-only. ## Acceptance criteria - Mapper tests cover normal timed events, all-day one-day and multi-day events, time zones, all Google event types, private hidden-detail events, transparent/free events, Meet links, descriptions with supported formatting, attachments/reminders/attendees metadata preservation, recurring masters, recurring exceptions, and cancelled instances. - Google metadata preservation is rich enough for later attendee, reminder, attachment, raw JSON, and conference UI without refetching every historical event. - The mapper does not add attendee/reminder/attachment UI. - The mapper does not write to Google. ## Non-goals - Do not add the manual pull route here if the mapper is not yet integrated. - Do not build future attachment, attendee, reminder, free/busy, or raw JSON UI here. - Do not introduce a new project/calendar model; use category mapping.

barrettruth added this to the v0.1.0 milestone

2026-05-13 18:43:22 +00:00

barrettruth added the

enhancement

track:api

track:core

labels

2026-05-13 18:43:22 +00:00

barrettruth referenced this issue

2026-05-13 18:43:47 +00:00

feat: implement Google Calendar manual pull sync #448

barrettruth referenced this issue