@kubun/connector-google-calendar 0.17.1 → 0.17.3

package/lib/index.d.ts

@@ -1,5 +1,10 @@
 export { createGoogleCalendarActionHandler, type GoogleCalendarActionHandlerConfig, } from './actions.js';
 export { buildCalendarListURL, buildEventFromParams, buildEventsListURL, createEvent, type GoogleCalendarListResponse, type GoogleCalendarResource, type GoogleEventDateTime, type GoogleEventResource, type GoogleEventsListResponse, mapCalendarToEntity, mapEventToEntity, updateEvent, } from './api.js';
 export { type CreateGoogleCalendarConnectorOptions, createGoogleCalendarConnector, } from './connector.js';
+export { GoogleCalendarError, type GoogleCalendarErrorCode, type GoogleCalendarErrorOptions, GoogleCalendarEventConflict, } from './errors.js';
+export { deriveEventID } from './event-id.js';
+export { canonicalizeEventIntent, eventHoldsIntent } from './intent.js';
 export { googleCalendarClusters, googleCalendarDefinition, googleCalendarEventDefinition, } from './model.js';
+export { predictCreatedEventSourceID } from './predict.js';
 export { type CalendarCheckpoint, createGoogleCalendarProvider, type GoogleCalendarProviderConfig, } from './provider.js';
+export { resolveCalendarTarget } from './target.js';

package/lib/index.js

@@ -1,5 +1,10 @@
 export { createGoogleCalendarActionHandler } from './actions.js';
 export { buildCalendarListURL, buildEventFromParams, buildEventsListURL, createEvent, mapCalendarToEntity, mapEventToEntity, updateEvent } from './api.js';
 export { createGoogleCalendarConnector } from './connector.js';
+export { GoogleCalendarError, GoogleCalendarEventConflict } from './errors.js';
+export { deriveEventID } from './event-id.js';
+export { canonicalizeEventIntent, eventHoldsIntent } from './intent.js';
 export { googleCalendarClusters, googleCalendarDefinition, googleCalendarEventDefinition } from './model.js';
+export { predictCreatedEventSourceID } from './predict.js';
 export { createGoogleCalendarProvider } from './provider.js';
+export { resolveCalendarTarget } from './target.js';

package/lib/intent.d.ts

@@ -0,0 +1,23 @@
+import type { EntityRecord, IntentCanonicalizer } from '@kubun/connector';
+/**
+ * The Calendar intent canonicalizer (see `IntentCanonicalizer`). Folds in only
+ * what Google itself does to a written event:
+ * - a start/end is compared as the instant (or, all-day, the date) it names,
+ *   only when it names one by itself (an explicit offset), and an all-day
+ *   value never matches a timed one;
+ * - `calendarID` is compared exactly: an operation's intent already carries
+ *   the calendar the `'primary'` alias was resolved to before the claim;
+ * - a cancelled (deleted) event holds no create or update.
+ */
+export declare const canonicalizeEventIntent: IntentCanonicalizer;
+/**
+ * Whether a Calendar event holds a write's intent: every event field the
+ * intent sets carries the intended value, as Google keeps it. Keys of the
+ * intent that are not event fields (a target, say) are not compared, and an
+ * intent that sets no event field does not hold.
+ */
+export declare function eventHoldsIntent(params: {
+    op: 'create' | 'update';
+    intent: Record<string, unknown>;
+    record: EntityRecord;
+}): boolean;

package/lib/intent.js

