@kubun/connector-google-calendar 0.17.1 → 0.17.2

package/lib/account-key.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Non-reversible, deterministic account key projected to the graph in place of
+ * the raw provider identity. A pure function of (iss, sub) — no salt — so it
+ * survives credential deletion/re-auth so it stays stable across reconcile.
+ * This is a consistency label, not provenance.
+ */
+export declare function deriveAccountKey(account: {
+    iss: string;
+    sub: string;
+}): string;

package/lib/account-key.js

@@ -0,0 +1,19 @@
+import { digestJSON } from '@kubun/id';
+import { toB64U } from '@sozai/codec';
+/**
+ * Non-reversible, deterministic account key projected to the graph in place of
+ * the raw provider identity. A pure function of (iss, sub) — no salt — so it
+ * survives credential deletion/re-auth so it stays stable across reconcile.
+ * This is a consistency label, not provenance.
+ */ export function deriveAccountKey(account) {
+    // The extractor (plugin-connector's extractProviderAccount) accepts both
+    // 'https://accounts.google.com' and bare 'accounts.google.com' as valid
+    // Google iss claims. The key must be stable across whichever spelling a
+    // given token carries, so canonicalize before hashing.
+    const canonicalIss = account.iss === 'accounts.google.com' ? 'https://accounts.google.com' : account.iss;
+    return toB64U(digestJSON({
+        v: 'gcal-account',
+        iss: canonicalIss,
+        sub: account.sub
+    }));
+}

package/lib/actions.d.ts

@@ -5,5 +5,6 @@ export type GoogleCalendarActionHandlerConfig = {
         scopes: Array<string>;
     };
     fetch?: typeof globalThis.fetch;
+    mintFetchHLC: () => string;
 };
 export declare function createGoogleCalendarActionHandler(config: GoogleCalendarActionHandlerConfig): ActionHandler;

package/lib/actions.js

