Two-way calendar sync with Google Calendar and Outlook

Your own writes come back as changes

Every event your app creates or moves is a change on that calendar, and the provider reports it like any other. If your handler copies it back into your schedule, and your schedule's save hook writes it to the calendar again, the two sides echo each other. At best that doubles the work. At worst a write that lands between two edits restores an old value.

On the providers directly, you have to recognize your own writes. Google lets you set hidden key-value pairs on an event as extended properties, and Graph events take extensions and extended properties. A tag says your app created the event, though, not that your app made the latest change. Comparing versions gets closer. Google's etag "changes every time the resource changes" (Google), so an etag in the sync that matches the one your write returned means nothing happened since. Outlook breaks that shortcut: on Outlook.com, a new event's change key moves on its own seconds after the create.

With Pyas, the webhook for a change your API call made carries request.traceId. Skip those, provided you updated your own record when you made the call.

Map IDs in both directions

Keep a table linking each of your records to a provider event: your id, the connected account, the calendar, the provider's event id, the event's last version and the fields you sync. You look it up from your side when a user edits a record, and from the event id when a webhook or sync names an event.

Two provider details shape that table:

• Google lets you choose an event's id at creation. It must use base32hex characters ("lowercase letters a-v and digits 0-9"), be 5 to 1024 characters long and be unique per calendar (events reference). Otherwise Google generates one.
• An Outlook event's id "changes when the item is moved from one container (such as a folder or calendar) to another", unless you request immutable IDs with Prefer: IdType="ImmutableId" (event resource).

Notifications say when, the sync says what

Neither provider promises delivery. Google: "Notifications are not 100% reliable. Expect a small percentage of messages to get dropped under normal working conditions" (push guide). Microsoft: if your endpoint answers slowly, "the change notification service might begin to drop notifications. Dropped notifications can't be recovered" (webhooks guide).

So a notification is a trigger, and the incremental sync from a stored cursor is the source of truth. Run that sync on a timer as well, so a lost notification costs minutes instead of a missing appointment. The webhooks guide covers Google channels and Graph subscriptions in detail.

Pyas keeps the channels and subscriptions alive and sends one kind of webhook for both providers. It names the changed event in data.object as { id, calendarId, seriesId, isSeries }, never its title or times, and never the values before the change. You read the event and compare it with your copy.

Sync tokens expire

From Google's sync guide: the nextSyncToken "is present only on the very last page", "each list request should use the same set of query parameters, including the initial request", and tokens can be invalidated "for various reasons including token expiration or changes in related ACLs". Google then answers 410, which "should trigger a full wipe of the client's store and a new full sync." Graph's equivalent is the delta link, and a calendar view delta covers one calendar and one date range: "To track the changes in multiple calendars, you need to track each calendar individually" (delta query for events).

In a two-way sync, "wipe the store" can't mean deleting your own records, because they are the other half of the sync. Wipe the cursor and the cached event fields, list the window again, and match each event to your records through the ID map. A linked event missing from the new listing counts as deleted only if it falls inside the window you listed.

Deleted events come back as cancelled

Google keeps deleted events. In the events reference, status cancelled means "The event is cancelled (deleted)", and a deleted event is "only guaranteed to have the id field populated". Your ID map is how you know which record it was. Reading a deleted event by its ID returns the whole event with status cancelled, not a 404 (field note). Graph's delta query marks deletions with "@removed": {"reason": "deleted"}.

Decide what a deletion means in your product before you apply it. In a practice-management tool, a session deleted from someone's Google Calendar may need to become "cancelled" with a note on your side, not disappear. Also expect a race: a webhook for an update can arrive after the event was deleted, so a read that finds nothing is a deletion, not an error.

A series is not an occurrence

A recurring meeting changes in two ways: the whole series, or one occurrence. Google marks an occurrence with recurringEventId and originalStartTime, which "uniquely identifies the instance within the recurring event series even if the instance was moved" (recurring events). Outlook gives each event a type of singleInstance, occurrence, exception or seriesMaster, with seriesMasterId on the parts of a series, and a series' instances "doesn't include occurrences canceled from the series" (event resource).

Key your occurrences by series and original start, not by current start, since moving one occurrence changes its start. In Pyas, a change to the whole series is one webhook with isSeries: true, and one changed occurrence has seriesId set:

const { id, calendarId, seriesId, isSeries } = event.data.object
if (isSeries) {
    for await (const occurrence of pyas.events.instances({ accountId: event.accountId, eventId: id, calendarRef: calendarId, from, to })) {
        await links.upsertOccurrence(id, occurrence)
    }
} else {
    const changed = await pyas.events.get({ accountId: event.accountId, eventId: id, calendarRef: calendarId })
    await links.upsertOccurrence(seriesId, changed) // seriesId is null for a one-off event
}

Two people edit the same event

Your user reschedules an appointment in your app while their assistant moves the same meeting in Outlook. Without a check, whichever write lands last wins and nobody is told. Google supports conditional writes: send If-Match with the etag you read, and if the event changed since, "you will get a 412 (Precondition failed) response code" (Google). Outlook's changeKey "identifies the version of the event object", but on Outlook.com it moves after a create with nothing changed, as the field note above shows.

In Pyas, ifMatch: event.version refuses the update if the event changed since you read it, on either provider. When it is refused, read the event again, compare it with your copy, and resolve field by field. A rule that holds up: your app owns the fields only it has, such as the client or the notes, and for times and titles the newer edit wins, decided after the re-read and not before.