@@ -0,0 +1,86 @@
+import { digestJSON } from '@kubun/id';
+import { toB64U } from '@sozai/codec';
+import { googleCalendarEventDefinition } from './model.js';
+const EVENT_FIELDS = new Set(googleCalendarEventDefinition.providerMergePolicy.group);
+const BARE_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_PREFIX = /^\d{4}-\d{2}-\d{2}/;
+// A date-time that names its instant by itself: an explicit `Z` or `±hh:mm`.
+const WITH_OFFSET = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/i;
+// A start/end in the form Google keeps it. An all-day value is its calendar
+// date (Google stores only the date) — kept a string, so it never equals a
+// timed instant. A timed value with an explicit offset is the instant it names
+// (Google re-renders a dateTime in the calendar's offset). Anything else — an
+// offset-less date-time, which would otherwise be read in the host's time
+// zone — stays as it is and is compared exactly.
+function canonicalDateTime(value, allDay) {
+    if (typeof value !== 'string') return value;
+    if (allDay) return DATE_PREFIX.test(value) ? value.slice(0, 10) : value;
+    return WITH_OFFSET.test(value) ? Date.parse(value) : value;
+}
+/**
+ * The Calendar intent canonicalizer (see `IntentCanonicalizer`). Folds in only
+ * what Google itself does to a written event:
+ * - a start/end is compared as the instant (or, all-day, the date) it names,
+ *   only when it names one by itself (an explicit offset), and an all-day
+ *   value never matches a timed one;
+ * - `calendarID` is compared exactly: an operation's intent already carries
+ *   the calendar the `'primary'` alias was resolved to before the claim;
+ * - a cancelled (deleted) event holds no create or update.
+ */ export const canonicalizeEventIntent = ({ model, intent, record })=>{
+    if (model !== googleCalendarEventDefinition.name) return {
+        intent,
+        record
+    };
+    if (record.status === 'CANCELLED') return null;
+    // Each side is read in its own shape: an all-day intent (declared, or a
+    // bare date) as dates, the record by its own allDay flag. A timed intent
+    // against an all-day event, or the reverse, therefore never compares equal.
+    const intentAllDay = intent.allDay === true;
+    const recordAllDay = record.allDay === true;
+    const canonicalIntent = {
+        ...intent
+    };
+    const canonicalRecord = {
+        ...record
+    };
+    for (const field of [
+        'startAt',
+        'endAt'
+    ]){
+        if (field in canonicalIntent) {
+            const value = canonicalIntent[field];
+            const asDate = intentAllDay || typeof value === 'string' && BARE_DATE.test(value);
+            canonicalIntent[field] = canonicalDateTime(value, asDate);
+        }
+        canonicalRecord[field] = canonicalDateTime(canonicalRecord[field], recordAllDay);
+    }
+    return {
+        intent: canonicalIntent,
+        record: canonicalRecord
+    };
+};
+function canonicalOf(value) {
+    return toB64U(digestJSON(value === undefined ? null : value));
+}
+// An intent that sets no event field confirms nothing, and does not hold.
+function holds(compared) {
+    let matched = 0;
+    for (const [field, intended] of Object.entries(compared.intent)){
+        if (!EVENT_FIELDS.has(field)) continue;
+        if (canonicalOf(compared.record[field]) !== canonicalOf(intended)) return false;
+        matched++;
+    }
+    return matched > 0;
+}
+/**
+ * Whether a Calendar event holds a write's intent: every event field the
+ * intent sets carries the intended value, as Google keeps it. Keys of the
+ * intent that are not event fields (a target, say) are not compared, and an
+ * intent that sets no event field does not hold.
+ */ export function eventHoldsIntent(params) {
+    const compared = canonicalizeEventIntent({
+        model: googleCalendarEventDefinition.name,
+        ...params
+    });
+    return compared != null && holds(compared);
+}

package/lib/model.d.ts