@@ -1,59 +1,111 @@
-import { createEvent, getCalendar, updateEvent } from './api.js';
+import { createEvent, updateEvent } from './api.js';
+import { GoogleCalendarError } from './errors.js';
+import { deriveEventID } from './event-id.js';
+/**
+ * The params of a sparse PATCH: only what the write changes, never the rest
+ * of the (possibly stale) local document. The one exception is how a changed
+ * start/end is written: it keeps the event's all-day form and time zone from
+ * the target document, and a changed time zone or all-day flag rewrites the
+ * start and end it applies to.
+ */ function sparsePatchParams(params, existing) {
+    const patch = {
+        ...params
+    };
+    // An all-day flip carries the event's current start/end over in the new
+    // form. Turning a timed event whose end falls on its start day all-day
+    // gives start.date == end.date, which Google rejects (400, an exclusive end
+    // must be later): the write dead-letters rather than guessing an end.
+    const reshapesTimes = 'timeZone' in params || 'allDay' in params;
+    for (const field of [
+        'startAt',
+        'endAt'
+    ]){
+        if (patch[field] == null && reshapesTimes && existing?.[field] != null) {
+            patch[field] = existing[field];
+        }
+    }
+    const writesTimes = patch.startAt != null || patch.endAt != null;
+    if (writesTimes) {
+        if (!('allDay' in patch) && existing?.allDay != null) patch.allDay = existing.allDay;
+        if (!('timeZone' in patch) && existing?.timeZone != null) patch.timeZone = existing.timeZone;
+    }
+    return patch;
+}
 export function createGoogleCalendarActionHandler(config) {
+    const mintActionFetchHLC = config.mintFetchHLC;
     return {
-        async create (_model, params) {
+        async create (_model, params, context) {
             const calendarID = params.calendarID;
             if (calendarID == null) {
                 throw new Error('calendarID is required for creating calendar events');
             }
-            // 'primary' is a per-account alias; sync sees the real id. Resolve it once
-            // on create so the composite sourceID matches the synced event's identity.
-            const resolvedCalendarID = calendarID === 'primary' ? (await getCalendar({
-                accessToken: config.credential.accessToken,
-                calendarID: 'primary',
-                fetch: config.fetch
-            })).id : calendarID;
-            return createEvent({
+            // The action layer resolves the 'primary' alias from synced data before
+            // the operation is claimed (resolveCalendarTarget); the handler writes
+            // only to a resolved calendar and never resolves the alias itself.
+            if (calendarID === 'primary') {
+                throw new GoogleCalendarError("the 'primary' calendar alias must be resolved before the write; name the calendar id", {
+                    kind: 'rejected'
+                });
+            }
+            const resolvedCalendarID = calendarID;
+            // The provider id is derived from the operation's deterministic event
+            // id, so every attempt of the operation inserts under the same id and a
+            // re-issue after a lost response hits a 409 instead of a duplicate.
+            const record = await createEvent({
                 accessToken: config.credential.accessToken,
                 calendarID: resolvedCalendarID,
                 params,
+                ...context != null ? {
+                    eventID: deriveEventID(context.deterministicEventID)
+                } : {},
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         },
-        async update (_model, sourceID, params) {
-            // sourceID is the composite calendarID/eventID. On a lookup hit the merged
-            // document supplies eventID + calendarID directly; on a miss recover both
-            // from the composite. An eventID never contains '/', a calendarID may, so
-            // split on the last '/'.
-            const mergedEventID = params.eventID;
-            const mergedCalendarID = params.calendarID;
+        async update (_model, sourceID, params, existing, context) {
+            // sourceID is the composite calendarID/eventID. The target document
+            // (`existing`) names the event; without it, recover both ids from the
+            // composite — an eventID never contains '/', a calendarID may, so split
+            // on the last '/'.
+            const knownEventID = existing?.eventID ?? params.eventID;
+            const knownCalendarID = existing?.calendarID ?? params.calendarID;
             let eventID;
             let calendarID;
-            if (mergedEventID != null) {
-                if (mergedCalendarID == null) {
+            if (knownEventID != null) {
+                if (knownCalendarID == null) {
                     throw new Error('calendarID is required for updating calendar events');
                 }
-                eventID = mergedEventID;
-                calendarID = mergedCalendarID;
+                eventID = knownEventID;
+                calendarID = knownCalendarID;
             } else {
                 const slash = sourceID.lastIndexOf('/');
                 if (slash <= 0 || slash === sourceID.length - 1) {
                     throw new Error(`Cannot recover eventID from sourceID "${sourceID}"`);
                 }
                 const recoveredCalendarID = sourceID.slice(0, slash);
-                if (mergedCalendarID != null && mergedCalendarID !== recoveredCalendarID) {
+                if (knownCalendarID != null && knownCalendarID !== recoveredCalendarID) {
                     throw new Error('calendarID does not match the event sourceID');
                 }
                 eventID = sourceID.slice(slash + 1);
                 calendarID = recoveredCalendarID;
             }
-            return updateEvent({
+            const record = await updateEvent({
                 accessToken: config.credential.accessToken,
                 calendarID,
                 eventID,
-                params,
+                params: sparsePatchParams(params, existing),
+                etag: context?.providerETag,
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         }
     };
 }

package/lib/api.d.ts

@@ -1,4 +1,5 @@
-import type { EntityRecord } from '@kubun/connector';
+import { type EntityRecord } from '@kubun/connector';
+export { type ConnectorErrorKind, classifyHTTPStatus } from '@kubun/connector';
 export declare function parseGoogleError(response: Response): Promise<string>;
 export type GoogleCalendarResource = {
     id: string;
@@ -23,6 +24,7 @@ export type GoogleEventDateTime = {
 };
 export type GoogleEventResource = {
     id: string;
+    etag?: string;
     summary?: string;
     description?: string;
     location?: string;
@@ -47,26 +49,42 @@ export declare function buildEventsListURL(params: {
     pageToken?: string;
     timeMin?: string;
 }): string;
-export declare function mapCalendarToEntity(calendar: GoogleCalendarResource): EntityRecord;
+export declare function mapCalendarToEntity(calendar: GoogleCalendarResource, accountKey?: string): EntityRecord;
 export declare function mapEventToEntity(event: GoogleEventResource, calendarID: string): EntityRecord;
 export declare function buildEventFromParams(params: Record<string, unknown>, options?: {
     create?: boolean;
+    eventID?: string;
 }): Record<string, unknown>;
-export declare function getCalendar(config: {
+export declare function getCalendarListEntry(config: {
     accessToken: string;
     calendarID: string;
     fetch?: typeof globalThis.fetch;
 }): Promise<GoogleCalendarResource>;
+export declare function splitEventSourceID(sourceID: string): {
+    calendarID: string;
+    eventID: string;
+};
 export declare function getEvent(config: {
     accessToken: string;
     calendarID: string;
     eventID: string;
     fetch?: typeof globalThis.fetch;
 }): Promise<EntityRecord>;
+export declare function getEventWithETag(config: {
+    accessToken: string;
+    calendarID: string;
+    eventID: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<{
+    record: EntityRecord;
+    etag?: string;
+}>;
 export declare function createEvent(config: {
     accessToken: string;
     calendarID: string;
     params: Record<string, unknown>;
+    /** The provider event id to insert under (see `deriveEventID`); takes precedence over `params.id`. */
+    eventID?: string;
     fetch?: typeof globalThis.fetch;
 }): Promise<EntityRecord>;
 export declare function updateEvent(config: {
@@ -74,5 +92,13 @@ export declare function updateEvent(config: {
     calendarID: string;
     eventID: string;
     params: Record<string, unknown>;
+    /**
+     * The event's etag as last fetched, sent as If-Match: a change at Google
+     * since then fails the PATCH with a 412 (outcome `unknown`, resolved by
+     * recovery's reconcile read) instead of being overwritten. It is never
+     * re-read right before the write — that would guard nothing. Absent, the
+     * PATCH is unconditional.
+     */
+    etag?: string | null;
     fetch?: typeof globalThis.fetch;
 }): Promise<EntityRecord>;

package/lib/api.js

@@ -1,3 +1,7 @@
+import { connectorHTTPError } from '@kubun/connector';
+import { GoogleCalendarEventConflict } from './errors.js';
+import { eventHoldsIntent } from './intent.js';
+export { classifyHTTPStatus } from '@kubun/connector';
 const CALENDAR_BASE_URL = 'https://www.googleapis.com/calendar/v3';
 export async function parseGoogleError(response) {
     try {
@@ -7,6 +11,23 @@ export async function parseGoogleError(response) {
         return `${response.status} ${response.statusText}`;
     }
 }
+/**
+ * Build the error thrown by an action's provider call, tagged with the HTTP
+ * status and its outcome classification so the caller can distinguish a
+ * definite rejection from an indeterminate failure.
+ */ function googleAPIError(status, detail) {
+    return connectorHTTPError(`Google Calendar API error: ${detail}`, status);
+}
+/**
+ * A create that collided with an existing event it could not confirm as its
+ * own. Outcome-unknown, not a rejection: the event may be this create's own
+ * earlier effect, edited since. `code: 'CONFLICT'` and `sourceID` let
+ * write-back recovery reconcile against the event.
+ */ function eventConflict(sourceID, cause) {
+    return new GoogleCalendarEventConflict(sourceID, cause != null ? {
+        cause
+    } : undefined);
+}
 export function buildCalendarListURL(params) {
     const url = new URL(`${CALENDAR_BASE_URL}/users/me/calendarList`);
     // Google rejects `showHidden=false` (and `showDeleted=false`) alongside a
@@ -37,7 +58,7 @@ export function buildEventsListURL(params) {
     }
     return url.toString();
 }
-export function mapCalendarToEntity(calendar) {
+export function mapCalendarToEntity(calendar, accountKey) {
     return {
         sourceService: 'google-calendar',
         sourceID: calendar.id,
@@ -46,7 +67,10 @@ export function mapCalendarToEntity(calendar) {
         description: calendar.description,
         timeZone: calendar.timeZone,
         primary: calendar.primary ?? false,
-        backgroundColor: calendar.backgroundColor
+        backgroundColor: calendar.backgroundColor,
+        ...accountKey != null ? {
+            accountKey
+        } : {}
     };
 }
 // Google gives all-day events a bare calendar date (`YYYY-MM-DD`); the model's
@@ -81,17 +105,19 @@ export function mapEventToEntity(event, calendarID) {
         calendar: {
             sourceService: 'google-calendar',
             sourceID: calendarID
-        }
+        },
+        etag: event.etag
     };
 }
 export function buildEventFromParams(params, options) {
     const event = {};
     const allDay = params.allDay === true;
-    // A caller-supplied id makes a create idempotent (Google rejects a duplicate
+    // A caller-chosen id makes a create idempotent (Google rejects a duplicate
     // with 409). Only insert accepts an id; PATCH must never carry one, so gate it
     // to the create path — the builder is shared with updateEvent.
-    if (options?.create === true && params.id != null) {
-        event.id = params.id;
+    const eventID = options?.eventID ?? params.id;
+    if (options?.create === true && eventID != null) {
+        event.id = eventID;
     }
     if (params.title != null) {
         event.summary = params.title;
@@ -127,9 +153,13 @@ export function buildEventFromParams(params, options) {
     }
     return event;
 }
-export async function getCalendar(config) {
+// One calendar as the account's calendar list holds it (calendarList.get) —
+// the same resource sync maps, with the per-account `primary` flag and
+// colour. calendars.get carries neither, so a re-pull from it would clear
+// `primary` and break resolving the 'primary' alias.
+export async function getCalendarListEntry(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
-    const url = `${CALENDAR_BASE_URL}/calendars/${encodeURIComponent(config.calendarID)}`;
+    const url = `${CALENDAR_BASE_URL}/users/me/calendarList/${encodeURIComponent(config.calendarID)}`;
     const response = await fetchFn(url, {
         headers: {
             Authorization: `Bearer ${config.accessToken}`
@@ -137,11 +167,23 @@ export async function getCalendar(config) {
     });
     if (!response.ok) {
         const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google Calendar API error: ${errorMessage}`);
+        throw googleAPIError(response.status, errorMessage);
     }
     return await response.json();
 }
-export async function getEvent(config) {
+// A composite calendarID/eventID sourceID splits on the LAST '/': an eventID
+// never contains one, but a calendarID (email-like) may.
+export function splitEventSourceID(sourceID) {
+    const slash = sourceID.lastIndexOf('/');
+    if (slash <= 0 || slash === sourceID.length - 1) {
+        throw new Error(`Cannot recover eventID from sourceID "${sourceID}"`);
+    }
+    return {
+        calendarID: sourceID.slice(0, slash),
+        eventID: sourceID.slice(slash + 1)
+    };
+}
+async function fetchEventResource(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
     const url = `${CALENDAR_BASE_URL}/calendars/${encodeURIComponent(config.calendarID)}/events/${encodeURIComponent(config.eventID)}`;
     const response = await fetchFn(url, {
@@ -151,16 +193,31 @@ export async function getEvent(config) {
     });
     if (!response.ok) {
         const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google Calendar API error: ${errorMessage}`);
+        throw googleAPIError(response.status, errorMessage);
     }
-    const data = await response.json();
+    return await response.json();
+}
+export async function getEvent(config) {
+    const data = await fetchEventResource(config);
     return mapEventToEntity(data, config.calendarID);
 }
+// Same as getEvent, but also surfaces the provider's etag/revision — used by
+// write-back recovery's reconcile read, which reports a providerETag
+// alongside the record.
+export async function getEventWithETag(config) {
+    const data = await fetchEventResource(config);
+    return {
+        record: mapEventToEntity(data, config.calendarID),
+        etag: data.etag
+    };
+}
 export async function createEvent(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
     const event = buildEventFromParams(config.params, {
-        create: true
+        create: true,
+        eventID: config.eventID
     });
+    const eventID = event.id;
     const url = `${CALENDAR_BASE_URL}/calendars/${encodeURIComponent(config.calendarID)}/events`;
     const response = await fetchFn(url, {
         method: 'POST',
@@ -171,19 +228,34 @@ export async function createEvent(config) {
         body: JSON.stringify(event)
     });
     if (!response.ok) {
-        // A 409 on a caller-supplied id means the event already exists — the create
-        // is already committed, so a retry after a lost response is idempotent: fetch
-        // and return the existing event instead of failing.
-        if (response.status === 409 && config.params.id != null) {
-            return getEvent({
-                accessToken: config.accessToken,
-                calendarID: config.calendarID,
-                eventID: config.params.id,
-                fetch: config.fetch
-            });
+        // A 409 on a caller-chosen id means an event already exists under it. It
+        // is this create's own earlier effect (a retry after a lost response) only
+        // if it holds what this create writes; anything else is a conflict naming
+        // the existing event, for recovery to reconcile — never a success.
+        if (response.status === 409 && eventID != null) {
+            const sourceID = `${config.calendarID}/${eventID}`;
+            let existing;
+            try {
+                existing = await getEvent({
+                    accessToken: config.accessToken,
+                    calendarID: config.calendarID,
+                    eventID,
+                    fetch: config.fetch
+                });
+            } catch (err) {
+                throw eventConflict(sourceID, err);
+            }
+            if (!eventHoldsIntent({
+                op: 'create',
+                intent: config.params,
+                record: existing
+            })) {
+                throw eventConflict(sourceID);
+            }
+            return existing;
         }
         const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google Calendar API error: ${errorMessage}`);
+        throw googleAPIError(response.status, errorMessage);
     }
     const data = await response.json();
     return mapEventToEntity(data, config.calendarID);
@@ -196,13 +268,16 @@ export async function updateEvent(config) {
         method: 'PATCH',
         headers: {
             Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json'
+            'Content-Type': 'application/json',
+            ...config.etag != null ? {
+                'If-Match': config.etag
+            } : {}
         },
         body: JSON.stringify(event)
     });
     if (!response.ok) {
         const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google Calendar API error: ${errorMessage}`);
+        throw googleAPIError(response.status, errorMessage);
     }
     const data = await response.json();
     return mapEventToEntity(data, config.calendarID);

package/lib/connector.js

@@ -1,6 +1,9 @@
 import { createGoogleCalendarActionHandler } from './actions.js';
+import { canonicalizeEventIntent } from './intent.js';
 import { googleCalendarClusters } from './model.js';
+import { predictCreatedEventSourceID } from './predict.js';
 import { createGoogleCalendarProvider } from './provider.js';
+import { resolveCalendarTarget } from './target.js';
 export function createGoogleCalendarConnector(options) {
     return {
         name: 'google-calendar',
@@ -42,7 +45,12 @@ export function createGoogleCalendarConnector(options) {
                         }
                     }
                 },
-                requiresCredential: true
+                requiresCredential: true,
+                // The provider event id is derived from the operation's deterministic
+                // event id (see deriveEventID), so a reissue inserts under the same id
+                // as the original attempt: a create that already landed answers 409
+                // instead of inserting a duplicate — safe to reissue.
+                recoveryClass: 'reissue-safe'
             },
             {
                 name: 'update',
@@ -76,13 +84,29 @@ export function createGoogleCalendarConnector(options) {
                         }
                     }
                 },
-                requiresCredential: true
+                requiresCredential: true,
+                // A sparse PATCH conditioned (If-Match) on the etag of the document
+                // the edit was made against, pinned on the operation at claim. A
+                // reissue after an unknown outcome would meet its own earlier write's
+                // new etag as a 412, and an unconditional one could clobber an
+                // intervening edit, so recovery reconciles (reads current provider
+                // state) rather than reissues.
+                recoveryClass: 'reconcile-only',
+                providerETagField: 'etag',
+                // An edit is only ever written against the version it was made on: an
+                // event with no stored etag (not synced yet) is refused before the
+                // claim rather than written unconditionally over a provider edit.
+                providerETagRequired: true
             }
         ],
+        canonicalizeIntent: canonicalizeEventIntent,
+        resolveActionTarget: resolveCalendarTarget,
+        predictCreatedSourceID: predictCreatedEventSourceID,
         actionHandler: (config)=>{
             return createGoogleCalendarActionHandler({
                 credential: config.credential,
-                fetch: options?.fetch
+                fetch: options?.fetch,
+                mintFetchHLC: config.mintFetchHLC
             });
         },
         auth: {
@@ -98,7 +122,8 @@ export function createGoogleCalendarConnector(options) {
             return createGoogleCalendarProvider({
                 credential: config.credential,
                 boundary: config.boundary,
-                fetch: options?.fetch
+                fetch: options?.fetch,
+                mintFetchHLC: config.mintFetchHLC
             });
         }
     };

package/lib/errors.d.ts

@@ -0,0 +1,32 @@
+import { ConnectorError, type ConnectorErrorOptions } from '@kubun/connector';
+/** A machine-readable failure code fixed for a given Google Calendar failure. */
+export type GoogleCalendarErrorCode = 'GOOGLE_CALENDARS_NOT_SYNCED' | 'GOOGLE_CALENDAR_ID_REQUIRED' | 'GOOGLE_CALENDAR_ID_MISMATCH' | 'CONFLICT';
+export type GoogleCalendarErrorOptions = ConnectorErrorOptions & {
+    code?: GoogleCalendarErrorCode;
+};
+/** A Google Calendar connector failure, classified the way `ConnectorError` is. */
+export declare class GoogleCalendarError extends ConnectorError {
+    constructor(message: string, options?: GoogleCalendarErrorOptions);
+    get code(): GoogleCalendarErrorCode | undefined;
+}
+/**
+ * A create that collided with an existing event it could not confirm as its
+ * own. Outcome-unknown, not a rejection: the event may be this create's own
+ * earlier effect, edited since. `sourceID` lets write-back recovery
+ * reconcile against the event.
+ */
+export declare class GoogleCalendarEventConflict extends GoogleCalendarError {
+    #private;
+    constructor(sourceID: string, options?: ErrorOptions);
+    get sourceID(): string;
+}
+/**
+ * A raw provider HTTP failure from a batch/list round trip (`fetchJSON` in
+ * `provider.ts`), carrying the response status so `fetchChanges` can detect
+ * an expired sync token (410) and fall back to a full resync.
+ */
+export declare class GoogleCalendarAPIError extends Error {
+    #private;
+    constructor(status: number, detail: string);
+    get status(): number;
+}

package/lib/errors.js

@@ -0,0 +1,46 @@
+import { ConnectorError } from '@kubun/connector';
+/** A Google Calendar connector failure, classified the way `ConnectorError` is. */ export class GoogleCalendarError extends ConnectorError {
+    constructor(message, options = {}){
+        super(message, options);
+        this.name = 'GoogleCalendarError';
+    }
+    get code() {
+        return super.code;
+    }
+}
+/**
+ * A create that collided with an existing event it could not confirm as its
+ * own. Outcome-unknown, not a rejection: the event may be this create's own
+ * earlier effect, edited since. `sourceID` lets write-back recovery
+ * reconcile against the event.
+ */ export class GoogleCalendarEventConflict extends GoogleCalendarError {
+    #sourceID;
+    constructor(sourceID, options){
+        super(`Google Calendar API error: an event already exists as "${sourceID}" and does not hold this create`, {
+            ...options,
+            code: 'CONFLICT',
+            httpStatus: 409,
+            kind: 'unknown'
+        });
+        this.name = 'GoogleCalendarEventConflict';
+        this.#sourceID = sourceID;
+    }
+    get sourceID() {
+        return this.#sourceID;
+    }
+}
+/**
+ * A raw provider HTTP failure from a batch/list round trip (`fetchJSON` in
+ * `provider.ts`), carrying the response status so `fetchChanges` can detect
+ * an expired sync token (410) and fall back to a full resync.
+ */ export 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;
+    }
+}

package/lib/event-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Google Calendar event id a create inserts under, derived from the
+ * operation's deterministic event id: the lowercase base32hex encoding (no
+ * padding) of a 32-byte digest of it, 52 characters — inside Google's allowed
+ * alphabet (`a-v`, `0-9`) and length (5 to 1024).
+ *
+ * Every attempt of the same operation derives the same id, so a create that is
+ * re-issued after its response was lost collides with its own earlier effect
+ * (a 409) instead of inserting a duplicate event. The mapping is one-way and
+ * versioned: changing it would re-key every create not yet confirmed.
+ */
+export declare function deriveEventID(deterministicEventID: string): string;

package/lib/event-id.js

@@ -0,0 +1,35 @@
+import { digestJSON } from '@kubun/id';
+// Google Calendar event ids use the base32hex alphabet (RFC 4648 §7), lowercase.
+const BASE32HEX = '0123456789abcdefghijklmnopqrstuv';
+function toBase32Hex(bytes) {
+    let out = '';
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes){
+        buffer = buffer << 8 | byte;
+        bits += 8;
+        while(bits >= 5){
+            bits -= 5;
+            out += BASE32HEX[buffer >> bits & 31];
+        }
+        buffer &= (1 << bits) - 1;
+    }
+    if (bits > 0) out += BASE32HEX[buffer << 5 - bits & 31];
+    return out;
+}
+/**
+ * The Google Calendar event id a create inserts under, derived from the
+ * operation's deterministic event id: the lowercase base32hex encoding (no
+ * padding) of a 32-byte digest of it, 52 characters — inside Google's allowed
+ * alphabet (`a-v`, `0-9`) and length (5 to 1024).
+ *
+ * Every attempt of the same operation derives the same id, so a create that is
+ * re-issued after its response was lost collides with its own earlier effect
+ * (a 409) instead of inserting a duplicate event. The mapping is one-way and
+ * versioned: changing it would re-key every create not yet confirmed.
+ */ export function deriveEventID(deterministicEventID) {
+    return toBase32Hex(digestJSON({
+        v: 'gcal-event-id',
+        deterministicEventID
+    }));
+}

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 { GoogleCalendarAPIError, 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 { GoogleCalendarAPIError, 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";
             };
@@ -104,6 +109,9 @@ export declare const googleCalendarEventDefinition: {
             readonly calendarID: {
                 readonly type: "string";
             };
+            readonly etag: {
+                readonly type: "string";
+            };
             readonly calendar: {
                 readonly $ref: "#/definitions/CalendarDocID";
             };
@@ -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

@@ -26,6 +26,11 @@ export const googleCalendarDefinition = {
             backgroundColor: {
                 type: 'string'
             },
+            accountKey: {
+                type: 'string',
+                minLength: 43,
+                maxLength: 43
+            },
             sourceService: {
                 $ref: '#/definitions/SourceService'
             },
@@ -114,6 +119,9 @@ export const googleCalendarEventDefinition = {
             calendarID: {
                 type: 'string'
             },
+            etag: {
+                type: 'string'
+            },
             calendar: {
                 $ref: '#/definitions/CalendarDocID'
             },
@@ -177,6 +185,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,19 +1,10 @@
 import { resolveModelID } from '@kubun/connector';
-import { buildCalendarListURL, buildEventsListURL, mapCalendarToEntity, mapEventToEntity, parseGoogleError } from './api.js';
+import { deriveAccountKey } from './account-key.js';
+import { buildCalendarListURL, buildEventsListURL, getCalendarListEntry, getEvent, getEventWithETag, mapCalendarToEntity, mapEventToEntity, parseGoogleError, splitEventSourceID } from './api.js';
+import { GoogleCalendarAPIError } from './errors.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: {
@@ -78,6 +69,17 @@ async function* fetchEventsForCalendar(params) {
 export function createGoogleCalendarProvider(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
     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;
+    // getCalendarListEntry/getEvent/getEventWithETag (api.ts) throw a plain Error tagged
+    // with `.httpStatus` (googleAPIError) — this is the seam fetchEntity/reconcile
+    // use to turn a 404 into a `present: false` result instead of a throw.
+    function isNotFound(err) {
+        return err?.httpStatus === 404;
+    }
     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
@@ -103,9 +105,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
@@ -141,14 +148,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
@@ -202,12 +215,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
         };
@@ -269,14 +288,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 +328,101 @@ 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();
+        try {
+            if (model === CALENDAR_MODEL_ID) {
+                const calendar = await getCalendarListEntry({
+                    accessToken: config.credential.accessToken,
+                    calendarID: sourceID,
+                    fetch: fetchFn
+                });
+                return {
+                    present: true,
+                    record: mapCalendarToEntity(calendar, accountKey),
+                    sourceFetchHLC
+                };
+            }
+            const { calendarID, eventID } = splitEventSourceID(sourceID);
+            const record = await getEvent({
+                accessToken: config.credential.accessToken,
+                calendarID,
+                eventID,
+                fetch: fetchFn
+            });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC
+            };
+        } catch (err) {
+            if (isNotFound(err)) {
+                return {
+                    present: false,
+                    sourceID,
+                    sourceFetchHLC
+                };
+            }
+            throw err;
+        }
+    }
+    // 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();
+        try {
+            if (model === CALENDAR_MODEL_ID) {
+                const calendar = await getCalendarListEntry({
+                    accessToken: config.credential.accessToken,
+                    calendarID: sourceID,
+                    fetch: fetchFn
+                });
+                return {
+                    present: true,
+                    record: mapCalendarToEntity(calendar, accountKey),
+                    sourceFetchHLC
+                };
+            }
+            const { calendarID, eventID } = splitEventSourceID(sourceID);
+            const { record, etag } = await getEventWithETag({
+                accessToken: config.credential.accessToken,
+                calendarID,
+                eventID,
+                fetch: fetchFn
+            });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC,
+                ...etag != null ? {
+                    providerETag: etag
+                } : {}
+            };
+        } catch (err) {
+            if (isNotFound(err)) {
+                return {
+                    present: false,
+                    sourceID,
+                    sourceFetchHLC
+                };
+            }
+            throw err;
+        }
+    }
     return {
         supportedStrategies: [
             'on-demand'
         ],
         fetchAll: fetchAllEntities,
+        fetchEntity,
+        reconcile,
         async *fetchChanges (params) {
             const checkpoint = params.checkpoint;
             if (checkpoint == null) {

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;

package/lib/target.js

@@ -0,0 +1,68 @@
+import { deriveAccountKey } from './account-key.js';
+import { splitEventSourceID } from './api.js';
+import { GoogleCalendarError } from './errors.js';
+import { googleCalendarDefinition } from './model.js';
+function calendarError(code, message) {
+    return new GoogleCalendarError(`${code}: ${message}`, {
+        code,
+        kind: 'rejected'
+    });
+}
+// The account's primary calendar, as synced to this device: the calendar-list
+// entry Google flags primary, under this account. Never a provider call —
+// before the calendars are synced there is nothing to resolve it to.
+async function syncedPrimaryCalendar(storage, providerAccount) {
+    const accountKey = deriveAccountKey(providerAccount);
+    const primary = (await storage.documents(googleCalendarDefinition.name)).filter((calendar)=>calendar.primary === true && calendar.accountKey === accountKey);
+    const [only] = primary;
+    if (primary.length !== 1 || typeof only?.sourceID !== 'string') {
+        throw calendarError('GOOGLE_CALENDARS_NOT_SYNCED', primary.length === 0 ? 'the primary calendar is not known on this device yet; sync calendars first' : 'more than one synced calendar is flagged primary for this account; sync calendars again');
+    }
+    return only.sourceID;
+}
+/**
+ * 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 const resolveCalendarTarget = async ({ op, input, sourceID, providerAccount, storage })=>{
+    const named = input.calendarID;
+    const resolveNamed = async ()=>{
+        if (named == null) return undefined;
+        if (typeof named !== 'string' || named === '') {
+            throw calendarError('GOOGLE_CALENDAR_ID_REQUIRED', 'calendarID must be a calendar id');
+        }
+        return named === 'primary' ? await syncedPrimaryCalendar(storage, providerAccount) : named;
+    };
+    if (op === 'create') {
+        const calendarID = await resolveNamed();
+        if (calendarID == null) {
+            throw calendarError('GOOGLE_CALENDAR_ID_REQUIRED', 'a new event needs a calendarID');
+        }
+        return {
+            target: calendarID,
+            input: {
+                ...input,
+                calendarID
+            }
+        };
+    }
+    if (sourceID == null) {
+        throw calendarError('GOOGLE_CALENDAR_ID_REQUIRED', 'an event update needs its sourceID');
+    }
+    const eventCalendarID = splitEventSourceID(sourceID).calendarID;
+    const calendarID = await resolveNamed();
+    if (calendarID != null && calendarID !== eventCalendarID) {
+        throw calendarError('GOOGLE_CALENDAR_ID_MISMATCH', `calendarID does not name the calendar of the event "${sourceID}"`);
+    }
+    return {
+        target: eventCalendarID,
+        input: calendarID != null ? {
+            ...input,
+            calendarID
+        } : input
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-calendar",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,12 +15,18 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/connector": "^0.17.1",
-    "@kubun/credential-types": "^0.17.0",
+    "@kubun/connector": "^0.17.2",
+    "@kubun/credential-types": "^0.17.2",
+    "@kubun/hlc": "^0.17.0",
+    "@kubun/id": "^0.17.0",
     "@kubun/models": "^0.17.0",
-    "@kubun/protocol": "^0.17.0",
+    "@kubun/protocol": "^0.17.1",
     "@kubun/provider-google": "^0.17.0",
-    "@kubun/scalars": "^0.17.0"
+    "@kubun/scalars": "^0.17.0",
+    "@sozai/codec": "^0.4.0"
+  },
+  "devDependencies": {
+    "@sozai/schema": "^0.1.2"
   },
   "publishConfig": {
     "access": "public"