@kubun/connector-google-calendar 0.12.1 → 0.13.0

package/lib/api.d.ts

@@ -1,4 +1,5 @@
 import type { EntityRecord } from '@kubun/connector';
+export declare function parseGoogleError(response: Response): Promise<string>;
 export type GoogleCalendarResource = {
     id: string;
     summary: string;

package/lib/api.js

@@ -1,5 +1,5 @@
 const CALENDAR_BASE_URL = 'https://www.googleapis.com/calendar/v3';
-async function parseGoogleError(response) {
+export async function parseGoogleError(response) {
     try {
         const body = await response.json();
         return body.error?.message ?? `${response.status} ${response.statusText}`;
@@ -9,13 +9,19 @@ async function parseGoogleError(response) {
 }
 export function buildCalendarListURL(params) {
     const url = new URL(`${CALENDAR_BASE_URL}/users/me/calendarList`);
-    url.searchParams.set('showHidden', 'false');
+    // Google rejects `showHidden=false` (and `showDeleted=false`) alongside a
+    // syncToken: an incremental list must not narrow the result set the token was
+    // issued against. A paged continuation (pageToken) inherits the first page's
+    // context, so only the very first, tokenless page constrains visibility.
     if (params.syncToken != null) {
         url.searchParams.set('syncToken', params.syncToken);
     }
     if (params.pageToken != null) {
         url.searchParams.set('pageToken', params.pageToken);
     }
+    if (params.syncToken == null && params.pageToken == null) {
+        url.searchParams.set('showHidden', 'false');
+    }
     return url.toString();
 }
 export function buildEventsListURL(params) {
@@ -43,10 +49,16 @@ export function mapCalendarToEntity(calendar) {
         backgroundColor: calendar.backgroundColor
     };
 }
+// Google gives all-day events a bare calendar date (`YYYY-MM-DD`); the model's
+// startAt/endAt are `date-time`, so a bare date fails schema validation. Anchor
+// it to midnight UTC — the allDay flag tells consumers to ignore the time.
+function allDayDateToDateTime(date) {
+    return date == null ? undefined : `${date}T00:00:00.000Z`;
+}
 export function mapEventToEntity(event, calendarID) {
     const allDay = event.start.date != null;
-    const startAt = allDay ? event.start.date : event.start.dateTime;
-    const endAt = allDay ? event.end.date : event.end.dateTime;
+    const startAt = allDay ? allDayDateToDateTime(event.start.date) : event.start.dateTime;
+    const endAt = allDay ? allDayDateToDateTime(event.end.date) : event.end.dateTime;
     return {
         sourceService: 'google-calendar',
         sourceID: event.id,

package/lib/model.d.ts

@@ -48,7 +48,11 @@ export declare const googleCalendarDefinition: {
                 readonly minLength: 1;
                 readonly maxLength: 500;
             };
-            readonly SourceURL: import("json-schema-typed").JSONSchema.String;
+            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;
         };
@@ -128,11 +132,23 @@ export declare const googleCalendarEventDefinition: {
                 readonly minLength: 1;
                 readonly maxLength: 500;
             };
-            readonly SourceURL: import("json-schema-typed").JSONSchema.String;
+            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: import("json-schema-typed").JSONSchema.String;
-            readonly CalendarDocID: import("json-schema-typed").JSONSchema.String;
+            readonly HtmlLink: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly title: "URL";
+            };
+            readonly CalendarDocID: {
+                readonly type: "string";
+                readonly title: "DocID";
+                readonly pattern: "^k[0-9a-z]{10,120}$";
+            };
             readonly EventStatus: {
                 readonly type: "string";
                 readonly title: "EventStatus";

package/lib/provider.js

@@ -1,8 +1,19 @@
 import { resolveModelID } from '@kubun/connector';
-import { buildCalendarListURL, buildEventsListURL, mapCalendarToEntity, mapEventToEntity } from './api.js';
+import { buildCalendarListURL, buildEventsListURL, mapCalendarToEntity, mapEventToEntity, parseGoogleError } 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: {
@@ -11,7 +22,7 @@ async function fetchJSON(url, credential, fetchFn, signal) {
         signal
     });
     if (!response.ok) {
-        throw new Error(`Google Calendar API error: ${response.status} ${response.statusText}`);
+        throw new GoogleCalendarAPIError(response.status, await parseGoogleError(response));
     }
     return await response.json();
 }
@@ -151,131 +162,144 @@ export function createGoogleCalendarProvider(config) {
             };
         }
     }
-    return {
-        supportedStrategies: [
-            'on-demand'
-        ],
-        fetchAll: fetchAllEntities,
-        async *fetchChanges (params) {
-            const checkpoint = params.checkpoint;
-            if (checkpoint == null) {
-                yield* fetchAllEntities(params);
-                return;
+    async function* fetchIncrementalEntities(params, checkpoint) {
+        const timeMin = computeTimeMin(params.boundary);
+        // Phase 1: fetch calendar list changes using stored syncToken
+        const activeCalendars = [];
+        const deletedCalendarIDs = [];
+        let newCalendarListSyncToken;
+        for await (const page of fetchAllCalendars({
+            credential: config.credential,
+            fetchFn,
+            syncToken: checkpoint.calendarListSyncToken,
+            signal: params.signal
+        })){
+            for (const cal of page.items){
+                if (cal.deleted === true) {
+                    deletedCalendarIDs.push(cal.id);
+                } else if (!excludeSet.has(cal.id)) {
+                    activeCalendars.push(cal);
+                }
+            }
+            if (page.nextSyncToken != null) {
+                newCalendarListSyncToken = page.nextSyncToken;
             }
-            const timeMin = computeTimeMin(params.boundary);
-            // Phase 1: fetch calendar list changes using stored syncToken
-            const activeCalendars = [];
-            const deletedCalendarIDs = [];
-            let newCalendarListSyncToken;
-            for await (const page of fetchAllCalendars({
+        }
+        // Yield calendar batch (active + deletions)
+        yield {
+            modelID: CALENDAR_MODEL_ID,
+            entities: activeCalendars.map(mapCalendarToEntity),
+            deleted: deletedCalendarIDs.map((id)=>({
+                    sourceService: 'google-calendar',
+                    sourceID: id
+                })),
+            hasMore: true
+        };
+        // Phase 2: determine the set of calendars to sync events for
+        // Start from the previous calendar set, remove deleted, add newly discovered active ones
+        const prevCalendarTokens = {
+            ...checkpoint.calendars
+        };
+        for (const deletedID of deletedCalendarIDs){
+            delete prevCalendarTokens[deletedID];
+        }
+        // Collect new calendars that weren't in the previous checkpoint
+        const newlyDiscoveredCalendars = activeCalendars.filter((cal)=>!(cal.id in checkpoint.calendars));
+        // All calendars to sync: known (from prev checkpoint, minus deleted) + newly discovered
+        const knownCalendarIDs = Object.keys(prevCalendarTokens);
+        // Combine: known calendar IDs (we don't have resource objects for them, only IDs)
+        // plus newly discovered calendar resources
+        const allCalendarIDsToSync = [
+            ...knownCalendarIDs.map((id)=>({
+                    id,
+                    isNew: false
+                })),
+            ...newlyDiscoveredCalendars.map((cal)=>({
+                    id: cal.id,
+                    isNew: true
+                }))
+        ];
+        const updatedCalendarTokens = {};
+        for(let i = 0; i < allCalendarIDsToSync.length; i++){
+            const { id: calendarID, isNew } = allCalendarIDsToSync[i];
+            const isLastCalendar = i === allCalendarIDsToSync.length - 1;
+            // Use stored syncToken for known calendars; use timeMin for new ones
+            const storedToken = isNew ? undefined : prevCalendarTokens[calendarID]?.eventsSyncToken;
+            let eventsSyncToken;
+            for await (const page of fetchEventsForCalendar({
+                calendarID,
                 credential: config.credential,
                 fetchFn,
-                syncToken: checkpoint.calendarListSyncToken,
+                syncToken: storedToken,
+                timeMin: isNew ? timeMin : undefined,
                 signal: params.signal
             })){
-                for (const cal of page.items){
-                    if (cal.deleted === true) {
-                        deletedCalendarIDs.push(cal.id);
-                    } else if (!excludeSet.has(cal.id)) {
-                        activeCalendars.push(cal);
-                    }
-                }
                 if (page.nextSyncToken != null) {
-                    newCalendarListSyncToken = page.nextSyncToken;
+                    eventsSyncToken = page.nextSyncToken;
                 }
+                const isLastPage = page.nextSyncToken != null;
+                const newCheckpoint = isLastCalendar && isLastPage ? {
+                    calendarListSyncToken: newCalendarListSyncToken,
+                    calendars: {
+                        ...updatedCalendarTokens,
+                        [calendarID]: {
+                            eventsSyncToken: page.nextSyncToken
+                        }
+                    }
+                } : undefined;
+                // Split items: cancelled → deleted, others → entities
+                const activeItems = page.items.filter((e)=>e.status !== 'cancelled');
+                const cancelledItems = page.items.filter((e)=>e.status === 'cancelled');
+                yield {
+                    modelID: CALENDAR_EVENT_MODEL_ID,
+                    entities: activeItems.map((event)=>mapEventToEntity(event, calendarID)),
+                    deleted: cancelledItems.map((e)=>({
+                            sourceService: 'google-calendar',
+                            sourceID: e.id
+                        })),
+                    hasMore: !(isLastCalendar && isLastPage),
+                    checkpoint: newCheckpoint
+                };
             }
-            // Yield calendar batch (active + deletions)
-            yield {
-                modelID: CALENDAR_MODEL_ID,
-                entities: activeCalendars.map(mapCalendarToEntity),
-                deleted: deletedCalendarIDs.map((id)=>({
-                        sourceService: 'google-calendar',
-                        sourceID: id
-                    })),
-                hasMore: true
+            updatedCalendarTokens[calendarID] = {
+                eventsSyncToken
             };
-            // Phase 2: determine the set of calendars to sync events for
-            // Start from the previous calendar set, remove deleted, add newly discovered active ones
-            const prevCalendarTokens = {
-                ...checkpoint.calendars
+        }
+        // If no event batches were yielded (zero calendars to sync), emit a final empty
+        // batch with hasMore: false and the composite checkpoint so the sync can complete.
+        if (allCalendarIDsToSync.length === 0) {
+            yield {
+                modelID: CALENDAR_EVENT_MODEL_ID,
+                entities: [],
+                hasMore: false,
+                checkpoint: {
+                    calendarListSyncToken: newCalendarListSyncToken,
+                    calendars: updatedCalendarTokens
+                }
             };
-            for (const deletedID of deletedCalendarIDs){
-                delete prevCalendarTokens[deletedID];
+        }
+    }
+    return {
+        supportedStrategies: [
+            'on-demand'
+        ],
+        fetchAll: fetchAllEntities,
+        async *fetchChanges (params) {
+            const checkpoint = params.checkpoint;
+            if (checkpoint == null) {
+                yield* fetchAllEntities(params);
+                return;
             }
-            // Collect new calendars that weren't in the previous checkpoint
-            const newlyDiscoveredCalendars = activeCalendars.filter((cal)=>!(cal.id in checkpoint.calendars));
-            // All calendars to sync: known (from prev checkpoint, minus deleted) + newly discovered
-            const knownCalendarIDs = Object.keys(prevCalendarTokens);
-            // Combine: known calendar IDs (we don't have resource objects for them, only IDs)
-            // plus newly discovered calendar resources
-            const allCalendarIDsToSync = [
-                ...knownCalendarIDs.map((id)=>({
-                        id,
-                        isNew: false
-                    })),
-                ...newlyDiscoveredCalendars.map((cal)=>({
-                        id: cal.id,
-                        isNew: true
-                    }))
-            ];
-            const updatedCalendarTokens = {};
-            for(let i = 0; i < allCalendarIDsToSync.length; i++){
-                const { id: calendarID, isNew } = allCalendarIDsToSync[i];
-                const isLastCalendar = i === allCalendarIDsToSync.length - 1;
-                // Use stored syncToken for known calendars; use timeMin for new ones
-                const storedToken = isNew ? undefined : prevCalendarTokens[calendarID]?.eventsSyncToken;
-                let eventsSyncToken;
-                for await (const page of fetchEventsForCalendar({
-                    calendarID,
-                    credential: config.credential,
-                    fetchFn,
-                    syncToken: storedToken,
-                    timeMin: isNew ? timeMin : undefined,
-                    signal: params.signal
-                })){
-                    if (page.nextSyncToken != null) {
-                        eventsSyncToken = page.nextSyncToken;
-                    }
-                    const isLastPage = page.nextSyncToken != null;
-                    const newCheckpoint = isLastCalendar && isLastPage ? {
-                        calendarListSyncToken: newCalendarListSyncToken,
-                        calendars: {
-                            ...updatedCalendarTokens,
-                            [calendarID]: {
-                                eventsSyncToken: page.nextSyncToken
-                            }
-                        }
-                    } : undefined;
-                    // Split items: cancelled → deleted, others → entities
-                    const activeItems = page.items.filter((e)=>e.status !== 'cancelled');
-                    const cancelledItems = page.items.filter((e)=>e.status === 'cancelled');
-                    yield {
-                        modelID: CALENDAR_EVENT_MODEL_ID,
-                        entities: activeItems.map((event)=>mapEventToEntity(event, calendarID)),
-                        deleted: cancelledItems.map((e)=>({
-                                sourceService: 'google-calendar',
-                                sourceID: e.id
-                            })),
-                        hasMore: !(isLastCalendar && isLastPage),
-                        checkpoint: newCheckpoint
-                    };
+            try {
+                yield* fetchIncrementalEntities(params, checkpoint);
+            } 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) {
+                    yield* fetchAllEntities(params);
+                    return;
                 }
-                updatedCalendarTokens[calendarID] = {
-                    eventsSyncToken
-                };
-            }
-            // If no event batches were yielded (zero calendars to sync), emit a final empty
-            // batch with hasMore: false and the composite checkpoint so the sync can complete.
-            if (allCalendarIDsToSync.length === 0) {
-                yield {
-                    modelID: CALENDAR_EVENT_MODEL_ID,
-                    entities: [],
-                    hasMore: false,
-                    checkpoint: {
-                        calendarListSyncToken: newCalendarListSyncToken,
-                        calendars: updatedCalendarTokens
-                    }
-                };
+                throw err;
             }
         }
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-calendar",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,11 +15,11 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/connector": "^0.12.1",
-    "@kubun/models": "^0.12.1",
+    "@kubun/connector": "^0.13.0",
     "@kubun/protocol": "^0.13.0",
-    "@kubun/provider-google": "^0.12.0",
-    "@kubun/scalars": "^0.12.0"
+    "@kubun/scalars": "^0.13.0",
+    "@kubun/models": "^0.13.0",
+    "@kubun/provider-google": "^0.13.0"
   },
   "publishConfig": {
     "access": "public"