@@ -20,6 +20,11 @@ export declare const googleCalendarDefinition: {
             readonly backgroundColor: {
                 readonly type: "string";
             };
+            readonly accountKey: {
+                readonly type: "string";
+                readonly minLength: 43;
+                readonly maxLength: 43;
+            };
             readonly sourceService: {
                 readonly $ref: "#/definitions/SourceService";
             };
@@ -36,6 +41,7 @@ export declare const googleCalendarDefinition: {
         readonly required: ["summary", "sourceService", "sourceID", "lastSyncedAt"];
         readonly additionalProperties: false;
         readonly definitions: {
+            readonly TimeZone: import("json-schema-typed").JSONSchema.String;
             readonly SourceService: {
                 readonly type: "string";
                 readonly title: "SourceService";
@@ -54,7 +60,6 @@ export declare const googleCalendarDefinition: {
                 readonly title: "URL";
             };
             readonly DateTime: import("json-schema-typed").JSONSchema.String;
-            readonly TimeZone: import("json-schema-typed").JSONSchema.String;
         };
     };
     readonly fieldsMeta: {};
@@ -104,6 +109,9 @@ export declare const googleCalendarEventDefinition: {
             readonly calendarID: {
                 readonly type: "string";
             };
+            readonly etag: {
+                readonly type: "string";
+            };
             readonly calendar: {
                 readonly $ref: "#/definitions/CalendarDocID";
             };
@@ -123,24 +131,12 @@ export declare const googleCalendarEventDefinition: {
         readonly required: ["title", "startAt", "allDay", "calendarID", "calendar", "sourceService", "sourceID", "lastSyncedAt"];
         readonly additionalProperties: false;
         readonly definitions: {
-            readonly SourceService: {
-                readonly type: "string";
-                readonly title: "SourceService";
-                readonly minLength: 1;
-                readonly maxLength: 50;
-            };
             readonly SourceID: {
                 readonly type: "string";
                 readonly title: "SourceID";
                 readonly minLength: 1;
                 readonly maxLength: 1400;
             };
-            readonly SourceURL: {
-                readonly type: "string";
-                readonly format: "uri";
-                readonly title: "URL";
-            };
-            readonly DateTime: import("json-schema-typed").JSONSchema.String;
             readonly TimeZone: import("json-schema-typed").JSONSchema.String;
             readonly HtmlLink: {
                 readonly type: "string";
@@ -157,6 +153,18 @@ export declare const googleCalendarEventDefinition: {
                 readonly title: "EventStatus";
                 readonly enum: ["CONFIRMED", "TENTATIVE", "CANCELLED"];
             };
+            readonly SourceService: {
+                readonly type: "string";
+                readonly title: "SourceService";
+                readonly minLength: 1;
+                readonly maxLength: 50;
+            };
+            readonly SourceURL: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly title: "URL";
+            };
+            readonly DateTime: import("json-schema-typed").JSONSchema.String;
         };
     };
     readonly fieldsMeta: {
@@ -165,5 +173,8 @@ export declare const googleCalendarEventDefinition: {
             readonly model: "#0";
         };
     };
+    readonly providerMergePolicy: {
+        readonly group: ["title", "startAt", "endAt", "allDay", "timeZone", "description", "location", "status", "htmlLink", "recurringEventID", "eventID", "calendarID", "calendar", "sourceService", "sourceID", "sourceURL", "etag"];
+    };
 };
 export declare const googleCalendarClusters: import("@kubun/protocol").ClustersRecord;

package/lib/model.js

@@ -1,7 +1,7 @@
-import { connectorClusters, connectorModelIDs } from '@kubun/connector';
+import { connectorClusters, connectorModelIDs, externalEntityDefinition } from '@kubun/connector';
 import { modelIDs, modelsClusters } from '@kubun/models';
 import { GraphBuilder } from '@kubun/protocol';
-import { dateTimeSchema, docIDSchema, timeZoneSchema, urlSchema } from '@kubun/scalars';
+import { docIDSchema, timeZoneSchema, urlSchema } from '@kubun/scalars';
 export const googleCalendarDefinition = {
     name: 'GoogleCalendar',
     behavior: 'default',
@@ -26,6 +26,11 @@ export const googleCalendarDefinition = {
             backgroundColor: {
                 type: 'string'
             },
+            accountKey: {
+                type: 'string',
+                minLength: 43,
+                maxLength: 43
+            },
             sourceService: {
                 $ref: '#/definitions/SourceService'
             },
@@ -47,20 +52,7 @@ export const googleCalendarDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            SourceService: {
-                type: 'string',
-                title: 'SourceService',
-                minLength: 1,
-                maxLength: 50
-            },
-            SourceID: {
-                type: 'string',
-                title: 'SourceID',
-                minLength: 1,
-                maxLength: 500
-            },
-            SourceURL: urlSchema,
-            DateTime: dateTimeSchema,
+            ...externalEntityDefinition.schema.definitions,
             TimeZone: timeZoneSchema
         }
     },
@@ -114,6 +106,9 @@ export const googleCalendarEventDefinition = {
             calendarID: {
                 type: 'string'
             },
+            etag: {
+                type: 'string'
+            },
             calendar: {
                 $ref: '#/definitions/CalendarDocID'
             },
@@ -142,12 +137,7 @@ export const googleCalendarEventDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            SourceService: {
-                type: 'string',
-                title: 'SourceService',
-                minLength: 1,
-                maxLength: 50
-            },
+            ...externalEntityDefinition.schema.definitions,
             // A composite calendarID/eventID: calendar id (email-like, up to ~254) +
             // '/' + a Google event id (up to 1024). 500 is too small.
             SourceID: {
@@ -156,8 +146,6 @@ export const googleCalendarEventDefinition = {
                 minLength: 1,
                 maxLength: 1400
             },
-            SourceURL: urlSchema,
-            DateTime: dateTimeSchema,
             TimeZone: timeZoneSchema,
             HtmlLink: urlSchema,
             CalendarDocID: docIDSchema,
@@ -177,6 +165,32 @@ export const googleCalendarEventDefinition = {
             type: 'document',
             model: '#0'
         }
+    },
+    // lastSyncedAt is a device-local sync-bookkeeping annotation, not fetched
+    // provider content, so it stays outside the group.
+    providerMergePolicy: {
+        group: [
+            'title',
+            'startAt',
+            'endAt',
+            'allDay',
+            'timeZone',
+            'description',
+            'location',
+            'status',
+            'htmlLink',
+            'recurringEventID',
+            'eventID',
+            'calendarID',
+            'calendar',
+            'sourceService',
+            'sourceID',
+            'sourceURL',
+            // The provider revision of this state: an update is written
+            // conditionally on it (If-Match), so it must travel with the fields it
+            // versions.
+            'etag'
+        ]
     }
 };
 const builder = new GraphBuilder({

package/lib/predict.d.ts

@@ -0,0 +1,8 @@
+import type { CreatedSourceIDPredictor } from '@kubun/connector';
+/**
+ * The provider id a calendar event create is stored under: the resolved
+ * calendar and the event id derived from the operation's deterministic event
+ * id, as the create handler inserts it. `null` for a calendar create and for
+ * an input whose calendar is not resolved.
+ */
+export declare const predictCreatedEventSourceID: CreatedSourceIDPredictor;

package/lib/predict.js

@@ -0,0 +1,12 @@
+import { deriveEventID } from './event-id.js';
+/**
+ * The provider id a calendar event create is stored under: the resolved
+ * calendar and the event id derived from the operation's deterministic event
+ * id, as the create handler inserts it. `null` for a calendar create and for
+ * an input whose calendar is not resolved.
+ */ export const predictCreatedEventSourceID = ({ model, input, deterministicEventID })=>{
+    if (model !== 'GoogleCalendarEvent') return null;
+    const calendarID = input.calendarID;
+    if (typeof calendarID !== 'string' || calendarID === '' || calendarID === 'primary') return null;
+    return `${calendarID}/${deriveEventID(deterministicEventID)}`;
+};

package/lib/provider.d.ts

@@ -5,6 +5,7 @@ export type GoogleCalendarProviderConfig = {
     boundary?: SyncBoundary;
     fetch?: typeof globalThis.fetch;
     excludeCalendars?: Array<string>;
+    mintFetchHLC: () => string;
 };
 export type CalendarCheckpoint = {
     calendarListSyncToken?: string;

package/lib/provider.js

@@ -1,39 +1,12 @@
-import { resolveModelID } from '@kubun/connector';
-import { buildCalendarListURL, buildEventsListURL, mapCalendarToEntity, mapEventToEntity, parseGoogleError } from './api.js';
+import { ConnectorError, fetchOrAbsent, parseMaxAgeDays, resolveModelID } from '@kubun/connector';
+import { deriveAccountKey } from './account-key.js';
+import { buildCalendarListURL, buildEventsListURL, calendarAPIClient, getCalendarListEntry, getEvent, getEventWithETag, mapCalendarToEntity, mapEventToEntity, splitEventSourceID } from './api.js';
 import { googleCalendarClusters } from './model.js';
 const CALENDAR_MODEL_ID = resolveModelID(googleCalendarClusters, 'GoogleCalendar');
 const CALENDAR_EVENT_MODEL_ID = resolveModelID(googleCalendarClusters, 'GoogleCalendarEvent');
-class GoogleCalendarAPIError extends Error {
-    #status;
-    constructor(status, detail){
-        super(`Google Calendar API error: ${detail}`);
-        this.name = 'GoogleCalendarAPIError';
-        this.#status = status;
-    }
-    get status() {
-        return this.#status;
-    }
-}
-async function fetchJSON(url, credential, fetchFn, signal) {
-    const response = await fetchFn(url, {
-        headers: {
-            Authorization: `Bearer ${credential.accessToken}`
-        },
-        signal
-    });
-    if (!response.ok) {
-        throw new GoogleCalendarAPIError(response.status, await parseGoogleError(response));
-    }
-    return await response.json();
-}
 function computeTimeMin(boundary) {
-    if (boundary.maxAge == null) return undefined;
-    // Parse PnD format (e.g. "P30D" = 30 days)
-    const match = /^P(\d+)D$/i.exec(boundary.maxAge);
-    if (match == null) return undefined;
-    const rawDays = match[1];
-    if (rawDays == null) return undefined;
-    const days = Number.parseInt(rawDays, 10);
+    const days = parseMaxAgeDays(boundary);
+    if (days == null) return undefined;
     const date = new Date();
     date.setDate(date.getDate() - days);
     return date.toISOString();
@@ -46,7 +19,9 @@ async function* fetchAllCalendars(params) {
             syncToken: isFirstPage ? params.syncToken : undefined,
             pageToken
         });
-        const data = await fetchJSON(url, params.credential, params.fetchFn, params.signal);
+        const data = await params.client.get(url, {
+            signal: params.signal
+        });
         yield {
             items: data.items ?? [],
             nextSyncToken: data.nextSyncToken,
@@ -66,7 +41,9 @@ async function* fetchEventsForCalendar(params) {
             pageToken,
             timeMin: params.timeMin
         });
-        const data = await fetchJSON(url, params.credential, params.fetchFn, params.signal);
+        const data = await params.client.get(url, {
+            signal: params.signal
+        });
         yield {
             items: data.items ?? [],
             nextSyncToken: data.nextSyncToken
@@ -77,7 +54,13 @@ async function* fetchEventsForCalendar(params) {
 }
 export function createGoogleCalendarProvider(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
+    const client = calendarAPIClient(config.credential.accessToken, fetchFn);
     const excludeSet = new Set(config.excludeCalendars ?? []);
+    const mintFetchHLC = config.mintFetchHLC;
+    // Derived once per provider instance — a pure function of (iss,sub), so it is
+    // stable across refresh and re-auth. Absent when the credential predates
+    // providerAccount capture.
+    const accountKey = config.credential.providerAccount != null ? deriveAccountKey(config.credential.providerAccount) : undefined;
     async function* fetchAllEntities(params) {
         // Reuse a window frozen by a prior sync (carried in an expired checkpoint on
         // the 410 resync path, or a re-driven initial) instead of recomputing from
@@ -89,8 +72,7 @@ export function createGoogleCalendarProvider(config) {
         const allCalendars = [];
         let calendarListSyncToken;
         for await (const page of fetchAllCalendars({
-            credential: config.credential,
-            fetchFn,
+            client,
             signal: params.signal
         })){
             for (const cal of page.items){
@@ -103,9 +85,14 @@ export function createGoogleCalendarProvider(config) {
             }
         }
         // Yield calendar batch (no checkpoint yet — will be on the last event batch)
+        const calendarListToken = mintFetchHLC();
         yield {
             modelID: CALENDAR_MODEL_ID,
-            entities: allCalendars.map(mapCalendarToEntity),
+            entities: allCalendars.map((c)=>({
+                    present: true,
+                    record: mapCalendarToEntity(c, accountKey),
+                    sourceFetchHLC: calendarListToken
+                })),
             hasMore: true
         };
         // Phase 2: fetch events per calendar
@@ -116,8 +103,7 @@ export function createGoogleCalendarProvider(config) {
             let eventsSyncToken;
             for await (const page of fetchEventsForCalendar({
                 calendarID: calendar.id,
-                credential: config.credential,
-                fetchFn,
+                client,
                 timeMin,
                 signal: params.signal
             })){
@@ -141,14 +127,20 @@ export function createGoogleCalendarProvider(config) {
                 // Split items: cancelled → deleted, others → entities
                 const activeItems = page.items.filter((e)=>e.status !== 'cancelled');
                 const cancelledItems = page.items.filter((e)=>e.status === 'cancelled');
+                const pageToken = mintFetchHLC();
                 yield {
                     modelID: CALENDAR_EVENT_MODEL_ID,
-                    entities: activeItems.map((event)=>mapEventToEntity(event, calendar.id)),
+                    entities: activeItems.map((event)=>({
+                            present: true,
+                            record: mapEventToEntity(event, calendar.id),
+                            sourceFetchHLC: pageToken
+                        })),
                     // Match the composite identity mapEventToEntity assigns, so the
                     // tombstone lookup hits the calendar-namespaced document.
                     deleted: cancelledItems.map((e)=>({
-                            sourceService: 'google-calendar',
-                            sourceID: `${calendar.id}/${e.id}`
+                            present: false,
+                            sourceID: `${calendar.id}/${e.id}`,
+                            sourceFetchHLC: pageToken
                         })),
                     hasMore: !(isLastCalendar && isLastPage),
                     checkpoint
@@ -185,8 +177,7 @@ export function createGoogleCalendarProvider(config) {
         const deletedCalendarIDs = [];
         let newCalendarListSyncToken;
         for await (const page of fetchAllCalendars({
-            credential: config.credential,
-            fetchFn,
+            client,
             syncToken: checkpoint.calendarListSyncToken,
             signal: params.signal
         })){
@@ -202,12 +193,18 @@ export function createGoogleCalendarProvider(config) {
             }
         }
         // Yield calendar batch (active + deletions)
+        const calendarListToken = mintFetchHLC();
         yield {
             modelID: CALENDAR_MODEL_ID,
-            entities: activeCalendars.map(mapCalendarToEntity),
+            entities: activeCalendars.map((c)=>({
+                    present: true,
+                    record: mapCalendarToEntity(c, accountKey),
+                    sourceFetchHLC: calendarListToken
+                })),
             deleted: deletedCalendarIDs.map((id)=>({
-                    sourceService: 'google-calendar',
-                    sourceID: id
+                    present: false,
+                    sourceID: id,
+                    sourceFetchHLC: calendarListToken
                 })),
             hasMore: true
         };
@@ -244,8 +241,7 @@ export function createGoogleCalendarProvider(config) {
             let eventsSyncToken;
             for await (const page of fetchEventsForCalendar({
                 calendarID,
-                credential: config.credential,
-                fetchFn,
+                client,
                 syncToken: storedToken,
                 timeMin: isNew ? timeMin : undefined,
                 signal: params.signal
@@ -269,14 +265,20 @@ export function createGoogleCalendarProvider(config) {
                 // Split items: cancelled → deleted, others → entities
                 const activeItems = page.items.filter((e)=>e.status !== 'cancelled');
                 const cancelledItems = page.items.filter((e)=>e.status === 'cancelled');
+                const pageToken = mintFetchHLC();
                 yield {
                     modelID: CALENDAR_EVENT_MODEL_ID,
-                    entities: activeItems.map((event)=>mapEventToEntity(event, calendarID)),
+                    entities: activeItems.map((event)=>({
+                            present: true,
+                            record: mapEventToEntity(event, calendarID),
+                            sourceFetchHLC: pageToken
+                        })),
                     // Match the composite identity mapEventToEntity assigns, so the
                     // tombstone lookup hits the calendar-namespaced document.
                     deleted: cancelledItems.map((e)=>({
-                            sourceService: 'google-calendar',
-                            sourceID: `${calendarID}/${e.id}`
+                            present: false,
+                            sourceID: `${calendarID}/${e.id}`,
+                            sourceFetchHLC: pageToken
                         })),
                     hasMore: !(isLastCalendar && isLastPage),
                     checkpoint: newCheckpoint
@@ -303,11 +305,81 @@ export function createGoogleCalendarProvider(config) {
             };
         }
     }
+    // Targeted single-entity fetch (anti-entropy repair verification). Mints its
+    // own fetch-order token at request start, independent of any batch token
+    // (see ServerProviderFactory.mintFetchHLC's doc). `model` distinguishes the
+    // account-level GoogleCalendar resource from a GoogleCalendarEvent — only
+    // the latter's sourceID is the composite calendarID/eventID.
+    async function fetchEntity(model, sourceID) {
+        const sourceFetchHLC = mintFetchHLC();
+        return fetchOrAbsent({
+            sourceID,
+            sourceFetchHLC,
+            read: async ()=>{
+                if (model === CALENDAR_MODEL_ID) {
+                    const calendar = await getCalendarListEntry({
+                        accessToken: config.credential.accessToken,
+                        calendarID: sourceID,
+                        fetch: fetchFn
+                    });
+                    return {
+                        record: mapCalendarToEntity(calendar, accountKey)
+                    };
+                }
+                const { calendarID, eventID } = splitEventSourceID(sourceID);
+                const record = await getEvent({
+                    accessToken: config.credential.accessToken,
+                    calendarID,
+                    eventID,
+                    fetch: fetchFn
+                });
+                return {
+                    record
+                };
+            }
+        });
+    }
+    // Provider-authoritative re-read for write-back recovery. Unlike
+    // fetchEntity, the present:true branch also surfaces a providerETag when the
+    // provider reports one — the current revision an update's If-Match can
+    // condition on.
+    async function reconcile(model, sourceID) {
+        const sourceFetchHLC = mintFetchHLC();
+        return fetchOrAbsent({
+            sourceID,
+            sourceFetchHLC,
+            read: async ()=>{
+                if (model === CALENDAR_MODEL_ID) {
+                    const calendar = await getCalendarListEntry({
+                        accessToken: config.credential.accessToken,
+                        calendarID: sourceID,
+                        fetch: fetchFn
+                    });
+                    return {
+                        record: mapCalendarToEntity(calendar, accountKey)
+                    };
+                }
+                const { calendarID, eventID } = splitEventSourceID(sourceID);
+                const { record, etag } = await getEventWithETag({
+                    accessToken: config.credential.accessToken,
+                    calendarID,
+                    eventID,
+                    fetch: fetchFn
+                });
+                return {
+                    record,
+                    providerETag: etag
+                };
+            }
+        });
+    }
     return {
         supportedStrategies: [
             'on-demand'
         ],
         fetchAll: fetchAllEntities,
+        fetchEntity,
+        reconcile,
         async *fetchChanges (params) {
             const checkpoint = params.checkpoint;
             if (checkpoint == null) {
@@ -319,7 +391,7 @@ export function createGoogleCalendarProvider(config) {
             } catch (err) {
                 // 410 Gone = the stored syncToken has expired; Google requires a full
                 // resync. Discard the checkpoint by delegating to fetchAll.
-                if (err instanceof GoogleCalendarAPIError && err.status === 410) {
+                if (err instanceof ConnectorError && err.httpStatus === 410) {
                     yield* fetchAllEntities(params);
                     return;
                 }

package/lib/target.d.ts

@@ -0,0 +1,11 @@
+import type { ActionTargetResolver } from '@kubun/connector';
+/**
+ * The Calendar target resolver (see `ActionTargetResolver`): a write's target
+ * is the calendar it lands in.
+ * - A create targets the `calendarID` of its input, required.
+ * - An update targets the calendar of its event (the `calendarID/eventID`
+ *   sourceID); a `calendarID` in its input must name that same calendar.
+ * - The `'primary'` alias is resolved to the account's synced primary
+ *   calendar, and the input carries the resolved id from then on.
+ */
+export declare const resolveCalendarTarget: ActionTargetResolver;